akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/workflows/ir/freeze.js

@@ -0,0 +1,233 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+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 { 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 } 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 = compilePlan(asset);
+    const engines = {};
+    const maxConcurrency = frozenConcurrency(config);
+    const documentDefaults = asset.document.defaults;
+    const freezeInvocation = (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");
+        const engine = engineDefinition(config, name);
+        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;
+        if (engine.kind !== "llm" && llm !== undefined) {
+            throw new ConfigError(`Workflow engine "${name}" is an agent engine and cannot receive llm overrides.`, "INVALID_CONFIG_FILE");
+        }
+        return { engine: name, model, timeoutMs, ...(llm ? { llm } : {}) };
+    };
+    const freezeUnit = (node, 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),
+        ...(node.schema ? { schema: node.schema } : {}),
+        ...(node.retry ? { retry: node.retry } : {}),
+        onError: node.onError,
+        ...(node.env ? { env: node.env } : {}),
+        isolation: node.isolation ?? "none",
+        ...(node.source ? { source: node.source } : {}),
+    });
+    const steps = preliminary.steps.map((step, index) => {
+        const sourceStep = asset.document.steps[index];
+        const sourceUnit = sourceStep?.map ? sourceStep.map.unit : sourceStep?.unit;
+        const root = step.root
+            ? step.root.kind === "map"
+                ? {
+                    kind: "map",
+                    id: step.root.id,
+                    over: step.root.over,
+                    template: freezeUnit(step.root.template, sourceUnit),
+                    concurrency: step.root.concurrency ?? 1,
+                    reducer: step.root.reducer,
+                    ...(step.root.source ? { source: step.root.source } : {}),
+                }
+                : freezeUnit(step.root, sourceUnit)
+            : undefined;
+        const criteria = step.gate.criteria;
+        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,
+            judge,
+        };
+        return {
+            stepId: step.stepId,
+            title: step.title,
+            sequenceIndex: step.sequenceIndex,
+            ...(root ? { root } : {}),
+            ...(step.route ? { route: step.route } : {}),
+            ...(step.outputSchema ? { outputSchema: step.outputSchema } : {}),
+            gate,
+        };
+    });
+    const plan = decodeWorkflowPlanV3({
+        irVersion: WORKFLOW_IR_VERSION,
+        title: preliminary.title,
+        ...(preliminary.params ? { params: preliminary.params } : {}),
+        ...(preliminary.paramSchemas ? { paramSchemas: preliminary.paramSchemas } : {}),
+        ...(preliminary.budget ? { budget: preliminary.budget } : {}),
+        execution: { maxConcurrency, engines },
+        steps,
+    });
+    return {
+        warnings: preliminary.warnings,
+        plan,
+    };
+}
+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 selectedEngine(config, layers) {
+    for (let index = layers.length - 1; index >= 0; index--)
+        if (layers[index]?.engine !== undefined)
+            return layers[index]?.engine;
+    return config.defaults?.engine;
+}
+function engineDefinition(config, name) {
+    const engine = config.engines?.[name];
+    if (!engine)
+        throw new ConfigError(`Engine "${name}" is not configured.`, "INVALID_CONFIG_FILE");
+    return engine;
+}
+function exactModel(config, name, engine, layers) {
+    let selected;
+    for (const layer of layers)
+        if (layer.model !== undefined)
+            selected = layer.model;
+    selected ??= engine.model;
+    if (!selected) {
+        if (engine.kind === "llm")
+            throw new ConfigError(`LLM engine "${name}" has no model.`, "INVALID_CONFIG_FILE");
+        if (engine.platform === "opencode-sdk") {
+            const fallbackName = engine.llmEngine ?? config.defaults?.llmEngine;
+            if (fallbackName) {
+                const fallback = engineDefinition(config, fallbackName);
+                if (fallback.kind !== "llm") {
+                    throw new ConfigError(`SDK engine "${name}" fallback "${fallbackName}" is not an LLM engine.`, "INVALID_CONFIG_FILE");
+                }
+                return exactModel(config, fallbackName, fallback, []);
+            }
+        }
+        return null;
+    }
+    if (engine.kind === "llm")
+        return resolveLlmModel(selected, name, config.modelAliases);
+    return resolveModel(selected, engine.platform, engine.modelAliases, config.modelAliases);
+}
+function effectiveTimeout(config, engine, layers) {
+    for (let index = layers.length - 1; index >= 0; index--) {
+        if (Object.hasOwn(layers[index] ?? {}, "timeoutMs"))
+            return layers[index]?.timeoutMs ?? null;
+    }
+    if (Object.hasOwn(engine, "timeoutMs"))
+        return engine.timeoutMs ?? null;
+    if (engine.kind === "llm")
+        return DEFAULT_LLM_TIMEOUT_MS;
+    if (engine.platform === "opencode-sdk") {
+        const fallbackName = engine.llmEngine ?? config.defaults?.llmEngine;
+        if (fallbackName) {
+            const fallback = engineDefinition(config, fallbackName);
+            if (fallback.kind === "llm") {
+                return Object.hasOwn(fallback, "timeoutMs") ? (fallback.timeoutMs ?? null) : DEFAULT_LLM_TIMEOUT_MS;
+            }
+        }
+    }
+    return DEFAULT_AGENT_TIMEOUT_MS;
+}
+function mergedLlmOverrides(layers) {
+    let merged;
+    for (const layer of layers)
+        if (layer.llm)
+            merged = deepMergeConfig(merged ?? {}, layer.llm);
+    return merged;
+}
+function addSnapshot(config, name, target) {
+    if (target[name])
+        return;
+    const engine = engineDefinition(config, name);
+    if (engine.kind === "llm") {
+        const resolved = resolveLlmEngineUse(config, [{ engine: name }]);
+        const snapshot = {
+            name,
+            kind: "llm",
+            endpoint: engine.endpoint,
+            model: exactModel(config, name, engine, []),
+            concurrency: engine.concurrency ?? 1,
+            ...(engine.provider ? { provider: engine.provider } : {}),
+            ...(resolved.credential ? { credential: resolved.credential } : {}),
+            ...(engine.temperature !== undefined ? { temperature: engine.temperature } : {}),
+            ...(engine.maxTokens !== undefined ? { maxTokens: engine.maxTokens } : {}),
+            ...(engine.supportsJsonSchema !== undefined ? { supportsJsonSchema: engine.supportsJsonSchema } : {}),
+            ...(engine.extraParams ? { extraParams: engine.extraParams } : {}),
+            ...(engine.contextLength !== undefined ? { contextLength: engine.contextLength } : {}),
+            ...(engine.enableThinking !== undefined ? { enableThinking: engine.enableThinking } : {}),
+        };
+        target[name] = snapshot;
+        return;
+    }
+    const harness = HARNESS_BY_ID.get(engine.platform);
+    if (!harness?.capabilities.agentDispatch)
+        throw new ConfigError(`Engine "${name}" cannot dispatch platform ${engine.platform}.`, "INVALID_CONFIG_FILE");
+    const sdk = engine.platform === "opencode-sdk";
+    const builtin = getBuiltinAgentProfile(engine.platform);
+    const fallback = sdk ? (engine.llmEngine ?? config.defaults?.llmEngine ?? null) : null;
+    if (fallback)
+        addSnapshot(config, fallback, target);
+    const snapshot = {
+        name,
+        kind: "agent",
+        runnerKind: sdk ? "sdk" : "agent",
+        platform: engine.platform,
+        bin: engine.bin ?? builtin?.bin ?? (sdk ? "opencode" : engine.platform),
+        args: [...(engine.args ?? builtin?.args ?? [])],
+        workspace: engine.workspace ? path.resolve(engine.workspace) : null,
+        envPassthrough: [...(builtin?.envPassthrough ?? [])],
+        commandBuilder: engine.platform,
+        fallbackLlmEngine: fallback,
+    };
+    target[name] = snapshot;
+}
+function freezeGateJudge(config, engines) {
+    const resolved = resolveLlmEngineUse(config, [], { optional: true });
+    if (!resolved)
+        return null;
+    addSnapshot(config, resolved.engine, engines);
+    return {
+        engine: resolved.engine,
+        model: exactModel(config, resolved.engine, engineDefinition(config, resolved.engine), []),
+        timeoutMs: resolved.timeoutMs,
+    };
+}
+function frozenConcurrency(config) {
+    const configured = config.workflow?.maxConcurrency;
+    return workflowMaxConcurrency(typeof configured === "number" && Number.isFinite(configured) ? configured : undefined);
+}

package/dist/workflows/ir/params.js

@@ -0,0 +1,54 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Pure module: no IO, no engine imports.
+ */
+import { UsageError } from "../../core/errors.js";
+import { validateJsonSchemaSubset } from "../../core/json-schema.js";
+/**
+ * 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 =
+ * valid). Params the plan does not declare a schema for are not constrained.
+ */
+export function validateWorkflowParams(plan, params) {
+    const schemas = plan.paramSchemas;
+    if (!schemas || Object.keys(schemas).length === 0)
+        return [];
+    // Validate the params object as a whole against a synthetic object schema
+    // whose `properties` are the declared param schemas. Missing declared params
+    // are NOT required (params may be optional / defaulted downstream); only a
+    // PRESENT param that violates its declared schema is an error.
+    // Re-root the validator's `$` JSON-pointer prefix to `params` for messages
+    // that read naturally in a start/CLI error (e.g. `params.files: expected …`).
+    return validateJsonSchemaSubset(params, { type: "object", properties: schemas }).map((e) => e.replace(/^\$/, "params"));
+}
+/**
+ * Brief/report 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
+ * mismatch and the tampered-params replay-divergence path. Refuse to describe
+ * or drive the run rather than resolve prompts from schema-violating params.
+ */
+export function assertRunParamsSatisfyPlan(runId, plan, params) {
+    const errors = validateWorkflowParams(plan, params);
+    if (errors.length === 0)
+        return;
+    throw new UsageError(`Workflow run ${runId} failed the frozen param-schema integrity check: the journaled params row no longer ` +
+        `satisfies the workflow's declared parameter schemas (edited after the run started). Refusing to execute it. ` +
+        `Start a new run.\n${errors.map((e) => `  - ${e}`).join("\n")}`);
+}

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

@@ -0,0 +1,68 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Plan hashing for the frozen-plan contract (redesign addendum, R1).
+ *
+ * `workflow start` 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
+ * insertion order, and the same program always freezes to the same hash.
+ *
+ * Pure module: no IO beyond node:crypto, no engine imports.
+ */
+import { createHash } from "node:crypto";
+import { utf8Bytes, WORKFLOW_MAX_JSON_DEPTH, WORKFLOW_MAX_PLAN_BYTES } from "../resource-limits.js";
+import { decodeWorkflowPlanV3 } from "./schema.js";
+/** sha256 hex of the canonical (recursively sorted-keys) JSON of the plan. */
+export function computePlanHash(plan) {
+    return createHash("sha256").update(canonicalPlanJson(plan)).digest("hex");
+}
+/** The canonical JSON string the hash is computed over (also what to persist). */
+export function canonicalPlanJson(plan) {
+    return canonicalJson(plan);
+}
+/** Canonical JSON used by every v3 plan and input hash. */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+/** Decode, require stored canonical bytes, then verify the stored SHA-256. */
+export function decodeCanonicalPlan(runId, planJson, planHash) {
+    if (utf8Bytes(planJson) > WORKFLOW_MAX_PLAN_BYTES)
+        throw new Error(`Workflow run ${runId} frozen plan exceeds the 2 MiB resource limit.`);
+    let parsed;
+    try {
+        parsed = JSON.parse(planJson);
+    }
+    catch {
+        throw new Error(`Workflow run ${runId} has corrupt frozen plan JSON.`);
+    }
+    const plan = decodeWorkflowPlanV3(parsed);
+    const canonical = canonicalPlanJson(plan);
+    if (planJson !== canonical)
+        throw new Error(`Workflow run ${runId} has noncanonical frozen plan JSON.`);
+    const actual = computePlanHash(plan);
+    if (!planHash || !/^[0-9a-f]{64}$/.test(planHash) || actual !== planHash)
+        throw new Error(`Workflow run ${runId} frozen plan integrity check failed.`);
+    return plan;
+}
+function sortKeys(value, depth = 0) {
+    if (depth > WORKFLOW_MAX_JSON_DEPTH)
+        throw new TypeError("JSON value exceeds maximum depth");
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("JSON values must be finite");
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => sortKeys(item, depth + 1));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => [k, sortKeys(v, depth + 1)]));
+    }
+    throw new TypeError("JSON value contains a non-JSON value");
+}