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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/CHANGELOG.md +117 -23
  2. package/dist/akm-migrate +3 -1
  3. package/dist/assets/hints/cli-hints-full.md +3 -4
  4. package/dist/assets/hints/cli-hints-short.md +5 -5
  5. package/dist/assets/workflows/workflow-template.md +4 -3
  6. package/dist/cli/invocation.js +3 -2
  7. package/dist/cli/retired-commands.js +3 -0
  8. package/dist/cli/unknown-flags.js +226 -0
  9. package/dist/cli.js +19 -35
  10. package/dist/commands/agent/contribute-cli.js +15 -3
  11. package/dist/commands/feedback-cli.js +6 -3
  12. package/dist/commands/improve/collapse-detector.js +2 -3
  13. package/dist/commands/lint/base-linter.js +4 -16
  14. package/dist/commands/lint/index.js +13 -13
  15. package/dist/commands/log.js +6 -1
  16. package/dist/commands/migration-tool.js +4 -5
  17. package/dist/commands/observability-cli.js +1 -1
  18. package/dist/commands/proposal/repository.js +5 -5
  19. package/dist/commands/read/knowledge.js +2 -0
  20. package/dist/commands/registry-cli.js +5 -3
  21. package/dist/commands/sources/add-cli.js +6 -6
  22. package/dist/commands/sources/self-update.js +30 -7
  23. package/dist/commands/sources/source-add.js +17 -2
  24. package/dist/commands/tasks/tasks.js +8 -3
  25. package/dist/commands/workflow-cli.js +142 -119
  26. package/dist/core/adapter/adapters/akm-lint.js +17 -13
  27. package/dist/core/adapter/adapters/akm-task-adapter.js +14 -11
  28. package/dist/core/asset/akm-markdown.js +41 -8
  29. package/dist/core/asset/frontmatter.js +22 -0
  30. package/dist/core/asset/resolve-ref.js +23 -3
  31. package/dist/core/common.js +45 -2
  32. package/dist/core/config/config-schema.js +8 -0
  33. package/dist/core/config/schema/experimental.js +5 -13
  34. package/dist/core/config/schema/sources-bundles.js +11 -0
  35. package/dist/core/config/schema/workflow.js +3 -1
  36. package/dist/core/errors.js +5 -0
  37. package/dist/core/logs-db.js +2 -1
  38. package/dist/core/parse.js +4 -1
  39. package/dist/core/state/migrations.js +11 -14
  40. package/dist/core/state-db.js +4 -6
  41. package/dist/core/subprocess.js +6 -4
  42. package/dist/core/type-presentation.js +1 -1
  43. package/dist/indexer/indexer.js +16 -1
  44. package/dist/indexer/search/search-source.js +1 -1
  45. package/dist/indexer/walk/matchers.js +3 -1
  46. package/dist/integrations/agent/config.js +2 -2
  47. package/dist/integrations/agent/detect.js +49 -19
  48. package/dist/integrations/agent/profiles.js +10 -0
  49. package/dist/integrations/agent/spawn.js +1 -2
  50. package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js +7 -3
  51. package/dist/integrations/lockfile.js +11 -56
  52. package/dist/output/shapes/passthrough.js +0 -4
  53. package/dist/output/text/command-format.js +3 -3
  54. package/dist/output/text/helpers.js +1 -1
  55. package/dist/output/text/show-directives.js +4 -6
  56. package/dist/output/text/workflow-format.js +7 -62
  57. package/dist/output/text/workflow.js +1 -5
  58. package/dist/scripts/akm-migrate-node.js +58773 -0
  59. package/dist/scripts/akm-migrate.js +33976 -11391
  60. package/dist/setup/detect.js +40 -15
  61. package/dist/setup/setup.js +1 -1
  62. package/dist/sources/providers/git-stash.js +4 -2
  63. package/dist/sources/providers/website.js +5 -0
  64. package/dist/sources/snapshot-fetchers/bluesky.js +146 -0
  65. package/dist/sources/snapshot-fetchers/content-extract.js +370 -0
  66. package/dist/sources/snapshot-fetchers/fetcher-util.js +40 -0
  67. package/dist/sources/snapshot-fetchers/host-guard.js +199 -0
  68. package/dist/sources/snapshot-fetchers/registry.js +10 -1
  69. package/dist/sources/snapshot-fetchers/robots.js +348 -0
  70. package/dist/sources/snapshot-fetchers/rss.js +279 -0
  71. package/dist/sources/snapshot-fetchers/secret-seam.js +42 -0
  72. package/dist/sources/snapshot-fetchers/website-ingest.js +488 -257
  73. package/dist/sources/snapshot-fetchers/x.js +193 -0
  74. package/dist/storage/engines/sqlite-migrations.js +22 -107
  75. package/dist/tasks/runner.js +19 -16
  76. package/dist/tasks/schema.js +24 -1
  77. package/dist/workflows/exec/brief.js +1 -1
  78. package/dist/workflows/exec/frozen-judge.js +28 -2
  79. package/dist/workflows/exec/native-executor.js +18 -1
  80. package/dist/workflows/exec/report.js +11 -4
  81. package/dist/workflows/exec/run-workflow.js +103 -44
  82. package/dist/workflows/exec/step-work.js +19 -18
  83. package/dist/workflows/exec/unit-dispatch.js +4 -0
  84. package/dist/workflows/exec/workflow-engine-gate.js +11 -13
  85. package/dist/workflows/ir/compile.js +2 -2
  86. package/dist/workflows/ir/freeze.js +16 -8
  87. package/dist/workflows/ir/params.js +134 -10
  88. package/dist/workflows/ir/plan-hash.js +1 -1
  89. package/dist/workflows/ir/schema.js +6 -2
  90. package/dist/workflows/renderer.js +2 -2
  91. package/dist/workflows/runtime/checkin.js +3 -3
  92. package/dist/workflows/runtime/runs.js +50 -29
  93. package/dist/workflows/validate-summary.js +30 -14
  94. package/docs/migration/release-notes/0.9.0.md +31 -4
  95. package/docs/migration/v0.8-to-v0.9.md +69 -100
  96. package/docs/reference/data-and-telemetry.md +5 -5
  97. package/package.json +6 -2
  98. package/schemas/akm-config.json +24 -0
  99. package/schemas/akm-workflow.json +1 -1
  100. package/dist/workflows/cli.js +0 -33
@@ -51,6 +51,7 @@ import { completeWorkflowStep, getNextWorkflowStep, snapshotRunForDriver, } from
51
51
  import { UNIT_STALE_MS } from "../runtime/unit-checkin.js";
52
52
  import { buildLease, resolveRunId } from "./brief.js";
53
53
  import { frozenSummaryJudge } from "./frozen-judge.js";
54
+ import { defaultUnitDispatcher } from "./native-executor.js";
54
55
  import { activeGateLoop, cascadeSkippedRouter, computeStepWorkList, finalizeExecutedStep, isRetryEligibleFailure, recoverGateFeedback, reduceEmptyStep, reduceStepOutcomes, seedJournaledRouteDecisions, selectUnitAttemptRow, stepOutputsFromEvidence, unitOutcomeFromRow, unitStillNeedsReport, } from "./step-work.js";
55
56
  /**
56
57
  * Claim time-to-live. Equal to the unit-checkin stale window
@@ -490,7 +491,9 @@ async function finalizeReportedUnit(ctx, input, written) {
490
491
  byUnit,
491
492
  gateLoop,
492
493
  priorEvidence,
493
- summaryJudge: input.summaryJudge === undefined ? frozenSummaryJudge(plan, stepPlan.gate.judge) : input.summaryJudge,
494
+ summaryJudge: input.summaryJudge === undefined
495
+ ? frozenSummaryJudge(plan, stepPlan.gate.judge, undefined, defaultUnitDispatcher)
496
+ : input.summaryJudge,
494
497
  now: nowFn,
495
498
  written: { unitId: journalId, status },
496
499
  recorded: "written",
@@ -553,7 +556,9 @@ async function finalizeReportedUnit(ctx, input, written) {
553
556
  byUnit,
554
557
  gateLoop,
555
558
  priorEvidence,
556
- summaryJudge: input.summaryJudge === undefined ? frozenSummaryJudge(plan, stepPlan.gate.judge) : input.summaryJudge,
559
+ summaryJudge: input.summaryJudge === undefined
560
+ ? frozenSummaryJudge(plan, stepPlan.gate.judge, undefined, defaultUnitDispatcher)
561
+ : input.summaryJudge,
557
562
  now: nowFn,
558
563
  written: { unitId: journalId, status },
559
564
  recorded: idempotent ? "idempotent" : "written",
@@ -957,7 +962,7 @@ async function finalizeStep(args) {
957
962
  missing: completion.missing,
958
963
  feedback: completion.feedback,
959
964
  summary: completion.feedback,
960
- }, `Step "${stepState.id}" was rejected and its ${maxLoops}-loop gate budget is exhausted. Resolve it manually (\`akm workflow complete\`/\`resume\`/\`abandon\`).`, recorded);
965
+ }, `Step "${stepState.id}" was rejected and its ${maxLoops}-loop gate budget is exhausted. Inspect the evidence, then abandon it or start a corrected workflow run.`, recorded);
961
966
  }
962
967
  // advanced — the spine moved. Settle forward over any non-dispatching steps
963
968
  // (route-only / skipped / empty fan-out / all-unresolvable) so the run never
@@ -995,7 +1000,9 @@ async function settleSpine(args) {
995
1000
  const sp = plan.steps.find((s) => s.stepId === step.id);
996
1001
  if (!sp)
997
1002
  break;
998
- const stepJudge = summaryJudge === undefined ? frozenSummaryJudge(plan, sp.gate.judge) : summaryJudge;
1003
+ const stepJudge = summaryJudge === undefined
1004
+ ? frozenSummaryJudge(plan, sp.gate.judge, undefined, defaultUnitDispatcher)
1005
+ : summaryJudge;
999
1006
  // A route-skipped target: complete it as skipped, cascading if it is itself
1000
1007
  // a router (identical to the engine loop's skip handling).
1001
1008
  const skipInfo = routeUnselected.get(step.id);
@@ -2,10 +2,9 @@
2
2
  // License, v. 2.0. If a copy of the MPL was not distributed with this
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  /**
5
- * Engine-driven workflow execution — `akm workflow run` (orchestration plan
6
- * P1, owner decision 5). akm itself walks the plan and dispatches units; the
7
- * existing `next`/`complete` loop remains for manual/agent-driven advancement
8
- * of the same runs.
5
+ * Engine-driven workflow execution — the canonical `akm workflow run`
6
+ * start/resume/execute path. akm walks the frozen plan and dispatches units;
7
+ * external drivers can operate an existing run through `brief`/`report`.
9
8
  *
10
9
  * Invariant (plan §*Never bypass the gate spine*): every step advances
11
10
  * through `completeWorkflowStep`, never by writing step rows directly, so the
@@ -46,8 +45,8 @@
46
45
  * `finally` unless a failed run retains it as forensic state; a second
47
46
  * `workflow run` on a live-leased run refuses up front,
48
47
  * and an expired lease is claimable (crash recovery). While the lease is
49
- * live, manual `workflow complete` is refused too — the engine owns the
50
- * spine while driving (enforced inside `completeWorkflowStep`).
48
+ * live, any competing spine advance is refused — the engine owns the run while
49
+ * driving (enforced inside `completeWorkflowStep`).
51
50
  *
52
51
  * Process-lifecycle contract (owner finding 4 — no leaked handles): the SDK
53
52
  * dispatch path caches `opencode serve` CHILD PROCESSES in a per-env registry
@@ -69,17 +68,51 @@ import { assertRunParamsSatisfyPlan } from "../ir/params.js";
69
68
  import { computePlanHash } from "../ir/plan-hash.js";
70
69
  import { decodeWorkflowPlanV3 } from "../ir/schema.js";
71
70
  import { requireExecutableWorkflowPlan } from "../runtime/plan-classifier.js";
72
- import { completeWorkflowStep, getNextWorkflowStep } from "../runtime/runs.js";
71
+ import { completeWorkflowStep, getNextWorkflowStep, resumeWorkflowRun } from "../runtime/runs.js";
73
72
  import { GATE_EVALUATION_PHASE } from "../runtime/unit-phases.js";
74
73
  import { frozenSummaryJudge } from "./frozen-judge.js";
75
- import { executeStepPlan } from "./native-executor.js";
74
+ import { defaultUnitDispatcher, executeStepPlan, } from "./native-executor.js";
76
75
  // Shared step semantics — route evaluation + cascaded-skip bookkeeping,
77
76
  // gate-evaluation journaling, and the whole step-completion path
78
77
  // (`finalizeExecutedStep`) live in step-work.ts so the engine loop and the R3
79
78
  // brief/report driver protocol share ONE implementation (no drift).
80
79
  import { activeGateLoop, cascadeSkippedRouter, finalizeExecutedStep, recoverGateFeedback, seedJournaledRouteDecisions, } from "./step-work.js";
81
80
  export async function runWorkflowSteps(options) {
82
- const next = await getNextWorkflowStep(options.target, options.params);
81
+ let target = options.target;
82
+ let params = options.params;
83
+ let parameterFlags = options.parameterFlags;
84
+ let remainingRetries = options.maxRetries ?? 0;
85
+ let remainingSteps = options.maxSteps;
86
+ const executed = [];
87
+ for (;;) {
88
+ const result = await runWorkflowAttempt({
89
+ ...options,
90
+ target,
91
+ ...(params !== undefined ? { params } : { params: undefined }),
92
+ ...(parameterFlags !== undefined ? { parameterFlags } : { parameterFlags: undefined }),
93
+ ...(remainingSteps !== undefined ? { maxSteps: remainingSteps } : { maxSteps: undefined }),
94
+ });
95
+ executed.push(...result.executed);
96
+ const aggregate = { ...result, executed };
97
+ if (result.run.status !== "failed" || result.aborted || result.gateRejection || remainingRetries <= 0) {
98
+ return aggregate;
99
+ }
100
+ if (remainingSteps !== undefined) {
101
+ remainingSteps -= result.executed.length;
102
+ if (remainingSteps <= 0)
103
+ return aggregate;
104
+ }
105
+ await resumeWorkflowRun(result.run.id);
106
+ target = result.run.id;
107
+ params = undefined;
108
+ parameterFlags = undefined;
109
+ remainingRetries -= 1;
110
+ }
111
+ }
112
+ async function runWorkflowAttempt(options) {
113
+ const next = await getNextWorkflowStep(options.target, options.params, {
114
+ parameterFlags: options.parameterFlags,
115
+ });
83
116
  // Version/canonical/hash validation precedes every executable mutation,
84
117
  // including lease acquisition. Historical rows remain inspectable/abandonable.
85
118
  if (!next.done && !options.loadPlan) {
@@ -294,30 +327,34 @@ class LeaseHeartbeat {
294
327
  this.detachUpstream?.();
295
328
  }
296
329
  }
330
+ /**
331
+ * A terminal run is a pure no-op: do not load or integrity-check its frozen
332
+ * plan, because post-completion plan corruption cannot change finished work.
333
+ */
334
+ async function completedRunResult(runId) {
335
+ const doneState = await getNextWorkflowStep(runId);
336
+ return {
337
+ run: doneState.run,
338
+ executed: [],
339
+ ...(doneState.run.status === "completed" ? { done: true } : {}),
340
+ };
341
+ }
342
+ function workflowSummaryJudge(options, plan, stepPlan, signal) {
343
+ if (options.summaryJudge !== undefined)
344
+ return options.summaryJudge;
345
+ return frozenSummaryJudge(plan, stepPlan.gate.judge, signal, options.dispatcher ?? defaultUnitDispatcher);
346
+ }
297
347
  /** The engine loop proper — runs under the lease held by `runWorkflowSteps`. */
298
348
  async function driveRun(options, initial, leaseHolder, heartbeat) {
299
349
  let next = initial;
300
- // A terminal (completed) run is a PURE no-op. `runWorkflowSteps` already
301
- // skipped lease acquisition for a done run (`leased = !next.done`), and this
302
- // path must ALSO refuse to read the journal or load/integrity-check the
303
- // frozen plan: a run that finished cleanly, then had its `plan_json` corrupted
304
- // or tampered afterwards, must still report `done` here rather than throwing a
305
- // frozen-plan integrity error (loadFrozenPlan would). Nothing will dispatch
306
- // and the engine_lease_* columns stay exactly as they were, so return the
307
- // fresh run state immediately.
308
- if (initial.done) {
309
- const doneState = await getNextWorkflowStep(initial.run.id);
310
- return {
311
- run: doneState.run,
312
- executed: [],
313
- ...(doneState.run.status === "completed" ? { done: true } : {}),
314
- };
315
- }
350
+ if (initial.done)
351
+ return completedRunResult(initial.run.id);
316
352
  // The effective dispatch signal: the heartbeat's controller (a lost lease or
317
353
  // a caller abort aborts it) while leased, else the raw caller signal.
318
354
  const dispatchSignal = heartbeat?.signal ?? options.signal;
319
355
  const executed = [];
320
356
  let gateRejection;
357
+ let aborted = false;
321
358
  const maxSteps = options.maxSteps ?? Number.POSITIVE_INFINITY;
322
359
  // Seed the lifetime unit cap AND the budget ceilings from the journal so
323
360
  // both are truly per-RUN: a resumed or re-invoked run must not restart the
@@ -383,8 +420,10 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
383
420
  // another engine owns the spine now. A caller abort (options.signal) is a
384
421
  // graceful break, distinct from a lost lease.
385
422
  heartbeat?.assertAlive();
386
- if (options.signal?.aborted)
423
+ if (options.signal?.aborted) {
424
+ aborted = true;
387
425
  break;
426
+ }
388
427
  // Renew the run lease between steps (a fresh 90s window per iteration).
389
428
  // Losing it (expired mid-step + claimed by another engine) throws — the
390
429
  // new owner drives the spine now.
@@ -392,8 +431,8 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
392
431
  const step = next.step;
393
432
  const stepPlan = plan.steps.find((s) => s.stepId === step.id);
394
433
  if (!stepPlan) {
395
- throw new UsageError(`Step "${step.id}" of run ${next.run.id} is not present in the current workflow asset (${next.run.workflowRef}). ` +
396
- `The source file changed since the run started — advance this step manually with \`akm workflow complete\`.`);
434
+ throw new UsageError(`Step "${step.id}" of run ${next.run.id} is not present in its frozen workflow plan (${next.run.workflowRef}). ` +
435
+ "The run journal is inconsistent; abandon this run and start a new one.");
397
436
  }
398
437
  // A branch target no completed router selected → auto-skip, no dispatch.
399
438
  const skipInfo = routeUnselected.get(step.id);
@@ -509,6 +548,11 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
509
548
  unitsDispatched = result.unitsDispatched;
510
549
  if (result.tokensUsed !== undefined)
511
550
  tokensUsed = result.tokensUsed;
551
+ if (options.signal?.aborted) {
552
+ aborted = true;
553
+ stopEngine = true;
554
+ break;
555
+ }
512
556
  executed.push({
513
557
  stepId: step.id,
514
558
  ok: result.ok,
@@ -524,22 +568,36 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
524
568
  // the spine identically. The engine owns only the loop control the result
525
569
  // maps onto (retry re-executes; advanced moves on; failure/exhaustion
526
570
  // stops this invocation).
527
- const finalize = await finalizeExecutedStep({
528
- runId: next.run.id,
529
- workflowRef: next.run.workflowRef,
530
- stepId: step.id,
531
- stepPlan,
532
- completionCriteria: stepPlan.gate.criteria,
533
- gateLoop,
534
- loopsRemaining: gateLoop < maxLoops,
535
- result,
536
- priorEvidence: evidence,
537
- params: next.run.params ?? {},
538
- routeSelected,
539
- routeUnselected,
540
- summaryJudge: options.summaryJudge === undefined ? frozenSummaryJudge(plan, stepPlan.gate.judge) : options.summaryJudge,
541
- leaseHolder,
542
- });
571
+ let finalize;
572
+ try {
573
+ finalize = await finalizeExecutedStep({
574
+ runId: next.run.id,
575
+ workflowRef: next.run.workflowRef,
576
+ stepId: step.id,
577
+ stepPlan,
578
+ completionCriteria: stepPlan.gate.criteria,
579
+ gateLoop,
580
+ loopsRemaining: gateLoop < maxLoops,
581
+ result,
582
+ priorEvidence: evidence,
583
+ params: next.run.params ?? {},
584
+ routeSelected,
585
+ routeUnselected,
586
+ summaryJudge: workflowSummaryJudge(options, plan, stepPlan, dispatchSignal),
587
+ signal: options.signal,
588
+ leaseHolder,
589
+ });
590
+ }
591
+ catch (error) {
592
+ heartbeat?.assertAlive();
593
+ if (options.signal?.aborted) {
594
+ aborted = true;
595
+ stopEngine = true;
596
+ break;
597
+ }
598
+ throw error;
599
+ }
600
+ heartbeat?.assertAlive();
543
601
  if (finalize.kind === "retry") {
544
602
  // Re-execute the subgraph with the judge/validation feedback threaded
545
603
  // into unit prompts — the changed prompt changes each unit's input
@@ -579,6 +637,7 @@ async function driveRun(options, initial, leaseHolder, heartbeat) {
579
637
  executed,
580
638
  ...(finalState.run.status === "completed" ? { done: true } : {}),
581
639
  ...(gateRejection ? { gateRejection } : {}),
640
+ ...(aborted ? { aborted: true } : {}),
582
641
  };
583
642
  }
584
643
  /**
@@ -52,11 +52,9 @@ import { completeWorkflowStep } from "../runtime/runs.js";
52
52
  import { GATE_EVALUATION_PHASE } from "../runtime/unit-phases.js";
53
53
  import { enqueueUnitWrite } from "./unit-writer.js";
54
54
  /**
55
- * Default per-unit timeout. Deliberately NOT the 60 s agent default
56
- * (`DEFAULT_AGENT_TIMEOUT_MS`) — workflow units routinely run real coding
57
- * tasks on slow local models; 10 minutes matches the LLM-path default
58
- * (`tryLlmFeature`). A unit's `timeout` declaration overrides this; `none`
59
- * disables.
55
+ * Default per-unit timeout for workflow units. A unit's `timeout` declaration
56
+ * overrides this; `none` disables it. Direct agent dispatch has no timeout by
57
+ * default, while workflow units retain an independent safety ceiling.
60
58
  */
61
59
  export const DEFAULT_UNIT_TIMEOUT_MS = 600_000;
62
60
  /** How much raw unit output is retained in step evidence (full text lives on the unit row). */
@@ -759,9 +757,10 @@ function gateLoopOf(unitId, stepId) {
759
757
  /**
760
758
  * Classify a gate-evaluation row's journaled verdict, failing LOUDLY on a
761
759
  * corrupt one (reviewer #17). A NULL `result_json` is the LEGITIMATE
762
- * errored-judge / in-flight shape (`journalGateEvaluationFinish` writes null for
763
- * an errored judge, and a `running` row has no verdict yet) and classifies as
764
- * `empty`. But a PRESENT `result_json` that does not parse as JSON, or parses to
760
+ * completion-error / in-flight shape (`journalGateEvaluationFinish` writes null
761
+ * if completion itself throws after judge invocation, and a `running` row has no
762
+ * verdict yet) and classifies as `empty`. But a PRESENT `result_json` that does
763
+ * not parse as JSON, or parses to
765
764
  * anything other than an object with a boolean `complete` field, is corruption —
766
765
  * a truncated or hand-edited row — and MUST NOT be silently treated as absent
767
766
  * (which would reset an active step's gate loop to 1 and re-dispatch work whose
@@ -809,7 +808,7 @@ export async function journalGateEvaluationStart(gate) {
809
808
  // Marks the row as a judge call, NOT a dispatch: the budget/lifetime
810
809
  // seed in `driveRun` skips these so resume accounting matches live.
811
810
  phase: GATE_EVALUATION_PHASE,
812
- runner: "llm",
811
+ runner: gate.runner,
813
812
  engine: gate.invocation.engine,
814
813
  model: gate.invocation.model,
815
814
  inputHash: gate.inputHash,
@@ -825,14 +824,14 @@ export async function journalGateEvaluationStart(gate) {
825
824
  * Finish the gate-evaluation unit row with the verdict as observed from the
826
825
  * completion outcome: a rejection journals `{ complete: false, missing,
827
826
  * feedback }`; a pass journals `{ complete: true, missing: [] }`; a judge that
828
- * threw journals a failed row with a NULL verdict and validation is skipped.
827
+ * threw journals a failed row with the synthesized fail-closed rejection.
829
828
  */
830
829
  export async function journalGateEvaluationFinish(gate, errored, rejection) {
831
830
  const unitId = gateUnitId(gate.stepId, gate.loop);
832
- const verdict = errored
833
- ? null
834
- : rejection
835
- ? { complete: false, missing: rejection.missing, feedback: rejection.feedback }
831
+ const verdict = rejection
832
+ ? { complete: false, missing: rejection.missing, feedback: rejection.feedback }
833
+ : errored
834
+ ? null
836
835
  : { complete: true, missing: [] };
837
836
  const status = errored ? "failed" : "completed";
838
837
  await enqueueUnitWrite(() => withWorkflowRunsRepo((repo) => repo.finishUnit({
@@ -1014,7 +1013,7 @@ export function seedJournaledRouteDecisions(plan, state, routeSelected, routeUns
1014
1013
  if (selected === undefined) {
1015
1014
  throw new UsageError(`Workflow run ${state.run.id} has a completed route step "${stepPlan.stepId}" with no journaled route ` +
1016
1015
  `decision, and the decision cannot be re-derived from the journaled evidence. Refusing to guess which ` +
1017
- `branch was selected — advance the remaining steps manually with \`akm workflow complete\`.`);
1016
+ `branch was selected. The run journal is inconsistent; abandon this run and start a new one.`);
1018
1017
  }
1019
1018
  applyRouteDecision(stepPlan.route, stepPlan.stepId, selected, routeSelected, routeUnselected);
1020
1019
  }
@@ -1090,9 +1089,9 @@ export async function finalizeExecutedStep(input) {
1090
1089
  const summary = stepPlan.root && completionCriteria.length > 0
1091
1090
  ? buildArtifactSummary(stepId, result.units, result.evidence)
1092
1091
  : (summaryOverride ?? result.summary);
1093
- // Journal engine-driven judge calls as unit rows (they are LLM calls). The
1094
- // wrapper's `invoked` stays false when the gate is fail-open (no criteria / no
1095
- // judge) — nothing is journaled, and human approvals are never cached.
1092
+ // Journal engine-driven judge calls as unit rows. With no criteria there is
1093
+ // no judge invocation or row; a criteria-bearing plan without a judge is a
1094
+ // configuration error rather than a silent bypass.
1096
1095
  const frozenGate = innerJudge
1097
1096
  ? await withWorkflowRunsRepo((repo) => {
1098
1097
  const row = repo.getRunById(runId);
@@ -1116,6 +1115,7 @@ export async function finalizeExecutedStep(input) {
1116
1115
  stepId,
1117
1116
  loop: gateLoop,
1118
1117
  invocation: gateInvocation,
1118
+ runner: frozenGate?.engine?.kind === "agent" ? frozenGate.engine.runnerKind : "llm",
1119
1119
  inputHash: createHash("sha256")
1120
1120
  .update(canonicalJsonString({
1121
1121
  hashVersion: 3,
@@ -1153,6 +1153,7 @@ export async function finalizeExecutedStep(input) {
1153
1153
  summary,
1154
1154
  evidence: result.evidence,
1155
1155
  summaryJudge,
1156
+ ...(input.signal ? { signal: input.signal } : {}),
1156
1157
  ...lease,
1157
1158
  });
1158
1159
  }
@@ -0,0 +1,4 @@
1
+ // This Source Code Form is subject to the terms of the Mozilla Public
2
+ // License, v. 2.0. If a copy of the MPL was not distributed with this
3
+ // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
+ export {};
@@ -2,13 +2,12 @@
2
2
  // License, v. 2.0. If a copy of the MPL was not distributed with this
3
3
  // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
4
  /**
5
- * The `akm workflow` engine gate (`experimental.workflowEngine`, Q-05).
5
+ * The workflow external-driver gate (`experimental.workflowEngine`, Q-05).
6
6
  *
7
7
  * Mirrors the shape of `src/commands/improve/autonomy-gate.ts` (D8) for a
8
- * different failure mode. `akm improve`'s gated lanes have a safe downgrade —
9
- * skip the lane, keep the rest of the run going — but a workflow step either
10
- * executes or it does not: there is no partial-execution fallback to degrade
11
- * into. So this gate REFUSES outright rather than silently skipping: an
8
+ * different failure mode. The experimental external-driver protocol either
9
+ * operates or it does not: there is no partial fallback to degrade into. So
10
+ * this gate REFUSES outright rather than silently skipping: an
12
11
  * ungated call throws a classified `ConfigError` naming the exact config key,
13
12
  * which the CLI's JSON error envelope (`emitJsonError`, `src/cli/shared.ts`)
14
13
  * always routes to stderr with a non-zero exit — in every `--format`, not
@@ -19,17 +18,16 @@
19
18
  * not just a test inconvenience.)
20
19
  *
21
20
  * Gated surfaces:
22
- * - `akm workflow run` — the native step-execution engine
23
21
  * - `akm workflow brief` — the harness-neutral driver protocol (read half)
24
22
  * - `akm workflow report` — the harness-neutral driver protocol (write half)
25
23
  *
26
- * Deliberately NOT gated: authoring/linting the unified markdown format and
27
- * the manual workflow CLI contract (`start`, `next`, `complete`, `status`,
28
- * `list`, `create`, `resume`, `abandon`) remain stable per STABILITY.md.
24
+ * Deliberately NOT gated: canonical native execution (`workflow run`),
25
+ * authoring/linting, and run inspection/recovery (`status`, `list`, `create`,
26
+ * `resume`, `abandon`) remain stable per STABILITY.md.
29
27
  */
30
28
  import { ConfigError } from "../../core/errors.js";
31
29
  /**
32
- * The config key an operator sets to enable the workflow engine.
30
+ * The config key an operator sets to enable the external-driver protocol.
33
31
  *
34
32
  * Named rather than inlined because it is user-facing text: it goes into the
35
33
  * thrown error's message and `akm task doctor`, and those must name the same
@@ -37,7 +35,7 @@ import { ConfigError } from "../../core/errors.js";
37
35
  */
38
36
  export const WORKFLOW_ENGINE_CONFIG_KEY = "experimental.workflowEngine";
39
37
  /**
40
- * True only when the user has explicitly opted into the workflow engine.
38
+ * True only when the user has explicitly opted into the external driver.
41
39
  * Absent, an absent `experimental` section, and an explicit `false` all read
42
40
  * as off — the engine is never enabled by inference.
43
41
  */
@@ -52,8 +50,8 @@ export function workflowEngineGateMessage(surface) {
52
50
  /**
53
51
  * Refuse a gated workflow-engine surface unless the opt-in is set.
54
52
  *
55
- * `surface` is the human name of the subcommand/action being refused (e.g.
56
- * `"run"`, `"brief"`, `"create <name>.yaml"`) — it is folded into the thrown
53
+ * `surface` is the human name of the subcommand being refused (`"brief"` or
54
+ * `"report"`) — it is folded into the thrown
57
55
  * error's message so the refusal names both the surface and the exact config
58
56
  * key that would enable it. The throw alone is the whole mechanism: every
59
57
  * command defined with `defineJsonCommand` routes an uncaught throw through
@@ -92,7 +92,7 @@ function compileStep(step, defaults) {
92
92
  stepId: step.id,
93
93
  // The body `### gate` rubric is carried through as the ONE criterion string
94
94
  // — the judge receives the whole section byte-exact (spec §2.4). A step
95
- // with no rubric has no gate at all (fail-open, criteria: []).
95
+ // with no rubric needs no verification (criteria: []).
96
96
  criteria: step.gateRubric?.text.trim() ? [step.gateRubric.text] : [],
97
97
  ...(step.gate?.maxLoops !== undefined ? { maxLoops: step.gate.maxLoops } : {}),
98
98
  };
@@ -200,7 +200,7 @@ function checkInputReference(text, index, check) {
200
200
  /**
201
201
  * Collect the document's non-fatal WARNINGS — advisories that never fail
202
202
  * compilation, never change the frozen plan or its hash, and are surfaced by
203
- * `workflow validate` (human + JSON) and as `warn()` lines at `workflow start`.
203
+ * lint output (human + JSON) and as `warn()` lines at `workflow run`.
204
204
  *
205
205
  * A. A unit/map step with NO step-level `output:` schema carries its units'
206
206
  * raw results as an untyped artifact — permitted, but worth flagging.
@@ -25,7 +25,13 @@ export function compileResolveFreezeWorkflow(asset, config) {
25
25
  const layers = [...(documentDefaults ? [documentDefaults] : []), ...(unit ? [unit] : [])];
26
26
  const name = selectedEngine(config, layers);
27
27
  if (!name)
28
- throw new ConfigError("No workflow engine is selected. Set defaults.engine or workflow defaults.engine.", "INVALID_CONFIG_FILE");
28
+ throw new ConfigError("No workflow engine is selected. Set defaults.engine or workflow defaults.engine.", "INVALID_CONFIG_FILE",
29
+ // Reachable from a clean install whenever setup detected no agent CLI —
30
+ // the message above names the KEY but not how to fill it, which is the
31
+ // whole question at that point.
32
+ "Run `akm setup` to detect an installed agent, or set one explicitly: " +
33
+ '`akm config set engines.claude \'{"kind":"agent","platform":"claude"}\'` ' +
34
+ "then `akm config set defaults.engine claude`.");
29
35
  const engine = engineDefinition(config, name);
30
36
  addSnapshot(config, name, engines);
31
37
  const model = exactModel(config, name, engine, layers);
@@ -217,14 +223,16 @@ function addSnapshot(config, name, target) {
217
223
  target[name] = snapshot;
218
224
  }
219
225
  function freezeGateJudge(config, engines) {
220
- const resolved = resolveLlmEngineUse(config, [], { optional: true });
221
- if (!resolved)
222
- return null;
223
- addSnapshot(config, resolved.engine, engines);
226
+ const name = config.workflow?.judgeEngine;
227
+ if (!name) {
228
+ 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");
229
+ }
230
+ const engine = engineDefinition(config, name);
231
+ addSnapshot(config, name, engines);
224
232
  return {
225
- engine: resolved.engine,
226
- model: exactModel(config, resolved.engine, engineDefinition(config, resolved.engine), []),
227
- timeoutMs: resolved.timeoutMs,
233
+ engine: name,
234
+ model: exactModel(config, name, engine, []),
235
+ timeoutMs: effectiveTimeout(config, engine, []),
228
236
  };
229
237
  }
230
238
  function frozenConcurrency(config) {