akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

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

@@ -0,0 +1,63 @@
+// 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,
+        v1Migration: 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 };
+};

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 (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 } from "../../agent/builder-shared.js";
+import { resolveModel } from "../../agent/model-aliases.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 = resolveModel(req.model, COPILOT_PLATFORM, profile.modelAliases, profile.globalModelAliases);
+            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,60 @@
+// 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,
+        v1Migration: 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,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/.
+/**
+ * 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 } from "../../agent/builder-shared.js";
+import { resolveModel } from "../../agent/model-aliases.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 = resolveModel(req.model, GEMINI_PLATFORM, profile.modelAliases, profile.globalModelAliases);
+            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,60 @@
+// 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,
+        v1Migration: 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,
+    });
+}