akm-cli 0.9.24 → 0.9.25-alpha.2

package/dist/integrations/agent/execution.js

@@ -6,9 +6,9 @@ import { ConfigError } from "../../core/errors.js";
 import { DURATION_UNITS, parseDuration } from "../../core/time.js";
 import { EXECUTION_MAX_TIMEOUT_MS } from "../../execution/limits.js";
 import { createInlineResolvedCommand, createResolvedExecutionRequest, decodeResolvedExecutionRequest, } from "../../execution/resolved-request.js";
-import { cloneToolSelection, isPortableExecutionAgentSelector, } from "../../execution/source.js";
+import { cloneToolSelection, isPortableExecutionAgentSelector, MODEL_WORK_POLICY_ID, } from "../../execution/source.js";
 import { getHarness } from "../harnesses/index.js";
-import { DEFAULT_AGENT_TIMEOUT_MS, DEFAULT_LLM_TIMEOUT_MS } from "./config.js";
+import { DEFAULT_LLM_TIMEOUT_MS } from "./config.js";
 import { FALLBACK_ENGINE_NAME, fallbackEngineConfig, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, } from "./engine-fallback.js";
 import { configuredEngine, resolveEngine } from "./engine-resolution.js";
 import { engineModelAndInference, loadModelMap, resolveModelMapAlias } from "./model-map.js";
@@ -62,21 +62,14 @@ function engineDefaults(name, engine, config) {
     if (engine.platform !== "opencode-sdk") {
         return { kind: "agent", platform: engine.platform, modelMapKey: engine.platform, values };
     }
-    // An SDK engine runs its LLM fallback's model/inference/timeout unless it sets its own.
-    const fallbackName = engine.llmEngine ?? config.defaults?.llmEngine;
+    // An SDK engine runs its own `llmEngine`'s model/inference/timeout unless it sets its own. With no
+    // `llmEngine` it has no fallback, and opencode picks the model: `defaults.llmEngine` is not borrowed.
+    const fallbackName = engine.llmEngine;
     const fallback = fallbackName && config.engines && Object.hasOwn(config.engines, fallbackName)
         ? config.engines[fallbackName]
         : undefined;
     if (fallback?.kind !== "llm" || !fallbackName) {
-        return {
-            kind: "sdk",
-            platform: "opencode-sdk",
-            modelMapKey: "opencode-sdk",
-            values: {
-                ...values,
-                timeout: has(values, "timeout") ? values.timeout : DEFAULT_AGENT_TIMEOUT_MS,
-            },
-        };
+        return { kind: "sdk", platform: "opencode-sdk", modelMapKey: "opencode-sdk", values };
     }
     const inherited = engineModelAndInference(fallback);
     return {
@@ -114,7 +107,10 @@ function runnerDefaults(runner) {
     const platform = runner.profile.platform ?? runner.profile.name;
     const fallback = runner.kind === "sdk" ? runner.fallbackConnection : undefined;
     const model = runner.profile.model ?? fallback?.model;
-    const inference = fallback ? inferenceOf(fallback) : undefined;
+    const fallbackInference = fallback ? inferenceOf(fallback) : undefined;
+    const inference = fallbackInference !== undefined || runner.profile.inference !== undefined
+        ? { ...fallbackInference, ...runner.profile.inference }
+        : undefined;
     return {
         kind: runner.kind,
         platform,
@@ -187,8 +183,19 @@ function requestedToolNames(tools) {
         return undefined;
     return Object.keys(policy).filter((tool) => policy[tool] === true);
 }
-/** Assets may only narrow the host's `execution.allowedTools`; without a config nothing is allowed. */
-function authorizeTools(tools, config) {
+/**
+ * Assets may only narrow the host's `execution.allowedTools`; without a config
+ * nothing is allowed. The model-work policy is akm's own and always allowed:
+ * it confines an engine more tightly than leaving tools unset does.
+ */
+function authorizeTools(tools, config, modelWork) {
+    if (modelWork) {
+        return {
+            status: "allowed",
+            reason: "The model-work tool policy is akm's own.",
+            policy: { id: MODEL_WORK_POLICY_ID },
+        };
+    }
     if (!hasToolSelection(tools))
         return { status: "not-required" };
     if (!config) {
@@ -239,14 +246,16 @@ function applyRequest(base, request) {
             ...timeout,
         };
     }
-    const { model: _model, workspace: _workspace, ...profile } = base.profile;
+    const { model: _model, workspace: _workspace, inference: ownInference, ...profile } = base.profile;
     const workspace = request.runtime.workspace;
+    const inference = Object.hasOwn(request, "inference") ? request.inference : ownInference;
     const next = {
         ...base,
         profile: {
             ...profile,
             ...(model !== undefined ? { model } : {}),
             ...(typeof workspace === "string" ? { workspace } : {}),
+            ...(inference ? { inference } : {}),
         },
         ...timeout,
     };
@@ -260,14 +269,29 @@ function applyRequest(base, request) {
     }
     return next;
 }
-function mergeInference(current, next, source, provenance) {
+/**
+ * Reasoning effort has one word in a request: `reasoningEffort`, which is what
+ * engines, opencode and the LLM request body call it. `effort` is the same
+ * setting as a `models.json` alias or an asset's `effort:` frontmatter spells
+ * it, and becomes `reasoningEffort` here, in the one place every layer's
+ * inference is merged, so the nearest layer wins whichever word it used. When
+ * one inference object has both, `reasoningEffort` wins.
+ */
+function withReasoningEffort(inference) {
+    if (!Object.hasOwn(inference, "effort"))
+        return inference;
+    const { effort, ...rest } = inference;
+    return Object.hasOwn(rest, "reasoningEffort") ? rest : { ...rest, reasoningEffort: effort };
+}
+function mergeInference(current, layerInference, source, provenance) {
     provenance["/inference"] = source;
-    if (next === null) {
+    if (layerInference === null) {
         for (const key of Object.keys(provenance))
             if (key.startsWith("/inference/"))
                 delete provenance[key];
         return null;
     }
+    const next = withReasoningEffort(layerInference);
     for (const key of Object.keys(next)) {
         provenance[`/inference/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`] = source;
     }
@@ -369,13 +393,14 @@ export function resolveExecution(input) {
         return layer;
     };
     const schemaLayer = select("outputSchema", "outputSchema");
-    const toolsLayer = select("tools", "tools");
+    const modelWork = input.modelWork === true;
+    const toolsLayer = modelWork ? undefined : select("tools", "tools");
     const timeoutLayer = select("timeout", "runtime.timeoutMs");
     const workspaceLayer = select("workspace", "runtime.workspace");
     const environmentLayer = select("environment", "runtime.environment");
     const settingsLayer = select("runtime", "runtime.settings");
     const tools = toolsLayer ? cloneToolSelection(toolsLayer.values.tools ?? null, "tools") : undefined;
-    const authorization = authorizeTools(tools, input.runner ? undefined : input.config);
+    const authorization = authorizeTools(tools, input.runner ? undefined : input.config, modelWork);
     provenance.authorization = {
         layer: typeof authorization.policy?.id === "string" ? authorization.policy.id : "not-required",
         kind: "authorization",
@@ -427,8 +452,9 @@ function buildLlm(request, runner, options) {
             skip(`inference.${key}`);
     }
     const chatOptions = {};
+    // Sent unless the engine opts out; chatCompletion drops it once if the provider rejects it.
     if (request.outputSchema) {
-        if (runner.connection.supportsJsonSchema === true)
+        if (runner.connection.supportsJsonSchema !== false)
             chatOptions.responseSchema = request.outputSchema;
         else
             skip("outputSchema");

package/dist/integrations/agent/index.js

@@ -4,4 +4,4 @@
 export { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
 export { _setAgentDetectForTests, defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect.js";
 export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
-export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "./prompts.js";
+export { buildProposePrompt, buildReflectPrompt, parseAgentProposalPayload } from "./prompts.js";

package/dist/integrations/agent/profiles.js

@@ -8,7 +8,7 @@
  * coding-agent CLI. Named engines lower canonical harness metadata into this
  * intentionally small internal shape. The wrapper is in `./spawn.ts`.
  */
-import { COMMON_SPAWN_ENV_PASSTHROUGH } from "../../core/spawn-env.js";
+import { COMMON_SPAWN_ENV_PASSTHROUGH, XDG_BASE_DIR_ENV_PASSTHROUGH } from "../../core/spawn-env.js";
 // AKM_EVENT_SOURCE carries usage-event provenance (improve/task) so that akm
 // invocations a spawned agent makes are recorded as machine traffic, not user
 // demand (DRIFT-6). Without it in the passthrough whitelist, buildChildEnv drops
@@ -30,7 +30,7 @@ const BUILTINS = {
         bin: "opencode",
         args: ["run"],
         stdio: "interactive",
-        envPassthrough: [...COMMON_PASSTHROUGH, "OPENCODE_API_KEY", "OPENCODE_CONFIG"],
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENCODE_API_KEY", "OPENCODE_CONFIG", ...XDG_BASE_DIR_ENV_PASSTHROUGH],
         parseOutput: "text",
     },
     claude: {

package/dist/integrations/agent/prompts.js

@@ -4,15 +4,14 @@
 /**
  * Shared prompt builders for proposal-producing agent commands (#226).
  *
- * `akm reflect` and `akm propose` both shell out to the configured agent CLI
- * (via {@link runAgent}) and ask it for a structured proposal payload. The
- * prompts are intentionally similar and share their construction here. Agent
- * and SDK stdout keeps the JSON/file-write contracts; direct LLM reflect adds
- * native-schema and framed-markdown contracts. Keeping the prompt builders in
- * `src/integrations/agent/` rather than `src/llm/` is deliberate: these are
- * shell-out prompts targeting an agent CLI, not in-tree LLM API calls.
+ * `akm reflect` and `akm proposal new` both ask the configured engine for a
+ * structured proposal payload. The prompts are intentionally similar and share
+ * their construction here. `proposal new` asks every engine kind for the JSON
+ * object below, with {@link PROPOSAL_JSON_SCHEMA} as the request's output
+ * schema. Reflect asks every engine kind for its own contract, JSON Schema or
+ * framed markdown ({@link ReflectOutputMode}).
  *
- * The stdout output an agent must produce is a strict JSON object:
+ * The output an engine must produce for `proposal new` is a strict JSON object:
  *
  * ```json
  * {
@@ -32,6 +31,7 @@ import reflectOutputRepair from "../../assets/prompts/reflect-output-repair.md"
 import { placementTypes } from "../../core/asset/asset-placement.js";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { authoringRulesForType, DESCRIPTION_MAX_CHARS, DESCRIPTION_MIN_CHARS, requiresDescription, } from "../../core/authoring-rules.js";
+import { isRecord } from "../../core/common.js";
 import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 /**
  * Per-asset-type frontmatter / authoring hints surfaced in the prompt so
@@ -77,10 +77,9 @@ export const REFLECT_CONTENT_CAP = 12_000;
  */
 export const REFLECT_TRUNCATION_MARKER = "... [truncated — focus on the visible portion]";
 /**
- * Common envelope every prompt asks the agent to honour when NO draft file
- * path is available. The wrapper code uses `JSON.parse(stdout)` to extract
- * the payload — anything outside the JSON object will be treated as a parse
- * error.
+ * The JSON envelope `proposal new` asks the engine to honour. The wrapper code
+ * uses `JSON.parse(stdout)` to extract the payload — anything outside the JSON
+ * object will be treated as a parse error.
  */
 const RESPONSE_CONTRACT_JSON = [
     "Respond ONLY with a single JSON object. No prose before or after.",
@@ -98,48 +97,25 @@ const RESPONSE_CONTRACT_JSON = [
     "Reviewers and the triage judge read this score when adjudicating the proposal queue. Overclaiming erodes trust in your proposals; underclaiming buries good ones. Be honest.",
 ].join("\n");
 /**
- * Response contract used when a draft file path is available. Instructs the
- * agent to write the improved asset content directly to the file using its
- * native file-editing tools — no stdout JSON parsing required.
+ * The JSON Schema of {@link RESPONSE_CONTRACT_JSON}'s object, the output
+ * schema `proposal new` sends with its request: an LLM engine gets it as
+ * `response_format`, codex as `--output-schema`, every agent engine as the
+ * shared schema instruction. It is in the strict form those native channels
+ * accept (every property required, no others), so it leaves out the optional
+ * `frontmatter`, which `content` already carries. The reply is held only to
+ * what {@link validateProposalPayload} needs.
  */
-function fileWriteContract(draftFilePath) {
-    return [
-        `Write the complete improved asset content to: ${draftFilePath}`,
-        "Use your file-editing tools to create or overwrite that file.",
-        "Do NOT output JSON to stdout. Do NOT print the file contents. Just write the file.",
-        `Never include the text "${REFLECT_TRUNCATION_MARKER}" or any other content from outside the provided asset content in the file you write.`,
-        "When done, output a single line on stdout: DRAFT_WRITTEN confidence=<0.0-1.0>",
-        "`confidence` is REQUIRED and must be your honest self-rated [0, 1] score for this proposal:",
-        "  • 0.90+ — fixes a real defect or adds load-bearing missing content; reviewer would clearly accept.",
-        "  • 0.70–0.89 — clear improvement, but a reviewer might prefer different framing.",
-        "  • 0.50–0.69 — marginal / judgment call.",
-        "  • Below 0.50 — not confident; prefer not writing changes at all.",
-        "Reviewers and the triage judge read this score during adjudication. Overclaim → trust erodes; underclaim → good changes buried.",
-    ].join("\n");
-}
-/**
- * Extract a confidence score from a `DRAFT_WRITTEN confidence=<n>` line emitted
- * by an agent following {@link fileWriteContract}. Tolerates trailing prose,
- * surrounding log lines, and missing/invalid confidence (returns `undefined`
- * so callers can keep the proposal without a score).
- *
- * Matched forms (case-insensitive, anywhere in stdout):
- *   - `DRAFT_WRITTEN confidence=0.85`
- *   - `DRAFT_WRITTEN confidence=0.85 ...trailing`
- *   - `DRAFT_WRITTEN` (no confidence — returns `undefined`)
- */
-export function extractDraftConfidence(stdout) {
-    if (!stdout)
-        return undefined;
-    const match = stdout.match(/\bDRAFT_WRITTEN\b[^\S\r\n]+confidence=([0-9]*\.?[0-9]+)/i);
-    if (!match)
-        return undefined;
-    const value = Number.parseFloat(match[1] ?? "");
-    if (!Number.isFinite(value) || value < 0 || value > 1)
-        return undefined;
-    return value;
-}
-export function reflectLlmResponseContract(mode, targetScoped) {
+export const PROPOSAL_JSON_SCHEMA = {
+    type: "object",
+    required: ["ref", "content", "confidence"],
+    additionalProperties: false,
+    properties: {
+        ref: { type: "string", description: "The new asset's ref as a subdir-qualified conceptId." },
+        content: { type: "string", description: "The full file contents that will be written if accepted." },
+        confidence: { type: "number", minimum: 0, maximum: 1, description: "Self-rated confidence in [0, 1]." },
+    },
+};
+export function reflectResponseContract(mode, targetScoped) {
     if (mode === "json_schema") {
         return reflectLlmSchemaContract
             .replace("{{FIELD_RULE}}", targetScoped
@@ -155,14 +131,7 @@ export function reflectLlmResponseContract(mode, targetScoped) {
         .trim();
 }
 export function buildReflectOutputRepairPrompt(mode, targetScoped) {
-    return reflectOutputRepair.replace("{{OUTPUT_CONTRACT}}", reflectLlmResponseContract(mode, targetScoped)).trim();
-}
-function reflectResponseContract(input) {
-    if (input.draftFilePath)
-        return fileWriteContract(input.draftFilePath);
-    if (input.outputMode)
-        return reflectLlmResponseContract(input.outputMode, input.ref !== undefined);
-    return RESPONSE_CONTRACT_JSON;
+    return reflectOutputRepair.replace("{{OUTPUT_CONTRACT}}", reflectResponseContract(mode, targetScoped)).trim();
 }
 /**
  * Whether the source asset content has a non-empty `description:` key in its
@@ -372,7 +341,8 @@ export function buildReflectPrompt(input) {
         // Embed concrete counts only when the gate will actually fire (source >= 200 chars).
         const showCharBounds = sourceBodyLen >= 200;
         const minChars = Math.max(Math.round(0.5 * sourceBodyLen), 150);
-        const maxChars = Math.min(Math.max(Math.round(2.5 * sourceBodyLen), 2500), 25000);
+        // A source already past the 25000 cap may not grow, and need not shrink to the cap.
+        const maxChars = Math.max(Math.min(Math.max(Math.round(2.5 * sourceBodyLen), 2500), 25000), sourceBodyLen);
         sections.push([
             "## Content preservation rules (MUST follow)",
             "1. PRESERVE ALL concrete content: code blocks, fenced snippets, CLI commands, numbered/bulleted checklists, tables, YAML/JSON examples, file paths, configuration keys, environment variable names, and CSS/HTML selectors. These are load-bearing — do NOT replace them with prose summaries.",
@@ -381,22 +351,18 @@ export function buildReflectPrompt(input) {
                 ? `3. DO NOT shrink the asset. Your body must be at least ${minChars} characters (source body is ${sourceBodyLen} chars; floor is 50%). If you genuinely need to remove a major section, explain why in a comment line at the top of the body (e.g. \`<!-- removed obsolete section X because ... -->\`).`
                 : "3. DO NOT shrink the asset dramatically. The improved body must be at least 50% of the source body length. If you genuinely need to remove a major section, explain why in a comment line at the top of the body (e.g. `<!-- removed obsolete section X because ... -->`).",
             showCharBounds
-                ? `4. DO NOT pad the asset with speculative material. Your body must be at most ${maxChars} characters (source body is ${sourceBodyLen} chars; ceiling is 250%). Do not add invented sections, hypothetical examples, or padding prose.`
+                ? `4. DO NOT pad the asset with speculative material. Your body must be at most ${maxChars} characters (source body is ${sourceBodyLen} chars; ceiling is ${maxChars === sourceBodyLen ? "100%" : "250%"}). Do not add invented sections, hypothetical examples, or padding prose.`
                 : "4. DO NOT pad the asset with speculative material. The improved body must be at most 250% of the source body length unless the feedback explicitly requests added sections.",
             "5. Improve clarity of surrounding prose, fix structural issues, add missing required frontmatter fields. Do NOT rewrite a runbook into an essay.",
         ].join("\n"));
     }
-    if (!input.draftFilePath && !input.outputMode && input.ref) {
-        // Reinforce that the `ref` field is mandatory and must exactly match the target.
-        // Small models frequently omit `ref` from the response JSON, causing parse errors.
-        sections.push(`IMPORTANT: The JSON "ref" field is REQUIRED. It MUST be exactly: "${input.ref}"`);
-    }
-    sections.push(reflectResponseContract(input));
+    sections.push(reflectResponseContract(input.outputMode ?? "json_schema", input.ref !== undefined));
     return { prompt: sections.join("\n\n") };
 }
 /**
- * Build the prompt for `akm propose <type> <name> --task ...`. Asks the
- * agent to author a brand-new asset of the given type fulfilling `task`.
+ * Build the prompt for `akm proposal new <type> <name> --task ...`. Asks the
+ * engine to author a brand-new asset of the given type fulfilling `task`, and
+ * to return it as the JSON object of {@link RESPONSE_CONTRACT_JSON}.
  */
 export function buildProposePrompt(input) {
     const sections = [];
@@ -420,44 +386,7 @@ export function buildProposePrompt(input) {
         }
     }
     sections.push("Produce a single proposal that, if accepted, would land as the asset described above.");
-    sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
-    return sections.join("\n\n");
-}
-/**
- * Build the prompt for the schema repair pass in `akm improve`. Asks the
- * agent to add the minimal required frontmatter to an asset that failed
- * validation — without rewriting the body.
- */
-export function buildSchemaRepairPrompt(input) {
-    const sections = [];
-    sections.push(`This ${input.type} asset failed schema validation with the error: "${input.reason}". ` +
-        `Your task is to fix the schema issue by adding or correcting the missing/invalid field(s) ` +
-        `while preserving all existing content.`);
-    sections.push(`Target ref: ${input.ref}`);
-    sections.push(`Schema requirements for ${input.type} assets: ${hintForType(input.type)}`);
-    if (input.standardsContext?.trim()) {
-        sections.push("Standards to follow (the rulebook for this target):");
-        sections.push(input.standardsContext.trim());
-    }
-    {
-        const authoringRules = authoringRulesForType(input.type);
-        if (authoringRules) {
-            sections.push(authoringRules);
-        }
-    }
-    const CONTENT_CAP = 3000;
-    const body = input.assetContent.trimEnd();
-    const truncated = body.length > CONTENT_CAP;
-    sections.push("Current asset content (first 3000 chars — sufficient to generate missing frontmatter):");
-    sections.push("```");
-    sections.push(truncated ? `${body.slice(0, CONTENT_CAP)}\n... [truncated]` : body);
-    sections.push("```");
-    sections.push("Produce the minimal fix: add ONLY the missing required frontmatter field(s). " +
-        "Do not rewrite the body unless it is empty. " +
-        "If `description` is missing, generate a concise one-sentence description from the content. " +
-        "If `when_to_use` is missing, generate a one-line trigger sentence. " +
-        "Preserve all existing frontmatter keys and the full body verbatim.");
-    sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
+    sections.push(RESPONSE_CONTRACT_JSON);
     return sections.join("\n\n");
 }
 /**
@@ -487,19 +416,31 @@ export function parseAgentProposalPayload(stdout) {
             throw directErr;
         parsed = embedded;
     }
+    const verdict = validateProposalPayload(parsed);
+    if (!verdict.ok)
+        throw new Error(verdict.errors.join("; "));
+    return verdict.value;
+}
+/**
+ * The proposal in a parsed reply, or why the reply is not one: `ref` and
+ * `content` must be non-empty strings. A malformed optional field is dropped,
+ * never refused.
+ */
+export function validateProposalPayload(parsed) {
+    if (!isRecord(parsed))
+        return { ok: false, errors: ["agent response is not a JSON object"] };
     if (typeof parsed.ref !== "string" || !parsed.ref.trim()) {
-        throw new Error('agent response missing required string field "ref"');
+        return { ok: false, errors: ['agent response missing required string field "ref"'] };
     }
     if (typeof parsed.content !== "string" || !parsed.content.trim()) {
-        throw new Error('agent response missing required string field "content"');
+        return { ok: false, errors: ['agent response missing required string field "content"'] };
     }
     const out = {
         ref: parsed.ref.trim(),
         content: parsed.content,
     };
-    if (parsed.frontmatter && typeof parsed.frontmatter === "object" && !Array.isArray(parsed.frontmatter)) {
+    if (isRecord(parsed.frontmatter))
         out.frontmatter = parsed.frontmatter;
-    }
     // Phase 6A: extract optional `confidence` (number in [0, 1]). Clamp gently
     // rather than reject — a model that returns 1.0 or 0 with extra precision
     // (e.g. 1.0000001) should still surface a usable score. Anything that isn't
@@ -509,5 +450,5 @@ export function parseAgentProposalPayload(stdout) {
         const clamped = Math.max(0, Math.min(1, parsed.confidence));
         out.confidence = clamped;
     }
-    return out;
+    return { ok: true, value: out };
 }

package/dist/integrations/agent/request-lowering.js

@@ -2,6 +2,9 @@
 // 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/.
 import { ConfigError } from "../../core/errors.js";
+import { withSchemaInstruction } from "../../core/structured.js";
+import { MODEL_WORK_POLICY_ID } from "../../execution/source.js";
+import { HARNESS_MODEL_WORK_IDS } from "../harnesses/ids.js";
 import { composeConversationFallbackPrompt } from "./conversation-fallback.js";
 import { composePersonaFallbackPrompt } from "./persona-fallback.js";
 /** A tool selection that actually names tools (not omitted, null, or empty). */
@@ -47,6 +50,7 @@ export function extensionFields(request) {
 export function createAgentRequestLowerer(options) {
     const supportedInference = new Set(options.inference ?? []);
     return (_profile, request) => {
+        const modelWork = request.authorization.policy?.id === MODEL_WORK_POLICY_ID;
         const notices = [];
         const skip = (field) => {
             notices.push(untranslated(options.adapter, field));
@@ -78,24 +82,33 @@ export function createAgentRequestLowerer(options) {
             }
             dispatch.agent = request.agent;
         }
+        // Every agent transport gets the schema as the one instruction; a harness
+        // with a native channel (codex --output-schema) also reads dispatch.schema.
+        if (request.outputSchema) {
+            prompt = withSchemaInstruction(prompt, request.outputSchema);
+            dispatch.schema = request.outputSchema;
+        }
         dispatch.prompt = prompt;
         if (request.model)
             dispatch.model = request.model.resolved;
         if (Object.hasOwn(request, "inference")) {
             dispatch.inference = request.inference ?? null;
             for (const key of Object.keys(request.inference ?? {}).sort()) {
-                if (!supportedInference.has(key))
+                if (!(modelWork && supportedInference.has(key)))
                     skip(`inference.${key}`);
             }
-            if (typeof request.inference?.effort === "string")
-                dispatch.effort = request.inference.effort;
         }
-        if (request.outputSchema) {
-            if (!options.outputSchema)
-                skip("outputSchema");
-            dispatch.schema = request.outputSchema;
+        if (modelWork) {
+            if (!HARNESS_MODEL_WORK_IDS.has(options.adapter)) {
+                throw new ConfigError(`The ${options.adapter} transport cannot enforce the model-work tool policy.`, "INVALID_CONFIG_FILE");
+            }
+            // The builder selects its own confined agent or flags; another agent would replace them.
+            if (dispatch.agent) {
+                throw new ConfigError(`The ${options.adapter} transport cannot run native agent ${JSON.stringify(dispatch.agent)} under the model-work tool policy.`, "INVALID_CONFIG_FILE");
+            }
+            dispatch.modelWork = true;
         }
-        if (request.tools !== undefined) {
+        else if (request.tools !== undefined) {
             // An explicit empty selection still reaches the builder (e.g. an empty allowlist).
             if (hasToolSelection(request.tools) && !translatesTools(options.tools, request.tools)) {
                 throw new ConfigError(`The ${options.adapter} transport cannot enforce the resolved tool policy.`, "INVALID_CONFIG_FILE");

package/dist/integrations/agent/runner-dispatch.js

@@ -8,11 +8,18 @@
  * credential and passthrough value that could reach the child is redacted
  * from the result.
  */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { assertNever } from "../../core/assert.js";
 import { UsageError } from "../../core/errors.js";
 import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose, redactSensitiveText, redactSensitiveValue, } from "../../core/redaction.js";
+import { MODEL_WORK_POLICY_ID } from "../../execution/source.js";
 import { chatCompletion, LlmCallError } from "../../llm/client.js";
+import { emitLlmUsage } from "../../llm/usage-telemetry.js";
+import { getHarness } from "../harnesses/index.js";
 import { closeServer as disposeOpencodeSdkServers, runOpencodeSdk } from "../harnesses/opencode-sdk/sdk-runner.js";
+import { modelFromArgs } from "./builder-shared.js";
 import { lookupApiKeyFileValue, lookupApiKeySecretRefValue, lookupCredentialFromEnv, resolveEngine, } from "./engine-resolution.js";
 import { materializeLlmRunnerConnection, materializeSdkFallbackConnection } from "./runner.js";
 import { runAgent } from "./spawn.js";
@@ -74,6 +81,42 @@ function llmFailureReason(error) {
             return "spawn_failed";
     }
 }
+const USAGE_ERROR_CODES = {
+    timeout: "timeout",
+    aborted: "aborted",
+    parse_error: "parse_error",
+    llm_rate_limit: "rate_limited",
+};
+/**
+ * The model an agent or SDK dispatch ran: the request's, else the one an agent
+ * CLI's own `args` select, which its command carries when the request names
+ * none. An SDK server never sees `args`, so an SDK engine with no model named
+ * has none to report: opencode picks it.
+ */
+function dispatchedModel({ request, runner }) {
+    return request.model?.resolved ?? (runner.kind === "agent" ? modelFromArgs(runner.profile.args) : undefined);
+}
+/**
+ * One usage record for an agent or SDK dispatch, through the same sink and
+ * ambient `withLlmStage` attribution as the LLM transport's per-HTTP-attempt
+ * records: the model it ran, and tokens when the runner reported them.
+ */
+function recordDispatchUsage(execution, result) {
+    const { inputTokens, outputTokens, reasoningTokens } = result.usage ?? {};
+    const reported = [inputTokens, outputTokens, reasoningTokens].filter((count) => count !== undefined);
+    const model = dispatchedModel(execution);
+    emitLlmUsage({
+        outcome: result.ok ? "success" : "error",
+        modelSource: "configured",
+        ...(model ? { model } : {}),
+        durationMs: result.durationMs,
+        ...(inputTokens !== undefined ? { promptTokens: inputTokens } : {}),
+        ...(outputTokens !== undefined ? { completionTokens: outputTokens } : {}),
+        ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
+        ...(reported.length > 0 ? { totalTokens: reported.reduce((sum, count) => sum + count, 0) } : {}),
+        ...(result.ok ? {} : { errorCode: (result.reason && USAGE_ERROR_CODES[result.reason]) ?? "unknown_error" }),
+    });
+}
 async function dispatchRunner(runner, prompt, opts, seams, llm) {
     const envSource = opts.envSource ?? process.env;
     const secrets = collectDispatchSensitiveValues(runner, opts, envSource);
@@ -103,9 +146,53 @@ async function dispatchRunner(runner, prompt, opts, seams, llm) {
     }
     return redactResult(result, collectSensitiveValues(secrets));
 }
-/** Run a built execution. Credentials are read here, once per call, and never returned. */
+/**
+ * The scratch working directory for one model-work dispatch on an agent or SDK
+ * engine, so the edit the model-work tool policy grants never reaches the
+ * stash.
+ */
+function createModelWorkDirectory() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), "akm-model-work-"));
+}
+/**
+ * Run a built execution. Credentials are read here, once per call, and never
+ * returned. Model work on an agent or SDK engine runs in a scratch working
+ * directory that akm creates for the dispatch and removes after it, and must
+ * end with an answer: an agent that stops with none (opencode at its step
+ * limit, for one) has failed with `parse_error`.
+ */
 export async function runExecution(execution, options = {}) {
-    const opts = { ...execution.options };
+    const scratch = execution.runner.kind !== "llm" && execution.request.authorization.policy?.id === MODEL_WORK_POLICY_ID
+        ? createModelWorkDirectory()
+        : undefined;
+    try {
+        return await runBuiltExecution(execution, options, scratch);
+    }
+    finally {
+        if (scratch)
+            fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/** A successful reply's text, unwrapped from its harness's framing (claude's `--output-format json` result envelope, for one). */
+export function unwrapHarnessReply(runner, result) {
+    const extractor = runner.kind === "agent" ? getHarness(runner.profile.platform ?? runner.profile.name)?.resultExtractor : undefined;
+    return extractor ? extractor(result) : { text: result.stdout };
+}
+/** A model-work reply's answer: its harness's framing stripped, and no answer is a `parse_error`. */
+function modelWorkAnswer(runner, result) {
+    const extracted = unwrapHarnessReply(runner, result);
+    const answer = {
+        ...result,
+        stdout: extracted.text,
+        ...(extracted.sessionId ? { sessionId: extracted.sessionId } : {}),
+    };
+    if (extracted.text.trim() !== "")
+        return answer;
+    return { ...answer, ok: false, reason: "parse_error", error: `Engine "${runner.engine}" returned no answer.` };
+}
+/** `scratch` is the model-work working directory, set only for model work on an agent or SDK engine. */
+async function runBuiltExecution(execution, options, scratch) {
+    const opts = { ...execution.options, ...(scratch ? { cwd: scratch } : {}) };
     const operational = options.runOptions ?? {};
     for (const key of OPERATIONAL_OPTIONS) {
         if (operational[key] !== undefined)
@@ -140,7 +227,13 @@ export async function runExecution(execution, options = {}) {
             };
         }
     };
-    return dispatchRunner(execution.runner, execution.prompt, opts, options, llm);
+    let result = await dispatchRunner(execution.runner, execution.prompt, opts, options, llm);
+    if (scratch !== undefined && result.ok)
+        result = modelWorkAnswer(execution.runner, result);
+    // The LLM transport records each HTTP attempt itself.
+    if (execution.runner.kind !== "llm")
+        recordDispatchUsage(execution, result);
+    return result;
 }
 /** `akm agent`: launch an agent engine interactively, with no prompt of its own. */
 export async function executeInteractiveAgentInvocation(input, seams = {}) {

package/dist/integrations/agent/runner.js

@@ -67,6 +67,12 @@ export function decodeFrozenRunnerSpec(value) {
 export function runnerIsLlm(runner) {
     return runner.kind === "llm";
 }
-export function runnerSupportsFileWrite(runner) {
-    return runner.kind !== "llm";
+/**
+ * The LLM connection behind a runner, whatever its kind: an llm runner's own,
+ * an sdk runner's provider fallback, none for an agent CLI.
+ */
+export function runnerLlmConnection(runner) {
+    if (runner.kind === "llm")
+        return runner.connection;
+    return runner.kind === "sdk" ? runner.fallbackConnection : undefined;
 }