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.
- package/CHANGELOG.md +117 -23
- package/dist/akm-migrate +3 -1
- package/dist/assets/hints/cli-hints-full.md +3 -4
- package/dist/assets/hints/cli-hints-short.md +5 -5
- package/dist/assets/workflows/workflow-template.md +4 -3
- package/dist/cli/invocation.js +3 -2
- package/dist/cli/retired-commands.js +3 -0
- package/dist/cli/unknown-flags.js +226 -0
- package/dist/cli.js +19 -35
- package/dist/commands/agent/contribute-cli.js +15 -3
- package/dist/commands/feedback-cli.js +6 -3
- package/dist/commands/improve/collapse-detector.js +2 -3
- package/dist/commands/lint/base-linter.js +4 -16
- package/dist/commands/lint/index.js +13 -13
- package/dist/commands/log.js +6 -1
- package/dist/commands/migration-tool.js +4 -5
- package/dist/commands/observability-cli.js +1 -1
- package/dist/commands/proposal/repository.js +5 -5
- package/dist/commands/read/knowledge.js +2 -0
- package/dist/commands/registry-cli.js +5 -3
- package/dist/commands/sources/add-cli.js +6 -6
- package/dist/commands/sources/self-update.js +30 -7
- package/dist/commands/sources/source-add.js +17 -2
- package/dist/commands/tasks/tasks.js +8 -3
- package/dist/commands/workflow-cli.js +142 -119
- package/dist/core/adapter/adapters/akm-lint.js +17 -13
- package/dist/core/adapter/adapters/akm-task-adapter.js +14 -11
- package/dist/core/asset/akm-markdown.js +41 -8
- package/dist/core/asset/frontmatter.js +22 -0
- package/dist/core/asset/resolve-ref.js +23 -3
- package/dist/core/common.js +45 -2
- package/dist/core/config/config-schema.js +8 -0
- package/dist/core/config/schema/experimental.js +5 -13
- package/dist/core/config/schema/sources-bundles.js +11 -0
- package/dist/core/config/schema/workflow.js +3 -1
- package/dist/core/errors.js +5 -0
- package/dist/core/logs-db.js +2 -1
- package/dist/core/parse.js +4 -1
- package/dist/core/state/migrations.js +11 -14
- package/dist/core/state-db.js +4 -6
- package/dist/core/subprocess.js +6 -4
- package/dist/core/type-presentation.js +1 -1
- package/dist/indexer/indexer.js +16 -1
- package/dist/indexer/search/search-source.js +1 -1
- package/dist/indexer/walk/matchers.js +3 -1
- package/dist/integrations/agent/config.js +2 -2
- package/dist/integrations/agent/detect.js +49 -19
- package/dist/integrations/agent/profiles.js +10 -0
- package/dist/integrations/agent/spawn.js +1 -2
- package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js +7 -3
- package/dist/integrations/lockfile.js +11 -56
- package/dist/output/shapes/passthrough.js +0 -4
- package/dist/output/text/command-format.js +3 -3
- package/dist/output/text/helpers.js +1 -1
- package/dist/output/text/show-directives.js +4 -6
- package/dist/output/text/workflow-format.js +7 -62
- package/dist/output/text/workflow.js +1 -5
- package/dist/scripts/akm-migrate-node.js +58773 -0
- package/dist/scripts/akm-migrate.js +33976 -11391
- package/dist/setup/detect.js +40 -15
- package/dist/setup/setup.js +1 -1
- package/dist/sources/providers/git-stash.js +4 -2
- package/dist/sources/providers/website.js +5 -0
- package/dist/sources/snapshot-fetchers/bluesky.js +146 -0
- package/dist/sources/snapshot-fetchers/content-extract.js +370 -0
- package/dist/sources/snapshot-fetchers/fetcher-util.js +40 -0
- package/dist/sources/snapshot-fetchers/host-guard.js +199 -0
- package/dist/sources/snapshot-fetchers/registry.js +10 -1
- package/dist/sources/snapshot-fetchers/robots.js +348 -0
- package/dist/sources/snapshot-fetchers/rss.js +279 -0
- package/dist/sources/snapshot-fetchers/secret-seam.js +42 -0
- package/dist/sources/snapshot-fetchers/website-ingest.js +488 -257
- package/dist/sources/snapshot-fetchers/x.js +193 -0
- package/dist/storage/engines/sqlite-migrations.js +22 -107
- package/dist/tasks/runner.js +19 -16
- package/dist/tasks/schema.js +24 -1
- package/dist/workflows/exec/brief.js +1 -1
- package/dist/workflows/exec/frozen-judge.js +28 -2
- package/dist/workflows/exec/native-executor.js +18 -1
- package/dist/workflows/exec/report.js +11 -4
- package/dist/workflows/exec/run-workflow.js +103 -44
- package/dist/workflows/exec/step-work.js +19 -18
- package/dist/workflows/exec/unit-dispatch.js +4 -0
- package/dist/workflows/exec/workflow-engine-gate.js +11 -13
- package/dist/workflows/ir/compile.js +2 -2
- package/dist/workflows/ir/freeze.js +16 -8
- package/dist/workflows/ir/params.js +134 -10
- package/dist/workflows/ir/plan-hash.js +1 -1
- package/dist/workflows/ir/schema.js +6 -2
- package/dist/workflows/renderer.js +2 -2
- package/dist/workflows/runtime/checkin.js +3 -3
- package/dist/workflows/runtime/runs.js +50 -29
- package/dist/workflows/validate-summary.js +30 -14
- package/docs/migration/release-notes/0.9.0.md +31 -4
- package/docs/migration/v0.8-to-v0.9.md +69 -100
- package/docs/reference/data-and-telemetry.md +5 -5
- package/package.json +6 -2
- package/schemas/akm-config.json +24 -0
- package/schemas/akm-workflow.json +1 -1
- package/dist/workflows/cli.js +0 -33
|
@@ -2,23 +2,147 @@
|
|
|
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
|
-
* Run-parameter validation against the frozen plan's param schemas
|
|
6
|
-
*
|
|
7
|
-
* `--
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* a pure function of the frozen plan and the supplied params — no live-asset
|
|
11
|
-
* re-read.
|
|
5
|
+
* Run-parameter validation against the frozen plan's param schemas. A workflow
|
|
6
|
+
* can declare `params.files: { type: array }`; supplying a non-array through
|
|
7
|
+
* the exact-name `--files` flag must be rejected at start rather than silently
|
|
8
|
+
* flowing into a unit prompt. The schemas are frozen into the plan, so
|
|
9
|
+
* validation is a pure function of the frozen plan and supplied params.
|
|
12
10
|
*
|
|
13
11
|
* Uses the same bounded {@link validateJsonSchemaSubset} the engine applies to
|
|
14
|
-
* unit output
|
|
15
|
-
*
|
|
16
|
-
* workflow, and programs without a `params:` block) validates trivially.
|
|
12
|
+
* unit output. Internal callers may validate partial parameter objects; the CLI
|
|
13
|
+
* separately rejects flags that do not exactly name declared parameters.
|
|
17
14
|
*
|
|
18
15
|
* Pure module: no IO, no engine imports.
|
|
19
16
|
*/
|
|
20
17
|
import { UsageError } from "../../core/errors.js";
|
|
21
18
|
import { validateJsonSchemaSubset } from "../../core/json-schema.js";
|
|
19
|
+
import { PROGRAM_PARAM_NAME_PATTERN } from "../program/schema.js";
|
|
20
|
+
/**
|
|
21
|
+
* Materialize exact-name CLI parameter flags against the plan being frozen for
|
|
22
|
+
* the run. The CLI deliberately carries raw values to this boundary so type
|
|
23
|
+
* coercion cannot race or drift from the persisted plan's schemas.
|
|
24
|
+
*/
|
|
25
|
+
export function materializeWorkflowParameterFlags(plan, flags) {
|
|
26
|
+
if (flags.length === 0)
|
|
27
|
+
return {};
|
|
28
|
+
const declared = new Set(plan.params ?? Object.keys(plan.paramSchemas ?? {}));
|
|
29
|
+
const grouped = new Map();
|
|
30
|
+
for (const flag of flags) {
|
|
31
|
+
if (!PROGRAM_PARAM_NAME_PATTERN.test(flag.name) || !declared.has(flag.name)) {
|
|
32
|
+
const available = [...declared]
|
|
33
|
+
.sort()
|
|
34
|
+
.map((name) => `--${name}`)
|
|
35
|
+
.join(", ");
|
|
36
|
+
throw new UsageError(`Unknown workflow parameter "--${flag.name}". Parameter flags must exactly match a declared workflow parameter.`, "UNKNOWN_FLAG", available ? `Declared parameters: ${available}.` : "This workflow declares no parameters.");
|
|
37
|
+
}
|
|
38
|
+
const values = grouped.get(flag.name) ?? [];
|
|
39
|
+
values.push(flag.value);
|
|
40
|
+
grouped.set(flag.name, values);
|
|
41
|
+
}
|
|
42
|
+
const entries = [];
|
|
43
|
+
for (const [name, values] of grouped) {
|
|
44
|
+
const schema = plan.paramSchemas?.[name];
|
|
45
|
+
entries.push([name, materializeFlagValues(name, values, schema)]);
|
|
46
|
+
}
|
|
47
|
+
const params = Object.fromEntries(entries);
|
|
48
|
+
const errors = validateWorkflowParams(plan, params);
|
|
49
|
+
if (errors.length > 0) {
|
|
50
|
+
throw new UsageError(`Workflow parameter flags do not satisfy the workflow's declared schemas:\n${errors.map((error) => ` - ${error}`).join("\n")}`, "INVALID_FLAG_VALUE");
|
|
51
|
+
}
|
|
52
|
+
return params;
|
|
53
|
+
}
|
|
54
|
+
function materializeFlagValues(name, values, schema) {
|
|
55
|
+
const types = schemaTypes(schema);
|
|
56
|
+
if (types.includes("array")) {
|
|
57
|
+
if (values.length === 1 && typeof values[0] === "string" && values[0].trim().startsWith("[")) {
|
|
58
|
+
const parsed = parseJsonFlag(name, values[0]);
|
|
59
|
+
if (!Array.isArray(parsed))
|
|
60
|
+
throw invalidParameter(name, "must be a JSON array");
|
|
61
|
+
return parsed;
|
|
62
|
+
}
|
|
63
|
+
const itemSchema = isRecord(schema?.items) ? schema.items : undefined;
|
|
64
|
+
return values.map((value) => coerceFlagValue(name, value, itemSchema));
|
|
65
|
+
}
|
|
66
|
+
if (values.length > 1) {
|
|
67
|
+
throw invalidParameter(name, "was provided more than once but is not declared as an array");
|
|
68
|
+
}
|
|
69
|
+
return coerceFlagValue(name, values[0], schema);
|
|
70
|
+
}
|
|
71
|
+
function coerceFlagValue(name, raw, schema) {
|
|
72
|
+
const types = schemaTypes(schema);
|
|
73
|
+
if (types.length === 0)
|
|
74
|
+
return raw;
|
|
75
|
+
if (typeof raw === "boolean") {
|
|
76
|
+
if (types.includes("boolean"))
|
|
77
|
+
return raw;
|
|
78
|
+
if (types.includes("string"))
|
|
79
|
+
return String(raw);
|
|
80
|
+
throw invalidParameter(name, `requires a value of type ${types.join(" | ")}`);
|
|
81
|
+
}
|
|
82
|
+
// A union that permits strings keeps the user's exact text. This prevents a
|
|
83
|
+
// value such as "001" from being silently converted to a number.
|
|
84
|
+
if (types.includes("string"))
|
|
85
|
+
return raw;
|
|
86
|
+
for (const type of types) {
|
|
87
|
+
switch (type) {
|
|
88
|
+
case "boolean":
|
|
89
|
+
if (raw === "true")
|
|
90
|
+
return true;
|
|
91
|
+
if (raw === "false")
|
|
92
|
+
return false;
|
|
93
|
+
break;
|
|
94
|
+
case "number": {
|
|
95
|
+
const value = Number(raw);
|
|
96
|
+
if (raw.trim() !== "" && Number.isFinite(value))
|
|
97
|
+
return value;
|
|
98
|
+
break;
|
|
99
|
+
}
|
|
100
|
+
case "integer": {
|
|
101
|
+
const value = Number(raw);
|
|
102
|
+
if (raw.trim() !== "" && Number.isSafeInteger(value))
|
|
103
|
+
return value;
|
|
104
|
+
break;
|
|
105
|
+
}
|
|
106
|
+
case "null":
|
|
107
|
+
if (raw === "null")
|
|
108
|
+
return null;
|
|
109
|
+
break;
|
|
110
|
+
case "object": {
|
|
111
|
+
const parsed = parseJsonFlag(name, raw);
|
|
112
|
+
if (isRecord(parsed))
|
|
113
|
+
return parsed;
|
|
114
|
+
break;
|
|
115
|
+
}
|
|
116
|
+
case "array": {
|
|
117
|
+
const parsed = parseJsonFlag(name, raw);
|
|
118
|
+
if (Array.isArray(parsed))
|
|
119
|
+
return parsed;
|
|
120
|
+
break;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
throw invalidParameter(name, `must be ${types.join(" | ")}; received ${JSON.stringify(raw)}`);
|
|
125
|
+
}
|
|
126
|
+
function schemaTypes(schema) {
|
|
127
|
+
const declared = schema?.type;
|
|
128
|
+
if (typeof declared === "string")
|
|
129
|
+
return [declared];
|
|
130
|
+
return Array.isArray(declared) ? declared.filter((value) => typeof value === "string") : [];
|
|
131
|
+
}
|
|
132
|
+
function parseJsonFlag(name, raw) {
|
|
133
|
+
try {
|
|
134
|
+
return JSON.parse(raw);
|
|
135
|
+
}
|
|
136
|
+
catch {
|
|
137
|
+
throw invalidParameter(name, "must contain valid JSON");
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
function invalidParameter(name, message) {
|
|
141
|
+
return new UsageError(`Workflow parameter "--${name}" ${message}.`, "INVALID_FLAG_VALUE");
|
|
142
|
+
}
|
|
143
|
+
function isRecord(value) {
|
|
144
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
145
|
+
}
|
|
22
146
|
/**
|
|
23
147
|
* Validate a run's supplied params against the plan's frozen param schemas.
|
|
24
148
|
* Returns a flat list of human-readable, path-prefixed error strings (empty =
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
/**
|
|
5
5
|
* Plan hashing for the frozen-plan contract (redesign addendum, R1).
|
|
6
6
|
*
|
|
7
|
-
* `workflow
|
|
7
|
+
* `workflow run` persists `plan_json` + `plan_hash` on the run row
|
|
8
8
|
* (migration 006); every later invocation executes that snapshot. The hash is
|
|
9
9
|
* the sha256 (hex) of the plan's CANONICAL JSON — object keys recursively
|
|
10
10
|
* sorted — so two structurally-equal plans hash identically regardless of key
|
|
@@ -110,8 +110,12 @@ export function decodeWorkflowPlanV3(input, hooks = {}) {
|
|
|
110
110
|
assertUnitEngineCompatibility(step.root, engines);
|
|
111
111
|
if (step.gate.judge) {
|
|
112
112
|
const judge = engines[step.gate.judge.engine];
|
|
113
|
-
if (!judge
|
|
114
|
-
fail(`gate ${step.gate.id}
|
|
113
|
+
if (!judge)
|
|
114
|
+
fail(`gate ${step.gate.id} references an unavailable engine`);
|
|
115
|
+
if (judge.kind === "llm" && step.gate.judge.model === null)
|
|
116
|
+
fail(`LLM gate ${step.gate.id} has no exact model`);
|
|
117
|
+
if (judge.kind === "agent" && step.gate.judge.llm !== undefined)
|
|
118
|
+
fail(`agent gate ${step.gate.id} cannot carry LLM invocation settings`);
|
|
115
119
|
}
|
|
116
120
|
}
|
|
117
121
|
return plan;
|
|
@@ -16,7 +16,7 @@ function shellQuote(value) {
|
|
|
16
16
|
return `'${value.replace(/'/g, `'\\''`)}'`;
|
|
17
17
|
}
|
|
18
18
|
export function buildWorkflowAction(ref) {
|
|
19
|
-
return `
|
|
19
|
+
return `Start or resume execution with \`akm workflow run ${shellQuote(ref)}\`.`;
|
|
20
20
|
}
|
|
21
21
|
function deriveName(ctx) {
|
|
22
22
|
const metaName = ctx.matchResult.meta?.name;
|
|
@@ -117,7 +117,7 @@ export const workflowMdRenderer = {
|
|
|
117
117
|
buildShowResponse(ctx) {
|
|
118
118
|
const name = deriveName(ctx);
|
|
119
119
|
const doc = loadDocument(ctx);
|
|
120
|
-
// WI-8.5b (display flip): the `akm workflow
|
|
120
|
+
// WI-8.5b (display flip): the `akm workflow run <ref>` action is DISPLAY
|
|
121
121
|
// output — its spelling follows the D-R5 display rule (`displayRef`). A
|
|
122
122
|
// primary/default-bundle workflow renders the SHORT conceptId
|
|
123
123
|
// (`workflows/<name>`); a named source qualifies it as
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
* reconciles #506 (file/command-loop signal) with #501 (background thread) in
|
|
10
10
|
* favour of the former. There is intentionally NO timer or resident process
|
|
11
11
|
* here. Arming a check-in writes a timestamp (`checkin_armed_at`) on the run
|
|
12
|
-
* row; the next time the agent polls the engine via `workflow
|
|
12
|
+
* row; the next time the agent polls the engine via `workflow run`/`status`,
|
|
13
13
|
* {@link evaluateCheckin} is called to decide — purely from timestamps — whether
|
|
14
14
|
* the run looks stalled and a strong `continue` directive should be surfaced
|
|
15
15
|
* through the normal command output.
|
|
@@ -48,8 +48,8 @@ export function evaluateCheckin(run, now = Date.now(), stallMs = CHECKIN_STALL_M
|
|
|
48
48
|
return {
|
|
49
49
|
signal: "continue",
|
|
50
50
|
directive: "CONTINUE: this workflow run has stalled with no progress. Resume immediately — " +
|
|
51
|
-
"
|
|
52
|
-
"
|
|
51
|
+
"inspect its status, then call `akm workflow run` with the run id to finish the outstanding work. " +
|
|
52
|
+
"Do not stop until the run reaches a terminal state or reports a verification rejection.",
|
|
53
53
|
idleMs,
|
|
54
54
|
agentHarness: run.agentHarness ?? null,
|
|
55
55
|
agentSessionId: run.agentSessionId ?? null,
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
import { randomUUID } from "node:crypto";
|
|
5
5
|
import { parseBundleRef } from "../../core/asset/asset-ref.js";
|
|
6
6
|
import { loadConfig } from "../../core/config/config.js";
|
|
7
|
-
import { NotFoundError, UsageError } from "../../core/errors.js";
|
|
7
|
+
import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
|
|
8
8
|
import { appendEvent } from "../../core/events.js";
|
|
9
9
|
import { warn } from "../../core/warn.js";
|
|
10
10
|
import { insertEventOnce } from "../../storage/repositories/events-repository.js";
|
|
@@ -14,7 +14,7 @@ import { frozenSummaryJudge } from "../exec/frozen-judge.js";
|
|
|
14
14
|
import { detectSecretShapedParams } from "../exec/param-secrets.js";
|
|
15
15
|
import { collectWorkflowWarnings } from "../ir/compile.js";
|
|
16
16
|
import { compileResolveFreezeWorkflow } from "../ir/freeze.js";
|
|
17
|
-
import { validateWorkflowParams } from "../ir/params.js";
|
|
17
|
+
import { materializeWorkflowParameterFlags, validateWorkflowParams } from "../ir/params.js";
|
|
18
18
|
import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
|
|
19
19
|
import { decodeWorkflowPlanV3, WORKFLOW_IR_VERSION } from "../ir/schema.js";
|
|
20
20
|
import { validateStepSummary } from "../validate-summary.js";
|
|
@@ -71,20 +71,26 @@ export async function startWorkflowRun(ref, params = {}, options) {
|
|
|
71
71
|
// later invocation executes this snapshot — the asset file is never re-read
|
|
72
72
|
// for an in-flight run; re-planning is an explicit new run.
|
|
73
73
|
const plan = decodeWorkflowPlanV3(compileResolveFreezeWorkflow(asset, loadConfig()).plan);
|
|
74
|
+
if (options?.parameterFlags?.length && Object.keys(params).length > 0) {
|
|
75
|
+
throw new UsageError("Workflow parameters must use either an object or per-parameter flags, not both.");
|
|
76
|
+
}
|
|
77
|
+
const effectiveParams = options?.parameterFlags?.length
|
|
78
|
+
? materializeWorkflowParameterFlags(plan, options.parameterFlags)
|
|
79
|
+
: params;
|
|
74
80
|
// Non-fatal WARNINGS: untyped-step and undeclared-param advisories surface
|
|
75
81
|
// as `warn()` lines at start (stderr, consistent with the repo's other
|
|
76
82
|
// author-facing warnings) without blocking the run.
|
|
77
83
|
for (const w of collectWorkflowWarnings(asset.document)) {
|
|
78
|
-
warn(`workflow
|
|
84
|
+
warn(`workflow run: ${asset.path}:${w.line} — ${w.message}`);
|
|
79
85
|
}
|
|
80
|
-
// Reviewer #12: validate supplied
|
|
86
|
+
// Reviewer #12: validate supplied parameters against the frozen param
|
|
81
87
|
// schemas BEFORE creating the run, so a type-mismatched param (e.g. a string
|
|
82
88
|
// for a `{ type: array }` param) is rejected with actionable errors instead
|
|
83
89
|
// of flowing silently into a unit prompt. Programs without declared param
|
|
84
90
|
// schemas (and every Markdown workflow) validate trivially.
|
|
85
|
-
const paramErrors = validateWorkflowParams(plan,
|
|
91
|
+
const paramErrors = validateWorkflowParams(plan, effectiveParams);
|
|
86
92
|
if (paramErrors.length > 0) {
|
|
87
|
-
throw new UsageError(`Cannot start ${asset.ref}: the supplied
|
|
93
|
+
throw new UsageError(`Cannot start ${asset.ref}: the supplied parameters do not satisfy the workflow's declared schemas:\n` +
|
|
88
94
|
paramErrors.map((e) => ` - ${e}`).join("\n"), "INVALID_JSON_ARGUMENT");
|
|
89
95
|
}
|
|
90
96
|
const planJson = canonicalPlanJson(plan);
|
|
@@ -105,8 +111,8 @@ export async function startWorkflowRun(ref, params = {}, options) {
|
|
|
105
111
|
// Concurrency guard (#485): if an active run already exists in this
|
|
106
112
|
// (workflow_ref, scope_key) pair, refuse to create a parallel run unless
|
|
107
113
|
// `force: true` is set. Previously every call inserted unconditionally,
|
|
108
|
-
// so two terminals
|
|
109
|
-
//
|
|
114
|
+
// so two terminals starting the same workflow could leave two runs racing.
|
|
115
|
+
// The
|
|
110
116
|
// active-alias query and all inserts now share this immediate transaction.
|
|
111
117
|
// #506: arm a file-signal check-in (a timestamp, NOT a background thread —
|
|
112
118
|
// per the workflow-agent check-in ADR) so a stalled run can be
|
|
@@ -117,7 +123,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
|
|
|
117
123
|
const existing = repo.findActiveRunForScope(workflowRefs, scopeKey);
|
|
118
124
|
if (existing) {
|
|
119
125
|
throw new UsageError(`Workflow ${asset.ref} already has an active run in this scope (id=${existing.id}, step=${existing.current_step_id ?? "—"}). ` +
|
|
120
|
-
`Use 'akm workflow
|
|
126
|
+
`Use 'akm workflow run ${asset.ref}' to resume it or 'akm workflow abandon ${existing.id}' to give up on it.`, "RESOURCE_ALREADY_EXISTS");
|
|
121
127
|
}
|
|
122
128
|
}
|
|
123
129
|
repo.insertRun({
|
|
@@ -126,7 +132,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
|
|
|
126
132
|
scopeKey,
|
|
127
133
|
workflowEntryId,
|
|
128
134
|
workflowTitle: asset.title,
|
|
129
|
-
paramsJson: JSON.stringify(
|
|
135
|
+
paramsJson: JSON.stringify(effectiveParams),
|
|
130
136
|
currentStepId,
|
|
131
137
|
createdAt: now,
|
|
132
138
|
updatedAt: now,
|
|
@@ -151,7 +157,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
|
|
|
151
157
|
// without breaking the driver protocol). Surface a loud, best-effort warning
|
|
152
158
|
// when a param LOOKS like a credential so the author moves it to an env
|
|
153
159
|
// binding. Advisory only — never blocks the start.
|
|
154
|
-
const secretWarnings = detectSecretShapedParams(
|
|
160
|
+
const secretWarnings = detectSecretShapedParams(effectiveParams);
|
|
155
161
|
if (secretWarnings.length > 0)
|
|
156
162
|
result.warnings = [...(result.warnings ?? []), ...secretWarnings];
|
|
157
163
|
// 07 P1-B: emit only the run id + status — NOT the raw workflowTitle (which
|
|
@@ -230,9 +236,9 @@ export async function listWorkflowRuns(input) {
|
|
|
230
236
|
.map(toWorkflowRunSummary),
|
|
231
237
|
}));
|
|
232
238
|
}
|
|
233
|
-
export async function getNextWorkflowStep(specifier, params) {
|
|
239
|
+
export async function getNextWorkflowStep(specifier, params, options) {
|
|
234
240
|
return withWorkflowRunsRepo(async (repo) => {
|
|
235
|
-
const { run, autoStarted } = await resolveRunSpecifier(repo, specifier, params);
|
|
241
|
+
const { run, autoStarted } = await resolveRunSpecifier(repo, specifier, params, options?.parameterFlags);
|
|
236
242
|
const steps = readWorkflowRunSteps(repo, run.id);
|
|
237
243
|
const plan = requireExecutableWorkflowPlan(run);
|
|
238
244
|
assertWorkflowSpineMatchesPlan(plan, run, steps);
|
|
@@ -387,15 +393,20 @@ export async function completeWorkflowStep(input) {
|
|
|
387
393
|
if (input.status === "completed" && !summary) {
|
|
388
394
|
throw new UsageError(`Completing step "${input.stepId}" requires a --summary describing the work done.`, "MISSING_REQUIRED_ARGUMENT");
|
|
389
395
|
}
|
|
390
|
-
// #506: validation gate —
|
|
391
|
-
//
|
|
392
|
-
// judge. Only a well-formed `complete: false` blocks completion.
|
|
396
|
+
// #506: validation gate — a criteria-bearing step must have a frozen judge
|
|
397
|
+
// and receive an affirmative verdict before it can advance.
|
|
393
398
|
if (input.status === "completed" && summary) {
|
|
394
399
|
const criteria = preflight.stepPlan.gate.criteria;
|
|
400
|
+
if (input.signal?.aborted)
|
|
401
|
+
throw interruptionReason(input.signal);
|
|
395
402
|
const judge = input.summaryJudge === undefined
|
|
396
|
-
? frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge)
|
|
403
|
+
? frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge, input.signal)
|
|
397
404
|
: input.summaryJudge;
|
|
398
|
-
|
|
405
|
+
if (criteria.length > 0 && !judge) {
|
|
406
|
+
throw new ConfigError(`Workflow run ${input.runId} has completion criteria for step "${input.stepId}" but its frozen plan has no judge. ` +
|
|
407
|
+
"Set workflow.judgeEngine, abandon this run, and create a new one with `akm workflow run <ref>`.", "INVALID_CONFIG_FILE");
|
|
408
|
+
}
|
|
409
|
+
const verdict = await validateStepSummary({ stepTitle: preflight.stepPlan.title, completionCriteria: criteria, summary }, judge ?? undefined, input.signal);
|
|
399
410
|
if (!verdict.complete) {
|
|
400
411
|
// Re-arm the check-in so a subsequent stall is still nudged, but leave the
|
|
401
412
|
// step pending and return corrective feedback instead of completing.
|
|
@@ -411,6 +422,8 @@ export async function completeWorkflowStep(input) {
|
|
|
411
422
|
};
|
|
412
423
|
}
|
|
413
424
|
}
|
|
425
|
+
if (input.signal?.aborted)
|
|
426
|
+
throw interruptionReason(input.signal);
|
|
414
427
|
return withWorkflowRunsRepo((repo) => {
|
|
415
428
|
let updatedRun;
|
|
416
429
|
let refreshedSteps = [];
|
|
@@ -436,6 +449,8 @@ export async function completeWorkflowStep(input) {
|
|
|
436
449
|
if (run.current_step_id !== existing.step_id) {
|
|
437
450
|
throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
|
|
438
451
|
}
|
|
452
|
+
if (input.signal?.aborted)
|
|
453
|
+
throw interruptionReason(input.signal);
|
|
439
454
|
const completedAt = new Date().toISOString();
|
|
440
455
|
repo.updateStepCompletion({
|
|
441
456
|
status: input.status,
|
|
@@ -485,11 +500,12 @@ export async function completeWorkflowStep(input) {
|
|
|
485
500
|
return detail;
|
|
486
501
|
});
|
|
487
502
|
}
|
|
488
|
-
async function resolveRunSpecifier(repo, specifier, params) {
|
|
503
|
+
async function resolveRunSpecifier(repo, specifier, params, parameterFlags) {
|
|
504
|
+
const hasParameters = (params && Object.keys(params).length > 0) || (parameterFlags?.length ?? 0) > 0;
|
|
489
505
|
const explicitRun = repo.getRunById(specifier);
|
|
490
506
|
if (explicitRun) {
|
|
491
|
-
if (
|
|
492
|
-
throw new UsageError(
|
|
507
|
+
if (hasParameters) {
|
|
508
|
+
throw new UsageError(`Workflow parameter flags can only be used when starting a new run, not with existing run id "${specifier}".`);
|
|
493
509
|
}
|
|
494
510
|
return { run: explicitRun, autoStarted: false };
|
|
495
511
|
}
|
|
@@ -504,8 +520,8 @@ async function resolveRunSpecifier(repo, specifier, params) {
|
|
|
504
520
|
}
|
|
505
521
|
catch (error) {
|
|
506
522
|
if (detached) {
|
|
507
|
-
if (
|
|
508
|
-
throw new UsageError(
|
|
523
|
+
if (hasParameters) {
|
|
524
|
+
throw new UsageError(`Workflow parameter flags can only be set on a new run; ${specifier} is already active.`);
|
|
509
525
|
}
|
|
510
526
|
return { run: detached, autoStarted: false };
|
|
511
527
|
}
|
|
@@ -516,14 +532,19 @@ async function resolveRunSpecifier(repo, specifier, params) {
|
|
|
516
532
|
}
|
|
517
533
|
const active = repo.getActiveRunRowForScope(await workflowRunRefSet(ref, exactRef), scopeKey);
|
|
518
534
|
if (active) {
|
|
519
|
-
if (
|
|
520
|
-
throw new UsageError(
|
|
535
|
+
if (hasParameters) {
|
|
536
|
+
throw new UsageError(`Workflow parameter flags can only be set on a new run; ${ref} is already active.`);
|
|
521
537
|
}
|
|
522
538
|
return { run: active, autoStarted: false };
|
|
523
539
|
}
|
|
524
|
-
const started = await startWorkflowRun(ref, params ?? {}
|
|
540
|
+
const started = await startWorkflowRun(ref, params ?? {}, {
|
|
541
|
+
...(parameterFlags !== undefined ? { parameterFlags } : {}),
|
|
542
|
+
});
|
|
525
543
|
return { run: readWorkflowRun(repo, started.run.id), autoStarted: true };
|
|
526
544
|
}
|
|
545
|
+
function interruptionReason(signal) {
|
|
546
|
+
return signal.reason instanceof Error ? signal.reason : new Error("Workflow run interrupted.");
|
|
547
|
+
}
|
|
527
548
|
async function canonicalizeWorkflowSpecifier(specifier) {
|
|
528
549
|
return canonicalizeWorkflowRefInput(specifier);
|
|
529
550
|
}
|
|
@@ -592,7 +613,7 @@ function readWorkflowRunSteps(repo, runId) {
|
|
|
592
613
|
}
|
|
593
614
|
function buildWorkflowRunDetail(run, steps) {
|
|
594
615
|
// Review M1: `workflow status` (and every other detail-shaped response) now
|
|
595
|
-
// evaluates the check-in, not just `workflow
|
|
616
|
+
// evaluates the check-in, not just `workflow run`. Pure timestamp check —
|
|
596
617
|
// no background thread (see checkin.ts).
|
|
597
618
|
const checkin = evaluateCheckin({
|
|
598
619
|
status: run.status,
|
|
@@ -630,7 +651,7 @@ function toWorkflowRunSummary(run) {
|
|
|
630
651
|
planIrVersion: plan.irVersion,
|
|
631
652
|
executionSupport: plan.support,
|
|
632
653
|
// Surface the engine lease (holder id + expiry — never workflow-authored
|
|
633
|
-
// content) so `workflow
|
|
654
|
+
// content) so `workflow run`/`status` show who is driving the run.
|
|
634
655
|
...(run.engine_lease_holder && run.engine_lease_until
|
|
635
656
|
? { engineLease: { holder: run.engine_lease_holder, until: run.engine_lease_until } }
|
|
636
657
|
: {}),
|
|
@@ -639,7 +660,7 @@ function toWorkflowRunSummary(run) {
|
|
|
639
660
|
/**
|
|
640
661
|
* Single-driver enforcement (R2 run lease): while a LIVE (unexpired) engine
|
|
641
662
|
* lease is held, only the holding engine may advance the gate spine. Manual
|
|
642
|
-
*
|
|
663
|
+
* A call with no `leaseHolder` — or a stale engine invocation
|
|
643
664
|
* whose lease was claimed by another — is refused with the holder + expiry.
|
|
644
665
|
* An EXPIRED lease never blocks: the engine that held it is presumed dead.
|
|
645
666
|
*/
|
|
@@ -9,10 +9,9 @@
|
|
|
9
9
|
* demonstrates each criterion is met, and returns either a pass or structured
|
|
10
10
|
* corrective feedback steering the agent on what to finish/fix.
|
|
11
11
|
*
|
|
12
|
-
* The
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
* check-in ADR).
|
|
12
|
+
* The judge call is injected so the gate is unit-testable without a live
|
|
13
|
+
* endpoint. A declared gate is fail-closed: only a well-formed affirmative
|
|
14
|
+
* verdict advances the step.
|
|
16
15
|
*
|
|
17
16
|
* @module workflows/validate-summary
|
|
18
17
|
*/
|
|
@@ -36,31 +35,45 @@ function buildUserPrompt(input) {
|
|
|
36
35
|
/**
|
|
37
36
|
* Run the summary-validation gate.
|
|
38
37
|
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
* - no judge → `{ complete: true, skipped: true }`
|
|
42
|
-
* - judge throws / returns unparseable → `{ complete: true, skipped: true }`
|
|
43
|
-
*
|
|
44
|
-
* Only a well-formed `complete: false` verdict blocks completion.
|
|
38
|
+
* No criteria skips verification. A missing, failing, or malformed judge is a
|
|
39
|
+
* rejection: declared criteria are never silently bypassed.
|
|
45
40
|
*/
|
|
46
|
-
export async function validateStepSummary(input, judge) {
|
|
41
|
+
export async function validateStepSummary(input, judge, signal) {
|
|
47
42
|
const criteria = input.completionCriteria.filter((c) => c.trim().length > 0);
|
|
48
43
|
if (criteria.length === 0) {
|
|
49
44
|
return { complete: true, missing: [], skipped: true };
|
|
50
45
|
}
|
|
51
46
|
if (!judge) {
|
|
52
|
-
return {
|
|
47
|
+
return {
|
|
48
|
+
complete: false,
|
|
49
|
+
missing: criteria,
|
|
50
|
+
feedback: "This step declares completion criteria but no verification judge is available.",
|
|
51
|
+
};
|
|
53
52
|
}
|
|
54
53
|
let raw;
|
|
55
54
|
try {
|
|
55
|
+
if (signal?.aborted)
|
|
56
|
+
throw interruptionReason(signal);
|
|
56
57
|
raw = await judge({ system: JUDGE_SYSTEM, user: buildUserPrompt({ ...input, completionCriteria: criteria }) });
|
|
58
|
+
if (signal?.aborted)
|
|
59
|
+
throw interruptionReason(signal);
|
|
57
60
|
}
|
|
58
61
|
catch {
|
|
59
|
-
|
|
62
|
+
if (signal?.aborted)
|
|
63
|
+
throw interruptionReason(signal);
|
|
64
|
+
return {
|
|
65
|
+
complete: false,
|
|
66
|
+
missing: criteria,
|
|
67
|
+
feedback: "The verification judge failed. Retry after fixing the verifier configuration or service.",
|
|
68
|
+
};
|
|
60
69
|
}
|
|
61
70
|
const parsed = parseJsonResponse(raw);
|
|
62
71
|
if (!parsed || typeof parsed.complete !== "boolean") {
|
|
63
|
-
return {
|
|
72
|
+
return {
|
|
73
|
+
complete: false,
|
|
74
|
+
missing: criteria,
|
|
75
|
+
feedback: "The verification judge returned a malformed verdict instead of the required JSON result.",
|
|
76
|
+
};
|
|
64
77
|
}
|
|
65
78
|
if (parsed.complete) {
|
|
66
79
|
return { complete: true, missing: [] };
|
|
@@ -74,3 +87,6 @@ export async function validateStepSummary(input, judge) {
|
|
|
74
87
|
"Finish the outstanding work and resubmit with a summary that addresses each criterion.";
|
|
75
88
|
return { complete: false, missing, feedback };
|
|
76
89
|
}
|
|
90
|
+
function interruptionReason(signal) {
|
|
91
|
+
return signal.reason instanceof Error ? signal.reason : new Error("Workflow verification interrupted.");
|
|
92
|
+
}
|
|
@@ -81,10 +81,37 @@ Primary public command family for 0.9.0:
|
|
|
81
81
|
|
|
82
82
|
## Release validation
|
|
83
83
|
|
|
84
|
-
Release validation
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
84
|
+
Release validation was repeated on 2026-07-31. An isolated manual pass covered
|
|
85
|
+
114 first-run, CLI, indexing, search/show, output-format, strict-flag,
|
|
86
|
+
tools-only agent classification, multi-bundle write/lint, workflow, task,
|
|
87
|
+
llm-wiki, env/secret, feedback/log, config/migration, health, upgrade, and
|
|
88
|
+
registry checks with no failures. `bun run release:check` verified the packed
|
|
89
|
+
npm installation, Node fallback and Bun launcher paths, migration and task
|
|
90
|
+
execution from published 0.8.14, the Linux standalone scheduler artifact,
|
|
91
|
+
3,003 unit tests, 5,071 integration tests, and all seven Docker install targets.
|
|
92
|
+
The gated semantic-search suite passed 9 tests; Node 24 passed all 9 fallback
|
|
93
|
+
smoke steps and 25 compatibility tests.
|
|
94
|
+
|
|
95
|
+
The post-release checklist audit added a separate 125-check deterministic pass
|
|
96
|
+
for cross-bundle identity, write fidelity, output destinations, lint/task
|
|
97
|
+
behavior, env secrecy, durable log cursors, workflow transitions, proposal
|
|
98
|
+
dry-runs, setup recovery, fresh health initialization, and source-install
|
|
99
|
+
safety. It passed 125/125 on Linux. The current branch also passed
|
|
100
|
+
`bun run check` (3,005 unit and 5,072 integration tests) and `bun run build`.
|
|
101
|
+
|
|
102
|
+
A container-isolated follow-up passed 188 destructive crash/recovery checks,
|
|
103
|
+
including real `SIGKILL` windows across proposal, workflow, and lock journals,
|
|
104
|
+
plus deterministic interruption replay across phase-free migration sentinels.
|
|
105
|
+
The container also passed `release:check --skip-docker`, the seven-image
|
|
106
|
+
Docker install matrix, 9 semantic-search tests, all 9 Node 22 smoke steps, all
|
|
107
|
+
25 Node compatibility tests, and the offline full gate (3,005 unit and 5,070
|
|
108
|
+
integration tests). This pass exposed and fixed host-scheduler and co-located
|
|
109
|
+
Node/Bun assumptions in three tests; no production behavior changed.
|
|
110
|
+
|
|
111
|
+
Live credential-backed agent/LLM calls and native macOS/Windows execution were
|
|
112
|
+
not run from this Linux host. Their deterministic paths remain covered by the
|
|
113
|
+
full unit/integration suite; release artifacts still require their normal
|
|
114
|
+
platform CI/release checks.
|
|
88
115
|
|
|
89
116
|
Required upgrade checks:
|
|
90
117
|
|