akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/workflows/program/project.js

@@ -0,0 +1,105 @@
+// 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/.
+/**
+ * Renderer name for YAML workflow programs. Lives in this leaf module (not
+ * `../renderer.ts`) so the indexer matcher can name it without importing the
+ * renderer module and its registration side effects.
+ */
+export const WORKFLOW_PROGRAM_RENDERER_NAME = "workflow-program-yaml";
+/** File extensions that mark a workflow asset as a YAML program. */
+const WORKFLOW_PROGRAM_PATH_RE = /\.ya?ml$/i;
+/** True when a workflow asset path holds a YAML program (vs. markdown). */
+export function isWorkflowProgramPath(filePath) {
+    return WORKFLOW_PROGRAM_PATH_RE.test(filePath);
+}
+/**
+ * The instruction text a step contributes to the flat step projection.
+ * Unit and map steps carry their unit's RAW instruction template; route
+ * steps have no unit, so a deterministic description of the routing table
+ * stands in (the spine still needs a non-empty instructions string).
+ */
+export function programStepInstructions(step) {
+    if (step.unit)
+        return step.unit.instructions;
+    if (step.map)
+        return step.map.unit.instructions;
+    if (step.route) {
+        const branches = step.route.branches.map((b) => `"${b.match}" -> ${b.stepId}`);
+        if (step.route.defaultStepId !== undefined)
+            branches.push(`default -> ${step.route.defaultStepId}`);
+        return `Route on ${step.route.input}: ${branches.join(", ")}.`;
+    }
+    return "";
+}
+/**
+ * Project the program's steps into flat `WorkflowStepDefinition`s.
+ *
+ * `gate.criteria` MUST project into `completionCriteria`: `startWorkflowRun`
+ * persists this projection as the step rows' `completion_json`, which is what
+ * `completeWorkflowStep` reads to run the summary-validation gate (fail-open
+ * when empty). Dropping the criteria here silently disarms every YAML gate.
+ */
+export function projectProgramStepDefinitions(program) {
+    return program.steps.map((step, index) => ({
+        id: step.id,
+        title: step.title ?? step.id,
+        instructions: programStepInstructions(step),
+        ...(step.gate && step.gate.criteria.length > 0 ? { completionCriteria: [...step.gate.criteria] } : {}),
+        sequenceIndex: index,
+    }));
+}
+/** Project the `params` block into the flat `WorkflowParameter` list. */
+export function projectProgramParameters(program) {
+    if (!program.params)
+        return undefined;
+    const parameters = Object.entries(program.params).map(([name, schema]) => {
+        const description = schema.description;
+        return {
+            name,
+            ...(typeof description === "string" && description !== "" ? { description } : {}),
+        };
+    });
+    return parameters.length > 0 ? parameters : undefined;
+}
+/**
+ * Compact, show-facing orchestration summary for one program step, reusing
+ * the existing `WorkflowStepOrchestrationSummary` shape. Field mapping:
+ * `runner`/`model`/`timeoutMs` merge the run-level `defaults` exactly like
+ * the compiler does (per-unit wins), `fanOut.over` carries the raw `${{ … }}`
+ * expression, and `route` carries the explicit input + branch table.
+ * Returns undefined when the step declares nothing worth summarizing.
+ */
+export function summarizeProgramStepOrchestration(step, defaults) {
+    const unit = step.unit ?? step.map?.unit;
+    const runner = unit?.runner ?? defaults?.runner;
+    const model = unit?.model ?? defaults?.model;
+    const timeoutMs = unit?.timeoutMs !== undefined ? unit.timeoutMs : defaults?.timeoutMs;
+    const summary = {
+        ...(runner !== undefined ? { runner } : {}),
+        ...(unit?.profile !== undefined ? { profile: unit.profile } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(step.map
+            ? {
+                fanOut: {
+                    over: step.map.over,
+                    ...(step.map.concurrency !== undefined ? { concurrency: step.map.concurrency } : {}),
+                    reducer: step.map.reducer ?? "collect",
+                },
+            }
+            : {}),
+        ...(unit?.output !== undefined || step.output !== undefined ? { hasSchema: true } : {}),
+        ...(unit?.env !== undefined ? { env: [...unit.env] } : {}),
+        ...(step.route
+            ? {
+                route: {
+                    input: step.route.input,
+                    branches: step.route.branches.map((b) => ({ match: b.match, stepId: b.stepId })),
+                    ...(step.route.defaultStepId !== undefined ? { defaultStepId: step.route.defaultStepId } : {}),
+                },
+            }
+            : {}),
+    };
+    return Object.keys(summary).length > 0 ? summary : undefined;
+}

package/dist/workflows/program/schema.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/.
+export const WORKFLOW_PROGRAM_VERSION = 1;
+/** Execution backend for a unit. `inherit` defers to the run-level default. */
+export const PROGRAM_RUNNER_KINDS = ["llm", "agent", "sdk", "inherit"];
+/** How a map step folds its per-item unit results into the step artifact. */
+export const PROGRAM_REDUCERS = ["collect", "vote"];
+/** Failure policy: fail the step on first unit failure, or record and go on. */
+export const PROGRAM_ON_ERROR = ["fail", "continue"];
+/** Filesystem isolation for file-mutating units (enforcement is R2). */
+export const PROGRAM_ISOLATION_KINDS = ["none", "worktree"];
+/**
+ * `retry.on` vocabulary — exactly the persisted `AgentFailureReason` taxonomy
+ * from `src/integrations/agent/spawn.ts`. The `satisfies` clause fails the
+ * typecheck if spawn.ts adds/renames a reason without this list (and the JSON
+ * Schema, via the drift test) being updated.
+ */
+const RETRY_REASON_SET = {
+    timeout: true,
+    spawn_failed: true,
+    non_zero_exit: true,
+    parse_error: true,
+    cooldown: true,
+    llm_rate_limit: true,
+    llm_content_filter: true,
+    llm_invalid_json: true,
+    content_policy_reject: true,
+    unsupported_type: true,
+    no_change: true,
+    aborted: true,
+};
+export const PROGRAM_RETRY_REASONS = Object.keys(RETRY_REASON_SET);
+/**
+ * Step ids: `[A-Za-z_][A-Za-z0-9_-]*` (also pinned in the JSON Schema).
+ *
+ * This is EXACTLY the `<ident>` grammar `readIdent` accepts in
+ * `program/expressions.ts` for `${{ steps.<id>.output }}` references: a
+ * letter/underscore first char, then letters/digits/underscores/dashes, and
+ * NO dots (the expression parser treats `.` as the `.output` path separator,
+ * so a dotted id could never be addressed). Keeping step ids inside the
+ * addressable grammar guarantees every step can be referenced from map
+ * inputs, routes, and unit templates without renaming.
+ *
+ * Forbidding dots additionally keeps the engine's internal gate-row node id
+ * `<stepId>.gate` collision-free: no user step id can contain a dot, so it can
+ * never equal another step's `<stepId>.gate` synthetic id.
+ */
+export const PROGRAM_STEP_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/**
+ * Param names must be `${{ params.<ident> }}`-addressable, so they are plain
+ * identifiers (no dots/dashes).
+ */
+export const PROGRAM_PARAM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;

package/dist/workflows/renderer.js

@@ -2,18 +2,28 @@
 // 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/.
 /**
- * Show + indexing renderer for workflow assets.
+ * Show + indexing renderers for workflow assets.
  *
- * Reads the markdown via `parseWorkflow` and projects the validated
- * `WorkflowDocument` down to the public `ShowResponse` shape (which still
- * uses the flat `WorkflowStepDefinition` type for backwards compatibility)
- * and into search hints for the indexer.
+ * Two formats, one asset type:
+ *
+ *   - `workflow-md` — reads the classic linear markdown via `parseWorkflow`
+ *     and projects the validated `WorkflowDocument` down to the public
+ *     `ShowResponse` shape (which still uses the flat
+ *     `WorkflowStepDefinition` type for backwards compatibility) and into
+ *     search hints for the indexer.
+ *   - `workflow-program-yaml` — reads a YAML workflow *program* (redesign
+ *     addendum, R1) via `parseWorkflowProgram` and projects it through
+ *     `program/project.ts`, including a compact orchestration summary per
+ *     step (runner/model, `fanOut.over` expression, route table).
  */
 import { makeAssetRef } from "../core/asset/asset-ref.js";
 import { UsageError } from "../core/errors.js";
 import { registerMetadataContributor } from "../indexer/passes/metadata-contributors.js";
 import { parseWorkflow } from "./parser.js";
+import { parseWorkflowProgram } from "./program/parser.js";
+import { programStepInstructions, projectProgramParameters, summarizeProgramStepOrchestration, WORKFLOW_PROGRAM_RENDERER_NAME, } from "./program/project.js";
 import { cacheWorkflowDocument } from "./runtime/document-cache.js";
+export { WORKFLOW_PROGRAM_RENDERER_NAME };
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -59,6 +69,43 @@ export const workflowMdRenderer = {
         };
     },
 };
+function loadProgram(ctx) {
+    const result = parseWorkflowProgram(ctx.content(), { path: ctx.relPath });
+    if (result.ok)
+        return result.program;
+    const summary = result.errors.map((e) => `${ctx.relPath}:${e.line} — ${e.message}`).join("\n");
+    throw new UsageError(`Workflow has errors:\n${summary}`);
+}
+/** Show renderer for YAML workflow programs — mirrors `workflowMdRenderer`. */
+export const workflowProgramRenderer = {
+    name: WORKFLOW_PROGRAM_RENDERER_NAME,
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const program = loadProgram(ctx);
+        const ref = makeAssetRef("workflow", name, ctx.origin);
+        const parameters = projectProgramParameters(program);
+        return {
+            type: "workflow",
+            name,
+            path: ctx.absPath,
+            action: buildWorkflowAction(ref),
+            description: program.description,
+            workflowTitle: program.name,
+            ...(parameters ? { parameters: parameters.map((p) => p.name), workflowParameters: parameters } : {}),
+            steps: program.steps.map((step, index) => {
+                const orchestration = summarizeProgramStepOrchestration(step, program.defaults);
+                return {
+                    id: step.id,
+                    title: step.title ?? step.id,
+                    instructions: programStepInstructions(step),
+                    ...(step.gate ? { completionCriteria: [...step.gate.criteria] } : {}),
+                    sequenceIndex: index,
+                    ...(orchestration ? { orchestration } : {}),
+                };
+            }),
+        };
+    },
+};
 registerMetadataContributor({
     name: "workflow-document-metadata",
     appliesTo: ({ rendererName }) => rendererName === "workflow-md",
@@ -84,3 +131,33 @@ registerMetadataContributor({
         cacheWorkflowDocument(entry, doc);
     },
 });
+registerMetadataContributor({
+    name: "workflow-program-metadata",
+    appliesTo: ({ rendererName }) => rendererName === WORKFLOW_PROGRAM_RENDERER_NAME,
+    contribute(entry, { renderContext }) {
+        // Parse failures throw, which the metadata pass turns into a
+        // skip-with-warning — broken programs never land in the index, mirroring
+        // markdown workflows. No workflow_documents cache row is written: YAML
+        // programs are re-parsed from disk by the runtime loader.
+        const program = loadProgram(renderContext);
+        const hints = new Set(entry.searchHints ?? []);
+        hints.add(program.name);
+        for (const step of program.steps) {
+            hints.add(step.id);
+            if (step.title)
+                hints.add(step.title);
+            hints.add(programStepInstructions(step));
+            for (const criterion of step.gate?.criteria ?? []) {
+                hints.add(criterion);
+            }
+        }
+        entry.searchHints = Array.from(hints).filter(Boolean);
+        if (!entry.description && program.description) {
+            entry.description = program.description;
+        }
+        const parameters = projectProgramParameters(program);
+        if (parameters?.length) {
+            entry.parameters = parameters;
+        }
+    },
+});

package/dist/workflows/runtime/agent-identity.js

@@ -11,14 +11,42 @@
  * already exposes via the environment.
  *
  * Resolution is best-effort and environment-driven:
- *   - harness:    AKM_AGENT_HARNESS, else inferred from a known harness env var.
+ *   - harness:    AKM_AGENT_HARNESS, else inferred from a harness session-id
+ *                 env var (`identityEnv`), else from a harness presence flag
+ *                 (`presenceEnv`).
  *   - sessionId:  AKM_SESSION_ID, else the harness-native session env var.
+ *                 Presence flags NEVER contribute a session id — their values
+ *                 (`CODEX_SANDBOX=seatbelt`, `GEMINI_CLI=1`) are modes/flags,
+ *                 not sessions, and must not be persisted as agent_session_id.
  *
  * Explicit values passed to `startWorkflowRun` always win over the environment.
  *
+ * The harness-native markers are DERIVED from `HARNESS_REGISTRY` (plan §"Kill
+ * registry drift", P2): each harness declares its session-id env vars via
+ * `identityEnv` and its presence-only flags via `presenceEnv`, so adding a
+ * harness never touches this module. Only the `AKM_*` explicit-override vars
+ * are non-registry (they are akm's own, not any harness's) and stay hardcoded
+ * here.
+ *
  * @module workflows/agent-identity
  */
-import { denormalizeRuntimeIdentity } from "../../integrations/harnesses/index.js";
+import { denormalizeRuntimeIdentity, HARNESS_REGISTRY } from "../../integrations/harnesses/index.js";
+/**
+ * Derive a marker table from one registry env-var field, ordered by canonical
+ * id. The sort keeps the pre-derivation precedence byte-identical ('claude'
+ * before 'opencode' — the old if/else chain's order) and independent of
+ * `HARNESS_REGISTRY` declaration order, which is pinned for JSON-schema enum
+ * stability, not detection precedence.
+ */
+function deriveMarkers(pick) {
+    return HARNESS_REGISTRY.filter((h) => (pick(h)?.length ?? 0) > 0)
+        .map((h) => ({ harnessId: h.id, envKeys: pick(h) ?? [] }))
+        .sort((a, b) => a.harnessId.localeCompare(b.harnessId));
+}
+/** Session-id-bearing markers — usable for BOTH harness inference and sessionId. */
+const SESSION_MARKERS = deriveMarkers((h) => h.identityEnv);
+/** Presence-only flags — harness inference ONLY; their values are never a session id. */
+const PRESENCE_MARKERS = deriveMarkers((h) => h.presenceEnv);
 function firstNonEmpty(env, keys) {
     for (const key of keys) {
         const value = env[key];
@@ -37,20 +65,37 @@ export function resolveAgentIdentity(env = process.env) {
     // Explicit override always wins.
     let harness = firstNonEmpty(env, ["AKM_AGENT_HARNESS"]);
     if (!harness) {
-        // Infer the harness from a harness-specific *session* env var. We only
-        // infer when a concrete session id is present: the bare "this process is
-        // Claude Code" flag does not mean a given run is owned by an agent session,
-        // so it must not silently stamp identity onto manual CLI invocations.
-        if (firstNonEmpty(env, ["CLAUDE_SESSION_ID"])) {
-            // Runtime identity for Claude Code is "claude-code" (vs the canonical
-            // config id "claude"). Derived from the unified registry's bridge (#562)
-            // so the persisted runtime string can't drift — still emits "claude-code".
-            harness = denormalizeRuntimeIdentity("claude");
+        // Infer the harness from a harness-specific *session* env var first
+        // (registry `identityEnv` markers). A concrete session id is the
+        // strongest evidence of the immediate driver, so it outranks any
+        // presence flag — e.g. opencode launched inside a codex sandbox
+        // (OPENCODE_SESSION_ID + CODEX_SANDBOX) attributes to opencode.
+        for (const marker of SESSION_MARKERS) {
+            if (firstNonEmpty(env, marker.envKeys)) {
+                // Report the harness's RUNTIME identity (e.g. canonical 'claude' →
+                // 'claude-code') via the registry's #562 bridge so the persisted
+                // runtime string can't drift.
+                harness = denormalizeRuntimeIdentity(marker.harnessId);
+                break;
+            }
         }
-        else if (firstNonEmpty(env, ["OPENCODE_SESSION_ID"])) {
-            harness = denormalizeRuntimeIdentity("opencode");
+    }
+    if (!harness) {
+        // Fall back to presence-only flags (registry `presenceEnv`). These are
+        // stamped by the harness on its OWN child processes (CODEX_SANDBOX,
+        // GEMINI_CLI=1), so they cannot mis-attribute manual CLI invocations —
+        // but they carry no session id, so sessionId stays null below.
+        for (const marker of PRESENCE_MARKERS) {
+            if (firstNonEmpty(env, marker.envKeys)) {
+                harness = denormalizeRuntimeIdentity(marker.harnessId);
+                break;
+            }
         }
     }
-    const sessionId = firstNonEmpty(env, ["AKM_SESSION_ID", "CLAUDE_SESSION_ID", "OPENCODE_SESSION_ID"]);
+    // Session id: the explicit AKM override first, then the session-id-bearing
+    // registry markers in the same precedence order as harness inference (so
+    // harness and session id agree when multiple harness env vars are present).
+    // Presence flags are deliberately excluded — their values are not sessions.
+    const sessionId = firstNonEmpty(env, ["AKM_SESSION_ID", ...SESSION_MARKERS.flatMap((m) => [...m.envKeys])]);
     return { harness, sessionId };
 }