pi-session-header

简体中文

Inject the current Pi session ID into LLM provider HTTP requests. Gateways can use this identifier for routing, session affinity, or cache reuse. The extension only adds the identifier; the gateway decides how to use it.

x-pi-session-id: <current-pi-session-id>

Compatibility

• Targets Pi 0.85.0 and later, using the official before_provider_headers hook.
• Type-checked against Pi 0.85.0 and 1.4.0. SDK and real CLI tests have passed on 0.85.0, 1.0.0, and 1.4.0; CI covers these versions. Future Pi releases depend on the hook continuing to support in-place header mutation.
• Node.js 22.19+ (Pi's requirement). No runtime npm dependencies and no build step.
• Applies to every provider that invokes Pi's HTTP header hook. There is no provider-name filter. Custom transports that bypass the hook cannot be injected; WebSocket frames and non-HTTP transports are outside this extension's scope.
• Local HTTP integration tests cover OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Google Generative AI, including tool follow-up requests. Other providers are not individually verified against live services.

Install

Install from npm:

pi install npm:pi-session-header
pi install npm:pi-session-header@0.1.0

Git installation (after the source is pushed):

pi install git:github.com/or-less/pi-session-header
pi install git:github.com/or-less/pi-session-header@v0.1.0

Private/internal Git sources use the same syntax, such as git:git.example.com/team/pi-session-header, or an SSH source such as ssh://git@git.example.com/team/pi-session-header.git. Git credentials are managed by Git. Tags must exist before using a tagged source.

pi install saves a personal/global package declaration by default. Add -l for a project installation. Restart Pi or run /reload after installing or editing.

pi list
pi update npm:pi-session-header
pi remove npm:pi-session-header

For a Git installation, use its Git source in update and remove. An explicitly pinned version/tag stays pinned; remove that source and install a new pin to upgrade. Use pi update <source> across supported Pi versions. The meaning of bare pi update changed between releases.

Configuration

Set variables before starting Pi. Configuration is read when the extension loads; restart Pi after changing the launching shell's environment.

Boolean values accept true/false, 1/0, yes/no, and on/off, ignoring case and surrounding whitespace. Other values are rejected. Header names must be valid HTTP tokens; whitespace is rejected. Names are normalized to lowercase.

PI_SESSION_HEADER_NAME=x-custom-session-id pi
PI_SESSION_HEADER_ENABLED=false pi
PI_SESSION_HEADER_DEBUG=true pi

Choose the header name required by your gateway. Gateways do not necessarily recognize x-pi-session-id. This version always applies to all providers; the optional provider whitelist is not implemented.

Authentication headers (including Authorization, Proxy-Authorization, common API-key headers and cookies) and transport headers (including Host, Content-Type, and Content-Length) are blocked as configuration targets. Invalid configuration prints a clear diagnostic and disables injection while Pi can continue normally. Debug logs contain no session IDs, credentials, prompts, request bodies, or responses.

Session behavior

The extension reads ctx.sessionManager.getSessionId() for each hook invocation. It never generates or caches a session ID.

Only the configured header is added or replaced, including differently cased spellings of that header. Other headers, payloads, and responses are preserved. Provider retries may reuse headers without re-firing the hook. Pi's print mode still uses streaming HTTP internally; the extension does not change this.

Development and verification

npm ci --ignore-scripts
npm run check
npm pack --dry-run
pi -e ./extensions/session-header.ts

For a persistent local installation, run pi install /absolute/path/to/pi-session-header. No compilation is necessary: Pi loads the TypeScript entry from the package manifest.

npm run typecheck checks the current and minimum supported SDK declarations. npm test checks configuration, header preservation, privacy, and real SDK session lifecycle behavior. npm run test:e2e starts a loopback HTTP server and runs the actual Pi 0.85.0 and current CLI with isolated configuration and session directories. It requires local socket/process permissions, no provider credentials, and no paid model calls. It also verifies pi install, pi list, and pi remove for local packages. See VALIDATION.md in the source repository for checked versions, results, and test dependency audit notes.

Release

Source: or-less/pi-session-header. See CHANGELOG and MIT License.

Before publishing, verify npm name ownership (npm view pi-session-header), update the version/changelog, run npm run check and npm pack --dry-run, and review the tarball for private files. An npm 404 means the name is not currently published; it does not reserve the name or guarantee publishing permission.

The publish workflow is manual only. Configure npm trusted publishing for this repository and publish.yml, create a GitHub npm environment with required reviewers, push a v<package-version> tag, then manually run the workflow on that tag. The workflow verifies the tag/version, checks the package, and publishes with provenance. No credentials belong in source. Local manual publication, when authorized, is:

npm publish --access public

Official references: Pi 0.85.0 extension API, Pi packages.