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

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

@@ -0,0 +1,138 @@
+// 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/.
+/**
+ * OpenAI Codex CLI agent command builder (P2, plan §"The adapter contract" /
+ * §"Capability matrix").
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * headless argv the `codex` CLI expects:
+ *
+ *   codex exec --sandbox workspace-write [--model <m>] --json [--output-schema <file>] -- "<prompt>"
+ *
+ * Capability-matrix facts this builder encodes (July 2026 research):
+ *   - Headless invocation is the `exec` subcommand (`codex exec "<p>"`), not a
+ *     flag. The built-in codex profiles carry `args: []`, so the builder
+ *     prepends `exec` itself; a user profile that already pins `exec` as its
+ *     first arg is not doubled.
+ *   - `--json` switches stdout to a JSONL event stream — the input contract of
+ *     `./result-extractor.ts`. Always emitted, mirroring how the Claude builder
+ *     always emits `--print`: dispatch is the captured, non-interactive path.
+ *   - Codex is the NATIVE-SCHEMA tier (plan §"Structured-output
+ *     normalization"): `req.schema` is written to a temp file and passed via
+ *     `--output-schema <file>`. The file is tiny, uniquely named under the OS
+ *     temp dir, and intentionally NOT cleaned up here — `BuiltCommand` has no
+ *     post-run hook, and the spawned process reads the file after `build()`
+ *     returns. OS temp reaping owns the lifecycle. The engine still validates
+ *     the output defensively (the constrained output is trusted but verified).
+ *   - `codex exec` has no system-prompt flag; `req.systemPrompt` is folded
+ *     into the prompt payload (system text first, blank line, then the task),
+ *     after the `--` end-of-options separator so it can never be parsed as a
+ *     flag.
+ *   - Tool policy is omitted, but the builder DOES inject `--sandbox
+ *     workspace-write` so dispatched units can write to their working
+ *     directory.  `codex exec` defaults to a read-only sandbox that silently
+ *     blocks file writes; without this flag the unit returns "workspace is
+ *     read-only" and the engine marks the step complete with no real mutation.
+ *     `--ask-for-approval` is NOT injected — that flag only exists on the
+ *     interactive `codex` command, not on `codex exec`, and exec mode is
+ *     already non-approval-blocking.  Profile-supplied `--sandbox` flags
+ *     (long or short form) are preserved (not duplicated).
+ *   - Resume is the `codex exec resume <id>` SUBCOMMAND, not a flag, so it is
+ *     not expressible through `AgentDispatchRequest` (which has no session
+ *     field yet); {@link codexResumeArgs} exposes the argv prefix for the
+ *     integration task that wires session-id reuse from `workflow_run_units`.
+ *   - `req.effort` stays unconsumed (reserved; codex would take it as
+ *     `-c model_reasoning_effort=<v>` — left to the integration task so the
+ *     shared request contract's "no builder consumes it yet" note stays true).
+ *
+ * Registered: `codexBuilder` is `CodexHarness.agentBuilder` (`./index.ts`),
+ * one of the ten harnesses `HARNESS_REGISTRY` constructs
+ * (`harnesses/index.ts`); `agent/builders.ts` derives `BUILTIN_BUILDERS` from
+ * that registry, so this builder is reachable under the `"codex"` platform
+ * name without any further wiring.
+ */
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { assertNotFlag, resolveDispatchModel } from "../../agent/builder-shared.js";
+/**
+ * Write a node's JSON Schema to a fresh temp file for `--output-schema`.
+ *
+ * A unique `mkdtemp` directory per build avoids collisions between concurrent
+ * fan-out units dispatching in the same process. Returns the absolute file
+ * path (the value handed to the flag).
+ */
+export function writeCodexOutputSchemaFile(schema) {
+    const dir = mkdtempSync(join(tmpdir(), "akm-codex-schema-"));
+    const file = join(dir, "output-schema.json");
+    writeFileSync(file, `${JSON.stringify(schema, null, 2)}\n`, "utf8");
+    return file;
+}
+/**
+ * Argv prefix that resumes a previous codex session: `exec resume <id>`.
+ * Codex resume is a subcommand chain, not a flag. The harness-native session
+ * id comes from the unit row (stored opportunistically by the result
+ * extractor); akm never depends on it (plan §"Session, MCP, and identity").
+ */
+export function codexResumeArgs(sessionId) {
+    assertNotFlag(sessionId, "sessionId");
+    return ["exec", "resume", sessionId];
+}
+/**
+ * Return `base` plus the `--sandbox workspace-write` flag that makes `codex exec`
+ * able to write to its working directory.  `codex exec` defaults to a read-only
+ * sandbox that silently blocks file writes — without this flag the unit returns
+ * "workspace is read-only" and the engine marks the step complete with no real
+ * mutation.  If the profile already pins `--sandbox` (long or short form) the
+ * default is not duplicated.
+ *
+ * Note: `--ask-for-approval` is an *interactive* codex flag only — `codex exec`
+ * does not accept it (it errors with "unexpected argument").  Non-interactive
+ * exec mode is implicitly non-approval-blocking; `--sandbox workspace-write`
+ * alone is sufficient for dispatched units.
+ */
+function ensureSandboxFlags(base) {
+    const out = [...base];
+    if (!out.includes("--sandbox") && !out.includes("-s")) {
+        out.push("--sandbox", "workspace-write");
+    }
+    return out;
+}
+/**
+ * OpenAI Codex builder.
+ * Command shape: codex exec --sandbox workspace-write [--model <m>] --json [--output-schema <file>] -- "<prompt>"
+ */
+export const codexBuilder = {
+    platform: "codex",
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        // Built-in codex profiles ship `args: []`; headless dispatch is the `exec`
+        // subcommand. Don't double it when a user profile already pins it.
+        const extra = profile.args[0] === "exec" ? profile.args.slice(1) : [...profile.args];
+        // `codex exec` defaults to a read-only sandbox that silently blocks file
+        // writes — dispatched units would return "workspace is read-only" and the
+        // engine would mark them complete with no real mutation.  Force
+        // `workspace-write` (writes scoped to cwd) unless the profile already pins
+        // its own --sandbox flag (`--ask-for-approval` is not injectable here —
+        // see ensureSandboxFlags).
+        const sandboxArgs = ensureSandboxFlags(extra);
+        const args = ["exec", ...sandboxArgs];
+        if (req.model) {
+            const resolved = resolveDispatchModel(req, profile, "codex");
+            args.push("--model", resolved);
+        }
+        // JSONL event stream on stdout — the codex result extractor's input.
+        args.push("--json");
+        if (req.schema) {
+            // Native-schema tier: pass the node schema straight through.
+            args.push("--output-schema", writeCodexOutputSchemaFile(req.schema));
+        }
+        // No system-prompt flag exists on `codex exec` — fold it into the prompt.
+        const prompt = req.systemPrompt ? `${req.systemPrompt}\n\n${req.prompt}` : req.prompt;
+        args.push("--");
+        args.push(prompt);
+        return { argv: [profile.bin, ...args] };
+    },
+};

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

@@ -0,0 +1,52 @@
+// 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/.
+/**
+ * OpenAI Codex CLI harness (P2 integration, plan §"The adapter contract").
+ *
+ * Per-harness barrel gathering the Codex integration surfaces:
+ *   - agent command builder → ./agent-builder.ts    (codexBuilder)
+ *   - result extractor      → ./result-extractor.ts (codexResultExtractor)
+ *
+ * It also defines {@link CodexHarness}, the {@link AkmHarness} descriptor that
+ * `HARNESS_REGISTRY` registers. Dispatch-only: no native session-log reader or
+ * config importer yet.
+ */
+import { caps } from "../shared.js";
+import { BaseHarness } from "../types.js";
+import { codexBuilder } from "./agent-builder.js";
+import { codexResultExtractor } from "./result-extractor.js";
+export { codexBuilder, codexResumeArgs, writeCodexOutputSchemaFile } from "./agent-builder.js";
+export { codexResultExtractor } from "./result-extractor.js";
+/**
+ * OpenAI Codex CLI.
+ *
+ * Canonical id is `'codex'`; no alias or distinct runtime identity.
+ */
+export class CodexHarness extends BaseHarness {
+    id = "codex";
+    displayName = "OpenAI Codex CLI";
+    aliases = [];
+    agentBuilder = codexBuilder;
+    resultExtractor = codexResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // akm spawns `codex exec` locally per unit ⇒ local-runner.
+    pattern = "local-runner";
+    // `--output-schema <file>` enforces a caller-supplied JSON schema natively.
+    structuredOutput = "native-schema";
+    // No flag-shaped resume: codex resume is the `exec resume <id>` SUBCOMMAND
+    // chain (see `codexResumeArgs` in ./agent-builder.ts).
+    // Presence flag: CODEX_SANDBOX is stamped only on processes codex itself
+    // spawns inside its sandbox, so it genuinely means "running under codex" —
+    // but its VALUE (e.g. "seatbelt") is a sandbox mode, not a session id, so it
+    // is registered as `presenceEnv` (harness inference only), never
+    // `identityEnv` (whose values persist as agent_session_id). CODEX_HOME (the
+    // matrix's other candidate) is deliberately NOT registered anywhere: it is a
+    // user config-dir var commonly exported in shell profiles, so it would stamp
+    // identity onto manual runs (see `AkmHarness.presenceEnv`).
+    presenceEnv = ["CODEX_SANDBOX"];
+    capabilities = caps({
+        agentDispatch: true,
+        detection: true,
+    });
+}

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

@@ -0,0 +1,73 @@
+// 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);
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** Interpret one parsed JSONL event in either codex event dialect. */
+function interpretEvent(event) {
+    // Legacy protocol: {"id":..., "msg":{"type": ...}}
+    const msg = event.msg;
+    if (isRecord(msg)) {
+        switch (msg.type) {
+            case "session_configured":
+                return { sessionId: asNonEmptyString(msg.session_id) };
+            case "agent_message":
+                return { agentMessage: asNonEmptyString(msg.message) };
+            case "task_complete":
+                return { finalMessage: asNonEmptyString(msg.last_agent_message) };
+            default:
+                return {};
+        }
+    }
+    // Newer protocol: flat {"type": "thread.started" | "item.completed" | ...}
+    switch (event.type) {
+        case "thread.started":
+            return { sessionId: asNonEmptyString(event.thread_id) };
+        case "item.completed": {
+            const item = event.item;
+            if (isRecord(item) && item.type === "agent_message") {
+                return { agentMessage: asNonEmptyString(item.text) };
+            }
+            return {};
+        }
+        default:
+            return {};
+    }
+}
+/**
+ * Codex result extractor: JSONL event stream (either dialect) → final agent
+ * message + opportunistic session id, with a plain-stdout fallback.
+ */
+export const codexResultExtractor = (result) => {
+    let sessionId = result.sessionId;
+    let lastAgentMessage;
+    let finalMessage;
+    for (const line of result.stdout.split("\n")) {
+        const trimmed = line.trim();
+        // Every codex event line is a JSON object; skip banner/noise lines cheaply.
+        if (!trimmed.startsWith("{"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue; // not a complete JSON line (e.g. wrapped text) — ignore
+        }
+        if (!isRecord(parsed))
+            continue;
+        const contribution = interpretEvent(parsed);
+        if (contribution.sessionId)
+            sessionId = contribution.sessionId;
+        if (contribution.agentMessage)
+            lastAgentMessage = contribution.agentMessage;
+        if (contribution.finalMessage)
+            finalMessage = contribution.finalMessage;
+    }
+    const text = finalMessage ?? lastAgentMessage ?? result.stdout.trim();
+    return sessionId === undefined ? { text } : { text, sessionId };
+};

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

@@ -0,0 +1,122 @@
+// 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 (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.
+ *
+ * Registered: `copilotBuilder` is `CopilotHarness.agentBuilder`
+ * (`./index.ts`), one of the ten harnesses `HARNESS_REGISTRY` constructs
+ * (`harnesses/index.ts`); `agent/builders.ts` derives `BUILTIN_BUILDERS` from
+ * that registry, so this builder is reachable under the `"copilot"` platform
+ * name without any further wiring.
+ */
+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,48 @@
+// 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 { caps } from "../shared.js";
+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";
+/**
+ * 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";
+    // 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 } : {}) };
+};