@inhuman.tools/harness 0.0.0-stage → 0.1.0

package/dist/providers/openai-compat/cache-affinity.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Prompt-cache routing for openai-compat completions.
+ *
+ * Caching itself is automatic prefix match (exact head of tools + messages).
+ * These fields only pin the request to a replica that still holds that KV.
+ * They are completion-only — handshake `/models` does not send them.
+ *
+ * Local / unknown hosts get an empty bag: extra keys 400 on LM Studio / Ollama.
+ *
+ * GROK.
+ * "The xAI API performs prompt caching automatically. However, we recommend
+ * setting the `x-grok-conv-id` HTTP header to maximize your cache hit rate."
+ * https://docs.x.ai/developers/advanced-api-usage/prompt-caching
+ * Chat Completions: header `x-grok-conv-id` ("routes requests with the same
+ * conversation ID to the same server. Since cache entries are stored
+ * per-server, this maximizes your cache hit rate.").
+ * https://docs.x.ai/developers/advanced-api-usage/prompt-caching/maximizing-cache-hits
+ * Body `prompt_cache_key` is plumbed to the same affinity (OpenAPI ChatRequest).
+ * grok-shell against cli-chat-proxy also stamps `x-grok-session-id` to the
+ * same session id (sticky pair) and `x-grok-req-id` per invocation — unique
+ * ids belong there, not on conv-id. `x-grok-turn-idx` is 1-based user-turn
+ * depth (SessionTurn chain), stable across ReACT rounds of one prompt.
+ * Remainder classifier PEWs must not reuse the live-tape id: they send a
+ * different prefix (`Reply in prose`, no tools) and evict the tape KV.
+ *
+ * CHATGPT / CODEX SUBSCRIPTION.
+ * Replica stickiness is the `session-id` / `thread-id` headers (Codex
+ * `build_session_headers`). Body `prompt_cache_key` is still sent; the
+ * backend rewrites it per response and does not route on it. The
+ * subscription 400s `store: true` and `prompt_cache_options`.
+ * Model names do not establish endpoint capabilities.
+ *
+ * OPENAI PUBLIC API.
+ * "Set `prompt_cache_key` on requests that share long, common prompt prefixes."
+ * "Replaces the `user` field." No cache HTTP headers — body only.
+ * https://developers.openai.com/api/docs/guides/prompt-caching
+ * GPT-5.6+: `prompt_cache_options.ttl` `"30m"` (default); `mode` `implicit`
+ * places a breakpoint on the latest eligible message. Earlier models:
+ * `prompt_cache_retention` `"24h"` when the org is not ZDR. Sending
+ * `prompt_cache_options` to pre-5.6 (Azure) is a 400.
+ *
+ * OPENROUTER.
+ * Sticky provider routing: header `x-session-id` or body `session_id`
+ * (≤256 chars); falls back to `prompt_cache_key`.
+ * https://openrouter.ai/docs/guides/best-practices/prompt-caching
+ */
+export type CacheFlavor = "grok" | "openai" | "chatgpt" | "openrouter" | "none";
+export type CacheAffinity = {
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: Readonly<Record<string, unknown>>;
+};
+/** Per-attempt grok-shell routing. Omit on handshake. */
+export type CacheAffinityRequest = {
+    readonly requestId?: string;
+    readonly turnIndex?: number;
+};
+/** GPT-5.6 / GPT-6+ take `prompt_cache_options`; earlier 5.x 400s on Azure. */
+export declare function usesExplicitPromptCache(model: string): boolean;
+export declare function cacheFlavorFromBaseUrl(baseUrl: string): CacheFlavor;
+export declare function grokCacheAffinity(sessionId: string, request?: CacheAffinityRequest): CacheAffinity;
+export declare function chatgptCacheAffinity(sessionId: string): CacheAffinity;
+export declare function openaiCacheAffinity(sessionId: string, model: string): CacheAffinity;
+export declare function openrouterCacheAffinity(sessionId: string): CacheAffinity;
+export declare function cacheAffinityFor(flavor: CacheFlavor, sessionId: string, model: string, request?: CacheAffinityRequest): CacheAffinity;
+/**
+ * Probe whether an unknown remote host actually does prompt caching.
+ *
+ * Accepting `prompt_cache_key` is not evidence: Atria returns 200 and ignores
+ * it. The only honest test is a repeat call with an identical prefix — a real
+ * cache reports `cached_tokens > 0` on the second call. Affinity keys are
+ * deliberately absent: this tests caching, not replica routing.
+ *
+ * Loopback is not privileged: an SSH tunnel or litellm proxy on 127.0.0.1
+ * forwards to a remote that does cache, and a real local Ollama reports
+ * cached_tokens: 0 — the probe answers both correctly. The probe sends no
+ * affinity keys, so the "extra keys 400 on LM Studio" risk does not apply.
+ *
+ * A miss is not cached forever — re-probe on demand. A provider can turn
+ * caching on server-side; the failure mode of a stale "none" is a false
+ * "cache hit · unexpected" tape mark, not a broken turn.
+ */
+export declare function probeCachePolicy(args: {
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly model: string;
+    readonly fetch: (url: string, init: RequestInit) => Promise<Response>;
+    readonly timeoutMs?: number;
+}): Promise<CacheFlavor>;
+//# sourceMappingURL=cache-affinity.d.ts.map

package/dist/providers/openai-compat/cache-affinity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-affinity.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-compat/cache-affinity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,MAAM,CAAC;AAChF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD,CAAC;AAEF,yDAAyD;AACzD,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAIF,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK9D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAqBnE;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAmBlG;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CASrE;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAenF;AAED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAYxE;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,oBAAoB,GAC7B,aAAa,CAaf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,GAAG,OAAO,CAAC,WAAW,CAAC,CAkCvB"}

package/dist/providers/openai-compat/cache-affinity.js

@@ -0,0 +1,221 @@
+/**
+ * Prompt-cache routing for openai-compat completions.
+ *
+ * Caching itself is automatic prefix match (exact head of tools + messages).
+ * These fields only pin the request to a replica that still holds that KV.
+ * They are completion-only — handshake `/models` does not send them.
+ *
+ * Local / unknown hosts get an empty bag: extra keys 400 on LM Studio / Ollama.
+ *
+ * GROK.
+ * "The xAI API performs prompt caching automatically. However, we recommend
+ * setting the `x-grok-conv-id` HTTP header to maximize your cache hit rate."
+ * https://docs.x.ai/developers/advanced-api-usage/prompt-caching
+ * Chat Completions: header `x-grok-conv-id` ("routes requests with the same
+ * conversation ID to the same server. Since cache entries are stored
+ * per-server, this maximizes your cache hit rate.").
+ * https://docs.x.ai/developers/advanced-api-usage/prompt-caching/maximizing-cache-hits
+ * Body `prompt_cache_key` is plumbed to the same affinity (OpenAPI ChatRequest).
+ * grok-shell against cli-chat-proxy also stamps `x-grok-session-id` to the
+ * same session id (sticky pair) and `x-grok-req-id` per invocation — unique
+ * ids belong there, not on conv-id. `x-grok-turn-idx` is 1-based user-turn
+ * depth (SessionTurn chain), stable across ReACT rounds of one prompt.
+ * Remainder classifier PEWs must not reuse the live-tape id: they send a
+ * different prefix (`Reply in prose`, no tools) and evict the tape KV.
+ *
+ * CHATGPT / CODEX SUBSCRIPTION.
+ * Replica stickiness is the `session-id` / `thread-id` headers (Codex
+ * `build_session_headers`). Body `prompt_cache_key` is still sent; the
+ * backend rewrites it per response and does not route on it. The
+ * subscription 400s `store: true` and `prompt_cache_options`.
+ * Model names do not establish endpoint capabilities.
+ *
+ * OPENAI PUBLIC API.
+ * "Set `prompt_cache_key` on requests that share long, common prompt prefixes."
+ * "Replaces the `user` field." No cache HTTP headers — body only.
+ * https://developers.openai.com/api/docs/guides/prompt-caching
+ * GPT-5.6+: `prompt_cache_options.ttl` `"30m"` (default); `mode` `implicit`
+ * places a breakpoint on the latest eligible message. Earlier models:
+ * `prompt_cache_retention` `"24h"` when the org is not ZDR. Sending
+ * `prompt_cache_options` to pre-5.6 (Azure) is a 400.
+ *
+ * OPENROUTER.
+ * Sticky provider routing: header `x-session-id` or body `session_id`
+ * (≤256 chars); falls back to `prompt_cache_key`.
+ * https://openrouter.ai/docs/guides/best-practices/prompt-caching
+ */
+const EMPTY = { headers: {}, body: {} };
+/** GPT-5.6 / GPT-6+ take `prompt_cache_options`; earlier 5.x 400s on Azure. */
+export function usesExplicitPromptCache(model) {
+    const id = model.trim().toLowerCase();
+    if (/gpt-5\.(?:[6-9]|\d{2,})/.test(id))
+        return true;
+    const major = /(?:^|[^a-z0-9])gpt-(\d+)/.exec(id);
+    return major != null && Number(major[1]) >= 6;
+}
+export function cacheFlavorFromBaseUrl(baseUrl) {
+    let host;
+    try {
+        host = new URL(baseUrl).hostname.toLowerCase();
+    }
+    catch {
+        return "none";
+    }
+    if (host === "api.x.ai" ||
+        host.endsWith(".x.ai") ||
+        host === "cli-chat-proxy.grok.com" ||
+        host.endsWith(".grok.com")) {
+        return "grok";
+    }
+    if (host === "api.openai.com" || host.endsWith(".openai.com")) {
+        return "openai";
+    }
+    if (host === "chatgpt.com" || host.endsWith(".chatgpt.com"))
+        return "chatgpt";
+    if (host === "openrouter.ai" || host.endsWith(".openrouter.ai"))
+        return "openrouter";
+    return "none";
+}
+export function grokCacheAffinity(sessionId, request) {
+    const id = sessionId.trim();
+    if (id === "")
+        return EMPTY;
+    const headers = {
+        "x-grok-conv-id": id,
+        "x-grok-session-id": id,
+    };
+    const requestId = request?.requestId?.trim() ?? "";
+    if (requestId !== "")
+        headers["x-grok-req-id"] = requestId;
+    const turnIndex = request?.turnIndex;
+    if (turnIndex != null && Number.isFinite(turnIndex) && turnIndex >= 1) {
+        headers["x-grok-turn-idx"] = String(Math.floor(turnIndex));
+    }
+    return {
+        headers,
+        body: {
+            prompt_cache_key: id,
+        },
+    };
+}
+export function chatgptCacheAffinity(sessionId) {
+    // Codex rejects prompt_cache_key values longer than 64 Unicode code points.
+    const id = [...sessionId.trim()].slice(0, 64).join("");
+    return id === ""
+        ? EMPTY
+        : {
+            headers: { "session-id": id, "thread-id": id },
+            body: { prompt_cache_key: id },
+        };
+}
+export function openaiCacheAffinity(sessionId, model) {
+    const id = sessionId.trim();
+    if (id === "")
+        return EMPTY;
+    return {
+        headers: {},
+        body: usesExplicitPromptCache(model)
+            ? {
+                prompt_cache_key: id,
+                prompt_cache_options: { mode: "implicit", ttl: "30m" },
+            }
+            : {
+                prompt_cache_key: id,
+                prompt_cache_retention: "24h",
+            },
+    };
+}
+export function openrouterCacheAffinity(sessionId) {
+    const id = sessionId.trim().slice(0, 256);
+    if (id === "")
+        return EMPTY;
+    return {
+        headers: {
+            "x-session-id": id,
+        },
+        body: {
+            prompt_cache_key: id,
+            session_id: id,
+        },
+    };
+}
+export function cacheAffinityFor(flavor, sessionId, model, request) {
+    switch (flavor) {
+        case "grok":
+            return grokCacheAffinity(sessionId, request);
+        case "openai":
+            return openaiCacheAffinity(sessionId, model);
+        case "chatgpt":
+            return chatgptCacheAffinity(sessionId);
+        case "openrouter":
+            return openrouterCacheAffinity(sessionId);
+        case "none":
+            return EMPTY;
+    }
+}
+/**
+ * Probe whether an unknown remote host actually does prompt caching.
+ *
+ * Accepting `prompt_cache_key` is not evidence: Atria returns 200 and ignores
+ * it. The only honest test is a repeat call with an identical prefix — a real
+ * cache reports `cached_tokens > 0` on the second call. Affinity keys are
+ * deliberately absent: this tests caching, not replica routing.
+ *
+ * Loopback is not privileged: an SSH tunnel or litellm proxy on 127.0.0.1
+ * forwards to a remote that does cache, and a real local Ollama reports
+ * cached_tokens: 0 — the probe answers both correctly. The probe sends no
+ * affinity keys, so the "extra keys 400 on LM Studio" risk does not apply.
+ *
+ * A miss is not cached forever — re-probe on demand. A provider can turn
+ * caching on server-side; the failure mode of a stale "none" is a false
+ * "cache hit · unexpected" tape mark, not a broken turn.
+ */
+export async function probeCachePolicy(args) {
+    if (args.model.trim() === "")
+        return "none";
+    const prefix = "Probe prefix for prompt cache detection. ".repeat(24);
+    const once = async (suffix) => {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), args.timeoutMs ?? 20_000);
+        try {
+            const response = await args.fetch(args.url, {
+                method: "POST",
+                headers: { ...args.headers, "content-type": "application/json" },
+                body: JSON.stringify({
+                    model: args.model,
+                    messages: [{ role: "user", content: prefix + suffix }],
+                    max_tokens: 1,
+                    temperature: 0,
+                }),
+                signal: ctrl.signal,
+            });
+            if (!response.ok)
+                return null;
+            const data = (await response.json());
+            return cachedTokensOf(data.usage);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    // First call warms the prefix; the second carries a fresh suffix that still
+    // shares the head, so a live cache reports cached_tokens on it.
+    await once("warm");
+    const second = await once("repeat");
+    if (second === null)
+        return "none";
+    return second > 0 ? "openai" : "none";
+}
+/** `usage.prompt_tokens_details.cached_tokens` (Chat) or `input_tokens_details` (Responses). */
+function cachedTokensOf(usage) {
+    if (typeof usage !== "object" || usage === null)
+        return null;
+    const rec = usage;
+    const raw = rec.prompt_tokens_details?.cached_tokens ?? rec.input_tokens_details?.cached_tokens ?? rec.cached_tokens;
+    const n = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : Number.NaN;
+    return Number.isFinite(n) ? n : null;
+}
+//# sourceMappingURL=cache-affinity.js.map

package/dist/providers/openai-compat/cache-affinity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-affinity.js","sourceRoot":"","sources":["../../../src/providers/openai-compat/cache-affinity.ts"],"names":[],"mappings":"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"}

package/dist/providers/openai-compat/cache-dump.d.ts

@@ -0,0 +1,32 @@
+export type CacheDumpKind = "unexpected-hit" | "unexpected-miss" | "aligned-hit" | "aligned-miss" | "unreported";
+export declare function cacheDumpKind(expected: boolean, cacheHit: boolean | null): CacheDumpKind;
+export declare function cacheDumpDir(workspacePath: string, sessionId: string, startedAt: number, kind: CacheDumpKind): string;
+export declare function redactCacheHeaders(headers: Readonly<Record<string, string>>): Record<string, string>;
+export type ReasoningGap = {
+    readonly index: number;
+    readonly contentChars: number;
+    readonly calls: number;
+};
+export declare function preferCacheResponse(prior: unknown, next: unknown): unknown;
+export declare function reasoningSurvey(body: unknown): {
+    readonly assistants: number;
+    readonly missingReasoning: readonly ReasoningGap[];
+};
+export declare function writeCacheDump(input: {
+    readonly workspacePath: string;
+    readonly sessionId: string;
+    readonly startedAt: number;
+    readonly kind: CacheDumpKind;
+    readonly expectedCacheHit: boolean;
+    readonly cacheHit: boolean | null;
+    readonly cachedTokens: number;
+    readonly totalTokens: number | null;
+    readonly request: unknown;
+    readonly response: unknown;
+    readonly answer?: {
+        readonly content: string;
+        readonly reasoning: string;
+        readonly calls: number;
+    };
+}): string | null;
+//# sourceMappingURL=cache-dump.d.ts.map

package/dist/providers/openai-compat/cache-dump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-dump.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-compat/cache-dump.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,aAAa,GAAG,cAAc,GAAG,YAAY,CAAC;AAIjH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,GAAG,aAAa,CAMxF;AAED,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAErH;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMpG;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AA6BF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAK1E;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,YAAY,EAAE,CAAC;CACpD,CAsBA;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,CAAC;CACH,GAAG,MAAM,GAAG,IAAI,CAgChB"}

package/dist/providers/openai-compat/cache-dump.js

@@ -0,0 +1,158 @@
+/**
+ * Every usage-reporting completion round is persisted under
+ * `{workspace}/.harness/cache/<session>/<startedAt>-<kind>/` so a miss
+ * diffs against the previous timestamped folder. Dumping only mismatches
+ * left that prior round off disk.
+ *
+ * `request.json` is the HTTP round (redacted headers + body).
+ * `response.json` is the last payload that still has output/choices/items;
+ * a trailing usage-only `response.completed` does not wipe them.
+ * `meta.json` is expected vs actual plus which assistant rows omit
+ * `reasoning_content` — xAI's top cache-miss cause on reasoning models.
+ * Auth / API-key headers stay off the dump.
+ */
+import { appendFileSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { asRecord, readField } from "./json-read.js";
+const REDACT_HEADER = /^(authorization|cookie|set-cookie|x-api-key)$/i;
+export function cacheDumpKind(expected, cacheHit) {
+    if (cacheHit === null)
+        return "unreported";
+    if (cacheHit && expected)
+        return "aligned-hit";
+    if (cacheHit && !expected)
+        return "unexpected-hit";
+    if (!cacheHit && expected)
+        return "unexpected-miss";
+    return "aligned-miss";
+}
+export function cacheDumpDir(workspacePath, sessionId, startedAt, kind) {
+    return join(workspacePath, ".harness", "cache", sessionId, `${startedAt}-${kind}`);
+}
+export function redactCacheHeaders(headers) {
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        out[key] = REDACT_HEADER.test(key) ? "[redacted]" : value;
+    }
+    return out;
+}
+function fieldPresent(rec, key) {
+    if (rec == null)
+        return false;
+    const value = rec[key];
+    if (value == null)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === "string")
+        return value !== "";
+    return true;
+}
+/**
+ * SSE last-wins would dump `response.completed` with empty `output` / empty
+ * `choices`. Keep the last payload that still has the model's items.
+ */
+function payloadHasItems(raw) {
+    const rec = asRecord(raw);
+    if (rec == null)
+        return false;
+    const inner = asRecord(rec.response) ?? rec;
+    return (fieldPresent(inner, "output") ||
+        fieldPresent(inner, "choices") ||
+        fieldPresent(rec, "delta") ||
+        fieldPresent(rec, "item") ||
+        fieldPresent(inner, "delta") ||
+        fieldPresent(inner, "item"));
+}
+export function preferCacheResponse(prior, next) {
+    if (next == null)
+        return prior;
+    if (prior == null)
+        return next;
+    if (payloadHasItems(next))
+        return next;
+    return payloadHasItems(prior) ? prior : next;
+}
+export function reasoningSurvey(body) {
+    const rec = asRecord(body);
+    const messages = rec == null ? undefined : readField(rec, "messages");
+    const input = rec == null ? undefined : readField(rec, "input");
+    const rows = Array.isArray(messages) ? messages : Array.isArray(input) ? input : [];
+    const missing = [];
+    let assistants = 0;
+    for (const [index, row] of rows.entries()) {
+        if (typeof row !== "object" || row === null)
+            continue;
+        if (readField(row, "role") !== "assistant")
+            continue;
+        assistants += 1;
+        const reasoning = readField(row, "reasoning_content");
+        if (typeof reasoning === "string" && reasoning !== "")
+            continue;
+        const content = readField(row, "content");
+        const toolCalls = readField(row, "tool_calls");
+        missing.push({
+            index,
+            contentChars: typeof content === "string" ? content.length : 0,
+            calls: Array.isArray(toolCalls) ? toolCalls.length : 0,
+        });
+    }
+    return { assistants, missingReasoning: missing };
+}
+export function writeCacheDump(input) {
+    const workspace = input.workspacePath.trim();
+    if (workspace === "" || !isDirectory(workspace))
+        return null;
+    const sessionId = input.sessionId.trim() === "" ? "session" : input.sessionId.trim();
+    const sessionDir = join(workspace, ".harness", "cache", sessionId);
+    const dir = cacheDumpDir(workspace, sessionId, input.startedAt, input.kind);
+    const request = redactRequest(input.request ?? null);
+    const body = typeof request === "object" && request !== null ? readField(request, "body") : undefined;
+    const survey = reasoningSurvey(body);
+    const meta = {
+        kind: input.kind,
+        expectedCacheHit: input.expectedCacheHit,
+        cacheHit: input.cacheHit,
+        cachedTokens: input.cachedTokens,
+        totalTokens: input.totalTokens,
+        startedAt: input.startedAt,
+        answer: input.answer ?? null,
+        wire: survey,
+    };
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "request.json"), `${JSON.stringify(request, null, 2)}\n`);
+        writeFileSync(join(dir, "response.json"), `${JSON.stringify(input.response ?? null, null, 2)}\n`);
+        writeFileSync(join(dir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`);
+        appendFileSync(join(sessionDir, "index.jsonl"), `${JSON.stringify({ ...meta, dir: `${input.startedAt}-${input.kind}` })}\n`);
+        return dir;
+    }
+    catch {
+        return null;
+    }
+}
+function redactRequest(request) {
+    if (typeof request !== "object" || request === null)
+        return request;
+    const rec = asRecord(request);
+    if (rec == null)
+        return request;
+    const headers = asRecord(rec.headers);
+    if (headers == null)
+        return request;
+    const strings = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (typeof value === "string")
+            strings[key] = value;
+    }
+    return { ...rec, headers: redactCacheHeaders(strings) };
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=cache-dump.js.map

package/dist/providers/openai-compat/cache-dump.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-dump.js","sourceRoot":"","sources":["../../../src/providers/openai-compat/cache-dump.ts"],"names":[],"mappings":"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"}

package/dist/providers/openai-compat/completion-face.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Live tools[] face for a session root.
+ *
+ * Product composition binds the session view (worker ceilings, blocklist,
+ * behavior, private MCP) plus any live description overlay. Frozen turn
+ * tools stay as snapshotted. Session and Scheme runtimes stay out of this
+ * package.
+ */
+import { type KernelToolCatalog } from "../../tool-catalog/index.js";
+export type LiveToolDescription = (toolName: string, catalog: KernelToolCatalog) => string | undefined;
+export type CompletionFace = {
+    catalog(): KernelToolCatalog | undefined;
+    liveDescription?: LiveToolDescription;
+};
+export declare function bindCompletionFace(root: object, face: CompletionFace): void;
+export declare function completionCatalogOf(root: object | undefined | null): KernelToolCatalog | undefined;
+export declare function liveToolDescriptionOf(root: object | undefined | null, toolName: string, catalog: KernelToolCatalog): string | undefined;
+//# sourceMappingURL=completion-face.d.ts.map

package/dist/providers/openai-compat/completion-face.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-face.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-compat/completion-face.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAa,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnE,MAAM,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,KAAK,MAAM,GAAG,SAAS,CAAC;AAEvG,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,IAAI,iBAAiB,GAAG,SAAS,CAAC;IACzC,eAAe,CAAC,EAAE,mBAAmB,CAAC;CACvC,CAAC;AAIF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAE3E;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,iBAAiB,GAAG,SAAS,CAMlG;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,iBAAiB,GACzB,MAAM,GAAG,SAAS,CAGpB"}

package/dist/providers/openai-compat/completion-face.js

@@ -0,0 +1,27 @@
+/**
+ * Live tools[] face for a session root.
+ *
+ * Product composition binds the session view (worker ceilings, blocklist,
+ * behavior, private MCP) plus any live description overlay. Frozen turn
+ * tools stay as snapshotted. Session and Scheme runtimes stay out of this
+ * package.
+ */
+import { catalogOf } from "../../tool-catalog/index.js";
+const facesByRoot = new WeakMap();
+export function bindCompletionFace(root, face) {
+    facesByRoot.set(root, face);
+}
+export function completionCatalogOf(root) {
+    if (root != null) {
+        const face = facesByRoot.get(root);
+        if (face !== undefined)
+            return face.catalog();
+    }
+    return catalogOf(root);
+}
+export function liveToolDescriptionOf(root, toolName, catalog) {
+    if (root == null)
+        return undefined;
+    return facesByRoot.get(root)?.liveDescription?.(toolName, catalog);
+}
+//# sourceMappingURL=completion-face.js.map

package/dist/providers/openai-compat/completion-face.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-face.js","sourceRoot":"","sources":["../../../src/providers/openai-compat/completion-face.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,SAAS,EAA0B,MAAM,gBAAgB,CAAC;AASnE,MAAM,WAAW,GAAG,IAAI,OAAO,EAA0B,CAAC;AAE1D,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,IAAoB;IACnE,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAA+B;IACjE,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,IAA+B,EAC/B,QAAgB,EAChB,OAA0B;IAE1B,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IACnC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,eAAe,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACrE,CAAC"}