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

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

@@ -0,0 +1,58 @@
+// 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/.
+/**
+ * Amazon Q Developer CLI harness (P2 integration, plan §"The adapter
+ * contract").
+ *
+ * Per-harness barrel gathering the Amazon Q integration surfaces:
+ *   - agent command builder → ./agent-builder.ts    (amazonqBuilder)
+ *   - result extractor      → ./result-extractor.ts (amazonqResultExtractor)
+ *
+ * It also defines {@link AmazonqHarness}, 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 { AMAZONQ_RESUME_FLAG, amazonqBuilder } from "./agent-builder.js";
+import { amazonqResultExtractor } from "./result-extractor.js";
+export { AMAZONQ_PLATFORM, AMAZONQ_RESUME_FLAG, amazonqBuilder } from "./agent-builder.js";
+export { amazonqResultExtractor, stripTerminalFraming } from "./result-extractor.js";
+function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        ...c,
+    };
+}
+/**
+ * Amazon Q Developer CLI (`q`).
+ *
+ * Canonical id is `'amazonq'`; no alias or distinct runtime identity.
+ */
+export class AmazonqHarness extends BaseHarness {
+    id = "amazonq";
+    displayName = "Amazon Q Developer CLI";
+    aliases = [];
+    agentBuilder = amazonqBuilder;
+    resultExtractor = amazonqResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // akm spawns `q chat` locally per unit ⇒ local-runner.
+    pattern = "local-runner";
+    // No documented structured output: akm injects the schema into the prompt
+    // and extracts embedded JSON from plain-text stdout.
+    structuredOutput = "none";
+    // Q's `--resume` is a BARE flag (takesSessionId: false): it replays the
+    // previous conversation of the working directory and takes no session id
+    // (see AMAZONQ_RESUME_FLAG in ./agent-builder.ts).
+    resume = { flag: AMAZONQ_RESUME_FLAG, takesSessionId: false };
+    // No `identityEnv`: the matrix lists Q's identity markers as uncertain, and
+    // Q stamps no session var onto child processes.
+    capabilities = caps({
+        agentDispatch: true,
+        detection: true,
+    });
+}

package/dist/integrations/harnesses/amazonq/result-extractor.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/.
+const ESC = "\u001B";
+const BEL = "\u0007";
+/**
+ * Matches ANSI CSI sequences (colors, cursor movement, erase-line) and OSC
+ * sequences (title, hyperlink) terminated by BEL or ST. Built via the RegExp
+ * constructor so the control characters live in named string constants
+ * instead of regex-literal escapes.
+ */
+const ANSI_SEQUENCE = new RegExp(`${ESC}\\[[0-9;?]*[ -/]*[@-~]` + `|${ESC}\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, "g");
+/**
+ * Resolve carriage-return overwrites within one physical line: a terminal
+ * would redraw from column 0 at each `\r`, so only the segment after the last
+ * `\r` survives (spinner frames like "⠋ Thinking..." disappear exactly as
+ * they do on screen). A trailing bare `\r` (CRLF line endings) is handled by
+ * splitting on `\r?\n` before this runs.
+ */
+function resolveCarriageReturns(line) {
+    const lastCr = line.lastIndexOf("\r");
+    return lastCr === -1 ? line : line.slice(lastCr + 1);
+}
+/** Strip terminal framing from raw captured stdout. See module doc, rule 1. */
+export function stripTerminalFraming(raw) {
+    const lines = raw.split(/\r?\n/).map((line) => resolveCarriageReturns(line).replace(ANSI_SEQUENCE, ""));
+    // Drop Q's "> " response marker from the first non-empty line only — deeper
+    // occurrences may be legitimate content (markdown blockquotes).
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (line.trim().length === 0)
+            continue;
+        if (line.startsWith("> "))
+            lines[i] = line.slice(2);
+        break;
+    }
+    return lines.join("\n").trim();
+}
+/**
+ * Normalize a raw Amazon Q run result into `{ text, sessionId? }`.
+ * See the module doc for the rules.
+ */
+export const amazonqResultExtractor = (result) => {
+    const sessionId = result.sessionId;
+    // Rule 2: a pre-parsed whole-stdout JSON *string* is the answer itself.
+    const text = typeof result.parsed === "string" ? result.parsed.trim() : stripTerminalFraming(result.stdout);
+    return { text, ...(sessionId ? { sessionId } : {}) };
+};

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

@@ -11,15 +11,48 @@
  * in `agent/builders.ts`, which imports this builder back into
  * `BUILTIN_BUILDERS`.
  *
- * Behaviour-preserving relocation: the produced argv is byte-identical to the
- * pre-migration `claudeBuilder`. The builder's `platform` stays `'claude'` (the
- * canonical harness id).
+ * ## Structured output (Codex round-3 finding A)
+ *
+ * The headless `claude -p` (`--print`) CLI has NO native output-SCHEMA flag
+ * (unlike Codex's `--output-schema <file>`). Its documented structured path is
+ * `--output-format json`, which wraps the run in a RESULT ENVELOPE
+ * (`{"type":"result","result":"<final answer>","session_id":"…", …}`) — the
+ * "native-json" tier, NOT "native-schema". (The registry's earlier
+ * `native-schema` claim described Claude Code's IN-HARNESS `Workflow`/`agent()`
+ * tool-input-schema path, which is a different execution surface than the
+ * agentBuilder dispatch akm's local-runner uses; the descriptor is aligned to
+ * `native-json` to match this builder honestly.)
+ *
+ * So for a schema-bearing unit this builder emits `--output-format json` and
+ * appends the SAME schema directive the engine's prompt assembly uses
+ * (`step-work.ts` `buildUnitPrompt`) so a direct (non-workflow) dispatch is
+ * self-sufficient — matching the copilot/gemini native-json builders. The
+ * result envelope is unwrapped by `./result-extractor.ts`, and the engine's
+ * shared `runStructured` retry-until-valid loop still validates the extracted
+ * text against the node schema (constrained/hinted output is trusted but
+ * verified). Without a schema the argv is byte-identical to the pre-fix shape.
+ *
+ * The builder's `platform` stays `'claude'` (the canonical harness id).
  */
-import { assertNotFlag, normalizeTools } from "../../agent/builder-shared.js";
-import { resolveModel } from "../../agent/model-aliases.js";
+import { assertNotFlag, normalizeTools, resolveDispatchModel, } from "../../agent/builder-shared.js";
+/**
+ * Assemble the positional prompt: the task prompt and — when a schema is
+ * requested — the same schema directive the workflow engine's prompt assembly
+ * uses (`step-work.ts` `buildUnitPrompt`), so both dispatch paths speak one
+ * dialect. Claude Code takes the system prompt as a `--system-prompt` FLAG (it
+ * has one, unlike copilot/gemini), so only the schema directive is folded in
+ * here.
+ */
+function buildPromptPayload(req) {
+    if (!req.schema)
+        return req.prompt;
+    return `${req.prompt}\n\nRespond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${JSON.stringify(req.schema)}`;
+}
 /**
  * Claude Code builder.
- * Command shape: claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>] --print "<prompt>"
+ * Command shape:
+ *   claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>]
+ *          [--output-format json] --print -- "<prompt (+ schema directive)>"
  *
  * --print switches Claude Code to non-interactive captured output mode.
  */
@@ -33,16 +66,21 @@ export const claudeBuilder = {
             args.push("--system-prompt", req.systemPrompt);
         }
         if (req.model) {
-            const resolved = resolveModel(req.model, "claude", profile.modelAliases, profile.globalModelAliases);
+            const resolved = resolveDispatchModel(req, profile, "claude");
             args.push("--model", resolved);
         }
         if (req.tools) {
             args.push("--allowedTools", normalizeTools(req.tools));
         }
+        if (req.schema) {
+            // Structured unit: request the documented JSON result envelope so
+            // `./result-extractor.ts` can pull the final answer + session id.
+            args.push("--output-format", "json");
+        }
         // --print = non-interactive, outputs to stdout — required for captured mode
         args.push("--print");
         args.push("--");
-        args.push(req.prompt);
+        args.push(buildPromptPayload(req));
         return { argv: [profile.bin, ...args] };
     },
 };

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

@@ -1,33 +1,13 @@
 // 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/.
-/**
- * Claude Code harness (#563).
- *
- * This is the per-harness barrel that gathers the Claude Code integration
- * surfaces that were previously scattered across the codebase:
- *   - session-log reader     → ./session-log.ts   (ClaudeCodeProvider)
- *   - agent command builder  → ./agent-builder.ts (claudeBuilder)
- *   - config importer        → ./config-import.ts (claudeCodeImporter)
- *
- * It also defines {@link ClaudeHarness}, the {@link AkmHarness} descriptor that
- * `HARNESS_REGISTRY` registers.
- *
- * ## id normalization bridge ('claude' vs 'claude-code')
- *
- * The canonical, persisted id is `'claude'` (used by the agent runner, agent
- * profiles, the Zod config schema and `--type` resolution after normalization).
- * `'claude-code'` is the historical RUNTIME identity — the string stamped on
- * session-log events/refs, the extracted-session dedup key, and the value
- * `resolveAgentIdentity` reports. It is registered as an `alias` and exposed as
- * `runtimeId` so BOTH directions round-trip via `normalizeHarnessId()` /
- * `denormalizeRuntimeIdentity()`. Existing persisted configs and session logs
- * that say `'claude-code'` keep working unchanged.
- */
 import { BaseHarness } from "../types.js";
 import { claudeBuilder } from "./agent-builder.js";
+import { claudeResultExtractor } from "./result-extractor.js";
+import { ClaudeCodeProvider } from "./session-log.js";
 export { claudeBuilder } from "./agent-builder.js";
 export { claudeCodeImporter } from "./config-import.js";
+export { claudeResultExtractor } from "./result-extractor.js";
 export { ClaudeCodeProvider } from "./session-log.js";
 function caps(c) {
     return {
@@ -36,7 +16,6 @@ function caps(c) {
         detection: false,
         configImport: false,
         runtimeIdentity: false,
-        v1Migration: false,
         ...c,
     };
 }
@@ -55,12 +34,33 @@ export class ClaudeHarness extends BaseHarness {
     // session-log provider, so offering it as a stash source is functional.
     setupDetectionDir = ".claude";
     agentBuilder = claudeBuilder;
+    resultExtractor = claudeResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // Claude Code is the in-harness pattern: the orchestrating session itself
+    // drives units via the `akm workflow` gate spine (`claude -p` headless
+    // dispatch also exists via `agentBuilder`, but the pattern classification
+    // follows the matrix row).
+    pattern = "in-harness";
+    // Structured output tier for the AGENT-DISPATCH (`claude -p`) path akm's
+    // local runner uses (Codex round-3 finding A). The headless CLI has NO
+    // output-schema flag — its documented structured path is `--output-format
+    // json`, a RESULT ENVELOPE akm parses (`./result-extractor.ts`) and then
+    // validates against the node schema ⇒ the "native-json" tier. (Claude Code's
+    // in-harness `Workflow`/`agent()` tool-input-schema path IS native-schema,
+    // but that is a different surface than the dispatch builder — the descriptor
+    // is aligned to what the builder honestly does.)
+    structuredOutput = "native-json";
+    // `claude --resume <sessionId>` replays a previous session in headless mode.
+    resume = { flag: "--resume", takesSessionId: true };
+    // Session-id env marker: presence of a concrete session id (not the bare
+    // "running under Claude Code" flag) attributes a run to this harness.
+    identityEnv = ["CLAUDE_SESSION_ID"];
+    sessionLogProvider = () => new ClaudeCodeProvider();
     capabilities = caps({
         sessionLogs: true,
         agentDispatch: true,
         detection: true,
         configImport: true,
         runtimeIdentity: true,
-        v1Migration: true,
     });
 }

package/dist/integrations/harnesses/claude/result-extractor.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/.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** JSON.parse that returns undefined instead of throwing. */
+function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Is this parsed object Claude Code's `--output-format json` RESULT ENVELOPE
+ * (rather than a bare JSON answer a schema unit produced without the flag)? A
+ * genuine envelope declares `type: "result"`, or carries the two envelope-only
+ * fields together (a string `result` AND a `session_id`). A bare structured
+ * answer — `{"result":"ok"}` — carries neither marker, so it is passed through
+ * raw and the engine's schema validator sees the whole object.
+ */
+function isResultEnvelope(value) {
+    if (value.type === "result")
+        return true;
+    return typeof value.result === "string" && asNonEmptyString(value.session_id) !== undefined;
+}
+/**
+ * Normalize a raw claude run result into `{ text, sessionId? }`. See the module
+ * doc for the two stdout shapes (JSON result envelope vs plain text).
+ */
+export const claudeResultExtractor = (result) => {
+    const fallbackSessionId = result.sessionId;
+    const raw = result.stdout;
+    const trimmed = raw.trim();
+    // Only attempt an envelope parse when stdout looks like a single JSON object
+    // (`--output-format json`). A plain-text run is passed through UNCHANGED
+    // (untrimmed) so schemaless dispatch stays byte-identical to today.
+    if (trimmed.startsWith("{")) {
+        const whole = result.parsed !== undefined ? result.parsed : tryParseJson(trimmed);
+        if (isRecord(whole) && isResultEnvelope(whole)) {
+            const text = typeof whole.result === "string" ? whole.result : trimmed;
+            const sessionId = asNonEmptyString(whole.session_id) ?? fallbackSessionId;
+            return { text, ...(sessionId ? { sessionId } : {}) };
+        }
+    }
+    return { text: raw, ...(fallbackSessionId ? { sessionId: fallbackSessionId } : {}) };
+};

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

@@ -0,0 +1,136 @@
+// 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).
+ *
+ * NOT registered anywhere yet: `HARNESS_REGISTRY` / `BUILTIN_BUILDERS` wiring
+ * is a follow-up integration task. Exported cleanly for that task to import.
+ */
+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 — kept here so the flag-shaped
+ * `HarnessResumeSupport` seam is not force-fitted. 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,62 @@
+// 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 { 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";
+function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        ...c,
+    };
+}
+/**
+ * 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), which the flag-shaped
+    // `HarnessResumeSupport` seam deliberately does not force-fit.
+    // 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 };
+};