Pi

Install the native package, inject context at before_agent_start, and flush captured Sources at lifecycle boundaries.

Version-gated: the package runtime requires Node >=22.19. Development declares Pi ^0.82.0; the lockfile and real-CLI package-load E2E use Pi 0.82.1. That is compatibility evidence, not a formal host-version range. Package load is Supported within that test boundary; the full real-host recall chain is Not validated.

Maturity and installation

Pi uses the source package powercontext-pi version 0.0.2. It contains an extension and a bundled project-context Skill. The current setup path installs the package from the selected PowerContext Git ref or a local checkout; installation by published npm package name is currently Unsupported.

powercontext setup pi --source oceanbase/powercontext --ref master
powercontext server run
powercontext doctor
powercontext doctor pi
pi

Setup verifies the package name, extension, and bundled SKILL.md, runs pi install <package-directory>, removes superseded user-scoped PowerContext registrations only after success, and then runs doctor.

Remote checkout materialization uses staging and restores the previous checkout if the staging swap fails. A later pi install failure has no transactional checkout rollback. Source credentials and clone output are not printed.

powercontext doctor pi checks the Pi executable, pi list, and an installed manifest named powercontext-pi. It does not check Server readiness, extension activation, bundled-Skill discovery, package or host version, or a model turn. The general powercontext doctor covers the Server separately.

Minimal usage

Start a new Pi process after installation or environment changes. Then keep automatic and explicit paths separate:

1. Submit a normal coding prompt. before_agent_start may recall temporary context and capture the trimmed prompt as a Source.
2. Use the 13 native Memory and Handoff tools for exact reads or supported durable operations.
3. Use /pc, /pc doctor, and /pc search <query> for diagnostics and explicit checks. /pc doctor calls the configured Server; it is different from powercontext doctor pi.

Invalid local Pi configuration keeps the host running but registers no tools or /pc; its hooks become no-ops. The bundled Skill describes tool usage, but real Pi Skill discovery is Not validated because the package-load E2E runs with --no-skills.

Execution flow

before_agent_start
→ trim prompt; skip an empty prompt
→ resolve and cache Scope by cwd
→ prepare and strictly validate context
→ capture eligible prompt Source and receive position
→ optionally flush through position, or retain it as pending
→ append ready untrusted context to systemPrompt

agent_end
→ start pending flush without waiting

session_before_compact / session_before_switch / session_shutdown
→ await pending flush within a bounded closing budget

Prepare and capture share one turn HTTP-budget signal but handle failure independently. Recall failure does not normally suppress capture. Capture failure does not erase valid recalled context. Automatic failures are fail-open and do not stop the Pi turn.

agent_end only starts flush and returns. No callback captures the assistant response or records Task Outcome. Pi’s session_shutdown event is not a Claude Code Stop Hook.

Scope

Pi derives Scope before each scoped Server operation:

1. Use non-empty POWERCONTEXT_PI_SCOPE_ID, hashing values over 256 characters.
2. Otherwise resolve the Git top-level and normalize remote.origin.url to a git: Scope.
3. Fall back to local:sha256(<absolute-project-root>).

Git normalization removes credentials and trailing .git noise. It accepts common HTTP, HTTPS, SSH, Git, and SCP-style remotes. Resolved promises are cached by cwd; failed resolutions are evicted. A tool caller cannot replace the derived scope_id with its own value.

Pi has no Codex- or Claude-style Workstream picker or Git-private Scope binding. That path is Unsupported.

Injection

PreparedContext is accepted only when it has exactly schema, status, content, and content_bytes; uses powercontext.prepared-context.v1; obeys empty/ready rules; reports the exact UTF-8 byte count; and stays within the configured content bound.

The extension appends ready content to Pi’s existing systemPrompt under a host-supplied, untrusted-historical-evidence label. Empty or invalid content is not injected. This is transient augmentation, not a transcript synchronization or a new Source, Memory, or Artifact.

Capture

Automatic capture is on by default. Source identity hashes Scope, normalized session identity, derived turn number, and the trimmed prompt. Metadata is exactly origin, event, cwd, session_id, and turn_id. The turn number comes from the current branch’s user-message count; the branch itself is not stored.

Capture skips content when disabled, when the UTF-8 prompt exceeds 200,000 bytes, or when the prompt matches a private key, credential assignment, Bearer value, or known token shape. The dedicated multibyte boundary case is Not validated because the current oversized test uses ASCII.

A capture becomes pending only when the response contains an integer position >= 1. Source acceptance, processing position, flush completion, Candidate generation, Review, and committed Memory remain separate stages.

Flush

The pending flusher retains the greatest unprocessed position per Scope. A lower position cannot reduce it. It clears an entry only after current_cursor >= position. Concurrent flush calls share one in-flight promise, and a higher position recorded during a flush cannot be cleared by the older completion.

Defaults are: immediate flush off, at most four calls, a 4,000 ms turn HTTP budget, and a lifecycle closing budget capped at 1,000 ms. With POWERCONTEXT_PI_FLUSH_ON_CAPTURE=true, capture retries immediate transient errors; exhaustion records the position for a later boundary.

At a lifecycle boundary, a thrown Server/transport error stops that Scope’s current loop but leaves it pending for a future event. Cursor-behind responses retry up to the call limit. The flusher continues with other Scopes and never claims that Memory exists.

Compaction and immediate-failure-to-compaction retry have direct tests. Multiple Scopes, in-flight coalescing, a permanently lagging cursor, and a higher position arriving during flush are Not validated by direct Pi tests.

Tools, commands, and permission

Pi registers exactly 13 model tools. Read/non-durable tools are pc_search, pc_memory_list, pc_memory_get, pc_prepare_context, pc_handoff_prepare, pc_handoff_finalize, and pc_handoff_continue. Confirmation-gated mutations are pc_remember, pc_memory_revise, pc_memory_retire, pc_capture_source, pc_handoff_activate, and pc_handoff_commit.

/pc supports no-argument diagnostics plus doctor, search, remember, flush, and stats. It has no generic operation command, Candidate Review command, Handoff command, or Task Outcome command.

A gated mutation proceeds only after interactive confirmation. No UI returns stable confirmation_required; user denial returns cancelled; UI failure returns unavailable. None of those paths sends the write request. /pc remember and /pc flush use the same boundary. Explicit operations replace caller Scope, reject secret-bearing payloads, and return stable model-visible errors.

The no-UI contract and helper behavior are unit-tested. Actual real-host display, denial, and missing-UI behavior are Not validated by a host-process test.

Transport

The default Server is http://127.0.0.1:8000. Plain HTTP is allowed only for localhost and loopback addresses; remote Servers require HTTPS. Base URLs with credentials, query, fragments, or non-HTTP schemes are rejected.

POWERCONTEXT_PI_AUTHORIZATION is sent as the complete Authorization value. Redirects are handled manually and rejected, so credentials are not forwarded. Responses are capped at 1 MiB, and successful bodies must contain valid JSON. Per-request timeout and the shared turn budget are separate limits.

Unsupported vs Not validated

State	Capability	Practical consequence
Version-gated	Node runtime >=22.19	Do not install the package on an older runtime.
Unsupported	published npm-name installation; managed Skill export or Pi external-Skill scan target; automatic assistant/transcript capture; automatic Task Outcome; Workstream picker/Git-private binding; MCP transport; starting or embedding the Server	Use source setup and native HTTP tools, and run the Server separately.
Unsupported on Pi-native surface	Explicit Task Outcome, Work Contract, acknowledgement, Experience/Skill generation, Candidate Review, external-Skill, generic API, and Handoff-report operations	Generated operation descriptors do not make these Pi tools or commands. Use another supported interface or extend the host.
Not validated	Formal Pi host range or compatibility beyond locked 0.82.1	Treat ^0.82.0 as development intent, not a support promise.
Not validated	Full real-Pi prepare/injection/model chain; bundled-Skill discovery; real-host confirmation behavior	Package install/load and /pc registration do not prove these paths.
Not validated	Callback execution for agent_end, switch, and shutdown; multibyte Source boundary; pending-flusher concurrency edges	Keep these claims at implementation evidence until direct tests exist.

The real package E2E installs the directory with locked Pi 0.82.1, starts offline RPC with no session and no Skills, and checks that /pc is registered. It does not create a session, call a model or Server, exercise recall, or load the bundled Skill.

Negative experiments

Run these before treating a Pi deployment as complete:

• Break local configuration and confirm Pi keeps running with no PowerContext tools, command, or hook effects.
• Stop the Server and confirm the turn continues without injected context.
• Make prepare fail while capture succeeds; reverse the failures and retain valid recalled context.
• Submit a blank, secret-shaped, disabled-capture, or over-limit prompt and verify the expected no-op or no-capture path.
• Make immediate flush fail, trigger compaction, and confirm the pending position is retried.
• Record lower and higher positions during flush; only current_cursor >= highest-position may clear the entry.
• Keep the cursor behind position and confirm bounded work ends without claiming Memory exists.
• Run a mutation without UI and confirm confirmation_required with no HTTP write; decline through UI and expect cancelled.
• Pass a different scope_id to a tool and confirm the derived Scope replaces it.
• Return a redirect or oversized/non-JSON response and confirm the client rejects it.
• Use plaintext on a non-loopback host and confirm configuration is rejected; use HTTPS remotely.
• Inspect tools and commands and confirm Task Outcome, Candidate Review, Experience/Skill generation, and generic API surfaces are absent.

Configuration defaults

Key	Default	Meaning
POWERCONTEXT_PI_BASE_URL	http://127.0.0.1:8000	Running Server
POWERCONTEXT_PI_SCOPE_ID	unset	Explicit Scope; otherwise Git / path
POWERCONTEXT_PI_AUTHORIZATION	unset	Complete Authorization header
POWERCONTEXT_PI_CAPTURE_PROMPTS	true	Capture the current user prompt
POWERCONTEXT_PI_MAX_BYTES	8000	Recall budget, clamped to 512–32768
POWERCONTEXT_PI_REQUEST_TIMEOUT_MS	1000	Per-request HTTP timeout
POWERCONTEXT_PI_HTTP_BUDGET_MS	4000	Total prepare/capture budget for one turn
POWERCONTEXT_PI_FLUSH_ON_CAPTURE	false	Test-only: wait for flush after capture

Do not put credentials in POWERCONTEXT_PI_BASE_URL. Use HTTPS outside loopback. Disable capture when the current work must not become Source evidence:

export POWERCONTEXT_PI_CAPTURE_PROMPTS=false
pi

Finish the shared check on this host

What should happen after the OpenAPI contract changes?

1. Store the answer in a stable Scope with pc_remember or /pc remember. With a UI, pass ui.confirm first.
2. Open a new session and ask the same question.
3. The recall must include a Citation and appear only at the end of systemPrompt, in the block that starts with PowerContext host-supplied context.
4. Stop the Server and ask an ordinary coding question. Recall, capture, and flush must not block the agent.
5. With the Server still down, run pc_remember again. A UI session must show the failure. Without a UI, the stable result is confirmation_required. Do not write silently.

Completion checklist

Treat the integration as complete only when these results are observable:

• PowerContext and the Pi package come from the same reviewed Git ref.
• Node is >=22.19.
• Pi 0.82.1 is recorded as compatibility evidence, not a formal minimum or complete 0.82.x promise.
• Both powercontext doctor and powercontext doctor pi pass for their separate boundaries.
• pi list points to a package manifest named powercontext-pi, and a new Pi process exposes /pc.
• /pc doctor reaches the intended Server.
• Scope is the explicit override, sanitized Git identity, or local-root hash.
• Caller Scope cannot replace it.
• Valid PreparedContext is strictly checked and appended to the existing systemPrompt as untrusted evidence.
• Capture stores the trimmed prompt with cwd, session_id, and derived turn_id, but no project or branch field.
• Secret and over-200,000-byte prompts are not captured.
• Pending work clears only at current_cursor >= position and stays within the call and closing budgets.
• Every gated tool and /pc mutation confirms or returns a stable no-write error.
• Remote transport uses HTTPS, rejects redirects, and enforces JSON and response-size bounds.
• Source, position, flush, Candidate, Review, and Memory remain distinct stages.
• Package-load evidence stays separate from bundled-Skill discovery and a full real-host turn.
• Pi-native Task Outcome and the other absent surfaces remain Unsupported.
• Bundled Skill presence does not imply managed Skill export.

Continue with Extend hooks.