Host boundary

Harn is the orchestration layer. Hosts supply facts and platform effects.

The boundary should stay narrow:

• Hosts expose typed capabilities such as project scan data, editor state, diagnostics, git facts, approval decisions, and persistence hooks.
• Harn owns orchestration policy: workflow topology, retries, verification, transcript lifecycle, context assembly, contract enforcement, replay, evals, and worker semantics.

What belongs in Harn std/* modules or the VM:

• Generic runtime wrappers like runtime_task(), process_run(), or interaction_ask()
• Reusable metadata/scanner helpers and product-agnostic project-state normalization
• Transcript schemas, assets, compaction, and replay semantics
• Context/artifact assembly rules that are product-agnostic
• Structured contract enforcement and eval/replay helpers
• Test-time typed host mocks such as host_mock(...) when the behavior is a runtime fixture for host-backed flows rather than a product-specific bridge
• Mutation-session identity and audit provenance for write-capable workflows and delegated workers

What should stay in host-side .harn scripts:

• Product-specific prompts and instruction tone
• IDE-specific flows such as edit application, approval UX, repo enrichment, or bespoke tool choreography
• Host-owned filesystem and edit wrappers built on capability-aware host_call(...)
• Host-owned editor, diagnostics, git, learning, and project-context wrappers
• Concrete undo/redo stacks and editor-native mutation application
• Proprietary ranking, routing, or heuristics tied to one host product
• Features that depend on host-only commercial, account, or app lifecycle rules

Rule of thumb:

• If a behavior decides how an agent or workflow should think, continue, verify, compact, replay, or select context, it probably belongs in Harn.
• If a behavior fetches facts from a specific editor or app surface, asks the user for approval, or performs a host-only side effect, it belongs in the host.

Keep advanced host-side .harn modules local to the host when they encode host-only UX, proprietary behavior, or app-specific heuristics. Move a helper into Harn only when it is general enough to be useful across hosts.

Trust boundary

Harn should own the audit contract for mutations:

• mutation-session IDs
• workflow/worker/session lineage
• tool-gate mutation classification and declared scope
• artifact and run-record provenance

Hosts should own the concrete UX:

• apply/approve/deny flows
• patch previews
• editor undo/redo semantics
• trust UI around which worker or session produced a change

Typed host capabilities

Typed capabilities surfaced through host_call(capability.operation, params) let Harn delegate platform effects without coupling to one host. Notable capabilities Harn defines today:

• process.exec and the process.* shell helpers — process execution.
• template.render — host-resolved template rendering.
• interaction.ask — synchronous user prompts.
• memory.embed — host-provided text embeddings used by the std/memory vector and hybrid backends. Request shape: {text, model_hint}. Response shape: {vector: list<float>, model?: string, dim?: int}. Hosts pick the model and own rate limiting and cost accounting; Harn caches embeddings per (model_hint, content_hash) so replays are deterministic. See Memory for the recall and storage contract.

Tests can satisfy any capability with host_mock(capability, op, {result}); embedders ship richer behavior via the HostCallBridge trait described in crates/harn-vm/src/stdlib/host.rs.

Process sandbox

harn run installs a default worktree capability ceiling before executing user code. The runtime confines every subprocess it spawns under that ceiling unless the operator passes --no-sandbox. The default profile is workspace-root path enforcement plus best-effort OS-level confinement (Linux Landlock + seccomp, macOS sandbox-exec, Windows AppContainer + Job Object), with network side effects denied by the default ceiling. Pipelines that spawn untrusted code opt into os_hardened, which makes the OS confinement required and turns every spawn into a tool_rejected if the platform mechanism is missing.

See Process sandboxing for the full per-platform capability → kernel-knob mapping table, profile selection examples, and replay semantics.

Contract surfaces

Harn now ships machine-readable contract exports so hosts do not need to reverse-engineer runtime assumptions:

• harn contracts builtins for the builtin registry and parser/runtime drift
• harn contracts host-capabilities for the effective host manifest used by preflight validation
• harn contracts bundle for entry modules, imported modules, prompt/template assets, explicit module-dependency edges, required host capabilities, literal execution directories, worker repo dependencies, and stable summary counts

Those surfaces are intended to be the generic boundary for embedded hosts such as editors or native apps. Product-specific packaging logic should build on top of them rather than re-implementing Harn’s import, asset, and host-capability resolution rules independently.