handoff-relay 0.1.0

package/examples/packets/ask.json

@@ -0,0 +1,73 @@
+{
+  "packet_id": "pkt_example_ask",
+  "packet_type": "ask",
+  "workspace_id": "wrk_example",
+  "sender_member_id": "mem_sam",
+  "recipient_member_ids": ["mem_alice"],
+  "created_at": "2026-06-15T12:00:00.000Z",
+  "updated_at": "2026-06-15T12:00:00.000Z",
+  "expires_at": "2026-06-16T12:00:00.000Z",
+  "status": "pending_sender_approval",
+  "project": {
+    "repo_name": "project-api",
+    "git_remote_fingerprint": "sha256:example",
+    "branch": "main",
+    "commit_hash": "abc123"
+  },
+  "source_client": "codex",
+  "title": "Auth refresh test keeps failing",
+  "summary": "The auth refresh integration test returns 401 after token rotation.",
+  "question": "Can you check why the auth refresh test keeps failing?",
+  "claims": [
+    {
+      "claim_id": "clm_1",
+      "text": "The failure happens after refresh token rotation.",
+      "confidence": "medium",
+      "status": "observed",
+      "evidence_ids": ["ev_1"],
+      "needs_recheck": true
+    }
+  ],
+  "evidence": [
+    {
+      "evidence_id": "ev_1",
+      "kind": "test_failure",
+      "label": "vitest failure",
+      "source": "pnpm test auth-refresh",
+      "excerpt": "expected 200, received 401",
+      "hash": "sha256:testfailure",
+      "captured_at": "2026-06-15T11:58:00.000Z",
+      "sensitivity": "normal"
+    }
+  ],
+  "files_or_symbols": ["src/auth/refresh.ts", "refreshSession"],
+  "commands_or_tests_run": ["pnpm test auth-refresh"],
+  "what_was_tried": ["Re-ran the failing integration test"],
+  "known_failures": ["Refresh token test returns 401"],
+  "current_hypothesis": "The rotated token is not persisted before the second request.",
+  "confidence": "medium",
+  "suggested_next_steps": ["Compare with Alice's auth branch"],
+  "redaction_report": {
+    "blocked": false,
+    "findings": [],
+    "warnings": []
+  },
+  "hydration_policy": {
+    "requires_recipient_approval": true,
+    "requires_sender_approval_for_replies": true,
+    "allow_raw_transcript": false,
+    "max_characters": 8000
+  },
+  "audit_receipt": {
+    "receipt_id": "rcp_example_draft",
+    "action": "draft",
+    "actor_member_id": "mem_sam",
+    "packet_id": "pkt_example_ask",
+    "workspace_id": "wrk_example",
+    "created_at": "2026-06-15T12:00:00.000Z",
+    "metadata": {
+      "source_client": "codex"
+    },
+    "receipt_hash": "sha256:example"
+  }
+}

package/examples/packets/reply.json

@@ -0,0 +1,62 @@
+{
+  "packet_id": "pkt_example_reply",
+  "packet_type": "reply",
+  "workspace_id": "wrk_example",
+  "sender_member_id": "mem_alice",
+  "recipient_member_ids": ["mem_sam"],
+  "parent_packet_id": "pkt_example_ask",
+  "created_at": "2026-06-15T12:20:00.000Z",
+  "updated_at": "2026-06-15T12:20:00.000Z",
+  "expires_at": "2026-06-16T12:20:00.000Z",
+  "status": "pending_recipient_approval",
+  "project": {
+    "repo_name": "project-api",
+    "git_remote_fingerprint": "sha256:example",
+    "branch": "main"
+  },
+  "source_client": "claude-code",
+  "title": "Reply: Auth refresh test keeps failing",
+  "summary": "Likely refresh persistence ordering issue.",
+  "answer": "Persist the rotated refresh token before retrying the request.",
+  "claims": [
+    {
+      "claim_id": "clm_reply_1",
+      "text": "The retry path reads the old refresh token.",
+      "confidence": "high",
+      "status": "inferred",
+      "evidence_ids": [],
+      "needs_recheck": true
+    }
+  ],
+  "evidence": [],
+  "files_or_symbols": ["src/auth/middleware.ts"],
+  "commands_or_tests_run": [],
+  "what_was_tried": ["Compared local retry path with Sam's packet"],
+  "known_failures": [],
+  "current_hypothesis": "Persist refresh before retrying.",
+  "confidence": "high",
+  "suggested_next_steps": ["Move persistence before retry and rerun auth-refresh tests"],
+  "redaction_report": {
+    "blocked": false,
+    "findings": [],
+    "warnings": []
+  },
+  "hydration_policy": {
+    "requires_recipient_approval": true,
+    "requires_sender_approval_for_replies": true,
+    "allow_raw_transcript": false,
+    "max_characters": 8000
+  },
+  "audit_receipt": {
+    "receipt_id": "rcp_example_reply",
+    "action": "draft",
+    "actor_member_id": "mem_alice",
+    "packet_id": "pkt_example_reply",
+    "workspace_id": "wrk_example",
+    "created_at": "2026-06-15T12:20:00.000Z",
+    "metadata": {
+      "source_client": "claude-code"
+    },
+    "receipt_hash": "sha256:example"
+  }
+}

package/examples/packets/share.json

@@ -0,0 +1,52 @@
+{
+  "packet_id": "pkt_example_share",
+  "packet_type": "share",
+  "workspace_id": "wrk_example",
+  "sender_member_id": "mem_sam",
+  "recipient_member_ids": ["mem_alice"],
+  "created_at": "2026-06-15T12:10:00.000Z",
+  "updated_at": "2026-06-15T12:10:00.000Z",
+  "recheck_by": "2026-06-17T12:10:00.000Z",
+  "status": "pending_sender_approval",
+  "project": {
+    "repo_name": "project-api",
+    "git_remote_fingerprint": "sha256:example",
+    "branch": "main"
+  },
+  "source_client": "codex",
+  "title": "Auth middleware finding",
+  "summary": "The middleware skips refresh persistence on retried requests.",
+  "finding": "Refresh persistence is skipped when middleware retries after a 401.",
+  "claims": [],
+  "evidence": [],
+  "files_or_symbols": ["src/auth/middleware.ts"],
+  "commands_or_tests_run": ["pnpm test auth-middleware"],
+  "what_was_tried": ["Traced retry path"],
+  "known_failures": [],
+  "current_hypothesis": "Persist refresh before retrying.",
+  "confidence": "high",
+  "suggested_next_steps": ["Patch middleware retry path"],
+  "redaction_report": {
+    "blocked": false,
+    "findings": [],
+    "warnings": []
+  },
+  "hydration_policy": {
+    "requires_recipient_approval": true,
+    "requires_sender_approval_for_replies": true,
+    "allow_raw_transcript": false,
+    "max_characters": 8000
+  },
+  "audit_receipt": {
+    "receipt_id": "rcp_example_share",
+    "action": "draft",
+    "actor_member_id": "mem_sam",
+    "packet_id": "pkt_example_share",
+    "workspace_id": "wrk_example",
+    "created_at": "2026-06-15T12:10:00.000Z",
+    "metadata": {
+      "source_client": "codex"
+    },
+    "receipt_hash": "sha256:example"
+  }
+}

package/fixtures/clarification.json

@@ -0,0 +1,7 @@
+{
+  "original_packet_id": "pkt_ask_normal",
+  "question": "Can you include the failing assertion and the token payload shape?",
+  "requested_evidence": ["test failure excerpt", "token payload fields"],
+  "recipient_member_id": "mem_alice",
+  "created_at": "2026-06-15T12:20:00.000Z"
+}

package/fixtures/declined-packet.json

@@ -0,0 +1,6 @@
+{
+  "packet_id": "pkt_declined",
+  "status": "declined",
+  "decline_reason": "Not my project area today.",
+  "actor_member_id": "mem_alice"
+}

package/fixtures/normal-ask.json

@@ -0,0 +1,72 @@
+{
+  "packet_id": "pkt_ask_normal",
+  "packet_type": "ask",
+  "workspace_id": "wrk_demo",
+  "sender_member_id": "mem_sam",
+  "recipient_member_ids": ["mem_alice"],
+  "created_at": "2026-06-15T12:00:00.000Z",
+  "updated_at": "2026-06-15T12:00:00.000Z",
+  "expires_at": "2026-06-16T12:00:00.000Z",
+  "status": "pending_sender_approval",
+  "project": {
+    "repo_name": "project-api",
+    "git_remote_fingerprint": "sha256:demo",
+    "branch": "main",
+    "commit_hash": "abc123"
+  },
+  "source_client": "codex",
+  "title": "Auth refresh test keeps failing",
+  "summary": "The auth refresh integration test fails after token rotation.",
+  "question": "Can you check why the auth refresh test keeps failing?",
+  "claims": [
+    {
+      "claim_id": "clm_1",
+      "text": "The failure happens after refresh token rotation.",
+      "confidence": "medium",
+      "status": "observed",
+      "evidence_ids": ["ev_1"],
+      "needs_recheck": true
+    }
+  ],
+  "evidence": [
+    {
+      "evidence_id": "ev_1",
+      "kind": "test_failure",
+      "label": "vitest failure",
+      "source": "pnpm test auth-refresh",
+      "excerpt": "expected 200, received 401 in auth refresh integration test",
+      "hash": "sha256:testfailure",
+      "captured_at": "2026-06-15T11:58:00.000Z",
+      "sensitivity": "normal"
+    }
+  ],
+  "files_or_symbols": ["src/auth/refresh.ts", "refreshSession"],
+  "commands_or_tests_run": ["pnpm test auth-refresh"],
+  "what_was_tried": ["Re-ran the failing integration test", "Checked token expiry math"],
+  "known_failures": ["Refresh token test returns 401"],
+  "current_hypothesis": "The rotated token is not persisted before the second request.",
+  "confidence": "medium",
+  "suggested_next_steps": ["Compare with Alice's local auth branch"],
+  "redaction_report": {
+    "blocked": false,
+    "findings": [],
+    "warnings": []
+  },
+  "hydration_policy": {
+    "requires_recipient_approval": true,
+    "requires_sender_approval_for_replies": true,
+    "allow_raw_transcript": false,
+    "max_characters": 8000
+  },
+  "audit_receipt": {
+    "receipt_id": "rcp_fixture",
+    "action": "draft",
+    "actor_member_id": "mem_sam",
+    "packet_id": "pkt_ask_normal",
+    "workspace_id": "wrk_demo",
+    "created_at": "2026-06-15T12:00:00.000Z",
+    "metadata": {
+      "source_client": "codex"
+    }
+  }
+}

package/fixtures/normal-share.json

@@ -0,0 +1,51 @@
+{
+  "packet_id": "pkt_share_normal",
+  "packet_type": "share",
+  "workspace_id": "wrk_demo",
+  "sender_member_id": "mem_sam",
+  "recipient_member_ids": ["mem_alice"],
+  "created_at": "2026-06-15T12:05:00.000Z",
+  "updated_at": "2026-06-15T12:05:00.000Z",
+  "recheck_by": "2026-06-17T12:05:00.000Z",
+  "status": "pending_sender_approval",
+  "project": {
+    "repo_name": "project-api",
+    "git_remote_fingerprint": "sha256:demo",
+    "branch": "main"
+  },
+  "source_client": "claude-code",
+  "title": "Auth middleware finding",
+  "summary": "The middleware skips refresh persistence on retried requests.",
+  "finding": "Refresh persistence is skipped when middleware retries after a 401.",
+  "claims": [],
+  "evidence": [],
+  "files_or_symbols": ["src/auth/middleware.ts"],
+  "commands_or_tests_run": ["pnpm test auth-middleware"],
+  "what_was_tried": ["Traced retry path"],
+  "known_failures": [],
+  "current_hypothesis": "Persist refresh before retrying.",
+  "confidence": "high",
+  "suggested_next_steps": ["Patch middleware retry path"],
+  "redaction_report": {
+    "blocked": false,
+    "findings": [],
+    "warnings": []
+  },
+  "hydration_policy": {
+    "requires_recipient_approval": true,
+    "requires_sender_approval_for_replies": true,
+    "allow_raw_transcript": false,
+    "max_characters": 8000
+  },
+  "audit_receipt": {
+    "receipt_id": "rcp_share_fixture",
+    "action": "draft",
+    "actor_member_id": "mem_sam",
+    "packet_id": "pkt_share_normal",
+    "workspace_id": "wrk_demo",
+    "created_at": "2026-06-15T12:05:00.000Z",
+    "metadata": {
+      "source_client": "claude-code"
+    }
+  }
+}

package/fixtures/revoked-member.json

@@ -0,0 +1,7 @@
+{
+  "workspace_id": "wrk_demo",
+  "member_id": "mem_bob",
+  "handle": "bob",
+  "status": "revoked",
+  "revoked_at": "2026-06-15T12:30:00.000Z"
+}

package/fixtures/secret-redaction.json

@@ -0,0 +1,10 @@
+{
+  "evidence_id": "ev_secret",
+  "kind": "log_excerpt",
+  "label": "local env",
+  "source": ".env",
+  "excerpt": "OPENAI_API_KEY=sk-proj-secretsecretsecretsecret\nDATABASE_URL=postgres://user:pass@example.com/db",
+  "hash": "sha256:secret",
+  "captured_at": "2026-06-15T12:10:00.000Z",
+  "sensitivity": "normal"
+}

package/fixtures/stale-handoff.json

@@ -0,0 +1,16 @@
+{
+  "title": "Stale incident handoff",
+  "summary": "The production symptom was observed before the rollback.",
+  "recheck_by": "2026-06-14T12:00:00.000Z",
+  "current_hypothesis": "Cache keys may have changed, but this must be rechecked.",
+  "claims": [
+    {
+      "claim_id": "clm_stale",
+      "text": "The error rate increased after deploy 2026.06.14.",
+      "confidence": "low",
+      "status": "observed",
+      "evidence_ids": [],
+      "needs_recheck": true
+    }
+  ]
+}

package/fixtures/superseded-packet.json

@@ -0,0 +1,6 @@
+{
+  "packet_id": "pkt_superseded",
+  "status": "superseded",
+  "superseded_by_packet_id": "pkt_share_normal",
+  "reason": "Newer packet includes corrected middleware trace."
+}

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "handoff-relay",
+  "version": "0.1.0",
+  "description": "Human-approved context handoffs between coding agents.",
+  "type": "module",
+  "license": "MIT",
+  "packageManager": "pnpm@10.17.1",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/server.d.ts",
+      "import": "./dist/api/server.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/server.d.ts",
+      "import": "./dist/mcp/server.js"
+    }
+  },
+  "keywords": [
+    "agent",
+    "mcp",
+    "coding-agents",
+    "handoff",
+    "sqlite"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0dust/handoff.git"
+  },
+  "bugs": {
+    "url": "https://github.com/0dust/handoff/issues"
+  },
+  "homepage": "https://github.com/0dust/handoff#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "handoff": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs/advanced-manual-setup.md",
+    "docs/claude-code-setup.md",
+    "docs/codex-setup.md",
+    "docs/demo-video-script.md",
+    "docs/generic-mcp-setup.md",
+    "docs/launch-copy.md",
+    "docs/local-self-hosting.md",
+    "docs/packet-schema.md",
+    "docs/security-privacy.md",
+    "docs/troubleshooting.md",
+    "examples",
+    "fixtures",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/cli.ts src/index.ts src/api/server.ts src/mcp/server.ts --format esm --dts --clean --splitting false",
+    "check": "pnpm lint && pnpm typecheck && pnpm test",
+    "cli": "tsx src/cli.ts",
+    "demo": "tsx src/cli.ts demo two-user",
+    "demo:recording-script": "node -e \"console.log('docs/demo-video-script.md')\"",
+    "dev:server": "tsx src/cli.ts server start",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "mcp": "tsx src/cli.ts server mcp",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm check && pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "better-sqlite3": "^12.2.0",
+    "commander": "^14.0.2",
+    "fastify": "^5.6.2",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^24.10.1",
+    "eslint": "^9.39.1",
+    "prettier": "^3.6.2",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vitest": "^4.0.14"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "esbuild"
+    ]
+  }
+}