pi-coralbricks-provider 1.0.28 → 1.0.30

package/README.md

@@ -108,7 +108,8 @@ Thinking levels attach to the model id with `:<level>` — e.g. `:low`, `:high`,
 
 ## Provider Settings
 
-Run `/coralbricks-settings` to choose the **API surface**. The searchable,
+Run `/coralbricks-settings` to choose the **API surface** and, for Responses,
+whether to **park turns**. The searchable,
 bordered settings list matches pi's settings UI; GUI/RPC clients get a selection
 dialog. Changes are saved immediately and apply to the next request without a
 restart, including when a CoralBricks model is already selected.
@@ -117,7 +118,7 @@ Settings live at `~/.pi/agent/extensions/coralbricks.json` (or under
 `PI_CODING_AGENT_DIR` when set):
 
 ```json
-{ "api": "responses" }
+{ "api": "responses", "park": false }
 ```
 
 - **`chat-completions`** (default): uses `/v1/chat/completions`; existing behavior
@@ -126,10 +127,36 @@ Settings live at `~/.pi/agent/extensions/coralbricks.json` (or under
   tool-call, image, usage, and cancellation handling. The same model IDs and API
   key work on both surfaces. Thinking levels map to `reasoning.effort` here.
 
-Responses requests replay the full local conversation and send `store: false`.
-This integration does **not** use `previous_response_id`, server-side conversation
-storage, background jobs, or resumable streams. Coral's broader Responses API is
-documented at [coralbricks.ai/docs](https://www.coralbricks.ai/docs).
+By default, Responses requests replay the full local conversation and send
+`store: false`. This integration does not use background jobs or resumable
+streams. Coral's broader Responses API is documented at
+[coralbricks.ai/docs](https://www.coralbricks.ai/docs).
+
+### Parking (`"park": true`)
+
+With parking on, every Responses request is sent with `store: true` and the
+next request continues it with `previous_response_id`. pi still builds the full
+transcript, but only the items after the parked response (tool results, the
+next user message) go over the wire. Tools are re-sent every time because Coral
+does not carry them across a chain.
+
+A turn is chained only when the full input starts with exactly what was sent
+for the parked response, followed by that response's own output. Compaction, a
+model switch, an edited or branched history, or a pi restart falls back to a
+full replay, and that request is parked again. If Coral no longer has the parent
+(`previous_response_not_found`), the same request is re-sent once in full.
+Parked ids live in memory only.
+
+Things to know before turning it on:
+
+- Coral keeps every parked response on its side. Deleting a parent breaks the
+  chain, so the extension does not delete them.
+- Coral bills a chained request as the tool definitions plus the new items. The
+  first chained request in a session writes the tool block to cache once, and
+  later ones read it back. With a warm cache, a 7-request tool loop cost about
+  the same as a full replay on DeepSeek V4.1 Flash and about a third more on
+  GLM 5.3 Flash. The parked history itself is not billed again, which matters
+  when Coral evicts a long session's cache.
 
 Live probes verified text, automatic tool calls, tool-result replay, and switching
 back to Chat Completions on all current models. The gateway currently rejects

package/index.ts

@@ -1,7 +1,8 @@
 /**
  * CoralBricks Provider Extension
  *
- * Registers CoralBricks with Chat Completions (default) or opt-in Responses.
+ * Registers CoralBricks with Chat Completions (default) or opt-in Responses,
+ * optionally parking Responses turns with previous_response_id (park.ts).
  * Base URL: https://inference.coralbricks.ai/v1
  *
  * Model resolution strategy: Stale-While-Revalidate
@@ -33,6 +34,7 @@ import { getAgentDir, type ExtensionAPI, type ModelRegistry } from "@earendil-wo
 import type { AssistantMessageEventStream, SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
 import { clampThinkingLevel, streamOpenAICompletions, streamOpenAIResponses } from "@earendil-works/pi-ai/compat";
 import { loadConfig, registerSettingsCommand } from "./settings";
+import { park, planPark, withParkFallback, type ParkPlan } from "./park";
 import modelsData from "./models.json" with { type: "json" };
 import customModelsData from "./custom-models.json" with { type: "json" };
 import patchData from "./patch.json" with { type: "json" };
@@ -449,10 +451,18 @@ async function revalidateModels(apiKey: string | undefined, embeddedModels: Json
   return merged;
 }
 
+/** pi-ai's clampOpenAIPromptCacheKey, inlined: Coral accepts the same field. */
+function clampPromptCacheKey(key: string | undefined): string | undefined {
+  if (key === undefined) return undefined;
+  const chars = Array.from(key);
+  return chars.length <= 64 ? key : chars.slice(0, 64).join("");
+}
+
 export function streamCoral(
   model: any,
   context: any,
   options?: SimpleStreamOptions,
+  settings: { park?: boolean } = {},
 ): AssistantMessageEventStream {
   const apiKey = options?.apiKey || cachedApiKey || "";
   if (!apiKey) {
@@ -469,12 +479,58 @@ export function streamCoral(
   const reasoningEffort = clampedReasoning === "off" ? undefined : clampedReasoning;
   const { reasoning: _reasoning, ...streamOptions } = options ?? {};
 
-  const stream = model.api === "openai-responses" ? streamOpenAIResponses : streamOpenAICompletions;
-  return stream(model, context, {
+  // Coral groups a conversation's turns by the first session id it finds: a
+  // session header, else the body's prompt_cache_key. pi-ai only sends the id as
+  // x-session-affinity on Chat Completions when a model opts in (forced below),
+  // and omits prompt_cache_key there for every base URL but api.openai.com, so
+  // send Coral's own header on both surfaces and the body key on Completions.
+  const sessionId = (streamOptions as any).sessionId as string | undefined;
+  const sessionHeaders = sessionId
+    ? { "x-coral-session": sessionId, ...((streamOptions as any).headers ?? {}) }
+    : (streamOptions as any).headers;
+  const promptCacheKey = (streamOptions as any).cacheRetention === "none" ? undefined : clampPromptCacheKey(sessionId);
+  const withPromptCacheKey = (params: any) => {
+    if (!promptCacheKey || params?.prompt_cache_key !== undefined) return params;
+    return { ...params, prompt_cache_key: promptCacheKey };
+  };
+
+  const compat = { ...model.compat, sendSessionAffinityHeaders: true };
+  const streamModel = { ...model, compat };
+
+  if (streamModel.api !== "openai-responses") {
+    const onPayload = (streamOptions as any).onPayload;
+    return streamOpenAICompletions(streamModel, context, {
+      ...streamOptions,
+      headers: sessionHeaders,
+      reasoningEffort,
+      apiKey,
+      onPayload: async (params: any, payloadModel: any) => withPromptCacheKey((await onPayload?.(params, payloadModel)) ?? params),
+    } as any);
+  }
+  if (!settings.park) {
+    return streamOpenAIResponses(streamModel, context, { ...streamOptions, headers: sessionHeaders, reasoningEffort, apiKey } as any);
+  }
+
+  let plan: ParkPlan | undefined;
+  const baseFetch = (streamOptions as any).fetch ?? ((input: any, init?: any) => globalThis.fetch(input, init));
+  const stream = streamOpenAIResponses(streamModel, context, {
     ...streamOptions,
+    headers: sessionHeaders,
     reasoningEffort,
     apiKey,
+    fetch: withParkFallback(baseFetch, () => plan),
+    onPayload: async (params: any, payloadModel: any) => {
+      const replaced = await options?.onPayload?.(params, payloadModel);
+      plan = planPark(withPromptCacheKey(replaced ?? params), context?.messages, model);
+      return plan.params;
+    },
   } as any);
+  void stream.result().then((message: any) => {
+    if (plan && message?.responseId && message.stopReason !== "error" && message.stopReason !== "aborted") {
+      park(message.responseId, model.id, plan.input);
+    }
+  }, () => {});
+  return stream;
 }
 
 // API Key Resolution (via ModelRegistry)
@@ -504,7 +560,7 @@ export default function (pi: ExtensionAPI) {
       models: currentModels,
       // An already-selected model may still carry the previous API. Snapshot
       // the current selection per request, without mutating that model/history.
-      streamSimple: (model, context, options) => streamCoral({ ...model, api: selectedApi() }, context, options),
+      streamSimple: (model, context, options) => streamCoral({ ...model, api: selectedApi() }, context, options, { park: config.park }),
     });
   }
   registerProvider();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-coralbricks-provider",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "CoralBricks provider extension for pi - Access GLM 5.3 and DeepSeek V4.1 Flash (FP4 variants included) through the Coral Inference API",
   "author": "monotykamary",
   "homepage": "https://github.com/monotykamary/pi-coralbricks-provider#readme",
@@ -38,6 +38,7 @@
   "files": [
     "index.ts",
     "settings.ts",
+    "park.ts",
     "models.json",
     "deprecated-models.json",
     "custom-models.json",

package/park.ts

@@ -0,0 +1,122 @@
+/**
+ * Parking: continue Coral Responses turns with `previous_response_id`.
+ *
+ * pi replays the whole transcript on every request. With parking on, each
+ * response is stored on Coral (`store: true`) and the next request sends only
+ * the items that came after it (tool results, the next user message). Coral
+ * keeps the parked state, sticky-routes the chain to the same replica and
+ * bills only the new input.
+ *
+ * A chain is used only when the full input pi would have sent starts with
+ * exactly the input of the parked request, followed by that response's own
+ * output items. Anything else (compaction, a model switch, an edited or
+ * branched history, a restart) sends the full transcript, which parks again.
+ * If Coral no longer has the parent (`previous_response_not_found`), the same
+ * request is re-sent once in full.
+ */
+import { createHash } from "node:crypto";
+
+type Item = Record<string, unknown>;
+
+interface ParkedTurn {
+  model: string;
+  /** Digests of the full input sent with the request that produced this response. */
+  input: string[];
+}
+
+export interface ParkPlan {
+  /** Request body to send. */
+  params: Record<string, any>;
+  /** Full-transcript body to re-send if the parent is gone; undefined when not chained. */
+  fallback?: Record<string, any>;
+  /** Digests of the full input, recorded against the response id on success. */
+  input: string[];
+}
+
+const MAX_PARKED = 256;
+const parked = new Map<string, ParkedTurn>();
+
+function digest(item: unknown): string {
+  return createHash("sha256").update(JSON.stringify(item)).digest("base64url");
+}
+
+function isOutputItem(item: Item): boolean {
+  return item.type === "reasoning"
+    || item.type === "function_call"
+    || item.type === "custom_tool_call"
+    || (item.type === "message" && item.role === "assistant");
+}
+
+/** The last assistant message, if it is a completed Coral Responses turn from this model. */
+function parentId(messages: any[] | undefined, model: { id: string; provider: string }): string | undefined {
+  for (let i = (messages?.length ?? 0) - 1; i >= 0; i--) {
+    const msg = messages![i];
+    if (msg?.role !== "assistant") continue;
+    const ok = typeof msg.responseId === "string"
+      && msg.provider === model.provider
+      && msg.api === "openai-responses"
+      && msg.model === model.id
+      && msg.stopReason !== "error"
+      && msg.stopReason !== "aborted";
+    return ok ? msg.responseId : undefined;
+  }
+  return undefined;
+}
+
+export function planPark(params: Record<string, any>, messages: any[] | undefined, model: { id: string; provider: string }): ParkPlan {
+  const full: Item[] = Array.isArray(params.input) ? params.input : [];
+  const input = full.map(digest);
+  const stored: Record<string, any> = { ...params, store: true };
+  delete stored.previous_response_id;
+
+  const id = parentId(messages, model);
+  const turn = id ? parked.get(id) : undefined;
+  if (!id || !turn || turn.model !== model.id || turn.input.length > input.length) return { params: stored, input };
+  for (let i = 0; i < turn.input.length; i++) {
+    if (turn.input[i] !== input[i]) return { params: stored, input };
+  }
+
+  // Skip the parent's own output; Coral already holds it.
+  let start = turn.input.length;
+  while (start < full.length && isOutputItem(full[start])) start++;
+  const delta = full.slice(start);
+  if (delta.length === 0 || delta.some(isOutputItem)) return { params: stored, input };
+
+  return { params: { ...stored, previous_response_id: id, input: delta }, fallback: stored, input };
+}
+
+export function park(responseId: string, model: string, input: string[]): void {
+  parked.delete(responseId);
+  parked.set(responseId, { model, input });
+  while (parked.size > MAX_PARKED) parked.delete(parked.keys().next().value!);
+}
+
+export function forget(responseId: string): void {
+  parked.delete(responseId);
+}
+
+export function clearParked(): void {
+  parked.clear();
+}
+
+export function isParentMissing(status: number, body: string): boolean {
+  return (status === 404 || status === 400) && body.includes("previous_response_not_found");
+}
+
+/**
+ * Wrap fetch so a chained request whose parent Coral no longer has is re-sent
+ * once with the full transcript. Every other response passes through untouched.
+ */
+export function withParkFallback(base: typeof fetch, plan: () => ParkPlan | undefined): typeof fetch {
+  return async (input: any, init?: any) => {
+    const response = await base(input, init);
+    const current = plan();
+    if (response.ok || !current?.fallback) return response;
+    const body = await response.clone().text().catch(() => "");
+    if (!isParentMissing(response.status, body)) return response;
+    forget(current.params.previous_response_id);
+    const headers = new Headers(init?.headers);
+    headers.delete("content-length");
+    return base(input, { ...init, headers, body: JSON.stringify(current.fallback) });
+  };
+}

package/settings.ts

@@ -4,7 +4,7 @@ import path from "node:path";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 export type CoralApi = "chat-completions" | "responses";
-export interface CoralConfig { api: CoralApi }
+export interface CoralConfig { api: CoralApi; park: boolean }
 
 export function configPath(): string {
   return path.join(getAgentDir(), "extensions", "coralbricks.json");
@@ -23,16 +23,16 @@ function readRawConfig(): Record<string, unknown> {
 
 export function loadConfig(): CoralConfig {
   try {
-    return { api: readRawConfig().api === "responses" ? "responses" : "chat-completions" };
+    const raw = readRawConfig();
+    return { api: raw.api === "responses" ? "responses" : "chat-completions", park: raw.park === true };
   } catch {
-    return { api: "chat-completions" };
+    return { api: "chat-completions", park: false };
   }
 }
 
 /** Preserve unrelated fields; never overwrite malformed settings. */
-export function saveApi(api: CoralApi): void {
-  const raw = readRawConfig();
-  raw.api = api;
+export function saveConfig(patch: Partial<CoralConfig>): void {
+  const raw = { ...readRawConfig(), ...patch };
   const file = configPath();
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const temporary = `${file}.${randomUUID()}.tmp`;
@@ -44,35 +44,49 @@ export function saveApi(api: CoralApi): void {
   }
 }
 
+export function saveApi(api: CoralApi): void {
+  saveConfig({ api });
+}
+
+const PARK_DESCRIPTION = "Responses only. Stores each response on Coral (store:true) and sends only new items with previous_response_id. Falls back to a full replay when the chain does not match.";
+
 export function registerSettingsCommand(
   pi: ExtensionAPI,
   getConfig: () => CoralConfig,
   apply: (config: CoralConfig) => void,
 ): void {
   pi.registerCommand("coralbricks-settings", {
-    description: "Configure CoralBricks API: Chat Completions or opt-in Responses",
+    description: "Configure CoralBricks API (Chat Completions or opt-in Responses) and Responses parking",
     async handler(_args, ctx) {
       if (!ctx.hasUI) {
         ctx.ui.notify("/coralbricks-settings requires a UI (TUI or GUI).", "error");
         return;
       }
       const values: CoralApi[] = ["chat-completions", "responses"];
-      const change = (value: string): boolean => {
-        if (!values.includes(value as CoralApi)) return false;
+      const parkValues = ["off", "on"];
+      const change = (id: string, value: string): boolean => {
+        let patch: Partial<CoralConfig>;
+        if (id === "api" && values.includes(value as CoralApi)) patch = { api: value as CoralApi };
+        else if (id === "park" && parkValues.includes(value)) patch = { park: value === "on" };
+        else return false;
         try {
-          saveApi(value as CoralApi);
+          saveConfig(patch);
         } catch {
           ctx.ui.notify(`Could not save ${configPath()}. Check its JSON and permissions; API unchanged.`, "error");
           return false;
         }
-        apply({ api: value as CoralApi });
-        ctx.ui.notify(`CoralBricks API: ${value} — applies to the next request.`, "info");
+        const next = { ...getConfig(), ...patch };
+        apply(next);
+        const label = id === "api" ? `CoralBricks API: ${value}` : `CoralBricks parking: ${value}`;
+        ctx.ui.notify(`${label} — applies to the next request.`, "info");
         return true;
       };
 
       if (ctx.mode !== "tui") {
         const selected = await ctx.ui.select(`CoralBricks API (current: ${getConfig().api})`, values);
-        if (selected !== undefined) change(selected);
+        if (selected === undefined || !change("api", selected) || selected !== "responses") return;
+        const park = await ctx.ui.select(`Park Responses turns with previous_response_id? (current: ${getConfig().park ? "on" : "off"})`, parkValues);
+        if (park !== undefined) change("park", park);
         return;
       }
 
@@ -87,12 +101,19 @@ export function registerSettingsCommand(
           {
             id: "api",
             label: "API surface",
-            description: "Chat Completions is the default. Responses is opt-in, replays full history with store:false; no server-side threading or background jobs.",
+            description: "Chat Completions is the default. Responses is opt-in; it replays full history with store:false unless parking is on.",
             currentValue: getConfig().api,
             values,
           },
-        ], 3, getSettingsListTheme(), (_id, value) => {
-          if (!change(value)) list.updateValue("api", getConfig().api);
+          {
+            id: "park",
+            label: "Park Responses turns",
+            description: PARK_DESCRIPTION,
+            currentValue: getConfig().park ? "on" : "off",
+            values: parkValues,
+          },
+        ], 3, getSettingsListTheme(), (id, value) => {
+          if (!change(id, value)) list.updateValue(id, id === "api" ? getConfig().api : getConfig().park ? "on" : "off");
         }, () => done(), { enableSearch: true });
         container.addChild(list);
         container.addChild(border());