# Harn > Harn is a pipeline-oriented language and runtime for orchestrating AI agents. Harn is pre-1.0. Prefer this file and the per-page `.md` URLs over scraping HTML. If the intended version is unclear, clarify before using these pages. Website: https://harnlang.com/ ## Docs ### Introduction - [Harn](https://harnlang.com/introduction.md): Harn is a programming language and runtime for building AI agents. Model calls, tools, retries, concurrency, transcripts, and workflows are language and standard-library... - [Concepts](https://harnlang.com/concepts/index.md): These pages explain how Harn fits together. They do not replace the syntax reference or a task guide. - [Mental model](https://harnlang.com/concepts/mental-model.md): Think of a Harn program as a task moving through a model, tools, and a recorded run. Add a loop or a workflow only when the task needs it. - [Glossary](https://harnlang.com/concepts/glossary.md): One-line definitions for every term Harn uses to describe a conversation, its parts, and its containers. Where two terms in Harn mean the same thing, the preferred one is... - [Portable execution](https://harnlang.com/concepts/portable-execution.md): Harn has one language implementation and more than one place to run it. The portable kernel makes WebAssembly an adapter for Harn, not a second Harn language. - [Choosing an agent abstraction](https://harnlang.com/concepts/abstraction-ladder.md): Harn ships several agent primitives at different heights on the stack. Use the lowest one that covers what you need. Climbing higher costs you control and code transparency;... - [The expressiveness spectrum](https://harnlang.com/concepts/expressiveness-spectrum.md): One task. Five levels of control. The point of this page is a promise: the easy case stays a few lines, and when you need more control you reach for it without throwing away... - [Steering seams](https://harnlang.com/concepts/steering-seams.md): A steering seam is a point during a running agent loop where the runtime checks for pending out-of-band influence: a queued user message, a system reminder, an inbox feedback... - [Why Harn has model jobs](https://harnlang.com/concepts/model-jobs.md): An image generator and a speech service look different at their HTTP edges. Inside an application, they have the same awkward shape: submit work, wait, show progress, collect... - [Why Harn apps separate behavior from pixels](https://harnlang.com/concepts/interactive-apps.md): A Harn app is a Harn program with an interactive view. The program owns the decisions: state, validation, model calls, restoring work, replay, and recovery. A shared renderer... - [Coming from elsewhere](https://harnlang.com/concepts/sota-comparison.md): Harn's vocabulary doesn't always match what you'd read in OpenAI's, Anthropic's, Flue's, LangGraph's, Inngest's, Mastra's, Cloudflare's, AWS Strands', BAML's, or the... - [Why Harn?](https://harnlang.com/why-harn.md): Building AI agents usually means coordinating models, tools, retries, concurrency, state, and sub-agents. In most languages, that turns into a stack of libraries: - [How Harn compares](https://harnlang.com/how-harn-compares.md): This page is for a developer who runs agents on another system and is deciding whether to move them to Harn. Each row asks where a primitive lives and what the runtime... ### Reference - [Cross-session pattern knowledge](https://harnlang.com/concepts/cross-session-pattern-knowledge.md): Harn owns cross-session pattern recall as a typed harness.knowledge layer over std/memory . The concrete stdlib entrypoint is std/agent/pattern_knowledge , which records... - [Language basics](https://harnlang.com/language-basics.md): This reference covers the core syntax and semantics of Harn. For a runnable program, start with an explicit entrypoint: - [Error handling](https://harnlang.com/error-handling.md): Harn provides try / catch / throw for error handling and retry for automatic recovery. - [Diagnostic codes](https://harnlang.com/diagnostics.md): Every diagnostic emitted by harn check , harn lint , and harn fmt carries a stable HARN-- code. Codes are dispatchable: agents, IDEs, and the hosted error pages all... - [Reading shape diagnostics](https://harnlang.com/reading-shape-diagnostics.md): Harn's typechecker and runtime aim to fail loudly at the closest point to the bug. Most authoring mistakes around shapes, structs, schemas, and nilable values surface as one of... - [Modules and imports](https://harnlang.com/modules.md): Harn supports splitting code across files using import and top-level fn declarations. - [Concurrency](https://harnlang.com/concurrency.md): Harn concurrency is structured around child tasks. A child task runs the block you give to spawn or parallel in its own interpreter instance, while the parent keeps a handle,... - [Streams](https://harnlang.com/streams.md): Streams are lazy, single-pass values produced by gen fn . A stream emits values over time and can be consumed with for , .next() , or .iter() . - [Runtime context](https://harnlang.com/runtime-context.md): Harn exposes logical runtime identity through runtime_context() . This is the task/thread abstraction Harn code should use for observability and debugging; raw OS thread IDs... - [Filesystem Host Capabilities](https://harnlang.com/host-capabilities/fs.md): Filesystem access is exposed through the capability-aware harness.fs sub-handle. Free filesystem globals do not exist in the script-facing language: the nominal handle is both... - [Harn language specification](https://harnlang.com/language-spec.md): Version: tracks the current workspace release series; derived from the implementation and updated alongside it. The language is still pre-1.0 — surface-level breaking changes... - [Lexical rules](https://harnlang.com/spec/language/01-lexical-rules.md): Spaces ( ' ' ), tabs ( '\t' ), and carriage returns ( '\r' ) are insignificant and skipped between tokens. Newlines ( '\n' ) are significant tokens used as statement... - [Grammar](https://harnlang.com/spec/language/02-grammar.md): The grammar is expressed in EBNF. Newlines between statements are implicit separators (the parser skips them with skipNewlines() ). Semicolons are accepted as alternate... - [Operator precedence table](https://harnlang.com/spec/language/03-operator-precedence-table.md): The table runs from lowest to highest binding. Operators with higher binding group first. For example, a && b || c parses as (a && b) || c because && binds more tightly than || . - [Scope rules](https://harnlang.com/spec/language/04-scope-rules.md): Harn uses lexical scoping with a parent-chain environment model. - [Destructuring patterns](https://harnlang.com/spec/language/05-destructuring-patterns.md): Destructuring binds multiple variables from a dict or list in a single const , let , or for - in statement. - [Evaluation order](https://harnlang.com/spec/language/06-evaluation-order.md): If no pipeline is found in the file, all top-level statements are compiled and executed directly as an implicit entry point (script mode). This allows simple scripts to work... - [Runtime values](https://harnlang.com/spec/language/07-runtime-values.md): Values are equal if they have the same type and same contents, with these exceptions: - [Binary operator semantics](https://harnlang.com/spec/language/08-binary-operator-semantics.md): ¹ When an int result would overflow the 64-bit range, it promotes to float rather than wrapping two's-complement (so i64::MAX + 1 is a large float , not a negative int ). This... - [Control flow](https://harnlang.com/spec/language/09-control-flow.md): else if chains are parsed as a nested ifElse node in the else branch. - [Concurrency](https://harnlang.com/spec/language/10-concurrency.md): runtime_context() returns the current logical runtime context as a dict. task_current() is an alias. This is Harn's stable task/thread identity surface; OS thread IDs are not... - [Pipeline lifecycle](https://harnlang.com/spec/language/11-pipeline-lifecycle.md): Pipelines do not end the moment their declared steps return. Between the last statement of the pipeline body and the value the host sees, the runtime fires a fixed sequence of... - [Error model](https://harnlang.com/spec/language/12-error-model.md): Evaluates the expression and throws it as HarnRuntimeError.thrownError(value) . Any value can be thrown (strings, dicts, etc.). - [Functions and closures](https://harnlang.com/spec/language/13-functions-and-closures.md): Declares a named function. Equivalent to let name = { param1, param2 -> ... } . The function captures the lexical scope at definition time. - [Enums](https://harnlang.com/spec/language/14-enums.md): Enums define a type with a fixed set of named variants, each optionally carrying associated data. - [Structs](https://harnlang.com/spec/language/15-structs.md): Structs define named record types with typed fields. Structs may also be generic. - [Impl blocks](https://harnlang.com/spec/language/16-impl-blocks.md): Impl blocks attach methods to a struct type. - [Interfaces](https://harnlang.com/spec/language/17-interfaces.md): Interfaces define a set of method signatures that a struct type must implement. Harn uses Go-style implicit satisfaction: a struct satisfies an interface if its impl block... - [Attributes](https://harnlang.com/spec/language/18-attributes.md): Attributes are declarative metadata attached to a top-level declaration with the @ prefix. They compile to side-effects (warnings, runtime registrations) at the attached... - [Type annotations](https://harnlang.com/spec/language/19-type-annotations.md): Harn has an optional, gradual type system. Omitting annotations is always valid. - [Built-in methods](https://harnlang.com/spec/language/20-built-in-methods.md): chars() (also the chars(text) builtin) materializes a string into a list of single-character strings in one linear pass. Because a string is UTF-8, random character access (... - [Iterator protocol](https://harnlang.com/spec/language/21-iterator-protocol.md): Harn provides a lazy iterator protocol layered over the eager collection methods. Eager methods ( list.map , list.filter , list.flat_map , dict.map_values , dict.filter , etc.)... - [Method-style builtins](https://harnlang.com/spec/language/22-method-style-builtins.md): If obj.method(args) is called and obj is an identifier, the interpreter first checks for a registered builtin named "obj.method" . If found, it is called with just args (not... - [Runtime errors](https://harnlang.com/spec/language/23-runtime-errors.md): Most undefinedBuiltin errors are now caught statically by the cross-module typechecker (see Static cross-module resolution ) — harn check and harn run refuse to start the VM... - [OAuth](https://harnlang.com/spec/language/24-oauth.md): Programs may compose OAuth flows by importing from std/oauth/* . The stack is portable across providers: there is no provider-specific Rust code in the language runtime. - [Persistent store](https://harnlang.com/spec/language/25-persistent-store.md): Six builtins provide a persistent key-value store backed by the resolved Harn state root (default .harn/store.json ): - [Checkpoint & resume](https://harnlang.com/spec/language/26-checkpoint-resume.md): Checkpoints enable resilient, resumable pipelines. State is persisted to the resolved Harn state root (default .harn/checkpoints/.json ) and survives crashes,... - [Agent lifecycle (suspend/resume)](https://harnlang.com/spec/language/27-agent-lifecycle-suspend-resume.md): Agent workers are cooperatively schedulable. A running worker may yield — mid-loop, at a turn boundary — to be resumed later in the same process, a different process, or on... - [Host shell discovery](https://harnlang.com/spec/language/28-host-shell-discovery.md): The process host capability owns shell discovery and shell-mode invocation. This keeps IDEs, TUIs, headless CLI runs, and cloud workers on the same contract instead of... - [Workspace manifest (`harn.toml`)](https://harnlang.com/spec/language/29-workspace-manifest-harn-toml.md): Harn projects declare a workspace manifest at the project root named harn.toml . Tooling walks upward from a target .harn file looking for the nearest ancestor manifest and... - [Sandbox mode](https://harnlang.com/spec/language/30-sandbox-mode.md): The harn run command installs a default worktree sandbox before the VM starts. The default policy uses sandbox_profile: "worktree" , roots filesystem/process access at the... - [Test framework](https://harnlang.com/spec/language/31-test-framework.md): Harn includes a built-in test runner invoked via harn test . - [Environment variables](https://harnlang.com/spec/language/32-environment-variables.md): The following environment variables configure runtime behavior: - [Known limitations and future work](https://harnlang.com/spec/language/33-known-limitations-and-future-work.md): The following are known limitations in the current implementation that may be addressed in future versions. - [Platform support](https://harnlang.com/platform-support.md): Which operating systems and processors Harn runs on, and what "supported" means for each. - [LLM calls and agents](https://harnlang.com/llm-and-agents.md): Use the smallest API that matches the job: - [LLM calls](https://harnlang.com/llm/llm_call.md): Make a single LLM request. Harn normalizes provider responses into a canonical dict so product code does not need to parse provider-native message shapes. - [LLM handler helpers](https://harnlang.com/llm/handlers.md): std/llm/handlers provides small middleware helpers for call handlers that accept a call dict such as {prompt, system, opts} . - [LLM reranking](https://harnlang.com/llm/rerank.md): std/llm/rerank provides pairwise reranking helpers for cases where a single scalar score is brittle, plus a low-level confidence helper for models that expose token log... - [Agent loops](https://harnlang.com/llm/agent_loop.md): Run an agent that keeps working until it's done. The agent maintains conversation history across turns. Native-tool loops stop naturally when the model returns final assistant... - [Completion control](https://harnlang.com/llm/completion-control.md): Agent loops combine mode-aware completion instructions, optional judges, input guardrails, and a deterministic completion gate. These controls share the loop contract but can... - [Prompt optimization](https://harnlang.com/llm/optimize.md): std/llm/optimize provides a deterministic prompt-search loop for tuning an instruction against an eval set: - [Composable callers and middleware](https://harnlang.com/stdlib/llm-handlers.md): Harn's agent_loop and llm_call historically exposed only a flat options dict for retry / fallback / shadow / budget behavior. v0.8 opens an explicit caller seam : agent_loop... - [Composable tool middleware](https://harnlang.com/stdlib/tool-middleware.md): Harn's agent_loop exposes two composable seams for tool calls — mirrors of the llm_caller seam at the model boundary, but operating on tool execution. They let harness authors... - [Model-job reference](https://harnlang.com/stdlib/model-jobs.md): Import std/model_job for the public model-job, media-asset, ComfyUI, and test APIs. - [std/ui reference](https://harnlang.com/stdlib/ui.md): std/ui is the typed application layer over MCP Apps . It exports std/ui/contracts , std/ui/renderer , and std/ui/testing . - [LLM tools](https://harnlang.com/llm/tools.md): agent_loop(harness, ...) does not need a bespoke host tool for every deterministic operation. The fastest path is usually to wrap pure stdlib logic in a typed tool and let the... - [LLM ensemble helpers](https://harnlang.com/llm/ensemble.md): std/llm/ensemble contains deterministic orchestration helpers for search patterns around model calls. The helpers are plain Harn functions, so tests can mock or replace... - [LLM streaming and transcripts](https://harnlang.com/llm/streaming.md): llm_stream returns a channel that yields response chunks as they arrive. Iterate over it with a for loop: - [Transcript projection](https://harnlang.com/llm/transcript-projection.md): Transcript projection is the read-side dual of compaction. Compaction archives historical messages forever; projection picks which slice of the unchanged raw transcript the... - [LLM providers](https://harnlang.com/llm/providers.md): Harn includes adapters for common cloud providers and local OpenAI-compatible servers. The model catalog is the current source of truth: - [Provider capability matrix](https://harnlang.com/provider-matrix.md): This table is generated from Harn's live provider capability rules. Model pattern is the model_match rule used by the runtime; first match wins within each provider. Version... - [Provider support recommendations](https://harnlang.com/provider-support.md): This page aggregates Harn's provider/model catalog, runtime capability rules, small curated notes, and optional harn eval coding-agent benchmark summaries. Regenerate with make... - [Provider catalog refresh workflow](https://harnlang.com/llm/provider-catalog-refresh.md): scripts/update_provider_catalog.harn is the Harn-native workflow that periodically collects model availability, pricing, and capability signals from provider sources,... - [Coding Agent Provider Benchmark](https://harnlang.com/llm/coding-agent-benchmark.md): harn eval coding-agent runs a small, repeatable coding-agent fixture suite across provider/model selectors and tool-call formats. The suite covers tiny task shapes that stress... - [Layered runtime configuration](https://harnlang.com/configuration.md): Harn runtime configuration is a typed, layered document used by the CLI, VM hosts, and downstream products to explain model policy, permissions, protocol endpoints, package and... - [Long-running tools](https://harnlang.com/long-running-tools.md): Long-running tool handles let a script start slow work, continue the agent loop, and receive the final result through the pending feedback queue on a later turn. The idiom is... - [Tool surface validation](https://harnlang.com/tool-surface-validation.md): Harn validates agent tool surfaces before a loop or workflow stage spends model tokens. The validator checks the active tool registry, capability policy, approval policy, and... - [Durable step stdlib](https://harnlang.com/stdlib/step.md): step.run(key, input?, handler, options?) memoizes a handler result in Harn's active EventLog. On a later process restart or script replay, Harn re-executes the program from the... - [Cache stdlib](https://harnlang.com/stdlib/cache.md): std/cache is the content-addressed cache substrate that lets every "I already computed this" decision share one governed implementation: LLM calls, repo scans,... - [Calendar stdlib](https://harnlang.com/stdlib/calendar.md): std/calendar layers civil-time, timezone, country, and business-calendar helpers over Harn's timestamp builtins. Use it when a workflow needs local calendar semantics instead... - [External actions](https://harnlang.com/stdlib/external-action.md): std/external_action binds consequential provider effects to exact authorization and durable receipts. It is the shared lifecycle for purchases, messages, calendar writes,... - [Daemon stdlib](https://harnlang.com/stdlib/daemon.md): Harn's daemon builtins wrap the existing agent_loop(harness, ..., {daemon: true}) runtime so scripts can manage long-lived assistants without hand-assembling snapshot paths and... - [harness.agent.current_id()](https://harnlang.com/stdlib/agent_session_current_id.md): Return the innermost active agent session id for the currently executing VM thread. - [Compaction pins and the goal object](https://harnlang.com/stdlib/agent-pins-goal.md): Two additive stdlib modules give long-running agents durable intent: std/agent/pins keeps load-bearing context alive across compaction, and std/agent/goal turns a fuzzy... - [Runtime introspection tools](https://harnlang.com/stdlib/runtime-introspection.md): Harness authors can put model identity and runtime facts in prompts, but model-visible prose goes stale and models often answer identity questions from their own training... - [Monitor stdlib](https://harnlang.com/stdlib/monitors.md): std/monitors provides wait_for(...) for waiting on external state while preserving deterministic replay records. - [Pool stdlib](https://harnlang.com/stdlib/lifecycle-pool.md): std/lifecycle/pool provides named, concurrency-bounded agent worker pools . Use a pool when work needs to share a single concurrency budget across an entire pipeline, session,... - [Pipeline lifecycle](https://harnlang.com/pipeline-lifecycle.md): Pipeline vs. workflow. Two different things that are deliberately not renamed — learn the distinction once: - [Pipeline lifecycle presets (std/lifecycle)](https://harnlang.com/stdlib/lifecycle.md): The pipeline DSL accepts a single on_finish callback that runs after the pipeline's declared steps complete and before the pipeline returns its value to the host. The callback... - [Observability](https://harnlang.com/stdlib/observability.md): std/observability is the friendly API for user-space spans, logs, metrics, and structured events. Configure routing once at runtime, then emit observations without choosing a... - [Run-record observability outputs](https://harnlang.com/observability/run-record-outputs.md): Harn persists the projections it computes while an agent runs. Observability consumers should read these fields instead of parsing assistant text or reconstructing spans from... - [Timing](https://harnlang.com/stdlib/timing.md): std/timing is the scoped-duration primitive for Harn scripts. It replaces hand-rolled let started_ms = harness.clock.now_ms() subtraction with a first-class observability span... - [Verification](https://harnlang.com/stdlib/verification.md): std/verification is the Harn-owned home for deterministic verification facts. It keeps reusable verification substrate in Harn rather than in a particular host product: hosts... - [Agent governors and detectors](https://harnlang.com/stdlib/governors.md): std/agent/governors and the unified detector surface in std/agent/stall provide the generic runtime guardrails an agent host would otherwise hand-roll on top of agent_loop : a... - [Agent guardrails (std/agent/guardrails)](https://harnlang.com/stdlib/agent-guardrails.md): Input guardrails are the input-side pair to agent_completion_gate : they decide whether a request should stop before the main agent loop spends a model turn. Harn owns the... - [Completion gate (std/agent/completion_gate)](https://harnlang.com/stdlib/agent-judge.md): agent_completion_gate(runtime, options) returns an options fragment for agent_loop . It checks host-supplied write and verification facts and can add a bounded LLM judge. Harn... - [Host-supplied facts](https://harnlang.com/stdlib/fact-intake-seams.md): Some of the most useful signals for steering an agent live outside the loop. The loop can count iterations and tokens and spot a repeated error, but it cannot know whether your... - [GraphQL stdlib](https://harnlang.com/stdlib/graphql.md): import "std/graphql" provides a small provider-neutral substrate for GraphQL-backed connector packages. - [Code librarian stdlib](https://harnlang.com/stdlib/code-librarian.md): import "std/code_librarian" exposes typed helpers over the nominal HarnessCodeIndex interface (issue #2434 , PR #2441 ) as a single as one ergonomic module. Consumers—IDE... - [Edit stdlib](https://harnlang.com/stdlib/edit.md): import "std/edit" exposes safe, structured helpers for mutating source files. Three flavors live side by side: - [Diff stdlib](https://harnlang.com/stdlib/diff.md): import "std/diff" exposes line-oriented diff helpers and structural review summaries backed by hostlib tree-sitter parsing. - [OAuth storage stdlib](https://harnlang.com/stdlib/oauth-storage.md): std/oauth/storage is the token-store abstraction shared by the OAuth client ( OAuth.client(...) , RFC 6749 + 7636, RFC 8628 device flow). One storage handle backs every grant... - [Prompt library stdlib](https://harnlang.com/stdlib/prompt-library.md): std/prompt_library manages reusable prompt fragments and deterministic hotspot proposals for repeated context prefixes. - [Identity stdlib](https://harnlang.com/stdlib/identity.md): std/identity provides Harn-native helpers for inspecting RFC 8693-style ActorChain dicts. Use it when a script, connector, status surface, or audit receipt needs the same... - [Disclosure stdlib](https://harnlang.com/stdlib/disclosure.md): std/disclosure renders authorship disclosure artifacts from an RFC 8693-style ActorChain value. Use it when a host or connector needs the same actor chain represented in a... - [Lanes and prompt overlays](https://harnlang.com/stdlib/agent-lanes-overlays.md): Two additive stdlib modules generalize hand-rolled orchestration mechanisms from burin-code into stdlib: std/agent/lanes (tool-surface narrowing keyed off a data-driven task... - [Human in the loop](https://harnlang.com/hitl.md): Harn's human-in-the-loop surface is first-class typed syntax . ask_user , request_approval , dual_control , and escalate_to are reserved keywords parsed as language-level... - [Trust graph](https://harnlang.com/trust-graph.md): Harn's trust graph is the runtime-owned event stream for autonomy decisions. Every trigger dispatch now appends a hash-chained OpenTrustGraph TrustRecord to trust_graph plus... - [Autonomy tiers](https://harnlang.com/autonomy.md): Harn enforces graduated autonomy at side-effect boundaries. Agent and workflow code can choose a tier, but the VM is responsible for deciding whether a mutating builtin... - [Audit receipts](https://harnlang.com/audit-receipts.md): Harn owns one canonical audit receipt envelope for run, persona, tool, model, approval, handoff, and side-effect summaries: - [Redaction policy](https://harnlang.com/redaction.md): Harn writes operational data to several places that an outside party might eventually see — .harn-runs/* transcripts, Receipt envelopes, the JSONL event log, the portal API,... - [Hooks](https://harnlang.com/extensibility/hooks.md): Harn exposes three concentric hook surfaces. Each surface fires synchronously on the agent-loop thread. Runtime hook handlers run inside the same VM context as the surrounding... - [Preset tool hooks](https://harnlang.com/tool-hooks.md): preset_run_command(...) is the shipped wrapper for the catalogue-driven "command faux-pas" library (epic #1884 ). It turns a versionable corpus of shell-mistake rules — find .... - [Contributing preset hooks](https://harnlang.com/contributing/preset-hooks.md): This guide is for contributors adding a new rule (or a whole new stack catalogue) to the shipped preset_run_command corpus. The shipped "harn-canon" catalogues live under... - [Context maintenance hook recipes](https://harnlang.com/context-maintenance-hooks.md): Long-lived coding hosts need context work that should not block the foreground agent turn: fast index refreshes after file edits, slower librarian or crystallization passes... - [Skills](https://harnlang.com/skills.md): Harn discovers skills — bundled instructions, tool lists, and activation rules — from the filesystem and from the host process. Every skill is a directory containing a SKILL.md... - [Engineering principles](https://harnlang.com/dev/engineering-principles.md): Harn is the orchestration substrate for products built across command-line, terminal, editor, headless, and cloud surfaces. Those surfaces should feel like one product because... - [Personas](https://harnlang.com/personas.md): Personas are durable agent roles. A persona is not a prompt file; it is an operational service contract that names an entry workflow and binds it to triggers, schedules, tools,... - [Persona prelude](https://harnlang.com/personas/prelude.md): std/personas/prelude provides small orchestration primitives for persona workflows. Each helper returns an explicit envelope with ok , status , result , error , and receipt... - [Per-stage tool scoping](https://harnlang.com/personas/stages.md): A persona that walks through research → plan → edit → verify usually runs the entire run under one ambient CapabilityPolicy . The model is trusted by prompt convention to only... - [Handoff policy overrides](https://harnlang.com/personas/handoff.md): Persona handoffs can carry a policy_override field on the typed handoff payload. The value is a normal CapabilityPolicy dict: - [Profile bulletins](https://harnlang.com/personas/profile-bulletins.md): std/personas/bulletins is Harn's typed envelope for proposing durable persona/user/project/team facts. Bulletins make persona context auditable and reviewable rather than... - [Merge captain persona](https://harnlang.com/personas/merge-captain.md): The Merge Captain persona is a Harn-native runbook for owning pull-request queues across multiple repositories. It is the recommended starting point for teams that want a... - [Skill provenance](https://harnlang.com/skill-provenance.md): Harn can require cryptographic provenance for filesystem-backed skills before load_skill(...) promotes their bodies into an agent session. The design is intentionally small: - [Skill activation evidence](https://harnlang.com/skill-activation-evidence.md): Harn owns one stable, host-consumable record of what happened to each skill this turn : which short cards were shown, which were omitted and why, what each cost against the... - [Sessions](https://harnlang.com/sessions.md): A session is a first-class VM resource that owns three things for a given conversational agent run: - [Workspace Anchor Cache Contract](https://harnlang.com/agents/cache_contract.md): The session workspace_anchor is transient turn context, not durable system prompt content. - [Session bundles](https://harnlang.com/session-bundles.md): A session bundle is the portable JSON envelope for moving a persisted Harn run between local debugging, support handoff, sharing, and replay workflows. It is built from the... - [Agent state](https://harnlang.com/agent-state.md): std/agent_state is Harn's durable, session-scoped scratch space for agent orchestration. It gives a caller-owned root directory plus a session id a small set of predictable... - [Agent lifecycle: suspend, resume, stop, self-park](https://harnlang.com/agent-lifecycle.md): Harn agents can park mid-loop, persist a resumable snapshot, resume later, or hand unfinished child work back to a parent with a typed stop handoff. This reference defines the... - [Memory](https://harnlang.com/memory.md): std/memory provides durable observations that can be recalled across later runs without treating transcript history as long-term knowledge. - [Cross-session pattern knowledge](https://harnlang.com/concepts/cross-session-pattern-knowledge.md): Harn owns cross-session pattern recall as a typed harness.knowledge layer over std/memory . The concrete stdlib entrypoint is std/agent/pattern_knowledge , which records... - [Transcript architecture](https://harnlang.com/transcript-architecture.md): Harn transcripts are now versioned runtime values with three distinct layers: - [Prompt assembly](https://harnlang.com/prompt-assembly.md): Every system prompt Harn sends to a model is the deterministic reduction of an ordered list of fragments , unless the caller selects an exclusive replacement root. The public... - [System reminders](https://harnlang.com/system-reminders.md): System reminders are typed transcript injections for a running agent session. They let Harn add ambient context at turn boundaries, such as token-pressure warnings,... - [Workflow runtime](https://harnlang.com/workflow-runtime.md): Harn's workflow runtime is the layer above raw harness.llm.call() and agent_loop(harness, ...) . It gives host applications a typed, inspectable, replayable orchestration... - [Portable workflow bundles](https://harnlang.com/workflow-bundles.md): A workflow bundle is Harn's local-first artifact for durable engineering automations. It is designed to run on a trusted laptop under your editor or the CLI and to remain... - [Typed task-plan IR (experimental)](https://harnlang.com/task-plan-ir.md): Status: experimental, behind no flag — the module is std/agent/task_plan . See burin-labs/harn#2196 for the recommendation that keeps this in experimental tier and the eval... - [Prepared-run authority](https://harnlang.com/prepared-run.md): harn_vm::prepared_run reconciles everything a workflow needs with everything its host can safely provide before execution starts. It is intended for product hosts, headless... - [Local workflow supervisor](https://harnlang.com/workflow-supervisor.md): harn supervisor is the stable local host surface for Burin GUI/TUI/CLI automation management. It wraps the existing orchestrator runtime instead of creating a second scheduler... - [Governed code mode](https://harnlang.com/code-mode.md): Governed Code Mode is executable tool composition with a small API surface and normal Harn audit. A model sees a binding manifest, writes a short Harn snippet against those... - [Team learning and context packs](https://harnlang.com/team-learning.md): Harn can turn repeated team friction into reviewable context packs or promoted workflows. The loop is: - [Workflow crystallization](https://harnlang.com/workflow-crystallization.md): Workflow crystallization mines repeated agent traces into a reviewable workflow skeleton and a machine-readable manifest of what that workflow would need to run. It is a review... - [Flow predicate language](https://harnlang.com/flow-predicates.md): Status: design decision record for Harn Flow v0. This page records the predicate-language decisions and the implementation shape they imply. - [Workflow State Channels v0](https://harnlang.com/spec/workflow-channels/v0.md): Status: exploratory design record - [Protocol support matrix](https://harnlang.com/protocol-support.md): This page is the quick routing table for Harn's protocol surfaces. The canonical task guides remain: - [MCP and ACP integration](https://harnlang.com/mcp-and-acp.md): Harn has built-in support for the Model Context Protocol (MCP), Agent Client Protocol (ACP), and Agent-to-Agent (A2A) protocol. This guide covers how to use each from both... - [Outbound workflow server](https://harnlang.com/harn-serve.md): harn-serve is the shared outbound-server crate for exposing Harn workflows to external callers. It contains the local Agents API, MCP, A2A, and ACP adapters plus the shared... - [Embedding Harn in Rust](https://harnlang.com/embedding-rust.md): harn-serve exposes the same ACP agent loop used by harn serve acp as a Rust API. Use it when a host application wants Harn in-process instead of spawning the CLI as a child... - [Portable kernel contract](https://harnlang.com/portable-kernel-reference.md): This page specifies Portable Harn Kernel artifact version 2 and its execute/resume boundary. - [Bridge protocol](https://harnlang.com/bridge-protocol.md): Harn's stdio bridge uses JSON-RPC 2.0 notifications and requests for host/runtime coordination below ACP session semantics. - [Generated protocol artifacts](https://harnlang.com/protocol-artifacts.md): Harn publishes downstream protocol artifacts under spec/protocol-artifacts/ . The directory is generated by: - [Host tools over the bridge](https://harnlang.com/bridge/host-tools.md): harness.tools.list_registered() and harness.tools.invoke(name, args) are the host-side mirror of Harn's LLM-facing tool_search flow: the script can ask the host what tools... - [ACP over WebSocket](https://harnlang.com/acp/websocket.md): Harn exposes ACP over WebSocket in two places: - [Harn ACP/MCP extensions v1](https://harnlang.com/spec/harn-extensions/v1.md): Canonical URL: https://harnlang.com/spec/harn-extensions/v1 - [MCP Apps UI resources](https://harnlang.com/interop/ui-resource.md): std/ui_resource packages interactive HTML widgets as portable UI resource records that follow the MCP Apps overview and fall back to text or structured tool output when a host... - [Harn agents protocol v1](https://harnlang.com/spec/agents-protocol/v1.md): The Harn Agents Protocol is the public wire contract for managed Harn agents. It lets clients, hosts, and third-party Harness implementations create sessions, submit tasks,... - [Harn agents protocol receipt format](https://harnlang.com/spec/agents-protocol/receipt-format-v1.md): The canonical receipt-format artifact lives in agents-protocol-receipts . - [Harn agents protocol replay contract](https://harnlang.com/spec/agents-protocol/replay-v1.md): This directory is the canonical v1 replay-as-API contract for the Harn Agents Protocol. It makes Harn's durable EventLog replay model visible as a public API verb without... - [Triggers](https://harnlang.com/triggers.md): Triggers connect external events to typed Harn handlers. A trigger binding matches inbound deliveries from a provider, optionally gates them through a typed predicate, and then... - [Trigger stdlib](https://harnlang.com/stdlib/triggers.md): The trigger stdlib exposes the live runtime registry to Harn scripts. Use it to inspect installed bindings, register new bindings at runtime, fire synthetic events for... - [Trigger manifests](https://harnlang.com/triggers/manifest.md): [[triggers]] extends harn.toml with declarative trigger registrations in the same manifest-overlay family as [exports] , [llm] , and [[hooks]] . - [Trigger budgets](https://harnlang.com/triggers/budgets.md): LLM-backed trigger predicates can run on every inbound event. A broad Slack classifier that asks "does this mention cake?" in a busy channel can become a runaway cost source,... - [Trigger event schema](https://harnlang.com/triggers/event-schema.md): TriggerEvent is the normalized envelope every inbound trigger provider converges on before dispatch. Connectors preserve provider-specific payload fidelity inside... - [Trigger dispatcher](https://harnlang.com/triggers/dispatcher.md): The trigger dispatcher is the runtime path that turns a normalized TriggerEvent plus a live registry binding into actual handler work. - [Trigger registry](https://harnlang.com/triggers/registry.md): The trigger registry is the runtime-owned binding table that turns validated [[triggers]] manifest entries into live, versioned trigger bindings inside a VM thread. - [Generic webhook intake substrate](https://harnlang.com/triggers/webhook-intake.md): The webhook intake substrate is the lowest-level layer connectors compose with to absorb webhook deliveries. It is deliberately ignorant of any specific provider (GitHub,... - [Agent channels](https://harnlang.com/agent-channels.md): Agent channels are a typed, durable pub/sub primitive for orchestrating multiple agents (and the triggers that watch them). One agent calls harness.channels.append(name,... - [Fleet coordination](https://harnlang.com/fleet-coordination.md): std/fleet/coordination adds a typed fleet vocabulary and a deterministic status projection on top of Harn's existing durable coordination ledger. It is an explicit-import... - [Agent pools](https://harnlang.com/agent-pools.md): Agent pools are named, concurrency-bounded worker pools for agent work. Use a pool when many independently-submitted tasks need to share one concurrency budget — capping how... - [Orchestrator](https://harnlang.com/orchestrator.md): harn orchestrator serve is the long-running process entry point for manifest-driven trigger ingestion and connector activation. - [Hot reload](https://harnlang.com/orchestrator/hot-reload.md): Hot reload lets a running orchestrator adopt a new harn.toml without dropping in-flight trigger deliveries. - [Orchestrator DLQ management](https://harnlang.com/orchestrator/dlq.md): Harn records failed trigger deliveries in trigger.dlq . The portal exposes that event-log topic at /dlq so operators can inspect, replay, purge, and export dead-letter entries... - [Dashboard job envelopes](https://harnlang.com/orchestrator/dashboard-jobs.md): std/dashboard/jobs defines the portable status event Harn emits for Jobs surfaces in a local editor and a cloud platform. The contract is intentionally a dashboard-facing... - [Orchestrator backpressure](https://harnlang.com/orchestrator/backpressure.md): Harn applies backpressure at the HTTP ingest edge, the durable trigger queue, and dispatcher destinations. The goal is to slow new work before one noisy source, one slow... - [Worker dispatch](https://harnlang.com/orchestrator/worker-dispatch.md): worker:// is Harn's durable queue-delegation path for triggers. Unlike a2a://... , it does not call a specific remote agent immediately. The dispatcher appends a job to... - [Local and A2A dispatch](https://harnlang.com/orchestrator/local-a2a-dispatch.md): Harn trigger handlers can move between in-process execution and A2A dispatch without changing the handler's input contract. Keep the trigger id , provider match, retry policy,... - [Orchestrator secrets](https://harnlang.com/orchestrator/secrets.md): Reactive Harn features need a single way to fetch secrets without sprinkling provider-specific code across connectors, OAuth flows, and future orchestrator runtime surfaces.... - [Multi-tenant orchestrator](https://harnlang.com/orchestrator/multi-tenant.md): Harn can run the orchestrator listener in a tenant-aware mode: - [Connector OAuth](https://harnlang.com/orchestrator/oauth.md): harn connect is the guided setup entry point for connector credentials. It is intended for local operator setup: run the browser flow once, store tokens in the workspace... - [Orchestrator MCP server](https://harnlang.com/mcp-server.md): harn mcp serve exposes a local Harn orchestrator as an MCP server so any MCP client can fire triggers, inspect queues, replay events, and read runtime state without a... - [Extend Harn](https://harnlang.com/extend-harn.md): Five things in Harn are meant to be extended by you. They are documented separately because they are genuinely different mechanisms; this page is the map. - [Package authoring](https://harnlang.com/package-authoring.md): Harn packages are ordinary Harn projects with package metadata, stable exports, tests, and optional connector contracts in harn.toml . They use the same [dependencies] ,... - [Connector authoring](https://harnlang.com/connectors/authoring.md): Provider connectors are .harn packages loaded through [[providers]] manifest entries. Rust owns only the provider-neutral runtime substrate in crates/harn-vm/src/connectors/ : - [Connector architecture status](https://harnlang.com/connectors/architecture.md): The original Rust-side connector library plan covered shared connector traits, generic webhooks, cron, GitHub, Slack, Linear, Notion, OAuth helpers, catalog docs, and... - [Connector parity matrix](https://harnlang.com/connectors/parity-matrix.md): This table is generated from connector package manifests. A checked feature means the package declares support for that connector surface; missing support highlights either an... - [Connector catalog](https://harnlang.com/connectors/catalog.md): This catalog is the entry point for choosing a connector, wiring its trigger manifest, and finding a ready-to-customize example. It reflects the current runtime split: - [Connector operator runbook](https://harnlang.com/connectors/operator-runbook.md): This is the release gate for Harn connector ingress. It validates the package contract first, then the HTTP or daemon path that operators actually run. Provider API mappings... - [Connector testkit](https://harnlang.com/connectors/testkit.md): harn_vm::connectors::testkit is the shared fixture surface for Harn core and connector package tests. It keeps connector tests deterministic without live provider credentials,... - [Triage inbox envelopes](https://harnlang.com/connectors/triage-inbox.md): std/triage defines the portable inbox event Harn emits for dashboard surfaces such as Burin Home's Start My Day feed. Connector payloads remain available for audit, but hosts... - [Cron connector](https://harnlang.com/connectors/cron.md): The cron connector is Harn's in-process scheduler for time-triggered work. It implements the shared Connector trait, evaluates cron expressions in an IANA time zone, and... - [GitHub connector](https://harnlang.com/connectors/github.md): GitHub provider behavior lives in the pure-Harn harn-github-connector package. Harn core keeps the shared trigger envelope, webhook signature primitives, inbox/dedupe path, and... - [Linear connector](https://harnlang.com/connectors/linear.md): Linear provider behavior lives in the pure-Harn harn-linear-connector package. Harn core keeps the shared trigger envelope, inbox/dedupe path, metrics, HMAC helpers, and... - [Notion connector](https://harnlang.com/connectors/notion.md): Notion provider behavior lives in the pure-Harn harn-notion-connector package, with outbound API typing in notion-sdk-harn . Harn core keeps the shared trigger envelope,... - [Slack events connector](https://harnlang.com/connectors/slack-events.md): Slack provider behavior lives in the pure-Harn harn-slack-connector package. Harn core keeps the trigger envelope, inbox/dedupe path, effect-policy enforcement, metrics, and... - [Generic webhook connector](https://harnlang.com/connectors/webhook.md): GenericWebhookConnector is the built-in raw HTTP ingress primitive for generic webhook deliveries. It verifies supported HMAC signature conventions against the raw request... - [A2A push connector](https://harnlang.com/connectors/a2a-push.md): a2a-push receives Agent2Agent push-notification webhooks from remote A2A agents. It is for federated Harn orchestrators: one orchestrator can start long-running work on another... - [Harn portal](https://harnlang.com/portal.md): harn portal launches a local observability UI for persisted Harn runs. - [harn usage — LLM spend and usage analytics](https://harnlang.com/usage.md): harn usage turns the per-call cost and token data Harn already records in the event log into spend/usage rollups by provider, model, or a day/week/month time series — including... - [Unified Observability API](https://harnlang.com/observability/unified-api.md): Use std/observability when Harn code wants to record "something happened" without caring whether the configured backend represents it as a log, span, metric, or event. - [Trigger observability in the action graph](https://harnlang.com/observability/triggers-in-action-graph.md): Harn projects trigger activity into both persisted run observability and the live dispatcher event stream. The current surface includes trigger , predicate , dispatch , a2a_hop... - [Orchestrator observability](https://harnlang.com/orchestrator/observability.md): harn orchestrator serve exposes metrics, structured logs, and OpenTelemetry spans for the trigger pipeline. - [Replay benchmarks](https://harnlang.com/observability/replay-benchmarks.md): harn bench replay scores replay determinism fixtures and emits a machine-readable artifact for CI and cloud leaderboard ingestion. It uses the same... - [Tool-call spans](https://harnlang.com/observability/tool-call-spans.md): with_telemetry (from std/llm/tool_middleware ) emits a standardized span for every tool dispatch funneled through the middleware stack. The span shape is the contract that... - [CLI reference](https://harnlang.com/cli-reference.md): All commands available in the harn CLI. - [Benchmark the portable kernel](https://harnlang.com/portable-kernel-benchmarking.md): Use harn bench portable to measure the canonical compiler, artifact decoder, and native execution kernel separately. The command runs pure executions with no host grants,... - [Linked-program reachability](https://harnlang.com/dev/linked-program-reachability.md): Harn removes unused Harn exports when it builds a closed native program. The package linker owns this decision because it can see the entrypoint, resolved module graph,... - [harn --json contract](https://harnlang.com/cli-json-contract.md): Every harn subcommand that exposes a machine-readable mode emits a versioned JSON envelope to stdout . Logs, progress, and warnings continue to go to stderr so a --json... - [Extending the CLI in .harn](https://harnlang.com/cli-extending-in-harn.md): How to add or port a harn subcommand without writing Rust. Most CLI work is a text/JSON transform, a catalog lookup, a directory walk, or a process spawn — once a port lands,... - [std/cli/argparse](https://harnlang.com/cli-argparse-reference.md): Declarative, schema-aware argument parsing for .harn CLI subcommand scripts dispatched via the harn-cli wedge ( harn#2293 epic, harn#2295 ). Each subcommand declares a parser... - [std/cli/envelope](https://harnlang.com/cli-envelope-reference.md): Fail-closed decoders for public harn-cli JSON envelopes published through harn --json-schemas . Emission helpers stay in std/cli/render ; this module owns consume/decode. - [std/cli/render](https://harnlang.com/cli-render-reference.md): Output helpers for .harn CLI subcommand scripts dispatched via the harn-cli wedge ( harn#2293 epic, harn#2296 ). This module is intentionally a thin layer — most port-facing... - [std/cli/paths](https://harnlang.com/cli-paths-reference.md): Application-scoped config, data, and cache directory helpers for CLI subcommand scripts. - [Builtins and Harness capabilities](https://harnlang.com/builtins.md): Reference notes for commonly used pure builtins and effectful Harness methods. This page is a curated subset, not an exhaustive list. The complete, authoritative... - [Postgres](https://harnlang.com/postgres.md): std/postgres exposes VM-native Postgres helpers for Harn pipelines that need tenant state, receipts, event logs, claims, audit records, or other durable relational state. - [SQLite](https://harnlang.com/sqlite.md): std/sqlite exposes VM-native SQLite helpers for Harn scripts that need a local, portable relational store without running a database server. - [Project scanning](https://harnlang.com/project-scan.md): The std/project module now includes a deterministic L0/L1 project scanner for lightweight "what kind of project is this?" evidence without any LLM calls. - [Prompt templating](https://harnlang.com/prompt-templating.md): Harn ships a small template language for rendering .harn.prompt and .prompt asset files or inline template strings. It is invoked by the harness.fs.render_prompt(path,... - [Editor integration](https://harnlang.com/editor-integration.md): Harn provides first-class editor support through an LSP server, a DAP debugger, and a tree-sitter grammar. These cover most modern editors and IDE workflows. - [Testing](https://harnlang.com/testing.md): Harn provides several layers of testing support: a conformance test runner, a standard library testing module, and host-mock helpers for isolating agent behavior from real host... - [Secret store](https://harnlang.com/hostlib/secret_store.md): The secret_store capability is a small, sync host primitive for storing per-application credentials in the operating system's native secret store, with a portable JSON file... - [Text similarity / embeddings](https://harnlang.com/hostlib/embed.md): The embed capability is a cross-platform, fully-offline core for cosine similarity. Hosts register one implementation and scripts reach it only through the hostlib_embed_*... - [Staged filesystem](https://harnlang.com/hostlib/staged-fs.md): harn-hostlib includes a session-scoped filesystem staging layer for hosts that want agents to accumulate a diff before applying it to the working tree. - [Per-tool-call filesystem snapshots](https://harnlang.com/hostlib/fs-snapshot.md): harn-hostlib ships a Gemini-style /restore primitive paralleling the staged filesystem mode : a snapshot captures the pre-image of paths a single mutating tool call is about to... - [Typed terminal sessions](https://harnlang.com/hostlib/terminal-session.md): harn-hostlib can drive an interactive terminal through six schema-backed host operations. The implementation is cross-platform and terminal-native: harn-terminal owns the... - [Ambient host conditions](https://harnlang.com/hostlib/host-conditions.md): std/host_conditions exposes a read-only snapshot of ambient contention: ### Tutorials - [Getting started](https://harnlang.com/getting-started.md): Install Harn, create a project, and run your first program. Harn can run a local model if your machine has room for one, mock a model while you write the program around it, or... - [Build your first workflow](https://harnlang.com/tutorials/build-your-first-workflow.md): By the end of this page you will have built an agent that fixes a failing test and checks its own work. You will start with a single model call, grow it into an agent that can... - [Tutorial: build a code review agent](https://harnlang.com/tutorial-code-review-agent.md): This tutorial shows a small but realistic review pipeline. The goal is not to rebuild a full IDE integration. Instead, we want a deterministic Harn program that can review a... - [Tutorial: build an MCP server](https://harnlang.com/tutorial-mcp-server.md): This tutorial builds a small MCP server in Harn. The same program can expose tools, static resources, resource templates, and prompts over stdio or Streamable HTTP. - [Tutorial: build an eval pipeline](https://harnlang.com/tutorial-eval-pipeline.md): This tutorial builds a small evaluation loop that runs a set of examples, records metrics, and produces an auditable summary. The goal is to make quality visible, not to build... - [Tutorial: from one-shot agent to durable daemon](https://harnlang.com/tutorial-daemon-agent.md): This tutorial walks an agent through every rung of the lifecycle ladder: from a single agent_loop call that returns once, to a parked worker that survives process restart, to a... ### Guides - [Common tasks](https://harnlang.com/common-tasks.md): Find the task that matches your next step. Follow one path until you have a working first version, then return to the reference pages for detail. - [Configure a model provider](https://harnlang.com/provider-setup.md): This guide helps you connect Harn to a model provider. It covers the checks you can run before you put a provider in a program. - [How to run a workflow bundle from the CLI](https://harnlang.com/workflow-authoring-quickstart.md): This guide takes a fresh harn install from "I have the binary" to "I can author, validate, preview, run, and supervise a portable workflow bundle." Every command and fixture... - [Cookbook](https://harnlang.com/cookbook.md): Task-oriented recipes for building agents and pipelines in Harn. Each recipe is self-contained — copy a block into a .harn file, set the provider credentials it expects, and run. - [Scripting cheatsheet](https://harnlang.com/scripting-cheatsheet.md): A compact, prose-friendly tour of everything you need to write real Harn scripts. The companion one-page LLM reference is at docs/llm/harn-quickref.md (published in the mdBook)... - [Harn quick reference (LLM-friendly)](https://harnlang.com/docs/llm/harn-quickref.md): Canonical URL: https://harnlang.com/docs/llm/harn-quickref.html - [Best practices](https://harnlang.com/best-practices.md): These habits make Harn programs easier to understand, test, and operate. - [Run an A/B experiment](https://harnlang.com/cookbooks/ab-experiment.md): You changed a prompt, a cache policy, or a model route, and you want to know whether it actually helped. Harn has three surfaces for that. Pick by what you are comparing. - [Coming from LangChain](https://harnlang.com/cookbooks/coming-from-langchain.md): You know how to build an agent. This page maps the LangChain pieces you already reach for onto their Harn equivalents so you can port a working idea rather than relearn the... - [Compile a bounded experiment from a hypothesis](https://harnlang.com/cookbooks/compile-hypothesis.md): Use std/eval/hypothesis when an agent or product needs to turn a question into an experiment without letting model output become executable authority. The planner produces... - [Pipeline lifecycle cookbook](https://harnlang.com/cookbooks/lifecycle.md): End-to-end patterns for the callback-first pipeline lifecycle. Each recipe is a self-contained, copy-paste starting point. For the surface reference see Pipeline lifecycle ;... - [Tool hooks cookbook](https://harnlang.com/cookbooks/tool-hooks.md): Copy-paste recipes for the preset_run_command wrapper. Drop one into a pipeline default(harness: Harness, task) { ... } body, wire the returned closure into your agent_loop 's... - [Channel cookbook](https://harnlang.com/cookbooks/channels.md): End-to-end patterns for agent channels. Each recipe is a self-contained, copy-paste starting point. For the surface reference see Agent channels ; for the LLM-friendly quickref... - [Pool cookbook](https://harnlang.com/cookbooks/pools.md): End-to-end patterns for agent pools. Each recipe is a self-contained, copy-paste starting point. For the surface reference see Agent pools ; for the LLM-friendly quickref see... - [Rename a symbol across the workspace](https://harnlang.com/cookbooks/rename-symbol.md): edit_rename_symbol is the safe alternative to grep + per-file text replace for cross-file renames. It uses the typed symbol graph from std/code_librarian to resolve the seed... - [Structured refactorings](https://harnlang.com/cookbooks/structured-refactorings.md): The std/edit module ships compound, language-aware refactorings built on top of the AST-precise edit primitives ( edit_apply_node , edit_insert_at_anchor , edit_safe_text_patch... - [Rule engine cookbook — scan, lint, and codemod](https://harnlang.com/cookbooks/rules-engine.md): The Harn rule engine matches and rewrites code structurally (by syntax tree), not by regex. A rule is a small TOML file; you run it read-only with harn scan , or as a codemod... - [Replace input?.x ?? default blocks with destructuring](https://harnlang.com/cookbooks/destructure-with-defaults.md): The single most repeated shape in Harn-using code is optional-field extraction with a fallback: - [Burin compass: choose safer edit tools](https://harnlang.com/cookbooks/burin-compass.md): Harn ships a set of AST-precise edit primitives — see the structured refactorings cookbook . They pay off when structural addressing, parse validation, or semantic-neighbor... - [Replay time-travel cookbook](https://harnlang.com/cookbooks/replay-time-travel.md): harn replay rehydrates a recorded agent session from a SQLite EventLog and replays it deterministically. With --at you can rewind to any past event and replay the... - [Run a FLUX.2 Klein image job with ComfyUI](https://harnlang.com/cookbooks/run-comfyui-model-job.md): This guide runs Harn's checked-in image example against a local or remote GPU. The result is a PNG stored by SHA-256 plus a receipt that can be replayed without ComfyUI. - [Run an OpenAI image job](https://harnlang.com/cookbooks/run-openai-image-job.md): This guide sends one image request through Harn's model-job lifecycle. The OpenAI Responses API returns the image; Harn verifies and stores it by SHA-256. - [Build an interactive Harn app](https://harnlang.com/cookbooks/build-interactive-app.md): This guide builds a stateful app without app-specific JavaScript or Rust. The complete small example is examples/apps/decision-card.harn . - [Run Harn app logic in the browser](https://harnlang.com/cookbooks/run-app-logic-in-browser.md): Use a browser reducer when pointer, keyboard, or form events should update the view without a server round trip. The same compiled Harn program also runs in the server... - [OAuth](https://harnlang.com/oauth.md): Harn ships a complete OAuth 2.x client stack as part of the standard library. One handle covers the human authorization-code dance, headless device flow, transparent refresh,... - [Playground](https://harnlang.com/playground.md): harn playground runs a pipeline against a Harn-native host module in the same process. harn try is an alias for the same command. It is intended for fast pipeline iteration... - [Debugging agent runs](https://harnlang.com/debugging.md): Harn provides several tools for inspecting, replaying, and evaluating agent runs. This page walks through the debugging workflow. - [Editor setup](https://harnlang.com/editor-setup.md): Harn ships a capable language server, harn-lsp , that powers diagnostics, completions, go-to-definition, hover, rename, formatting, and code actions. The install script puts... - [Use Harn from ACP editor hosts](https://harnlang.com/acp-editor-hosts.md): Harn can run as a native Agent Client Protocol (ACP) coding agent for editors that host external ACP agents, including Zed, JetBrains IDEs, Lumide, and other ACP clients. - [Run a portable reducer in a browser](https://harnlang.com/portable-kernel-browser.md): This guide builds the core WebAssembly adapter and runs a two-module reducer package in a dedicated browser worker. It does not depend on the interactive app stack. - [Migrate to the Portable Harn Kernel](https://harnlang.com/migrations/portable-kernel-v1.md): Portable Kernel v1 replaces the former harn-wasm source interpreter. The old adapter parsed and evaluated a subset of Harn independently; it is removed. This is an intentional... - [Migrate to the single agent plane](https://harnlang.com/migrations/agent-plane-cutover.md): This migration removes public wrappers that owned overlapping loop, chat, and editor-completion behavior. Migrate each call to the capability that owns its lifecycle. - [Migrating from 0.6.x to 0.7.0](https://harnlang.com/migrations/v0.7.md): Harn 0.7.0 replaces the implicit transcript_policy dict with first-class sessions . Session lifecycle is driven by imperative builtins, and unknown inputs hard-error instead of... - [Migrating to 0.10](https://harnlang.com/migrations/v0.10.md): Harn 0.10 removes long-deprecated resilience and composition surfaces. There are no compatibility shims. harn check and the runtime reject removed LLM option names and report... - [Migrating to the const/let keyword scheme](https://harnlang.com/migrations/const-let.md): Harn's variable-binding keywords follow the TypeScript and Swift convention. Migrate every .harn source file that predates this change. - [Migrating pure collection method names](https://harnlang.com/migrations/pure-collection-methods.md): Harn collection methods return new values and never modify their receivers. Their names now make that value semantics explicit: - [Prompt templates: v2 migration](https://harnlang.com/migrations/template-engine-v2.md): The prompt-template engine used by harness.fs.render_prompt(...) now supports else / elif , loops, includes, filters, comments, raw blocks, and whitespace trim markers.... - [Migration: package-root prompt assets](https://harnlang.com/migrations/package-root-prompt-assets.md): Harn supports two refactor-safe forms for addressing .harn.prompt assets: - [Migration — schema-as-type (type aliases drive output)](https://harnlang.com/migrations/schema-as-type.md): Prior to this change, Harn had two parallel representations for structured LLM output: - [Migrating Rust provider connectors to pure-Harn packages](https://harnlang.com/migrations/rust-connectors-to-harn-packages.md): GitHub, Slack, Linear, and Notion provider business logic now ships in pure-Harn connector packages. Harn core keeps only the shared connector primitives, so cloud platforms... - [Migration: harn-hostlib host contracts](https://harnlang.com/migrations/harn-hostlib-host-contracts.md): harn-hostlib began as a migration path for code-intelligence and tool surfaces that had lived in an external IDE host's Swift code-intelligence modules. That history explains... ### Internals - [Host boundary](https://harnlang.com/host-boundary.md): Harn is the orchestration layer. Hosts supply facts and platform effects. - [Process sandboxing](https://harnlang.com/sandboxing.md): What this page covers: which directories a script can read and write, and what a command the script spawns is allowed to do. Three related boundaries are documented elsewhere,... - [OpenTrustGraph v0](https://harnlang.com/spec/open-trust-graph/v0.md): OpenTrustGraph is the open, vendor-neutral data format Harn uses to log agent autonomy decisions as an append-only, hash-chained event stream. This page is the mdbook view of... - [LLM dialect ownership](https://harnlang.com/dev/llm-dialect-contract.md): An LLM route has one wire dialect for its entire lifetime. Harn resolves that dialect from capability data before building a request, then carries the same typed contract... - [Agent plane ownership](https://harnlang.com/dev/agent-loops.md): Harn has one public agent-loop entrypoint: agent_loop . HarnessAgent owns session mutations, checkpoints, event emission, transcript projection, and terminal classification.... - [Evidence-aware repair loop (repair-diagnostics)](https://harnlang.com/dev/repair-diagnostics.md): The agent loop's stall detector ( crates/harn-stdlib/src/stdlib/agent/stall.harn ) historically tracked a blind counter of repeated identical actions. That counter cannot tell... - [Protocol contribution RFCs](https://harnlang.com/protocol-contributions/README.md): This directory collects RFC-shaped documents that Burin Labs intends to contribute to upstream agent-protocol working groups. Each RFC describes a primitive that Harn already... - [Protocol filing status ledger](https://harnlang.com/protocol-contributions/status-ledger.md): Last verified: 2026-08-22 UTC. - [ACP RFC: session/inject_reminder + SessionUpdate::ReminderEmitted](https://harnlang.com/protocol-contributions/acp-session-inject-reminder.md): ACP has two well-defined input channels for a session: - [ACP RFC: session/suspend + session/await_resumption](https://harnlang.com/protocol-contributions/acp-session-suspend.md): ACP today has three session lifecycle verbs: - [Typed host-event injection](https://harnlang.com/protocol-contributions/acp-session-inject-host-event.md): Harn advertises session/inject_host_event under agentCapabilities.session.injectHostEvent . The request carries a session ID and the same typed event contract used by the... - [A2A RFC: ambient reminder injection for peer agents](https://harnlang.com/protocol-contributions/a2a-message-kind-reminder.md): Revised 2026-07-03 to A2A v1.0 conventions: a2a.proto is the normative source of truth, the proposed operation is PascalCase ( InjectTaskReminder ), the streamed reminder... - [A2A RFC: explicit TASK_STATE_PAUSED task state + PauseTask / ResumeTask](https://harnlang.com/protocol-contributions/a2a-paused-state.md): Revised 2026-07-03 to A2A v1.0 conventions: a2a.proto is the normative source of truth, operations are PascalCase ( PauseTask , ResumeTask , AwaitTaskResumption ), enum values... - [A2A RFC: actor-chain extension for delegated authority](https://harnlang.com/protocol-contributions/a2a-actor-chain-extension.md): Written against A2A v1.0 conventions: a2a.proto is normative, operations are PascalCase, and enum values are SCREAMING_SNAKE_CASE ProtoJSON strings. - [MCP RFC: notifications/reminder server→host ambient context](https://harnlang.com/protocol-contributions/mcp-notifications-reminder.md): MCP servers expose tools, resources, and prompts to a host. The existing server→host notification surface covers: - [MCP RFC: authenticatedIdentity on InitializeResult](https://harnlang.com/protocol-contributions/mcp-authenticated-identity.md): Verified non-duplicate on 2026-07-03: SEP-1299 is unrelated (server-side OAuth flow management, closed 2025-09-02) and discussion #1827 ( upstream_identity ) runs the opposite... - [MCP RFC: per-call budget caps for sampling/createMessage](https://harnlang.com/protocol-contributions/mcp-sampling-budget-caps.md): Sampling is deprecated. SEP-2577 ("Deprecate Roots, Sampling, and Logging") merged 2026-05-15, deprecating the feature as of protocol version 2026-07-28 , with earliest removal... - [Positioning note: actor chains in MCP enterprise auth (ID-JAG)](https://harnlang.com/protocol-contributions/oauth-actor-chain-positioning.md): Unlike the other documents here there is no new proposal to file. The substance already lives in active upstream drafts, so the useful contribution is implementer feedback in... - [ADR 0001: pipe operator with explicit placeholder](https://harnlang.com/adr/0001-pipe-operator.md): Accepted. - [ADR 0002: compile-time capability invariants](https://harnlang.com/adr/0002-compile-time-capability-invariants.md): Accepted. Narrow version shipped in #378 (closes #279 ). - [ADR 0003: use the official Rust MCP SDK](https://harnlang.com/adr/0003-mcp-hand-rolled-vs-rmcp.md): Superseded on 2026-08-02. Harn now uses rmcp 3.1 for MCP client lifecycle, stdio transport, framing, request association, standard metadata, version negotiation, and typed... - [ADR 0004: VM multithreading via Send values + share-nothing isolates](https://harnlang.com/adr/0004-vm-multithreading.md): Proposed. Records the strategy for the multithreading epic #2688 and its phase children ( #2689 , #2690 , #2691 , #2692 ). Phase 0 (the ambient-state removal that unblocks... - [ADR 0005: keep Harn's A2A adapter; do not adopt a2a-lf](https://harnlang.com/adr/0005-a2a-keep-bespoke-adapter.md): Accepted on 2026-08-06 for #6089 . Harn keeps the bespoke A2A server and client under crates/harn-serve/src/adapters/a2a/ and crates/harn-vm/src/a2a/ . The pinned schema at... - [ADR 0006: keep hand-rolled ACP until the official SDK clears the Zed falsifier](https://harnlang.com/adr/0006-acp-hand-rolled-vs-sdk.md): Accepted on 2026-08-05 for #6088 . Decision: keep the hand-rolled ACP implementation; do not adopt agent-client-protocol as a runtime dependency yet. - [ADR 0007: compile hypotheses into Harn's experiment-registration owner](https://harnlang.com/adr/0007-hypothesis-compiler-ownership.md): Accepted on 2026-08-08 for #6353 . - [ADR 0008: Harn owns prepared-run authority](https://harnlang.com/adr/0008-harn-owns-prepared-run-authority.md): Accepted on 2026-08-14 for #6662 , and extended by #6666 , #6667 , and #6860 . ### Deploy - [Platform compatibility](https://harnlang.com/dev/platform-compatibility.md): This page is the per-capability compatibility table for the Harn runtime. It is the authoritative source on what Harn supports, what it restricts, and what it deliberately... - [Bootstrap an exact Harn release](https://harnlang.com/dev/bootstrap-harn.md): scripts/bootstrap_harn.mjs is Harn's supported host-native bootstrap interface for local development and CI systems outside GitHub Actions. It uses only Node.js built-ins, runs... - [Deploy to Render](https://harnlang.com/deploy/render.md): Harn ships a Render Blueprint at deploy/render/render.yaml and the harn orchestrator deploy helper can generate a project-local variant for your manifest. - [Deploy to Fly.io](https://harnlang.com/deploy/fly.md): Harn ships a Fly template at deploy/fly/fly.toml and the deploy helper can generate a project-local app config: - [Deploy to Railway](https://harnlang.com/deploy/railway.md): Harn ships a Railway config at deploy/railway/railway.json . The deploy helper can generate it and run the Railway CLI: ### Contributing - [Maintainer release workflow](https://harnlang.com/maintainer-release.md): This page is for Harn maintainers cutting a release. User-facing CLI behavior lives in CLI reference . - [release-assets.json manifest](https://harnlang.com/dev/release-assets-manifest.md): Every published GitHub release uploads a release-assets.json file alongside the per-target archives. It is the consumer contract for downstream packagers — fetch-harn.sh... - [Release runner policy](https://harnlang.com/dev/release-runner-policy.md): Release binary runner labels are data, not workflow control flow. The source of truth is .github/release-runner-policy.json ; scripts/release_runner_matrix.sh validates that... - [Release binary-size policy](https://harnlang.com/dev/release-binary-size-policy.md): .github/release-binary-size-policy.json is the source of truth for release binary-size admission. It answers two different questions with two different numbers. - [Reusable "bump Harn runtime" workflow](https://harnlang.com/dev/reusable-bump-harn-runtime.md): Every Harn package repo pins the Harn runtime it builds against in a .harn-version file. Keeping that pin current used to mean copying a large bump-harn.yml state machine into... - [Merge overrides](https://harnlang.com/dev/merge-overrides.md): How to land a pull request when the merge queue or required CI status check is the wrong tool for a rare, time-sensitive change. - [Agent shell guard](https://harnlang.com/dev/agent-shell-guard.md): Harn gives Codex and Claude the same repository command rules. The guard keeps Rust builds and tests on the Make targets that configure a private build directory for each... - [Deterministic test patterns](https://harnlang.com/dev/testing.md): This page documents how to write fast, deterministic tests in the Harn workspace. It explains the approved patterns, the patterns that are banned by make lint-test-patterns ,... - [Windows test coverage](https://harnlang.com/dev/windows-test-coverage.md): This page tracks the disposition of every workspace test module that opts out of Windows via #![cfg(unix)] (or per-test #[cfg(unix)] ). It exists so that a new contributor can... - [Testbench mode](https://harnlang.com/dev/testbench.md): Testbench mode is the composition primitive that wires Harn's deterministic substrate — virtual time, mocked LLMs, filesystem overlay, recorded subprocesses, and a... - [Single-threaded DES runtime mode](https://harnlang.com/dev/des-mode.md): harn test-bench run --runtime des swaps the testbench's default multi-threaded Tokio runtime for a single-threaded current_thread runtime. All Harn tasks, I/O completions, and... - [Event tape format](https://harnlang.com/dev/tape-format.md): The event tape is the canonical artifact behind harn test-bench --emit-tape . Every non-deterministic input a script consumed during a run — clock reads, sleeps, LLM responses,... - [Annotation tape format](https://harnlang.com/dev/annotation-tape-format.md): An annotation file ( .annotations.jsonl ) is the durable form of human judgment over a recorded testbench run. It pairs with a unified event tape and lets humans (or... - [Update Harn's MCP integration](https://harnlang.com/dev/mcp-maintenance.md): This guide is for maintainers changing Harn's MCP client, either MCP server, or the generated protocol contract. It covers the update workflow. For the public API, see MCP,... - [Update Harn's ACP integration](https://harnlang.com/dev/acp-maintenance.md): This guide is for maintainers changing Harn's ACP server, ACP LLM provider, or Harn-owned ACP extensions. For the public API, see MCP, ACP, and A2A integration . For the... - [Thread-Local Work-Stealing Audit](https://harnlang.com/dev/thread-local-work-stealing-audit.md): Harn still has VM runtime state stored in thread_local! slots. That was acceptable while VM work was pinned to one LocalSet , but pool workers now cross the first work-stealing... - [VM and stdlib hot-path profile](https://harnlang.com/dev/vm-stdlib-perf-notes.md): This page captures the allocation profile behind issue #1426 and the follow-on runtime/typechecker performance wave tracked by issue #2095. The first sections are historical... - [Bytecode cache](https://harnlang.com/perf/bytecode-cache.md): Short-lived harn invocations spend the bulk of their wall time before the VM executes a single instruction: read the source, lex it, parse it, run the type checker, compile the... ## Optional - [Full documentation](https://harnlang.com/llms-full.txt): every page concatenated - [Language quick reference](https://harnlang.com/docs/llm/harn-quickref.md) - [Triggers quick reference](https://harnlang.com/docs/llm/harn-triggers-quickref.md)