akm-cli 0.9.24 → 0.9.25-alpha.1

package/dist/integrations/harnesses/opencode/model-work-agent.js

@@ -0,0 +1,80 @@
+// 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/.
+/**
+ * The opencode agent that runs unattended model work under the model-work
+ * tool policy (`MODEL_WORK_TOOLS`). The CLI builder injects it through
+ * `OPENCODE_CONFIG_CONTENT` and selects it with `--agent`; the SDK runner adds
+ * it to its server config and names it in the prompt body.
+ *
+ * What opencode 1.18.25 confines, checked against a local stub:
+ *   - read and edit stay inside the session directory (`external_directory`
+ *     is denied). Write is part of opencode's edit permission, so it is
+ *     confined the same way and cannot be denied on its own.
+ *   - bash is denied, so `akm search` and `akm show` are not granted: opencode
+ *     matches a bash rule against the command's words only, so
+ *     `akm show x > ~/stash/asset.md` would pass an `akm show *` rule and
+ *     write anywhere.
+ *   - every other tool is denied, `doom_loop` included (its default, `ask`,
+ *     would hang a headless server). Each permission opencode knows is named,
+ *     so a same-named agent in the user's config cannot re-allow one through
+ *     opencode's config merge, and `*` covers the rest.
+ * The same rules also go in the top-level `permission`, so an opencode that
+ * falls back to its default agent is confined too.
+ *
+ * The agent also keeps opencode's coding-assistant defaults out of model work:
+ *   - its own short `prompt` replaces the provider's coding prompt, which
+ *     tells the model to search extensively; opencode appends a request's
+ *     system text after it and never substitutes it;
+ *   - `steps` bounds the agentic loop. opencode only asks the model to stop
+ *     at the limit, so the SDK runner also aborts the session a little past
+ *     it (`MODEL_WORK_STEP_GRACE`); on the CLI the dispatch timeout bounds it;
+ *   - automatic compaction is off, so a long run cannot summarize the task
+ *     away.
+ */
+export const MODEL_WORK_OPENCODE_AGENT = "akm-model-work";
+/** The agentic iterations a model-work run may take: a judge answers in one, a generator in a few. */
+export const MODEL_WORK_STEPS = 8;
+/** Steps past {@link MODEL_WORK_STEPS} after which the SDK runner aborts the session. */
+export const MODEL_WORK_STEP_GRACE = 2;
+const MODEL_WORK_PROMPT = "You do one bounded task for akm. Use tools only to check what the task needs, never repeat a tool call, and reply with exactly what the task asks for.";
+const MODEL_WORK_PERMISSION = {
+    "*": "deny",
+    read: "allow",
+    edit: "allow",
+    external_directory: "deny",
+    bash: "deny",
+    doom_loop: "deny",
+    glob: "deny",
+    grep: "deny",
+    list: "deny",
+    lsp: "deny",
+    question: "deny",
+    skill: "deny",
+    task: "deny",
+    todowrite: "deny",
+    webfetch: "deny",
+    websearch: "deny",
+};
+/**
+ * The opencode config fragment that defines and confines the model-work agent.
+ * The agent carries the request's inference options (`model-config.ts`), which
+ * apply to its calls only: opencode's own calls on the same model, a title for
+ * the session, keep the model's defaults.
+ */
+export function modelWorkOpencodeConfig(options) {
+    return {
+        permission: { ...MODEL_WORK_PERMISSION },
+        compaction: { auto: false },
+        agent: {
+            [MODEL_WORK_OPENCODE_AGENT]: {
+                mode: "primary",
+                description: "akm unattended model work: read and edit inside its working directory only.",
+                prompt: MODEL_WORK_PROMPT,
+                steps: MODEL_WORK_STEPS,
+                ...(options ? { options } : {}),
+                permission: { ...MODEL_WORK_PERMISSION },
+            },
+        },
+    };
+}

package/dist/integrations/harnesses/opencode-sdk/harness.js

@@ -21,7 +21,9 @@
  * Importing the descriptor from this leaf keeps the registry a config-leaf and
  * breaks the cycle.
  */
+import { isModelWorkTools } from "../../../execution/source.js";
 import { createAgentRequestLowerer } from "../../agent/request-lowering.js";
+import { opencodeCarriedKeys } from "../opencode/model-config.js";
 import { caps } from "../shared.js";
 import { BaseHarness } from "../types.js";
 /**
@@ -33,12 +35,6 @@ export class OpencodeSdkHarness extends BaseHarness {
     id = "opencode-sdk";
     displayName = "OpenCode SDK";
     // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
-    // Embedded-SDK dispatch on this machine ⇒ local-runner (the matrix's
-    // "local (sdk/cli)" row, SDK half).
-    pattern = "local-runner";
-    // `session.prompt` returns structured SDK events/messages; akm extracts the
-    // final message then validates against the node schema ⇒ native-json tier.
-    structuredOutput = "native-json";
     executionLowerer = {
         platform: "opencode-sdk",
         personaChannel: "native",
@@ -47,7 +43,10 @@ export class OpencodeSdkHarness extends BaseHarness {
             personaChannel: "native",
             nativeAgentSelector: true,
             tools: "sdk",
-            outputSchema: false,
+            modelWorkTools: true,
+            // The server config gives the routed model its inference entry, so the request must name a model, except
+            // that model work's agent carries its options whichever model opencode picks.
+            inference: (_profile, request) => opencodeCarriedKeys(Boolean(request.model?.resolved), request.inference, isModelWorkTools(request.tools)),
         }),
     };
     // No flag-shaped resume: session reuse is programmatic — the SDK session id is

package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js

@@ -92,8 +92,12 @@
  */
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
+import { isRecord } from "../../../core/common.js";
 import { COMMON_SPAWN_ENV_PASSTHROUGH, spawnEnvNamesFor } from "../../../core/spawn-env.js";
+import { isModelWorkTools } from "../../../execution/source.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "../../agent/config.js";
+import { opencodeInferenceConfig, opencodeModelConfig } from "../opencode/model-config.js";
+import { MODEL_WORK_OPENCODE_AGENT, MODEL_WORK_STEP_GRACE, MODEL_WORK_STEPS, modelWorkOpencodeConfig, } from "../opencode/model-work-agent.js";
 // Server registry — one server per complete server-material signature. Caller
 // deadlines race the shared promise independently; they never become startup
 // configuration inherited by later callers.
@@ -232,21 +236,45 @@ function toolsToSdkAllowlist(tools) {
         out[n] = true;
     return out;
 }
+/** The inference a fallback LLM connection carries, which opencode can take. */
+function fallbackInference(llmConfig) {
+    const out = {};
+    for (const key of ["temperature", "maxTokens", "contextLength", "enableThinking", "reasoningEffort"]) {
+        if (llmConfig?.[key] !== undefined)
+            out[key] = llmConfig[key];
+    }
+    return out;
+}
 /**
  * Assemble the OpenCode SDK server config from the profile + LLM fallback.
  * Pure and exported for tests. `profile.model` is already exact because model
- * aliases resolve once before harness lowering.
+ * aliases resolve once before harness lowering. A server for model work also
+ * defines the confined model-work agent (`../opencode/model-work-agent`).
+ *
+ * The routed model carries the dispatch's inference (`../opencode/model-config`):
+ * the fallback LLM engine's, under `requestInference`, the request's own. A
+ * model the config routes through `akm-custom` is declared in full; any other
+ * model's entry merges over the user's own opencode config for it. For model
+ * work the options go on the confined agent instead of the model, which needs
+ * no model named: it runs whichever model opencode picks.
  */
-export function buildSdkConfig(profile, llmConfig) {
+export function buildSdkConfig(profile, llmConfig, modelWork = false, requestInference) {
     const endpoint = llmConfig?.endpoint;
     const apiKey = llmConfig?.apiKey;
     const profileModel = profile.model;
     const model = profileModel ?? llmConfig?.model;
+    const inference = requestInference === null ? undefined : { ...fallbackInference(llmConfig), ...requestInference };
+    const { entry, agentOptions } = opencodeInferenceConfig(inference, modelWork);
     const sdkConfig = {};
     if (model)
         sdkConfig.model = model;
     if (endpoint || apiKey) {
-        // Configure a custom OpenAI-compatible provider
+        // The first path segment selects the OpenCode provider. Model IDs may
+        // themselves contain slashes, but still belong to this custom endpoint.
+        const modelId = model?.startsWith("akm-custom/") ? model.slice("akm-custom/".length) : model;
+        // Configure a custom OpenAI-compatible provider. OpenCode registers only
+        // the models a custom provider lists, so the routed model is declared
+        // (#1015: without it every dispatch failed with ProviderModelNotFoundError).
         sdkConfig.provider = {
             "akm-custom": {
                 npm: "@ai-sdk/openai-compatible",
@@ -254,14 +282,18 @@ export function buildSdkConfig(profile, llmConfig) {
                     baseURL: canonicalProviderBase(endpoint) ?? undefined,
                     ...(apiKey ? { apiKey } : {}),
                 },
+                ...(modelId ? { models: { [modelId]: entry } } : {}),
             },
         };
-        // The first path segment selects the OpenCode provider. Model IDs may
-        // themselves contain slashes, but still belong to this custom endpoint.
-        if (model)
-            sdkConfig.model = model.startsWith("akm-custom/") ? model : `akm-custom/${model}`;
+        if (modelId)
+            sdkConfig.model = `akm-custom/${modelId}`;
+    }
+    else {
+        const modelConfig = opencodeModelConfig(model, entry);
+        if (modelConfig)
+            Object.assign(sdkConfig, modelConfig);
     }
-    return sdkConfig;
+    return modelWork ? { ...sdkConfig, ...modelWorkOpencodeConfig(agentOptions) } : sdkConfig;
 }
 /** Digest the executable and exact environment received by the child. */
 function serverRegistryKey(profile, env) {
@@ -550,10 +582,10 @@ async function startServer(profile, sdkConfig, env, registryKey, startupSignal)
  * start (the registry stores the in-flight promise). A failed start is
  * evicted so the next call can retry instead of caching the error forever.
  */
-function getOrStartServer(profile, llmConfig, env, envSource = process.env) {
+function getOrStartServer(profile, llmConfig, env, envSource = process.env, modelWork = false, inference) {
     if (_testServer)
         return { promise: Promise.resolve(_testServer), release() { } };
-    const sdkConfig = buildSdkConfig(profile, llmConfig);
+    const sdkConfig = buildSdkConfig(profile, llmConfig, modelWork, inference);
     const serverEnv = buildServerEnv(profile, sdkConfig, env, envSource);
     const key = serverRegistryKey(profile, serverEnv);
     let entry = _servers.get(key);
@@ -665,6 +697,25 @@ function errorText(err) {
 function appendStderr(stderr, message) {
     return stderr ? `${stderr}\n${message}` : message;
 }
+/**
+ * Map an SDK `{ error }` result or a reply's `info.error` onto a failure
+ * (#1015). Both are opencode NamedErrors, `{ name, data: { message } }`. An
+ * aborted message is `aborted`, a reply cut off at the output limit is
+ * `parse_error`, and every other error (auth, API, unknown, an HTTP error
+ * body) is `non_zero_exit`.
+ */
+function sdkErrorFailure(error) {
+    if (!isRecord(error) || typeof error.name !== "string") {
+        return { reason: "non_zero_exit", message: typeof error === "string" ? error : JSON.stringify(error) };
+    }
+    const detail = isRecord(error.data) ? error.data.message : undefined;
+    const message = typeof detail === "string" ? `${error.name}: ${detail}` : error.name;
+    if (error.name === "MessageAbortedError")
+        return { reason: "aborted", message };
+    if (error.name === "MessageOutputLengthError")
+        return { reason: "parse_error", message };
+    return { reason: "non_zero_exit", message };
+}
 async function deleteSessionBestEffort(client, sessionId, query, setTimeoutFn, clearTimeoutFn) {
     try {
         const deleted = await raceSdkOperation(client.session.delete({ path: { id: sessionId }, ...(query ? { query } : {}) }), {
@@ -681,6 +732,55 @@ async function deleteSessionBestEffort(client, sessionId, query, setTimeoutFn, c
         return `OpenCode session cleanup failed: ${errorText(err)}`;
     }
 }
+/** Stop a server-side session that the dispatch has given up on, so it stops calling the model. */
+function abortSessionBestEffort(client, sessionId, query) {
+    void client.session.abort?.({ path: { id: sessionId }, ...(query ? { query } : {}) }).catch(() => { });
+}
+/** How often a model-work session's messages are polled for its step count. */
+const MODEL_WORK_STEP_POLL_MS = 1_000;
+/**
+ * Count a model-work session's steps, its `step-start` parts, once a second
+ * and abort the session once they pass `MODEL_WORK_STEPS` +
+ * `MODEL_WORK_STEP_GRACE`: opencode 1.18.25 only asks the model to stop at the
+ * agent's `steps`. Polled rather than read from the server's event stream,
+ * because the SDK's stream cannot be closed mid-read without an unhandled
+ * AbortError (its abort handler drops the promise `reader.cancel()` returns),
+ * which the CLI turns into a crash. Best effort: the dispatch timeout still
+ * bounds the session.
+ */
+function watchModelWorkSteps(client, sessionId, query, timers) {
+    let steps = 0;
+    let timer;
+    let stopped = false;
+    const poll = async () => {
+        const listed = await client.session.messages?.({ path: { id: sessionId }, ...(query ? { query } : {}) });
+        if (stopped)
+            return;
+        steps = (listed?.data ?? [])
+            .flatMap((message) => message.parts ?? [])
+            .filter((p) => p.type === "step-start").length;
+        if (steps > MODEL_WORK_STEPS + MODEL_WORK_STEP_GRACE)
+            abortSessionBestEffort(client, sessionId, query);
+        else
+            schedule();
+    };
+    const schedule = () => {
+        if (stopped || !client.session.messages)
+            return;
+        timer = timers.setTimeoutFn(() => void poll().catch(() => schedule()), MODEL_WORK_STEP_POLL_MS);
+        if (typeof timer !== "number")
+            timer.unref?.();
+    };
+    schedule();
+    return {
+        steps: () => steps,
+        stop: () => {
+            stopped = true;
+            if (timer !== undefined)
+                timers.clearTimeoutFn(timer);
+        },
+    };
+}
 function abortedBeforeSdkStart(profile) {
     return {
         ok: false,
@@ -701,12 +801,13 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
     const clearTimeoutImpl = opts.clearTimeoutFn ?? clearTimeout;
     if (opts.signal?.aborted)
         return abortedBeforeSdkStart(profile);
+    const modelWork = isModelWorkTools(opts.dispatch?.tools);
     let client;
     if (_testServer) {
         client = _testServer.client;
     }
     else {
-        const startupHandle = getOrStartServer(profile, llmConfig, opts.env, opts.envSource);
+        const startupHandle = getOrStartServer(profile, llmConfig, opts.env, opts.envSource, modelWork, opts.dispatch?.inference);
         try {
             const startup = await raceSdkOperation(startupHandle.promise, {
                 timeoutMs: remainingTimeoutMs(),
@@ -830,10 +931,11 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
     // dispatch request. Both were previously accepted on AgentDispatchRequest but
     // silently dropped on the SDK path, so SDK-mode dispatch ignored agent-asset
     // system prompts and tool policies entirely (the CLI path honours both).
+    // Model work runs the confined agent its server config defines; its tools are that agent's.
     const dispatch = opts.dispatch;
-    const agent = dispatch?.agent;
+    const agent = modelWork ? MODEL_WORK_OPENCODE_AGENT : dispatch?.agent;
     const system = dispatch?.systemPrompt;
-    const tools = toolsToSdkAllowlist(dispatch?.tools);
+    const tools = modelWork ? undefined : toolsToSdkAllowlist(dispatch?.tools);
     const body = { parts: [{ type: "text", text: prompt }] };
     if (agent)
         body.agent = agent;
@@ -842,6 +944,9 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
     if (tools)
         body.tools = tools;
     let result;
+    const steps = modelWork
+        ? watchModelWorkSteps(client, sessionId, query, { setTimeoutFn: setTimeoutImpl, clearTimeoutFn: clearTimeoutImpl })
+        : undefined;
     try {
         const prompted = await raceSdkOperation(client.session.prompt({ path: { id: sessionId }, body, ...(query ? { query } : {}) }), {
             timeoutMs: remainingTimeoutMs(),
@@ -852,6 +957,10 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
                 void deleteSessionBestEffort(client, sessionId, query, setTimeoutImpl, clearTimeoutImpl);
             },
         });
+        // A model-work session the dispatch stops early is aborted on the server too.
+        if (modelWork && (prompted === SDK_OPERATION_ABORTED || prompted === SDK_OPERATION_TIMED_OUT)) {
+            abortSessionBestEffort(client, sessionId, query);
+        }
         if (prompted === SDK_OPERATION_ABORTED) {
             result = {
                 ok: false,
@@ -878,21 +987,53 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
         }
         else {
             const parts = prompted.data?.parts ?? [];
-            const textPart = parts.find((p) => p.type === "text");
-            const stdout = textPart?.text ?? "";
+            // The last text part is the answer; earlier ones narrate the steps before it.
+            const stdout = parts.filter((p) => p.type === "text").at(-1)?.text ?? "";
             // Token accounting from the AssistantMessage (previously discarded) —
             // the seam that makes workflow budget.maxTokens meterable on the
             // default sdk runner.
             const usage = extractUsage(prompted.data?.info);
-            result = {
-                ok: true,
-                stdout,
-                stderr: "",
-                durationMs: Date.now() - start,
-                exitCode: 0,
-                sessionId,
-                ...(usage ? { usage } : {}),
-            };
+            const sdkError = prompted.error ?? prompted.data?.info?.error;
+            const overSteps = steps !== undefined && steps.steps() > MODEL_WORK_STEPS + MODEL_WORK_STEP_GRACE;
+            if (overSteps) {
+                const message = `opencode-sdk agent "${profile.name}" ran past the ${MODEL_WORK_STEPS}-step limit for model work; akm aborted the session.`;
+                result = {
+                    ok: false,
+                    stdout,
+                    stderr: message,
+                    durationMs: Date.now() - start,
+                    exitCode: 1,
+                    reason: "parse_error",
+                    error: message,
+                    sessionId,
+                    ...(usage ? { usage } : {}),
+                };
+            }
+            else if (sdkError) {
+                const failure = sdkErrorFailure(sdkError);
+                result = {
+                    ok: false,
+                    stdout,
+                    stderr: failure.message,
+                    durationMs: Date.now() - start,
+                    exitCode: failure.reason === "aborted" ? null : 1,
+                    reason: failure.reason,
+                    error: failure.message,
+                    sessionId,
+                    ...(usage ? { usage } : {}),
+                };
+            }
+            else {
+                result = {
+                    ok: true,
+                    stdout,
+                    stderr: "",
+                    durationMs: Date.now() - start,
+                    exitCode: 0,
+                    sessionId,
+                    ...(usage ? { usage } : {}),
+                };
+            }
         }
     }
     catch (err) {
@@ -907,6 +1048,9 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
             sessionId,
         };
     }
+    finally {
+        steps?.stop();
+    }
     // Clean up session to prevent disk accumulation in ~/.local/share/opencode/.
     // Failures are non-fatal to the agent result but must not be invisible.
     const cleanupWarning = await deleteSessionBestEffort(client, sessionId, query, setTimeoutImpl, clearTimeoutImpl);

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

@@ -44,10 +44,8 @@
  * - **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
+ *   written; the JSON Schema reaches it as the instruction the shared request
+ *   lowering appends to the prompt. 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
@@ -60,16 +58,15 @@
  *   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).
+ * - **inference** — not translated: the shared lowering reports each field of
+ *   the request's inference as untranslated (`inference` in `harnesses/ids.ts`
+ *   lists none for this harness).
  *
  * Registered: `openhandsBuilder` is `OpenhandsHarness.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 `"openhands"`
- * platform name without any further wiring. The registry entry also declares
- * `pattern: "local-runner"`, `structuredOutput: "native-json"` alongside it
- * (`./index.ts`).
+ * platform name without any further wiring.
  */
 import { resolveDispatchModel } from "../../agent/builder-shared.js";
 import { createAgentRequestLowerer } from "../../agent/request-lowering.js";
@@ -82,27 +79,18 @@ export const OPENHANDS_PLATFORM = "openhands";
  * 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").
- */
+/** Assemble the `--task` payload: optional system text, then the task prompt. */
 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]>
+ *   openhands --headless --json --task=<[system\n\n]prompt>
  * with the resolved model (if any) carried on env as LLM_MODEL.
  */
 export const openhandsBuilder = {
@@ -112,7 +100,6 @@ export const openhandsBuilder = {
         adapter: OPENHANDS_PLATFORM,
         personaChannel: "prompt",
         tools: "none",
-        outputSchema: true,
     }),
     build(profile, req) {
         const args = [...profile.args];

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

@@ -29,11 +29,6 @@ export class OpenhandsHarness extends BaseHarness {
     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 flag-shaped 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

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

@@ -27,10 +27,9 @@
  * - **systemPrompt** — passed via `--system-prompt` (Pi follows the Claude
  *   Code flag conventions).
  * - **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
+ *   native `--output-schema` equivalent, unlike Codex), so the JSON Schema
+ *   reaches it as the instruction the shared request lowering appends to the
+ *   prompt, 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
@@ -40,8 +39,9 @@
  *   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).
+ * - **inference** — not translated: the shared lowering reports each field of
+ *   the request's inference as untranslated (`inference` in `harnesses/ids.ts`
+ *   lists none for this harness).
  *
  * Registered: `piBuilder` is `PiHarness.agentBuilder` (`./index.ts`), one of
  * the ten harnesses `HARNESS_REGISTRY` constructs (`harnesses/index.ts`);
@@ -54,22 +54,10 @@ import { resolveDispatchModel } from "../../agent/builder-shared.js";
 import { createAgentRequestLowerer } from "../../agent/request-lowering.js";
 /** Canonical harness/platform id used for model-alias resolution. */
 export const PI_PLATFORM = "pi";
-/**
- * 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]>"
+ *   pi [--system-prompt "..."] [--model <m>] [--mode json] -p -- "<prompt>"
  */
 export const piBuilder = {
     platform: PI_PLATFORM,
@@ -78,7 +66,6 @@ export const piBuilder = {
         adapter: PI_PLATFORM,
         personaChannel: "native",
         tools: "none",
-        outputSchema: true,
     }),
     build(profile, req) {
         const args = [...profile.args];
@@ -97,7 +84,7 @@ export const piBuilder = {
         // -p = non-interactive print mode; prompt is the trailing positional.
         args.push("-p");
         args.push("--");
-        args.push(buildPromptPayload(req));
+        args.push(req.prompt);
         return { argv: [profile.bin, ...args] };
     },
 };

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

@@ -29,11 +29,6 @@ export class PiHarness extends BaseHarness {
     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";
     // 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"];

package/dist/llm/client.js

@@ -412,6 +412,11 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
         catch {
             throw new LlmCallError(`LLM response was not valid JSON ${config.endpoint}: ${redactSensitiveText(redactErrorBody(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "parse_error", response.status);
         }
+        // A 2xx can still carry a provider failure. OpenRouter answers a provider
+        // that fails after the headers with a body holding only `error`.
+        if (json.error !== undefined && json.error !== null && !json.choices?.length) {
+            throw new LlmCallError(`LLM provider error (${response.status}) ${config.endpoint}: ${redactSensitiveText(redactErrorBody(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "provider_error", response.status);
+        }
         const responseModel = typeof json.model === "string" && json.model.trim().length > 0 ? json.model : undefined;
         terminalFields = {
             model: responseModel ?? config.model,

package/dist/llm/feature-gate.js

@@ -44,7 +44,8 @@ const DEFAULT_TIMEOUT_MS = 600_000;
 /**
  * Run `fn()` only if `isLlmFeatureEnabled(config, feature)` is `true`. On
  * disablement, throw, or timeout, return `fallback` (or — if it is a
- * thunk — the value produced by calling it).
+ * thunk — the value produced by calling it). The timeout aborts the signal
+ * `fn` receives, so the work it started stops too.
  */
 export async function tryLlmFeature(feature, config, fn, fallback, opts) {
     const resolveFallback = async () => typeof fallback === "function" ? await fallback() : fallback;
@@ -55,7 +56,7 @@ export async function tryLlmFeature(feature, config, fn, fallback, opts) {
     const timeoutMs = opts && Object.hasOwn(opts, "timeoutMs") ? (opts.timeoutMs ?? null) : DEFAULT_TIMEOUT_MS;
     try {
         if (timeoutMs === null || timeoutMs <= 0) {
-            return await fn();
+            return await fn(new AbortController().signal);
         }
         return await runWithTimeout(fn, timeoutMs, feature);
     }
@@ -97,11 +98,16 @@ export class LlmFeatureTimeoutError extends Error {
 }
 async function runWithTimeout(fn, timeoutMs, feature) {
     let timer;
+    const controller = new AbortController();
     try {
         return await new Promise((resolve, reject) => {
-            timer = setTimeout(() => reject(new LlmFeatureTimeoutError(feature, timeoutMs)), timeoutMs);
+            timer = setTimeout(() => {
+                const timedOut = new LlmFeatureTimeoutError(feature, timeoutMs);
+                controller.abort(timedOut);
+                reject(timedOut);
+            }, timeoutMs);
             Promise.resolve()
-                .then(() => fn())
+                .then(() => fn(controller.signal))
                 .then(resolve, reject);
         });
     }