pi-openai-toolkit 0.14.5 → 0.14.6

package/docs/internals.md

@@ -1,8 +1,10 @@
 # Toolkit Internals
 
-Developer-facing reference for [pi-openai-toolkit](../README.md). This is the protocol and implementation detail that the README deliberately keeps out of the user's way. If you are only installing the toolkit, you never need this page; if you are changing wire behavior, fixtures, or the compaction strategy code, start here.
+Developer-facing reference for [pi-openai-toolkit](../README.md). The README keeps this protocol and implementation detail out of the installation path. If you are changing wire behavior, fixtures, or the compaction strategy code, start here.
 
-## Table of Contents
+---
+
+### Table of Contents
 
 - [Remote Context protocol](#remote-context-protocol)
 - [Rollover lifecycle](#rollover-lifecycle)
@@ -10,28 +12,34 @@ Developer-facing reference for [pi-openai-toolkit](../README.md). This is the pr
 - [Artifacts and debugging](#artifacts-and-debugging)
 - [Provenance](#provenance)
 
-## Remote Context protocol
+---
+
+### Remote Context protocol
 
 Internal alpha endpoints, adapted from `@howaboua/pi-codex-conversion`:
 
 ```text
 POST {base}/alpha/history/v2/list_windows | list_items | read_item | search_contents
 POST {base}/alpha/notes/v2/list_files_by_prefix | read_file | search_contents | append_to_file | write_file
-GET  {base}/alpha/notes/v2/thread_hint
+POST {base}/alpha/notes/v2/thread_hint
 ```
 
-Native route uses `{base} = <backend-api>/codex` with `Authorization: Bearer <oauth token>`, `ChatGPT-Account-ID`, and Codex CLI headers. Gateway route uses the configured `/v1` base with the data-plane API key, `originator: codex_cli_rs`, `X-Codex-Affinity-Scope`, and `X-Codex-Model` carrying the bare model id, never local credentials. Both set `Session-Id` / `X-Client-Request-Id` to the bounded Pi session id, `x-openai-tool-output-truncation-policy`, and `x-openai-encrypted-tool-arguments` for endpoints with encrypted parameters; encrypted results come back as `encrypted_output` and are re-encoded into later requests. These are alpha contracts: the upstream backend may change them at any time.
+The native route uses `{base} = <backend-api>/codex` with `Authorization: Bearer <oauth token>`, `ChatGPT-Account-ID`, and Codex CLI headers. The gateway route uses the configured `/v1` base with the API key configured for that provider, `originator: codex_cli_rs`, `X-Codex-Affinity-Scope`, and `X-Codex-Model` carrying the bare model ID. Inherited OAuth headers, cookies, and account IDs are stripped before the request leaves the process. Both routes set `Session-Id` and `X-Client-Request-Id` to the bounded Pi session ID, plus `x-openai-tool-output-truncation-policy` and `x-openai-encrypted-tool-arguments` for endpoints with encrypted parameters. Encrypted results come back as `encrypted_output` and are re-encoded into later requests. These are alpha contracts, so the upstream backend may change them at any time.
 
 Search text and note bodies are sent under the encrypted-argument policy. Live model requests carry `x-codex-window-id` and `x-codex-turn-metadata` request headers derived from the active window identity.
 
-Coverage is never inferred from model names. A native session is `provider: "openai-codex"` on api `openai-codex-responses` (any model id). A gateway session must be on api `openai-responses` and carry an exact `provider/model` key listed in `compaction.gatewayContextModels`; the list ships empty and there is no built-in gateway SKU ([src/context-management/codex-provider.ts](../src/context-management/codex-provider.ts)). Unlisted gateway models, listed or not, keep running remote compaction v2 when Remote Context declines them. The toolkit registers no provider or model with Pi; it resolves credentials and base URLs through Pi's `ModelRegistry`.
+Coverage is never inferred from model names. A native session uses provider `openai-codex` with API `openai-codex-responses` for any model ID. A gateway session uses API `openai-responses` and must carry an exact `provider/model` key listed in `compaction.gatewayContextModels`; the list ships empty and there is no built-in gateway SKU. See [src/context-management/codex-provider.ts](../src/context-management/codex-provider.ts). The toolkit registers no provider or model with Pi. It resolves credentials and base URLs through Pi's `ModelRegistry`.
 
-## Rollover lifecycle
+---
+
+### Rollover lifecycle
 
 The `new_context` happy path, end to end:
 
 ```mermaid
 sequenceDiagram
+  accTitle: Remote Context rollover
+  accDescr: A Pi model checkpoints notes, requests a local new_context boundary, and sends the next request with the new window identity.
   participant Model
   participant Toolkit
   participant Pi
@@ -41,6 +49,7 @@ sequenceDiagram
   Backend-->>Toolkit: encrypted_output
   Model->>Toolkit: new_context
   Toolkit->>Toolkit: verify successful notes write in this window
+  Toolkit-->>Model: checkpoint receipt with the successful note path
   Toolkit-->>Pi: window marker appended, previous window trim scheduled
   Model->>Backend: next request with the new x-codex-window-id
   Pi->>Toolkit: session_before_compact
@@ -49,25 +58,37 @@ sequenceDiagram
 
 State invariants the lifecycle code must keep honest:
 
-- The checkpoint gate verifies a *successful* `notes` `append_to_file` / `write_file` against the persisted session branch after the latest window boundary, so it survives restarts and forks.
-- Budget checks are skipped until the current window has produced its own assistant usage; acting on the previous window's usage anchor burns the once-per-window reminder on a false alarm.
-- The scheduled trim is consumed exactly once, synchronously, by the first compaction attempt whose boundary window id matches. Every other compaction path (threshold without a scheduled rollover, manual `/compact`, overflow) is cancelled.
-- A window boundary is persisted as a `codex-context-window` custom message; `session_start` replays boundaries from the branch and rebuilds identity after forks.
+- The checkpoint gate verifies a successful `notes` `append_to_file` or `write_file` against the persisted session branch after the latest window boundary, so it survives restarts and forks. A response with `ok: false` or `success: false` is not successful, even when HTTP returns 200.
+- Every rollover carries the most recent successful checkpoint path in its handoff message. The optional `thread_hint` is supplemental; a hint failure must not erase the local receipt.
+- `new_context` has no force escape hatch: a successful notes checkpoint is always required before rollover.
+- Budget checks are skipped until the current window has produced its own assistant usage. Acting on the previous window's usage anchor would burn the once-per-window reminder on a false alarm.
+- The scheduled trim is consumed exactly once, synchronously, by the first compaction attempt whose boundary window ID matches. Every other compaction path, including a threshold without a scheduled rollover, manual `/compact`, and overflow, is cancelled.
+- A window boundary is persisted as a `codex-context-window` custom message. `session_start` replays boundaries from the branch and rebuilds identity after forks.
+
+---
+
+### Remote Compaction v2 wire contract
+
+v2 is what an uncovered session gets. Any model that Remote Context declines, such as a gateway model absent from `gatewayContextModels`, can still compact through v2 when its API appears in `responsesApis`. The two strategies never compete for one session.
+
+A `compaction_trigger` item appended to the live streaming request yields one output item of `type: "compaction"` with non-empty `encrypted_content`, stored in `CompactionEntry.details.compactedWindow`. On later requests the opaque checkpoint is replayed ahead of live turns, with no text summary. Replay fails closed: if the summary anchor cannot be located, the request is aborted with a notification and a content-free failure artifact. The sentinel-only payload is never sent.
+
+A v2 response with a missing or empty checkpoint is never stored, and the `nativeFallback` tier is skipped. Pi's own threshold drives the next attempt, which may use `remoteCompactModel` when configured. `remoteCompactModel` must resolve to the same effective base URL as the active model.
 
-## Remote Compaction v2 wire contract
+---
 
-A `compaction_trigger` item appended to the live streaming request yields one output item of `type: "compaction"` with non-empty `encrypted_content`, stored in `CompactionEntry.details.compactedWindow`. On later requests the opaque checkpoint is replayed ahead of live turns: zero-loss, no text summary. Replay fails closed: if the summary anchor cannot be located, the request is aborted with a notification and a content-free failure artifact; the sentinel-only payload is never sent. A v2 response with a missing or empty checkpoint is never stored, and the `nativeFallback` tier is skipped: Pi's own threshold drives the next attempt, which may use `remoteCompactModel` when configured. `remoteCompactModel` must resolve to the same effective base URL as the active model.
+### Artifacts and debugging
 
-## Artifacts and debugging
+With `debug: true`, the toolkit writes lifecycle and compaction artifacts under `artifactRoot` (default `~/.pi/agent/artifacts/pi-openai-toolkit/compaction`):
 
-With `debug: true` the toolkit writes lifecycle and compaction artifacts under `artifactRoot` (default `~/.pi/agent/artifacts/pi-openai-toolkit/compaction`):
+- Each `session_start` writes a lifecycle artifact whose `activation` field records `active` or the exact inactive reason, such as `unsupported-model`, `unsupported-api`, `missing-api-key`, `auth-resolution-failed`, or `tool-name-conflict`.
+- `logProviderPayloads` additionally writes provider request metadata and payloads, while `logCompactResponses` writes compact status and structural summaries with complete response and body fields critically redacted. Keep both off unless inspecting a specific request.
+- Artifacts always redact Authorization credentials, API keys and tokens, Codex account IDs, and opaque `encrypted_content` or `encrypted_output`, even when `redactSensitiveData` is `false`.
 
-- each `session_start` writes a lifecycle artifact whose `activation` field records `active`, or the exact inactive reason (`tool-name-conflict`, `missing-api-key`, `auth-resolution-failed`, `model-not-covered`, ...);
-- `logProviderPayloads` additionally writes raw provider request payloads, `logCompactResponses` the compact SSE bodies; keep both off unless inspecting a specific request;
-- artifacts always redact Authorization credentials, API keys/tokens, Codex account ids, and opaque `encrypted_content` / `encrypted_output`, even with `redactSensitiveData: false`.
+---
 
-## Provenance
+### Provenance
 
-The Remote Context protocol was reverse-engineered from `@howaboua/pi-codex-conversion@3.0.29` (source commit `7021ae48e8efe36a3becc5830d529696ff798e5e`). The Astra compatibility layer is adapted from Oh My Pi 18.1.8 (MIT). Web Search behavior was adapted from [`pi-openai-web-search`](https://github.com/code-yeongyu/pi-openai-web-search) (commit `3964338`). Attribution details are in [NOTICE](../NOTICE).
+The Remote Context protocol was reverse-engineered from `@howaboua/pi-codex-conversion@3.0.29` (source commit `7021ae48e8efe36a3becc5830d529696ff798e5e`). The Astra compatibility layer is adapted from Oh My Pi 18.1.8 (MIT). Web Search behavior was adapted from [pi-openai-web-search](https://github.com/code-yeongyu/pi-openai-web-search) (commit `3964338`). Attribution details are in [NOTICE](../NOTICE).
 
-Protocol fixtures live in [src/context-management/](../src/context-management/) and must be updated together with any upstream alpha endpoint change; fixture-based tests are required for new wire behavior.
+Protocol fixtures live in [src/context-management/](../src/context-management/) and must be updated together with any upstream alpha endpoint change. New wire behavior requires fixture-based tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.14.5",
+  "version": "0.14.6",
   "private": false,
   "type": "module",
   "engines": {

package/src/auto-mode/classifier.ts

@@ -1,165 +1,165 @@
-import type { Api, Model } from "@earendil-works/pi-ai";
-import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { parseModelSpec } from "../runtime";
-import { CLASSIFIER_SYSTEM_PROMPT } from "./prompt";
-import { boundReviewText, type ClassifierRisk, type FastDecisionReason } from "./types";
-
-/** One completed classification of the trajectory, tagged to a tool-call position. */
-export type ScoreRecord = {
-	risk: ClassifierRisk;
-	/** Tool-call counter value when the sample was taken. */
-	scoredAtCall: number;
-	/** Fingerprint of the user turns the score was based on. */
-	authorizationVersion: string;
-	sampledAt: number;
-};
-
-/**
- * Mutable per-session tracker for the non-blocking pre-scorer.
- *
- * The counters reproduce Codex's staleness rule: the agent keeps running while a
- * classification is in flight, so a score is only trustworthy if it is recent
- * enough and nothing the user said has changed underneath it.
- */
-export type ScoreTracker = {
-	latestCallIndex: number;
-	latestScoredIndex: number;
-	latestFailedIndex: number;
-	score?: ScoreRecord;
-};
-
-export function createScoreTracker(): ScoreTracker {
-	return { latestCallIndex: 0, latestScoredIndex: 0, latestFailedIndex: 0 };
-}
-
-/** Reset everything: a new turn or a disengaged mode invalidates prior scoring. */
-export function resetScoreTracker(tracker: ScoreTracker): void {
-	tracker.latestCallIndex = 0;
-	tracker.latestScoredIndex = 0;
-	tracker.latestFailedIndex = 0;
-	tracker.score = undefined;
-}
-
-/**
- * Fingerprint of the user-authored conversation. Any new or edited user turn makes
- * an existing score stale, because the score's authorization premise changed.
- */
-export function authorizationVersion(userText: string): string {
-	const bounded = boundReviewText(userText, 8_000);
-	let hash = 2166136261;
-	for (let index = 0; index < bounded.length; index += 1) {
-		hash ^= bounded.charCodeAt(index);
-		hash = Math.imul(hash, 16777619);
-	}
-	return `${bounded.length}:${(hash >>> 0).toString(36)}`;
-}
-
-export function recordScoredCall(tracker: ScoreTracker, score: ScoreRecord): void {
-	tracker.score = score;
-	tracker.latestScoredIndex = Math.max(tracker.latestScoredIndex, score.scoredAtCall);
-}
-
-export function recordFailedCall(tracker: ScoreTracker, scoredAtCall: number): void {
-	tracker.latestFailedIndex = Math.max(tracker.latestFailedIndex, scoredAtCall);
-}
-
-export type FastDecisionInput = {
-	tracker: ScoreTracker;
-	/** Tool-call counter value for the call being gated. */
-	currentCallIndex: number;
-	authorizationVersion: string;
-	maxLag: number;
-	/** Retries after a denial and widened gates must not take the fast path. */
-	requiresSynchronousReview?: boolean;
-};
-
-/**
- * Decide whether a cached classification can satisfy this gated call without
- * running the blocking reviewer. Anything other than `low_risk` defers to the
- * synchronous review; the classifier never denies an action on its own.
- */
-export function fastApprovalEligible(input: FastDecisionInput): {
-	eligible: boolean;
-	reason: FastDecisionReason;
-} {
-	const defer = (reason: FastDecisionReason) => ({ eligible: false, reason });
-
-	if (input.requiresSynchronousReview) return defer("requires_synchronous_review");
-	if (input.tracker.latestFailedIndex > input.tracker.latestScoredIndex) return defer("scoring_failure");
-
-	const score = input.tracker.score;
-	if (!score) return defer("missing_score");
-
-	const lag = input.currentCallIndex - score.scoredAtCall;
-	if (lag > input.maxLag) return defer("stale_score");
-	if (score.authorizationVersion !== input.authorizationVersion) return defer("authorization_changed");
-	if (score.risk === "low") return { eligible: true, reason: "low_risk" };
-	return defer("elevated_risk");
-}
-
-export type ClassificationResult =
-	| { kind: ClassifierRisk; model: string }
-	| { kind: "failed"; reason: string };
-
-/**
- * Run one non-blocking classification. Output is a single token; anything else is a
- * failed sample rather than a verdict, so a confused classifier costs a review and
- * never an approval or a denial.
- */
-export async function classifyTrajectory(params: {
-	registry: Pick<ModelRegistry, "find" | "complete">;
-	modelSpec: string;
-	prompt: string;
-	timeoutMs: number;
-	signal?: AbortSignal;
-}): Promise<ClassificationResult> {
-	const parsed = parseModelSpec(params.modelSpec);
-	if (!parsed) {
-		return { kind: "failed", reason: `autoMode.classifier.model "${params.modelSpec}" is not provider/model-id.` };
-	}
-	const model = params.registry.find(parsed.provider, parsed.modelId) as Model<Api> | undefined;
-	if (!model) {
-		return { kind: "failed", reason: `Classifier model ${params.modelSpec} is not available.` };
-	}
-	const label = boundReviewText(`${model.provider}/${model.id}`, 256);
-
-	const controller = new AbortController();
-	const abortFromCaller = () => controller.abort();
-	if (params.signal?.aborted) controller.abort();
-	else params.signal?.addEventListener("abort", abortFromCaller);
-	const timer = setTimeout(() => controller.abort(), params.timeoutMs);
-
-	try {
-		const response = await params.registry.complete(
-			model,
-			{
-				systemPrompt: CLASSIFIER_SYSTEM_PROMPT,
-				messages: [
-					{
-						role: "user",
-						content: [{ type: "text", text: params.prompt }],
-						timestamp: Date.now(),
-					},
-				],
-			},
-			{ signal: controller.signal, cacheRetention: "none" },
-		);
-		if (response.stopReason === "error" || response.stopReason === "aborted") {
-			return { kind: "failed", reason: response.errorMessage ?? `Classifier stopped: ${response.stopReason}` };
-		}
-		const text = response.content
-			.filter((block): block is { type: "text"; text: string } => block.type === "text")
-			.map((block) => block.text)
-			.join("")
-			.trim()
-			.toLowerCase();
-		if (/^high\b/.test(text)) return { kind: "high", model: label };
-		if (/^low\b/.test(text)) return { kind: "low", model: label };
-		return { kind: "failed", reason: `Classifier returned unreadable output: ${boundReviewText(text, 80)}` };
-	} catch (error) {
-		return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };
-	} finally {
-		clearTimeout(timer);
-		params.signal?.removeEventListener("abort", abortFromCaller);
-	}
-}
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { parseModelSpec } from "../runtime";
+import { CLASSIFIER_SYSTEM_PROMPT } from "./prompt";
+import { boundReviewText, type ClassifierRisk, type FastDecisionReason } from "./types";
+
+/** One completed classification of the trajectory, tagged to a tool-call position. */
+export type ScoreRecord = {
+	risk: ClassifierRisk;
+	/** Tool-call counter value when the sample was taken. */
+	scoredAtCall: number;
+	/** Fingerprint of the user turns the score was based on. */
+	authorizationVersion: string;
+	sampledAt: number;
+};
+
+/**
+ * Mutable per-session tracker for the non-blocking pre-scorer.
+ *
+ * The counters reproduce Codex's staleness rule: the agent keeps running while a
+ * classification is in flight, so a score is only trustworthy if it is recent
+ * enough and nothing the user said has changed underneath it.
+ */
+export type ScoreTracker = {
+	latestCallIndex: number;
+	latestScoredIndex: number;
+	latestFailedIndex: number;
+	score?: ScoreRecord;
+};
+
+export function createScoreTracker(): ScoreTracker {
+	return { latestCallIndex: 0, latestScoredIndex: 0, latestFailedIndex: 0 };
+}
+
+/** Reset everything: a new turn or a disengaged mode invalidates prior scoring. */
+export function resetScoreTracker(tracker: ScoreTracker): void {
+	tracker.latestCallIndex = 0;
+	tracker.latestScoredIndex = 0;
+	tracker.latestFailedIndex = 0;
+	tracker.score = undefined;
+}
+
+/**
+ * Fingerprint of the user-authored conversation. Any new or edited user turn makes
+ * an existing score stale, because the score's authorization premise changed.
+ */
+export function authorizationVersion(userText: string): string {
+	const bounded = boundReviewText(userText, 8_000);
+	let hash = 2166136261;
+	for (let index = 0; index < bounded.length; index += 1) {
+		hash ^= bounded.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return `${bounded.length}:${(hash >>> 0).toString(36)}`;
+}
+
+export function recordScoredCall(tracker: ScoreTracker, score: ScoreRecord): void {
+	tracker.score = score;
+	tracker.latestScoredIndex = Math.max(tracker.latestScoredIndex, score.scoredAtCall);
+}
+
+export function recordFailedCall(tracker: ScoreTracker, scoredAtCall: number): void {
+	tracker.latestFailedIndex = Math.max(tracker.latestFailedIndex, scoredAtCall);
+}
+
+export type FastDecisionInput = {
+	tracker: ScoreTracker;
+	/** Tool-call counter value for the call being gated. */
+	currentCallIndex: number;
+	authorizationVersion: string;
+	maxLag: number;
+	/** Retries after a denial and widened gates must not take the fast path. */
+	requiresSynchronousReview?: boolean;
+};
+
+/**
+ * Decide whether a cached classification can satisfy this gated call without
+ * running the blocking reviewer. Anything other than `low_risk` defers to the
+ * synchronous review; the classifier never denies an action on its own.
+ */
+export function fastApprovalEligible(input: FastDecisionInput): {
+	eligible: boolean;
+	reason: FastDecisionReason;
+} {
+	const defer = (reason: FastDecisionReason) => ({ eligible: false, reason });
+
+	if (input.requiresSynchronousReview) return defer("requires_synchronous_review");
+	if (input.tracker.latestFailedIndex > input.tracker.latestScoredIndex) return defer("scoring_failure");
+
+	const score = input.tracker.score;
+	if (!score) return defer("missing_score");
+
+	const lag = input.currentCallIndex - score.scoredAtCall;
+	if (lag > input.maxLag) return defer("stale_score");
+	if (score.authorizationVersion !== input.authorizationVersion) return defer("authorization_changed");
+	if (score.risk === "low") return { eligible: true, reason: "low_risk" };
+	return defer("elevated_risk");
+}
+
+export type ClassificationResult =
+	| { kind: ClassifierRisk; model: string }
+	| { kind: "failed"; reason: string };
+
+/**
+ * Run one non-blocking classification. Output is a single token; anything else is a
+ * failed sample rather than a verdict, so a confused classifier costs a review and
+ * never an approval or a denial.
+ */
+export async function classifyTrajectory(params: {
+	registry: Pick<ModelRegistry, "find" | "complete">;
+	modelSpec: string;
+	prompt: string;
+	timeoutMs: number;
+	signal?: AbortSignal;
+}): Promise<ClassificationResult> {
+	const parsed = parseModelSpec(params.modelSpec);
+	if (!parsed) {
+		return { kind: "failed", reason: `autoMode.classifier.model "${params.modelSpec}" is not provider/model-id.` };
+	}
+	const model = params.registry.find(parsed.provider, parsed.modelId) as Model<Api> | undefined;
+	if (!model) {
+		return { kind: "failed", reason: `Classifier model ${params.modelSpec} is not available.` };
+	}
+	const label = boundReviewText(`${model.provider}/${model.id}`, 256);
+
+	const controller = new AbortController();
+	const abortFromCaller = () => controller.abort();
+	if (params.signal?.aborted) controller.abort();
+	else params.signal?.addEventListener("abort", abortFromCaller);
+	const timer = setTimeout(() => controller.abort(), params.timeoutMs);
+
+	try {
+		const response = await params.registry.complete(
+			model,
+			{
+				systemPrompt: CLASSIFIER_SYSTEM_PROMPT,
+				messages: [
+					{
+						role: "user",
+						content: [{ type: "text", text: params.prompt }],
+						timestamp: Date.now(),
+					},
+				],
+			},
+			{ signal: controller.signal, cacheRetention: "none" },
+		);
+		if (response.stopReason === "error" || response.stopReason === "aborted") {
+			return { kind: "failed", reason: response.errorMessage ?? `Classifier stopped: ${response.stopReason}` };
+		}
+		const text = response.content
+			.filter((block): block is { type: "text"; text: string } => block.type === "text")
+			.map((block) => block.text)
+			.join("")
+			.trim()
+			.toLowerCase();
+		if (/^high\b/.test(text)) return { kind: "high", model: label };
+		if (/^low\b/.test(text)) return { kind: "low", model: label };
+		return { kind: "failed", reason: `Classifier returned unreadable output: ${boundReviewText(text, 80)}` };
+	} catch (error) {
+		return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };
+	} finally {
+		clearTimeout(timer);
+		params.signal?.removeEventListener("abort", abortFromCaller);
+	}
+}