Errors and contracts

@nylorun/agents/define · beta

import { isHarnessError } from "@nylorun/agents/define";
import { run, bindingFromAgent } from "@nylorun/harness/run";

try {
  await run({
    binding: bindingFromAgent(agent.build()),
    input: "Run the task",
    onModelCall: adapter,
  });
} catch (error) {
  if (isHarnessError(error)) console.error(error.code, error.details);
}

HarnessError and JSON contracts are exported from @nylorun/agents/define. They are not @nylorun/harness root exports. Recording failures reject run(). They do not emit a session-only observation path. SDK HTTP failures use RuntimeError from @nylorun/agents.

Shared JSON contracts

Access: @nylorun/agents/define → JsonPrimitive, JsonValue, JsonObject, DeferredOutcome, ContextItem, Tripwire

Type	Shape or fields	Description
`JsonPrimitive`	`string`, `number`, `boolean`, or `null`	JSON scalar.
`JsonValue`	Primitive, object, or readonly JSON-value array	JSON-only boundary.
`JsonObject`	String-keyed JSON values	Configuration, context, metadata.
`DeferredOutcome`	`kind: "deferred"`, optional `token`	Defers a tool operation for host-managed settlement.
`Patch`	`instructions?`, `capabilities?`, `tools?`, `state?`, `block?`, `active?`	Closed-world before-hook result. No `model`.
`Decision`	`text?`, `deny?`, `approve?`, `retry?`, `block?`	After-step result.
`TurnDecision`	`text?`, `output?`, `retry?`, `block?`	After-turn result.

Diagnostics and manifests

Access: @nylorun/agents → AgentManifest

Access: @nylorun/agents/define → BuildDiagnostic, CapabilityManifest

Type	Name	Required	Description
`BuildDiagnostic`	`code`	Yes	Programmatic invalid-build code.
`BuildDiagnostic`	`message`	Yes	Human-readable diagnostic.
`AgentManifest`	`manifestSchemaVersion`	Yes	Published value is `4`.
`AgentManifest`	`id`	Yes	Public built-agent identity.
`AgentManifest`	`name`, `description`, `outputSchema`	No	Catalog and output contract.
`CapabilityManifest`	`id`, `type`	Yes	`type` is `"agent"` or `"agent-plugin"`.
`CapabilityManifest`	`hooks`	No	`{ at, scope }[]` (`before`/`after` × `turn`/`step`).

Two different version numbers exist: manifest 4 versus core DEFINITION_SCHEMA_VERSION 2 (definition-hash metadata). Do not document the latter as the public manifest field.

Observability contracts

Access: @nylorun/agents/define → Observer, ObserveEvent

run({ onEvent }) wraps those observations in ExecutionEvent (@nylorun/harness). They are not Runtime SSE types. See Events.

`HarnessError`

Access: @nylorun/agents/define → HarnessError, HarnessErrorCode, isHarnessError

Name	Type	Required	Description
`code`	`HarnessErrorCode`	Yes	Stable machine-readable error code.
`message`	`string`	Yes	Human-readable explanation.
`details`	`HarnessErrorDetails`	Yes	Frozen scalar details map.
`isHarnessError(error)`	`unknown`	Yes	Narrows an unknown error to `HarnessError`.

Use code rather than matching an error message.

Error family	Codes
Agent	`agent.build-failed`, `agent.lifecycle-sealed`
Execution	`execution.invalid-state`, `execution.invalid-input`, `execution.incompatible`, `execution.record-failed`
Context	`context.invalid-item`, `context.invalid-item-type`, `context.invalid-order`, `context.invalid-reason`, `context.invalid-slot`
Configuration	`configuration.duplicate-tool-name`, `configuration.invalid`, `configuration.invalid-instructions`, `configuration.invalid-order`, `configuration.invalid-reason`, `configuration.invalid-slot`, `configuration.invalid-tools`, `configuration.model-selection-conflict`
Interaction	`interaction.invalid`, `interaction.missing-resume`, `interaction.uncorrelated-resume`
Input and output	`input.invalid-content`, `output.invalid`, `output.invalid-schema`
JSON	`json.invalid-data`, `json.invalid-object`
Model	`model.candidate-missing`, `model.adapter-invalid-options`, `model.adapter-invalid-response`, `model.invalid-candidate`, `model.invalid-directive`, `model.unsupported-content`, `model.unsupported-output-schema`
Response	`response.invalid-replacement`
Tool	`tool.invalid`, `tool.invalid-arguments`, `tool.invalid-output`, `tool.invalid-name`, `tool.invalid-schema`, `tool.invalid-tool-result`, `tool.unregistered`, `tool.invalid-binding`
Sandbox	`sandbox.runtime-only` (stub execute), `sandbox.unsupported`, `sandbox.unknown-option` (`SandboxError`)

Connected execution also uses tool.invalid-input on failed argument validation. That code is an executor outcome, not this HarnessError table.

A delegated agent's ctx.ask, ctx.approve, ctx.sleep, or ctx.waitFor fails as a tool result with delegation.interaction-unsupported. Nested delegation fails the parent build with a named diagnostic. See Subagents.