{"_id":"@danchamorro/pi-handoff-agent","_rev":"3-4c59322875266ef2edfffbdb12c4842d","name":"@danchamorro/pi-handoff-agent","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@danchamorro/pi-handoff-agent","version":"0.1.0","keywords":["pi-package","pi","pi-extension","handoff","session","export","coding-agent"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-handoff-agent@0.1.0","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"dd821f200ac8f2f182682a9b2468e8f21172e4c2","tarball":"https://registry.npmjs.org/@danchamorro/pi-handoff-agent/-/pi-handoff-agent-0.1.0.tgz","fileCount":18,"integrity":"sha512-fiX/6lBUICkF5Mbn4kFA7wC6Cqrb6KkmY9ZGg0CRmBJXHlHOHM3BDSua1G5EAUK3BhPO/BdJzn/Nbl7MzHbPbg==","signatures":[{"sig":"MEUCIQDMm4yusmEZu7SNq1a1d0zYY20jcd0OVDcUvF/bYhbBNwIgTEAqbPbxkHm/bK5Dz68Uj/9soagImCrGx1EjT9irwqA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29820},"type":"module","gitHead":"8cd99841b7733a336909b705cd9b7ee223f8dbe6","scripts":{"test":"node --test *.test.ts","typecheck":"tsc --noEmit --project ../../tsconfig.packages.json"},"_npmUser":{"name":"danchamorro","email":"i@danchamorro.com"},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/handoff-pi-agent"},"_npmVersion":"11.8.0","description":"Export clean Pi session handoffs for portable agent continuity","directories":{},"_nodeVersion":"24.13.1","_hasShrinkwrap":false,"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-handoff-agent_0.1.0_1778996786033_0.4849872803083408","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@danchamorro/pi-handoff-agent","version":"0.1.1","keywords":["pi-package","pi","pi-extension","handoff","session","export","coding-agent"],"author":{"name":"Daniel Chamorro"},"license":"MIT","_id":"@danchamorro/pi-handoff-agent@0.1.1","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"b181b79d8a05e300a3408e8b755de0c08c0cfc10","tarball":"https://registry.npmjs.org/@danchamorro/pi-handoff-agent/-/pi-handoff-agent-0.1.1.tgz","fileCount":18,"integrity":"sha512-rAHHcktN5dHQGLAF3byH3jOQYOVMY7dy5kc8TXG500qS6Rew+OVHrNgxPh3QV5kodYQQ9gRSik1pKlXr0JboJQ==","signatures":[{"sig":"MEYCIQDTMdq7YbItyEixwAGO5KJzIFKsKBrPCzNPN6RuehGxxgIhAMgR5pElk9aai4x6IkzmIiMwfiBDQvdaee4EvF3xYdmZ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35863},"type":"module","gitHead":"999354032b8157f88107bf81d01ffe66cbdd2134","scripts":{"test":"node --test *.test.ts","typecheck":"tsc --noEmit --project ../../tsconfig.packages.json"},"_npmUser":{"name":"danchamorro","email":"i@danchamorro.com"},"repository":{"url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","type":"git","directory":"packages/handoff-pi-agent"},"_npmVersion":"11.8.0","description":"Export clean Pi session handoffs for portable agent continuity","directories":{},"_nodeVersion":"24.13.1","_hasShrinkwrap":false,"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-handoff-agent_0.1.1_1779058628749_0.9477455764781411","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@danchamorro/pi-handoff-agent","version":"0.2.0","description":"Export clean Pi session handoffs for portable agent continuity","keywords":["pi-package","pi","pi-extension","handoff","session","export","coding-agent"],"license":"MIT","author":{"name":"Daniel Chamorro"},"repository":{"type":"git","url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","directory":"packages/handoff-pi-agent"},"type":"module","scripts":{"test":"node --test *.test.ts","typecheck":"tsc --noEmit --project ../../tsconfig.packages.json"},"pi":{"extensions":["./index.ts"]},"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-coding-agent":"*"},"gitHead":"f5969521e74e22e6d49ae03e6730a92043a1747f","_id":"@danchamorro/pi-handoff-agent@0.2.0","bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","_nodeVersion":"24.13.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-e4DPh85I8Y6M+a8jrAmKgfY1d6M+g3za0A338KxbJ/kZrXEV3c5B8SNpiGkIDvAJ9sSxV9WpawOJ3uHiiEb63g==","shasum":"f85622dbe82102937e75fc3c7ac5b93ab5d85054","tarball":"https://registry.npmjs.org/@danchamorro/pi-handoff-agent/-/pi-handoff-agent-0.2.0.tgz","fileCount":18,"unpackedSize":59377,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCVS7hEYILMYVTxMYLK3YMnY8cwUrbWa9Y3zFLyxw81qAIhAO3FVESSz1f7KAZnMhtn3ULg65LR6Mnp6jhz1FEkRlOp"}]},"_npmUser":{"name":"danchamorro","email":"i@danchamorro.com"},"directories":{},"maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-handoff-agent_0.2.0_1779062652476_0.03572259341479689"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-17T05:46:25.902Z","modified":"2026-05-18T00:04:12.730Z","0.1.0":"2026-05-17T05:46:26.195Z","0.1.1":"2026-05-17T22:57:08.948Z","0.2.0":"2026-05-18T00:04:12.606Z"},"bugs":{"url":"https://github.com/danchamorro/pi-agent-toolkit/issues"},"author":{"name":"Daniel Chamorro"},"license":"MIT","homepage":"https://github.com/danchamorro/pi-agent-toolkit#readme","keywords":["pi-package","pi","pi-extension","handoff","session","export","coding-agent"],"repository":{"type":"git","url":"git+https://github.com/danchamorro/pi-agent-toolkit.git","directory":"packages/handoff-pi-agent"},"description":"Export clean Pi session handoffs for portable agent continuity","maintainers":[{"name":"danchamorro","email":"i@danchamorro.com"}],"readme":"# @danchamorro/pi-handoff-agent\n\nExport the active Pi conversation into a portable continuity packet that another agent session can read and continue from.\n\n## Why this exists\n\nLong-running agent work often outlives a single session. You may need to move from one Pi session to another, continue work after compaction, hand context to a different model, or preserve the exact decision trail before switching tasks. Native session files are not a good handoff format because they include thinking traces and Pi-specific state, while transcript-only exports can miss important evidence from tools.\n\n`pi-handoff-agent` turns the current active Pi branch into one clean handoff artifact:\n\n- writes a model-generated briefing when the active model is available\n- falls back to a deterministic briefing when model access is unavailable\n- preserves user and assistant message text\n- preserves tool calls, tool results, command output, MCP output, and subagent context as evidence\n- keeps branch or compaction summaries when they are part of active context\n- preserves raw pre-compact branch history instead of relying only on lossy compact summaries\n- removes thinking and reasoning traces\n- omits extension state records that do not participate in LLM context\n- writes a canonical JSON file for the next agent session\n- writes a Markdown companion for human review\n- protects `.handoffs/` with `.gitignore` so private context is not accidentally committed\n\nThe point is not native session cloning. The point is portable continuity: a fresh agent can read the briefing first, then inspect timeline evidence only when needed.\n\n## Install\n\n```bash\npi install npm:@danchamorro/pi-handoff-agent\n```\n\nFor local development from this repo:\n\n```bash\npi install ./packages/handoff-pi-agent\n```\n\n## Command\n\nRun this inside the Pi session you want to export:\n\n```text\n/handoff-export\n```\n\nThe command writes project-local files:\n\n```text\n.handoffs/<timestamp-pi-agent>/handoff.json\n.handoffs/<timestamp-pi-agent>/handoff.md\n```\n\n`handoff.json` is the canonical artifact for receiving agents. `handoff.md` is generated from the JSON for inspection and review.\n\n## How it works in simple terms\n\n1. Code reads the active Pi branch through Pi's session API.\n2. Code builds a clean timeline from that branch.\n3. The timeline keeps transcript text and tool evidence, including command output and subagent summaries.\n4. The timeline removes thinking traces and Pi-only state.\n5. The extension makes a separate one-shot model call using the same active model and credentials. This call has a fresh context window and only sees the cleaned timeline plus stats.\n6. That model call writes the `briefing`. If it fails, code writes a deterministic fallback briefing.\n7. Code writes `handoff.json` and renders `handoff.md` from the same JSON.\n\n## Receiving workflow\n\nStart a fresh agent session in the same repo and say:\n\n```text\nPlease read .handoffs/<timestamp-pi-agent>/handoff.json so we can pick up where I left off. Start with the briefing, then inspect timeline messages only if supporting evidence is needed. The companion handoff.md is for human review.\n```\n\nA good receiving session should be able to identify the current goal, key decisions, completed work, open caveats, validation status, and the next action.\n\n## Artifact structure\n\nThe package intentionally keeps one command and one canonical JSON format:\n\n- `briefing`: current-state handoff summary generated by a fresh one-shot call to the active model when possible.\n- `messages`: active branch timeline with transcript text and tool evidence preserved after thinking traces are removed.\n- `policy`: preservation policy for the artifact.\n- `stats`: counts of entries, preserved tool evidence, omitted state, removed thinking, and warnings.\n\nThe model-generated briefing is like a tiny summarizer subagent with no tools. It does not use the current chat context window directly. It only receives the cleaned handoff timeline and stats.\n\n## Why a package-backed extension\n\nThe export must read the live Pi session branch. File modification time is not reliable when sessions are resumed, forked, compacted, or running concurrently. This package registers a Pi extension command so it can use Pi runtime APIs for the active branch and session metadata instead of guessing from session files.\n\n## Privacy and gitignore behavior\n\nHandoffs may contain private prompts, code snippets, local paths, command output, API responses, database rows, logs, and business context. The exporter appends `.handoffs/` to an existing `.gitignore`. If no `.gitignore` exists, it fails safely rather than silently creating one.\n\nReview handoffs before sharing them outside the project or organization.\n\n## What gets preserved\n\nThe exporter preserves continuity evidence by default:\n\n- user and assistant text\n- context summaries\n- tool calls and arguments\n- tool results and outputs\n- shell command output\n- MCP output\n- subagent context messages\n- compacted branch summaries and raw pre-compact branch history when present\n\n## What gets removed\n\nThe exporter removes only material that is not appropriate for portable continuity:\n\n- thinking or reasoning blocks\n- extension state records such as `custom` and `label` entries\n- known Pi settings events such as model changes\n- empty messages left after removing thinking or state-only entries\n\n## Compaction behavior\n\nPi compaction is append-only: compacting a session appends a summary entry but does not delete the earlier raw messages from the session file. Because this package exports the active branch path, handoffs can still include pre-compact user and assistant messages. Compaction summaries are preserved as `context` records so a receiving agent can see that compaction occurred, but they are not the only source of continuity.\n\n## CLI for explicit snapshots\n\nThe CLI is for tests and explicit normalized snapshots. It cannot export the current Pi session because that requires the live extension context.\n\n```bash\nnode packages/handoff-pi-agent/scripts/extract-handoff.ts \\\n  --input shared/handoff/fixtures/simple-transcript.json \\\n  --cwd \"$PWD\" \\\n  --out .handoffs/cli-test \\\n  --add-gitignore=false\n```\n\n## Development note\n\nThis package includes a package-local copy of the shared implementation under `shared/handoff/` so the npm tarball is self-contained. Keep those files synchronized with the repo-level canonical source in `shared/handoff/` before publishing.\n","readmeFilename":"README.md"}