akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/workflows/ir/freeze.js

@@ -10,14 +10,16 @@ import { resolveLlmEngineUse, } from "../../integrations/agent/engine-resolution
 import { resolveLlmModel, resolveModel } from "../../integrations/agent/model-aliases.js";
 import { getBuiltinAgentProfile } from "../../integrations/agent/profiles.js";
 import { HARNESS_BY_ID } from "../../integrations/harnesses/index.js";
-import { workflowMaxConcurrency } from "../concurrency-policy.js";
+import { defaultLlmEngineConcurrency, defaultMapConcurrency, workflowMaxConcurrency } from "../concurrency-policy.js";
+import { projectExecCore } from "../program/schema.js";
+import { DEFAULT_EXEC_TIMEOUT_MS } from "../resource-limits.js";
 import { compileWorkflowPlan } from "./compile.js";
 import { decodeWorkflowPlanV3, WORKFLOW_IR_VERSION } from "./schema.js";
 /**
  * The only source-to-runtime boundary. Source compilation remains pure; engine
  * selection and every dispatch-significant setting are resolved here once.
  */
-export function compileResolveFreezeWorkflow(asset, inputConfig) {
+export function compileResolveFreezeWorkflow(asset, inputConfig, options = {}) {
     // Applied ONCE, before any resolution: every engine lookup below (selection,
     // snapshots, the gate judge) then sees one config and needs no fallback
     // awareness of its own.
@@ -26,11 +28,19 @@ export function compileResolveFreezeWorkflow(asset, inputConfig) {
     // `defaults.engine` is the lowest-precedence selector, so a document- or
     // unit-level `engine:` still wins and must not be reported as opencode's.
     let usedFallbackEngine = false;
-    const preliminary = compilePlan(asset);
+    const preliminary = (options.compile ?? compilePlan)(asset);
     const engines = {};
     const maxConcurrency = frozenConcurrency(config);
+    const mapDefaultConcurrency = frozenMapDefaultConcurrency(config);
     const documentDefaults = asset.document.defaults;
-    const freezeInvocation = (unit) => {
+    // Keyed by stepId, NOT by array position. Compile is 1:1 and order-preserving
+    // today, so `asset.document.steps[index]` happened to line up with
+    // `preliminary.steps[index]` — but nothing enforces that, and a compile pass
+    // that ever filtered or reordered steps would silently attribute one step's
+    // engine/model/timeout overrides to a different step. Every draft step
+    // already carries its `stepId`, so look the source up by it.
+    const sourceStepsById = new Map(asset.document.steps.map((step) => [step.id, step]));
+    const freezeInvocation = (unit, stepId) => {
         const layers = [...(documentDefaults ? [documentDefaults] : []), ...(unit ? [unit] : [])];
         const name = selectedEngine(config, layers);
         if (!name)
@@ -44,19 +54,51 @@ export function compileResolveFreezeWorkflow(asset, inputConfig) {
         addSnapshot(config, name, engines);
         const model = exactModel(config, name, engine, layers);
         const timeoutMs = effectiveTimeout(config, engine, layers);
-        const llm = engine.kind === "llm" ? mergedLlmOverrides(layers) : undefined;
+        // Merge llm overrides REGARDLESS of engine kind so a non-llm engine with
+        // overrides anywhere in its layer stack (unit `llm:` or document
+        // `defaults.llm`) is detected instead of silently dropped. SDK engines'
+        // legitimate LLM *fallback* (`llmEngine`) is a separate mechanism — it
+        // never contributes to `layers`, so it cannot false-positive here.
+        const llm = mergedLlmOverrides(layers);
         if (engine.kind !== "llm" && llm !== undefined) {
-            throw new ConfigError(`Workflow engine "${name}" is an agent engine and cannot receive llm overrides.`, "INVALID_CONFIG_FILE");
+            throw new ConfigError(`Workflow step "${stepId}" uses engine "${name}", which is an agent engine and cannot receive llm: ` +
+                `overrides — llm: tuning (from the step's unit or defaults.llm) applies only to engines of kind "llm". ` +
+                `Remove the llm: block or select an LLM engine for this step.`, "INVALID_CONFIG_FILE");
         }
         return { engine: name, model, timeoutMs, ...(llm ? { llm } : {}) };
     };
-    const freezeUnit = (node, unit) => ({
+    /**
+     * Resolve an exec unit's wall-clock budget at the single freeze boundary:
+     * unit `timeout:` → document `defaults.timeout` → {@link DEFAULT_EXEC_TIMEOUT_MS}.
+     * There is no engine layer to consult — an exec unit names no engine — and
+     * `null` (the author's `timeout: none`) is honored as genuinely unbounded,
+     * exactly like `effectiveTimeout`'s null.
+     */
+    const freezeExec = (exec, unit) => {
+        const layers = [...(documentDefaults ? [documentDefaults] : []), ...(unit ? [unit] : [])];
+        const declared = layeredTimeout(layers);
+        const timeoutMs = declared === undefined ? DEFAULT_EXEC_TIMEOUT_MS : declared;
+        // The shared structural projection, plus the one thing freezing adds: the
+        // RESOLVED timeout. The default allowlist stays the ABSENCE of both env
+        // keys — one encoding per state, which is what keeps the canonical hash
+        // preimage stable. `command` is non-empty by parser construction.
+        const core = projectExecCore(exec);
+        return {
+            ...core,
+            command: core.command,
+            timeoutMs,
+        };
+    };
+    const freezeUnit = (node, stepId, unit) => ({
         kind: "unit",
         id: node.id,
         instructions: node.instructions,
         templating: node.templating ?? "verbatim",
         ...(node.inputs && node.inputs.length > 0 ? { inputs: node.inputs } : {}),
-        invocation: freezeInvocation(unit),
+        // An exec unit dispatches a child process, so it freezes an exec spec and
+        // NO invocation — engine selection is skipped entirely, which is why an
+        // exec-only workflow runs on an install with no engines configured at all.
+        ...(node.exec ? { exec: freezeExec(node.exec, unit) } : { invocation: freezeInvocation(unit, stepId) }),
         ...(node.schema ? { schema: node.schema } : {}),
         ...(node.retry ? { retry: node.retry } : {}),
         onError: node.onError,
@@ -64,8 +106,8 @@ export function compileResolveFreezeWorkflow(asset, inputConfig) {
         isolation: node.isolation ?? "none",
         ...(node.source ? { source: node.source } : {}),
     });
-    const steps = preliminary.steps.map((step, index) => {
-        const sourceStep = asset.document.steps[index];
+    const steps = preliminary.steps.map((step) => {
+        const sourceStep = sourceStepsById.get(step.stepId);
         const sourceUnit = sourceStep?.map ? sourceStep.map.unit : sourceStep?.unit;
         const root = step.root
             ? step.root.kind === "map"
@@ -73,12 +115,14 @@ export function compileResolveFreezeWorkflow(asset, inputConfig) {
                     kind: "map",
                     id: step.root.id,
                     over: step.root.over,
-                    template: freezeUnit(step.root.template, sourceUnit),
-                    concurrency: step.root.concurrency ?? 1,
+                    template: freezeUnit(step.root.template, step.stepId, sourceUnit),
+                    // `?? ` — not `||` — keeps an authored `concurrency: 1` (explicit
+                    // opt-out, serial) distinguishable from an unset one (the default).
+                    concurrency: step.root.concurrency ?? mapDefaultConcurrency,
                     reducer: step.root.reducer,
                     ...(step.root.source ? { source: step.root.source } : {}),
                 }
-                : freezeUnit(step.root, sourceUnit)
+                : freezeUnit(step.root, step.stepId, sourceUnit)
             : undefined;
         const criteria = step.gate.criteria;
         const judge = criteria.length === 0 ? null : freezeGateJudge(config, engines);
@@ -161,11 +205,24 @@ function exactModel(config, name, engine, layers) {
         return resolveLlmModel(selected, name, config.modelAliases);
     return resolveModel(selected, engine.platform, engine.modelAliases, config.modelAliases);
 }
-function effectiveTimeout(config, engine, layers) {
+/**
+ * Newest-layer-first scan for a declared `timeoutMs` across authoring layers
+ * (document `defaults`, then the unit). Returns `undefined` when no layer
+ * declares one; an explicit `timeoutMs: null` ("unbounded") wins over deeper
+ * layers — hence `hasOwn`, not a value test. The ONE definition of authoring
+ * timeout precedence, shared by engine and exec freezing.
+ */
+function layeredTimeout(layers) {
     for (let index = layers.length - 1; index >= 0; index--) {
         if (Object.hasOwn(layers[index] ?? {}, "timeoutMs"))
             return layers[index]?.timeoutMs ?? null;
     }
+    return undefined;
+}
+function effectiveTimeout(config, engine, layers) {
+    const declared = layeredTimeout(layers);
+    if (declared !== undefined)
+        return declared;
     if (Object.hasOwn(engine, "timeoutMs"))
         return engine.timeoutMs ?? null;
     if (engine.kind === "llm")
@@ -199,7 +256,7 @@ function addSnapshot(config, name, target) {
             kind: "llm",
             endpoint: engine.endpoint,
             model: exactModel(config, name, engine, []),
-            concurrency: engine.concurrency ?? 1,
+            concurrency: defaultLlmEngineConcurrency(engine.endpoint, engine.concurrency),
             ...(engine.provider ? { provider: engine.provider } : {}),
             ...(resolved.credential ? { credential: resolved.credential } : {}),
             ...(engine.temperature !== undefined ? { temperature: engine.temperature } : {}),
@@ -251,3 +308,13 @@ function frozenConcurrency(config) {
     const configured = config.workflow?.maxConcurrency;
     return workflowMaxConcurrency(typeof configured === "number" && Number.isFinite(configured) ? configured : undefined);
 }
+/**
+ * Width to freeze into a `map` node that declared no `concurrency:`. Resolved
+ * HERE, at the single freeze boundary, so the number lands in `plan_json` and
+ * an in-flight run keeps the width it started with even if this default (or
+ * the config key) changes underneath it.
+ */
+function frozenMapDefaultConcurrency(config) {
+    const configured = config.workflow?.defaultMapConcurrency;
+    return defaultMapConcurrency(typeof configured === "number" ? configured : undefined);
+}

package/dist/workflows/ir/schema.js

@@ -2,22 +2,37 @@
 // 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 path from "node:path";
+import { isContainedRelativePath } from "../../core/common.js";
 import { UsageError } from "../../core/errors.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
 import { HARNESS_BY_ID } from "../../integrations/harnesses/index.js";
 import { parseReference } from "../program/expressions.js";
 import { PROGRAM_PARAM_NAME_PATTERN, PROGRAM_RETRY_REASONS, PROGRAM_STEP_ID_PATTERN } from "../program/schema.js";
-import { jsonBytes, WORKFLOW_MAX_ENGINES, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_INPUTS, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_JSON_DEPTH, WORKFLOW_MAX_MAP_EXPANSION, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_PLAN_BYTES, WORKFLOW_MAX_ROUTE_BRANCHES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_STEPS, } from "../resource-limits.js";
+import { jsonBytes, utf8Bytes, WORKFLOW_ENGINE_NAME_PATTERN, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_ENGINE_NAME_LENGTH, WORKFLOW_MAX_ENGINES, WORKFLOW_MAX_EXEC_ARG_BYTES, WORKFLOW_MAX_EXEC_ARGV, WORKFLOW_MAX_EXEC_CWD_LENGTH, WORKFLOW_MAX_EXEC_PASS_ENV, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_GATE_LOOPS, WORKFLOW_MAX_INPUTS, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_JSON_DEPTH, WORKFLOW_MAX_MAP_EXPANSION, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_PLAN_BYTES, WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_ROUTE_BRANCHES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_STEPS, WORKFLOW_MAX_TIMEOUT_MS, } from "../resource-limits.js";
 /** The only executable persisted workflow plan format. */
 export const WORKFLOW_IR_VERSION = 3;
-export const WORKFLOW_MAX_CONCURRENCY = 64;
-export const WORKFLOW_MAX_GATE_LOOPS = 100;
-export const WORKFLOW_MAX_RETRIES = 100;
+/**
+ * The {@link IrRuntimeKind} a frozen engine dispatches as — the value journaled
+ * in `workflow_run_units.runner` and read back by `status --units`.
+ *
+ * Lives here, beside the union, because the mapping is a property OF the union:
+ * spelled at each call site instead, a kind added to `FrozenEngineSnapshot`
+ * would type-check against whichever site happens to end with a default and be
+ * silently mis-journaled. Callers supply their own answer for the ABSENCE of an
+ * engine, which genuinely differs — a unit without one is an `exec` unit, while
+ * a gate without one is an llm judge.
+ */
+export function engineRuntimeKind(engine) {
+    return engine.kind === "llm" ? "llm" : engine.runnerKind;
+}
+// Shared dispatch-significant bounds now live in `../resource-limits` so the
+// parser, the published JSON Schema, and this decoder enforce identical
+// values. Re-exported here for existing importers (e.g. `commands/workflow-cli.ts`).
+export { WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_GATE_LOOPS, WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_TIMEOUT_MS };
 export const WORKFLOW_MAX_UNITS = WORKFLOW_MAX_MAP_EXPANSION;
-export const WORKFLOW_MAX_TIMEOUT_MS = 2 ** 31 - 1;
 const MAX_LIST_ITEMS = 1024;
 const MAX_STRING_LENGTH = 1_000_000;
-const ENGINE_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const ENGINE_NAME_PATTERN = WORKFLOW_ENGINE_NAME_PATTERN;
 /** Strictly decode persisted v3 data before it can drive a workflow. */
 export function decodeWorkflowPlanV3(input, hooks = {}) {
     if (!isRecord(input) || input.irVersion !== WORKFLOW_IR_VERSION)
@@ -34,7 +49,7 @@ export function decodeWorkflowPlanV3(input, hooks = {}) {
         !Number.isInteger(plan.execution.maxConcurrency) ||
         plan.execution.maxConcurrency < 1 ||
         plan.execution.maxConcurrency > WORKFLOW_MAX_CONCURRENCY) {
-        fail("execution.maxConcurrency must be an integer from 1 through 64");
+        fail(`execution.maxConcurrency must be an integer from 1 through ${WORKFLOW_MAX_CONCURRENCY}`);
     }
     assertKeys(plan.execution, ["maxConcurrency", "engines"], "execution");
     if (!isRecord(plan.execution.engines))
@@ -62,8 +77,7 @@ export function decodeWorkflowPlanV3(input, hooks = {}) {
         assertString(step.title, `step ${step.stepId} title`);
         if (!!step.root === !!step.route)
             fail(`step ${step.stepId} must contain exactly one of root or route`);
-        assertKeys(step, ["stepId", "title", "sequenceIndex", "dependsOn", "root", "route", "outputSchema", "gate"], `step ${step.stepId}`);
-        validateStringArray(step.dependsOn, `step ${step.stepId} dependsOn`, WORKFLOW_MAX_STEPS, true);
+        assertKeys(step, ["stepId", "title", "sequenceIndex", "root", "route", "outputSchema", "gate"], `step ${step.stepId}`);
         if (step.outputSchema !== undefined)
             validateSchema(step.outputSchema, `step ${step.stepId} outputSchema`);
         if (step.root)
@@ -83,13 +97,6 @@ export function decodeWorkflowPlanV3(input, hooks = {}) {
             if (targetIndex <= index)
                 fail(`route target ${target} must come after step ${step.stepId}`);
         }
-        const dependencies = new Set();
-        for (const dependency of step.dependsOn ?? []) {
-            const dependencyIndex = stepIndex.get(dependency);
-            if (dependencyIndex === undefined || dependencyIndex >= index || dependencies.has(dependency))
-                fail(`step ${step.stepId} has an invalid dependency`);
-            dependencies.add(dependency);
-        }
         validateStepExpressions(step, index, stepIndex);
     }
     for (const name of references) {
@@ -122,7 +129,7 @@ export function decodeWorkflowPlanV3(input, hooks = {}) {
 }
 function validateEngine(key, engine, references, hooks) {
     if (!ENGINE_NAME_PATTERN.test(key) ||
-        key.length > 63 ||
+        key.length > WORKFLOW_MAX_ENGINE_NAME_LENGTH ||
         !isRecord(engine) ||
         engine.name !== key ||
         (engine.kind !== "llm" && engine.kind !== "agent"))
@@ -204,7 +211,7 @@ function validateEngine(key, engine, references, hooks) {
         !(typeof engine.workspace === "string" || engine.workspace === null) ||
         !Array.isArray(engine.envPassthrough) ||
         engine.envPassthrough.length > MAX_LIST_ITEMS ||
-        !engine.envPassthrough.every((name) => typeof name === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) ||
+        !engine.envPassthrough.every((name) => typeof name === "string" && WORKFLOW_ENV_VAR_NAME_PATTERN.test(name)) ||
         new Set(engine.envPassthrough).size !== engine.envPassthrough.length ||
         typeof engine.commandBuilder !== "string" ||
         engine.commandBuilder !== engine.platform ||
@@ -255,6 +262,7 @@ function validateNode(node, stepId, references, nodeIds, hooks) {
         "templating",
         "inputs",
         "invocation",
+        "exec",
         "schema",
         "retry",
         "onError",
@@ -264,13 +272,13 @@ function validateNode(node, stepId, references, nodeIds, hooks) {
     ], `unit ${node.id}`);
     if (typeof node.instructions !== "string" ||
         !node.instructions ||
-        (node.templating !== "expressions" && node.templating !== "verbatim") ||
+        node.templating !== "verbatim" ||
         (node.onError !== "fail" && node.onError !== "continue") ||
         (node.isolation !== "none" && node.isolation !== "worktree"))
         fail(`unit ${node.id} is invalid`);
     if (node.id !== stepId && node.id !== `${stepId}.unit`)
         fail(`unit ${node.id} does not belong to step ${stepId}`);
-    if (Buffer.byteLength(node.instructions, "utf8") > WORKFLOW_MAX_INSTRUCTION_BYTES)
+    if (utf8Bytes(node.instructions) > WORKFLOW_MAX_INSTRUCTION_BYTES)
         fail(`unit ${node.id} instructions exceed the 256 KiB resource limit`);
     if (node.schema !== undefined)
         validateSchema(node.schema, `unit ${node.id} schema`);
@@ -278,8 +286,77 @@ function validateNode(node, stepId, references, nodeIds, hooks) {
     validateStringArray(node.env, `unit ${node.id} env`, MAX_LIST_ITEMS, true);
     validateStringArray(node.inputs, `unit ${node.id} inputs`, WORKFLOW_MAX_INPUTS, true);
     validateSource(node.source, `unit ${node.id} source`);
+    // Exactly one dispatch mechanism per unit. A node carrying both would let a
+    // tampered plan smuggle a shell command past the engine-compatibility checks
+    // (which key off the invocation); one carrying neither has nothing to run.
+    if ((node.invocation === undefined) === (node.exec === undefined)) {
+        fail(`unit ${node.id} must declare exactly one of invocation or exec`);
+    }
+    if (node.exec !== undefined) {
+        validateExecSpec(node.exec, `unit ${node.id} exec`);
+        return;
+    }
     validateInvocation(node.invocation, references, hooks);
 }
+/**
+ * Strictly decode a frozen {@link IrExecSpec}. This is the corruption gate for
+ * a persisted plan: the argv bounds, the relative-and-contained `cwd`, and the
+ * timeout range are all re-checked here, because `plan_json` may have been
+ * hand-edited between freeze and dispatch.
+ */
+function validateExecSpec(value, label) {
+    if (!isRecord(value))
+        fail(`${label} must be an object`);
+    assertKeys(value, ["command", "cwd", "passEnv", "inheritEnv", "timeoutMs"], label);
+    validateExecEnvScope(value, label);
+    const command = value.command;
+    if (!Array.isArray(command) ||
+        command.length === 0 ||
+        command.length > WORKFLOW_MAX_EXEC_ARGV ||
+        !command.every((arg) => typeof arg === "string" && arg.length > 0 && utf8Bytes(arg) <= WORKFLOW_MAX_EXEC_ARG_BYTES)) {
+        fail(`${label}.command must be an argv array of 1 through ${WORKFLOW_MAX_EXEC_ARGV} bounded non-empty strings`);
+    }
+    if (value.cwd !== undefined) {
+        if (typeof value.cwd !== "string" ||
+            value.cwd.length === 0 ||
+            value.cwd.length > WORKFLOW_MAX_EXEC_CWD_LENGTH ||
+            !isContainedRelativePath(value.cwd)) {
+            fail(`${label}.cwd must be a relative path contained in the unit working directory`);
+        }
+    }
+    if (!(value.timeoutMs === null ||
+        (Number.isSafeInteger(value.timeoutMs) &&
+            value.timeoutMs >= 1 &&
+            value.timeoutMs <= WORKFLOW_MAX_TIMEOUT_MS))) {
+        fail(`${label}.timeoutMs must be null or an integer from 1 through ${WORKFLOW_MAX_TIMEOUT_MS}`);
+    }
+}
+/**
+ * The child's ENVIRONMENT SCOPE half of a frozen exec spec. Split out so
+ * {@link validateExecSpec} keeps its shape (and the src-fn-size ratchet stays
+ * shrink-only).
+ *
+ * Both keys are canonical-form-only: `inheritEnv` may only be `true` and
+ * `passEnv` may only be a non-empty deduplicated name list. A persisted `false`
+ * or `[]` means exactly what absence means, and admitting a second spelling of
+ * the default would give the same unit two different input hashes.
+ */
+function validateExecEnvScope(value, label) {
+    if (value.inheritEnv !== undefined && value.inheritEnv !== true) {
+        fail(`${label}.inheritEnv must be true when present (the allowlist default is the key's ABSENCE)`);
+    }
+    if (value.passEnv === undefined)
+        return;
+    const passEnv = value.passEnv;
+    if (!Array.isArray(passEnv) ||
+        passEnv.length === 0 ||
+        passEnv.length > WORKFLOW_MAX_EXEC_PASS_ENV ||
+        !passEnv.every((name) => typeof name === "string" && WORKFLOW_ENV_VAR_NAME_PATTERN.test(name)) ||
+        new Set(passEnv).size !== passEnv.length) {
+        fail(`${label}.passEnv must be 1 through ${WORKFLOW_MAX_EXEC_PASS_ENV} distinct environment variable names ` +
+            `matching ${WORKFLOW_ENV_VAR_NAME_PATTERN.source}`);
+    }
+}
 function validateGate(gate, stepId, references, nodeIds, hooks) {
     if (!isRecord(gate) ||
         gate.kind !== "gate" ||
@@ -331,6 +408,14 @@ function validateRoute(route, stepId) {
 }
 function assertUnitEngineCompatibility(node, engines) {
     const unit = node.kind === "map" ? node.template : node;
+    // An exec unit names no engine at all, so there is no engine pairing to
+    // check. It is the ONE kind that may carry `env` + `isolation: worktree`
+    // without an engine behind it: it spawns a real child process, which is
+    // exactly the precondition those two features require. `validateNode` has
+    // already proven it carries no `invocation`, so nothing here can be bypassed
+    // by declaring both.
+    if (unit.exec !== undefined)
+        return;
     const engine = unit.invocation ? engines[unit.invocation.engine] : undefined;
     if (!engine)
         return;