akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/workflows/runtime/runs.js

@@ -4,24 +4,28 @@
 import { randomUUID } from "node:crypto";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { canonicalizeWorkflowName } from "../../core/asset/asset-spec.js";
-import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
+import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { warn } from "../../core/warn.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
 import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
+import { frozenSummaryJudge } from "../exec/frozen-judge.js";
 import { detectSecretShapedParams } from "../exec/param-secrets.js";
 import { collectProgramWarnings } from "../ir/compile.js";
+import { compileResolveFreezeWorkflow } from "../ir/freeze.js";
 import { validateWorkflowParams } from "../ir/params.js";
 import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
+import { decodeWorkflowPlanV3, WORKFLOW_IR_VERSION } from "../ir/schema.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
 import { evaluateCheckin } from "./checkin.js";
+import { assertWorkflowSpineMatchesPlan, classifyWorkflowRunPlan, frozenStepRows, requireAbandonableWorkflowPlan, requireExecutableWorkflowPlan, } from "./plan-classifier.js";
 import { evaluateStaleUnits } from "./unit-checkin.js";
-import { compileWorkflowAssetPlan, loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
+import { loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
 /** Clip bound for a unit's `result_json` on the `--units` diagnostic surface. */
 const UNIT_DIAGNOSTIC_CLIP = 2000;
-function toUnitDiagnostic(row, stale) {
+function toUnitDiagnostic(row, stale, plannedEngine) {
     let diagnostic = null;
     if (row.result_json !== null) {
         // `result_json` is a JSON-encoded value: a bare JSON string for a free-text
@@ -55,6 +59,10 @@ function toUnitDiagnostic(row, stale) {
         staleIdleMs: stale ? (Number.isFinite(stale.idleMs) ? stale.idleMs : null) : null,
         claimHolder: row.claim_holder,
         claimExpiresAt: row.claim_expires_at,
+        engine: row.engine ?? null,
+        runtimeKind: row.engine && (row.runner === "llm" || row.runner === "agent" || row.runner === "sdk") ? row.runner : null,
+        platform: plannedEngine?.kind === "agent" ? plannedEngine.platform : null,
+        ...(!row.engine && row.runner ? { legacyRunnerSelector: row.runner } : {}),
     };
 }
 export async function startWorkflowRun(ref, params = {}, options) {
@@ -63,7 +71,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
     // persist it on the run row in the same transaction as the insert. Every
     // later invocation executes this snapshot — the asset file is never re-read
     // for an in-flight run; re-planning is an explicit new run.
-    const plan = compileWorkflowAssetPlan(asset);
+    const plan = decodeWorkflowPlanV3(compileResolveFreezeWorkflow(asset, loadConfig()).plan);
     // Non-fatal WARNINGS (redesign addendum): a YAML program's untyped-step and
     // undeclared-param advisories surface as `warn()` lines at start (stderr,
     // consistent with the repo's other author-facing warnings) without blocking
@@ -89,7 +97,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
         const now = new Date().toISOString();
         const runId = randomUUID();
         const scopeKey = getCurrentWorkflowScopeKey();
-        const currentStepId = asset.steps[0]?.id ?? null;
+        const currentStepId = plan.steps[0]?.stepId ?? null;
         const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref);
         // Capture the agent harness + session driving this run. Explicit options
         // win; otherwise fall back to best-effort environment detection. This is
@@ -128,17 +136,17 @@ export async function startWorkflowRun(ref, params = {}, options) {
                 agentSessionId,
                 checkinArmedAt: now,
             });
-            repo.insertSteps(asset.steps.map((step) => ({
+            repo.insertSteps(frozenStepRows(plan).map((step) => ({
                 runId,
-                stepId: step.id,
-                stepTitle: step.title,
+                stepId: step.stepId,
+                stepTitle: step.stepTitle,
                 instructions: step.instructions,
-                completionJson: step.completionCriteria ? JSON.stringify(step.completionCriteria) : null,
-                sequenceIndex: step.sequenceIndex ?? 0,
+                completionJson: step.completionJson,
+                sequenceIndex: step.sequenceIndex,
             })));
             // Same transaction as the insert: a run row never exists without its
             // frozen plan (rows with NULL plan_json are pre-006 legacy runs).
-            repo.setRunPlan(runId, planJson, planHash);
+            repo.setRunPlan(runId, planJson, planHash, WORKFLOW_IR_VERSION);
         });
         const result = await getWorkflowStatus(runId);
         // #13: params are declared non-secret (they are copied verbatim into every
@@ -176,7 +184,9 @@ export async function getWorkflowStatus(runId, opts) {
             // uses (`now` injected for deterministic tests) so a dead driver's claimed
             // `running` unit surfaces as stale here too, not just as raw `running`.
             const staleById = new Map(evaluateStaleUnits(rows, opts.now ?? Date.now()).map((u) => [u.unitId, u]));
-            detail.units = rows.map((row) => toUnitDiagnostic(row, staleById.get(row.unit_id)));
+            const classified = classifyWorkflowRunPlan(run);
+            const engines = classified.support === "supported" ? classified.plan.execution?.engines : undefined;
+            detail.units = rows.map((row) => toUnitDiagnostic(row, staleById.get(row.unit_id), row.engine ? engines?.[row.engine] : undefined));
         }
         return detail;
     });
@@ -207,6 +217,8 @@ export async function getNextWorkflowStep(specifier, params) {
     return withWorkflowRunsRepo(async (repo) => {
         const { run, autoStarted } = await resolveRunSpecifier(repo, specifier, params);
         const steps = readWorkflowRunSteps(repo, run.id);
+        const plan = requireExecutableWorkflowPlan(run);
+        assertWorkflowSpineMatchesPlan(plan, run, steps);
         return { ...projectNextResult(run, steps), ...(autoStarted ? { autoStarted: true } : {}) };
     });
 }
@@ -255,6 +267,8 @@ export async function snapshotRunForDriver(runId) {
     return withWorkflowRunsRepo((repo) => repo.transaction(() => {
         const run = readWorkflowRun(repo, runId);
         const steps = readWorkflowRunSteps(repo, run.id);
+        const plan = requireExecutableWorkflowPlan(run);
+        assertWorkflowSpineMatchesPlan(plan, run, steps);
         const units = repo.getUnitsForRun(run.id);
         return { next: projectNextResult(run, steps), run, units };
     }));
@@ -262,11 +276,13 @@ export async function snapshotRunForDriver(runId) {
 export async function resumeWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, runId);
+        const plan = requireExecutableWorkflowPlan(run);
+        const steps = readWorkflowRunSteps(repo, run.id);
+        assertWorkflowSpineMatchesPlan(plan, run, steps);
         if (run.status === "completed") {
             throw new UsageError(`Workflow run ${run.id} is already completed and cannot be resumed.`);
         }
         if (run.status === "active") {
-            const steps = readWorkflowRunSteps(repo, run.id);
             return buildWorkflowRunDetail(run, steps);
         }
         // blocked or failed → flip back to active and re-open the current step so
@@ -279,8 +295,8 @@ export async function resumeWorkflowRun(runId) {
             repo.markRunActive(run.id, now);
         });
         const updated = { ...run, status: "active", updated_at: now };
-        const steps = readWorkflowRunSteps(repo, run.id);
-        return buildWorkflowRunDetail(updated, steps);
+        const refreshedSteps = readWorkflowRunSteps(repo, run.id);
+        return buildWorkflowRunDetail(updated, refreshedSteps);
     });
 }
 /**
@@ -292,6 +308,11 @@ export async function resumeWorkflowRun(runId) {
 export async function abandonWorkflowRun(runId) {
     return withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, runId);
+        requireAbandonableWorkflowPlan(run);
+        const classified = classifyWorkflowRunPlan(run);
+        const existingSteps = readWorkflowRunSteps(repo, run.id);
+        if (classified.support === "supported")
+            assertWorkflowSpineMatchesPlan(classified.plan, run, existingSteps);
         if (run.status === "completed" || run.status === "failed") {
             throw new UsageError(`Workflow run ${run.id} is already ${run.status}.`);
         }
@@ -324,6 +345,9 @@ export async function completeWorkflowStep(input) {
     // the write transaction — a slow/hung LLM must never hold a db write lock.
     const preflight = await withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, input.runId);
+        const plan = requireExecutableWorkflowPlan(run);
+        const steps = readWorkflowRunSteps(repo, run.id);
+        assertWorkflowSpineMatchesPlan(plan, run, steps);
         if (run.status !== "active") {
             throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
         }
@@ -338,7 +362,10 @@ export async function completeWorkflowStep(input) {
         if (run.current_step_id !== existing.step_id) {
             throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
         }
-        return { existing };
+        const stepPlan = plan.steps.find((step) => step.stepId === input.stepId);
+        if (!stepPlan)
+            throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
+        return { existing, plan, stepPlan };
     });
     const summary = input.summary?.trim();
     // #506: completing a step requires a summary of the work done.
@@ -349,9 +376,11 @@ export async function completeWorkflowStep(input) {
     // completionCriteria via the configured LLM. Fail-open when no criteria or no
     // judge. Only a well-formed `complete: false` blocks completion.
     if (input.status === "completed" && summary) {
-        const criteria = parseJsonArray(preflight.existing.completion_json) ?? [];
-        const judge = input.summaryJudge === undefined ? buildDefaultSummaryJudge() : input.summaryJudge;
-        const verdict = await validateStepSummary({ stepTitle: preflight.existing.step_title, completionCriteria: criteria, summary }, judge ?? undefined, { required: input.requireGate === true });
+        const criteria = preflight.stepPlan.gate.criteria;
+        const judge = input.summaryJudge === undefined
+            ? frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge)
+            : input.summaryJudge;
+        const verdict = await validateStepSummary({ stepTitle: preflight.stepPlan.title, completionCriteria: criteria, summary }, judge ?? undefined, { required: input.requireGate === true });
         if (!verdict.complete) {
             // Re-arm the check-in so a subsequent stall is still nudged, but leave the
             // step pending and return corrective feedback instead of completing.
@@ -375,6 +404,9 @@ export async function completeWorkflowStep(input) {
         let refreshedSteps = [];
         repo.transaction(() => {
             const run = readWorkflowRun(repo, input.runId);
+            const plan = requireExecutableWorkflowPlan(run);
+            const spine = readWorkflowRunSteps(repo, run.id);
+            assertWorkflowSpineMatchesPlan(plan, run, spine);
             if (run.status !== "active") {
                 throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
             }
@@ -500,6 +532,7 @@ function buildWorkflowRunDetail(run, steps) {
     };
 }
 function toWorkflowRunSummary(run) {
+    const plan = classifyWorkflowRunPlan(run);
     return {
         id: run.id,
         workflowRef: run.workflow_ref,
@@ -514,6 +547,8 @@ function toWorkflowRunSummary(run) {
         params: parseJsonObject(run.params_json),
         agentHarness: run.agent_harness ?? null,
         agentSessionId: run.agent_session_id ?? null,
+        planIrVersion: plan.irVersion,
+        executionSupport: plan.support,
         // Surface the engine lease (holder id + expiry — never workflow-authored
         // content) so `workflow next`/`status` show who is driving the run.
         ...(run.engine_lease_holder && run.engine_lease_until
@@ -579,34 +614,6 @@ function deriveRunState(steps) {
         .at(-1);
     return { status: "completed", currentStepId: null, completedAt: completedAt ?? null };
 }
-/**
- * Build the default summary-validation judge from the configured LLM, or return
- * `null` when no LLM is configured (gate is then skipped — fail-open). Lazily
- * imports the client/config so the workflow engine has no hard LLM dependency.
- *
- * Exported for the engine loop (`exec/run-workflow.ts`), which wraps the judge
- * to journal engine-driven gate evaluations as unit rows (addendum R2).
- */
-export function buildDefaultSummaryJudge() {
-    let llm;
-    try {
-        const config = loadConfig();
-        llm = getDefaultLlmConfig(config);
-    }
-    catch {
-        return null;
-    }
-    if (!llm)
-        return null;
-    const resolved = llm;
-    return async ({ system, user }) => {
-        const { chatCompletion } = await import("../../llm/client.js");
-        return chatCompletion(resolved, [
-            { role: "system", content: system },
-            { role: "user", content: user },
-        ]);
-    };
-}
 function parseJsonObject(value) {
     if (!value)
         return undefined;

package/dist/workflows/runtime/workflow-asset-loader.js

@@ -12,31 +12,9 @@ import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
 import { withIndexDb } from "../../storage/repositories/index-db.js";
 import { formatWorkflowErrors } from "../authoring/authoring.js";
-import { compileWorkflowPlan, compileWorkflowProgram } from "../ir/compile.js";
 import { parseWorkflow } from "../parser.js";
 import { parseWorkflowProgram } from "../program/parser.js";
 import { isWorkflowProgramPath, projectProgramParameters, projectProgramStepDefinitions } from "../program/project.js";
-/**
- * Compile a loaded workflow asset into the plan graph that gets frozen on the
- * run row. YAML programs compile via `compileWorkflowProgram` with full
- * expression validation; markdown documents compile via `compileWorkflowPlan`
- * (linear workflows — the stable contract — produce the same linear plan as
- * today). Exactly one of `program` / `document` is set by this loader.
- */
-export function compileWorkflowAssetPlan(asset) {
-    if (asset.program) {
-        const compiled = compileWorkflowProgram(asset.program);
-        if (!compiled.ok) {
-            throw new UsageError(formatWorkflowErrors(asset.path, compiled.errors));
-        }
-        return compiled.plan;
-    }
-    if (asset.document) {
-        return compileWorkflowPlan(asset.document);
-    }
-    // Unreachable for assets produced by loadWorkflowAsset; guards hand-built ones.
-    throw new UsageError(`Workflow asset ${asset.ref} carries neither a parsed document nor a program to compile.`);
-}
 /**
  * Resolve a `workflow:<name>` ref to a fully-projected {@link WorkflowAsset}.
  *

package/dist/workflows/validator.js

@@ -1,12 +1,37 @@
 // 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/.
+/**
+ * Cross-cutting semantic checks over an assembled WorkflowDocument draft.
+ *
+ * The parser handles per-line shape checks; this module runs rules that need
+ * the whole document or the raw frontmatter at once: duplicate step IDs,
+ * step-id format, and the frontmatter key whitelist.
+ */
+import { utf8Bytes, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_STEPS } from "./resource-limits.js";
 const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated", "when_to_use"]);
 export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
     checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
     checkStepIdFormat(draft, errors);
     checkDuplicateStepIds(draft, errors);
+    checkResourceLimits(draft, errors);
+}
+function checkResourceLimits(draft, errors) {
+    if (draft.steps.length > WORKFLOW_MAX_STEPS) {
+        errors.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_STEPS} steps.` });
+    }
+    if ((draft.parameters?.length ?? 0) > WORKFLOW_MAX_PARAMS) {
+        errors.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_PARAMS} parameters.` });
+    }
+    for (const step of draft.steps) {
+        if (utf8Bytes(step.instructions.text) > WORKFLOW_MAX_INSTRUCTION_BYTES) {
+            errors.push({
+                line: step.instructions.source.start,
+                message: `Step "${step.id}" instructions exceed the 256 KiB resource limit.`,
+            });
+        }
+    }
 }
 function checkFrontmatterKeys(data, fmEndLine, errors) {
     for (const key of Object.keys(data)) {

package/docs/data-and-telemetry.md

@@ -26,7 +26,7 @@ AKM writes to these locations on your machine. All paths follow [XDG Base Direct
 
 | Path | Contents | Safe to delete? |
 |---|---|---|
-| `config.json` | Your AKM configuration: LLM endpoints, stash paths, feature flags, profiles | **No** — deleting resets all settings |
+| `config.json` | Your AKM configuration: engines, strategies, stash paths, and feature settings | **No** — deleting resets all settings |
 
 Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 
@@ -109,7 +109,7 @@ An append-only log of every mutating action you perform with AKM. Events are sto
 | `select` | `akm show` after a search returning the same ref | `ref`, `entryId` |
 | `promoted` | `akm proposal accept <id>` | `ref` |
 | `rejected` | `akm proposal reject <id>` | `ref` |
-| `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, profile |
+| `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, engine |
 | `reflect_completed` | Reflect phase produced a proposal | `ref` |
 | `improve_reflect_outcome` | Per-asset reflect result | `ref`, `ok`, `durationMs`, `reason` |
 | `propose_invoked` | `akm propose` | `ref` |

package/docs/migration/release-notes/0.6.0.md

@@ -90,7 +90,7 @@ vault | wiki | enable | disable | completions | upgrade | save | help |
 hints
 
 Full migration guides:
-- https://github.com/itlackey/akm/blob/main/docs/migration/v1.md (v1
+- https://github.com/itlackey/akm/blob/main/docs/archive/pre-1.0-migration.md (pre-1.0
   architecture refactor — read this first if you are coming from 0.5.x or
   an earlier 0.6 pre-release)
 - https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md

package/docs/migration/release-notes/0.7.0.md

@@ -13,7 +13,7 @@ grammar continue to match the v1 architecture spec
 pre-releases — the formal freeze itself happens at 1.0 GA.
 
 If you are coming from 0.6.x, the
-[v1 migration guide](../v1.md) covers the per-surface delta and is the
+[archived pre-1.0 migration plan](../../archive/pre-1.0-migration.md) covers the historical per-surface delta and is the
 canonical upgrade reference. This file is the executive summary of
 what's new in 0.7.0.
 
@@ -47,7 +47,8 @@ akm proposal reject <id> --reason "…"   # archive with reason
 Multiple proposals for the same `ref` coexist without filesystem
 collisions. Auto-accept is gated per-source via the source config
 (`autoAcceptProposals: true`); the default is off and requires a
-writable source. See v1 spec §11 and `docs/migration/v1.md`.
+writable source. See the archived pre-1.0 migration spec §11 at
+`docs/archive/pre-1.0-migration.md`.
 
 ### `akm reflect`, `akm propose`, `akm distill` — new CLI surfaces (#225, #226, #227)
 
@@ -141,7 +142,7 @@ The bench technical reference lives in
 - Earlier 0.7.x pre-release work (#220–#223) finalised the registry
   curation surface removal, classification pipeline rewrites, and
   error envelope shape that 0.7.0 ships. Operators upgrading from a
-  0.6.x baseline should read [`docs/migration/v1.md`](../v1.md) for
+  0.6.x baseline should read the [archived pre-1.0 plan](../../archive/pre-1.0-migration.md) for
   the per-surface migration recipe.
 
 ### CLI surface as of 0.7.0
@@ -257,7 +258,7 @@ akm proposal accept <id>
 
 ## Full migration guides
 
-- [v1 migration guide](../v1.md) — per-surface delta from any 0.6.x
+- [Archived pre-1.0 migration plan](../../archive/pre-1.0-migration.md) — per-surface delta from any 0.6.x
   baseline. The canonical reference for upgrading.
 - [v0.5 → v0.6](../v0.5-to-v0.6.md) — the older terminology cut and
   registry schema v3.