Crate harn_hostlib 

harn-hostlib: opt-in host builtins for code intelligence (tree-sitter, repo scanning, deterministic indexing) and tool execution (search, file I/O, git, process lifecycle, file watcher).

This crate is the Rust home of two classes of optional host capabilities:

1. Code intelligence — ast/, code_index/, scanner/, fs_watch/.
2. Deterministic tools — tools/ (search, fs, git, process).

These don’t belong inside harn-vm — pulling tree-sitter grammars, ripgrep, and notify into the VM would balloon the footprint of every pipeline that doesn’t index host code. Instead, this crate exposes a single HostlibCapability trait. Embedders such as harn-cli’s ACP server) compose the modules they need via HostlibRegistry and wire the resulting builtins into the VM through harn_vm::Vm::register_builtin / harn_vm::Vm::register_async_builtin.

Status

The AST, scanner, code-index, and deterministic-tool surfaces are implemented. fs_watch/ still registers its public contract with HostlibError::Unimplemented handlers. Module names, method names, and JSON schemas under schemas/ are the source of truth for hostlib request/response compatibility, so they must stay stable while module bodies evolve.

Re-exports

pub use error::HostlibError;

pub use host_conditions::HostConditionObservation;

pub use host_conditions::HostConditionStatus;

pub use host_conditions::HostConditionsCapability;

pub use host_conditions::HostConditionsSnapshot;

pub use host_conditions::HostConditionsSource;

pub use host_conditions::HostContentionQuestion;

pub use host_conditions::HostEnvironment;

pub use host_conditions::InjectedHostConditionsSource;

pub use host_conditions::LocalHostConditionsSource;

pub use host_conditions::HOST_CONDITIONS_SCHEMA_VERSION;

pub use host_lease::HostLeaseAcquireReceipt;

pub use host_lease::HostLeaseAcquireStatus;

pub use host_lease::HostLeaseCargoExecutionContext;

pub use host_lease::HostLeaseDeferReason;

pub use host_lease::HostLeaseDeferReceipt;

pub use host_lease::HostLeaseError;

pub use host_lease::HostLeaseExecutionContext;

pub use host_lease::HostLeaseHandle;

pub use host_lease::HostLeaseMetadataUpdateReceipt;

pub use host_lease::HostLeaseOperationKind;

pub use host_lease::HostLeasePathIdentity;

pub use host_lease::HostLeasePriorityClass;

pub use host_lease::HostLeaseProcessExit;

pub use host_lease::HostLeaseReleaseReceipt;

pub use host_lease::HostLeaseRenewReceipt;

pub use host_lease::HostLeaseRequest;

pub use host_lease::HostLeaseResourceClass;

pub use host_lease::HostLeaseResourceDefinition;

pub use host_lease::HostLeaseResourceKey;

pub use host_lease::HostLeaseRunLaunchFailure;

pub use host_lease::HostLeaseRunReceipt;

pub use host_lease::HostLeaseRunReleaseOutcome;

pub use host_lease::HostLeaseRunStartFailure;

pub use host_lease::HostLeaseRunState;

pub use host_lease::HostLeaseState;

pub use host_lease::HostLeaseStore;

pub use host_lease::DEFAULT_HOST_LEASE_DOMAIN;

pub use host_lease::HOST_LEASE_ROOT_ENV;

Modules

ast

AST host capability.

code_index

Code index host capability.

embed

Text-similarity / embedding host capability.

error

Error type for hostlib host calls.

fs

Session-scoped staged filesystem mode.

fs_snapshot

Per-tool-call filesystem snapshots — Gemini-style /restore primitives.

fs_watch

File-system watch host capability.

host_conditions

Portable, read-only ambient host-condition observations.

host_env_custody

Shared host-environment custody contracts.

host_lease

Atomic, machine-global leases for scarce host resources.

host_lease_capability

Harn VM bridge for cancellation-safe machine-global host lease scopes.

process

Process abstraction used by the deterministic process tools.

sandbox

The runtime arm of the permission primitive: pluggable sandbox backends that enforce a declared policy rather than merely gating tool dispatch.

scanner

Repo scanner host capability.

schemas

Embedded JSON Schemas for every hostlib host method.

secret_store

Per-OS secret-store host primitive.

session

In-process adapter for the canonical Harn session/transcript store.

terminal_session

Default-off typed terminal-session host capability.

tools

Deterministic tools capability.

verdict

harness.verdict.* issuance validator — the host authority that decides whether a real host-executed test run earns a positive verdict.

Structs

BuiltinRegistry

Mutable collector each capability writes into during register.

DefaultHostlibHandles

Handles retained from install_default_with_handles so embedders can warm or introspect capabilities out-of-band of the VM.

HostlibRegistry

Composes capabilities and emits VM registrations.

RegisteredBuiltin

One registered builtin. The name is what Harn scripts call (e.g. hostlib_ast_parse_file); module and method are the canonical schema-directory coordinates (schemas/<module>/<method>.request.json).

Traits

HostlibCapability

One module’s worth of builtins. Kept tiny on purpose: capabilities exist purely so tests can reason about the surface without booting a VM, and so embedders can opt into individual modules.

Functions

install_default

Convenience: build a HostlibRegistry populated with every capability the crate ships, register them on the supplied VM, and return the registry so callers can introspect (e.g. for schema-drift tests).

install_default_with_handles

Like install_default, but also returns retained capability handles.