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

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

@@ -0,0 +1,126 @@
+// 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/.
+/**
+ * OpenHands 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 `openhands` CLI expects. Per the capability matrix the
+ * headless invocation is:
+ *
+ *   openhands --headless -t "<p>" --json
+ *
+ * with `--json` producing the documented JSONL event stream (structured tier
+ * "via prompt+validate"), workspace-state resume (no session-id flag), and
+ * native MCP support.
+ *
+ * Platform-specific mapping decisions (all localized here, per the adapter
+ * contract):
+ *
+ * - **prompt** — `--task` is the long form of the matrix's `-t` (used for
+ *   self-documenting argv, mirroring the aider builder's `--message`). Like
+ *   aider — and unlike claude/codex/pi — there is NO positional prompt and NO
+ *   `--` end-of-options separator to hide behind: the task is a *flag value*.
+ *   The glued `--task=<payload>` form is therefore used so a payload that
+ *   begins with `-`/`--` binds to the flag lexically and can never be parsed
+ *   as a separate option by the CLI's argument parser.
+ * - **--headless / --json** — always emitted: `--headless` is what makes a
+ *   captured, unattended run possible, and `--json` switches stdout to the
+ *   JSONL event stream that `./result-extractor.ts` normalizes (the same
+ *   "dispatch is the captured path" reasoning as the Claude builder's
+ *   unconditional `--print`; both flags are the matrix's documented headless
+ *   shape).
+ * - **systemPrompt** — OpenHands headless mode has no documented
+ *   system-prompt flag (agent behaviour is shaped by its own agent configs
+ *   and microagents). Folded into the task payload — system text first, blank
+ *   line, then the task — mirroring the aider/codex treatment.
+ * - **model** — OpenHands does not take the model on the headless command
+ *   line; its documented configuration channel is the `LLM_MODEL` environment
+ *   variable (config.toml `[llm] model` equivalent). The alias is resolved via
+ *   `resolveModel` with this platform id and returned on `BuiltCommand.env`
+ *   (the seam exists precisely for platform-specific extras), NOT as an
+ *   invented `--model` flag that would produce a silently broken command.
+ * - **schema** — the matrix places OpenHands in the "via prompt+validate"
+ *   tier (plan §"Structured-output normalization", tier "native-json"): no
+ *   Codex-style `--output-schema` flag exists, so NO temp schema file is
+ *   written; the JSON Schema is injected into the task payload using the
+ *   exact directive wording of the engine's prompt assembly
+ *   (`step-work.ts` `buildUnitPrompt`) and the pi/aider builders, so
+ *   all dispatch paths speak one dialect. Downstream, the extractor pulls the
+ *   final message out of the JSONL stream and the engine's shared
+ *   retry-until-valid loop performs the actual validation.
+ * - **tools** — deliberately unconsumed. OpenHands has no per-tool allowlist
+ *   flag; tool access is governed by its own runtime/sandbox configuration
+ *   and (natively supported) MCP config. A restrictive policy is therefore
+ *   dropped rather than approximated — never silently widened.
+ * - **resume/session** — NOT expressible: per the matrix OpenHands resumes
+ *   from *workspace state*, not a session-id flag, so there is no flag-shaped
+ *   `HarnessResumeSupport` to export. The extractor still captures a
+ *   conversation/session id opportunistically when the stream reveals one;
+ *   akm's `workflow_run_units` remains the durable source of truth either way
+ *   (plan §"Session, MCP, and identity across harnesses").
+ * - **effort** — stays unconsumed (reserved; the shared request contract's
+ *   "no builder consumes it yet" note stays true).
+ *
+ * NOT registered anywhere: `builders.ts` / `harnesses/index.ts` wiring is a
+ * follow-up integration task (as is the registry entry declaring
+ * `pattern: "local-runner"`, `structuredOutput: "native-json"`, and no
+ * `resume`). 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 OPENHANDS_PLATFORM = "openhands";
+/**
+ * Env var OpenHands reads its LLM model from — the platform's documented
+ * model-selection channel for headless runs (there is no headless model
+ * flag). Exported so the follow-up integration task and tests share the one
+ * constant.
+ */
+export const OPENHANDS_MODEL_ENV = "LLM_MODEL";
+/**
+ * Assemble the `--task` payload: optional system text, the task prompt, and —
+ * when a schema is requested — the same schema directive the workflow
+ * engine's prompt assembly uses (OpenHands has no native schema flag, so the
+ * prompt is the schema's only channel; plan §"Structured-output
+ * normalization").
+ */
+function buildTaskPayload(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");
+}
+/**
+ * OpenHands builder.
+ * Command shape:
+ *   openhands --headless --json --task=<[system\n\n]prompt[\n\nschema directive]>
+ * with the resolved model (if any) carried on env as LLM_MODEL.
+ */
+export const openhandsBuilder = {
+    platform: OPENHANDS_PLATFORM,
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        const args = [...profile.args];
+        // Headless essentials (matrix shape): non-interactive run, JSONL stdout
+        // for the extractor.
+        args.push("--headless");
+        args.push("--json");
+        // Glued form: the payload is a flag VALUE (no positional prompt exists),
+        // so `=` binding keeps a dash-leading payload from parsing as an option.
+        args.push(`--task=${buildTaskPayload(req)}`);
+        let env;
+        if (req.model) {
+            const resolved = resolveModel(req.model, OPENHANDS_PLATFORM, profile.modelAliases, profile.globalModelAliases);
+            // Model travels via env, not argv — OpenHands' documented channel.
+            env = { [OPENHANDS_MODEL_ENV]: resolved };
+        }
+        return { argv: [profile.bin, ...args], ...(env ? { env } : {}) };
+    },
+};

package/dist/integrations/harnesses/openhands/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/.
+/**
+ * OpenHands CLI harness (P2 integration, plan §"The adapter contract").
+ *
+ * Per-harness barrel gathering the OpenHands integration surfaces:
+ *   - agent command builder → ./agent-builder.ts    (openhandsBuilder)
+ *   - result extractor      → ./result-extractor.ts (openhandsResultExtractor)
+ *
+ * It also defines {@link OpenhandsHarness}, 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 { openhandsBuilder } from "./agent-builder.js";
+import { openhandsResultExtractor } from "./result-extractor.js";
+export { OPENHANDS_MODEL_ENV, OPENHANDS_PLATFORM, openhandsBuilder } from "./agent-builder.js";
+export { openhandsResultExtractor } from "./result-extractor.js";
+function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        v1Migration: false,
+        ...c,
+    };
+}
+/**
+ * OpenHands CLI.
+ *
+ * Canonical id is `'openhands'`; no alias or distinct runtime identity.
+ */
+export class OpenhandsHarness extends BaseHarness {
+    id = "openhands";
+    displayName = "OpenHands";
+    aliases = [];
+    agentBuilder = openhandsBuilder;
+    resultExtractor = openhandsResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // akm spawns `openhands --headless` locally per unit ⇒ local-runner.
+    pattern = "local-runner";
+    // `--json` emits a documented JSONL event stream akm parses, then validates
+    // against the node schema ⇒ native-json tier.
+    structuredOutput = "native-json";
+    // No `resume`: per the matrix OpenHands resumes from workspace state, not a
+    // session-id flag. The extractor still captures a conversation id
+    // opportunistically; akm's `workflow_run_units` remains the durable source
+    // of truth.
+    // No `identityEnv`: the matrix lists OpenHands' identity markers as
+    // uncertain, and it stamps no session var onto child processes.
+    capabilities = caps({
+        agentDispatch: true,
+        detection: true,
+    });
+}

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

@@ -0,0 +1,103 @@
+// 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 harness-native session id, in precedence order. */
+const SESSION_KEYS = ["session_id", "sessionId", "sid", "conversation_id"];
+/** Return a non-empty string, else undefined. */
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Extract the agent's answer text from one parsed OpenHands event, if the
+ * event is one of the two message-bearing kinds (see module doc). Everything
+ * else — user echoes, observations, tool actions — yields undefined.
+ */
+function extractAgentText(event) {
+    // Only agent-authored events count; a missing `source` is tolerated for
+    // finish/message actions from older serializations, but an explicit
+    // non-agent source (user echo, environment) never contributes.
+    if (event.source !== undefined && event.source !== "agent")
+        return undefined;
+    if (typeof event.action !== "string")
+        return undefined;
+    const args = isRecord(event.args) ? event.args : undefined;
+    if (event.action === "message") {
+        return nonEmptyString(args?.content) ?? nonEmptyString(event.message);
+    }
+    if (event.action === "finish") {
+        return nonEmptyString(args?.final_thought) ?? nonEmptyString(args?.thought) ?? nonEmptyString(event.message);
+    }
+    return undefined;
+}
+/** Extract a harness-native session id from one parsed JSON value, if any. */
+function extractSessionId(event) {
+    for (const key of SESSION_KEYS) {
+        const candidate = nonEmptyString(event[key]);
+        if (candidate)
+            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 openhands run result into `{ text, sessionId? }`.
+ * See the module doc for the stdout shapes handled.
+ */
+export const openhandsResultExtractor = (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"). A multi-event JSONL
+    // stream never parses as a single document, so this cannot shadow shape 2.
+    const whole = result.parsed !== undefined ? result.parsed : raw.length > 0 ? tryParseJson(raw) : undefined;
+    if (whole !== undefined) {
+        if (typeof whole === "string") {
+            return { text: whole, ...(fallbackSessionId ? { sessionId: fallbackSessionId } : {}) };
+        }
+        if (isRecord(whole)) {
+            const sessionId = extractSessionId(whole) ?? fallbackSessionId;
+            // Unknown envelope (no agent message): fall back to raw stdout so
+            // downstream embedded-JSON parsing still has material to work with.
+            const text = extractAgentText(whole) ?? raw;
+            return { text, ...(sessionId ? { sessionId } : {}) };
+        }
+    }
+    // Shape 2 — JSONL event stream (`--json`): last message-bearing agent event
+    // wins; first id-bearing event supplies the session id. Non-JSON banner
+    // lines 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 || !isRecord(event))
+            continue;
+        sawJsonLine = true;
+        streamSessionId ??= extractSessionId(event);
+        const text = extractAgentText(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/pi/agent-builder.js

@@ -0,0 +1,104 @@
+// 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/.
+/**
+ * Pi coding-agent CLI command builder (P2, plan §"The adapter contract"
+ * step 2 / §"Capability matrix").
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * headless argv the `pi` CLI expects. Per the capability matrix the headless
+ * invocation is:
+ *
+ *   pi -p "<prompt>"
+ *
+ * with `--mode json` for structured (JSONL) output, `--model <m>` for model
+ * selection, and `-c`/`-r`/`--session <id>` for resume. Resume is
+ * registry-side (`AkmHarness.resume`, flag-shaped: {@link PI_RESUME_FLAG}) —
+ * not built here because `AgentDispatchRequest` carries no session id.
+ *
+ * Platform-specific mapping decisions (all localized here, per the adapter
+ * contract):
+ *
+ * - **prompt** — `-p` is Pi's non-interactive print mode (same convention as
+ *   Claude Code's `--print`); the prompt is the trailing positional message.
+ *   The `--` end-of-options separator precedes it, mirroring the claude/codex
+ *   builders, so a prompt whose text begins with `-`/`--` can never be parsed
+ *   as flags.
+ * - **systemPrompt** — passed via `--system-prompt` (Pi follows the Claude
+ *   Code flag conventions), guarded by `assertNotFlag`.
+ * - **schema** — the matrix places Pi 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 prompt
+ *   payload, and `--mode json` is emitted so stdout is the documented JSONL
+ *   event stream that `./result-extractor.ts` normalizes. The engine's shared
+ *   retry-until-valid loop performs the actual validation. Without a schema
+ *   the argv matches the matrix's bare headless shape (`pi -p "<p>"`) and the
+ *   extractor's plain-text path applies.
+ * - **tools** — deliberately unconsumed. Pi manages tool access through its
+ *   own config/extension system (the matrix lists MCP as "extensions only");
+ *   there is no documented per-tool allowlist flag, and inventing one would
+ *   produce a silently broken command. A restrictive policy is therefore
+ *   dropped rather than approximated — never silently widened.
+ * - **effort** — stays unconsumed (reserved; the shared request contract's
+ *   "no builder consumes it yet" note stays true).
+ *
+ * NOT registered anywhere: `builders.ts` / `harnesses/index.ts` wiring is a
+ * follow-up integration task (as are the `PI_*` identity-env markers, which
+ * are registry-side). 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 PI_PLATFORM = "pi";
+/**
+ * Flag-shaped resume support per the capability matrix (`--session <id>`).
+ * Exported for the integration task's `AkmHarness.resume` registry entry; 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 across harnesses").
+ */
+export const PI_RESUME_FLAG = "--session";
+/**
+ * Assemble the positional prompt payload: 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 = [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");
+}
+/**
+ * Pi builder.
+ * Command shape:
+ *   pi [--system-prompt "..."] [--model <m>] [--mode json] -p -- "<prompt[\n\nschema directive]>"
+ */
+export const piBuilder = {
+    platform: PI_PLATFORM,
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        const args = [...profile.args];
+        if (req.systemPrompt) {
+            args.push("--system-prompt", req.systemPrompt);
+        }
+        if (req.model) {
+            const resolved = resolveModel(req.model, PI_PLATFORM, profile.modelAliases, profile.globalModelAliases);
+            args.push("--model", resolved);
+        }
+        if (req.schema) {
+            // Structured unit: JSONL event stream on stdout — the pi result
+            // extractor's documented input (prompt+validate tier).
+            args.push("--mode", "json");
+        }
+        // -p = non-interactive print mode; prompt is the trailing positional.
+        args.push("-p");
+        args.push("--");
+        args.push(buildPromptPayload(req));
+        return { argv: [profile.bin, ...args] };
+    },
+};

package/dist/integrations/harnesses/pi/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/.
+/**
+ * Pi coding-agent CLI harness (P2 integration, plan §"The adapter contract").
+ *
+ * Per-harness barrel gathering the Pi integration surfaces:
+ *   - agent command builder → ./agent-builder.ts    (piBuilder)
+ *   - result extractor      → ./result-extractor.ts (piResultExtractor)
+ *
+ * It also defines {@link PiHarness}, 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 { PI_RESUME_FLAG, piBuilder } from "./agent-builder.js";
+import { piResultExtractor } from "./result-extractor.js";
+export { PI_PLATFORM, PI_RESUME_FLAG, piBuilder } from "./agent-builder.js";
+export { piResultExtractor } from "./result-extractor.js";
+function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        v1Migration: false,
+        ...c,
+    };
+}
+/**
+ * Pi coding-agent CLI.
+ *
+ * Canonical id is `'pi'`; no alias or distinct runtime identity.
+ */
+export class PiHarness extends BaseHarness {
+    id = "pi";
+    displayName = "Pi";
+    aliases = [];
+    agentBuilder = piBuilder;
+    resultExtractor = piResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // akm spawns the `pi` CLI locally per unit ⇒ local-runner.
+    pattern = "local-runner";
+    // `--mode json` emits a documented JSONL event stream akm parses, then
+    // validates against the node schema ⇒ native-json tier.
+    structuredOutput = "native-json";
+    // `pi --session <id>` replays a previous session (the matrix's -c/-r/
+    // --session family; the id-taking long form is the registered flag).
+    resume = { flag: PI_RESUME_FLAG, takesSessionId: true };
+    // Session-id env marker only — the matrix's bare PI_* presence vars must
+    // not stamp identity onto manual runs (see `AkmHarness.identityEnv`).
+    identityEnv = ["PI_SESSION_ID"];
+    capabilities = caps({
+        agentDispatch: true,
+        detection: true,
+    });
+}

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

@@ -0,0 +1,135 @@
+// 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 harness-native session id, in precedence order. */
+const SESSION_KEYS = ["session_id", "sessionId", "session"];
+/**
+ * Coerce a candidate value into text. Handles the shapes Pi nests assistant
+ * answers in: bare strings, arrays of content blocks, and `{content|text}`
+ * wrappers. Blocks without a `content`/`text` string (thinking, tool-use)
+ * contribute nothing. 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 text of one assistant-authored message record, if it is one. */
+function assistantMessageText(message) {
+    if (!isRecord(message) || message.role !== "assistant")
+        return undefined;
+    return textOf(message.content ?? message.text);
+}
+/**
+ * Extract assistant text from one parsed JSON event/value:
+ * `message` envelopes (`message_start`/`message_end`), `messages` transcripts
+ * (`agent_end` — last assistant entry wins), and tolerant flat
+ * `role:"assistant"` events.
+ */
+function extractAssistantText(event) {
+    const fromEnvelope = assistantMessageText(event.message);
+    if (fromEnvelope !== undefined)
+        return fromEnvelope;
+    const transcript = event.messages;
+    if (Array.isArray(transcript)) {
+        for (let i = transcript.length - 1; i >= 0; i--) {
+            const text = assistantMessageText(transcript[i]);
+            if (text !== undefined)
+                return text;
+        }
+        return undefined;
+    }
+    return assistantMessageText(event);
+}
+/** Extract a harness-native session id from one parsed JSON value, if any. */
+function extractSessionId(event) {
+    for (const key of SESSION_KEYS) {
+        const candidate = event[key];
+        if (typeof candidate === "string" && candidate.length > 0)
+            return candidate;
+    }
+    // Session-lifecycle events may carry the id under a bare `id` key.
+    if (typeof event.type === "string" && event.type.startsWith("session") && typeof event.id === "string" && event.id) {
+        return event.id;
+    }
+    return undefined;
+}
+/** JSON.parse that returns undefined instead of throwing. */
+function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Normalize a raw pi run result into `{ text, sessionId? }`.
+ * See the module doc for the stdout shapes handled.
+ */
+export const piResultExtractor = (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"). A multi-event JSONL
+    // stream never parses as a single document, so this cannot shadow shape 2.
+    const whole = result.parsed !== undefined ? result.parsed : raw.length > 0 ? tryParseJson(raw) : undefined;
+    if (whole !== undefined) {
+        if (typeof whole === "string") {
+            return { text: whole, ...(fallbackSessionId ? { sessionId: fallbackSessionId } : {}) };
+        }
+        if (isRecord(whole)) {
+            const sessionId = extractSessionId(whole) ?? fallbackSessionId;
+            // Unknown envelope (no assistant text): fall back to raw stdout so
+            // downstream embedded-JSON parsing still has material to work with.
+            const text = extractAssistantText(whole) ?? textOf(whole) ?? raw;
+            return { text, ...(sessionId ? { sessionId } : {}) };
+        }
+    }
+    // Shape 2 — JSONL event stream (`--mode json`): last assistant text-bearing
+    // event wins; first session-id-bearing event supplies the id. Non-JSON
+    // banner lines 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 || !isRecord(event))
+            continue;
+        sawJsonLine = true;
+        streamSessionId ??= extractSessionId(event);
+        const text = extractAssistantText(event);
+        if (text !== undefined && text.length > 0)
+            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/types.js

@@ -13,6 +13,14 @@
 export class BaseHarness {
     runtimeId;
     setupDetectionDir;
+    agentBuilder;
+    pattern;
+    structuredOutput;
+    resume;
+    identityEnv;
+    presenceEnv;
+    resultExtractor;
+    sessionLogProvider;
     /**
      * Lowercase prefixes that a decorated v1 profile name may start with and
      * still belong to this harness (e.g. `["opencode-sdk"]`). The canonical id