pi-openai-toolkit 0.14.4 → 0.14.6

package/src/codex-astra/effort-planner.ts

@@ -1,175 +1,175 @@
-import { createHash } from "node:crypto";
-
-/**
- * Stable request-level reasoning effort via `configuration_update` input items
- * (GPT-6 Astra), ported from Oh My Pi (`@oh-my-pi/pi-ai`, MIT licensed,
- * Copyright (c) 2025-2026 Can Bölük / Stencil Labs) to an extension-side
- * payload rewrite.
- *
- * The request-level `reasoning.effort` is pinned to the value of the session's
- * first request so the cached prompt prefix survives an effort change. Each
- * later change is carried as a `configuration_update` item inserted at the
- * tail of the transcript — before the user message it takes effect on, or
- * after the latest tool result when the level changes inside a tool loop — and
- * replayed at that position on every subsequent request until another update
- * overrides it.
- *
- * Wire constraints (verified upstream against the Codex backend): only
- * `gpt-6-astra` accepts the item type, consecutive updates are rejected, and
- * `/responses/compact` rejects histories containing them — compaction
- * requests are built outside this planner and never carry the items.
- */
-
-/** `configuration_update` input item; only `reasoning.effort` is updatable. */
-export type ConfigurationUpdateItem = {
-	type: "configuration_update";
-	reasoning: { effort: string };
-};
-
-export type PlannableInputItem = {
-	type?: string | null;
-	role?: string;
-	id?: string | null;
-	status?: string | null;
-	[key: string]: unknown;
-};
-
-type EffortTransition = {
-	/** Input-array position the item is spliced into (before `input[index]`). */
-	index: number;
-	/** Fingerprint of `input[index - 1]` at record time; a mismatch means the history was rewritten. */
-	anchor: string;
-	effort: string;
-};
-
-/** Per-conversation effort baseline and recorded transitions. */
-export type EffortControlState = {
-	baseEffort?: string;
-	currentEffort?: string;
-	transitions: EffortTransition[];
-};
-
-export type EffortPlanResult = {
-	/** The request-level effort that must accompany the returned input. */
-	effort: string;
-	/** Number of `configuration_update` items spliced into this request. */
-	spliced: number;
-};
-
-export function createEffortControlState(): EffortControlState {
-	return { transitions: [] };
-}
-
-const MAX_EFFORT_CONTROL_STATES = 16;
-
-/**
- * Fetch (or create) the control state for one conversation from a bounded
- * LRU map, refreshing its slot.
- */
-export function getEffortControlState(states: Map<string, EffortControlState>, key: string): EffortControlState {
-	const existing = states.get(key);
-	if (existing) {
-		states.delete(key);
-		states.set(key, existing);
-		return existing;
-	}
-	const created = createEffortControlState();
-	states.set(key, created);
-	if (states.size > MAX_EFFORT_CONTROL_STATES) {
-		const oldest = states.keys().next().value;
-		if (oldest !== undefined) states.delete(oldest);
-	}
-	return created;
-}
-
-/**
- * Fingerprint of the item a transition sits after. Output-only lifecycle
- * fields are excluded: a live response item carries `id`/`status` that the
- * sanitized replay of the same item drops.
- */
-function transitionAnchor(input: readonly PlannableInputItem[], index: number): string {
-	if (index === 0) return "";
-	const item = input[index - 1];
-	if (!item) return "";
-	const { id: _id, status: _status, ...stable } = item;
-	return createHash("sha1").update(JSON.stringify(stable)).digest("hex");
-}
-
-function resetEffortControlState(state: EffortControlState): void {
-	state.baseEffort = undefined;
-	state.currentEffort = undefined;
-	state.transitions = [];
-}
-
-/**
- * Discard the baseline when the request no longer continues the conversation
- * it was captured for: a wire history that shrank or was rewritten under a
- * recorded transition (compaction, branch switch, `/clear`). The next request
- * re-baselines from its own effort, which is what the API asks for after
- * compaction anyway.
- */
-function syncEffortControlState(state: EffortControlState, input: readonly PlannableInputItem[]): void {
-	for (const transition of state.transitions) {
-		if (transition.index > input.length || transition.anchor !== transitionAnchor(input, transition.index)) {
-			resetEffortControlState(state);
-			return;
-		}
-	}
-}
-
-/**
- * Pin the request-level effort to the session baseline and splice pending
- * `configuration_update` items into a copy of `input`.
- *
- * `input` is the freshly built transcript for this request, without any
- * `configuration_update` items. `requested` is the wire effort the caller
- * would otherwise send at the request level.
- */
-export function planStableEffort(
-	state: EffortControlState,
-	input: readonly PlannableInputItem[],
-	requested: string,
-): { input: Array<PlannableInputItem | ConfigurationUpdateItem>; result: EffortPlanResult } {
-	const next: Array<PlannableInputItem | ConfigurationUpdateItem> = [...input];
-	syncEffortControlState(state, next);
-	if (state.baseEffort === undefined) {
-		state.baseEffort = requested;
-		state.currentEffort = requested;
-		return { input: next, result: { effort: requested, spliced: 0 } };
-	}
-	if (state.currentEffort !== requested) {
-		const last = next[next.length - 1];
-		const index = last && last.role === "user" ? next.length - 1 : next.length;
-		const existing = state.transitions.find((transition) => transition.index === index);
-		if (existing) {
-			existing.effort = requested;
-		} else {
-			state.transitions.push({ index, anchor: transitionAnchor(next, index), effort: requested });
-		}
-		// A change back to the effort already in force at that position is a
-		// no-op on the wire; drop it rather than send a redundant item.
-		let preceding = state.baseEffort;
-		let precedingIndex = -1;
-		for (const transition of state.transitions) {
-			if (transition.index < index && transition.index > precedingIndex) {
-				preceding = transition.effort;
-				precedingIndex = transition.index;
-			}
-		}
-		if (requested === preceding) {
-			state.transitions = state.transitions.filter((transition) => transition.index !== index);
-		}
-		state.currentEffort = requested;
-	}
-	// Splice in ascending order so each insertion offsets only the ones after it.
-	state.transitions.sort((a, b) => a.index - b.index);
-	let offset = 0;
-	for (const transition of state.transitions) {
-		next.splice(transition.index + offset, 0, {
-			type: "configuration_update",
-			reasoning: { effort: transition.effort },
-		});
-		offset++;
-	}
-	return { input: next, result: { effort: state.baseEffort, spliced: state.transitions.length } };
-}
+import { createHash } from "node:crypto";
+
+/**
+ * Stable request-level reasoning effort via `configuration_update` input items
+ * (GPT-6 Astra), ported from Oh My Pi (`@oh-my-pi/pi-ai`, MIT licensed,
+ * Copyright (c) 2025-2026 Can Bölük / Stencil Labs) to an extension-side
+ * payload rewrite.
+ *
+ * The request-level `reasoning.effort` is pinned to the value of the session's
+ * first request so the cached prompt prefix survives an effort change. Each
+ * later change is carried as a `configuration_update` item inserted at the
+ * tail of the transcript — before the user message it takes effect on, or
+ * after the latest tool result when the level changes inside a tool loop — and
+ * replayed at that position on every subsequent request until another update
+ * overrides it.
+ *
+ * Wire constraints (verified upstream against the Codex backend): only
+ * `gpt-6-astra` accepts the item type, consecutive updates are rejected, and
+ * `/responses/compact` rejects histories containing them — compaction
+ * requests are built outside this planner and never carry the items.
+ */
+
+/** `configuration_update` input item; only `reasoning.effort` is updatable. */
+export type ConfigurationUpdateItem = {
+	type: "configuration_update";
+	reasoning: { effort: string };
+};
+
+export type PlannableInputItem = {
+	type?: string | null;
+	role?: string;
+	id?: string | null;
+	status?: string | null;
+	[key: string]: unknown;
+};
+
+type EffortTransition = {
+	/** Input-array position the item is spliced into (before `input[index]`). */
+	index: number;
+	/** Fingerprint of `input[index - 1]` at record time; a mismatch means the history was rewritten. */
+	anchor: string;
+	effort: string;
+};
+
+/** Per-conversation effort baseline and recorded transitions. */
+export type EffortControlState = {
+	baseEffort?: string;
+	currentEffort?: string;
+	transitions: EffortTransition[];
+};
+
+export type EffortPlanResult = {
+	/** The request-level effort that must accompany the returned input. */
+	effort: string;
+	/** Number of `configuration_update` items spliced into this request. */
+	spliced: number;
+};
+
+export function createEffortControlState(): EffortControlState {
+	return { transitions: [] };
+}
+
+const MAX_EFFORT_CONTROL_STATES = 16;
+
+/**
+ * Fetch (or create) the control state for one conversation from a bounded
+ * LRU map, refreshing its slot.
+ */
+export function getEffortControlState(states: Map<string, EffortControlState>, key: string): EffortControlState {
+	const existing = states.get(key);
+	if (existing) {
+		states.delete(key);
+		states.set(key, existing);
+		return existing;
+	}
+	const created = createEffortControlState();
+	states.set(key, created);
+	if (states.size > MAX_EFFORT_CONTROL_STATES) {
+		const oldest = states.keys().next().value;
+		if (oldest !== undefined) states.delete(oldest);
+	}
+	return created;
+}
+
+/**
+ * Fingerprint of the item a transition sits after. Output-only lifecycle
+ * fields are excluded: a live response item carries `id`/`status` that the
+ * sanitized replay of the same item drops.
+ */
+function transitionAnchor(input: readonly PlannableInputItem[], index: number): string {
+	if (index === 0) return "";
+	const item = input[index - 1];
+	if (!item) return "";
+	const { id: _id, status: _status, ...stable } = item;
+	return createHash("sha1").update(JSON.stringify(stable)).digest("hex");
+}
+
+function resetEffortControlState(state: EffortControlState): void {
+	state.baseEffort = undefined;
+	state.currentEffort = undefined;
+	state.transitions = [];
+}
+
+/**
+ * Discard the baseline when the request no longer continues the conversation
+ * it was captured for: a wire history that shrank or was rewritten under a
+ * recorded transition (compaction, branch switch, `/clear`). The next request
+ * re-baselines from its own effort, which is what the API asks for after
+ * compaction anyway.
+ */
+function syncEffortControlState(state: EffortControlState, input: readonly PlannableInputItem[]): void {
+	for (const transition of state.transitions) {
+		if (transition.index > input.length || transition.anchor !== transitionAnchor(input, transition.index)) {
+			resetEffortControlState(state);
+			return;
+		}
+	}
+}
+
+/**
+ * Pin the request-level effort to the session baseline and splice pending
+ * `configuration_update` items into a copy of `input`.
+ *
+ * `input` is the freshly built transcript for this request, without any
+ * `configuration_update` items. `requested` is the wire effort the caller
+ * would otherwise send at the request level.
+ */
+export function planStableEffort(
+	state: EffortControlState,
+	input: readonly PlannableInputItem[],
+	requested: string,
+): { input: Array<PlannableInputItem | ConfigurationUpdateItem>; result: EffortPlanResult } {
+	const next: Array<PlannableInputItem | ConfigurationUpdateItem> = [...input];
+	syncEffortControlState(state, next);
+	if (state.baseEffort === undefined) {
+		state.baseEffort = requested;
+		state.currentEffort = requested;
+		return { input: next, result: { effort: requested, spliced: 0 } };
+	}
+	if (state.currentEffort !== requested) {
+		const last = next[next.length - 1];
+		const index = last && last.role === "user" ? next.length - 1 : next.length;
+		const existing = state.transitions.find((transition) => transition.index === index);
+		if (existing) {
+			existing.effort = requested;
+		} else {
+			state.transitions.push({ index, anchor: transitionAnchor(next, index), effort: requested });
+		}
+		// A change back to the effort already in force at that position is a
+		// no-op on the wire; drop it rather than send a redundant item.
+		let preceding = state.baseEffort;
+		let precedingIndex = -1;
+		for (const transition of state.transitions) {
+			if (transition.index < index && transition.index > precedingIndex) {
+				preceding = transition.effort;
+				precedingIndex = transition.index;
+			}
+		}
+		if (requested === preceding) {
+			state.transitions = state.transitions.filter((transition) => transition.index !== index);
+		}
+		state.currentEffort = requested;
+	}
+	// Splice in ascending order so each insertion offsets only the ones after it.
+	state.transitions.sort((a, b) => a.index - b.index);
+	let offset = 0;
+	for (const transition of state.transitions) {
+		next.splice(transition.index + offset, 0, {
+			type: "configuration_update",
+			reasoning: { effort: transition.effort },
+		});
+		offset++;
+	}
+	return { input: next, result: { effort: state.baseEffort, spliced: state.transitions.length } };
+}

package/src/codex-astra/extension.ts

@@ -1,122 +1,122 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { ASTRA_MODEL_ID } from "../types";
-import { CODEX_CLIENT_VERSION } from "../responses-headers";
-import {
-	getEffortControlState,
-	planStableEffort,
-	type EffortControlState,
-	type PlannableInputItem,
-} from "./effort-planner";
-
-type AstraPayload = {
-	model: string;
-	input: PlannableInputItem[];
-	reasoning: { effort: string; [key: string]: unknown };
-	[key: string]: unknown;
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
-/**
- * Recognize the live Codex Responses request body: model + wire input array
- * + a request-level string effort. Anything else (titles, embeddings, or a
- * shape we do not understand) is left untouched.
- */
-function parseAstraPayload(payload: unknown): AstraPayload | undefined {
-	if (!isRecord(payload)) return undefined;
-	if (typeof payload.model !== "string") return undefined;
-	if (!Array.isArray(payload.input)) return undefined;
-	const reasoning = payload.reasoning;
-	if (!isRecord(reasoning) || typeof reasoning.effort !== "string") return undefined;
-	if (reasoning.effort.length === 0 || reasoning.effort === "none") return undefined;
-	if (!payload.input.every((item) => isRecord(item))) return undefined;
-	return payload as unknown as AstraPayload;
-}
-
-function isCompactionShaped(payload: AstraPayload): boolean {
-	// A `compaction_trigger` history belongs to a compact endpoint request,
-	// which rejects `configuration_update` items. Our compaction clients use
-	// direct fetch and never reach this hook; this guard covers any future
-	// provider-routed compaction.
-	const last = payload.input[payload.input.length - 1];
-	return !!last && isRecord(last) && last.type === "compaction_trigger";
-}
-
-function getSessionId(ctx: { sessionManager: { getSessionId(): string } }): string | undefined {
-	try {
-		return ctx.sessionManager.getSessionId();
-	} catch {
-		return undefined;
-	}
-}
-
-export function registerCodexAstraExtension(pi: ExtensionAPI): void {
-	const states = new Map<string, EffortControlState>();
-
-	// Switching or forking a session rebuilds the runtime and re-fires
-	// session_start; clearing there covers every replacement path.
-	pi.on("session_start", () => {
-		states.clear();
-	});
-
-	pi.on("before_provider_request", (event, ctx) => {
-		try {
-			// Silent activation by design: the Astra compatibility layer exists only
-			// to keep `gpt-6-astra` working through the Codex backend gate, so it
-			// keys off the bare model id instead of an operator allowlist.
-			const model = ctx.model;
-			// Both Responses wire families carry the same reasoning.effort prefix
-			// problem, and upstream OMP plans on both providers.
-			if (!model || (model.api !== "openai-codex-responses" && model.api !== "openai-responses")) {
-				return undefined;
-			}
-			if (model.id !== ASTRA_MODEL_ID) return undefined;
-
-			const payload = parseAstraPayload(event.payload);
-			// The payload must belong to the model the eligibility check just
-			// passed; a mismatch means this request is not ours to plan.
-			if (!payload || payload.model !== model.id) return undefined;
-			if (isCompactionShaped(payload)) return undefined;
-
-			const sessionId = getSessionId(ctx);
-			const state = getEffortControlState(
-				states,
-				`${model.baseUrl ?? ""}\u0000${model.id}\u0000${sessionId ?? "no-session"}`,
-			);
-
-			// Idempotence: never plan on top of items a previous pass injected.
-			const history = payload.input.filter((item) => item.type !== "configuration_update");
-			const { input, result } = planStableEffort(state, history, payload.reasoning.effort);
-			if (result.effort === payload.reasoning.effort && result.spliced === 0) return undefined;
-
-			return {
-				...payload,
-				input,
-				reasoning: { ...payload.reasoning, effort: result.effort },
-			};
-		} catch {
-			// A planner failure must never break the provider request path.
-			return undefined;
-		}
-	});
-
-	pi.on("before_provider_headers", (event, ctx) => {
-		try {
-			const model = ctx.model;
-			if (!model || model.api !== "openai-codex-responses") return;
-			// Live requests need the same backend version gate as our synthetic
-			// ones: an old or missing `version` never reaches gated SKUs.
-			if (!event.headers.version) {
-				event.headers.version = CODEX_CLIENT_VERSION;
-			}
-		} catch {
-			// Header injection is best-effort.
-		}
-	});
-}
-
-export default function codexAstraExtension(pi: ExtensionAPI): void {
-	registerCodexAstraExtension(pi);
-}
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ASTRA_MODEL_ID } from "../types";
+import { CODEX_CLIENT_VERSION } from "../responses-headers";
+import {
+	getEffortControlState,
+	planStableEffort,
+	type EffortControlState,
+	type PlannableInputItem,
+} from "./effort-planner";
+
+type AstraPayload = {
+	model: string;
+	input: PlannableInputItem[];
+	reasoning: { effort: string; [key: string]: unknown };
+	[key: string]: unknown;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Recognize the live Codex Responses request body: model + wire input array
+ * + a request-level string effort. Anything else (titles, embeddings, or a
+ * shape we do not understand) is left untouched.
+ */
+function parseAstraPayload(payload: unknown): AstraPayload | undefined {
+	if (!isRecord(payload)) return undefined;
+	if (typeof payload.model !== "string") return undefined;
+	if (!Array.isArray(payload.input)) return undefined;
+	const reasoning = payload.reasoning;
+	if (!isRecord(reasoning) || typeof reasoning.effort !== "string") return undefined;
+	if (reasoning.effort.length === 0 || reasoning.effort === "none") return undefined;
+	if (!payload.input.every((item) => isRecord(item))) return undefined;
+	return payload as unknown as AstraPayload;
+}
+
+function isCompactionShaped(payload: AstraPayload): boolean {
+	// A `compaction_trigger` history belongs to a compact endpoint request,
+	// which rejects `configuration_update` items. Our compaction clients use
+	// direct fetch and never reach this hook; this guard covers any future
+	// provider-routed compaction.
+	const last = payload.input[payload.input.length - 1];
+	return !!last && isRecord(last) && last.type === "compaction_trigger";
+}
+
+function getSessionId(ctx: { sessionManager: { getSessionId(): string } }): string | undefined {
+	try {
+		return ctx.sessionManager.getSessionId();
+	} catch {
+		return undefined;
+	}
+}
+
+export function registerCodexAstraExtension(pi: ExtensionAPI): void {
+	const states = new Map<string, EffortControlState>();
+
+	// Switching or forking a session rebuilds the runtime and re-fires
+	// session_start; clearing there covers every replacement path.
+	pi.on("session_start", () => {
+		states.clear();
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		try {
+			// Silent activation by design: the Astra compatibility layer exists only
+			// to keep `gpt-6-astra` working through the Codex backend gate, so it
+			// keys off the bare model id instead of an operator allowlist.
+			const model = ctx.model;
+			// Both Responses wire families carry the same reasoning.effort prefix
+			// problem, and upstream OMP plans on both providers.
+			if (!model || (model.api !== "openai-codex-responses" && model.api !== "openai-responses")) {
+				return undefined;
+			}
+			if (model.id !== ASTRA_MODEL_ID) return undefined;
+
+			const payload = parseAstraPayload(event.payload);
+			// The payload must belong to the model the eligibility check just
+			// passed; a mismatch means this request is not ours to plan.
+			if (!payload || payload.model !== model.id) return undefined;
+			if (isCompactionShaped(payload)) return undefined;
+
+			const sessionId = getSessionId(ctx);
+			const state = getEffortControlState(
+				states,
+				`${model.baseUrl ?? ""}\u0000${model.id}\u0000${sessionId ?? "no-session"}`,
+			);
+
+			// Idempotence: never plan on top of items a previous pass injected.
+			const history = payload.input.filter((item) => item.type !== "configuration_update");
+			const { input, result } = planStableEffort(state, history, payload.reasoning.effort);
+			if (result.effort === payload.reasoning.effort && result.spliced === 0) return undefined;
+
+			return {
+				...payload,
+				input,
+				reasoning: { ...payload.reasoning, effort: result.effort },
+			};
+		} catch {
+			// A planner failure must never break the provider request path.
+			return undefined;
+		}
+	});
+
+	pi.on("before_provider_headers", (event, ctx) => {
+		try {
+			const model = ctx.model;
+			if (!model || model.api !== "openai-codex-responses") return;
+			// Live requests need the same backend version gate as our synthetic
+			// ones: an old or missing `version` never reaches gated SKUs.
+			if (!event.headers.version) {
+				event.headers.version = CODEX_CLIENT_VERSION;
+			}
+		} catch {
+			// Header injection is best-effort.
+		}
+	});
+}
+
+export default function codexAstraExtension(pi: ExtensionAPI): void {
+	registerCodexAstraExtension(pi);
+}