akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/workflows/freeze/environment.js

@@ -3,42 +3,73 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
+import dotenv from "dotenv";
 import { loadAdapterExecutionSource } from "../../commands/command/execution-source-loader.js";
 import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { compareCodePoints, isWithin, toPosix } from "../../core/common.js";
 import { parseEnvRef } from "../../core/env-secret-ref.js";
 import { UsageError } from "../../core/errors.js";
 import { deriveInstallations } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
-import { freezeWorkflowEnvironment } from "../ir/environment-v4.js";
+import { isInferredSecretName } from "../../tasks/log-redaction.js";
+import { SECRET_TOKEN_RE } from "../exec/environment.js";
+import { detectSecretShapedParams } from "../exec/param-secrets.js";
+/**
+ * A step's frozen environment: literal `env:` values, `pass_env` names, then
+ * one value-free descriptor per `unit.env` ref (owner, key set, secret-token
+ * names). Values are read at dispatch (`exec/environment.ts`), never frozen.
+ */
 export function freezeEnvironment(source, exec, context) {
-    const literals = Object.entries(source.env ?? {}).map(([name, value]) => Object.freeze({ kind: "literal", name, value: String(value) }));
-    const passThrough = (exec?.passEnv ?? []).map((name) => Object.freeze({ kind: "pass-through", name }));
-    const refs = source.unit?.env ?? [];
-    const envRefs = freezeWorkflowEnvironment(refs, {
-        collector: context.collector,
-        resolveRef: (ref) => {
-            const parsedEnv = parseEnvRef(ref);
-            if (parsedEnv.type !== "env")
-                throw new UsageError(`Expected an env ref; got ${ref}.`, "WORKFLOW_SOURCE_INVALID");
-            const owned = resolveOwnedAssetSync(ref, "env", context);
-            return { ref: owned.ref, bundle: owned.bundle, adapter: owned.adapter, root: owned.root, path: owned.file };
-        },
+    const literals = Object.entries(source.env ?? {}).map(([name, raw]) => {
+        const value = String(raw);
+        // A literal is frozen into plan_json; a credential belongs in an env ref, as for task env.
+        if (isInferredSecretName(name) || detectSecretShapedParams({ [name]: value }).length > 0) {
+            throw new UsageError(`Workflow step ${source.id} env.${name} is a secret-shaped literal env value. Store credentials in an env asset (unit.env) rather than workflow source.`, "WORKFLOW_SOURCE_INVALID");
+        }
+        return Object.freeze({ kind: "literal", name, value });
     });
+    const passThrough = (exec?.passEnv ?? []).map((name) => Object.freeze({ kind: "pass-through", name }));
+    const seen = new Set();
+    const envRefs = [];
+    for (const [precedence, ref] of (source.unit?.env ?? []).entries()) {
+        if (parseEnvRef(ref).type !== "env") {
+            throw new UsageError(`Expected an env ref; got ${ref}.`, "WORKFLOW_SOURCE_INVALID");
+        }
+        const owned = resolveOwnedAssetSync(ref, "env", context);
+        if (seen.has(owned.ref))
+            continue;
+        seen.add(owned.ref);
+        const parsed = dotenv.parse(fs.readFileSync(owned.file));
+        const secretNames = new Set();
+        for (const value of Object.values(parsed)) {
+            for (const match of value.matchAll(SECRET_TOKEN_RE))
+                if (match[1])
+                    secretNames.add(match[1]);
+        }
+        envRefs.push(Object.freeze({
+            kind: "env-ref",
+            ref: owned.ref,
+            owner: Object.freeze({
+                bundle: owned.bundle,
+                adapter: owned.adapter,
+                requestedRoot: owned.root,
+                requestedPath: owned.file,
+                relativePath: toPosix(path.relative(owned.root, owned.file)),
+            }),
+            keys: Object.keys(parsed).sort(compareCodePoints),
+            secretNames: [...secretNames].sort(compareCodePoints),
+            precedence,
+        }));
+    }
     return [...literals, ...passThrough, ...envRefs];
 }
-export async function guardedExecutionSource(ref, kind, context) {
+/** Load a command or persona the workflow names, resolved through the workflow's own bundles. */
+export async function workflowExecutionSource(ref, kind, context) {
     const owned = await resolveOwnedAsset(ref, kind === "command" ? "command" : "agent", context);
-    captureOwned(owned, context.collector);
-    const options = {
-        config: context.config,
-        fileContext: () => context.collector.fileContext(owned.root, owned.file),
-    };
-    const rendered = kind === "command"
-        ? await loadAdapterExecutionSource(owned.ref, "command", options)
-        : await loadAdapterExecutionSource(owned.ref, "persona", options);
-    context.collector.bindIdentity(owned.file, owned.root, rendered.identity);
-    return rendered;
+    return kind === "command"
+        ? loadAdapterExecutionSource(owned.ref, "command", { config: context.config })
+        : loadAdapterExecutionSource(owned.ref, "persona", { config: context.config });
 }
 export async function resolveOwnedAsset(ref, type, context) {
     return resolveOwnedAssetCore(ref, type, context, false);
@@ -46,44 +77,26 @@ export async function resolveOwnedAsset(ref, type, context) {
 export function resolveOwnedAssetSync(ref, type, context) {
     return resolveOwnedAssetCore(ref, type, context, true);
 }
-export function resolveOwnedAssetCore(refInput, type, context, sync) {
+function resolveOwnedAssetCore(refInput, type, context, sync) {
     const parsed = parseBundleRef(refInput);
     const plural = type === "env" ? "env" : `${type}s`;
     const conceptId = parsed.conceptId.startsWith(`${plural}/`) ? parsed.conceptId : `${plural}/${parsed.conceptId}`;
     const name = conceptId.slice(plural.length + 1);
     const direct = parsed.bundle ? configuredOwner(parsed.bundle, context.config) : undefined;
-    const sources = resolveSourceEntries(undefined, context.config);
-    const installations = deriveInstallations(sources);
-    const candidates = direct
-        ? [direct]
-        : sources.flatMap((source, index) => {
-            const installation = installations[index];
-            if (!installation || (parsed.bundle && installation.id !== parsed.bundle))
-                return [];
-            return [
-                {
-                    bundle: installation.id,
-                    root: source.path,
-                    adapter: source.adapterId ?? installation.components[0]?.adapter ?? "akm",
-                },
-            ];
-        });
+    const candidates = direct ? [direct] : installedOwners(parsed.bundle, context.config);
     const findSync = () => {
         for (const candidate of candidates) {
             const directory = path.join(candidate.root, plural);
             for (const extension of assetExtensions(type)) {
                 const file = path.resolve(directory, `${name}${extension}`);
                 if (fs.existsSync(file) && fs.statSync(file).isFile()) {
+                    if (!isWithin(file, candidate.root)) {
+                        throw new UsageError(`${file} resolves outside its owning root.`, "PATH_ESCAPE_VIOLATION");
+                    }
                     return { ...candidate, ref: makeBundleRef(candidate.bundle, conceptId), file };
                 }
             }
         }
-        // P4 (docs/plans/specs/p4-deletions-closeout.md §5.2, row B-11 preservation
-        // gate): PRESERVED, not re-coded — tests/workflows/child-workflow-freeze.test.ts's
-        // "B-11: workflows/<ref> that does not resolve fails the existing
-        // asset-resolution failure, unchanged in code and shape" pins this exact
-        // code by name and by its own title. Recorded deviation from §5.2's flat
-        // "→ WORKFLOW_SOURCE_INVALID" for this file's 3 sites.
         throw new UsageError(`Workflow source target ${refInput} was not found.`, "INVALID_FLAG_VALUE");
     };
     if (sync)
@@ -101,7 +114,24 @@ export function resolveOwnedAssetCore(refInput, type, context, sync) {
         return findSync();
     })();
 }
-export function configuredOwner(bundle, config) {
+/** Every installed bundle root (or just `bundle`'s), in installation priority order. */
+function installedOwners(bundle, config) {
+    const sources = resolveSourceEntries(undefined, config);
+    const installations = deriveInstallations(sources);
+    return sources.flatMap((source, index) => {
+        const installation = installations[index];
+        if (!installation || (bundle && installation.id !== bundle))
+            return [];
+        return [
+            {
+                bundle: installation.id,
+                root: source.path,
+                adapter: source.adapterId ?? installation.components[0]?.adapter ?? "akm",
+            },
+        ];
+    });
+}
+function configuredOwner(bundle, config) {
     const entry = config.bundles?.[bundle];
     if (!entry || typeof entry.path !== "string")
         return undefined;
@@ -113,55 +143,32 @@ export function configuredOwner(bundle, config) {
         adapter: component?.adapter ?? "akm",
     };
 }
-export function assetExtensions(type) {
+const SCRIPT_EXTENSIONS = [
+    "",
+    ".sh",
+    ".ts",
+    ".js",
+    ".py",
+    ".rb",
+    ".go",
+    ".pl",
+    ".php",
+    ".lua",
+    ".r",
+    ".swift",
+    ".kt",
+    ".kts",
+    ".ps1",
+    ".cmd",
+    ".bat",
+];
+function assetExtensions(type) {
     if (type === "script")
-        return [
-            "",
-            ".sh",
-            ".ts",
-            ".js",
-            ".py",
-            ".rb",
-            ".go",
-            ".pl",
-            ".php",
-            ".lua",
-            ".r",
-            ".swift",
-            ".kt",
-            ".kts",
-            ".ps1",
-            ".cmd",
-            ".bat",
-        ];
+        return SCRIPT_EXTENSIONS;
     if (type === "env")
         return ["", ".env"];
     return ["", ".md", ".yml"];
 }
-export function captureOwned(owned, collector) {
-    trackAncestry(collector, owned.root, owned.file);
-    const retained = collector.capture(owned.file, owned.root, { authored: true });
-    return collector.bindIdentity(owned.file, owned.root, {
-        ref: owned.ref,
-        bundle: owned.bundle,
-        adapter: owned.adapter,
-        file: retained.relativePath,
-        hash: retained.sha256,
-    });
-}
-export function trackAncestry(collector, rootInput, file) {
-    const root = path.resolve(rootInput);
-    collector.trackDirectory(root, root);
-    const relative = path.relative(root, path.dirname(file));
-    if (relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw new UsageError(`${file} resolves outside its owning root.`, "PATH_ESCAPE_VIOLATION");
-    }
-    let current = root;
-    for (const segment of relative === "" ? [] : relative.split(path.sep)) {
-        current = path.join(current, segment);
-        collector.trackDirectory(current, root);
-    }
-}
 export function qualifyRef(ref, plural, asset, config) {
     const parsed = parseBundleRef(ref);
     if (parsed.bundle)

package/dist/workflows/freeze/freeze.js

@@ -0,0 +1,172 @@
+// 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/.
+/**
+ * Freeze a compiled workflow plan into the plan a run executes. Every step's
+ * authored spec resolves through the shared command/task authorities into a
+ * frozen `root` (engine, model, timeout, concurrency, dispatch target and
+ * environment descriptors); gates get their judge; the compile-only fields are
+ * dropped; the source file's sha256 is recorded. Nothing is published here.
+ */
+import { createHash } from "node:crypto";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
+import { NO_ENGINE_MESSAGE_SUFFIX } from "../../integrations/agent/engine-fallback.js";
+import { resolveExecution } from "../../integrations/agent/execution.js";
+import { checkWorkflowPlan } from "../compile.js";
+import { defaultMapConcurrency, workflowMaxConcurrency } from "../concurrency-policy.js";
+import { canonicalJson } from "../ir/plan-hash.js";
+import { WORKFLOW_PLAN_VERSION, } from "../plan.js";
+import { classifyWorkflowStepUses } from "../source-semantics.js";
+import { assertChildOutputReferences } from "./child-output-references.js";
+import { qualifyRef } from "./environment.js";
+import { baseUnitOf } from "./step-values.js";
+import { childWorkflowDispatch } from "./targets/child-workflow.js";
+import { commandDispatch, commandResult } from "./targets/command.js";
+import { directScript } from "./targets/script.js";
+import { directShell } from "./targets/shell.js";
+import { taskDispatch } from "./targets/task.js";
+/** Resolve and freeze one workflow (and, recursively, every child it composes). */
+export async function freezeWorkflow(asset, config, refPath = [asset.ref]) {
+    const compiled = asset.plan;
+    const checked = checkWorkflowPlan(compiled);
+    if (!checked.ok) {
+        throw new UsageError(checked.errors.map((error) => `${asset.path}:${error.line}: ${error.message}`).join("\n"), "WORKFLOW_SOURCE_INVALID");
+    }
+    const context = {
+        asset,
+        config,
+        plan: compiled,
+        refPath,
+        freezeChild: (child, childRefPath) => freezeWorkflow(child, config, childRefPath),
+    };
+    let engineAnnouncement;
+    const steps = [];
+    for (const step of compiled.steps) {
+        const { spec, ...frozenStep } = step;
+        const source = { ...(spec ?? { source: { path: asset.path, start: 1, end: 1 } }), id: step.stepId };
+        let root;
+        if (!step.route) {
+            const resolved = await resolveStep(source, context);
+            engineAnnouncement ??= resolved.engineAnnouncement;
+            root = frozenRoot(step.stepId, source, resolved, compiled, config);
+        }
+        let frozenJudge = null;
+        if (step.gate.criteria.length > 0) {
+            const judge = resolveJudge(source, step.gate.criteria[0] ?? "", context);
+            if (judge) {
+                frozenJudge = judge.target;
+                engineAnnouncement ??= judge.engineAnnouncement;
+            }
+            else {
+                warn(`Workflow step "${step.stepId}" has completion criteria but no verification engine is available ` +
+                    "(set workflow.judgeEngine, defaults.engine, or install an opencode-sdk binary). The step will block " +
+                    "for `akm workflow resume` once it is reached.");
+            }
+        }
+        steps.push({ ...frozenStep, ...(root ? { root } : {}), gate: { ...step.gate, frozenJudge } });
+    }
+    assertChildOutputReferences(steps);
+    const plan = {
+        irVersion: WORKFLOW_PLAN_VERSION,
+        title: asset.title,
+        ...(compiled.params ? { params: compiled.params } : {}),
+        ...(compiled.paramSchemas ? { paramSchemas: compiled.paramSchemas } : {}),
+        ...(compiled.budget ? { budget: compiled.budget } : {}),
+        ...(compiled.outputs ? { outputs: compiled.outputs } : {}),
+        execution: { maxConcurrency: workflowMaxConcurrency(config.workflow?.maxConcurrency) },
+        sourceHash: asset.sourceHash,
+        steps,
+    };
+    return { plan, warnings: checked.warnings, ...(engineAnnouncement ? { engineAnnouncement } : {}) };
+}
+async function resolveStep(source, context) {
+    const baseUnit = baseUnitOf(source);
+    if (source.exec)
+        return directShell(source, baseUnit, context);
+    if (!source.uses)
+        throw new Error(`workflow step ${source.id} has neither exec nor uses`);
+    const target = classifyWorkflowStepUses(source.uses);
+    if (target.kind === "task")
+        return taskDispatch(source, baseUnit, target.ref, context);
+    if (target.kind === "workflow") {
+        return childWorkflowDispatch({
+            source,
+            baseUnit,
+            childRefInput: target.ref,
+            context,
+            via: "direct",
+            authoredInputs: { kind: "with", value: source.with },
+        });
+    }
+    // `commands/<ref>` and `scripts/<ref>` are not binding surfaces; `akm/command`'s
+    // `with:` is its own argument bag.
+    if (target.kind !== "builtin-command" && source.with !== undefined) {
+        const family = target.kind === "command" ? "commands" : "scripts";
+        throw new UsageError(`Workflow step ${source.id} cannot pass with: to ${family} target ${target.ref}; a ${target.kind} ref is not a binding surface.`, "COMPOSITION_INVALID");
+    }
+    if (target.kind === "script")
+        return directScript(source, baseUnit, target.ref, context);
+    const action = target.kind === "builtin-command"
+        ? source.with
+        : { ref: qualifyRef(target.ref, "commands", context.asset, context.config) };
+    return commandDispatch(source, baseUnit, action, context);
+}
+/** The gate judge's frozen command target, or undefined when no engine is available and none is configured. */
+function resolveJudge(source, rubric, context) {
+    const configuredEngine = context.config.workflow?.judgeEngine;
+    try {
+        const prepared = resolveExecution({
+            content: rubric.trim() || "Judge workflow completion.",
+            config: context.config,
+            ...(configuredEngine ? { current: { engine: configuredEngine } } : {}),
+        });
+        return commandResult(source, { onError: "fail", source: source.source }, prepared, context);
+    }
+    catch (err) {
+        if (configuredEngine || !(err instanceof ConfigError && err.message.includes(NO_ENGINE_MESSAGE_SUFFIX)))
+            throw err;
+        return undefined;
+    }
+}
+function frozenRoot(stepId, source, resolved, plan, config) {
+    const unit = resolved.unit;
+    const target = resolved.target.kind === "shell"
+        ? {
+            ...resolved.target,
+            contentHash: createHash("sha256")
+                .update("akm.workflow.shell.v1\0")
+                .update(canonicalJson({
+                exec: resolved.target.exec,
+                environment: resolved.environment,
+                cwdIdentity: resolved.target.cwdIdentity,
+            }))
+                .digest("hex"),
+        }
+        : resolved.target;
+    const node = {
+        kind: "unit",
+        id: source.map ? `${stepId}.unit` : stepId,
+        instructions: resolved.instructions,
+        ...(source.inputs && source.inputs.length > 0 ? { inputs: [...source.inputs] } : {}),
+        ...(unit.output !== undefined ? { schema: unit.output } : {}),
+        ...(unit.retry ? { retry: { max: unit.retry.max, on: [...unit.retry.on] } } : {}),
+        onError: unit.onError ?? plan.defaults?.onError ?? "fail",
+        ...(unit.env ? { env: [...unit.env] } : {}),
+        isolation: unit.isolation ?? "none",
+        source: { ...source.source },
+        frozenTarget: target,
+        environment: [...resolved.environment],
+    };
+    if (!source.map)
+        return node;
+    return {
+        kind: "map",
+        id: `${stepId}.map`,
+        over: source.map.over,
+        template: node,
+        concurrency: source.map.concurrency ?? defaultMapConcurrency(config.workflow?.defaultMapConcurrency),
+        reducer: source.map.reducer ?? "collect",
+        source: { ...source.source },
+    };
+}

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

@@ -4,11 +4,20 @@
 import { canonicalResolvedExecutionRequest, decodeResolvedExecutionRequest, } from "../../execution/resolved-request.js";
 import { defaultLlmEngineConcurrency } from "../concurrency-policy.js";
 import { DEFAULT_EXEC_TIMEOUT_MS } from "../resource-limits.js";
+/** The unit's authored settings plus its source span and argv, before any target resolution. */
+export function baseUnitOf(source) {
+    return {
+        ...(source.unit ? structuredClone(source.unit) : {}),
+        source: { ...source.source },
+        ...(source.exec ? { exec: { ...source.exec } } : {}),
+    };
+}
+/** Resolve an exec's timeout: unit `timeout:` → document `defaults.timeout` → the default. */
 export function freezeExecSpec(source, exec, context) {
     const declared = Object.hasOwn(source.unit ?? {}, "timeoutMs")
         ? source.unit?.timeoutMs
-        : context.sourceIr.defaults && Object.hasOwn(context.sourceIr.defaults, "timeoutMs")
-            ? context.sourceIr.defaults.timeoutMs
+        : context.plan.defaults && Object.hasOwn(context.plan.defaults, "timeoutMs")
+            ? context.plan.defaults.timeoutMs
             : undefined;
     return {
         ...exec,
@@ -28,6 +37,7 @@ export function targetConcurrency(runner, config) {
     const fallback = fallbackName ? config.engines?.[fallbackName] : undefined;
     return defaultLlmEngineConcurrency(runner.fallbackConnection.endpoint, fallback?.kind === "llm" ? fallback.concurrency : undefined);
 }
+/** The request as it may be persisted: its live runtime environment removed. */
 export function durableRequest(request) {
     const wire = JSON.parse(canonicalResolvedExecutionRequest(request));
     const runtime = { ...wire.runtime };
@@ -35,9 +45,6 @@ export function durableRequest(request) {
     wire.runtime = runtime;
     return decodeResolvedExecutionRequest(wire);
 }
-export function executionValues(source, workspace) {
-    return executionUnitValues(source.unit, workspace);
-}
 export function executionUnitValues(unit, workspace) {
     return Object.freeze({
         ...(unit && Object.hasOwn(unit, "engine") ? { engine: unit.engine } : {}),
@@ -48,21 +55,12 @@ export function executionUnitValues(unit, workspace) {
         workspace,
     });
 }
-/**
- * Step ids that appear BEFORE `stepId` in the frozen step order (A-N4) — the
- * SAME ordering map.over/inputs[] rely on. Shared by `targets/task.ts` (a
- * step's own `with:` against its composed task's declared `inputs:`) and
- * `targets/child-workflow.ts` (the SAME step's effective inputs, re-bound
- * against a composed child workflow's declared `params:`, spec A-N8) — moved
- * here rather than duplicated so both can import it without either importing
- * the other.
- */
-export function earlierStepIds(sourceIr, stepId) {
-    const steps = sourceIr.jobs[0]?.steps ?? [];
-    const index = steps.findIndex((step) => step.id === stepId);
-    return new Set(index < 0 ? [] : steps.slice(0, index).map((step) => step.id));
+/** Step ids declared BEFORE `stepId` — the same ordering `map.over` and `inputs:` rely on. */
+export function earlierStepIds(plan, stepId) {
+    const index = plan.steps.findIndex((step) => step.stepId === stepId);
+    return new Set(index < 0 ? [] : plan.steps.slice(0, index).map((step) => step.stepId));
 }
-/** THIS workflow's own declared param names (A-N4) — never an outer composing task's. See {@link earlierStepIds}. */
-export function declaredParamNames(sourceIr) {
-    return new Set(sourceIr.params ? Object.keys(sourceIr.params) : []);
+/** THIS workflow's own declared param names — never an outer composing task's. */
+export function declaredParamNames(plan) {
+    return new Set(plan.paramSchemas ? Object.keys(plan.paramSchemas) : (plan.params ?? []));
 }