akm-cli 0.9.23 → 0.9.25-alpha.1

package/dist/workflows/exec/step-work.js

@@ -13,6 +13,7 @@ import unitPreambleTemplate from "../../assets/prompts/workflow-unit-preamble.md
 import { UsageError } from "../../core/errors.js";
 import { validateJsonSchemaSubset } from "../../core/json-schema.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { withSchemaInstruction } from "../../core/structured.js";
 import { canonicalInputJson, validateInputs } from "../../execution/input-contract.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
 import { canonicalJson } from "../ir/plan-hash.js";
@@ -248,7 +249,9 @@ function buildStepWorkUnit(ctx, unitId, item, index) {
             // `inputBindings`, when non-empty — see StepWorkUnitContext.taskInputs.
             ...(taskInputs && Object.keys(taskInputs).length > 0 ? { taskInputs } : {}),
             ...(input.gateFeedback ? { gateFeedback: input.gateFeedback } : {}),
-            ...(template.schema ? { schema: template.schema } : {}),
+            // An agent or SDK transport's request lowering appends the schema
+            // instruction itself; a direct-LLM unit carries it in its prompt.
+            ...(template.schema && ctx.runner === "llm" ? { schema: template.schema } : {}),
             instructions: template.instructions,
         });
     const inputHash = computeUnitInputHash(ctx, item);
@@ -373,10 +376,8 @@ export function buildUnitPrompt(input) {
                 ? `\nUnmet criteria:\n${gateFeedback.missing.map((m) => `- ${m}`).join("\n")}`
                 : "")
         : "";
-    const schemaDirective = schema
-        ? `\n\nRespond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${safeJson(schema)}`
-        : "";
-    return `${preamble}\n${instructions}${itemBlock}${inputsBlock}${taskInputsBlock}${gateBlock}${schemaDirective}`;
+    const prompt = `${preamble}\n${instructions}${itemBlock}${inputsBlock}${taskInputsBlock}${gateBlock}`;
+    return schema ? withSchemaInstruction(prompt, schema) : prompt;
 }
 /**
  * Content-derived unit identity (module doc): `<node_id>:<sha256>` for a

package/dist/workflows/freeze/step-values.js

@@ -33,7 +33,7 @@ export function targetConcurrency(runner, config) {
     if (runner.kind !== "sdk" || !runner.fallbackConnection)
         return undefined;
     const selected = typeof runner.engine === "string" ? config.engines?.[runner.engine] : undefined;
-    const fallbackName = selected?.kind === "agent" ? (selected.llmEngine ?? config.defaults?.llmEngine) : undefined;
+    const fallbackName = selected?.kind === "agent" ? selected.llmEngine : undefined;
     const fallback = fallbackName ? config.engines?.[fallbackName] : undefined;
     return defaultLlmEngineConcurrency(runner.fallbackConnection.endpoint, fallback?.kind === "llm" ? fallback.concurrency : undefined);
 }

package/docs/reference/cli.md

@@ -2326,7 +2326,8 @@ or inference payload was selected.
 
 **Platform-specific dispatch:** akm uses a platform builder to construct the
 CLI argv for each engine's harness platform. `platform: "opencode"` engines emit:
-`opencode run [--system-prompt "..."] [--model opencode/claude-opus-4-7] "<prompt>"`.
+`opencode run [--model opencode/claude-opus-4-7] "<prompt>"`. `opencode run` has
+no system-prompt option, so akm composes a persona into the prompt.
 `platform: "claude"` engines emit:
 `claude [--system-prompt "..."] [--model claude-opus-4-7] --print -- "<prompt>"`.
 Agent engines may set `bin`, `args`, `workspace`, `model`, and `timeoutMs` in
@@ -2446,7 +2447,7 @@ akm improve report --since 7d          # ...aggregated over every real run start
 | `--strategy <name>` | Override the active improve strategy (a built-in or entry under `improve.strategies`) |
 | `--json-to-stdout` | Also emit the full persisted JSON result on stdout for a live run. Without this flag, stdout stays empty. Dry-runs always emit their result and are never persisted. |
 | `--skip-if-locked` | If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with "already running" (exit 75, `TransientError`, code `IMPROVE_LOCK_HELD` — field follow-up to #948: two legitimate `improve` invocations colliding on this lock is ordinary, retryable contention, not a broken config file). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress. |
-| `--require-engines` | Abort (exit 78, before any indexing, lock, or log side effect) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment, OR whose endpoint fails a bounded reachability probe — the same probe `akm health`'s `default-llm-engine`/`configured-engines` checks run, once per distinct endpoint. Without this flag, improve degrades gracefully: it skips the affected processes and reports them in the result's `skippedProcesses`. Recommended alongside `--skip-if-locked` for scheduled runs, since the operator's own shell can pass config validation while a scheduler's stripped-down environment (see #953) cannot. |
+| `--require-engines` | Abort (exit 78, before any indexing, lock, or log side effect) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment, OR whose endpoint fails a bounded reachability probe — the same probe `akm health`'s `default-llm-engine`/`configured-engines` checks run, once per distinct endpoint. An agent engine's check is that its binary is on PATH, and an `opencode-sdk` engine's is both its binary and, when it sets `llmEngine`, that LLM fallback's endpoint. Without this flag, improve degrades gracefully: it skips the affected processes and reports them in the result's `skippedProcesses`. Recommended alongside `--skip-if-locked` for scheduled runs, since the operator's own shell can pass config validation while a scheduler's stripped-down environment (see #953) cannot. |
 | `--show-prompt` | Print the composed reflect prompt (#952) for one asset and exit — before any lock, index write, or engine dispatch. Requires a fully-qualified asset ref as the scope (`akm improve lessons/my-lesson --show-prompt`); rejected with a type or whole-bundle scope. The default output format is JSON, which carries the prompt as a `prompt` field (escaped into one line) alongside the resolved `engine`/`engineKind`; pass `--format text` to print the prompt itself, unwrapped and readable by eye. |
 | `--sync` / `--no-sync` | Commit (and optionally push) the git-backed primary bundle when the run finishes. Default: on for git-backed bundles (per profile config). |
 | `--push` / `--no-push` | Push after the end-of-run sync commit when writable with a remote configured. `--no-push` commits only, skipping the push. Default: per profile config (`true`). `sync.push` stays outside the autonomy gate — this is a per-run opt-out, not a default change. |
@@ -2582,7 +2583,7 @@ table: one row per improve process (`reflect`, `distill`, `consolidate`,
 `memoryInference`, `extract`, `validation`, `triage`,
 `proactiveMaintenance`), plus a `triage.judgment` row when the strategy
 configures a judgment engine. Each row carries `enabled`, the resolved
-`engine`/`model` (llm-backed processes only) and `engineKind`, this process's
+`engine`, its `model` (when the engine has an LLM connection) and `engineKind`, this process's
 own lowering `notices`, and — for reflect/distill/consolidate only —
 `eligibleRefs`, the count of this run's `effectiveRefs` the process would act
 on (`shouldSkipRef`'s allowedTypes/excludeRefPrefixes (reflect only)/
@@ -2607,7 +2608,9 @@ default probe-on behavior) to check whether a named engine actually answers.
 builds the exact prompt reflect would send for one asset — the same source
 resolution, runner selection, feedback/schema-hint/related-lesson/rejected-
 proposal gathering `akm improve`'s live reflect step uses — and prints it
-without reading a credential, so it never calls an engine. Add
+without reading a credential, so it never calls an engine. An LLM engine
+receives the reply's JSON Schema as `response_format`, and an agent engine as
+an instruction that dispatch appends to this prompt. Add
 `--format text` (the default JSON/yaml envelope escapes the prompt into one
 line, which defeats a by-eye read) to confirm by eye that recent feedback is
 framed as an unverified report to investigate (never a fact to insert
@@ -2619,7 +2622,7 @@ destination than `memory`.
 
 #### improve report
 
-`akm improve report` (#944) answers "which engine did each LLM-backed process
+`akm improve report` (#944) answers "which engine did each model-calling process
 use this run, how much did it cost, and which enabled processes made zero
 calls (and why)" without hand-written SQLite against `state.db`. It is a
 `scope` value, not a subcommand — `report` is not, and will never be, a real
@@ -2632,7 +2635,7 @@ field on the result (`result_json` in `improve_runs`, and in the
 `byProcessEngineModel` is a cross-tab of this run's own `llm_usage` events
 (#576) — one row per distinct `(process, engine, model)` triple, each with
 `calls`, `failures`, `promptTokens`, `completionTokens`, `totalTokens`,
-`reasoningTokens`, and `totalDurationMs`. `noCalls` lists every LLM-backed
+`reasoningTokens`, and `totalDurationMs`. `noCalls` lists every model-calling
 process (`reflect`, `distill`, `consolidate`, `memoryInference`,
 `extract`, `validation` — not `triage`/`proactiveMaintenance`,
 which never make an attributable LLM call themselves) the active strategy
@@ -2706,7 +2709,7 @@ akm proposal extract --type claude --location /custom/path --session-id <id>
 | `--dry-run` | Show candidates without queuing proposals. |
 | `--force` | Re-process sessions even if they were already extracted and have no new events. Default: skip already-seen sessions. |
 | `--timeout-ms <ms>` | Per-session LLM timeout in ms (default `600000`). |
-| `--engine <name>` | Named LLM engine for this invocation. Mutually exclusive with `--strategy`. |
+| `--engine <name>` | Named engine for this invocation: an LLM engine, or a `claude`, `opencode` or `opencode-sdk` agent engine. Mutually exclusive with `--strategy`. |
 | `--strategy <name>` | Improve strategy supplying extract behavior and engine. Mutually exclusive with `--engine`. |
 
 `--type` and `--auto` are mutually exclusive; one of them is required.
@@ -2721,8 +2724,10 @@ dropped — a foreground polling daemon in a one-shot CLI); the shipped
 `core/extract.yml` cron template (`akm proposal extract --auto` on a
 schedule) is the answer.
 
-Requires an LLM engine: pass `--engine`, select a `--strategy` whose
-`processes.extract.engine` is set, or configure `defaults.llmEngine`.
+Requires an engine that can run unattended model work (an LLM engine, or a
+`claude`, `opencode` or `opencode-sdk` agent): pass `--engine`, select a
+`--strategy` whose `processes.extract.engine` is set, or configure
+`defaults.llmEngine`.
 
 **Output.** `ok` means the command ran to completion — it is `true` even when
 every session was skipped (an unreachable LLM engine included); it does not
@@ -2732,7 +2737,7 @@ harvest" branch on `skipReasons`, `warnings`, or `sessionsProcessed` /
 
 | Field | Description |
 | --- | --- |
-| `engine` | Resolved LLM engine name for this run. Absent only when extract is disabled by the selected improve strategy (the run returns before an engine is resolved). |
+| `engine` | Resolved engine name for this run. Absent only when extract is disabled by the selected improve strategy (the run returns before an engine is resolved). |
 | `engineKind` | `"llm"`, `"sdk"`, or `"agent"` — the kind of runner `engine` resolved to. Same absence condition as `engine`. |
 | `skipReasons` | Per-`skipReason` count across `sessions[]` (e.g. `{ "llm_unavailable": 25 }`). Present only when `sessionsSkipped > 0`. |
 | `warnings` | Includes one aggregate line per infrastructure skip reason that fired (`llm_unavailable`, `read_failed`, `exception`, `locked_concurrent`) — e.g. `25 of 25 sessions skipped: llm_unavailable (engine "default")` — so an engine outage is visible without inspecting `sessions[]`. Session-content skips (`already_extracted`, `too_short`, `triaged_out`) are counted in `skipReasons` but never produce a warning line. |
@@ -2755,11 +2760,24 @@ akm proposal new skill code-review --path team --task "PR-style review skill"  #
 | `--path` | Relative subdirectory under the type dir to place the proposed asset in (e.g. `release`). The filename comes from `<name>`. |
 | `--task` | Inline task text |
 | `--file` | Read task text from a UTF-8 file |
-| `--engine` | Override the default execution engine |
+| `--engine` | Override the default execution engine. Any kind works: an LLM engine, an agent CLI or `opencode-sdk` |
 | `--timeout-ms` | Override the selected engine timeout for this call |
 
 Exactly one of `--task` or `--file` is required. Emits `propose_invoked`.
 
+Every engine kind returns the proposal the same way: as one JSON object on
+stdout with the asset's `ref`, its full `content` and a self-rated
+`confidence`. akm sends the object's JSON Schema with the request, as
+`response_format` to an LLM engine and as an instruction at the end of the
+prompt to an agent engine (codex also gets it as `--output-schema`). akm
+captures the reply; an agent CLI runs headless, with no live terminal session.
+A harness's own JSON envelope, such as claude's
+`--output-format json` result, is unwrapped first.
+A reply that is not a valid proposal gets one corrective retry that says what
+was wrong. If that reply is not valid either, the command exits 1 with
+`reason: "parse_error"` and an error that names the engine, for example
+`Engine "local" reply was not valid proposal JSON after 2 attempts: …`.
+
 **Prompt-task `timeoutMs`:** a version-2 prompt task may set `timeoutMs` to
 override its selected engine timeout. Set it to `null` to disable the timer, or
 to a positive integer (milliseconds) to apply a task-specific limit.
@@ -3039,9 +3057,11 @@ Drain the standing pending-proposal backlog instead of adjudicating proposals
 one at a time. One rule decides each proposal: a proposal whose quality judge
 passed on its current content is accepted (unless its target changed since it
 was minted — that one is auto-rejected as `stale-target`); an empty diff is
-rejected; everything else goes to the judgment tier when one is enabled, and
-is otherwise left for review. Default mode stages decisions (queue mode); pass
-`--promote` to actually accept.
+rejected; a proposal that reflect or distill deferred for review is left for a
+person; everything else goes to the judgment tier when one is enabled, and
+is otherwise left for review. A reflect revision that changes the body is
+deferred for review even when its judge passes it. Default mode stages
+decisions (queue mode); pass `--promote` to actually accept.
 
 ```sh
 akm proposal drain --dry-run                        # Preview without writing

package/docs/reference/configuration.md

@@ -116,9 +116,32 @@ settable via `extraParams`. A response with reasoning tokens despite
 `enableThinking: false` triggers a runtime warning and the `akm health`
 `thinking-control` advisory.
 
-An agent engine may set `bin`, `args`, `workspace`, `model`, and `timeoutMs`.
+When a call asks for JSON that matches a schema, an LLM engine sends the schema
+as `response_format` (`json_schema`, strict) unless the engine sets
+`supportsJsonSchema: false`. If the endpoint rejects it with a 4xx other than
+429, AKM retries once without `response_format` and stops sending it to that
+endpoint and model for the rest of the process. An agent engine receives the
+schema as one instruction at the end of its prompt (`Respond with ONLY a JSON
+value matching this JSON Schema (no prose, no code fences):` followed by the
+schema), plus the harness's own schema channel where it has one (codex
+`--output-schema`).
+
+An agent engine may set `bin`, `args`, `workspace`, `model`, and `timeoutMs`,
+and the inference fields its platform translates (see
+[Inference on an agent engine](#inference-on-an-agent-engine)).
 Only `platform: "opencode-sdk"` may set `llmEngine`; it names
-the LLM engine used as that SDK engine's fallback connection.
+the LLM engine used as that SDK engine's fallback connection. With no
+`llmEngine`, an SDK engine has no fallback connection and opencode resolves
+provider, model and auth from its own configuration. `defaults.llmEngine` is
+not a substitute.
+
+On an engine without `timeoutMs`, model work (an improve process, a quality or
+triage judge, or an index pass) stops after 600 seconds, whatever the engine's
+kind; other work on an agent engine runs until it finishes. An improve stage's
+reply that does not match the stage's JSON Schema gets one corrective retry
+before the stage reads it. Reflect holds its reply to its own contract the same
+way on every engine kind: a reply that is not the JSON object of reflect's
+schema gets one repair turn, and one still invalid fails with `parse_error`.
 
 Executable assets may request tools, but the request is not authority. Configure
 the host-local `execution.allowedTools` list to define the ceiling; `"*"` is an
@@ -132,6 +155,126 @@ client with no dependencies — it spawns `opencode serve` and talks to it — s
 the npm dependency alone does not make the platform usable. Install the binary
 with `npm i -g opencode-ai` or opencode's own installer.
 
+### Inference on an agent engine
+
+A request's inference (`temperature`, `maxTokens`, `contextLength`,
+`enableThinking`, `reasoningEffort`) reaches an agent engine's harness from
+every place it can come from: the engine's own settings, an improve process's
+`llm` overlay, a task, command or agent asset's `inference`, a workflow's
+`llm:`, and a `models.json` alias. The nearest layer wins, field by field, as
+for an LLM engine. With no setting anywhere akm sends nothing of its own, so
+the model's own default applies: a `reasoningEffort: "none"` that your opencode
+config sets on a model stays in force until a layer overrides it.
+
+Each platform translates what it can carry:
+
+| Platform | Translates | How |
+|---|---|---|
+| `claude` | `reasoningEffort` | `--effort <level>`, in the harness's own levels (`low`, `medium`, `high`, `xhigh`, `max` in Claude Code 2.1.283). The value is passed as given, so one Claude Code rejects fails the dispatch. |
+| `opencode`, `opencode-sdk` | `temperature`, `reasoningEffort`, `enableThinking`, and `maxTokens` with `contextLength` | Injected opencode config, below. |
+| every other platform | nothing | |
+
+An agent engine that sets a field its platform does not translate fails to
+load, with an error that names the platform and the fields it does translate.
+Inference that reaches the engine from an asset or a caller, and that the
+platform does not translate, is reported as an `untranslated-field` notice and
+dispatch continues, because the same asset may run on any engine.
+
+On `opencode` and `opencode-sdk`, inference goes into opencode's config for the
+model the dispatch names: the request's model, or the `--model` an `opencode`
+engine's `args` name. That must be a `provider/model`, except for an
+`opencode-sdk` engine with an `llmEngine` fallback, which routes the
+fallback's model through its own provider. Without a model to attach to the
+fields are reported as untranslated, except that model work's agent (below)
+carries its options whichever model opencode picks, so an `opencode-sdk` engine
+with no `model` and no `llmEngine` still gets them. The injected entry merges
+over your own opencode config for the same provider and model, so what the
+request does not set stays as you wrote it. A dispatch with no inference injects
+nothing. akm
+checked these shapes against opencode 1.18.25 and an OpenAI-compatible provider
+(`@ai-sdk/openai-compatible`); another provider package is given the same
+options and may ignore one.
+
+- `temperature` becomes `options.temperature`, and `reasoningEffort` becomes
+  `options.reasoningEffort`. opencode reads the camelCase name: its
+  `reasoning_effort` spelling is dropped, so a model option written that way in
+  `opencode.jsonc` does nothing.
+- `enableThinking` becomes `options.chat_template_kwargs.enable_thinking` and
+  `options.enable_thinking`, the two forms an LLM engine sends.
+- `maxTokens` becomes `limit.output` and `contextLength` becomes
+  `limit.context`. Set them together. Without `limit.output` opencode asks for
+  `max_tokens: 32000`, which a small-context server rejects, and a wrong
+  `limit.context` lets opencode build requests longer than the server's window.
+  opencode refuses a `limit` with only one of them, and a half would overwrite
+  the other half of a limit you declared for the model, so akm declares `limit`
+  only when it has both and reports a lone `maxTokens` or `contextLength` as
+  untranslated.
+- For model work (below) the options go on the `akm-model-work` agent that runs
+  the dispatch, so opencode's own call on the same model, a title for the
+  session, keeps the model's defaults. Any other dispatch runs your own agent,
+  whose name akm cannot rely on, so the options go on the model and the title
+  call sees them too. `opencode-sdk` names its session, so it makes no title
+  call.
+- `opencode-sdk` declares the model of its `llmEngine` fallback with the
+  fallback's own inference, under the request's, field by field. Each distinct
+  set of inference starts its own `opencode serve`, as a different model does.
+
+Reasoning effort has one word in a request, `reasoningEffort`. `effort`, as a
+`models.json` alias or an asset's `effort:` frontmatter spells it, is the same
+setting and is read as `reasoningEffort` wherever layers are merged, so the
+nearest layer wins whichever word it used. On an LLM engine an alias's or
+asset's `effort` is therefore sent as `reasoning_effort`; before, it was
+reported as untranslated.
+
+### Engines for unattended model work
+
+Unattended model work is the work akm hands a model with no one watching:
+- the improve processes (reflect, distill, consolidate, memory inference,
+  extract, and validation's repair);
+- the quality, triage and retrieval-gate judges;
+- index passes;
+- `akm remember --enrich`.
+
+It runs on any engine kind under one tool policy. The model may read, edit
+files only inside a scratch working directory that akm creates for the
+dispatch and removes after it, and run `akm search` and `akm show`. The
+stash stays read-only to it: what model work changes reaches the stash only
+as a proposal, through the review queue.
+
+Each engine enforces as much of the policy as it can, and grants nothing it
+cannot enforce:
+
+| Engine | What the model gets |
+|---|---|
+| LLM | No tools. |
+| `claude` | Read and Edit inside the working directory, and Bash for `akm search` and `akm show` only. akm runs it with `--restricted`, so your user, project and local settings cannot widen that. |
+| `opencode`, `opencode-sdk` | Read and edit inside the working directory, through an injected `akm-model-work` agent. No bash, so no `akm search` or `akm show`, because opencode cannot stop a redirect such as `akm show x > file` from writing elsewhere. |
+| `codex`, `copilot`, `pi`, `gemini`, `aider`, `amazonq`, `openhands` | Cannot run model work: akm refuses the request before it starts. |
+
+**The one rule.** Every key model work reads its engine from must name an
+LLM engine or a `claude`, `opencode` or `opencode-sdk` agent engine. Those
+keys are:
+- `defaults.llmEngine`;
+- `index.defaults.engine` and `index.<pass>.engine`;
+- `improve.strategies.<name>.engine`;
+- `improve.strategies.<name>.processes.<process>.engine`;
+- an enabled `processes.triage.judgment.engine`;
+- `processes.<process>.qualityGate.engine`.
+
+A config that breaks the rule fails to load, with an error that names the
+key, the engine and its platform. Other engine keys, `defaults.engine` and
+`workflow.judgeEngine`, may name any configured engine.
+
+**Further details:**
+- A model-work dispatch builds its own command, so the engine's `args` do not
+  apply to it, except a `--model` they name, and neither does its `workspace`.
+- The temporary directory must not be inside a git repository, because
+  opencode would treat the whole repository as its working directory. Point
+  `TMPDIR` elsewhere if it is.
+- `llm` overrides that reach an agent engine are translated when its platform
+  translates them (see [Inference on an agent engine](#inference-on-an-agent-engine))
+  and reported as `untranslated-field` notices, not errors, when it does not.
+
 ### Model-map files
 
 AKM ships an immutable `models.json` package asset with three intent aliases:
@@ -176,7 +319,10 @@ profile may omit `model` when the installed layer already supplies it, as the
 partial Claude override above does. After overlay, every alias/engine entry
 must have a usable model. Unknown profile fields are rejected; JSON-safe
 fields inside `inference` are preserved for engine adapters to lower
-optimistically.
+optimistically. An `inference.effort` is read as `reasoningEffort`
+(see [Inference on an agent engine](#inference-on-an-agent-engine)), so the
+starter's `reasoning` alias sets `--effort high` on `claude` and
+`options.reasoningEffort: "high"` on `opencode` and `opencode-sdk`.
 
 A profile's `engine` field (0.9.15, #946) borrows a column's `model` (and, for
 an `llm`-kind engine, its inference defaults) from a configured
@@ -265,16 +411,24 @@ the embedded copy, and release tests pin copied bytes to `src/assets/models.json
 The health check passes when the optional user file is absent and warns with
 its path and JSON location when the user file is unreadable or invalid.
 
-`defaults.engine` names an LLM or agent engine. `defaults.llmEngine` must name
-an LLM engine. There is no first-engine fallback: an unset `defaults.engine`
+`defaults.engine` names an LLM or agent engine. `defaults.llmEngine` names the
+default engine for unattended model work, so it follows
+[the one rule](#engines-for-unattended-model-work). There is no first-engine
+fallback: an unset `defaults.engine`
 never resolves to some arbitrary entry in `engines`. It resolves instead to a
 synthesized, config-free `opencode-sdk` engine when the `opencode` binary is on
 PATH — announced once per run, and preempted by any `opencode-sdk` engine you
 configure yourself. Naming an engine that is not configured is always an error
 and is never rescued by that fallback.
 
+`defaults.llmEngine` is not an `opencode-sdk` engine's fallback connection. An
+SDK engine gets an LLM fallback only from its own `llmEngine`, so the
+synthesized engine, which sets none, runs on opencode's own provider, model and
+auth.
+
 Index passes select engines through `index.defaults.engine` or
-`index.<pass>.engine`. Per-pass `model`, `timeoutMs`, and `llm` fields are
+`index.<pass>.engine`, which follow
+[the one rule](#engines-for-unattended-model-work). Per-pass `model`, `timeoutMs`, and `llm` fields are
 invocation overrides; `enabled: false` disables that pass. Connection fields
 such as `endpoint`, `provider`, `apiKey`, and `apiKeyFile` belong only on
 named engines.
@@ -323,7 +477,8 @@ can select `engine`, `model`, `timeoutMs`, and LLM request overrides:
 }
 ```
 
-LLM-only improve processes require an LLM engine; an explicit invalid or
+An improve process's engine follows
+[the one rule](#engines-for-unattended-model-work); an explicit invalid or
 incompatible engine never falls back to another engine. Built-in strategies
 are complete presets. User-defined strategies inherit omitted fields from the
 built-in `default` strategy before applying their own overrides.
@@ -356,12 +511,16 @@ guidance. When enabled, engine selection is judgment → triage → strategy →
 
 `processes.reflect.qualityGate` and `processes.distill.qualityGate` control
 each process's LLM-as-judge quality gate. Each is on unless it sets
-`enabled: false`, and each follows only its own switch. The judge is the
-process's own LLM engine, or `defaults.llmEngine` when an agent generates.
-`engine`, `model`, `timeoutMs` and `llm` give the gate a judge of its own,
+`enabled: false`, and each follows only its own switch. A reflect revision
+that changes the body is never auto-accepted; when the judge passes it, it
+waits for review. With the gate off, it waits for review too. The judge is the
+process's own engine when that is an LLM engine, or the `defaults.llmEngine`
+engine when an agent generates. `engine`, `model`, `timeoutMs` and `llm` give the gate a judge of its own,
 resolved over the process's settings the way `triage.judgment` resolves over
-triage's. A gate whose settings resolve to no LLM engine fails before anything
-is generated; it never falls back to another engine. The judge runs at
+triage's. The judge may be any engine that follows
+[the one rule](#engines-for-unattended-model-work). A gate whose settings
+resolve to no engine fails before anything is generated; it never falls back
+to another engine. The judge runs at
 temperature 0 with thinking off unless its engine sets `enableThinking: true`.
 Thinking is slow: on a 27B llama.cpp server, a thinking judgment took a median
 of 30–67 s and up to about 3 minutes, against about 5 s without.

package/docs/reference/workflow-schema.md

@@ -297,13 +297,17 @@ families) plus the orchestration keys:
 - `params` — name → `{ type, description }` (JSON-Schema-typed, unlike a bare
   description string).
 - `defaults` — run-level dispatch defaults (`engine`, `model`, `llm`,
-  `timeout`, `on_error`), overridable per unit. `defaults.llm` is the
-  exception: `llm:` tuning applies only to engines of kind `llm`, and a
-  document-level `llm:` reaches EVERY step, so a document that also has a step
-  on an agent engine fails to freeze — naming the step and the engine — rather
-  than dropping the settings for that step. There is no per-step opt-out (`llm:
-  {}` is a no-op and `llm: null` is a parse error), so in a mixed document put
-  `llm:` on the `unit:` of each LLM step instead of in `defaults:`.
+  `timeout`, `on_error`), overridable per unit. `llm:` tuning reaches an engine
+  of any kind, and a document-level `llm:` reaches EVERY step. An LLM engine
+  sends it; an agent engine translates what its platform can carry
+  (`temperature`, `reasoning_effort`, `enable_thinking`, and `max_tokens` with
+  `context_length` on `opencode` and `opencode-sdk`; `reasoning_effort` on
+  `claude`; see
+  [Inference on an agent engine](configuration.md#inference-on-an-agent-engine))
+  and reports the rest as an `untranslated-field` notice on that step. There is
+  no per-step opt-out (`llm: {}` is a no-op and `llm: null` is a parse error),
+  so in a mixed document put `llm:` on the `unit:` of each step it is meant for
+  instead of in `defaults:`.
 - `outputs` — name → `{ from, schema? }`, a run-level export projected from
   a step's own artifact (Markdown-only; see [Workflow
   outputs](#workflow-outputs) below).
@@ -1179,8 +1183,8 @@ and return HTTP 500 — a hard failure, so loopback endpoints stay at 1 and a
 `engines.<name>.concurrency` yourself. Remote providers fail softly (a
 retryable 429), and four concurrent completions is well inside any hosted
 provider's entry tier. Agent engines carry no concurrency limit of their own —
-except an `opencode-sdk` engine with an `llmEngine` fallback, which inherits
-that fallback engine's limit.
+except an `opencode-sdk` engine that sets `llmEngine`, which inherits that
+fallback engine's limit.
 
 #### What counts as a loopback endpoint
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.23",
+  "version": "0.9.25-alpha.1",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [

package/schemas/akm-config.json

@@ -146,6 +146,24 @@
                 "type": "string",
                 "maxLength": 63,
                 "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+              },
+              "temperature": {
+                "type": "number"
+              },
+              "maxTokens": {
+                "type": "integer",
+                "exclusiveMinimum": 0
+              },
+              "contextLength": {
+                "type": "integer",
+                "exclusiveMinimum": 0
+              },
+              "enableThinking": {
+                "type": "boolean"
+              },
+              "reasoningEffort": {
+                "type": "string",
+                "minLength": 1
               }
             },
             "required": [
@@ -1798,6 +1816,24 @@
                     "type": "string",
                     "maxLength": 63,
                     "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+                  },
+                  "temperature": {
+                    "type": "number"
+                  },
+                  "maxTokens": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0
+                  },
+                  "contextLength": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0
+                  },
+                  "enableThinking": {
+                    "type": "boolean"
+                  },
+                  "reasoningEffort": {
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "required": [