Agent Work Receipt v0.1

Agent Work Receipt is an account-free interchange contract for recording what an agent was asked to do, what authority it had, what it did, what changed, how the result was checked, and what it cost.

The contract does not require an OrgX account, workspace id, UUID, database row, or proprietary runtime. Every cross-system identifier is an opaque { system, type, id } reference owned by its producer. Git commits, GitHub pull requests, MCP calls, A2A tasks, deployments, and OpenTelemetry traces can all be represented without translation into an OrgX identifier.

Contract

• Schema version: agent-work-receipt/v0.1
• JSON Schema: schema/agent-work-receipt.v0.1.schema.json
• Dialect: JSON Schema Draft 2020-12
• License: Apache-2.0

The required top-level records are:

• intent
• actor
• authority
• actions
• artifacts
• evidence
• outcome
• verification
• cost
• lineage
• human_interventions
• timestamps

Hashes and signatures are optional under integrity. Artifact and evidence digests describe the referenced bytes. When a producer emits integrity.content_hash, it should hash RFC 8785 canonical JSON for the receipt with the entire integrity property omitted. A signature should sign that digest. Cryptographic digest and signature verification is intentionally a consumer policy; the v0.1 validator checks their portable shape, not key trust.

Numeric values follow the interoperable JSON/IEEE-754 boundary: they must be finite and between -9007199254740991 and 9007199254740991; integer fields must be safe integers. RFC 8785 hashing therefore has the same number semantics in JavaScript, JSONB, and conforming consumers. Arbitrary-precision values belong in a namespaced string extension with an explicit unit or encoding.

TypeScript

Published to npm under the Apache-2.0 licence. No OrgX account is required to use it — the schema, types, and validator are self-contained and the package makes no network calls.

npm install @useorgx/agent-work-receipt

import {
  parseAgentWorkReceipt,
  validateAgentWorkReceipt,
  type AgentWorkReceipt,
} from '@useorgx/agent-work-receipt';

const result = validateAgentWorkReceipt(input);
if (!result.ok) {
  console.error(result.issues);
}

const receipt: AgentWorkReceipt = parseAgentWorkReceipt(input);

Validation failures use RFC 6901 JSON Pointer paths and are sorted by path, code, then message. This makes errors stable for CLIs, APIs, tests, and import pipelines. parseAgentWorkReceipt throws AgentWorkReceiptValidationError with the same structured issues. validateAgentWorkReceipt returns at most 100 issues; failure results include issue_count and issues_truncated so callers can report the observed finding count without returning an amplified payload. Schema validation fails fast at the first structural violation; schema-valid receipts can receive multiple bounded semantic findings.

The standard JSON Schema date-time and uri-reference formats are validated with AJV Formats in full mode. Timestamps therefore follow RFC 3339 (including the permitted lowercase t and z forms), while URI references reject malformed percent escapes, IP literals, and whitespace.

Before JSON Schema evaluation, the SDK applies bounded traversal guards: at most 64 levels and 50,000 visited JSON nodes. These limits prevent adversarial recursive extensions values from exhausting a validator. A document can therefore satisfy the standalone JSON Schema yet still fail SDK/API admission with input.structure_limit; public validator metadata exposes both limits.

The validator enforces the JSON Schema plus cross-record invariants:

• unique action, artifact, evidence, intervention, and verification-check ids;
• evidence references resolve to the receipt's evidence records;
• receipt, action, and authority timestamps are ordered;
• terminal actions include completion timestamps; and
• verification summaries agree with their checks.

Fixtures

The fixtures directory contains valid, account-free receipts emitted in the style of Codex, Claude Code, and OpenClaw. The OpenClaw fixture demonstrates MCP, A2A, and OpenTelemetry references in a single lineage record.

Two reusable negative fixtures demonstrate distinct failure boundaries:

• missing authority is structurally invalid because every receipt must declare its authority boundary;
• unresolved evidence is schema-valid but semantically invalid because its verification references an evidence id that does not exist in the receipt.

Hosted OrgX import (optional)

Portable receipts can remain entirely outside OrgX. Producers that want a hosted ledger can POST https://useorgx.com/api/v1/agent-work-receipts with a bearer token or authenticated session and this JSON body:

{
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "receipt": {},
  "idempotency_key": "producer-owned-retry-key"
}

workspace_id and receipt are required; idempotency_key is optional. A new import returns 201, and a safe retry of the same content returns 200. When no key is supplied, OrgX derives one from the canonical SHA-256 hash of the full receipt. An explicit key is workspace-scoped, and reuse for different content returns 409. Imported producer claims remain unverified until OrgX records hosted verification or human review. See the public OpenAPI contract for complete request, response, and authentication details.

Versioning

v0.1 is an interoperability preview. Producers must emit the exact schema_version they implement. Breaking field or meaning changes require a new schema version; additions that older strict validators cannot accept also require a new version. Runtime-specific data belongs in namespaced extensions and must not be required to interpret the core receipt.