npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@protokol11/pi-session-transfer

v0.1.1

Published

Lossy context compaction replaced with a typed handoff document and session rotation for pi agents.

Readme

@protokol11/pi-session-transfer

Pi extension that replaces lossy context compaction with a typed handoff document and a session rotation.

Context windows degrade before they overflow: past roughly 150k tokens of accumulated conversation the model enters a measurable quality drop ("dumb zone"). Pi's built-in compaction answers this with a summarised transcript — a lossy text dump with no type contract, no verification, and no way to check what was lost. This extension answers it with a handoff: a typed document the agent authors (via the hands-off skill), that the child session is seeded from, so the session rotates on the document instead of on a guess. See the handoffs skill family for the document format.

Scope: packaging (/transfer), explicit rotation (/transfer-resume), and optional gated auto-rotation. Non-scope: summarising transcript history (that is compaction), and any session migration across machines.

Why

  • Rotation triggers at min(0.70 × contextWindow, 150_000) tokens — the same degradation threshold used across this repo's lifecycle tooling — before quality collapse, not after.
  • The handoff lives under .docs/handoff/ with frontmatter sessionId and next_session_mode. That is the contract: /transfer-resume finds the newest handoff carrying the current session id and reuses it, no repackaging.
  • The rotation is mechanical: newSession with the handoff seed, carrying model and thinking level to the child through a module-scoped queue (the parent context is stale after replacement).
  • Every step logs to .pi/session-transfer.log; every guard fails silent so a broken transfer never breaks the session it serves.

Prerequisites

None further.

Install

npm install @protokol11/pi-session-transfer

Or add the package to packages in your pi settings. See pi.dev for the extension API. Expected result: pi loads /transfer and /transfer-resume at next start.

Usage

One worked path — package and resume:

  1. Run /transfer. The extension injects an instruction; the agent writes a handoff via hands-off and a status via update-docs, then calls request_transfer with the handoff path. No new session is created.
  2. Run /transfer-resume. The extension reuses the handoff for this session (or writes one first), then rotates: a fresh session starts, seeded with the handoff and carrying the parent's model and thinking level.

Optional automatic path (off by default):

  • SESSION_TRANSFER_AUTO=1 arms two automatic channels: an idle gate (usage ≥ threshold and no user input) confirmed by a second model acting as observer (SESSION_TRANSFER_OBSERVER_MODEL, default deepseek/deepseek-flash), and an agent tool begin_transfer once the warn band is hit. Non-explicit channels always ask the user before rotating.

Commands

| Command | Effect | |---|---| | /transfer | Package the session into handoff + status; no rotation | | /transfer-resume | Reuse-or-produce a handoff, then rotate and auto-start the child | | /transfer-rotate | Internal; dispatched by the extension once a transfer is armed | | begin_transfer (tool) | Agent-initiated transfer at warn band; requires SESSION_TRANSFER_AUTO=1 | | request_transfer (tool) | Arm the rotation with a handoff file path |

Configuration

| Variable | Type | Default | Effect | |---|---|---|---| | SESSION_TRANSFER_AUTO | flag | off | Enable idle gate and begin_transfer | | SESSION_TRANSFER_DISABLE | flag | off | Hard off-switch for all transfer paths | | SESSION_TRANSFER_AUTO_RESUME | flag | off | Auto-start the child on non-explicit channels too | | SESSION_TRANSFER_OBSERVER_MODEL | provider/model | deepseek/deepseek-flash | Observer model for idle-gate confirmation | | CONTEXT_GUARD_WARN_TOKENS | number | 0.70 × window | Absolute warn band override | | CONTEXT_GUARD_CRITICAL_TOKENS | number | derived | Absolute critical band override |

Troubleshooting

  • Symptom: begin_transfer returns "Automatic transfer is off." — Cause: SESSION_TRANSFER_AUTO is unset. — Fix: set it, or use /transfer / /transfer-resume.
  • Symptom: rotation never fires after request_transfer. — Cause: a non-explicit channel awaits user confirmation; no answer means no rotation. — Fix: run /transfer-resume, which rotates immediately.
  • Symptom: "rotation failed" notification. — Cause: see .pi/session-transfer.log in the project directory.

Contributing

File issues in the agent-governance monorepo (source under lifecycle/session-transfer). Run the checks there; this package is a publish copy.

License

MIT — see LICENSE.