API Reference
Types and errors
Shared JSON contracts, observations, manifests, diagnostics, and machine-readable Harness errors.
Shared JSON contracts
Access: @nylorun/harness → 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 used throughout Harness records and contracts. |
JsonObject | String-keyed JSON values | JSON object used for configuration, context, metadata, and tokens. |
DeferredOutcome | kind: "deferred", optional token | Defers a model or tool operation for host-managed continuation. |
ContextItem | optional type, value: JsonValue | One runtime-context entry. |
Tripwire | code, message, optional scope | Stops the current step or complete session. |
Diagnostics and manifests
Access: @nylorun/harness → BuildDiagnostic, AgentManifest
| Type | Name | Required | Description |
|---|---|---|---|
BuildDiagnostic | code | Yes | Programmatic invalid-build code. |
BuildDiagnostic | message | Yes | Human-readable diagnostic. |
BuildDiagnostic | toolName, details, cause | No | Related tool, scalar detail map, and original failure. |
AgentManifest | id, name, middleware | Yes | Public built-agent identity and middleware ids. |
Observability contracts
Access: @nylorun/harness → Observer, ObserveEvent, ObserveModelRequested,
ObserveModelConfigurationSnapshot, ObserveToolSnapshot, ObserveSealedCall
| Type | Parameters or fields | Description |
|---|---|---|
Observer | event: ObserveEvent | Synchronous or async listener for lifecycle observations. |
ObserveModelRequested | call, configuration, context | JSON-safe logical model call and attributed model/context snapshots. |
ObserveModelConfigurationSnapshot | Configuration snapshot with observation-safe tools | Configuration view suitable for telemetry. |
ObserveToolSnapshot | name, description, owner, JSON Schema | Tool view suitable for telemetry. |
ObserveSealedCall | call id, name, args, invocation, owner, optional interaction | Validated tool-call view suitable for telemetry. |
ObserveEvent family | Description |
|---|---|
| Session and capability | Session stopped/seeded/continued and failed capability-state disposal. |
| Input and recording | Received, queued, rejected, cancelled input and recorder failures. |
| Model and middleware | Requested, completed, deferred model calls; middleware entry/completion and lease violations. |
| Tool and interaction | Sealed, started, completed, deferred tool calls; interaction requirements. |
| Turn and policy | Final turn output and step/session tripwires. |
HarnessError
Access: @nylorun/harness → HarnessError, HarnessErrorCode, HarnessErrorDetails,
HarnessErrorOptions, isHarnessError
| Name | Type | Required | Description |
|---|---|---|---|
code | HarnessErrorCode | Yes | Stable machine-readable error code. |
message | string | Yes | Human-readable explanation inherited from Error. |
details | HarnessErrorDetails | Yes | Frozen scalar details map. |
constructor cause | unknown | No | Original error retained as the error cause. |
constructor details | HarnessErrorDetails | No | Additional diagnostic facts. |
isHarnessError(error) | unknown | Yes | Narrows an unknown error to HarnessError. |
Use code rather than matching an error message.
| Error family | Codes |
|---|---|
| Agent and capability | agent.build-failed, agent.lifecycle-sealed, capability.state.create-failed, capability.state.undeclared |
| 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 |
| JSON | json.invalid-data, json.invalid-object |
| Middleware | middleware.next-after-return, middleware.next-called-twice, middleware.request-mutators-revoked |
| Model | model.candidate-missing, model.adapter-invalid-options, model.adapter-invalid-response, model.invalid-candidate, model.invalid-directive |
| Response | response.invalid-replacement |
| Session | session.invalid-seed, session.record-failed, session.stale-result |
| Tool | tool.invalid, tool.invalid-arguments, tool.invalid-name, tool.invalid-schema, tool.invalid-tool-result |