{"_id":"@agent-arc-status/reference","_rev":"3-e88db6ff745a9d76636b706b85789936","name":"@agent-arc-status/reference","dist-tags":{"latest":"0.3.2"},"versions":{"0.3.0":{"name":"@agent-arc-status/reference","version":"0.3.0","keywords":["agent","agents","ai","llm","observability","progress","webhook","arc-status"],"author":{"name":"Joe Fisher"},"license":"MIT","_id":"@agent-arc-status/reference@0.3.0","maintainers":[{"name":"joethefisher","email":"joefisherpersonal@gmail.com"}],"homepage":"https://github.com/joethefisher/agent-arc-status#readme","bugs":{"url":"https://github.com/joethefisher/agent-arc-status/issues"},"dist":{"shasum":"7c550ee73e8cac3a445794422a4b2252666f2ec4","tarball":"https://registry.npmjs.org/@agent-arc-status/reference/-/reference-0.3.0.tgz","fileCount":35,"integrity":"sha512-VbyGmazjhrQDdu3K0CUG0lYNyZf/9rB5ClFfrMBoySkoZmkZhVQt0thSack/MTV4y5msh5fZTjW9mSHYSKuA9Q==","signatures":[{"sig":"MEQCIExd/1DJR9V0QM7jCn3okvXAyMv9WlnZvnFBxM5iW1INAiAsjT3g/gwJuDq6u1edUoQpE6EUExFXBBoVW3ec6R/l9g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agent-arc-status%2freference@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":84006},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"421bf5c6179c005c98824c92cf49b065b1445e59","scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"joethefisher","email":"joefisherpersonal@gmail.com"},"repository":{"url":"git+https://github.com/joethefisher/agent-arc-status.git","type":"git","directory":"packages/reference"},"_npmVersion":"10.9.8","description":"Reference implementation of the Agent Arc Status Protocol: types, parser, validator, renderer, cadence, state, and delegation-tree tooling. Zero runtime dependencies.","directories":{},"_nodeVersion":"22.23.1","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/reference_0.3.0_1783738317108_0.1672393387191078","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@agent-arc-status/reference","version":"0.3.1","keywords":["agent","agents","ai","llm","observability","progress","webhook","arc-status"],"author":{"name":"Joe Fisher"},"license":"MIT","_id":"@agent-arc-status/reference@0.3.1","maintainers":[{"name":"joethefisher","email":"joefisherpersonal@gmail.com"}],"homepage":"https://github.com/joethefisher/agent-arc-status#readme","bugs":{"url":"https://github.com/joethefisher/agent-arc-status/issues"},"dist":{"shasum":"f3a9e4d382ac201183897d2137d1182951c1b126","tarball":"https://registry.npmjs.org/@agent-arc-status/reference/-/reference-0.3.1.tgz","fileCount":35,"integrity":"sha512-FBSX8AR+oeaCALrms33jZ8fDwIxRkN9/P67zmz963ED72IJlkI0pC9KDzDasXxbHuvTnpSvSkJPSsGZ6xaXM3A==","signatures":[{"sig":"MEUCIE3gGEVAiGiJYXZG+lwZK0OrIuMbP+Mhe+fDpPANM69zAiEAua1aFU3vNKlLdMYVatxNAWkLnT+5RpZdhlXa4/1ObFY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agent-arc-status%2freference@0.3.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":84006},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"cff6c28c805bba4f15e9bea0ce43dcdc515ecf66","scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2035850e-53e3-4b38-bb6d-3f23c05d4336"}},"repository":{"url":"git+https://github.com/joethefisher/agent-arc-status.git","type":"git","directory":"packages/reference"},"_npmVersion":"12.0.1","description":"Reference implementation of the Agent Arc Status Protocol: types, parser, validator, renderer, cadence, state, and delegation-tree tooling. Zero runtime dependencies.","directories":{},"_nodeVersion":"22.23.1","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/reference_0.3.1_1783740627938_0.5738299527967266","host":"s3://npm-registry-packages-npm-production"}},"0.3.2":{"name":"@agent-arc-status/reference","version":"0.3.2","description":"Reference implementation of the Agent Arc Status Protocol: types, parser, validator, renderer, cadence, state, and delegation-tree tooling. Zero runtime dependencies.","license":"MIT","author":{"name":"Joe Fisher"},"repository":{"type":"git","url":"git+https://github.com/joethefisher/agent-arc-status.git","directory":"packages/reference"},"homepage":"https://github.com/joethefisher/agent-arc-status#readme","bugs":{"url":"https://github.com/joethefisher/agent-arc-status/issues"},"keywords":["agent","agents","ai","llm","observability","progress","webhook","arc-status"],"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"publishConfig":{"access":"public","provenance":true},"scripts":{"build":"tsc","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit"},"engines":{"node":">=20"},"gitHead":"541a2a2c6ea3a031354c5ecc744bce9a6fe5d75b","_id":"@agent-arc-status/reference@0.3.2","_nodeVersion":"22.23.1","_npmVersion":"12.0.1","dist":{"integrity":"sha512-UpBnNZUUJ+HuO3XB1owO2YnXAF6LQOy188/5rWVkFgtlCFgZaW3NThnEou9wj3oey1sz1J9aZ8cneM360vEIrw==","shasum":"e9f1479228c39155b7b4c57fe8ecdd1e35449fb1","tarball":"https://registry.npmjs.org/@agent-arc-status/reference/-/reference-0.3.2.tgz","fileCount":35,"unpackedSize":84006,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agent-arc-status%2freference@0.3.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBbfkR6RNlJNDJL4v/yBLdITUtvoq9jvxzkSShPcZytoAiBjRrCO9wXJGhnYgm28+x9RJIkqPBTuWVjVBJCuUBhdIg=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2035850e-53e3-4b38-bb6d-3f23c05d4336"}},"directories":{},"maintainers":[{"name":"joethefisher","email":"joefisherpersonal@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/reference_0.3.2_1783741377221_0.8644713504378385"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-11T02:51:56.922Z","modified":"2026-07-11T03:42:57.619Z","0.3.0":"2026-07-11T02:51:57.247Z","0.3.1":"2026-07-11T03:30:28.098Z","0.3.2":"2026-07-11T03:42:57.350Z"},"bugs":{"url":"https://github.com/joethefisher/agent-arc-status/issues"},"author":{"name":"Joe Fisher"},"license":"MIT","homepage":"https://github.com/joethefisher/agent-arc-status#readme","keywords":["agent","agents","ai","llm","observability","progress","webhook","arc-status"],"repository":{"type":"git","url":"git+https://github.com/joethefisher/agent-arc-status.git","directory":"packages/reference"},"description":"Reference implementation of the Agent Arc Status Protocol: types, parser, validator, renderer, cadence, state, and delegation-tree tooling. Zero runtime dependencies.","maintainers":[{"name":"joethefisher","email":"joefisherpersonal@gmail.com"}],"readme":"# `@agent-arc-status/reference`: Node reference implementation\n\nReference TypeScript implementation of the [Agent Arc Status Protocol](../../README.md) v0.2.\n\nProvides:\n\n- Types matching the wire schema (`ArcStatusEvent`, `ArcStatusPhase`)\n- A structural validator (`validate`)\n- A sequence validator for per-arc phase ordering (`validateSequence`)\n- JSON / JSON Lines parsers that never throw (`parse`, `parseJsonl`)\n- A default human-line renderer (`render`)\n- Cadence helpers (`CadenceController` and `SilenceWatchdog`) that drive the\n  silence backstop and cadence-floor gating\n- `reduceArc`, which folds an event stream into current arc state\n\nZero runtime dependencies.\n\n## Install\n\n```bash\nnpm install @agent-arc-status/reference\n```\n\n> Working from a clone instead? This package is a workspace in the\n> [monorepo](https://github.com/joethefisher/agent-arc-status); run `npm install` at the repo\n> root and the `prepare` script builds `dist/`. The surface is small enough to vendor `src/` too.\n\n## Use\n\n### Emit and validate an event\n\n```ts\nimport { validate, type ArcStatusEvent } from \"@agent-arc-status/reference\";\n\nconst event: ArcStatusEvent = {\n  arc_id: crypto.randomUUID(),\n  phase: \"milestone\",\n  title: \"receiver booted, smoke test passes\",\n  step: 5,\n  total: 11,\n  eta_minutes: 25,\n  sent_at: new Date().toISOString(),\n  protocol_version: \"0.1\",\n};\n\nconst result = validate(event);\nif (!result.ok) {\n  for (const issue of result.issues) {\n    console.error(`${issue.path}: ${issue.message}`);\n  }\n  throw new Error(\"malformed arc.status event\");\n}\n\nawait postWebhook(\"https://...\", JSON.stringify(result.event));\n```\n\n### Parse a JSON Lines stream of events\n\n```ts\nimport { parseJsonl, validateSequence } from \"@agent-arc-status/reference\";\nimport { readFileSync } from \"node:fs\";\n\nconst { events, errors } = parseJsonl(readFileSync(\"./arc.jsonl\", \"utf8\"));\n\nif (errors.length > 0) {\n  console.warn(`${errors.length} malformed events skipped`);\n}\n\nconst seq = validateSequence(events);\nif (!seq.ok) {\n  console.error(\"arc phase ordering invalid:\", seq.issues);\n}\n```\n\n### Render for human surfaces\n\n```ts\nimport { render } from \"@agent-arc-status/reference\";\n\n// \"▶ build Pulsefeed v0.1\"\nrender({ ... phase: \"started\", title: \"build Pulsefeed v0.1\" });\n\n// \"✓ [5/11] receiver booted (ETA 25m)\"\nrender({ ... phase: \"milestone\", title: \"receiver booted\", step: 5, total: 11, eta_minutes: 25 });\n\n// \"⛔ need finance sign-off on plan-B reclassification\\ndetails about what would unblock\"\nrender(event, { body: true });\n```\n\n## Development\n\n```bash\nnpm install\nnpm test         # vitest\nnpm run build    # tsc → dist/\nnpm run typecheck\n```\n\nTests include end-to-end runs against the shipped [`examples/`](../../examples/) JSONL fixtures, so any deviation from the documented examples is caught immediately.\n\n## Scope\n\nThis package implements **structural conformance plus cadence discipline**. It does not implement:\n\n- Transport (HTTP/queue/etc.): the Protocol is transport-agnostic; bring your own.\n- Persistence: emitters and consumers store events as fits their architecture.\n\nThe silence backstop and cadence-floor gating ship as `CadenceController` and\n`SilenceWatchdog` (see [`src/cadence.ts`](src/cadence.ts)); drive them from a\ntimer independent of your work loop, since an emitter that heartbeats from its\nown work loop cannot signal liveness in the one case that matters: when that\nloop has stalled.\n\nFor the canonical schema, see [`spec/schema.json`](../../spec/schema.json). For the full specification, see [`spec/v0.2.md`](../../spec/v0.2.md).\n","readmeFilename":"README.md"}