harn_hostlib/
lib.rs

1//! `harn-hostlib`: opt-in host builtins for code intelligence (tree-sitter,
2//! repo scanning, deterministic indexing) and tool execution (search, file
3//! I/O, git, process lifecycle, file watcher).
4//!
5//! This crate is the Rust home of two classes of optional host capabilities:
6//!
7//! 1. **Code intelligence** — `ast/`, `code_index/`, `scanner/`, `fs_watch/`.
8//! 2. **Deterministic tools** — `tools/` (search, fs, git, process).
9//!
10//! These don't belong inside `harn-vm` — pulling tree-sitter grammars,
11//! ripgrep, and `notify` into the VM would balloon the footprint of every
12//! pipeline that doesn't index host code. Instead, this crate exposes a
13//! single [`HostlibCapability`] trait. Embedders such as `harn-cli`'s ACP
14//! server) compose the modules they need via [`HostlibRegistry`] and wire
15//! the resulting builtins into the VM through [`harn_vm::Vm::register_builtin`]
16//! / [`harn_vm::Vm::register_async_builtin`].
17//!
18//! ## Status
19//!
20//! The AST, scanner, code-index, and deterministic-tool surfaces are
21//! implemented. `fs_watch/` still registers its public contract with
22//! [`HostlibError::Unimplemented`] handlers. Module names, method names,
23//! and JSON schemas under `schemas/` are the source of truth for hostlib
24//! request/response compatibility, so they must stay stable while module
25//! bodies evolve.
26
27#![deny(rust_2018_idioms)]
28#![warn(missing_docs)]
29
30#[cfg(feature = "ast")]
31pub mod ast;
32#[cfg(feature = "ast")]
33pub mod code_index;
34#[cfg(feature = "computer")]
35pub mod computer;
36pub mod embed;
37pub mod error;
38pub mod fs;
39pub mod fs_snapshot;
40pub mod fs_watch;
41pub mod host_env_custody;
42pub mod host_lease;
43pub mod process;
44mod process_liveness;
45pub mod sandbox;
46pub mod scanner;
47pub mod schemas;
48pub mod secret_store;
49#[cfg(feature = "terminal-session")]
50pub mod terminal_session;
51pub mod tools;
52
53mod json;
54mod registry;
55mod text;
56mod value_args;
57
58pub use error::HostlibError;
59pub use host_lease::{
60    HostLeaseAcquireReceipt, HostLeaseAcquireStatus, HostLeaseDeferReason, HostLeaseDeferReceipt,
61    HostLeaseError, HostLeaseHandle, HostLeasePriorityClass, HostLeaseReleaseReceipt,
62    HostLeaseRenewReceipt, HostLeaseRequest, HostLeaseState, HostLeaseStore, HOST_LEASE_ROOT_ENV,
63};
64pub use registry::{BuiltinRegistry, HostlibCapability, HostlibRegistry, RegisteredBuiltin};
65
66/// Convenience: build a `HostlibRegistry` populated with every capability
67/// the crate ships, register them on the supplied VM, and return the
68/// registry so callers can introspect (e.g. for schema-drift tests).
69///
70/// This is the canonical entry point for embedders that want the full
71/// hostlib surface; pick-and-choose embedders should construct
72/// [`HostlibRegistry`] directly.
73pub fn install_default(vm: &mut harn_vm::Vm) -> HostlibRegistry {
74    let mut registry = HostlibRegistry::new();
75    // The code-intelligence capabilities (`ast` + `code_index`) are only
76    // compiled when the `ast` feature is on. Lean clients that omit it get
77    // the deterministic tool surface without tree-sitter or any grammar.
78    #[cfg(feature = "ast")]
79    {
80        let code_index = code_index::CodeIndexCapability::new();
81        registry = registry
82            .with(ast::AstCapabilityWithCodeIndex::new(code_index.shared()))
83            .with(code_index);
84    }
85    registry = registry
86        .with(scanner::ScannerCapability)
87        .with(embed::EmbedCapability::default())
88        .with(fs::FsCapability)
89        .with(fs_snapshot::FsSnapshotCapability)
90        .with(fs_watch::FsWatchCapability)
91        .with(tools::ToolsCapability)
92        .with(secret_store::SecretStoreCapability);
93    #[cfg(feature = "terminal-session")]
94    {
95        registry = registry.with(terminal_session::TerminalSessionCapability::new());
96    }
97    // Computer use (screenshot + mouse/keyboard) is opt-in at the feature
98    // level AND default-deny at runtime: even with `computer-local` compiled,
99    // the backend is a NullBackend unless `BURIN_COMPUTER_USE_TRANSPORT` is
100    // explicitly set to `local` (or `helper`/`remote`). In the product it is
101    // gated again by an off-by-default setting. Registering the builtins is
102    // therefore harmless when unarmed — every call fails with an explanatory
103    // message until the transport is explicitly chosen.
104    #[cfg(feature = "computer")]
105    {
106        registry = registry.with(computer::ComputerUseCapability::new());
107    }
108    registry.register_into_vm(vm);
109    registry
110}
harn_hostlib/lib.rs

harn_hostlib/
lib.rs
