Pre-release Harn is pre-1.0 — the language, standard library, and CLI may change between releases. See the release notes

Learned workflows

std/agent/learned selects reviewed tools under execution qualification and composes them into an existing agent loop. See why qualification is required.

Dispatcher#

learned_dispatcher(options: LearnedDispatcherOptions) -> LearnedDispatcher returns a decision definition, its execution identity, binding options, and two selection functions:

FunctionContract
assess(llm, request, qualification)Requires matching qualification before inference, then applies the certified threshold.
probe(llm, request)Selects without qualification for an explicitly isolated experiment.

Options require id, instructions, capabilities, policy, evaluator_revision, binding, runtime_digest, grader_digest, and population. A LearnedCapability supplies id, meaning, the canonical ToolCatalogEntry, package_digest, project_digest, verification_digest, and minimum_probability. Empty required identities throw.

An optional preflight_tool checks bound arguments and current project state before the mutating tool is selected. It must have a distinct name, the same input schema, annotations.readOnlyHint: true, and policy.side_effect_level: "read_only" with declared policy provenance. Author this with execution_policy: {kind: "read", side_effect_level: "read_only"}. Harn enforces the declared effect ceiling for local and served MCP handlers. A presentation hint alone supplies no execution policy. Legacy annotations.kind and annotations.side_effect_level remain scheduling classifications and cannot qualify a preflight. The preflight returns canonical tool-result data matching LearnedPreflight: {kind: "ready"} or {kind: "declined", reason: string}. Missing or invalid results cause fallback. The mutating handler must recheck mutable preconditions before writing.

The returned assessment is selected, unqualified, or a non-match from std/decision. An empty capability list requires no inference.

After binding arguments, middleware asks the native evaluator whether the parameter values preserve the request's names, values, and roles. This check uses the dispatcher's evaluation policy. A mismatch, uncertainty, or evaluation failure causes fallback before preflight or mutation. Normal execution requires both the configured acceptance probability and the admitted qualification threshold.

learned_binding_request(fs, request, capability, arguments, policy) returns the typed LearnedBindingRequest shared by dispatch, fixtures, and evaluation. It contains the question, serialized schema and arguments, request, and policy.

Qualification#

learned_qualify(identity, trials, {risk}) -> LearnedQualification delegates threshold certification to std/eval/selective_risk. Each LearnedTrial has:

FieldMeaning
idUnique nonempty trial identifier.
expectedExpected capability identifier; empty for an incompatible request.
selectedCommitted capability identifier; empty when abstaining.
confidenceMinimum of applicability, route, and binding-check probabilities.
abstainedWhether dispatch explicitly declined commitment.
executionnot_run, or passed/failed with a unique receipt and workspace digest.

learned_trial(observation: LearnedObservation) -> LearnedTrial constructs a trial from the assessment, explicit runtime disposition, expected label, and independent execution evidence. Disposition is abstained with a nonempty reason, or committed with the assessed capability and decision receipt. Committed observations also require the answered binding evaluation and its distinct binding_receipt. Its accepted answer must match the receipt named by the runtime disposition. An applicability receipt cannot substitute for it. The middleware emits one disposition checkpoint. Missing records are unmeasured; absence of a mutation is insufficient to establish abstention.

Committed calls without passing execution evidence count as errors. Abstained trials mustn't execute. Duplicate identifiers, reused receipts, and empty execution identities throw.

Declare whether a study measures assessment alone or the combined dispatch path before collecting evidence. Report assessment mistakes and coverage alongside execution risk. Changing that protocol requires a new study; constructing observations cannot repair an earlier failed report.

learned_qualification_issue(identity, qualification) -> string returns an empty string when qualification is usable. Otherwise it returns missing_qualification, stale_qualification, insufficient_execution_evidence, risk_not_certified, or inconsistent_qualification.

learned_qualification_threshold(identity, qualification) -> Result<float, string> returns the admitted threshold or the same refusal reason. Selection and binding use this shared qualification owner.

Agent composition#

learned_agent_options(harness, setup) -> LearnedAgentOptions returns llm_caller and tool_caller middleware for the ordinary agent loop. Setup requires request, dispatcher, qualification, the original caller, and refresh_identity; tool_caller is optional. Measurement failures cause fallback to the original caller.

learned_probe_agent_options(harness, setup, trial) uses the same execution path without qualification. The trial requires a nonempty id, the current workspace_root, and a different source_project_root. The caller owns workspace isolation and independent grading. Trial execution is recorded as qualification_trial, never as qualified execution.

learned_agent_options_deferred(harness, fallback, resolve, trial = nil) resolves setup once against the live tool registry after MCP bootstrap. The resolver returns ready with setup or unavailable with a reason. This avoids copying tool schemas or guessing MCP dispatch names before connection.

Source measurements#

learned_dispatch_declaration validates an executable's declared dispatch meaning. learned_capability_snapshot binds its declaration and canonical tool to package, project, and verifier file sets. Hosts own the file coordinates; Harn owns validation and digest construction.