@desplega.ai/agent-swarm 1.76.2 → 1.76.3

package/src/utils/internal-ai/complete-structured.ts

@@ -0,0 +1,296 @@
+/**
+ * General-purpose structured-output LLM wrapper.
+ *
+ * Plan: thoughts/taras/plans/2026-05-10-fix-session-summarization-workers.md
+ * → Phase 0 § "complete-structured.ts"
+ *
+ * Context-agnostic: callable from both worker subprocesses and the API
+ * server. Resolves a credential per the precedence in `./credentials.ts`,
+ * then either:
+ *   - Calls pi-ai's `complete()` with a single typebox-defined tool and
+ *     extracts the tool-call payload (provider/anthropic/openai/openai-codex
+ *     paths), OR
+ *   - Shells out to `claude -p` (CLAUDE_CODE_OAUTH_TOKEN fallback path).
+ *
+ * Worker-safe: uses fetch() only, no bun:sqlite import.
+ */
+
+import type { ToolCall } from "@mariozechner/pi-ai";
+import { complete, getModel } from "@mariozechner/pi-ai";
+import type { TSchema } from "typebox";
+import { z } from "zod";
+import { type ResolvedCredential, resolveCredential } from "./credentials.js";
+import { parseModelStr } from "./models.js";
+
+export interface CompleteStructuredOptions<TZod extends z.ZodTypeAny> {
+  /** Zod schema used for output validation (final source of truth). */
+  zodSchema: TZod;
+  /** Typebox schema used as pi-ai `Tool.parameters` (provider-side validation). */
+  toolSchema: TSchema;
+  toolName: string;
+  toolDescription: string;
+  systemPrompt: string;
+  userPrompt: string;
+  /**
+   * Optional context for codex-OAuth lookup. When omitted, only env vars are tried.
+   * - Workers: pass `config.apiUrl` / `config.apiKey`.
+   * - API server: pass `MCP_BASE_URL` / `API_KEY` (loopback).
+   * - Skip entirely to disable codex OAuth probing.
+   */
+  apiUrl?: string;
+  apiKey?: string;
+  /** Default: 3. */
+  retries?: number;
+  signal?: AbortSignal;
+  /** Optional diagnostic tag (e.g. `"session-summary:pi"`). */
+  callerTag?: string;
+  // Test injection points:
+  _resolveCredential?: typeof resolveCredential;
+  _complete?: typeof complete;
+  _spawnClaudeCli?: (
+    prompt: string,
+    model: string,
+    signal?: AbortSignal,
+    jsonSchema?: object,
+  ) => Promise<string>;
+  /**
+   * Bypass `resolveCredential` entirely — opencode auth path (and tests)
+   * pass an already-resolved credential.
+   */
+  _credentialOverride?: ResolvedCredential;
+}
+
+/**
+ * Default 30s timeout for the `claude -p` shellout — matches the existing
+ * pattern in `src/providers/pi-mono-extension.ts:328-351` (the call site
+ * being retired in Phase 1).
+ */
+const CLAUDE_CLI_TIMEOUT_MS = 30_000;
+
+/**
+ * Tolerant JSON extractor for `claude -p` `result` strings. Claude sometimes
+ * wraps JSON in ```json … ``` fences despite a "no code fences" prompt; this
+ * peels off the fence so `JSON.parse` can handle it.
+ */
+function stripJsonFences(raw: string): string {
+  const trimmed = raw.trim();
+  const fenced = trimmed.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
+  return fenced?.[1] ? fenced[1].trim() : trimmed;
+}
+
+async function defaultSpawnClaudeCli(
+  prompt: string,
+  model: string,
+  signal?: AbortSignal,
+  jsonSchema?: object,
+): Promise<string> {
+  const cmd = [
+    process.env.CLAUDE_BINARY ?? "claude",
+    "-p",
+    "--model",
+    model,
+    "--output-format",
+    "json",
+  ];
+  if (jsonSchema) {
+    cmd.push("--json-schema", JSON.stringify(jsonSchema));
+  }
+  // The hook subprocess receives an empty CLAUDE_CODE_OAUTH_TOKEN (claude
+  // CLI strips it from hooks). Restore it from the mirror set by
+  // claude-adapter.ts so the inner `claude -p` invocation authenticates.
+  const env: Record<string, string> = { ...(process.env as Record<string, string>) };
+  if (!env.CLAUDE_CODE_OAUTH_TOKEN && env.AGENT_SWARM_CLAUDE_OAUTH_TOKEN) {
+    env.CLAUDE_CODE_OAUTH_TOKEN = env.AGENT_SWARM_CLAUDE_OAUTH_TOKEN;
+  }
+  const proc = Bun.spawn({
+    cmd,
+    env,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const timeout = setTimeout(() => {
+    try {
+      proc.kill();
+    } catch {
+      // ignore — process may have already exited
+    }
+  }, CLAUDE_CLI_TIMEOUT_MS);
+  const abortHandler = () => {
+    try {
+      proc.kill();
+    } catch {
+      // ignore
+    }
+  };
+  signal?.addEventListener("abort", abortHandler, { once: true });
+  try {
+    proc.stdin.write(prompt);
+    await proc.stdin.end();
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (exitCode !== 0) {
+      console.error(`internal-ai: claude -p exited ${exitCode}; stderr=${stderr.slice(0, 500)}`);
+    }
+    // claude -p --output-format json envelope shape:
+    //   { ..., result: "<text>", structured_output?: <validated-object> }
+    // When --json-schema is passed, prefer `structured_output` (validated
+    // by claude server-side). When it's absent, fall back to `result` — the
+    // caller has also embedded the schema in the prompt so `result` should
+    // be valid JSON; if it isn't, the caller's JSON.parse retry surfaces it.
+    try {
+      const envelope = JSON.parse(stdout) as { result?: string; structured_output?: unknown };
+      if (jsonSchema && envelope.structured_output !== undefined) {
+        return JSON.stringify(envelope.structured_output);
+      }
+      return envelope.result ?? stdout;
+    } catch {
+      return stdout;
+    }
+  } finally {
+    clearTimeout(timeout);
+    signal?.removeEventListener("abort", abortHandler);
+  }
+}
+
+/**
+ * Run a structured-output completion. Returns the parsed object on success,
+ * `null` on auth-missing or exhausted retries (errors logged, never thrown).
+ */
+export async function completeStructured<TZod extends z.ZodTypeAny>(
+  opts: CompleteStructuredOptions<TZod>,
+): Promise<z.infer<TZod> | null> {
+  const retries = opts.retries ?? 3;
+  const callerTag = opts.callerTag ?? "<unset>";
+
+  // 1. Resolve credential (or use override).
+  let cred: ResolvedCredential | null;
+  if (opts._credentialOverride) {
+    cred = opts._credentialOverride;
+  } else {
+    const resolver = opts._resolveCredential ?? resolveCredential;
+    cred = await resolver({
+      env: process.env,
+      apiUrl: opts.apiUrl,
+      apiKey: opts.apiKey,
+      callerTag: opts.callerTag,
+    });
+  }
+  if (!cred) {
+    // No auth — graceful no-op. Don't log noisily; callers may invoke this
+    // routinely in environments without LLM credentials.
+    return null;
+  }
+
+  // Always-on debug log — relied on by Manual E2E Scenario 5 + Phase 4 QA.
+  console.log(`internal-ai: kind=${cred.kind} callerTag=${callerTag}`);
+
+  // 2. Claude-CLI fallback path.
+  if (cred.kind === "claude-cli") {
+    const spawn = opts._spawnClaudeCli ?? defaultSpawnClaudeCli;
+    // Belt-and-suspenders: pass the schema both as `--json-schema` (sets
+    // `envelope.structured_output` when the model complies) AND inline in
+    // the prompt (forces JSON-only `envelope.result` when it doesn't).
+    // The CLI flag alone is unreliable — claude sometimes asks "where's
+    // the schema?" if the prompt doesn't reference one.
+    const jsonSchema = z.toJSONSchema(opts.zodSchema) as object;
+    const schemaStr = JSON.stringify(jsonSchema);
+    const claudeUserPrompt = `${opts.userPrompt}\n\nRespond with ONLY a JSON object (no prose, no code fences) matching this schema:\n${schemaStr}`;
+    let lastErr: unknown = null;
+    for (let attempt = 0; attempt < retries; attempt++) {
+      try {
+        const raw = await spawn(
+          `${opts.systemPrompt}\n\n${claudeUserPrompt}`,
+          cred.modelDefault,
+          opts.signal,
+          jsonSchema,
+        );
+        let parsedJson: unknown;
+        try {
+          parsedJson = JSON.parse(stripJsonFences(raw));
+        } catch (err) {
+          lastErr = err;
+          continue;
+        }
+        const validated = opts.zodSchema.safeParse(parsedJson);
+        if (validated.success) {
+          return validated.data;
+        }
+        lastErr = validated.error;
+      } catch (err) {
+        lastErr = err;
+      }
+    }
+    console.error(
+      `internal-ai: structured output failed after ${retries} retries (callerTag=${callerTag} kind=${cred.kind})`,
+      lastErr,
+    );
+    return null;
+  }
+
+  // 3. pi-ai path (openrouter / anthropic / openai / openai-codex).
+  const [provider, modelId] = parseModelStr(cred.modelDefault);
+  let model: ReturnType<typeof getModel>;
+  try {
+    // The typed overload is too restrictive for our dynamic-string case; the
+    // runtime tolerates any registered (provider, id) pair.
+    model = getModel(provider as Parameters<typeof getModel>[0], modelId as never);
+  } catch (err) {
+    console.error(
+      `internal-ai: getModel(${provider}, ${modelId}) threw (callerTag=${callerTag})`,
+      err,
+    );
+    return null;
+  }
+
+  const completeFn = opts._complete ?? complete;
+  let userPrompt = opts.userPrompt;
+  let lastErr: unknown = null;
+  for (let attempt = 0; attempt < retries; attempt++) {
+    try {
+      const msg = await completeFn(
+        model,
+        {
+          systemPrompt: opts.systemPrompt,
+          messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }],
+          tools: [
+            {
+              name: opts.toolName,
+              description: opts.toolDescription,
+              parameters: opts.toolSchema,
+            },
+          ],
+        },
+        // pi-ai's ProviderStreamOptions type only allows known providers;
+        // we pass the validated apiKey through verbatim.
+        { apiKey: cred.apiKey, signal: opts.signal } as Parameters<typeof completeFn>[2],
+      );
+
+      const toolCall = msg.content.find(
+        (c): c is ToolCall => c.type === "toolCall" && c.name === opts.toolName,
+      );
+      if (!toolCall) {
+        userPrompt = `${userPrompt}\n\nYou did not call the ${opts.toolName} tool. You MUST call it with the requested arguments.`;
+        lastErr = new Error("no tool call in response");
+        continue;
+      }
+
+      const validated = opts.zodSchema.safeParse(toolCall.arguments);
+      if (validated.success) {
+        return validated.data;
+      }
+      userPrompt = `${userPrompt}\n\nThe ${opts.toolName} arguments did not validate: ${validated.error.message}. Please retry with correct arguments.`;
+      lastErr = validated.error;
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  console.error(
+    `internal-ai: structured output failed after ${retries} retries (callerTag=${callerTag} kind=${cred.kind})`,
+    lastErr,
+  );
+  return null;
+}

package/src/utils/internal-ai/credentials.ts

@@ -0,0 +1,175 @@
+/**
+ * Credential resolver for the internal-ai abstraction.
+ *
+ * Plan: thoughts/taras/plans/2026-05-10-fix-session-summarization-workers.md
+ * → Phase 0 § "credentials.ts"
+ *
+ * Context-agnostic: tries env vars first, then optionally probes codex OAuth
+ * via HTTP if `apiUrl + apiKey` are provided. Workers pass through
+ * `config.apiUrl` / `config.apiKey`; API-server callers pass `MCP_BASE_URL` /
+ * `API_KEY` (loopback). Callers that don't want codex-OAuth probing omit both.
+ *
+ * NO HARNESS CHECK — this resolver is harness-agnostic. The codex-OAuth probe
+ * costs one localhost HTTP call, which is fine to attempt on any worker.
+ *
+ * Worker-safe: uses fetch() only, no bun:sqlite import.
+ */
+
+import type { OAuthCredentials } from "@mariozechner/pi-ai";
+import { getEnvApiKey } from "@mariozechner/pi-ai";
+import { getOAuthApiKey } from "@mariozechner/pi-ai/oauth";
+import { getValidCodexOAuth, persistCodexOAuth } from "../../providers/codex-oauth/storage.js";
+import { type CredentialKind, DEFAULT_MODEL, resolveModelString } from "./models.js";
+
+export type ResolvedCredential =
+  | {
+      kind: "openrouter" | "anthropic" | "openai" | "openai-codex";
+      apiKey: string;
+      modelDefault: string;
+    }
+  | {
+      kind: "claude-cli";
+      modelDefault: string;
+      // No apiKey — the `claude` CLI uses CLAUDE_CODE_OAUTH_TOKEN from env directly.
+    };
+
+export interface ResolveCredentialOptions {
+  /** Defaulted to `process.env`; injectable for tests. */
+  env?: NodeJS.ProcessEnv;
+  /** Optional: enables codex-OAuth lookup over HTTP. */
+  apiUrl?: string;
+  /** Optional: paired with apiUrl. */
+  apiKey?: string;
+  /** Optional log tag — purely for diagnostics, not load-bearing. */
+  callerTag?: string;
+  /** Test injection: override the codex OAuth lookup. */
+  _getValidCodexOAuth?: typeof getValidCodexOAuth;
+  /** Test injection: override pi-ai's OAuth-to-API-key resolution. */
+  _getOAuthApiKey?: typeof getOAuthApiKey;
+  /** Test injection: override pi-ai's env API key lookup. */
+  _getEnvApiKey?: typeof getEnvApiKey;
+  /** Test injection: override the persistCodexOAuth call. */
+  _persistCodexOAuth?: typeof persistCodexOAuth;
+}
+
+/**
+ * Resolve a credential according to the documented precedence. Returns `null`
+ * if no credential could be resolved — callers MUST treat null as a graceful
+ * no-op (do NOT throw; structured-output completion is a best-effort path).
+ *
+ * Precedence (top wins):
+ *   1. `env.OPENROUTER_API_KEY` (via pi-ai `getEnvApiKey("openrouter")`)
+ *   2. `env.ANTHROPIC_API_KEY`  (via pi-ai `getEnvApiKey("anthropic")`)
+ *   3. `env.OPENAI_API_KEY`     (via pi-ai `getEnvApiKey("openai")`)
+ *   4. codex OAuth (only when `apiUrl && apiKey` are provided)
+ *   5. `env.CLAUDE_CODE_OAUTH_TOKEN` → claude-cli fallback
+ *   6. null
+ */
+export async function resolveCredential(
+  opts: ResolveCredentialOptions = {},
+): Promise<ResolvedCredential | null> {
+  const env = opts.env ?? process.env;
+  const getEnvKey = opts._getEnvApiKey ?? getEnvApiKey;
+  const getCodex = opts._getValidCodexOAuth ?? getValidCodexOAuth;
+  const getOAuth = opts._getOAuthApiKey ?? getOAuthApiKey;
+  const persistCodex = opts._persistCodexOAuth ?? persistCodexOAuth;
+
+  // 1. OpenRouter.
+  const openrouterKey = env.OPENROUTER_API_KEY ?? getEnvKey("openrouter");
+  if (openrouterKey) {
+    return {
+      kind: "openrouter",
+      apiKey: openrouterKey,
+      modelDefault: resolveModelString("openrouter"),
+    };
+  }
+
+  // 2. Anthropic.
+  const anthropicKey = env.ANTHROPIC_API_KEY ?? getEnvKey("anthropic");
+  if (anthropicKey) {
+    return {
+      kind: "anthropic",
+      apiKey: anthropicKey,
+      modelDefault: resolveModelString("anthropic"),
+    };
+  }
+
+  // 3. OpenAI.
+  const openaiKey = env.OPENAI_API_KEY ?? getEnvKey("openai");
+  if (openaiKey) {
+    return {
+      kind: "openai",
+      apiKey: openaiKey,
+      modelDefault: resolveModelString("openai"),
+    };
+  }
+
+  // 4. Codex OAuth — only if we have apiUrl + apiKey to probe the config store.
+  if (opts.apiUrl && opts.apiKey) {
+    try {
+      const codexCreds = await getCodex(opts.apiUrl, opts.apiKey);
+      if (codexCreds) {
+        // pi-ai expects a Record<providerID, OAuthCredentials>.
+        const credMap: Record<string, OAuthCredentials> = {
+          "openai-codex": {
+            access: codexCreds.access,
+            refresh: codexCreds.refresh,
+            expires: codexCreds.expires,
+          },
+        };
+        const oauthResult = await getOAuth("openai-codex", credMap);
+        if (oauthResult) {
+          // Persist any rotated refresh token — best-effort, must not block.
+          // Wrap defensively here even though the production helper already
+          // swallows; tests may inject a throwing hook, and persistence
+          // failure must never prevent the current call from succeeding.
+          if (oauthResult.newCredentials) {
+            const updated = oauthResult.newCredentials;
+            try {
+              await persistCodex(opts.apiUrl, opts.apiKey, {
+                access: String(updated.access),
+                refresh: String(updated.refresh),
+                expires: Number(updated.expires),
+                accountId: codexCreds.accountId,
+              });
+            } catch (err) {
+              console.error(
+                `internal-ai: persistCodexOAuth failed (callerTag=${opts.callerTag ?? "<unset>"}):`,
+                err,
+              );
+            }
+          }
+          return {
+            kind: "openai-codex",
+            apiKey: oauthResult.apiKey,
+            modelDefault: resolveModelString("openai-codex"),
+          };
+        }
+      }
+    } catch (err) {
+      console.error(
+        `internal-ai: codex OAuth probe failed (callerTag=${opts.callerTag ?? "<unset>"}):`,
+        err,
+      );
+      // Fall through to claude-cli fallback below.
+    }
+  }
+
+  // 5. CLAUDE_CODE_OAUTH_TOKEN → claude-cli fallback.
+  // `AGENT_SWARM_CLAUDE_OAUTH_TOKEN` is the mirror set by claude-adapter.ts
+  // before spawning `claude` — the CLI strips `CLAUDE_CODE_OAUTH_TOKEN` from
+  // hook subprocesses (security), so the hook reads the mirror instead.
+  if (env.AGENT_SWARM_CLAUDE_OAUTH_TOKEN || env.CLAUDE_CODE_OAUTH_TOKEN) {
+    return {
+      kind: "claude-cli",
+      modelDefault: resolveModelString("claude-cli"),
+    };
+  }
+
+  // 6. No creds.
+  return null;
+}
+
+// Re-export for convenience to keep imports flat.
+export { DEFAULT_MODEL };
+export type { CredentialKind };

package/src/utils/internal-ai/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Internal-AI: reusable structured-output LLM abstraction for both worker
+ * subprocesses and the API server.
+ *
+ * Plan: thoughts/taras/plans/2026-05-10-fix-session-summarization-workers.md
+ *
+ * Worker-safe: uses fetch() only, no bun:sqlite import.
+ *
+ * Public surface:
+ *   - `completeStructured<TZod>({...})` — context-agnostic lower layer.
+ *   - `summarizeSession({...})` — worker-side session-end domain helper.
+ *   - `resolveCredential({...})` — exposed for opencode-auth and tests.
+ */
+
+export {
+  type CompleteStructuredOptions,
+  completeStructured,
+} from "./complete-structured.js";
+export {
+  type CredentialKind,
+  DEFAULT_MODEL,
+  type ResolveCredentialOptions,
+  type ResolvedCredential,
+  resolveCredential,
+} from "./credentials.js";
+export { parseModelStr, resolveModelString } from "./models.js";
+export {
+  type SummarizeSessionOptions,
+  summarizeSession,
+  summaryToolSchema,
+} from "./summarize-session.js";

package/src/utils/internal-ai/models.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-credential default model registry for the internal-ai abstraction.
+ *
+ * Plan: thoughts/taras/plans/2026-05-10-fix-session-summarization-workers.md
+ * → Phase 0 § "models.ts"
+ *
+ * Model defaults are per credential kind, NOT per harness — every credential
+ * kind has exactly one default model. Override via `MEMORY_RATER_MODEL` env
+ * (kept for backwards-compat with the claude hook).
+ */
+
+export type CredentialKind = "openrouter" | "anthropic" | "openai" | "openai-codex" | "claude-cli";
+
+/**
+ * Per-credential default model strings. The "claude-cli" kind uses the
+ * shorthand "haiku" because the only consumer is the `claude -p --model haiku`
+ * shellout, not pi-ai's `getModel`.
+ */
+export const DEFAULT_MODEL: Record<CredentialKind, string> = {
+  openrouter: "openrouter/google/gemini-3-flash-preview",
+  anthropic: "anthropic/claude-haiku-4-5",
+  openai: "openai/gpt-5.4-mini",
+  "openai-codex": "openai-codex/gpt-5.4-mini",
+  "claude-cli": "haiku",
+};
+
+/**
+ * Resolve the effective model string for a credential kind. Honours the
+ * `MEMORY_RATER_MODEL` env var so existing claude-hook users keep their
+ * override (it pre-dates the per-kind registry).
+ */
+export function resolveModelString(kind: CredentialKind): string {
+  return process.env.MEMORY_RATER_MODEL ?? DEFAULT_MODEL[kind];
+}
+
+/**
+ * Split a `provider/model-id` string on the FIRST `/` so that OpenRouter
+ * compound IDs like `openrouter/google/gemini-3-flash-preview` parse as
+ * `("openrouter", "google/gemini-3-flash-preview")`. Mirrors the existing
+ * convention in `src/providers/pi-mono-adapter.ts:161-170`.
+ */
+export function parseModelStr(modelStr: string): [provider: string, modelId: string] {
+  const idx = modelStr.indexOf("/");
+  if (idx < 0) throw new Error(`invalid model string (no '/'): ${modelStr}`);
+  return [modelStr.slice(0, idx), modelStr.slice(idx + 1)];
+}

package/src/utils/internal-ai/summarize-session.ts

@@ -0,0 +1,101 @@
+/**
+ * Worker-side domain helper for session-end summarization.
+ *
+ * Plan: thoughts/taras/plans/2026-05-10-fix-session-summarization-workers.md
+ * → Phase 0 § "summarize-session.ts"
+ *
+ * Composes `completeStructured` with `SummaryWithRatingsSchema` and the
+ * shared `BASE_SUMMARIZE_PROMPT` extracted from `src/hooks/hook.ts`. API-server
+ * callers wanting structured AI completion call `completeStructured` directly
+ * with their own schemas — this helper is for session-transcript consumers
+ * only.
+ *
+ * Worker-safe: uses fetch() only via underlying helpers; no bun:sqlite import.
+ */
+
+import { Type } from "typebox";
+import type { z } from "zod";
+import {
+  BASE_SUMMARIZE_PROMPT,
+  buildSummaryWithRatingsPrompt,
+  type RetrievalRow,
+  SummaryWithRatingsSchema,
+} from "../../be/memory/raters/llm.js";
+import { completeStructured } from "./complete-structured.js";
+import type { ResolvedCredential } from "./credentials.js";
+
+export interface SummarizeSessionOptions {
+  /** Diagnostic tag only — propagated into `callerTag`, not into `completeStructured` directly. */
+  harness: "claude" | "pi" | "opencode" | "codex";
+  /** Pre-truncated transcript text. */
+  transcript: string;
+  /** Memory retrievals for the per-memory ratings block; [] when not requested. */
+  retrievals: RetrievalRow[];
+  taskContext: { sourceTaskId: string; agentId: string; prompt?: string };
+  /** Passed through to `completeStructured` for codex-OAuth probing. */
+  apiUrl: string;
+  apiKey: string;
+  signal?: AbortSignal;
+  /**
+   * Bypass `resolveCredential` entirely — opencode auth path (and tests) pass
+   * an already-resolved credential through to `completeStructured`. Phase 2
+   * amendment: clean injection point so harnesses with their own credential
+   * stores (opencode's `auth.json`) can skip the harness-agnostic resolver.
+   */
+  _credentialOverride?: ResolvedCredential;
+  /** Test injection. */
+  _completeStructured?: typeof completeStructured;
+}
+
+/**
+ * Typebox tool schema mirroring `SummaryWithRatingsSchema`.
+ *
+ * Kept in lockstep with the zod schema via `src/tests/internal-ai/schema-parity.test.ts`
+ * which fuzzes both validators with a fixture set.
+ */
+export const summaryToolSchema = Type.Object({
+  summary: Type.String(),
+  ratings: Type.Array(
+    Type.Object({
+      id: Type.String({ minLength: 1 }),
+      score: Type.Number({ minimum: 0, maximum: 1 }),
+      reasoning: Type.String({ minLength: 1, maxLength: 500 }),
+      referencesSource: Type.Optional(Type.String({ minLength: 1, maxLength: 512 })),
+    }),
+  ),
+});
+
+/**
+ * Returns the structured summary (with optional per-memory ratings), or
+ * `null` when:
+ *   - the transcript is too short (≤ 100 chars), OR
+ *   - `completeStructured` could not resolve a credential, OR
+ *   - the LLM repeatedly failed to produce schema-valid output.
+ */
+export async function summarizeSession(
+  opts: SummarizeSessionOptions,
+): Promise<z.infer<typeof SummaryWithRatingsSchema> | null> {
+  if (opts.transcript.length <= 100) return null;
+
+  const taskLine = opts.taskContext.prompt ? `\nTask: ${opts.taskContext.prompt}` : "";
+  const basePrompt = `${BASE_SUMMARIZE_PROMPT}${taskLine}\n\nTranscript:\n${opts.transcript}`;
+  const userPrompt = buildSummaryWithRatingsPrompt(basePrompt, opts.retrievals);
+
+  const runner = opts._completeStructured ?? completeStructured;
+  return await runner({
+    zodSchema: SummaryWithRatingsSchema,
+    toolSchema: summaryToolSchema,
+    toolName: "record_session_summary",
+    toolDescription:
+      "Record the high-value learnings extracted from this session, plus per-memory ratings of any retrievals.",
+    systemPrompt:
+      "You are an expert at extracting durable, generalizable learnings from agent sessions.",
+    userPrompt,
+    callerTag: `session-summary:${opts.harness}`,
+    apiUrl: opts.apiUrl,
+    apiKey: opts.apiKey,
+    signal: opts.signal,
+    retries: 3,
+    ...(opts._credentialOverride ? { _credentialOverride: opts._credentialOverride } : {}),
+  });
+}