harn

Harn

Harn is a programming language and runtime for orchestrating AI agents. It sits between product code and provider/runtime code: products declare workflows, policies, capabilities, and UI hooks, while Harn owns transcripts, context assembly, retries, tool routing, persistence, replay, and provider normalization.

Harn also emits portable opentrustgraph/v0.1 trust records for autonomy decisions, approval gates, and tier transitions. v0.1 adds three reserved metadata keys (effects_grant, effects_used, parent_record_id) so chain validators can prove that a child agent's effects_used stayed inside the parent's effects_grant. The public schema and fixtures live in opentrustgraph-spec/.

Core capabilities

- Typed workflow graphs via workflow_graph(...) and workflow_execute(...) with explicit nodes, edges, validation, policy attachment, map/join style stages, and resumable execution. - Planner-oriented action graphs via import "std/agents": action_graph(...), action_graph_batches(...), action_graph_flow(...), and action_graph_run(...) normalize planner schema variants into a shared executable schedule instead of leaving dependency repair and batch grouping to leaf pipelines. - Persona orchestration primitives via import "std/personas/prelude": verifier-then-actor gates, bounded loops, cheap-classifier escalation, circuit-broken parallel sweeps, audit receipt wrappers, and approval gates give durable personas reusable control flow without host-specific glue. - Transparent profile bulletin proposals via import "std/personas/bulletins": bulletin_propose builds typed harn.profile_bulletin.v1 envelopes with stable id, scope, evidence, source, privacy, and TTL fields; bulletin_emit always writes proposals to personas.bulletins.proposed, and bulletin_accept / bulletin_reject / bulletin_expire / bulletin_supersede emit harn.profile_bulletin_decision.v1 audit records so hosts (Burin local, Harn Cloud) can review persona context instead of accepting silent prompt mutation. - Delegated worker lifecycle builtins via spawn_agent(...), send_input(...), resume_agent(...), wait_agent(...), close_agent(...), and list_agents(), with child run lineage, persisted worker snapshots, and host-visible worker lifecycle events. Worker handles retain immutable original request metadata plus normalized provenance so parent orchestration can recover research questions, action items, workflow stages, and verification steps without positional rebinding. Agent loops also expose lifecycle tools for worker self-parking (agent_await_resumption) and opt-in parent-side subagent pause/resume control. - Per-worker execution scoping on spawn_agent(...): delegated workers inherit the current execution ceiling by default and can narrow it further with a policy dict or tools: ["name", ...] shorthand, with permission denials returned as structured tool results instead of opaque failures. - sub_agent_run(task, options?) for isolated child agent loops that preserve a clean parent transcript while returning a typed summary envelope or a background worker handle. - Explicit continuation policy for delegated workers: carry.transcript_mode (inherit, fork, reset, compact), artifact carryover, workflow resume control, and compact parent-facing worker_result artifacts. - Runtime schema helpers for structured LLM I/O: schema_check(...), schema_parse(...), schema_is(...), JSON Schema/OpenAPI conversion, and schema composition helpers, plus a lazy std/schema builder module for ergonomic schema authoring when imported. - Provider-neutral GraphQL connector helpers via import "std/graphql": request/envelope normalization, introspection and SDL fixture parsing, persisted-query metadata, cursor pagination helpers, auth headers, and generated-style operation wrapper source for GraphQL-first providers such as Linear. - Prompt fragment reuse via import "std/prompt_library": load TOML catalogs or front-matter .harn.prompt files, render cache-aware fragment payloads, and propose tenant-scoped k-means hotspots for repeated context prefixes. - Deterministic vision OCR via vision_ocr(...) and import "std/vision": image path / payload normalization, structured text output (blocks, lines, tokens), and event-log-backed OCR audit records for replayable agent/tool flows. - Manifest-backed extension ABI: packages can publish stable module entry points via [exports], declare custom tool and skill surfaces via [[package.tools]] and [[package.skills]], and ship provider/alias adapters declaratively via [llm] in harn.toml, without editing core runtime registration code. harn tool new <name> scaffolds a Harn-native tool package with manifest metadata, tests, docs, and CI, while harn package scaffold openapi turns an OpenAPI spec into a focused generated SDK package with a regeneration script and package checks. Local sibling packages can be added with harn add ../harn-openapi; Harn derives the alias from the dependency's harn.toml and live-links directory path dependencies into .harn/packages/ for fast multi-repo development. Registry-backed discovery is available through harn package search, harn package info, and harn add @burin/<name>@<version>, which resolve through the package index and then use the same git-backed install path as direct GitHub refs. Manifests can also pin direct git tags with tag = "v1.2.3" or resolve registry semver ranges with version = "^1.2". harn package list and harn package doctor expose locked exports, permissions, host requirements, and materialized-package integrity for host UI and CI policy checks. - Design-by-contract and project/runtime helpers: require ..., metadata/scanner runtime builtins, import "std/project" for freshness-aware metadata and scan state, and import "std/runtime" for generic runtime/process/interaction helpers inside Harn itself. - Isolated execution substrate via directory-scoped command builtins (exec_at, shell_at) plus the std/worktree module for git worktree creation, status, diff, shell execution, and cleanup. Worker execution profiles can pin delegated runs to a cwd, env overlay, or managed worktree so background execution is reproducible instead of ambient-cwd dependent. Subprocesses spawned under an active capability ceiling run inside a per-platform OS sandbox by default: Linux Landlock + seccomp, macOS sandbox-exec, or Windows AppContainer + Job Object, selected via CapabilityPolicy::sandbox_profile and documented in docs/src/sandboxing.md. Pipelines that spawn untrusted code opt into sandbox_profile: "os_hardened" to make the OS confinement required (the spawn fails as tool_rejected if the platform mechanism is missing) instead of best-effort. - Stronger preflight behavior via harn check: import graph resolution, literal template/render path validation, import symbol collision detection, and host capability contract validation all fail before runtime. harn check / harn run / the LSP share one recursive module graph that resolves every import (including std/* embeds) and rejects calls to names that are not builtins, local declarations, struct constructors, callable variables, or imported symbols, so stale or typo'd references surface before the VM starts. render(...) resolves relative to the module source tree (including inside imported modules) instead of the ambient process cwd. Literal delegated execution roots, exec_at(...) / shell_at(...) directories, and unknown host_call("capability.operation", ...) contracts are also checked before launch. - Runtime-local typed host mocking for tests via host_mock(...), host_mock_clear(), and host_mock_calls(), so .harn conformance and VM tests can exercise host-backed flows without requiring a live bridge host. import "std/testing" adds higher-level helpers such as mock_host_result(...), mock_host_error(...), and assert_host_called(...) for ordinary Harn tests. - Configurable LLM mock responses via llm_mock(...), llm_mock_calls(), and llm_mock_clear(): queue specific text, tool calls, or mixed responses for the mock provider. Supports FIFO queuing and glob-pattern matching against prompts. - Eval suite manifests and portable eval packs via eval_pack { ... }, eval_pack_manifest(...), eval_pack_run(...), eval_suite_manifest(...), eval_suite_run(...), persona_eval_ladder_run(...), `harn eval <manifest.json|harn.eval.toml>, and harn test package --evals`, so grouped replay, rubric, threshold, timeout-ladder, and package-shipped connector evals are first-class runtime data instead of external scripts. - Typed artifacts and resources as the real context boundary. Context selection is artifact-aware, budget-aware, and policy-driven rather than raw prompt concatenation. - Host-facing artifact helpers for workspace files, snapshots, editor selections, command/test/verification outputs, and diff/review decisions, so product code can pass structured state into Harn without rebuilding artifact taxonomy or provenance conventions. - Durable run records with persisted stage transcripts, artifacts, policy decisions, verification outcomes, delegated child lineage, and inspection/replay/eval entrypoints including recursive run-tree loading. - Provider-normalized LLM output with visible_text, private_reasoning, thinking_summary, tool_calls, blocks, provider, stop_reason, and transcript events. - Structured transcript lifecycle support: continue, fork, compact, summarize, render public-only output, or render full execution history. - Workflow meta-editing builtins such as workflow.inspect, clone/insert/ replace/rewire operations, per-node model/context/transcript policy edits, diff, validate, and commit-style validation. - Capability ceiling enforcement for workflows and sub-orchestration: internal plans may narrow capabilities but cannot exceed the host ceiling. - ACP pending user-message injects for agent execution: accept with a stable messageId, optionally replace or revoke while pending, steer after the current operation, or queue until the agent yields back to the human. - ACP pending reminder controls for operator UIs: inspect the bridge queue and revoke queued session/remind reminders before a checkpoint drains them. - Remote MCP over stdio and HTTP, including OAuth metadata discovery, stored bearer tokens for standalone CLI use, and automatic token reuse for HTTP MCP servers declared in harn.toml. - Runtime semantic cleanup for older surfaces: repeated catch e { ... } bindings work within the same enclosing block, and float division keeps IEEE NaN/Infinity behavior instead of raising runtime errors. - Formatter width handling wraps oversized comma-separated forms consistently across calls, list literals, dict literals, enum payloads, and struct-style construction instead of leaving long single-line output intact. - Tool lifecycle hooks via register_tool_hook(...): pre-execution deny/modify and post-execution result interception for agent tool calls, with glob-pattern matching on tool names. - Automatic transcript compaction in agent loops: microcompaction snips oversized tool outputs, auto-compaction triggers at configurable token thresholds, and compact_strategy supports default LLM summarization, truncate fallback, or custom Harn closure-based compaction. Host/user compaction instructions flow through the typed CompactionPolicy lane so /compact <instructions> style commands can reuse runtime audit/events without bespoke prompt wiring. The same pipeline is exposed directly as transcript_auto_compact(...). - Daemon agent mode (daemon: true): agents stay alive waiting for host-injected messages instead of terminating on text-only responses, with adaptive idle backoff, persisted snapshots, timer/file-watch wakes, and explicit bridge wake/resume signaling. - Per-agent capability policies with argument-level constraints: agent_loop accepts a policy dict to scope tool permissions, including tool_arg_constraints for pattern-matching on tool arguments. - Rule-based approval policies: approval_policy.rules expresses allow/ask/deny over tool names/kinds, side-effect levels, declared paths, command identity, URLs/domains/methods, MCP identity, agent/persona/mode, and repeat counts, with deny-by-default sensitive path guards and replayable policy-decision receipts in permission events and host approval prompts. - Dynamic per-agent permissions: agent_loop, sub_agent_run, and spawn_agent accept permissions with allow / deny tool rules, VM predicates over the tool args, and on_escalation callbacks that can grant a denied call once or for the session. Permission decisions emit PermissionGrant, PermissionDeny, and PermissionEscalation transcript events. - Generic call-site type checking is stricter: where-clause interface violations are errors, repeated generic parameters must bind to one concrete type, and container bindings like list<T> propagate their element type. - Workflow map stages can execute in parallel with "all", "first", or "quorum" join strategies plus max_concurrent throttling. - LSP completions surface inferred shape fields, struct members, and enum payload fields on dot access instead of defaulting to dict methods. - Adaptive context assembly with deduplication and microcompaction via select_artifacts_adaptive(...), plus estimate_tokens(...) and microcompact(...) utility builtins. - Model-aware token counting via tiktoken_count_tokens(...) and std/llm/budget, with exact tiktoken counts for known OpenAI models and labeled approximations for Claude/Gemini model families. - Host-aware static preflight: harn check can load host-specific capability schemas and alternate bundle roots from harn.toml or CLI flags so host adapters and bundled template layouts validate cleanly. - Mutation-session audit metadata for workflows, delegated workers, and bridge tool gates so hosts can group write-capable operations under one trust boundary without forcing one edit-application UX. - String method aliases for case normalization: .lower(), .upper(), .to_lower(), and .to_upper().