akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/workflows/ir/freeze.js

@@ -5,27 +5,41 @@ import path from "node:path";
 import { deepMergeConfig } from "../../core/config/deep-merge.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { DEFAULT_AGENT_TIMEOUT_MS, DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
+import { FALLBACK_ANNOUNCEMENT, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { resolveLlmEngineUse, } from "../../integrations/agent/engine-resolution.js";
 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 { compileWorkflowPlan, compileWorkflowProgram, } from "./compile.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, config) {
-    const preliminary = asset.program ? compileProgram(asset) : compileMarkdown(asset);
+export function compileResolveFreezeWorkflow(asset, inputConfig) {
+    // 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.
+    const { config, fallbackEngineName } = withEngineFallback(inputConfig);
+    // Announce only if the fallback candidate is what a unit actually froze to:
+    // `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 engines = {};
     const maxConcurrency = frozenConcurrency(config);
-    const programDefaults = asset.program?.defaults;
+    const documentDefaults = asset.document.defaults;
     const freezeInvocation = (unit) => {
-        const layers = [...(programDefaults ? [programDefaults] : []), ...(unit ? [unit] : [])];
+        const layers = [...(documentDefaults ? [documentDefaults] : []), ...(unit ? [unit] : [])];
         const name = selectedEngine(config, layers);
         if (!name)
-            throw new ConfigError("No workflow engine is selected. Set defaults.engine or workflow defaults.engine.", "INVALID_CONFIG_FILE");
+            throw new ConfigError(
+            // Reached only when the implicit opencode-sdk fallback did not apply
+            // either, so the remedy names both routes.
+            `This workflow ${NO_ENGINE_MESSAGE_SUFFIX} Set defaults.engine or workflow defaults.engine.`, "INVALID_CONFIG_FILE", NO_ENGINE_REMEDY);
+        if (name === fallbackEngineName)
+            usedFallbackEngine = true;
         const engine = engineDefinition(config, name);
         addSnapshot(config, name, engines);
         const model = exactModel(config, name, engine, layers);
@@ -41,6 +55,7 @@ export function compileResolveFreezeWorkflow(asset, config) {
         id: node.id,
         instructions: node.instructions,
         templating: node.templating ?? "verbatim",
+        ...(node.inputs && node.inputs.length > 0 ? { inputs: node.inputs } : {}),
         invocation: freezeInvocation(unit),
         ...(node.schema ? { schema: node.schema } : {}),
         ...(node.retry ? { retry: node.retry } : {}),
@@ -50,8 +65,8 @@ export function compileResolveFreezeWorkflow(asset, config) {
         ...(node.source ? { source: node.source } : {}),
     });
     const steps = preliminary.steps.map((step, index) => {
-        const sourceStep = asset.program?.steps[index];
-        const sourceUnit = sourceStep?.unit ?? sourceStep?.map?.unit;
+        const sourceStep = asset.document.steps[index];
+        const sourceUnit = sourceStep?.map ? sourceStep.map.unit : sourceStep?.unit;
         const root = step.root
             ? step.root.kind === "map"
                 ? {
@@ -66,14 +81,13 @@ export function compileResolveFreezeWorkflow(asset, config) {
                 : freezeUnit(step.root, sourceUnit)
             : undefined;
         const criteria = step.gate.criteria;
-        const judge = criteria.length === 0 ? null : freezeGateJudge(config, engines, step.gate.required === true);
+        const judge = criteria.length === 0 ? null : freezeGateJudge(config, engines);
         const gate = {
             kind: "gate",
             id: `${step.stepId}.gate`,
             stepId: step.stepId,
             criteria,
             maxLoops: step.gate.maxLoops ?? 1,
-            required: step.gate.required === true,
             judge,
         };
         return {
@@ -95,24 +109,21 @@ export function compileResolveFreezeWorkflow(asset, config) {
         execution: { maxConcurrency, engines },
         steps,
     });
+    // `usedFallbackEngine` IS the candidate-won predicate, so use the constant
+    // directly rather than re-asking a helper to compare a name with itself.
+    const engineAnnouncement = usedFallbackEngine ? FALLBACK_ANNOUNCEMENT : undefined;
     return {
-        warnings: asset.program ? preliminary.warnings : [],
+        warnings: preliminary.warnings,
+        ...(engineAnnouncement ? { engineAnnouncement } : {}),
         plan,
     };
 }
-function compileProgram(asset) {
-    if (!asset.program)
-        throw new UsageError(`Workflow asset ${asset.ref} has no YAML program.`);
-    const compiled = compileWorkflowProgram(asset.program);
+function compilePlan(asset) {
+    const compiled = compileWorkflowPlan(asset.document, asset.title);
     if (!compiled.ok)
         throw new UsageError(compiled.errors.map((error) => `${asset.path}:${error.line}: ${error.message}`).join("\n"));
     return { ...compiled.plan, warnings: compiled.warnings };
 }
-function compileMarkdown(asset) {
-    if (!asset.document)
-        throw new UsageError(`Workflow asset ${asset.ref} has no source document.`);
-    return { ...compileWorkflowPlan(asset.document), warnings: [] };
-}
 function selectedEngine(config, layers) {
     for (let index = layers.length - 1; index >= 0; index--)
         if (layers[index]?.engine !== undefined)
@@ -223,18 +234,17 @@ function addSnapshot(config, name, target) {
     };
     target[name] = snapshot;
 }
-function freezeGateJudge(config, engines, required) {
-    const resolved = resolveLlmEngineUse(config, [], { optional: true });
-    if (!resolved) {
-        if (required)
-            throw new ConfigError("A required workflow gate needs defaults.llmEngine at start.", "LLM_NOT_CONFIGURED");
-        return null;
+function freezeGateJudge(config, engines) {
+    const name = config.workflow?.judgeEngine;
+    if (!name) {
+        throw new ConfigError("This workflow declares completion criteria but no verification engine is configured. Set workflow.judgeEngine to a named LLM or agent engine.", "INVALID_CONFIG_FILE");
     }
-    addSnapshot(config, resolved.engine, engines);
+    const engine = engineDefinition(config, name);
+    addSnapshot(config, name, engines);
     return {
-        engine: resolved.engine,
-        model: exactModel(config, resolved.engine, engineDefinition(config, resolved.engine), []),
-        timeoutMs: resolved.timeoutMs,
+        engine: name,
+        model: exactModel(config, name, engine, []),
+        timeoutMs: effectiveTimeout(config, engine, []),
     };
 }
 function frozenConcurrency(config) {

package/dist/workflows/ir/params.js

@@ -2,23 +2,147 @@
 // 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/.
 /**
- * Run-parameter validation against the frozen plan's param schemas (reviewer
- * #12). A program can declare `params.files: { type: array }`; supplying
- * `--params '{"files":"not-an-array"}'` must be rejected at start rather than
- * silently flowing into a unit prompt. The schemas are frozen into the plan
- * ({@link WorkflowPlanGraph.paramSchemas}, program path only) so validation is
- * a pure function of the frozen plan and the supplied params — no live-asset
- * re-read.
+ * Run-parameter validation against the frozen plan's param schemas. A workflow
+ * can declare `params.files: { type: array }`; supplying a non-array through
+ * the exact-name `--files` flag must be rejected at start rather than silently
+ * flowing into a unit prompt. The schemas are frozen into the plan, so
+ * validation is a pure function of the frozen plan and supplied params.
  *
  * Uses the same bounded {@link validateJsonSchemaSubset} the engine applies to
- * unit output: undeclared params are permitted (the schema map only constrains
- * the params it names), and a workflow with no declared schemas (every Markdown
- * workflow, and programs without a `params:` block) validates trivially.
+ * unit output. Internal callers may validate partial parameter objects; the CLI
+ * separately rejects flags that do not exactly name declared parameters.
  *
  * Pure module: no IO, no engine imports.
  */
 import { UsageError } from "../../core/errors.js";
 import { validateJsonSchemaSubset } from "../../core/json-schema.js";
+import { PROGRAM_PARAM_NAME_PATTERN } from "../program/schema.js";
+/**
+ * Materialize exact-name CLI parameter flags against the plan being frozen for
+ * the run. The CLI deliberately carries raw values to this boundary so type
+ * coercion cannot race or drift from the persisted plan's schemas.
+ */
+export function materializeWorkflowParameterFlags(plan, flags) {
+    if (flags.length === 0)
+        return {};
+    const declared = new Set(plan.params ?? Object.keys(plan.paramSchemas ?? {}));
+    const grouped = new Map();
+    for (const flag of flags) {
+        if (!PROGRAM_PARAM_NAME_PATTERN.test(flag.name) || !declared.has(flag.name)) {
+            const available = [...declared]
+                .sort()
+                .map((name) => `--${name}`)
+                .join(", ");
+            throw new UsageError(`Unknown workflow parameter "--${flag.name}". Parameter flags must exactly match a declared workflow parameter.`, "UNKNOWN_FLAG", available ? `Declared parameters: ${available}.` : "This workflow declares no parameters.");
+        }
+        const values = grouped.get(flag.name) ?? [];
+        values.push(flag.value);
+        grouped.set(flag.name, values);
+    }
+    const entries = [];
+    for (const [name, values] of grouped) {
+        const schema = plan.paramSchemas?.[name];
+        entries.push([name, materializeFlagValues(name, values, schema)]);
+    }
+    const params = Object.fromEntries(entries);
+    const errors = validateWorkflowParams(plan, params);
+    if (errors.length > 0) {
+        throw new UsageError(`Workflow parameter flags do not satisfy the workflow's declared schemas:\n${errors.map((error) => `  - ${error}`).join("\n")}`, "INVALID_FLAG_VALUE");
+    }
+    return params;
+}
+function materializeFlagValues(name, values, schema) {
+    const types = schemaTypes(schema);
+    if (types.includes("array")) {
+        if (values.length === 1 && typeof values[0] === "string" && values[0].trim().startsWith("[")) {
+            const parsed = parseJsonFlag(name, values[0]);
+            if (!Array.isArray(parsed))
+                throw invalidParameter(name, "must be a JSON array");
+            return parsed;
+        }
+        const itemSchema = isRecord(schema?.items) ? schema.items : undefined;
+        return values.map((value) => coerceFlagValue(name, value, itemSchema));
+    }
+    if (values.length > 1) {
+        throw invalidParameter(name, "was provided more than once but is not declared as an array");
+    }
+    return coerceFlagValue(name, values[0], schema);
+}
+function coerceFlagValue(name, raw, schema) {
+    const types = schemaTypes(schema);
+    if (types.length === 0)
+        return raw;
+    if (typeof raw === "boolean") {
+        if (types.includes("boolean"))
+            return raw;
+        if (types.includes("string"))
+            return String(raw);
+        throw invalidParameter(name, `requires a value of type ${types.join(" | ")}`);
+    }
+    // A union that permits strings keeps the user's exact text. This prevents a
+    // value such as "001" from being silently converted to a number.
+    if (types.includes("string"))
+        return raw;
+    for (const type of types) {
+        switch (type) {
+            case "boolean":
+                if (raw === "true")
+                    return true;
+                if (raw === "false")
+                    return false;
+                break;
+            case "number": {
+                const value = Number(raw);
+                if (raw.trim() !== "" && Number.isFinite(value))
+                    return value;
+                break;
+            }
+            case "integer": {
+                const value = Number(raw);
+                if (raw.trim() !== "" && Number.isSafeInteger(value))
+                    return value;
+                break;
+            }
+            case "null":
+                if (raw === "null")
+                    return null;
+                break;
+            case "object": {
+                const parsed = parseJsonFlag(name, raw);
+                if (isRecord(parsed))
+                    return parsed;
+                break;
+            }
+            case "array": {
+                const parsed = parseJsonFlag(name, raw);
+                if (Array.isArray(parsed))
+                    return parsed;
+                break;
+            }
+        }
+    }
+    throw invalidParameter(name, `must be ${types.join(" | ")}; received ${JSON.stringify(raw)}`);
+}
+function schemaTypes(schema) {
+    const declared = schema?.type;
+    if (typeof declared === "string")
+        return [declared];
+    return Array.isArray(declared) ? declared.filter((value) => typeof value === "string") : [];
+}
+function parseJsonFlag(name, raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw invalidParameter(name, "must contain valid JSON");
+    }
+}
+function invalidParameter(name, message) {
+    return new UsageError(`Workflow parameter "--${name}" ${message}.`, "INVALID_FLAG_VALUE");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /**
  * Validate a run's supplied params against the plan's frozen param schemas.
  * Returns a flat list of human-readable, path-prefixed error strings (empty =
@@ -37,7 +161,7 @@ export function validateWorkflowParams(plan, params) {
     return validateJsonSchemaSubset(params, { type: "object", properties: schemas }).map((e) => e.replace(/^\$/, "params"));
 }
 /**
- * Brief/report integrity assert (reviewer #12): the journaled `params_json`
+ * Run-integrity assert (reviewer #12): the journaled `params_json`
  * row must STILL satisfy the frozen param schemas. `startWorkflowRun` already
  * validated the params it stored, so a violation here means the row was edited
  * after the run started — loud corruption, exactly like the frozen-plan hash

package/dist/workflows/ir/plan-hash.js

@@ -4,7 +4,7 @@
 /**
  * Plan hashing for the frozen-plan contract (redesign addendum, R1).
  *
- * `workflow start` persists `plan_json` + `plan_hash` on the run row
+ * `workflow run` persists `plan_json` + `plan_hash` on the run row
  * (migration 006); every later invocation executes that snapshot. The hash is
  * the sha256 (hex) of the plan's CANONICAL JSON — object keys recursively
  * sorted — so two structurally-equal plans hash identically regardless of key

package/dist/workflows/ir/schema.js

@@ -5,9 +5,9 @@ import path from "node:path";
 import { UsageError } from "../../core/errors.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
 import { HARNESS_BY_ID } from "../../integrations/harnesses/index.js";
-import { listReferences, parseTemplate } from "../program/expressions.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_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, 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";
 /** The only executable persisted workflow plan format. */
 export const WORKFLOW_IR_VERSION = 3;
 export const WORKFLOW_MAX_CONCURRENCY = 64;
@@ -110,8 +110,12 @@ export function decodeWorkflowPlanV3(input, hooks = {}) {
             assertUnitEngineCompatibility(step.root, engines);
         if (step.gate.judge) {
             const judge = engines[step.gate.judge.engine];
-            if (!judge || judge.kind !== "llm")
-                fail(`gate ${step.gate.id} must reference an LLM engine`);
+            if (!judge)
+                fail(`gate ${step.gate.id} references an unavailable engine`);
+            if (judge.kind === "llm" && step.gate.judge.model === null)
+                fail(`LLM gate ${step.gate.id} has no exact model`);
+            if (judge.kind === "agent" && step.gate.judge.llm !== undefined)
+                fail(`agent gate ${step.gate.id} cannot carry LLM invocation settings`);
         }
     }
     return plan;
@@ -249,6 +253,7 @@ function validateNode(node, stepId, references, nodeIds, hooks) {
         "id",
         "instructions",
         "templating",
+        "inputs",
         "invocation",
         "schema",
         "retry",
@@ -271,6 +276,7 @@ function validateNode(node, stepId, references, nodeIds, hooks) {
         validateSchema(node.schema, `unit ${node.id} schema`);
     validateRetry(node.retry, node.id);
     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`);
     validateInvocation(node.invocation, references, hooks);
 }
@@ -284,17 +290,14 @@ function validateGate(gate, stepId, references, nodeIds, hooks) {
         !gate.criteria.every((x) => typeof x === "string" && x.length > 0 && x.length <= MAX_STRING_LENGTH) ||
         !Number.isInteger(gate.maxLoops) ||
         gate.maxLoops < 1 ||
-        gate.maxLoops > WORKFLOW_MAX_GATE_LOOPS ||
-        typeof gate.required !== "boolean")
+        gate.maxLoops > WORKFLOW_MAX_GATE_LOOPS)
         fail(`gate for step ${stepId} is invalid`);
     if (nodeIds.has(gate.id))
         fail(`gate id ${gate.id} collides with a node`);
-    assertKeys(gate, ["kind", "id", "stepId", "criteria", "maxLoops", "required", "judge"], `gate ${stepId}`);
+    assertKeys(gate, ["kind", "id", "stepId", "criteria", "maxLoops", "judge"], `gate ${stepId}`);
     nodeIds.add(gate.id);
     if (gate.criteria.length === 0 && gate.judge !== null)
         fail(`gate ${gate.id} without criteria cannot have a judge`);
-    if (gate.required && gate.criteria.length === 0)
-        fail(`gate ${gate.id} cannot be required without criteria`);
     if (gate.judge !== null)
         validateInvocation(gate.judge, references, hooks);
 }
@@ -461,31 +464,27 @@ function validateExtraParamsValue(value, label, hooks) {
         fail(`${label}: ${policyError}`);
 }
 function validateStepExpressions(step, index, steps) {
-    const validateReferences = (text, label, itemAllowed, wholeValue) => {
-        const parsed = parseTemplate(text);
+    const validateReference = (text, label, paramsAllowed) => {
+        const parsed = parseReference(text);
         if (!parsed.ok)
-            fail(`${label} contains an invalid expression`);
-        if (wholeValue && (parsed.segments.length !== 1 || parsed.segments[0]?.kind !== "reference"))
-            fail(`${label} must be one whole-value expression`);
-        for (const reference of listReferences(parsed.segments)) {
-            if ((reference.kind === "item" || reference.kind === "itemIndex") && !itemAllowed)
-                fail(`${label} uses item outside a map unit`);
-            if (reference.kind === "stepOutput") {
-                const referenced = steps.get(reference.stepId);
-                if (referenced === undefined || referenced >= index)
-                    fail(`${label} references a non-earlier step`);
-            }
+            fail(`${label} contains an invalid reference`);
+        if (parsed.expr.kind === "param" && !paramsAllowed)
+            fail(`${label} must reference a step output`);
+        if (parsed.expr.kind === "stepOutput") {
+            const referenced = steps.get(parsed.expr.stepId);
+            if (referenced === undefined || referenced >= index)
+                fail(`${label} references a non-earlier step`);
         }
     };
     if (step.root) {
         const unit = step.root.kind === "map" ? step.root.template : step.root;
         if (step.root.kind === "map")
-            validateReferences(step.root.over, `map ${step.root.id} over`, false, true);
-        if (unit.templating === "expressions")
-            validateReferences(unit.instructions, `unit ${unit.id} instructions`, step.root.kind === "map", false);
+            validateReference(step.root.over, `map ${step.root.id} over`, true);
+        for (const reference of unit.inputs ?? [])
+            validateReference(reference, `unit ${unit.id} inputs`, false);
     }
     if (step.route)
-        validateReferences(step.route.input, `route ${step.stepId} input`, false, true);
+        validateReference(step.route.input, `route ${step.stepId} input`, true);
 }
 function validateSource(value, label) {
     if (value === undefined)