akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/dist/integrations/harnesses/copilot/agent-builder.js

@@ -0,0 +1,121 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * GitHub Copilot CLI agent command builder (P2, plan §"The adapter contract"
+ * step 2 / §"Capability matrix").
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * headless argv the `copilot` CLI expects. Per the capability matrix the
+ * headless invocation is:
+ *
+ *   copilot -p "<prompt>" --allow-all-tools
+ *
+ * with `--output-format json` for structured output, `--model <m>` for model
+ * selection, and `--resume <id>` for resume (resume is registry-side —
+ * `AkmHarness.resume` — not built here because `AgentDispatchRequest` carries
+ * no session id).
+ *
+ * Platform-specific mapping decisions (all localized here, per the adapter
+ * contract):
+ *
+ * - **systemPrompt** — Copilot CLI has no system-prompt flag (it reads
+ *   repo/user custom-instructions files instead), so the system prompt is
+ *   folded into the `-p` payload ahead of the task prompt, separated by a
+ *   blank line. `assertNotFlag` still guards it so a `--`-prefixed system
+ *   prompt cannot turn the front of the `-p` value into a flag.
+ * - **schema** — the matrix places Copilot in the "via prompt+validate" tier
+ *   (no native `--output-schema` equivalent, unlike Codex), so the JSON
+ *   Schema is passed through the prompt: a directive matching the engine's
+ *   wording (`step-work.ts` `buildUnitPrompt`) is appended to the `-p`
+ *   payload, and `--output-format json` is emitted so stdout is the
+ *   documented JSON envelope the copilot result extractor normalizes. The
+ *   engine's shared retry-until-valid loop performs the actual validation.
+ * - **tools** — a string/array tool policy maps to repeated
+ *   `--allow-tool <t>` flags (Copilot's per-tool approval flag). With no
+ *   policy at all, headless runs need autonomy, so `--allow-all-tools` is
+ *   emitted per the matrix. A *structured* policy object is NOT expressible
+ *   as Copilot flags; it is deliberately dropped without falling back to
+ *   `--allow-all-tools` (never silently widen a restriction) — in
+ *   programmatic mode Copilot then denies unapproved tool calls, which is the
+ *   conservative failure mode.
+ *
+ * NOT registered anywhere: `builders.ts` / `harnesses/index.ts` wiring is a
+ * follow-up integration task. Exported standalone so that task only adds a
+ * registry entry.
+ */
+import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
+/** Canonical harness/platform id used for model-alias resolution. */
+export const COPILOT_PLATFORM = "copilot";
+/**
+ * Split a tool policy into individual tool names for `--allow-tool`.
+ * Strings are comma-separated lists; arrays are taken as-is. Structured
+ * policy objects return `undefined` (not expressible as Copilot flags — see
+ * module doc).
+ */
+function toolPolicyEntries(tools) {
+    if (typeof tools === "string") {
+        return tools
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean);
+    }
+    if (Array.isArray(tools)) {
+        return tools.map((t) => t.trim()).filter(Boolean);
+    }
+    return undefined;
+}
+/**
+ * Assemble the `-p` payload: optional system prompt, the task prompt, and —
+ * when a schema is requested — the same schema directive the workflow
+ * engine's prompt assembly uses, so both dispatch paths speak one dialect.
+ */
+function buildPromptPayload(req) {
+    const sections = [];
+    if (req.systemPrompt)
+        sections.push(req.systemPrompt);
+    sections.push(req.prompt);
+    if (req.schema) {
+        sections.push(`Respond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${JSON.stringify(req.schema)}`);
+    }
+    return sections.join("\n\n");
+}
+/**
+ * GitHub Copilot CLI builder.
+ * Command shape:
+ *   copilot [--model <m>] (--allow-all-tools | --allow-tool <t> ...)
+ *           [--output-format json] -p "<systemPrompt?\n\nprompt\n\nschema?>"
+ */
+export const copilotBuilder = {
+    platform: COPILOT_PLATFORM,
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        const args = [...profile.args];
+        if (req.model) {
+            const resolved = resolveDispatchModel(req, profile, COPILOT_PLATFORM);
+            args.push("--model", resolved);
+        }
+        if (req.tools) {
+            const entries = toolPolicyEntries(req.tools);
+            // Structured policy objects (entries === undefined) emit NO allow flags:
+            // dropping a restriction must never widen to --allow-all-tools.
+            for (const tool of entries ?? []) {
+                assertNotFlag(tool, "tools entry");
+                args.push("--allow-tool", tool);
+            }
+        }
+        else {
+            // Headless default per the capability matrix: units must run without
+            // interactive tool-approval prompts.
+            args.push("--allow-all-tools");
+        }
+        if (req.schema) {
+            // Structured unit: ask for the documented JSON envelope so the result
+            // extractor can pull the final message + session id deterministically.
+            args.push("--output-format", "json");
+        }
+        args.push("-p", buildPromptPayload(req));
+        return { argv: [profile.bin, ...args] };
+    },
+};

package/dist/integrations/harnesses/copilot/index.js

@@ -0,0 +1,59 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * GitHub Copilot CLI harness (P2 integration, plan §"The adapter contract").
+ *
+ * Per-harness barrel gathering the Copilot CLI integration surfaces:
+ *   - agent command builder → ./agent-builder.ts    (copilotBuilder)
+ *   - result extractor      → ./result-extractor.ts (copilotResultExtractor)
+ *
+ * It also defines {@link CopilotHarness}, the {@link AkmHarness} descriptor
+ * that `HARNESS_REGISTRY` registers. This is the LOCAL Copilot CLI
+ * (`copilot -p …`); the cloud "Copilot coding agent" is the plan's
+ * cloud-delegate pattern and is a separate, future descriptor.
+ */
+import { BaseHarness } from "../types.js";
+import { copilotBuilder } from "./agent-builder.js";
+import { copilotResultExtractor } from "./result-extractor.js";
+export { COPILOT_PLATFORM, copilotBuilder } from "./agent-builder.js";
+export { copilotResultExtractor } from "./result-extractor.js";
+function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        ...c,
+    };
+}
+/**
+ * GitHub Copilot CLI (local headless CLI, not the cloud coding agent).
+ *
+ * Canonical id is `'copilot'`; no alias or distinct runtime identity.
+ */
+export class CopilotHarness extends BaseHarness {
+    id = "copilot";
+    displayName = "GitHub Copilot CLI";
+    aliases = [];
+    agentBuilder = copilotBuilder;
+    resultExtractor = copilotResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // akm spawns the `copilot` CLI locally per unit ⇒ local-runner.
+    pattern = "local-runner";
+    // `--output-format json` emits a documented JSON envelope akm parses, then
+    // validates against the node schema ⇒ native-json tier.
+    structuredOutput = "native-json";
+    // `copilot --resume <sessionId>` replays a previous session.
+    resume = { flag: "--resume", takesSessionId: true };
+    // Session-id env marker only. The matrix's other candidates (GH_TOKEN,
+    // bare COPILOT_* presence vars) are credential/presence flags that would
+    // stamp identity onto manual runs, so they are deliberately NOT registered
+    // (see `AkmHarness.identityEnv`).
+    identityEnv = ["COPILOT_SESSION_ID"];
+    capabilities = caps({
+        agentDispatch: true,
+        detection: true,
+    });
+}

package/dist/integrations/harnesses/copilot/result-extractor.js

@@ -0,0 +1,151 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Keys that may carry the final answer, in precedence order. */
+const TEXT_KEYS = ["result", "response", "text", "output", "content", "message"];
+/** Keys that may carry the harness-native session id, in precedence order. */
+const SESSION_KEYS = ["session_id", "sessionId", "conversation_id", "conversationId", "thread_id", "threadId"];
+/**
+ * Coerce a candidate value into text. Handles the shapes Copilot's envelope
+ * nests answers in: bare strings, `{content|text}` wrappers (assistant
+ * message objects), and arrays of `{type:"text",text}` content blocks.
+ * Depth-bounded: JSON.parse output is acyclic, but nesting is capped anyway
+ * so a pathological envelope cannot recurse unboundedly.
+ */
+function textOf(value, depth = 0) {
+    if (depth > 4)
+        return undefined;
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        const parts = [];
+        for (const block of value) {
+            const t = textOf(block, depth + 1);
+            if (t)
+                parts.push(t);
+        }
+        return parts.length > 0 ? parts.join("\n") : undefined;
+    }
+    if (isRecord(value)) {
+        return textOf(value.content ?? value.text, depth + 1);
+    }
+    return undefined;
+}
+/** Extract the final-answer text from one parsed JSON value, if any. */
+function extractText(value) {
+    if (typeof value === "string")
+        return value;
+    if (!isRecord(value))
+        return undefined;
+    for (const key of TEXT_KEYS) {
+        if (!(key in value))
+            continue;
+        const text = textOf(value[key]);
+        if (text !== undefined)
+            return text;
+    }
+    return undefined;
+}
+/** Extract a harness-native session id from one parsed JSON value, if any. */
+function extractSessionId(value) {
+    if (!isRecord(value))
+        return undefined;
+    for (const key of SESSION_KEYS) {
+        const candidate = value[key];
+        if (typeof candidate === "string" && candidate.length > 0)
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * `type` discriminator values Copilot's `--output-format json` envelopes are
+ * documented to use (plus the `session.*` event family). Deliberately a
+ * CLOSED set: a schema unit's own answer may legitimately be a discriminated
+ * union with a `type` field (`{"type":"success","output":"data"}`), and
+ * treating ANY string `type` as a transport marker would unwrap — and
+ * corrupt — such answers. An unrecognized type degrades to raw pass-through,
+ * which the schema validator handles (whole object) and free-text tolerates.
+ */
+const ENVELOPE_TYPES = new Set(["result", "response", "message", "assistant", "error"]);
+/**
+ * Does this parsed object look like one of Copilot's transport ENVELOPES (a
+ * `result`/event document) rather than a bare JSON answer the model produced?
+ *
+ * Copilot's `--output-format json` documents always carry a transport marker:
+ * a known `type` discriminator (`"result"`, `"session.start"`, `"message"`, …)
+ * and, in every documented result envelope, a session-id field. A bare
+ * structured answer a schema unit was asked for — e.g. `{"result":"ok"}` or
+ * `{"type":"success","output":"data"}` — carries neither a known discriminator
+ * nor (normally) a session-id key. Unwrapping such an answer would hand the
+ * schema validator only the field value (`"ok"`) and reject the run despite
+ * valid JSON (PR #714 review), so we only unwrap objects that are genuinely
+ * envelopes and pass everything else through raw.
+ */
+function isTransportEnvelope(value) {
+    const type = value.type;
+    if (typeof type === "string" && (ENVELOPE_TYPES.has(type) || type.startsWith("session.")))
+        return true;
+    return extractSessionId(value) !== undefined;
+}
+/** JSON.parse that returns undefined instead of throwing. */
+function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Normalize a raw copilot run result into `{ text, sessionId? }`.
+ * See the module doc for the three stdout shapes handled.
+ */
+export const copilotResultExtractor = (result) => {
+    // The raw result's own sessionId (SDK-style paths) is the fallback; an id
+    // found in the output stream wins because it is fresher.
+    const fallbackSessionId = result.sessionId;
+    const raw = result.stdout.trim();
+    // Shape 1 — whole stdout is one JSON document (spawn may have pre-parsed
+    // it when the profile requested parseOutput: "json").
+    const whole = result.parsed !== undefined ? result.parsed : raw.length > 0 ? tryParseJson(raw) : undefined;
+    if (whole !== undefined) {
+        const sessionId = extractSessionId(whole) ?? fallbackSessionId;
+        // A bare JSON OBJECT with no transport marker is a legitimate structured
+        // answer (a schema unit's `{"result":"ok"}`), NOT an envelope — pass its
+        // raw JSON through so the engine's schema validator receives the whole
+        // object instead of an unwrapped field value (PR #714 review). Only
+        // genuine Copilot envelopes are unwrapped; non-object JSON (a top-level
+        // string/array/primitive) keeps the prior extraction. Either way, an
+        // unknown envelope with no recognized text key falls back to raw stdout.
+        const text = isRecord(whole) && !isTransportEnvelope(whole) ? raw : (extractText(whole) ?? raw);
+        return { text, ...(sessionId ? { sessionId } : {}) };
+    }
+    // Shape 2 — JSONL event stream: last text-bearing event wins; first
+    // session-id-bearing event supplies the id. Non-JSON lines are banner
+    // noise and are skipped.
+    let lastText;
+    let streamSessionId;
+    let sawJsonLine = false;
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const event = tryParseJson(trimmed);
+        if (event === undefined)
+            continue;
+        sawJsonLine = true;
+        streamSessionId ??= extractSessionId(event);
+        const text = extractText(event);
+        if (text !== undefined)
+            lastText = text;
+    }
+    if (sawJsonLine) {
+        const sessionId = streamSessionId ?? fallbackSessionId;
+        return { text: lastText ?? raw, ...(sessionId ? { sessionId } : {}) };
+    }
+    // Shape 3 — plain text passthrough.
+    return { text: raw, ...(fallbackSessionId ? { sessionId: fallbackSessionId } : {}) };
+};

package/dist/integrations/harnesses/gemini/agent-builder.js

@@ -0,0 +1,120 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Gemini CLI agent command builder (P2, plan §"The adapter contract" step 2 /
+ * §"Capability matrix").
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * headless argv the `gemini` CLI expects. Per the capability matrix the
+ * headless invocation is:
+ *
+ *   gemini -p "<prompt>"
+ *
+ * with `--output-format json` for structured output, `--model <m>` for model
+ * selection, and `--resume <id>` for resume. Resume is registry-side
+ * (`AkmHarness.resume` — Gemini's resume IS flag-shaped, so the shared
+ * `HarnessResumeSupport` seam covers it); it is not built here because
+ * `AgentDispatchRequest` carries no session id. The `GEMINI_CLI=1` identity
+ * env marker is likewise registry-side (`AkmHarness.identityEnv` /
+ * `agent-identity.ts`), not a builder concern.
+ *
+ * Platform-specific mapping decisions (all localized here, per the adapter
+ * contract):
+ *
+ * - **systemPrompt** — Gemini CLI has no system-prompt flag in headless mode
+ *   (system text comes from `GEMINI.md` context files / `GEMINI_SYSTEM_MD`),
+ *   so the system prompt is folded into the `-p` payload ahead of the task
+ *   prompt, separated by a blank line. `assertNotFlag` still guards it so a
+ *   `--`-prefixed system prompt cannot turn the front of the `-p` value into
+ *   a flag.
+ * - **schema** — the matrix places Gemini in the "via prompt+validate" tier
+ *   (no native `--output-schema` equivalent, unlike Codex — so no temp-file
+ *   plumbing here), so the JSON Schema is passed through the prompt: a
+ *   directive matching the engine's wording (`step-work.ts`
+ *   `buildUnitPrompt`) is appended to the `-p` payload, and
+ *   `--output-format json` is emitted so stdout is the documented JSON
+ *   envelope the gemini result extractor normalizes. The engine's shared
+ *   retry-until-valid loop performs the actual validation.
+ * - **tools** — a string/array tool policy maps to repeated
+ *   `--allowed-tools <t>` flags (Gemini's run-without-confirmation
+ *   allowlist). A *structured* policy object is NOT expressible as Gemini
+ *   flags; it is deliberately dropped without widening to an auto-approve
+ *   flag (never silently widen a restriction). With no policy at all,
+ *   NOTHING is emitted — the matrix's headless shape is the bare
+ *   `gemini -p "<p>"`; autonomy flags (`--yolo`, `--approval-mode`) belong in
+ *   `profile.args` where the operator opts in explicitly.
+ *
+ * NOT registered anywhere: `builders.ts` / `harnesses/index.ts` wiring is a
+ * follow-up integration task. Exported standalone so that task only adds a
+ * registry entry.
+ */
+import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
+/** Canonical harness/platform id used for model-alias resolution. */
+export const GEMINI_PLATFORM = "gemini";
+/**
+ * Split a tool policy into individual tool names for `--allowed-tools`.
+ * Strings are comma-separated lists; arrays are taken as-is. Structured
+ * policy objects return `undefined` (not expressible as Gemini flags — see
+ * module doc).
+ */
+function toolPolicyEntries(tools) {
+    if (typeof tools === "string") {
+        return tools
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean);
+    }
+    if (Array.isArray(tools)) {
+        return tools.map((t) => t.trim()).filter(Boolean);
+    }
+    return undefined;
+}
+/**
+ * Assemble the `-p` payload: optional system prompt, the task prompt, and —
+ * when a schema is requested — the same schema directive the workflow
+ * engine's prompt assembly uses, so both dispatch paths speak one dialect.
+ */
+function buildPromptPayload(req) {
+    const sections = [];
+    if (req.systemPrompt)
+        sections.push(req.systemPrompt);
+    sections.push(req.prompt);
+    if (req.schema) {
+        sections.push(`Respond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${JSON.stringify(req.schema)}`);
+    }
+    return sections.join("\n\n");
+}
+/**
+ * Gemini CLI builder.
+ * Command shape:
+ *   gemini [--model <m>] [--allowed-tools <t> ...]
+ *          [--output-format json] -p "<systemPrompt?\n\nprompt\n\nschema?>"
+ */
+export const geminiBuilder = {
+    platform: GEMINI_PLATFORM,
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        const args = [...profile.args];
+        if (req.model) {
+            const resolved = resolveDispatchModel(req, profile, GEMINI_PLATFORM);
+            args.push("--model", resolved);
+        }
+        if (req.tools) {
+            // Structured policy objects (entries === undefined) emit NO flags:
+            // dropping a restriction must never widen to auto-approval.
+            for (const tool of toolPolicyEntries(req.tools) ?? []) {
+                assertNotFlag(tool, "tools entry");
+                args.push("--allowed-tools", tool);
+            }
+        }
+        if (req.schema) {
+            // Structured unit: ask for the documented JSON envelope so the result
+            // extractor can pull the final message + session id deterministically.
+            args.push("--output-format", "json");
+        }
+        args.push("-p", buildPromptPayload(req));
+        return { argv: [profile.bin, ...args] };
+    },
+};

package/dist/integrations/harnesses/gemini/index.js

@@ -0,0 +1,59 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Gemini CLI harness (P2 integration, plan §"The adapter contract").
+ *
+ * Per-harness barrel gathering the Gemini CLI integration surfaces:
+ *   - agent command builder → ./agent-builder.ts    (geminiBuilder)
+ *   - result extractor      → ./result-extractor.ts (geminiResultExtractor)
+ *
+ * It also defines {@link GeminiHarness}, the {@link AkmHarness} descriptor
+ * that `HARNESS_REGISTRY` registers. Dispatch-only: no native session-log
+ * reader or config importer yet.
+ */
+import { BaseHarness } from "../types.js";
+import { geminiBuilder } from "./agent-builder.js";
+import { geminiResultExtractor } from "./result-extractor.js";
+export { GEMINI_PLATFORM, geminiBuilder } from "./agent-builder.js";
+export { geminiResultExtractor } from "./result-extractor.js";
+function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        ...c,
+    };
+}
+/**
+ * Gemini CLI.
+ *
+ * Canonical id is `'gemini'`; no alias or distinct runtime identity.
+ */
+export class GeminiHarness extends BaseHarness {
+    id = "gemini";
+    displayName = "Gemini CLI";
+    aliases = [];
+    agentBuilder = geminiBuilder;
+    resultExtractor = geminiResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // akm spawns the `gemini` CLI locally per unit ⇒ local-runner.
+    pattern = "local-runner";
+    // `--output-format json` emits a documented JSON envelope akm parses, then
+    // validates against the node schema ⇒ native-json tier.
+    structuredOutput = "native-json";
+    // `gemini --resume <id>` replays a previous session.
+    resume = { flag: "--resume", takesSessionId: true };
+    // The matrix's identity marker: Gemini CLI stamps GEMINI_CLI=1 only on
+    // processes it spawns, so it genuinely means "running under gemini" (it is
+    // not a user-profile config var) — but its VALUE ("1") is a bare flag, not
+    // a session id, so it is registered as `presenceEnv` (harness inference
+    // only), never `identityEnv` (whose values persist as agent_session_id).
+    presenceEnv = ["GEMINI_CLI"];
+    capabilities = caps({
+        agentDispatch: true,
+        detection: true,
+    });
+}

package/dist/integrations/harnesses/gemini/result-extractor.js

@@ -0,0 +1,121 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Keys that may carry the final answer, in precedence order. `response` is
+ * Gemini's documented `--output-format json` envelope key.
+ */
+const TEXT_KEYS = ["response", "result", "text", "output", "content", "message"];
+/** Keys that may carry the harness-native session id, in precedence order. */
+const SESSION_KEYS = ["session_id", "sessionId", "conversation_id", "conversationId", "chat_id", "chatId"];
+/**
+ * Coerce a candidate value into text. Handles the shapes Gemini nests
+ * answers in: bare strings, `{content|text}` wrappers (assistant message
+ * objects), and arrays of `{type:"text",text}` content blocks (Gemini API
+ * `parts`-style lists). Depth-bounded: JSON.parse output is acyclic, but
+ * nesting is capped anyway so a pathological envelope cannot recurse
+ * unboundedly.
+ */
+function textOf(value, depth = 0) {
+    if (depth > 4)
+        return undefined;
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        const parts = [];
+        for (const block of value) {
+            const t = textOf(block, depth + 1);
+            if (t)
+                parts.push(t);
+        }
+        return parts.length > 0 ? parts.join("\n") : undefined;
+    }
+    if (isRecord(value)) {
+        return textOf(value.content ?? value.text, depth + 1);
+    }
+    return undefined;
+}
+/** Extract the final-answer text from one parsed JSON value, if any. */
+function extractText(value) {
+    if (typeof value === "string")
+        return value;
+    if (!isRecord(value))
+        return undefined;
+    for (const key of TEXT_KEYS) {
+        if (!(key in value))
+            continue;
+        const text = textOf(value[key]);
+        if (text !== undefined)
+            return text;
+    }
+    return undefined;
+}
+/** Extract a harness-native session id from one parsed JSON value, if any. */
+function extractSessionId(value) {
+    if (!isRecord(value))
+        return undefined;
+    for (const key of SESSION_KEYS) {
+        const candidate = value[key];
+        if (typeof candidate === "string" && candidate.length > 0)
+            return candidate;
+    }
+    return undefined;
+}
+/** JSON.parse that returns undefined instead of throwing. */
+function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Normalize a raw gemini run result into `{ text, sessionId? }`.
+ * See the module doc for the three stdout shapes handled.
+ */
+export const geminiResultExtractor = (result) => {
+    // The raw result's own sessionId (SDK-style paths) is the fallback; an id
+    // found in the output stream wins because it is fresher.
+    const fallbackSessionId = result.sessionId;
+    const raw = result.stdout.trim();
+    // Shape 1 — whole stdout is one JSON document (spawn may have pre-parsed
+    // it when the profile requested parseOutput: "json").
+    const whole = result.parsed !== undefined ? result.parsed : raw.length > 0 ? tryParseJson(raw) : undefined;
+    if (whole !== undefined) {
+        const sessionId = extractSessionId(whole) ?? fallbackSessionId;
+        // Unknown envelope (no recognized text key — includes the error-only
+        // variant): fall back to raw stdout so downstream embedded-JSON parsing
+        // and failure handling still have the full material to work with.
+        const text = extractText(whole) ?? raw;
+        return { text, ...(sessionId ? { sessionId } : {}) };
+    }
+    // Shape 2 — JSONL event stream: last text-bearing event wins; first
+    // session-id-bearing event supplies the id. Non-JSON lines are banner
+    // noise and are skipped.
+    let lastText;
+    let streamSessionId;
+    let sawJsonLine = false;
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const event = tryParseJson(trimmed);
+        if (event === undefined)
+            continue;
+        sawJsonLine = true;
+        streamSessionId ??= extractSessionId(event);
+        const text = extractText(event);
+        if (text !== undefined)
+            lastText = text;
+    }
+    if (sawJsonLine) {
+        const sessionId = streamSessionId ?? fallbackSessionId;
+        return { text: lastText ?? raw, ...(sessionId ? { sessionId } : {}) };
+    }
+    // Shape 3 — plain text passthrough.
+    return { text: raw, ...(fallbackSessionId ? { sessionId: fallbackSessionId } : {}) };
+};