akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/tasks/run/task-history.js

@@ -0,0 +1,134 @@
+// 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/.
+/**
+ * The task_history read/write boundary: `appendHistory` (write) and
+ * `readTaskHistory` / `taskHistoryRowToResult` (read).
+ *
+ * Moved from src/tasks/runner.ts (spec docs/plans/specs/p1b-model-extraction.md
+ * §5.1, §9, runner.ts:1071-1158). `appendHistory` was module-private at head;
+ * it is exported here because every dispatch arm (run-native-task.ts,
+ * run-workflow-task.ts, run-command-task.ts), attempt-lifecycle.ts, and
+ * run-task.ts's disabled-task path all call it (spec §5.1's module split
+ * moves what was one file's internal call graph across several files).
+ *
+ * D8 result-vocabulary re-code (why, and the WRITE side's exact shape): see
+ * docs/architecture/decisions/0005-task-result-vocabulary-and-legacy-read-mapping.md.
+ * The READ side's mapping rule is a PERMANENT invariant kept here, not moved
+ * — a maintainer touching `taskHistoryRowToResult` needs it right here, and
+ * row B-51 (docs/plans/specs/p4-deletions-closeout.md) makes deleting it a
+ * review-blocking violation: it reads rows written by every previous
+ * release, forever.
+ *
+ *   A legacy row (no `targetVocab` marker — written before D8) maps:
+ *   `"prompt"` -> `{kind:"command", engine}`, `"command"` -> `{kind:"shell"}`,
+ *   `"workflow"` unchanged, anything else (including the new vocabulary's own
+ *   "shell"/"script"/"prompt" written WITHOUT a marker, which no production
+ *   writer ever does) -> `"unknown"`. The P0-pinned null fallbacks survive:
+ *   workflow `ref` falls back to `""`, the command/prompt arm's `engine`
+ *   falls back to `null`. A row carrying `targetVocab: 2` reads `target_kind`
+ *   directly in the current vocabulary — no mapping needed.
+ *
+ * A DAG leaf with respect to the rest of src/tasks/run/**: this module
+ * imports TaskRunResult/TaskRunStatus's TYPE from ./task-result but no VALUE
+ * from it, and nothing at all from ./task-log or ./attempt-lifecycle — so
+ * nothing here risks closing an import cycle with a module that itself
+ * imports appendHistory or readTaskHistory from here.
+ */
+import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { withStateDb } from "../../core/state-db.js";
+import { decodeTaskHistoryMetadata, finalizeTaskHistoryAttempt, getTaskHistory, getTaskHistoryRuns, queryTaskHistory, upsertTaskHistory, } from "../../storage/repositories/task-history-repository.js";
+/** Append (or finalize a reserved attempt into) one task_history row. */
+export function appendHistory(result, historyReserved = false) {
+    const row = {
+        task_id: result.id,
+        status: result.status,
+        started_at: result.startedAt,
+        completed_at: result.finishedAt,
+        failed_at: result.status === "failed" ? result.finishedAt : null,
+        log_path: result.log || null,
+        target_kind: result.target.kind === "unknown" ? null : result.target.kind,
+        target_ref: result.target.kind === "workflow" ? result.target.ref : null,
+        metadata_json: JSON.stringify({
+            metadataVersion: 2,
+            durationMs: result.durationMs,
+            detail: result.detail ?? null,
+            // D8 (spec §5.3): every NEW row carries the vocabulary marker.
+            targetVocab: 2,
+            ...(result.target.kind === "command" ? { engine: result.target.engine } : {}),
+        }),
+    };
+    try {
+        withStateDb((db) => {
+            if (historyReserved && finalizeTaskHistoryAttempt(db, row))
+                return;
+            upsertTaskHistory(db, row);
+        });
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        // History recording is fully best-effort and must not alter CLI output.
+    }
+}
+export function readTaskHistory(options = {}) {
+    return withStateDb((db) => {
+        if (options.limit === 0)
+            return [];
+        if (options.id) {
+            // An id-scoped query used the single-row helper, so `--limit` was silently
+            // discarded and `akm task history --id X --limit 20` always returned one
+            // run. The CLI documents --limit as "Maximum rows to return"; honour it.
+            if (options.limit !== undefined && options.limit > 0) {
+                return getTaskHistoryRuns(db, options.id, options.limit).map(taskHistoryRowToResult);
+            }
+            const row = getTaskHistory(db, options.id);
+            return row ? [taskHistoryRowToResult(row)] : [];
+        }
+        return queryTaskHistory(db, options.limit !== undefined && options.limit > 0 ? { limit: options.limit } : {}).map(taskHistoryRowToResult);
+    });
+}
+/**
+ * Convert a `TaskHistoryRow` from state.db back to a `TaskRunResult` shape
+ * that callers of `readTaskHistory()` expect.
+ *
+ * D8 read boundary (spec §5.3): branches on the decoded metadata's
+ * `targetVocab` marker — see the module header's table.
+ */
+function taskHistoryRowToResult(row) {
+    const meta = decodeTaskHistoryMetadata(row.metadata_json);
+    const marked = meta.targetVocab === 2;
+    const target = (() => {
+        switch (row.target_kind) {
+            case "workflow":
+                // PRESERVED for both vintages (incl. the null-ref fallback).
+                return { kind: "workflow", ref: row.target_ref ?? "" };
+            case "command":
+                // NEW vocabulary: a prepared command (agent/LLM) result.
+                // LEGACY vocabulary: the native shell/script arm's shared string.
+                return marked ? { kind: "command", engine: meta.engine ?? null } : { kind: "shell" };
+            case "shell":
+                // Only the NEW vocabulary ever writes this string; an unmarked
+                // "shell" row is unreachable from any production writer.
+                return marked ? { kind: "shell" } : { kind: "unknown" };
+            case "script":
+                // Only the NEW vocabulary ever writes this string; an unmarked
+                // "script" row is unreachable from any production writer.
+                return marked ? { kind: "script" } : { kind: "unknown" };
+            case "prompt":
+                // Only LEGACY rows (pre-P1b) ever wrote this string.
+                return marked ? { kind: "unknown" } : { kind: "command", engine: meta.engine ?? null };
+            default:
+                return { kind: "unknown" };
+        }
+    })();
+    return {
+        id: row.task_id,
+        status: row.status,
+        startedAt: row.started_at,
+        finishedAt: row.completed_at ?? row.failed_at ?? row.started_at,
+        durationMs: meta.durationMs,
+        log: row.log_path ?? "",
+        target,
+        ...(meta.detail ? { detail: meta.detail } : {}),
+    };
+}

package/dist/tasks/run/task-log.js

@@ -0,0 +1,179 @@
+// 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/.
+/**
+ * Task-run log persistence: log path resolution, the flat per-run log file,
+ * structured logs.db rows, and the shared redaction pass both sinks go
+ * through before either is written.
+ *
+ * Moved body-intact from src/tasks/runner.ts (spec
+ * docs/plans/specs/p1b-model-extraction.md §5.1, runner.ts:779-968).
+ *
+ * A DAG leaf with respect to the rest of src/tasks/run/**: nothing here
+ * imports ./task-result, ./task-history, or ./attempt-lifecycle, so every
+ * other run/** module can depend on this one without risking an import
+ * cycle (tests/architecture/import-cycle-ratchet.test.ts counts type-only
+ * imports as real edges too).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "../../core/config/config.js";
+import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { buildTaskRunId, insertTaskLogLines, openLogsDatabase, } from "../../core/logs-db.js";
+import { getTaskLogDir } from "../../core/paths.js";
+import { redactCredentialPatterns, redactSensitiveText } from "../../core/redaction.js";
+import { collectTaskLogSensitiveValues } from "../log-redaction.js";
+function taskLogPath(logDir, taskId, startedAtIso) {
+    const tsSlug = startedAtIso.replace(/[:.]/g, "-");
+    return path.join(logDir, taskId, `${tsSlug}.log`);
+}
+export function resolveTaskLogPath(logDir, taskId, startedAtIso) {
+    try {
+        return taskLogPath(logDir ?? getTaskLogDir(), taskId, startedAtIso);
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        return "";
+    }
+}
+/**
+ * Redact logs.db rows against the SAME contiguous text the file sink sees.
+ *
+ * The rows arrive already split on "\n" (see {@link streamLines}), but the
+ * redaction needles are whole env values — and a needle containing a newline
+ * can never match inside a single line. Scrubbing row-by-row therefore left
+ * multi-line secrets (PEM keys, multi-line service-account credentials) intact
+ * in logs.db while the flat .log was correctly scrubbed, defeating all three
+ * tiers including the explicit `redact:` opt-in.
+ *
+ * Consecutive rows sharing a stream and level are rejoined, scrubbed as one
+ * string, and re-split, so a needle spanning lines matches. Collapsing a
+ * multi-line secret into a single [REDACTED] row is the intended outcome.
+ */
+export function scrubDbLines(dbLines, scrub) {
+    const out = [];
+    for (let i = 0; i < dbLines.length;) {
+        const { stream, level } = dbLines[i];
+        let end = i;
+        while (end < dbLines.length && dbLines[end].stream === stream && dbLines[end].level === level)
+            end++;
+        const joined = dbLines
+            .slice(i, end)
+            .map((entry) => entry.line)
+            .join("\n");
+        for (const line of scrub(joined).split("\n")) {
+            if (line.length > 0)
+                out.push({ stream, level, line });
+        }
+        i = end;
+    }
+    return out;
+}
+/** Split captured pipe output into per-line logs.db rows (blank lines dropped). */
+export function streamLines(text, stream, level) {
+    return (text
+        .split("\n")
+        // Windows child output is CRLF-terminated. Splitting on "\n" alone left a
+        // trailing "\r" on every row and turned blank CRLF lines into phantom
+        // rows containing just "\r" (length 1 passes the filter below).
+        .map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line))
+        .filter((line) => line.length > 0)
+        .map((line) => ({ stream, level, line })));
+}
+/**
+ * Exact secret values to scrub from this run's persisted output (#755).
+ *
+ * Best-effort by construction: this runs on the persistence path of a run that
+ * has already finished, so a config that will not load must degrade to
+ * "pattern-based redaction only" rather than fail the run. It does NOT degrade
+ * to "log it anyway with no redaction at all" — `redactCredentialPatterns`
+ * still runs unconditionally in the caller.
+ */
+function taskLogSensitiveValues(redactNames, environment) {
+    const env = { ...process.env, ...environment };
+    try {
+        return collectTaskLogSensitiveValues({
+            env,
+            config: loadConfig(),
+            declaredNames: redactNames,
+        });
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        // No config — the name heuristic and the task's own `redact:` list still apply.
+        try {
+            return collectTaskLogSensitiveValues({ env, declaredNames: redactNames });
+        }
+        catch (fallbackError) {
+            rethrowIfTestIsolationError(fallbackError);
+            return [];
+        }
+    }
+}
+/** Scrub one piece of durable-result text against a prepared task's own secrets. */
+export function scrubTaskOutput(task, text) {
+    const patterned = redactCredentialPatterns(text);
+    const sensitive = taskLogSensitiveValues(task.redact, task.environment);
+    return sensitive.length > 0 ? redactSensitiveText(patterned, sensitive) : patterned;
+}
+/**
+ * Persist a finished run's log: the flat text file (so `log_path` in
+ * task_history keeps resolving for humans and older consumers) plus
+ * structured rows in logs.db keyed by `buildTaskRunId(taskId, startedAt)`.
+ *
+ * Both sinks are pattern-redacted (`redactCredentialPatterns`) before being
+ * written — task output is raw command/agent/LLM text that can echo a
+ * credential-bearing URL (e.g. a Discord webhook) nothing upstream expects to
+ * scrub.
+ *
+ * The DB write is best-effort, mirroring history recording: an unwritable
+ * logs.db must never fail a task run.
+ */
+export function persistRunLog(input) {
+    // Two arms, and both are needed. `redactCredentialPatterns` catches
+    // credential SHAPES nobody listed; the exact-value pass catches configured
+    // secrets whose value is shaped like nothing in particular (#755). The
+    // command target had only the first, so a scheduled command that echoed an
+    // ordinary-looking secret persisted it verbatim to both sinks. Applying the
+    // exact pass here — the one sink all three target kinds funnel through —
+    // covers every arm once rather than per-arm; prompt/workflow runs already
+    // scrub upstream, and redaction is idempotent, so the overlap is free.
+    const sensitive = taskLogSensitiveValues(input.redactNames, input.environment);
+    const scrub = (text) => sensitive.length > 0
+        ? redactSensitiveText(redactCredentialPatterns(text), sensitive)
+        : redactCredentialPatterns(text);
+    const fileText = scrub(input.fileText);
+    const dbLines = scrubDbLines(input.dbLines, scrub);
+    if (input.logPath) {
+        try {
+            // Written at the process umask. #756 pinned 0600/0700 here; that went out
+            // with the rest of akm's permission enforcement (#791) — the operator owns
+            // the mode of their own data directory, and akm neither sets nor reports
+            // on it.
+            fs.mkdirSync(path.dirname(input.logPath), { recursive: true });
+            fs.writeFileSync(input.logPath, fileText);
+        }
+        catch (error) {
+            rethrowIfTestIsolationError(error);
+            // Transitional file logging is fully best-effort.
+        }
+    }
+    try {
+        const db = openLogsDatabase();
+        try {
+            insertTaskLogLines(db, {
+                taskId: input.taskId,
+                runId: buildTaskRunId(input.taskId, input.startedAtIso),
+                ts: input.finishedAtIso,
+                lines: dbLines,
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+        // Structured logging is fully best-effort and must not alter CLI output.
+    }
+}

package/dist/tasks/run/task-result.js

@@ -0,0 +1,19 @@
+// 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/.
+/**
+ * The exit code surfaced to the OS scheduler. Mapped from {@link TaskRunStatus}
+ * so cron / launchd / schtasks see a useful return value.
+ */
+export function exitCodeForStatus(status) {
+    switch (status) {
+        case "completed":
+            return 0;
+        case "active":
+            return 0;
+        case "blocked":
+            return 1;
+        case "failed":
+            return 1;
+    }
+}

package/dist/tasks/scheduler-binding.js

@@ -12,6 +12,7 @@
 import { createHash } from "node:crypto";
 import { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
 import { UsageError } from "../core/errors.js";
+import { canonicalInputJson } from "../execution/input-contract.js";
 import { normaliseTaskConceptId } from "./task-id.js";
 export function compileTaskSchedulerBindings(input) {
     const id = normaliseTaskConceptId(input.id);
@@ -19,9 +20,20 @@ export function compileTaskSchedulerBindings(input) {
     const bundle = parseBundleRef(ref).bundle;
     if (!bundle)
         throw new Error("invariant: qualified scheduler task ref lost its bundle");
-    const invocation = Object.freeze(["task", "run", id, "--bundle", bundle, "--scheduled"]);
+    // P2b Lane B (B-N3): the invocation is compiled PER schedule entry now —
+    // each entry's own `inputs` produces its own trailing flag tail, so it can
+    // no longer be hoisted as one binding shared by every entry.
     return Object.freeze(input.schedules.map((schedule) => {
         const bindingId = schedule.ordinal === 0 ? id : digestBindingId("task", ref, schedule.ordinal);
+        const invocation = Object.freeze([
+            "task",
+            "run",
+            id,
+            "--bundle",
+            bundle,
+            "--scheduled",
+            ...schedulerInputFlagTail(schedule.inputs),
+        ]);
         return freezeBinding({
             id: bindingId,
             nativeId: schedulerNativeBindingId(bindingId),
@@ -29,11 +41,63 @@ export function compileTaskSchedulerBindings(input) {
             cron: schedule.cron,
             source: schedule.source,
             ordinal: schedule.ordinal,
-            enabled: input.enabled,
+            enabled: schedule.enabled ?? input.enabled,
             invocation,
         });
     }));
 }
+/**
+ * The canonically-sorted `--<name> <value>` flag tail for one schedule
+ * entry's `inputs` (spec §1.7 B-N3). Empty/absent `inputs` yields an empty
+ * tail — the fixed six-token invocation, byte-identical to every schedule
+ * entry before P2b (B-03).
+ *
+ * Code-review finding (scheduler-binding.ts:536): a value whose exact text
+ * begins with `-` (a negative number, or a string that just happens to
+ * start with a dash) is indistinguishable from a NEW flag in the two-token
+ * `--<name> <value>` form — `isValidSchedulerInputFlagTail`
+ * (scheduler-invocation.ts) refuses it outright, and even a looser parser
+ * would still be wrong for a non-numeric dash-leading string: the real `akm
+ * task run` flag parser (`parseTaskInputFlags`, tasks-cli.ts) only
+ * special-cases a dash-DIGIT lead, so it would silently treat `--scope
+ * -urgent` as the boolean flag `--scope` followed by an orphaned,
+ * dropped `-urgent` token. The inline `--<name>=<value>` form has no such
+ * ambiguity on EITHER side — `isValidSchedulerInputFlagTail` accepts it
+ * unconditionally, and `parseTaskInputFlags`'s own inline-`=` branch splits
+ * on the first `=` without ever inspecting the value's leading character —
+ * so it is used whenever the value's exact text would otherwise be
+ * ambiguous. Every other value keeps the existing two-token form
+ * byte-identical to before this fix (B-03/B-45).
+ */
+function schedulerInputFlagTail(inputs) {
+    if (!inputs)
+        return [];
+    const names = Object.keys(inputs).sort();
+    const tail = [];
+    for (const name of names) {
+        const text = schedulerInputFlagValueText(inputs[name]);
+        if (text.startsWith("-"))
+            tail.push(`--${name}=${text}`);
+        else
+            tail.push(`--${name}`, text);
+    }
+    return tail;
+}
+/**
+ * One input value's argv text. A scalar is its exact text — `String(value)`
+ * for a number/boolean (a `true` boolean is `"true"`, never a bare flag, so
+ * the tail round-trips through one parser), the string itself for a string.
+ * An object/array value is its `canonicalInputJson` text, which
+ * `materializeInputFlags`'s JSON-shorthand path already coerces back through
+ * the declaration.
+ */
+function schedulerInputFlagValueText(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return canonicalInputJson(value);
+}
 export function compileWorkflowSchedulerBindings(input) {
     const ref = assertQualifiedRef(input.qualifiedRef, "workflow");
     const invocation = Object.freeze(["workflow", "run", ref]);

package/dist/tasks/scheduler-invocation.js

@@ -8,6 +8,7 @@ import { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
 import { resolveStashDir } from "../core/common.js";
 import { ConfigError } from "../core/errors.js";
 import { getCacheDir, getConfigDir, getDataDir, getTaskContextDir } from "../core/paths.js";
+import { INPUT_NAME_PATTERN } from "../execution/input-contract.js";
 import { normaliseTaskConceptId } from "./task-id.js";
 export const SCHEDULED_TASK_CONTEXT_KEYS = [
     "AKM_BUNDLE_DIR",
@@ -205,12 +206,20 @@ function parsePublicSchedulerInvocation(invocation) {
                 return undefined;
             index += 2;
         }
-        if (invocation[index] !== "--scheduled" || index !== invocation.length - 1)
+        if (invocation[index] !== "--scheduled")
+            return undefined;
+        // P2b Lane B (spec §4.4, §1.7 B-N3): zero or more `--<name> <value>`
+        // schedule-supplied input flags may follow `--scheduled` — the same
+        // trailing tail `compileTaskSchedulerBindings` compiles from
+        // `schedule[i].inputs`. Absent/empty is the pre-P2b shape, byte-identical
+        // (B-03).
+        if (!isValidSchedulerInputFlagTail(invocation.slice(index + 1)))
             return undefined;
         return { invocation: [...invocation], ...(target !== undefined ? { target } : {}) };
     }
-    if (invocation[0] !== "workflow" || invocation[1] !== "run" || invocation.length !== 3)
+    if (invocation[0] !== "workflow" || invocation[1] !== "run" || invocation.length !== 3) {
         return undefined;
+    }
     const ref = invocation[2];
     if (!ref)
         return undefined;
@@ -224,6 +233,56 @@ function parsePublicSchedulerInvocation(invocation) {
         return undefined;
     }
 }
+/**
+ * Validate an OPTIONAL trailing schedule-input flag tail (spec §1.7 B-N3):
+ * empty is valid (the pre-P2b shape). Otherwise the tail is a sequence of
+ * entries, each EITHER:
+ *
+ *   - a single inline `--<name>=<value>` token (code-review finding,
+ *     scheduler-binding.ts:536 — the ONLY encoding a dash-leading value's
+ *     exact text can round-trip through, since `<value>` here is everything
+ *     after the first `=`, whatever its leading character); or
+ *   - a `(--<name>, <value>)` pair, where `<value>` is a single non-flag
+ *     token (does not start with `-`) — the pre-P2b shape.
+ *
+ * In both forms `<name>` matches {@link INPUT_NAME_PATTERN} and no name
+ * repeats. A bare flag, a repeated name, a flag-shaped value in the pair
+ * form, or a malformed token are all refused. This validates SHAPE only;
+ * the real materialization against the task's declared contract happens
+ * through the same `parseTaskInputFlags` + `materializeInputFlags` path
+ * `akm task run --<name>` already uses (B-48) — `parseTaskInputFlags`
+ * accepts both forms natively (its inline-`=` branch never inspects the
+ * value's leading character).
+ */
+function isValidSchedulerInputFlagTail(tail) {
+    if (tail.length === 0)
+        return true;
+    const seen = new Set();
+    let index = 0;
+    while (index < tail.length) {
+        const token = tail[index];
+        if (!token || !token.startsWith("--"))
+            return false;
+        const body = token.slice(2);
+        const equalsAt = body.indexOf("=");
+        if (equalsAt !== -1) {
+            const name = body.slice(0, equalsAt);
+            if (!INPUT_NAME_PATTERN.test(name) || seen.has(name))
+                return false;
+            seen.add(name);
+            index += 1;
+            continue;
+        }
+        if (!INPUT_NAME_PATTERN.test(body) || seen.has(body))
+            return false;
+        const value = tail[index + 1];
+        if (value === undefined || value.startsWith("-"))
+            return false;
+        seen.add(body);
+        index += 2;
+    }
+    return true;
+}
 function canonicalContext(input) {
     const inputKeys = Object.keys(input);
     if (inputKeys.length !== SCHEDULED_TASK_CONTEXT_KEYS.length ||
@@ -325,5 +384,6 @@ function invalidSchedulerContext() {
     return new ConfigError(`Invalid scheduler context; expected exactly ${SCHEDULED_TASK_CONTEXT_KEYS.join(", ")} as absolute paths.`, "INVALID_CONFIG_FILE");
 }
 function invalidSchedulerInvocation() {
-    return new ConfigError("Invalid scheduler invocation; expected public `task run <id> [--bundle <bundle>] --scheduled` or `workflow run <qualified-ref>` argv.", "INVALID_CONFIG_FILE");
+    return new ConfigError("Invalid scheduler invocation; expected public " +
+        "`task run <id> [--bundle <bundle>] --scheduled [--<input> <value>…]` or `workflow run <qualified-ref>` argv.", "INVALID_CONFIG_FILE");
 }