@huntye1/pi-auto-session-name

简体中文

A non-blocking, privacy-conscious Pi extension that generates a short name for a new session after its first successful task.

Installation

Requires Pi 1.1.0 or a compatible later version and Node.js >=22.19.0.

pi install npm:@huntye1/pi-auto-session-name

Run /reload in an active Pi session and use /new to start a new session. For local development:

pi --extension ./packages/pi-auto-session-name/extensions/auto-session-name.ts

The package does not rewrite Pi settings, register model-callable tools, alter the main conversation prompt, or create background processes. Do not enable another automatic naming extension at the same time.

Default behavior

• Attempts automatic naming once, after the first successful task in a new persistent TUI or RPC session.
• Uses the current session model by default; it does not silently select another service or fall back across providers.
• Calls ctx.modelRegistry.streamSimple() without injecting tools or messages into the main transcript.
• Does not await the naming promise from agent_settled, so the next turn can begin while naming is pending.
• Reads at most 800 Unicode characters from the original request and 400 from the latest final answer; intermediate tool narration is ignored.
• Limits titles to 24 Unicode code points by default and follows the user's language unless configured otherwise.
• Uses an isolated session-affinity ID and cleans up provider resources after the request.
• Applies a 10-second end-to-end timeout by default, including authentication. There are no automatic retries or scheduled renames.
• Does not automatically rename existing, resumed, reloaded, forked, temporary, print, or JSON sessions.
• Cancels or invalidates pending naming when the session is renamed, cleared, replaced, reloaded, shut down, or moved to another branch.
• A normal follow-up turn on the same branch does not cancel naming; context edits and compaction invalidate the old snapshot.

Commands

Explicit commands wait for their own result, while automatic naming remains non-blocking. Without an interactive UI, the extension will not replace an existing name. If no suitable request or successful final answer is available, naming is skipped.

/auto-name uses the original request (up to 800 characters), the latest distinct request (up to 400), and the latest final answer (up to 400). A failed automatic attempt is not retried unless requested explicitly.

Configuration

Only the user configuration is read:

${PI_CODING_AGENT_DIR:-~/.pi/agent}/auto-session-name.json

Project configuration is deliberately ignored so a repository cannot change the naming provider. No configuration is required.

{
  "enabled": true,
  "mode": "llm",
  "model": "",
  "language": "auto",
  "timeoutMs": 10000,
  "maxTitleChars": 24
}

Manual configuration changes take effect after /reload. /auto-name model ... validates and atomically updates the user config immediately. Unknown fields, invalid values, non-regular files, files larger than 8 KiB, and malformed JSON disable naming safely. Credentials are not supported in this config; authentication remains managed by Pi.

Privacy and limitations

• Ignores tool results and arguments, thinking, images, system/custom messages, branch summaries, and compaction summaries.
• Reads only the active branch and respects context_edit replacements and omissions.
• Heuristically redacts private keys, common API keys, Bearer/Basic credentials, Cookie/Authorization values, JWTs, sensitive assignments, and URL credentials/query strings/fragments.
• Removes Markdown code blocks and Pi <file> attachment blocks. Code pasted as ordinary prose may still enter the excerpt.
• Filters and redacts bounded input before truncation: up to 8,192 UTF-16 code units and 128 content blocks per message, and up to 2,048 active-branch entries.
• Sends only an isolated system instruction and JSON excerpt to the selected model, with no tools. Suspicious secrets and control/bidirectional characters in model output are rejected.
• Heuristic redaction is not DLP and cannot guarantee detection of every secret. LLM mode sends a small excerpt to the selected provider. Use an approved provider, or choose local mode/disable the extension when no additional transmission is acceptable.
• Does not upload telemetry or persist excerpts and server error text. Session names are stored in Pi's session JSONL and may appear in titles, footers, and resume lists.
• The custom pi-auto-session-name/v1 entry stores only attempt ownership, outcome, duration, and numeric usage—not excerpts or credentials.
• Naming creates an additional model call. Its latest cost is shown by /auto-name status and is not included in the main session footer.

Development and publishing

npm run check
npm run pack:check
npm publish --access public

check includes type-checking, unit tests, and an offline integration test against the real Pi SDK using a fake provider. The published package contains only the extension entry point, source, both READMEs, license, and package metadata. Pi host APIs are optional peer dependencies supplied by the host.

License

MIT