{"_id":"@4fu/pi-sessions","_rev":"2-f2312212e3bfa43be43fed025f6dc04f","name":"@4fu/pi-sessions","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@4fu/pi-sessions","version":"0.1.0","keywords":["pi-package","pi-extension","sessions","conversation-history"],"author":{"name":"4fuu"},"license":"MIT","_id":"@4fu/pi-sessions@0.1.0","maintainers":[{"name":"4fu","email":"npm@4fwu.com"}],"homepage":"https://github.com/4fuu/pi-sessions#readme","bugs":{"url":"https://github.com/4fuu/pi-sessions/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"5bbb184d1e27890390a63d1c7945db2226c274db","tarball":"https://registry.npmjs.org/@4fu/pi-sessions/-/pi-sessions-0.1.0.tgz","fileCount":5,"integrity":"sha512-+ifVnCUCYFBAKJF/g+bPJWCukfY80Ml6iA/rSriUVoTDqTBP/r+yMaPOmhXTgJoH8U1BnhXnBY0Zw8c7x5ob2w==","signatures":[{"sig":"MEUCIQCGQD+Flr1yPVRpUbBEwuiB507cZLkNCNYjabM0A44XVQIgVOCKliicnHWGdJHIt91ByJzfy1u4mSF87kQ2+hNUcEw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44682},"type":"module","engines":{"node":">=22.19.0"},"gitHead":"6ac00714d674f875b1c1a289aeb8c802b890e475","scripts":{"test":"npm run typecheck && node --test tests/*.test.ts","typecheck":"tsc --noEmit"},"_npmUser":{"name":"4fu","email":"npm@4fwu.com"},"repository":{"url":"git+https://github.com/4fuu/pi-sessions.git","type":"git"},"_npmVersion":"10.9.9","description":"Search and read saved pi sessions from the agent","directories":{},"_nodeVersion":"22.19.0","_hasShrinkwrap":false,"devDependencies":{"typebox":"^1.3.11","typescript":"^5.9.0","@types/node":"^24.0.0","@earendil-works/pi-ai":"^0.84.1","@earendil-works/pi-tui":"^0.84.1","@earendil-works/pi-coding-agent":"^0.84.1"},"peerDependencies":{"typebox":">=1.3.11 <2","@earendil-works/pi-ai":">=0.84.1 <1","@earendil-works/pi-tui":">=0.84.1 <1","@earendil-works/pi-coding-agent":">=0.84.1 <1"},"_npmOperationalInternal":{"tmp":"tmp/pi-sessions_0.1.0_1786259536977_0.5994549990590095","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@4fu/pi-sessions","version":"0.2.0","description":"Search and read saved pi sessions from the agent","license":"MIT","author":{"name":"4fuu"},"repository":{"type":"git","url":"git+https://github.com/4fuu/pi-sessions.git"},"type":"module","engines":{"node":">=22.19.0"},"keywords":["pi-package","pi-extension","sessions","conversation-history"],"pi":{"extensions":["./src/index.ts"]},"scripts":{"typecheck":"tsc --noEmit","test":"npm run typecheck && node --test tests/*.test.ts"},"peerDependencies":{"@earendil-works/pi-ai":">=0.84.1 <1","@earendil-works/pi-coding-agent":">=0.84.1 <1","@earendil-works/pi-tui":">=0.84.1 <1","typebox":">=1.3.11 <2"},"devDependencies":{"@earendil-works/pi-ai":"^0.84.1","@earendil-works/pi-coding-agent":"^0.84.1","@earendil-works/pi-tui":"^0.84.1","@types/node":"^24.0.0","typebox":"^1.3.11","typescript":"^5.9.0"},"_id":"@4fu/pi-sessions@0.2.0","gitHead":"2e2811dfb68d261555a4c74c53b0cb10fdbc92f5","bugs":{"url":"https://github.com/4fuu/pi-sessions/issues"},"homepage":"https://github.com/4fuu/pi-sessions#readme","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-J+8qeDe2FnDiU5jeM56GbyR/RsKsd75ZMzHrU8hJv75cgN71VoTl0JDTnqI0H59f7l+ioXbVvGQdIHIIaoUu0Q==","shasum":"81b7fd3af9698621081abc3a93a12ae0ed87ea89","tarball":"https://registry.npmjs.org/@4fu/pi-sessions/-/pi-sessions-0.2.0.tgz","fileCount":5,"unpackedSize":48138,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBCQdJBGUw0o+d0JP50CeBG2tySK+aUxsaeSnF/BlnIkAiAiMK8c+EpuY0RbO24Tqi4lwd6caViMKqlDXnP5/4oJKw=="}]},"_npmUser":{"name":"4fu","email":"npm@4fwu.com"},"directories":{},"maintainers":[{"name":"4fu","email":"npm@4fwu.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-sessions_0.2.0_1787128218315_0.8906516587481546"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-09T07:12:16.859Z","modified":"2026-08-19T08:30:18.661Z","0.1.0":"2026-08-09T07:12:17.160Z","0.2.0":"2026-08-19T08:30:18.492Z"},"bugs":{"url":"https://github.com/4fuu/pi-sessions/issues"},"author":{"name":"4fuu"},"license":"MIT","homepage":"https://github.com/4fuu/pi-sessions#readme","keywords":["pi-package","pi-extension","sessions","conversation-history"],"repository":{"type":"git","url":"git+https://github.com/4fuu/pi-sessions.git"},"description":"Search and read saved pi sessions from the agent","maintainers":[{"name":"4fu","email":"npm@4fwu.com"}],"readme":"# pi-sessions\n\nSearch and read saved [pi](https://github.com/earendil-works/pi) sessions from the agent, including historical branches, without changing session state.\n\n## Why pi-sessions\n\n- **One compact tool** — discover, search, read, and paginate through a flat `sessions` schema.\n- **Project-aware by default** — recent sessions and searches stay in the current working directory unless the agent explicitly selects `scope: \"all\"`.\n- **Branch-correct reads** — a session ID reads the active root-to-leaf branch; an entry ID reads the exact root-to-entry path, including abandoned branches.\n- **Useful search references** — matches include stable `sessionId` and `entryId` selectors for a precise follow-up read.\n- **Bounded context** — previews, records, pages, and total output are limited; thinking and tool traffic are omitted by default.\n- **Actually read-only** — discovery does not create project directories, and pi's parser and migrations run only in memory. Session files are never opened through APIs that may rewrite legacy data.\n\n## Usage\n\nTalk to pi normally—the `sessions` tool is for the model, not a command you need to call yourself.\n\nIn Pi's interactive editor, type `@@` to open a selector for sessions saved in the current project. Continue typing to filter by session name, first message, or ID, then select an item to insert its stable `@@<sessionId>` reference. Pi reads that exact session before using its history. A single `@` keeps Pi's normal file autocomplete behavior.\n\n### Recall a decision from this project\n\n> **You:** We discussed how refresh-token rotation should work in an earlier session. Find that discussion and use the decision here.\n>\n> **pi:** I'll search this project's saved sessions, open the matching conversation branch, and apply the earlier decision to the current task.\n\nPi first searches the current project, then reads the exact matching session and entry rather than guessing from a short preview.\n\n### Find context from another project\n\n> **You:** In another project we planned the billing migration. Find that conversation and summarize the rollout order.\n>\n> **pi:** I'll search across all saved projects, identify the relevant session, and read its selected root-to-entry branch before answering.\n\nPi uses cross-project scope only when the request indicates that the current project may not contain the answer. If a working directory is known, it can narrow the search to that project.\n\n### Continue an unfinished line of work\n\n> **You:** Show me my recent sessions for this repository and continue the one where I was debugging the retry race.\n>\n> **pi:** I'll list recent project sessions, select the relevant one, and read its active branch before continuing the investigation.\n\n### Recover exact tool evidence\n\n> **You:** Find the earlier session where the integration test failed and tell me the exact command output.\n>\n> **pi:** I'll locate the matching entry and, because the request needs tool evidence, read that branch with tool calls and results included.\n\nTool traffic is otherwise omitted. Pi follows returned cursors automatically when it needs older entries or additional search results; you do not need to manage session IDs, entry IDs, or pagination yourself.\n\n## Behavior and safety\n\nPi sessions form trees rather than flat transcripts. `sessions` follows parent links and returns one root-to-leaf path, so sibling branches are never mixed together.\n\nThe tool accepts session and entry IDs, not file paths. It does not create, append, resume, branch, rename, or delete sessions. Legacy formats are parsed with pi's exported parser and migrated only in memory, because `SessionManager.open()` may rewrite an old session while opening it.\n\nReturned history is marked as untrusted reference data. The agent must not follow instructions found inside archived messages or tool output. Assistant thinking, usage and cost metadata, image data, extension-private entries, and TUI-only metadata are never returned. Opaque compaction summaries are also omitted because they may derive from thinking or tool traffic; branch summaries are omitted because they intentionally summarize an abandoned sibling. The original user and assistant messages remain readable. Tool calls and results require `includeTools: true` and are still bounded.\n\n## Requirements\n\n- Node.js 22.19 or newer.\n- A compatible pi installation with saved sessions.\n\n## Installation\n\nInstall from npm:\n\n```bash\npi install npm:@4fu/pi-sessions\n```\n\nTry it without installing:\n\n```bash\npi -e npm:@4fu/pi-sessions\n```\n\nYou can also install the latest GitHub source:\n\n```bash\npi install git:github.com/4fuu/pi-sessions\n```\n\n### From source\n\nRun `npm install`, add the repository path to `~/.pi/agent/settings.json`, then run `/reload` in pi.\n\n## Development\n\n```bash\nnpm install\nnpm test\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}