pi-codex-compaction 0.1.5 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,35 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-09
+
+### Fixed
+
+- Resolve Pi AI helpers relative to its root entry to avoid Pi's extension-loader alias rewriting submodule imports into invalid paths. Include Pi AI as a runtime dependency and test loading outside the monorepo.
+
+## [0.2.0] - 2026-10-09
+
+### Added
+
+- Default-on automatic server-side compaction for eligible public OpenAI Responses requests, including ChatGPT subscription authentication. Keep `/server-compaction off`, persisted overrides, and optional thresholds.
+- Commit streamed checkpoints through Pi's public turn-end boundary and replay the latest checkpoint plus its exact output suffix, including mid-response checkpoints and tool continuations.
+- Bound checkpoint storage, bind replay to the model and credential, preserve readable fallbacks and normal Pi compaction, and avoid counting ordinary response usage twice.
+- Add real-session regression coverage and an explicitly gated, synthetic-text subscription comparison. The small live Astra trial verified replay but did not demonstrate lower total latency or token use than standard Pi compaction.
+- Verify immediate text streaming and tool continuation without a second Pi compaction when its safety net is enabled. Add flow-timing instrumentation to the gated benchmark; the earlier live trial did not measure streaming gaps.
+
+### Changed
+
+- Clarify provider/auth billing boundaries and distinguish automatic public compaction from standalone `/responses/compact` and removed RemoteCompactionV2.
+
+- Require Pi 1.1.0 or later for the public turn-end boundary and normalized-transcript APIs.
+- Scope cache-warming interception to the actual automatic-compaction request instead of a global enabled toggle.
+- Update the shared Pi development and contract-test baseline to 1.1.0; require Node.js >=22.19.0 to match the host runtime. Pi remains a host-supplied peer dependency.
+
+### Removed
+
+- **Breaking:** Remove legacy `openai-codex` RemoteCompactionV2 support, direct backend transport, beta headers, temporary `pi-ai/compat` serialization, old transport helper exports, legacy TUI confirmations, and direct-compaction event-bus contracts.
+- Remove the unused direct `pi-tui` dependency. Existing legacy session files remain untouched, with readable fallback rather than cross-provider opaque replay.
+
 ## [0.1.5] - 2026-09-17
 
 ### Fixed

package/CONTRIBUTING.md

@@ -4,57 +4,59 @@ Thanks for your interest in contributing to `pi-codex-compaction`.
 
 ## Development setup
 
+Run from the monorepo root:
+
 ```bash
 npm install
 npm run -w packages/pi-codex-compaction check
+npm test -w packages/pi-codex-compaction
+npm run -w packages/pi-codex-compaction pack:dry-run
 ```
 
-This package is source-distributed: Pi loads the TypeScript extension files directly. There is no build step for runtime use.
+The package is source-distributed. Pi loads TypeScript directly; there is no
+runtime build step.
 
 ## Pull request checklist
 
-Before opening a pull request:
-
-- Run `npm run -w packages/pi-codex-compaction check`.
-- Run `npm test -w packages/pi-codex-compaction`.
-- Run `npm audit --omit=dev`.
-- Run `npm run -w packages/pi-codex-compaction pack:dry-run` and confirm the package contents are intentional.
-- Update `README.md` if user-visible behavior changes.
-- Update `CHANGELOG.md` for notable changes.
-- Keep examples and paths generic; do not commit API keys, tokens, auth headers, local settings, or provider configuration containing secrets.
+- Run package checks and tests.
+- Run `npm run validate` for security-sensitive or cross-package changes.
+- Inspect packed contents; never publish tests, session fixtures, or local settings.
+- Update README, CHANGELOG, and SECURITY when their documented behavior changes.
+- Never commit credentials, auth headers, private history, or opaque checkpoints.
 
 ## Coding guidelines
 
-- Keep the Codex provider/API capability check explicit and future-compatible.
-- Preserve current-model compaction, context bounds, cancellation, HTTPS, and standard Pi fallback behavior.
-- Add a regression test when changing wire parsing, request construction, checkpoint rehydration, or model-switch fallback behavior.
-
-## Token-budget regression and smoke checks
-
-`tests/integration.test.mjs` uses the real Pi compaction hook, serializer, and
-session tree with fake credentials and mocked Responses transport. A synthetic
-long transcript must produce a remote checkpoint even when its UTF-8 bytes
-exceed the numeric token budget. Oversized input must still invoke the standard
-compactor and record a safe fallback reason. A later model request must not
-contain the diagnostic entry. No private session fixtures or live requests are
-needed for these tests.
-
-The token conversion follows Codex's ordinary JSON-item heuristic:
-[byte-to-token estimate](https://github.com/openai/codex/blob/654b0a77d0d2f81aa21f61caf7af4be88fe550bb/codex-rs/utils/string/src/truncate.rs)
-and [history sizing](https://github.com/openai/codex/blob/654b0a77d0d2f81aa21f61caf7af4be88fe550bb/codex-rs/core/src/context_manager/history.rs).
-This package keeps all serialized opaque/image bytes in its estimate instead of
-copying Codex's modality-specific discounts. Never equate bytes and tokens or
-remove the independent wire-size ceiling.
-
-For an offline replay, reconstruct a compaction's discarded history in memory,
-use fake authentication, replace `fetch` with a fixture checkpoint response,
-and call `createRemoteCompaction`. Print only sizes and the success/fallback
-code. Do not save the transcript, request, auth headers, or opaque content.
-
-For an approved live smoke test, follow the procedure in [README.md](./README.md#reference-and-smoke-test).
-Check for `fromHook: true` and `details.kind: "pi-codex-compaction"` on success.
-On fallback, inspect only the reason and counters in the custom diagnostic
-entry. Never inspect or print `encryptedContent`.
+Use public Pi request, stream, and turn-end APIs. Preserve normal streaming and
+the effective request rather than constructing a separate compaction request.
+Do not restore legacy provider transport or the temporary compat serializer.
+
+Automatic mode defaults on only for eligible public OpenAI requests. Preserve
+off overrides, safe checkpoint bounds, cancellation, credential binding, ordinary
+usage accounting, and standard Pi recovery. Never infer model-token counts from
+ciphertext length or equate request count with cost.
+
+## Regression and smoke tests
+
+`tests/automatic.test.mjs` exercises real Pi sessions, serializer, tool loops and
+session projection with fake credentials and mocked Responses streams.
+`tests/default-mode.test.mjs` checks default policy, unsupported routes and
+cache-warming decisions. No live requests are needed for ordinary validation.
+
+Add integration coverage when changing checkpoint capture, ordering, replay,
+threshold coordination, or message normalization. Keep a stream open to verify
+text delivery before completion. Successful checkpoint adoption must not start
+a second Pi compaction between tool continuations. Missing checkpoints must
+leave the standard compactor available.
+
+The gated `tests/benchmark-automatic.mjs` consumes subscription usage and is not
+part of `npm test`. Obtain explicit approval before every live run. Use synthetic
+text only, bound requests and input, and never print raw provider errors,
+credentials, or encrypted content. `tests/AUTOMATIC_BENCHMARK.md` documents the
+existing measurements and their limits.
+
+For an approved TUI smoke test, follow the procedure in README. Check saved
+checkpoint replay after reload, branch navigation and mode-off. Do not interpret
+passing protocol tests as proof of long-session latency or cost savings.
 
 ## Code of conduct
 

package/README.md

@@ -1,19 +1,19 @@
 # pi-codex-compaction
 
-Keep long Pi sessions usable on OpenAI Codex models by replacing Pi's local summary request with Codex's provider-side **RemoteCompactionV2** checkpoint when the current model supports the Codex Responses API.
+Keep long Pi sessions flowing with **automatic server-side compaction** inside
+ordinary OpenAI Responses requests. The server can emit an encrypted checkpoint
+and continue inference without Pi stopping for a separate summary request.
 
-## Features
+- **On by default** for eligible public `openai` GPT-5/GPT-6 requests.
+- Uses your existing ChatGPT subscription login or API-key authentication without
+  changing providers, models, credentials, or billing mode.
+- Preserves Pi's effective tools, streamed text, tool continuations, and Fast tier.
+- Saves checkpoints on the session branch for reload and continuation.
+- Keeps `/server-compaction off`, manual `/compact`, and Pi's standard compactor
+  as recovery options.
 
-- Uses the current `openai-codex` model for each compaction; it never silently changes the session model.
-- Sends only the history Pi is discarding, plus the previous Codex checkpoint, so the incoming/kept user message is not duplicated.
-- Retains the normal Codex Responses request envelope, including system instructions, active tool schemas, reasoning settings, prompt-cache fields, and routing fields.
-- Persists Codex's opaque encrypted checkpoint and rehydrates it only for supported Codex requests.
-- Reuses checkpoints only for the same model, trusted endpoint, Codex account, and authentication mode.
-- Bounds input with a Codex-style UTF-8 token estimate and a separate hard byte limit, trims tool output when necessary, retries transient failures, and honors cancellation.
-- Falls back to standard Pi compaction on failure or when custom compaction instructions are requested.
-- Keeps a bounded readable transcript excerpt so switching models or providers remains usable.
-
-The current Codex catalog includes `gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna`. Capability detection follows the provider/API contract (`openai-codex` + `openai-codex-responses`) rather than a brittle model-name list. Use Pi 0.85.1 or later.
+Requires **Pi 1.1.0 or later**. The package name is unchanged, but the legacy
+`openai-codex` provider is no longer supported.
 
 ## Installation
 
@@ -33,109 +33,175 @@ Or load it for one run:
 pi -e /path/to/pi-mono/packages/pi-codex-compaction
 ```
 
-## Behavior
-
-After a Codex checkpoint is saved, the TUI shows
-`[compaction (codex)] Checkpoint saved.` Pi's built-in `[compaction]` heading
-remains unchanged. The notice is stored as a TUI-only custom session entry, so it
-survives the compaction chat rebuild and reload. It is not added to model context.
-Standard Pi compaction does not create a Codex success notice.
-Print, JSON, and RPC modes receive no extra notification.
-
-When Pi starts compaction on a supported Codex model, the extension sends a streamed Responses request whose `input` contains only discardable history, any compatible prior checkpoint, and a `compaction_trigger` item. The normal request envelope is retained because Codex's compaction path is parity-tested against ordinary Responses requests; this includes the effective system prompt, active tool definitions, reasoning level, prompt-cache fields, and routing fields. The request uses the `remote_compaction_v2` beta feature, and the returned opaque checkpoint and bounded provider usage are stored in the Pi compaction entry. Later requests rehydrate the raw checkpoint only when the model, endpoint, account, and authentication mode match; other providers/models receive the bounded textual fallback instead.
-
-Compaction uses the model active when Pi triggers it. If a session switches from a larger to a smaller model, the remote request is bounded against the new model's context window and tool outputs are reduced before sending. A previous opaque checkpoint is treated as incompatible after a model, endpoint, account, or authentication-mode switch; Pi's readable previous summary is sent instead. If the full request still cannot fit, the extension leaves compaction to Pi's normal implementation.
-
-If the remote request fails or returns an unexpected response, Pi's standard compaction path runs. Cancellation remains cancelled. Custom compaction instructions also use Pi's standard path because RemoteCompactionV2 has no documented custom-instructions field. The direct checkpoint request is restricted to `https://chatgpt.com`, rejects redirects, limits request/response size, and never decodes or logs `encrypted_content`. No configuration is required.
-
-### Size limits
-
-Input is estimated as `ceil(UTF-8 request bytes / 4)`, with 8,192 tokens reserved
-from the active model's context window. This uses Codex's ordinary-item heuristic,
-not an exact tokenizer. The complete transformed request is counted, including
-system instructions, tool definitions, and routing fields. Opaque checkpoints
-and image data remain counted at their serialized size; they are not decoded or
-discounted. Non-ASCII text uses UTF-8 bytes, not JavaScript string length.
-
-The uncompressed request also has an independent **16 MiB hard limit**. Tool
-outputs are reduced only when one of these limits is exceeded. User messages,
-tool calls, and opaque checkpoints are not removed. If the remaining request
-still cannot fit, or the model's context limit is unknown, standard Pi compaction
-runs. The estimate can differ from the server's token count; a server rejection
-still uses the existing fallback.
-
-### Fallback diagnostics
-
-A fallback on a supported model records a local custom session entry with type
-`pi-codex-compaction:fallback:v1`. It contains `version: 1` and a reason:
-`custom-instructions`, `auth-unavailable`, `request-unavailable`,
-`context-window-unavailable`, `context-limit`, `request-size-limit`, or
-`remote-failed`. Size failures also include estimated tokens, token budget,
-request bytes, byte limit, and the number of tool outputs reduced.
-Unexpected preparation failures use `request-unavailable`; `remote-failed`
-is reserved for failures from the transport call.
-
-No prompt, tool content, encrypted checkpoint, account identifier, credential, or
-raw provider error is included. These entries are not sent to the model. Pi
-shows a warning only in TUI mode when notifications are available; print, JSON,
-and RPC modes get no extra notifications or console output. Unsupported models
-and cancelled attempts do not create fallback diagnostics. Diagnostic storage
-or notification failure does not stop the standard compactor.
-
-## Development
-
-### Other Codex extensions
-
-With `pi-fast` installed, direct compaction requests use the current Fast toggle.
-With `pi-codex-tools` installed, `apply_patch` keeps its raw grammar definition,
-custom-tool calls, and custom-tool results during compaction. Neither package is
-required. No package reads a private Pi tool registry.
-With `pi-openai-reasoning` installed, verified Astra requests keep the original
-request effort and receive the current effort as a configuration update.
-Failed compaction does not change saved reasoning state.
-
-Pi 0.85.1 does not expose grammar metadata in `getAllTools()`. Two synchronous,
-versioned `pi.events` contracts let cooperating extensions supply it:
-
-- `pi-codex-compaction:tools:v1`: `{ model, tools }`, before provider serialization.
-  A tool owner can attach its own `constrainedSampling` metadata.
-- `pi-codex-compaction:request:v1`: `{ ctx, messages, payload }`, after input
-  assembly and before size checks. A listener can replace `payload`. This event
-  is not the general `before_provider_request` chain and does not carry auth.
-  Size checks use the transformed envelope, including field removals.
-
-Other extensions' private request changes are not applied automatically.
-Unknown third-party grammar metadata needs cooperation through the tools event.
-The checkpoint entry includes standard Pi `usage`, including cache reads and
-cache writes, as well as the original bounded token counters in `details`.
-Costs follow Pi's catalog estimates. They are not a ChatGPT subscription bill.
-
-### Reference and smoke test
-
-The automated display smoke tests exercise Pi's actual compaction-end handler
-and chat renderer for manual, threshold, and overflow compaction. They check
-redraw, reload, standard compaction, and exclusion from subsequent model requests.
-Only provider responses and terminal I/O are replaced with local fixtures.
-
-Behavior was checked against `openai/codex` commit
-`654b0a77d0d2f81aa21f61caf7af4be88fe550bb` (2026-09-11), notably
-`core/src/compact_remote_v2{,_attempt}.rs`. No Codex code was copied.
-RemoteCompactionV2 is a changing Codex protocol, not the public `/responses/compact`
-API. Async tools and mid-turn steering require upstream Pi support.
-
-For a small live test, load this package and select `openai-codex/gpt-6-astra`.
-Send two short messages, run `/compact`, then ask about the first message.
-Confirm `[compaction (codex)] Checkpoint saved.` remains visible after the
-compaction finishes and after `/reload`. Then run
-`/compact Focus on recent work` and confirm the standard-compaction warning
-appears without a new Codex success notice.
-Repeat with `/fast on` and `pi-codex-tools` loaded. Check that compaction succeeds,
-the continuation retains context, and session usage includes compaction tokens.
-Use only a temporary file if you test `apply_patch`. Do not generate images.
+Select a GPT-5/GPT-6 model on provider `openai`, API `openai-responses`, at
+`https://api.openai.com/v1`. No enable command is needed. A previously saved
+`off` setting on the current session branch remains respected.
+
+Load this package **after extensions that transform provider requests**. Pi
+orders handlers by extension load order. The compatibility guard cannot prevent
+a later extension from adding incompatible fields.
+
+## Controls and thresholds
+
+```text
+/server-compaction status
+/server-compaction off
+/server-compaction on
+/server-compaction on 100000
+```
+
+Commands persist the mode and optional token threshold on the current session
+branch, not in global or project settings. `on` without a number uses the startup
+threshold, or the default when none was supplied.
+
+`--server-compaction` defaults to true.
+`--server-compaction-threshold 100000` supplies a startup threshold.
+Saved command settings take precedence.
+
+The default threshold is 60% of Pi's local trigger
+(`contextWindow - reserveTokens`), including per-model reserve overrides. This
+is a headroom heuristic, not an OpenAI-prescribed optimal threshold. Explicit
+thresholds must be integers of at least 1,000 and below Pi's local trigger.
+Invalid or too-late thresholds leave ordinary inference unchanged.
+
+Very small thresholds can compact repeatedly within one response and increase
+latency and token use. Do not use the 1,000-token protocol-test threshold for
+ordinary long sessions.
+
+## How continuation works
+
+The extension adds
+`context_management: [{ type: "compaction", compact_threshold: ... }]`,
+`store: false`, and `stream: true` to eligible ordinary requests. It does not
+construct a separate compaction request or reconstruct tool declarations.
+Pi's actual request retains grammar tools, hidden loadouts, reasoning options,
+Fast settings, and declarations carried through `additional_tools`.
+
+Text streams normally. After successful completion, the extension commits a
+Pi compaction entry at `turn_end`, before the next assistant response. It stores
+the latest encrypted checkpoint and the exact provider output following it.
+On subsequent requests, it replaces the readable fallback and the retained
+assistant's serialized items with that checkpoint and output suffix. Later
+tool results and messages remain.
+
+The original transcript stays in the session file. Reload and tree navigation
+use the selected branch, not a global cache. Turning the mode off stops requesting
+new checkpoints but still replays a compatible saved checkpoint while the
+extension remains loaded.
+
+Successful adoption avoids a separate Pi compaction lifecycle, including between
+tool continuations. It does **not** promise zero server-side delay or concurrent
+inference during the server's compaction pass. It does not set `background: true`.
+
+## Support and recovery
+
+Authentication stays with Pi: `/login openai` with **Sign in with ChatGPT**
+uses plan quota; an OpenAI API key uses separate API billing. Neither path
+falls back to the other. This is automatic `context_management` in ordinary
+`/responses`, not the standalone `/responses/compact` API or the removed private
+RemoteCompactionV2 protocol.
+
+| Route | Behavior |
+| --- | --- |
+| `openai` + `openai-responses`, official endpoint, GPT-5/GPT-6 | Automatic compaction on by default; server/model availability still applies |
+| Same route with ChatGPT sign-in | Live checkpoint/replay verified with `gpt-6-astra` |
+| Same route with an API key | Mocked contract coverage; no live billing test |
+| Legacy `openai-codex`, custom endpoints, other providers, routed model mismatch | Left unchanged; no compaction or auth hooks for those routes |
+
+Virtual-model selections are also ineligible, including when their physical
+dispatch returns to the same public OpenAI model. Pi 1.1.0 request hooks expose
+the selected virtual model, not a complete physical request/auth identity.
+Existing checkpoints use their bounded readable fallback rather than opaque
+replay. Pi's ordinary routed context-limit checks and standard compaction remain
+available; no checkpoint identity is inferred from the payload's model name.
+
+GPT-6.1 Sol matches the GPT-6 candidate guard, but the existing live replay
+evidence is Astra-only. Model eligibility is not proof of account availability.
+No default model is changed. See the [provider migration assessment](../pi-openai-reasoning/README.md#provider-migration-assessment)
+for the separate reasoning-update limitation.
+
+- Requests with `configuration_update`, `compaction_trigger`, an existing
+  `context_management`, stateful continuation, truncation, background processing,
+  or enabled multi-agent mode are not opted in.
+- Keep Pi's normal automatic compaction enabled. If no checkpoint is adopted,
+  its normal threshold and overflow recovery remain available. Manual `/compact`,
+  including custom instructions, uses Pi's standard summarizer.
+- Failed, cancelled, malformed, oversized, or unsupported output does not
+  replace history. An unsuccessful automatic attempt pauses new automatic
+  requests until `/server-compaction on` or session reload. The extension does
+  not issue an extra paid retry or switch credentials; Pi owns its own retries.
+- Adoption supports reasoning, single-text assistant messages, function/custom
+  calls, and compaction items. Other output shapes leave history intact.
+- Replay requires the same model, endpoint, auth mode, credential and relevant
+  headers. Credential rotation, including OAuth refresh, conservatively uses
+  the readable excerpt rather than an unverified checkpoint.
+- Edits or transforms of the retained assistant prevent stale raw replay. The
+  fallback is a bounded excerpt, **not a complete summary**. Edits to history
+  already compacted cannot retroactively change an opaque checkpoint.
+- Pi cannot measure the opaque checkpoint's token footprint natively. Local
+  context estimates are not exact server-context measurements.
+- Cache warming is stopped only when the last ordinary request actually enabled
+  automatic compaction. Turning the toggle off does not make an already-cached
+  automatic request safe to replay; a new ordinary non-automatic request clears
+  that restriction. Unrelated providers retain their normal warming behavior.
+- Usage stays on the ordinary assistant response and is counted once. Bounded
+  success diagnostics stay local; they contain timing and size counters, not
+  conversation content.
+
+## Migration from the legacy provider
+
+Legacy RemoteCompactionV2 requests, `chatgpt.com/backend-api` transport, beta
+headers, the temporary `pi-ai/compat` serializer, old transport helper exports,
+and the `pi-codex-compaction:tools:v1` / `:request:v1` event-bus contracts have
+been removed. Fast and grammar integrations now use the ordinary Pi pipeline.
+
+Existing legacy session files are not modified or deleted. Old encrypted
+checkpoints are not migrated or replayed across providers; their readable
+fallback remains available. Use compatible package versions together.
+`pi-fast` and `pi-codex-tools` still support their own legacy-provider use cases;
+this change removes only their obsolete direct-compaction adapters.
+
+`pi-openai-reasoning` remains a legacy-provider-only extension. This package
+does not migrate it or enable its reasoning-update feature on the public route.
+Automatic compaction and histories containing `configuration_update` are
+incompatible in the public API.
+
+## Validation and measured results
+
+Tests use real Pi sessions with mocked transport to cover effective loadouts,
+streaming, tool continuations, checkpoint ordering, branches, reloads,
+cancellation, credential changes, context edits, default-on behavior, and
+the standard compaction safety net.
+
+A small live subscription test with `gpt-6-astra` verified checkpoint adoption,
+replay, and synthetic fact recall. At a deliberately low 1,000-token threshold,
+automatic mode used two requests versus four for standard Pi. The first answer
+completed sooner, but overall elapsed time and reported token use were higher.
+That protocol test did not measure long-session streaming continuity and does
+not establish cost or latency savings.
+
+In a checkout, `tests/AUTOMATIC_BENCHMARK.md` contains the measurements, limits,
+and Codex source comparison. `tests/benchmark-automatic.mjs` is an explicitly
+gated live test and is not run by `npm test`. Live testing requires approval to
+consume usage; use synthetic text, not private session history or images.
 
 ```bash
-npm install
 npm run -w packages/pi-codex-compaction check
 npm test -w packages/pi-codex-compaction
 npm run -w packages/pi-codex-compaction pack:dry-run
 ```
+
+For an approved TUI smoke test, cross the configured threshold in a synthetic
+session, then check facts from earlier turns and a tool continuation. Check replay
+after `/reload`, mode-off, and branch navigation. Successful adoption should
+not start Pi's separate compaction lifecycle.
+
+References:
+
+- [OpenAI compaction guide](https://developers.openai.com/api/docs/guides/compaction)
+- [ChatGPT subscription inference](https://developers.openai.com/siwc/token-sharing-open-source/models-and-inference)
+- [Subscription restrictions](https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations)
+- [Reasoning-update restrictions](https://developers.openai.com/api/docs/guides/deployment-checklist)
+
+Install telemetry is best-effort, once per version. Disable it with
+`PI_OFFLINE=1`, `PI_TELEMETRY=0`, or `enableInstallTelemetry: false`.

package/SECURITY.md

@@ -7,46 +7,74 @@ Security fixes are provided for the latest released version of `pi-codex-compact
 ## Reporting a vulnerability
 
 Please do not open a public issue for suspected security vulnerabilities.
-
-Report privately through [GitHub Security Advisories](https://github.com/jvm/pi-mono/security/advisories/new) or by contacting the repository maintainer through GitHub. Include:
-
-- a description of the issue;
-- steps to reproduce;
-- affected versions or commits, if known;
-- any suggested mitigation.
+Report privately through
+[GitHub Security Advisories](https://github.com/jvm/pi-mono/security/advisories/new)
+or contact the maintainer through GitHub. Include the affected version,
+description, reproduction steps, and any suggested mitigation.
 
 ## Security model
 
-`pi-codex-compaction` is a Pi package. Pi extensions execute with the same permissions as the local user running Pi. Users should review installed Pi packages and only install packages from sources they trust.
-
-For supported `openai-codex` models, the extension sends the portion of conversation Pi is about to discard to the OpenAI Codex Responses endpoint over HTTPS, using credentials and provider headers resolved by Pi. The request also includes the normal Codex Responses envelope: the effective system prompt, active tool schemas, reasoning settings, and provider-generated cache/routing fields. It stores the provider-issued opaque `encrypted_content` checkpoint in the local Pi session's compaction details so compatible Codex requests can reuse it. The checkpoint is not decoded, printed, or logged.
-
-The extension bounds request, compaction input, and response size, validates the HTTPS endpoint against the official `chatgpt.com` origin, rejects redirects, validates the account claim shape, binds checkpoints to a hashed account identity/model/endpoint/authentication mode, honors Pi cancellation, and retries only transient transport failures. It falls back to standard Pi compaction on authentication, transport, response, or context-limit failures. A bounded textual transcript excerpt remains in the compaction summary so switching to another model or provider does not leave the session with only an unusable Codex checkpoint. The fallback may contain conversation content already present in the local session and is still subject to the user's normal Pi session-file permissions.
-
-The extension never logs prompts, conversation contents, credentials, authorization headers, or raw provider responses. Install/update telemetry is best-effort and sends only package/version/runtime metadata; it can be disabled with `PI_OFFLINE=1`, `PI_TELEMETRY=0`, or Pi's `enableInstallTelemetry: false` setting.
-
-Direct requests allow only the official `/backend-api/codex/responses` endpoint
-on the default HTTPS port, without query strings or fragments. Total request
-time is limited to five minutes, including retries. Completed streams are closed
-without waiting for a server disconnect. A pre-aborted request does no network I/O.
-Null auth headers remove matching model headers; beta features are merged.
-
-Cooperating local extensions can inspect and transform compaction inputs through
-the documented event bus before size checks. These events contain no credentials.
-They have the same trust level as other installed Pi extensions.
-
-Context sizing uses `ceil(UTF-8 serialized request bytes / 4)` with an 8,192-token
-reserve from the active model's context window. It is an estimate, not a strict
-tokenizer bound. The complete transformed envelope is counted, including opaque
-content at its serialized size. A separate 16 MiB uncompressed request limit is
-enforced before network I/O. The HTTPS, redirect, response-size, checkpoint
-compatibility, and cancellation checks remain independent of token estimation.
-
-Fallback diagnostics store only a fixed reason code and finite non-negative
-size counters in `pi-codex-compaction:fallback:v1` custom session entries.
-These local records never include credentials, account/model identifiers,
-request content, encrypted checkpoints, or raw errors, and do not enter model
-context. No external diagnostic telemetry is added. They use the existing
-session's permissions and retention policy.
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development and validation instructions.
+Pi extensions execute with the permissions of the local user. Install only
+trusted packages. This extension enables automatic compaction by default only
+for eligible `openai` GPT-5/GPT-6 models on `openai-responses` at the exact
+official endpoint `https://api.openai.com/v1`.
+
+It transforms ordinary Pi requests; it does not make direct HTTP inference
+requests, register a provider, or use ChatGPT's legacy backend endpoints.
+Pi owns TLS, transport limits, cancellation, provider retries, authentication,
+and credential refresh. The extension does not copy credentials between
+providers or fall back from subscription authentication to API-key billing.
+
+## Checkpoints and local data
+
+Raw `response.output_item.done` items are copied, bounded to 1,024 items and
+4 MiB total, and adopted only after matching successful stream completion.
+Added/partial items are never treated as checkpoints. Unknown output forms,
+missing indices, failed streams, and cancellation leave history intact.
+Encrypted checkpoint strings are additionally limited to 2 million characters.
+The complete persisted details are bounded to 4 MiB.
+
+The checkpoint and its exact post-checkpoint output suffix are sensitive session
+data. Provider encryption does not make the surrounding transcript or suffix
+public. Neither is logged or sent through install telemetry.
+
+A domain-separated HMAC-SHA-256 binds replay to the current credential, auth
+mode, model, endpoint and headers. The provider-issued, high-entropy bearer
+credential and potentially secret headers form the HMAC key material and are
+never stored in checkpoint details. Only non-secret routing/auth-mode metadata
+is used as the HMAC message. This is
+credential binding, not storage or verification of user-chosen passwords.
+Rotation invalidates replay, including OAuth token refresh. The fallback is
+a bounded transcript excerpt, not a complete summary. The original history and
+fallback remain subject to the user's Pi session-file permissions and retention.
+
+Replay checks the canonical retained assistant and serialized output
+fingerprints. Omitted, edited, or transformed messages fall back rather than
+restoring stale raw content. As with Pi text summaries, edits to already-compacted
+source history cannot alter an opaque checkpoint. Legacy checkpoint details are
+not migrated or replayed across provider/authentication boundaries.
+
+## Extension composition and recovery
+
+Load this extension after request transformers. Its compatibility check cannot
+constrain a later trusted extension that changes the payload. It skips observed
+reasoning configuration updates, stateful continuation, truncation, multi-agent
+requests, and preexisting compaction policies.
+
+Cache warming is stopped only for a cached request that actually enabled
+automatic compaction, because replay could produce an uncommitted checkpoint.
+Other providers and skipped requests retain Pi's normal warming behavior.
+Turning automatic mode off still blocks warming the old automatic request until
+a new ordinary request replaces it.
+
+The extension does not execute tools, duplicate response usage, or issue an
+automatic paid retry after a failed attempt. Pi's standard compaction remains
+available. Local success diagnostics contain only a version, elapsed
+milliseconds, byte count and output-item count.
+
+No project settings are read. Install telemetry is best-effort, once per
+version, with a five-second timeout. It sends only package/version/runtime
+metadata and respects CI, `PI_OFFLINE`, `PI_TELEMETRY`, and
+`enableInstallTelemetry: false`.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for validation and live-test precautions.