akm-cli 0.9.17-alpha.1 → 0.9.17-alpha.10

package/dist/workflows/ir/schema.js

@@ -1,354 +0,0 @@
-// 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/.
-import { isContainedRelativePath, isRecord } from "../../core/common.js";
-import { UsageError } from "../../core/errors.js";
-import { parseReference } from "../program/expressions.js";
-import { PROGRAM_PARAM_NAME_PATTERN, PROGRAM_RETRY_REASONS, PROGRAM_STEP_ID_PATTERN } from "../program/schema.js";
-import { jsonBytes, utf8Bytes, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_TIMEOUT_MS, } from "../resource-limits.js";
-// Shared dispatch-significant bounds now live in `../resource-limits` so the
-// parser, the published JSON Schema, and this decoder enforce identical
-// values. Re-exported here for existing importers (e.g. `commands/workflow-cli.ts`).
-export { WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_TIMEOUT_MS };
-const MAX_LIST_ITEMS = 1024;
-const MAX_STRING_LENGTH = 1_000_000;
-/** Validate the current durable execution graph. */
-export function validateWorkflowPlanStructure(input, options) {
-    if (!isRecord(input) || input.irVersion !== options.expectedVersion) {
-        fail(`irVersion must be ${options.expectedVersion}`);
-    }
-    assertJson(input);
-    const plan = input;
-    assertKeys(input, ["irVersion", "title", "params", "paramSchemas", "budget", "execution", "steps", ...(options.planExtraKeys ?? [])], "plan");
-    assertString(plan.title, "title");
-    validateParams(plan.params, plan.paramSchemas);
-    validateBudget(plan.budget);
-    if (!isRecord(plan.execution) ||
-        !Number.isInteger(plan.execution.maxConcurrency) ||
-        plan.execution.maxConcurrency < 1 ||
-        plan.execution.maxConcurrency > WORKFLOW_MAX_CONCURRENCY) {
-        fail(`execution.maxConcurrency must be an integer from 1 through ${WORKFLOW_MAX_CONCURRENCY}`);
-    }
-    assertKeys(plan.execution, ["maxConcurrency"], "execution");
-    if (!Array.isArray(plan.steps) || plan.steps.length === 0)
-        fail("steps must be a non-empty array");
-    const stepIds = new Set();
-    const nodeIds = new Set();
-    for (let index = 0; index < plan.steps.length; index++) {
-        const step = plan.steps[index];
-        if (!isRecord(step) ||
-            typeof step.stepId !== "string" ||
-            !PROGRAM_STEP_ID_PATTERN.test(step.stepId) ||
-            stepIds.has(step.stepId))
-            fail("step ids must be unique non-empty strings");
-        stepIds.add(step.stepId);
-        if (step.sequenceIndex !== index)
-            fail("step sequence indices must be contiguous and unique");
-        assertString(step.title, `step ${step.stepId} title`);
-        if (!!step.root === !!step.route)
-            fail(`step ${step.stepId} must contain exactly one of root or route`);
-        assertKeys(step, ["stepId", "title", "sequenceIndex", "root", "route", "outputSchema", "gate"], `step ${step.stepId}`);
-        if (step.outputSchema !== undefined)
-            validateSchema(step.outputSchema, `step ${step.stepId} outputSchema`);
-        if (step.root)
-            validateNode(step.root, step.stepId, nodeIds, options.unitExtraKeys ?? []);
-        if (step.route)
-            validateRoute(step.route, step.stepId);
-        validateGate(step.gate, step.stepId, nodeIds, options.gateExtraKeys ?? []);
-    }
-    const stepIndex = new Map(plan.steps.map((step, index) => [step.stepId, index]));
-    for (const [index, step] of plan.steps.entries()) {
-        for (const target of step.route
-            ? [...Object.values(step.route.when), ...(step.route.defaultStepId ? [step.route.defaultStepId] : [])]
-            : []) {
-            const targetIndex = stepIndex.get(target);
-            if (targetIndex === undefined)
-                fail(`route target ${target} does not name a step`);
-            if (targetIndex <= index)
-                fail(`route target ${target} must come after step ${step.stepId}`);
-        }
-        validateStepExpressions(step, index, stepIndex);
-    }
-}
-function validateNode(node, stepId, nodeIds, unitExtraKeys) {
-    if (!isRecord(node) ||
-        (node.kind !== "unit" && node.kind !== "map") ||
-        typeof node.id !== "string" ||
-        !node.id ||
-        nodeIds.has(node.id))
-        fail("node ids must be unique non-empty strings");
-    nodeIds.add(node.id);
-    if (node.kind === "map") {
-        assertKeys(node, ["kind", "id", "over", "template", "concurrency", "reducer", "source"], `map ${node.id}`);
-        if (typeof node.over !== "string" ||
-            !node.over ||
-            !Number.isInteger(node.concurrency) ||
-            node.concurrency < 1 ||
-            node.concurrency > WORKFLOW_MAX_CONCURRENCY ||
-            (node.reducer !== "collect" && node.reducer !== "vote"))
-            fail(`map ${node.id} is invalid`);
-        if (node.id !== `${stepId}.map`)
-            fail(`map ${node.id} does not match step ${stepId}`);
-        validateSource(node.source, `map ${node.id} source`);
-        validateNode(node.template, stepId, nodeIds, unitExtraKeys);
-        if (!isRecord(node.template) || node.template.kind !== "unit")
-            fail(`map ${node.id} template must be a unit`);
-        if (node.template.id !== `${stepId}.unit`)
-            fail(`map ${node.id} template id is invalid`);
-        return;
-    }
-    assertKeys(node, [
-        "kind",
-        "id",
-        "instructions",
-        "inputs",
-        "schema",
-        "retry",
-        "onError",
-        "env",
-        "isolation",
-        "source",
-        ...unitExtraKeys,
-    ], `unit ${node.id}`);
-    if (typeof node.instructions !== "string" ||
-        !node.instructions ||
-        (node.onError !== "fail" && node.onError !== "continue") ||
-        (node.isolation !== "none" && node.isolation !== "worktree"))
-        fail(`unit ${node.id} is invalid`);
-    if (node.id !== stepId && node.id !== `${stepId}.unit`)
-        fail(`unit ${node.id} does not belong to step ${stepId}`);
-    if (utf8Bytes(node.instructions) > WORKFLOW_MAX_INSTRUCTION_BYTES)
-        fail(`unit ${node.id} instructions exceed the 256 KiB resource limit`);
-    if (node.schema !== undefined)
-        validateSchema(node.schema, `unit ${node.id} schema`);
-    validateRetry(node.retry, node.id);
-    validateStringArray(node.env, `unit ${node.id} env`, MAX_LIST_ITEMS, true);
-    validateStringArray(node.inputs, `unit ${node.id} inputs`, Infinity, true);
-    validateSource(node.source, `unit ${node.id} source`);
-}
-/**
- * Strictly decode a frozen {@link IrExecSpec}. This is the corruption gate for
- * a persisted plan: the argv bounds, the relative-and-contained `cwd`, and the
- * timeout range are all re-checked here, because `plan_json` may have been
- * hand-edited between freeze and dispatch.
- */
-function validateExecSpec(value, label) {
-    if (!isRecord(value))
-        fail(`${label} must be an object`);
-    assertKeys(value, ["command", "cwd", "passEnv", "timeoutMs"], label);
-    validateExecEnvScope(value, label);
-    const command = value.command;
-    if (!Array.isArray(command) ||
-        command.length === 0 ||
-        !command.every((arg) => typeof arg === "string" && arg.length > 0)) {
-        fail(`${label}.command must be an argv array of non-empty strings`);
-    }
-    if (value.cwd !== undefined) {
-        if (typeof value.cwd !== "string" || value.cwd.length === 0 || !isContainedRelativePath(value.cwd)) {
-            fail(`${label}.cwd must be a relative path contained in the unit working directory`);
-        }
-    }
-    if (!(value.timeoutMs === null ||
-        (Number.isSafeInteger(value.timeoutMs) &&
-            value.timeoutMs >= 1 &&
-            value.timeoutMs <= WORKFLOW_MAX_TIMEOUT_MS))) {
-        fail(`${label}.timeoutMs must be null or an integer from 1 through ${WORKFLOW_MAX_TIMEOUT_MS}`);
-    }
-}
-/** Decode one current frozen exec spec. */
-export function decodeWorkflowExecSpec(value, label) {
-    validateExecSpec(value, label);
-    return value;
-}
-/**
- * The child's ENVIRONMENT SCOPE half of a frozen exec spec. Split out so
- * {@link validateExecSpec} keeps its shape (and the src-fn-size ratchet stays
- * shrink-only).
- *
- * `passEnv` is canonical-form-only and may only be a non-empty deduplicated
- * name list. A persisted `[]` means exactly what absence means, and admitting a
- * second spelling of the default would give the same unit two different input
- * hashes.
- */
-function validateExecEnvScope(value, label) {
-    if (value.passEnv === undefined)
-        return;
-    const passEnv = value.passEnv;
-    if (!Array.isArray(passEnv) ||
-        passEnv.length === 0 ||
-        !passEnv.every((name) => typeof name === "string" && WORKFLOW_ENV_VAR_NAME_PATTERN.test(name)) ||
-        new Set(passEnv).size !== passEnv.length) {
-        fail(`${label}.passEnv must be a non-empty list of distinct environment variable names matching ` +
-            `${WORKFLOW_ENV_VAR_NAME_PATTERN.source}`);
-    }
-}
-function validateGate(gate, stepId, nodeIds, gateExtraKeys) {
-    if (!isRecord(gate) ||
-        gate.kind !== "gate" ||
-        gate.id !== `${stepId}.gate` ||
-        gate.stepId !== stepId ||
-        !Array.isArray(gate.criteria) ||
-        gate.criteria.length > MAX_LIST_ITEMS ||
-        !gate.criteria.every((x) => typeof x === "string" && x.length > 0 && x.length <= MAX_STRING_LENGTH) ||
-        !Number.isInteger(gate.maxLoops) ||
-        gate.maxLoops < 1)
-        fail(`gate for step ${stepId} is invalid`);
-    if (nodeIds.has(gate.id))
-        fail(`gate id ${gate.id} collides with a node`);
-    assertKeys(gate, ["kind", "id", "stepId", "criteria", "maxLoops", ...gateExtraKeys], `gate ${stepId}`);
-    nodeIds.add(gate.id);
-}
-function validateRoute(route, stepId) {
-    if (!isRecord(route) ||
-        typeof route.input !== "string" ||
-        !route.input ||
-        !isRecord(route.when) ||
-        Object.keys(route.when).length === 0 ||
-        !Object.keys(route.when).every((match) => match.length > 0 && match.length <= MAX_STRING_LENGTH) ||
-        !Object.values(route.when).every((target) => typeof target === "string" && target))
-        fail(`route for step ${stepId} is invalid`);
-    assertKeys(route, ["input", "when", "defaultStepId"], `route ${stepId}`);
-    if (route.defaultStepId !== undefined && (typeof route.defaultStepId !== "string" || !route.defaultStepId))
-        fail(`route for step ${stepId} has an invalid default target`);
-}
-function assertKeys(value, allowed, label) {
-    for (const key of Object.keys(value))
-        if (!allowed.includes(key))
-            fail(`${label} contains unknown key ${key}`);
-}
-function assertJson(value) {
-    if (value === null || typeof value === "boolean")
-        return;
-    if (typeof value === "string") {
-        if (value.length > MAX_STRING_LENGTH)
-            fail("plan contains an oversized string");
-        return;
-    }
-    if (typeof value === "number") {
-        if (!Number.isFinite(value))
-            fail("plan contains a non-finite number");
-        return;
-    }
-    if (Array.isArray(value)) {
-        for (const item of value)
-            assertJson(item);
-        return;
-    }
-    if (isRecord(value)) {
-        for (const item of Object.values(value))
-            assertJson(item);
-        return;
-    }
-    fail("plan contains a non-JSON value");
-}
-function validateParams(params, schemas) {
-    validateStringArray(params, "params", Infinity, true);
-    if (params?.some((name) => !PROGRAM_PARAM_NAME_PATTERN.test(name)))
-        fail("params contains an invalid name");
-    if (schemas !== undefined) {
-        if (!isRecord(schemas))
-            fail("paramSchemas must be an object");
-        for (const [name, schema] of Object.entries(schemas)) {
-            if (!PROGRAM_PARAM_NAME_PATTERN.test(name))
-                fail(`paramSchemas.${name} is invalid`);
-            validateSchema(schema, `paramSchemas.${name}`);
-        }
-    }
-    const names = params ?? [];
-    if (schemas && (names.length !== Object.keys(schemas).length || names.some((name) => !Object.hasOwn(schemas, name))))
-        fail("params and paramSchemas must name the same parameters");
-    if (!schemas && names.length > 0) {
-        // Markdown workflows have named parameters but no schemas, which is valid.
-        return;
-    }
-}
-function validateBudget(budget) {
-    if (budget === undefined)
-        return;
-    if (!isRecord(budget))
-        fail("budget must be an object");
-    assertKeys(budget, ["maxTokens", "maxUnits"], "budget");
-    if (budget.maxTokens === undefined && budget.maxUnits === undefined)
-        fail("budget must declare a ceiling");
-    validateOptionalPositiveInteger(budget.maxTokens, "budget.maxTokens");
-    const maxUnits = budget.maxUnits;
-    if (maxUnits !== undefined && (!Number.isSafeInteger(maxUnits) || maxUnits < 1))
-        fail("budget.maxUnits must be a positive integer");
-}
-function validateRetry(retry, nodeId) {
-    if (retry === undefined)
-        return;
-    if (!isRecord(retry))
-        fail(`unit ${nodeId} retry must be an object`);
-    assertKeys(retry, ["max", "on"], `unit ${nodeId} retry`);
-    if (!Number.isSafeInteger(retry.max) || retry.max < 0)
-        fail(`unit ${nodeId} retry.max is invalid`);
-    validateStringArray(retry.on, `unit ${nodeId} retry.on`, PROGRAM_RETRY_REASONS.length, true);
-    if (retry.on === undefined ||
-        retry.on.length === 0 ||
-        retry.on.some((reason) => !PROGRAM_RETRY_REASONS.includes(reason)))
-        fail(`unit ${nodeId} retry.on is invalid`);
-}
-function validateSchema(value, label) {
-    if (!isRecord(value))
-        fail(`${label} must be an object`);
-    if (jsonBytes(value) > WORKFLOW_MAX_SCHEMA_BYTES)
-        fail(`${label} exceeds the 256 KiB resource limit`);
-}
-function validateStepExpressions(step, index, steps) {
-    const validateReference = (text, label, paramsAllowed) => {
-        const parsed = parseReference(text);
-        if (!parsed.ok)
-            fail(`${label} contains an invalid reference`);
-        if (parsed.expr.kind === "param" && !paramsAllowed)
-            fail(`${label} must reference a step output`);
-        if (parsed.expr.kind === "stepOutput") {
-            const referenced = steps.get(parsed.expr.stepId);
-            if (referenced === undefined || referenced >= index)
-                fail(`${label} references a non-earlier step`);
-        }
-    };
-    if (step.root) {
-        const unit = step.root.kind === "map" ? step.root.template : step.root;
-        if (step.root.kind === "map")
-            validateReference(step.root.over, `map ${step.root.id} over`, true);
-        for (const reference of unit.inputs ?? [])
-            validateReference(reference, `unit ${unit.id} inputs`, false);
-    }
-    if (step.route)
-        validateReference(step.route.input, `route ${step.stepId} input`, true);
-}
-function validateSource(value, label) {
-    if (value === undefined)
-        return;
-    if (!isRecord(value))
-        fail(`${label} must be an object`);
-    assertKeys(value, ["path", "start", "end"], label);
-    if (typeof value.path !== "string" ||
-        !value.path ||
-        !Number.isSafeInteger(value.start) ||
-        !Number.isSafeInteger(value.end) ||
-        value.start < 1 ||
-        value.end < value.start)
-        fail(`${label} is invalid`);
-}
-function validateStringArray(value, label, max, unique) {
-    if (value === undefined)
-        return;
-    if (!Array.isArray(value) ||
-        value.length > max ||
-        !value.every((item) => typeof item === "string" && item.length > 0 && item.length <= MAX_STRING_LENGTH) ||
-        (unique && new Set(value).size !== value.length))
-        fail(`${label} is invalid`);
-}
-function validateOptionalPositiveInteger(value, label) {
-    if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
-        fail(`${label} must be a positive safe integer`);
-}
-function assertString(value, label) {
-    if (typeof value !== "string" || value.length === 0 || value.length > MAX_STRING_LENGTH)
-        fail(`${label} must be a non-empty bounded string`);
-}
-function fail(message) {
-    throw new UsageError(`Invalid frozen workflow plan: ${message}.`);
-}

package/dist/workflows/program/schema.js

@@ -1,78 +0,0 @@
-// 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/.
-/** 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. */
-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,
-    quality_rejected: 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) — the
- * ONE id grammar for the shared source IR (workflow-format-unification, spec
- * §2.2). 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 `inputs:` 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). Re-exported from the shared input contract
- * (`src/execution/input-contract.ts`'s `INPUT_NAME_PATTERN`) so task source
- * v4's `inputs:` declarations share the exact same name pattern rather than a
- * second, hand-maintained copy (P2a, D3-N1).
- */
-export { INPUT_NAME_PATTERN as PROGRAM_PARAM_NAME_PATTERN } from "../../execution/input-contract.js";
-/**
- * The ONE structural projection of an exec spec — ONE encoding per state.
- *
- * Every layer that carries an exec forward derives from this: the compiled
- * draft, the frozen plan (which layers `timeoutMs` on top), and the summary
- * `akm workflow show` prints. Written out per layer instead, a field added to
- * {@link ProgramExec} reaches whichever copies were remembered and silently
- * vanishes from the rest — and nothing catches it, because every key here is
- * optional, so an omitted spread is not a type error. What it would cost:
- * either the frozen plan loses a field the author wrote (and the canonical
- * hash preimage stops matching the authored intent), or `show` describes
- * something other than what runs.
- *
- * The ABSENCE of both env keys is the default allowlist. The parser rejects an
- * empty `pass_env` outright, so no layer has to distinguish absent from empty.
- */
-export function projectExecCore(exec) {
-    return {
-        command: [...exec.command],
-        ...(exec.cwd ? { cwd: exec.cwd } : {}),
-        ...(exec.passEnv && exec.passEnv.length > 0 ? { passEnv: [...exec.passEnv] } : {}),
-    };
-}

package/dist/workflows/runtime/checkin.js

@@ -1,57 +0,0 @@
-// 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/.
-/**
- * Agent check-in: a no-background-thread "continue" nudge for stalled workflow
- * runs (#506).
- *
- * The design decision (the workflow-agent check-in ADR)
- * reconciles #506 (file/command-loop signal) with #501 (background thread) in
- * favour of the former. There is intentionally NO timer or resident process
- * here. Arming a check-in writes a timestamp (`checkin_armed_at`) on the run
- * row; the next time the agent polls the engine via `workflow run`/`status`,
- * {@link evaluateCheckin} is called to decide — purely from timestamps — whether
- * the run looks stalled and a strong `continue` directive should be surfaced
- * through the normal command output.
- *
- * @module workflows/checkin
- */
-/**
- * Default stall window. If a run has been active and untouched for at least
- * this long since the later of its last update and its armed timestamp, the
- * next poll surfaces a check-in directive.
- */
-export const CHECKIN_STALL_MS = 90_000;
-function parseIso(value) {
-    if (!value)
-        return null;
-    const ms = Date.parse(value);
-    return Number.isNaN(ms) ? null : ms;
-}
-/**
- * Pure check-in evaluator. Returns a `continue` directive when an *active* run
- * has been idle past the stall window, otherwise `null`. Deterministic in
- * `now`, so it is trivially unit-testable and free of timer flakiness.
- */
-export function evaluateCheckin(run, now = Date.now(), stallMs = CHECKIN_STALL_MS) {
-    if (run.status !== "active")
-        return null;
-    const updated = parseIso(run.updatedAt);
-    const armed = parseIso(run.checkinArmedAt);
-    // Never armed → no check-in (opt-in per run via startWorkflowRun).
-    if (armed === null)
-        return null;
-    const last = Math.max(updated ?? armed, armed);
-    const idleMs = now - last;
-    if (idleMs < stallMs)
-        return null;
-    return {
-        signal: "continue",
-        directive: "CONTINUE: this workflow run has stalled with no progress. Resume immediately — " +
-            "inspect its status, then call `akm workflow run` with the run id to finish the outstanding work. " +
-            "Do not stop until the run reaches a terminal state or reports a verification rejection.",
-        idleMs,
-        agentHarness: run.agentHarness ?? null,
-        agentSessionId: run.agentSessionId ?? null,
-    };
-}