{"_id":"@else-ventures/agent-provenance-dag","name":"@else-ventures/agent-provenance-dag","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@else-ventures/agent-provenance-dag","version":"0.1.0","description":"Signed causal provenance DAGs for delegated agent work","type":"module","main":"./dist/src/index.js","types":"./dist/src/index.d.ts","exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","example":"tsx examples/alice-bob.ts"},"keywords":["openclaw","ai-agents","provenance","delegation","dag","typescript"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Else-Ventures/agent-provenance-dag.git"},"homepage":"https://github.com/Else-Ventures/agent-provenance-dag#readme","bugs":{"url":"https://github.com/Else-Ventures/agent-provenance-dag/issues"},"devDependencies":{"@types/node":"^22.15.3","tsx":"^4.19.2","typescript":"^5.8.3","vitest":"^3.2.4"},"gitHead":"7270f78279c988fcb7aa503130c1848a76d7bd19","_id":"@else-ventures/agent-provenance-dag@0.1.0","_nodeVersion":"24.13.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-AnXZO8d1CgP2EBG3zPRWwuSqGoaDLvaUaV4vDw6rWTmSoDyA9rpR8AvzwfNZy22+LMZBSuoah1cQ+9/9lwKD4w==","shasum":"4643041c274e240ede6be4181d369a3374f8656e","tarball":"https://registry.npmjs.org/@else-ventures/agent-provenance-dag/-/agent-provenance-dag-0.1.0.tgz","fileCount":9,"unpackedSize":21156,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGc+XRDp6u/vOKjuHNL6AyTmw0iWWw/hw7Iz2KcAWcHGAiAyT2wbAwDXovir3GMEHW/QCv3zxP2WU+EhOeZUoMuBwg=="}]},"_npmUser":{"name":"elseventures","email":"elsie@else.ventures"},"directories":{},"maintainers":[{"name":"elseventures","email":"elsie@else.ventures"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-provenance-dag_0.1.0_1777184038065_0.7880913750508292"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-26T06:13:57.974Z","0.1.0":"2026-04-26T06:13:58.204Z","modified":"2026-04-26T06:13:58.387Z"},"maintainers":[{"name":"elseventures","email":"elsie@else.ventures"}],"description":"Signed causal provenance DAGs for delegated agent work","homepage":"https://github.com/Else-Ventures/agent-provenance-dag#readme","keywords":["openclaw","ai-agents","provenance","delegation","dag","typescript"],"repository":{"type":"git","url":"git+https://github.com/Else-Ventures/agent-provenance-dag.git"},"bugs":{"url":"https://github.com/Else-Ventures/agent-provenance-dag/issues"},"license":"MIT","readme":"# agent-provenance-dag\n\nSigned causal provenance DAGs for delegated agent work.\n\n`agent-provenance-dag` is a small TypeScript package for creating and verifying signed event graphs that explain how delegated work moved from one agent to another. It is built for OpenClaw agents, autonomous agents, and human operators who want a portable provenance envelope instead of a hand-wavy trust story.\n\n## Agent metadata\n\n- Built for: OpenClaw agents, autonomous agents, and human operators\n- Category: agent-infrastructure\n- Use cases: delegated task provenance, agent handoff verification, artifact lineage, compact trust envelopes\n- Runtime: Node.js / TypeScript\n\n## Current status\n\nV1 is intentionally narrow:\n- create signed provenance events\n- link them with `selfParent` and `causalParents`\n- verify graph integrity offline\n- create a compact signed claim that can travel with a task\n- carry the full DAG inline or by pointer\n\nV1 does **not** try to solve:\n- agent reputation\n- payment settlement\n- RPC-based on-chain verification\n- key management or rotation\n- protocol-wide policy engines\n\n## Why a DAG instead of a plain log?\n\nDelegated agent work is rarely a single straight line.\n\nOne agent can start a task, delegate part of it to another agent, receive a signed artifact back, and then forward the result downstream. Payment, delivery, and verification can happen on different branches. A DAG captures that causal structure directly.\n\n## Mental model: Alice and Bob\n\nAlice is handling a task but needs market context before she can continue.\n\n1. Alice creates a `GENESIS` event for the task.\n2. Alice delegates part of the task to Bob and signs a `DELEGATED` event.\n3. Bob verifies the incoming claim, accepts the work, and signs an `ACCEPTED` event.\n4. Bob produces an artifact, signs a `DELIVERED` event, and returns it to Alice.\n5. Alice forwards the result to another agent with:\n   - the task output\n   - a compact signed claim\n   - optionally a pointer to the full DAG\n\nThe next agent does not need to interrogate Alice or Bob live. It can inspect the signed provenance payload, verify the structure offline, and decide whether to trust the handoff.\n\n## Install\n\nClone the repo and install dependencies:\n\n```bash\ngit clone https://github.com/Else-Ventures/agent-provenance-dag.git\ncd agent-provenance-dag\nnpm install\nnpm run build\n```\n\nnpm publish comes after v1 review.\n\n## API\n\n```ts\ncreateEvent(input): Promise<ProvenanceEvent>\nverifyEvent(event): Promise<boolean>\ncreateDag(): ProvenanceDag\ninsertEvent(dag, event): ProvenanceDag\nverifyDag(dag): Promise<{ valid: boolean; errors: string[] }>\nhashDag(dag): string\ncreateClaim(input): Promise<ChainClaim>\nverifyClaim(claim): Promise<boolean>\ncreatePaymentReceiptRef(txHash, chainId, amount, asset): PaymentReceiptRef\nattachProvenance(task, envelope): taskWithExtensions\nextractProvenance(task): ProvenanceEnvelope | null\ngenerateEd25519Identity(): { publicKey: string; privateKey: string }\nmakeSigner(privateKey)\nmakeVerifier(publicKey)\n```\n\n## Example\n\n```ts\nimport {\n  attachProvenance,\n  createClaim,\n  createDag,\n  createEvent,\n  generateEd25519Identity,\n  hashDag,\n  insertEvent,\n  makeSigner,\n} from '@else-ventures/agent-provenance-dag';\n\nconst alice = generateEd25519Identity();\nconst bob = generateEd25519Identity();\n\nconst genesis = await createEvent({\n  type: 'GENESIS',\n  agentId: 'alice',\n  publicKey: alice.publicKey,\n  nonce: 0,\n  payload: { taskId: 'task-alice-bob-001', description: 'Research one opportunity' },\n  sign: makeSigner(alice.privateKey),\n});\n\nconst delegated = await createEvent({\n  type: 'DELEGATED',\n  agentId: 'alice',\n  publicKey: alice.publicKey,\n  nonce: 1,\n  payload: { taskId: 'task-alice-bob-001', to: 'bob' },\n  selfParent: genesis.id,\n  causalParents: [genesis.id],\n  sign: makeSigner(alice.privateKey),\n});\n\nconst accepted = await createEvent({\n  type: 'ACCEPTED',\n  agentId: 'bob',\n  publicKey: bob.publicKey,\n  nonce: 0,\n  payload: { taskId: 'task-alice-bob-001', acceptedFrom: 'alice' },\n  causalParents: [delegated.id],\n  sign: makeSigner(bob.privateKey),\n});\n\nconst delivered = await createEvent({\n  type: 'DELIVERED',\n  agentId: 'bob',\n  publicKey: bob.publicKey,\n  nonce: 1,\n  payload: { taskId: 'task-alice-bob-001', artifactHash: 'sha256:artifact-001' },\n  selfParent: accepted.id,\n  causalParents: [accepted.id, delegated.id],\n  sign: makeSigner(bob.privateKey),\n});\n\nlet dag = createDag();\ndag = insertEvent(dag, genesis);\ndag = insertEvent(dag, delegated);\ndag = insertEvent(dag, accepted);\ndag = insertEvent(dag, delivered);\n\nconst claim = await createClaim({\n  issuer: 'alice',\n  publicKey: alice.publicKey,\n  taskId: 'task-alice-bob-001',\n  headIds: [delivered.id],\n  dagHash: hashDag(dag),\n  dagRef: 'ipfs://bafy-example',\n  sign: makeSigner(alice.privateKey),\n});\n\nconst outgoingTask = attachProvenance(\n  { id: 'task-alice-bob-001' },\n  { claim, dagRef: claim.dagRef, dag },\n);\n```\n\nSee `examples/alice-bob.ts` for a runnable end-to-end example.\n\n## Offline vs online verification\n\nOffline verification in v1 covers:\n- event integrity\n- signatures\n- self-parent nonce progression\n- parent existence\n- cycle detection\n- DAG hash matching when you compare a fetched DAG to a claim\n\nOnline verification is intentionally out of scope for v1. If you want to reference payment receipts now, attach a `PaymentReceiptRef` and handle chain-specific verification in your own adapter.\n\n## Key management note\n\nThis package does not manage private keys. You are responsible for generating, storing, and rotating signing keys in a way that fits your deployment.\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run build\nnpm run example\n```\n","readmeFilename":"README.md","_rev":"1-e3a1bcd64fd4d3d876351ff1e246f172"}