@datspike/pi-codex-session-fast 0.0.0-stage → 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+## Before making changes
+
+1. Install Node.js 22 or newer.
+2. Install dependencies without running third-party scripts:
+
+   ```sh
+   npm ci --ignore-scripts
+   ```
+
+3. Run the checks:
+
+   ```sh
+   npm run check
+   npm pack --dry-run
+   ```
+
+Changes must preserve the extension boundaries: do not change auth, transport, reasoning, or Pi core. Fast lives only in memory for the active session and must not be enabled through files, environment variables, or startup settings.
+
+## Pull requests
+
+Describe the behavior before and after the change, add a regression test for every new scenario, and include the result of `npm run check`. Do not commit `.runtime/`, `.task_files/`, `.pi/`, `node_modules/`, credentials, or session JSONL.
+
+Use Conventional Commits for commit messages.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 datspike
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# pi-codex-session-fast
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Explicit Fast mode for one active native `openai-codex` session in Pi 1.3.0+. The extension adds `service_tier: "priority"`; the server may reject or downgrade the tier. This is not a guarantee of faster responses.
+
+## Installation
+
+Install the local package with `pi install /absolute/path/to/pi-codex-session-fast`, then start a new Pi session or run `/reload`.
+
+Choose any `openai-codex` model through Pi's normal model picker. The extension does not change the default model, OAuth, CLIProxyAPI, transport, or reasoning. Do not load another extension that owns `/fast` or `service_tier` at the same time.
+
+## Commands
+
+- `/fast` — toggle the mode.
+- `/fast on` — enable it explicitly.
+- `/fast off` — disable it for future requests.
+- `/fast status` — show the current state.
+
+Fast can be enabled at any time: the command changes only future requests and does not modify a request that has already been sent. The command does nothing for other providers. The `priority requested` indicator means that the extension requested the tier; it does not confirm that the server applied it.
+
+## State boundaries
+
+Fast is disabled at startup, on `/new`, resume, fork, `/reload`, and session shutdown. Switching away from provider `openai-codex` also disables it; switching back does not re-enable it. The state survives model changes within `openai-codex` in the same session.
+
+Normal responses, tools, retries, and compaction keep the state within the same session. New processes and subagents get a disabled instance. The extension does not use files, global preferences, environment variables, or startup flags to enable Fast. Response receipts are reporting data only and never restore Fast.
+
+`/fast off` does not cancel a request that has already been sent or remove settings owned by another component. If another `service_tier` is present, the extension leaves the payload unchanged and disables its own mode. An external `priority` is preserved with a warning. A later hook may change the final payload; do not have multiple components own the tier.
+
+## Models and cost
+
+Fast is available for every model on provider `openai-codex`. There is no model ID allowlist; new models from this provider are supported automatically. Other providers are not supported.
+
+Fast increases subscription credit usage, including banked credits. The extension does not set a spending limit. Check the current terms in the [Codex documentation](https://developers.openai.com/codex/speed).
+
+## Development and checks
+
+```sh
+npm ci --ignore-scripts
+npm run check
+npm pack --dry-run
+```
+
+TypeScript checks and lifecycle tests do not replace live acceptance. Run real model checks separately with an explicit budget and receipts. The architecture decision is documented in `docs/adr/0001-volatile-session-priority.md`.
+
+Private plans live in the ignored `.task_files/` directory, and local runs live in `.runtime/`. Neither is included in Git or the npm package.
+
+## Response receipts
+
+The extension writes metadata-only `codex-session-fast-response.v1` entries to Pi JSONL: the session, model, exact `responseId`, `requestedTier` at request-hook time, and `serverTier` when the provider reports it. Request and response text are not stored. The receipt is bound at `response.created`; later events from another response or session cannot inherit it.
+
+`requestedTier: "priority"` means that Fast was requested, not that the server honored it. A later hook may change the payload. To match receipts with SQLite telemetry, `context-compaction` must preserve `flags_json.providerResponseId`. If an ID or receipt is missing, or receipts conflict, the report keeps the mode unknown. The change takes effect after `/reload` or a new Pi process; do not repeat paid requests just to populate history.
+
+## Contributing and security
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for local checks and contribution boundaries. See [`SECURITY.md`](SECURITY.md) for handling vulnerabilities and sensitive data.

package/SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+Do not submit keys, tokens, `auth.json` contents, session JSONL, or other secrets in issues, pull requests, or CI logs.
+
+If you find a vulnerability, do not disclose it publicly before it is fixed. Contact the repository owner through a private channel and include the smallest reproducible description you can provide.
+
+The extension does not own auth or transport, does not store Fast on disk, and does not store request or response text in its metadata receipts.

package/docs/adr/0001-volatile-session-priority.md

@@ -0,0 +1,36 @@
+# Fast Without Persistent State
+
+## Status
+
+Accepted. Verified on Pi 1.3.0: commands in the real TUI, session replacement through the SDK, and limited model requests.
+
+## Context
+
+Fast is a paid server preference. Persisting a global switch could silently carry higher usage into another session. Replacing the provider to add one field would take ownership of transport and cleanup that this extension does not need.
+
+## Decision
+
+Use one TypeScript entrypoint with public command, lifecycle, and request hooks. Keep state in a closure keyed by the session ID. Do not add runtime dependencies, state files, CLI flags, background resources, or provider registration. Not restoring Fast is intentional protection, not a missing feature.
+
+Enable Fast only through `/fast` on `openai-codex`, including while a turn is active; the command changes only future requests. `session_start` and `session_shutdown` reset it. Leaving `openai-codex` resets it. A request must match the current session ID, provider, and model. Do not overwrite another tier; an external `priority` remains external. The hook does not confirm the served tier.
+
+## Alternatives
+
+- CLIProxyAPI provider: adds tier and transport ownership, while dynamic Pi adaptation and persisted state are unnecessary here.
+- calesennett: provides a short injector and broad compatibility, but its commands write shared settings, which is not needed here.
+- SI-RUI-ZHANG: separates core and state carefully, but persisted preferences, startup flags, and overwriting another tier do not fit this contract.
+- dasomji: validates payload and model and avoids overwriting a tier, but its global state file is unnecessary.
+
+The implementation is independent. It borrows verified ideas from the reference implementations rather than copying their code. A small new implementation avoids adapting their state, storage, and provider layers.
+
+## Consequences
+
+Fast must be enabled again after `new`, resume, fork, reload, or restart. Compaction and ordinary turns preserve it. Subagents receive a separate disabled instance. `/fast on` and `/fast off` affect only future requests owned by this extension; the backend and other hooks may have their own settings.
+
+## Non-goals
+
+Changing auth, transport, reasoning, the model, the default provider, guaranteed acceleration, or subscription spending controls.
+
+## Verification
+
+Lifecycle tests, Jiti loading, and a real TUI check are followed by a limited model check. Unit tests do not prove backend Fast behavior.

package/docs/adr/0002-response-mode-receipts.md

@@ -0,0 +1,17 @@
+# Requested Mode Receipt for Each Response
+
+## Decision
+
+Store a `codex-session-fast-response.v1` entry in Pi JSONL that links the requested mode to the exact `sessionId`, `responseId`, and model. Use the existing `pi.appendEntry()` and `provider_stream_event`; do not create another database or a restorable mode switch.
+
+The receipt stores `requestedTier` when the extension processes the request and, separately, `serverTier` when the provider reports it. Request and model text are not copied. Bind the receipt at `response.created`; terminal events `response.done`, `response.completed`, `response.failed`, and `response.incomplete` close only that same response. A new session clears unfinished bindings.
+
+To link receipts with existing SQLite telemetry, `context-compaction` preserves `flags_json.providerResponseId`. This removes ambiguity based on timing or message order. Old rows without an ID and responses without a receipt remain unknown.
+
+## Boundaries
+
+Fast means that priority was requested, not that the server honored it. A later hook may change the payload. The server-returned tier does not enable Fast and does not replace the requested tier. CLIProxyAPI responses are not marked by this extension.
+
+## Alternatives
+
+Matching by speed, time, or whole-session state was rejected: the mode can change between adjacent requests, while retries and errors disrupt ordering. A separate mode store is unnecessary because JSONL and SQLite already exist.

package/extensions/session-fast.ts

@@ -0,0 +1,130 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const STATUS = "codex-session-fast";
+
+type Model = { provider: string; id: string } | undefined;
+
+/** Any model on the native subscription provider is eligible. */
+export function eligible(model: Model): boolean {
+  return model?.provider === "openai-codex";
+}
+
+/** Registers volatile Fast state and metadata-only response receipts; never restores Fast from disk. */
+export default function sessionFast(pi: ExtensionAPI): void {
+  let owner: string | undefined;
+  let warned = false;
+  type Receipt = { sessionId: string; provider: string; model: string; requestedTier: string };
+  let pending: Receipt | undefined;
+  let active: { id: string; receipt: Receipt } | undefined;
+
+  function show(ctx: ExtensionContext): void {
+    if (ctx.mode === "tui") {
+      ctx.ui.setStatus(STATUS, owner && eligible(ctx.model) ? "⚡ priority requested" : undefined);
+    }
+  }
+  function reset(ctx: ExtensionContext): void {
+    owner = undefined;
+    warned = false;
+    show(ctx);
+  }
+  function sync(ctx: ExtensionContext): void {
+    if (owner && (owner !== ctx.sessionManager.getSessionId() || !eligible(ctx.model))) reset(ctx);
+  }
+  function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" = "info"): void {
+    if (ctx.hasUI) ctx.ui.notify(message, level);
+  }
+
+  function resetSession(ctx: ExtensionContext): void {
+    pending = undefined;
+    active = undefined;
+    reset(ctx);
+  }
+  pi.on("session_start", (_event, ctx) => resetSession(ctx));
+  pi.on("session_shutdown", (_event, ctx) => resetSession(ctx));
+  pi.on("model_select", (event, ctx) => {
+    // event.model is authoritative: ctx.model can still describe the previous selection.
+    if (!eligible(event.model)) reset(ctx);
+    else show(ctx);
+  });
+
+  pi.registerCommand("fast", {
+    description: "Fast одной Codex-сессии: /fast [on|off|status]",
+    handler: async (args, ctx) => {
+      sync(ctx);
+      const command = args.trim().toLowerCase() || "toggle";
+      if (!["on", "off", "status", "toggle"].includes(command)) {
+        notify(ctx, "Использование: /fast [on|off|status]", "warning");
+        return;
+      }
+      if (command === "status") {
+        notify(ctx, owner ? "Fast включён: priority запрошен, исполнение сервером не гарантируется."
+          : "Fast выключен: расширение не добавляет priority.");
+        return;
+      }
+      if (command === "off" || (command === "toggle" && owner)) {
+        reset(ctx);
+        notify(ctx, "Fast выключен. Уже отправленный запрос не изменён.");
+        return;
+      }
+      if (!eligible(ctx.model)) {
+        reset(ctx);
+        notify(ctx, "Fast доступен только на поддержанной модели openai-codex. Провайдер не переключён.", "warning");
+        return;
+      }
+      owner = ctx.sessionManager.getSessionId();
+      warned = false;
+      show(ctx);
+      notify(ctx, "Fast включён только для текущей сессии. Расход кредитов выше; сервер может не применить priority.");
+    },
+  });
+
+  pi.on("before_provider_request", (event, ctx) => {
+    sync(ctx);
+    pending = undefined;
+    active = undefined;
+    const payload = event.payload;
+    if (!ctx.model || !eligible(ctx.model) || !payload || typeof payload !== "object" || Array.isArray(payload)) return;
+    const body = payload as Record<string, unknown>;
+    if (body.model !== ctx.model?.id) return;
+    const requestedTier = typeof body.service_tier === "string" ? body.service_tier : "default";
+    pending = { sessionId: ctx.sessionManager.getSessionId(), provider: "openai-codex",
+      model: ctx.model.id, requestedTier };
+    if (!owner) return;
+    // Another owner may have explicit tier policy. Never silently overwrite it.
+    if ("service_tier" in body) {
+      if (body.service_tier !== "priority") {
+        reset(ctx);
+        notify(ctx, "Конфликт service_tier: Fast выключен, чужой tier не изменён.", "warning");
+      } else if (!warned) {
+        warned = true;
+        notify(ctx, "priority уже задан другим компонентом. /fast off не отменяет чужие настройки.", "warning");
+      }
+      return;
+    }
+    pending.requestedTier = "priority";
+    return { ...body, service_tier: "priority" };
+  });
+
+  pi.on("provider_stream_event", (event, ctx) => {
+    if (event.provider !== "openai-codex" || !event.data || typeof event.data !== "object") return;
+    const frame = event.data as { type?: string; response?: { id?: string; service_tier?: string } };
+    const response = frame.response;
+    if (!response || typeof response.id !== "string") return;
+    if (frame.type === "response.created" && pending
+        && pending.sessionId === ctx.sessionManager.getSessionId() && pending.model === event.model) {
+      active = { id: response.id, receipt: pending };
+      pending = undefined;
+    }
+    if (!active || active.id !== response.id || active.receipt.sessionId !== ctx.sessionManager.getSessionId()) return;
+    if (!["response.created", "response.done", "response.completed", "response.failed", "response.incomplete"].includes(frame.type ?? "")) return;
+    // Receipts contain no payload or model text. A later hook may still override the requested tier.
+    try {
+      pi.appendEntry("codex-session-fast-response.v1", { ...active.receipt, version: 1,
+        responseId: response.id, stage: frame.type,
+        serverTier: typeof response.service_tier === "string" ? response.service_tier : null });
+    } catch {
+      notify(ctx, "Не удалось сохранить метку Fast; режим этого ответа может остаться неизвестным в отчёте.", "warning");
+    }
+    if (frame.type !== "response.created") active = undefined;
+  });
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@datspike/pi-codex-session-fast",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "Explicit, volatile Fast for one native Codex session",
+  "files": [
+    "extensions/session-fast.ts",
+    "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "docs/adr"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/session-fast.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=1.3.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@types/node": "^22",
+    "typescript": "^5.9.3"
+  }
+}