akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/commands/improve/extract-cli.js

@@ -14,12 +14,15 @@
  * Output is the AkmExtractResult JSON envelope (or an aggregated one when
  * `--auto` runs multiple harnesses).
  */
-import { defineCommand } from "citty";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import fs from "node:fs";
+import path from "node:path";
+import { getStringArg } from "../../cli/parse-args.js";
+import { defineJsonCommand, EXIT_CODES, output } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
-import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
+import { getAvailableHarnesses, getWatchTargets } from "../../integrations/session-logs/index.js";
 import { akmExtract } from "./extract.js";
-export const extractCommand = defineCommand({
+import { akmExtractWatch } from "./extract-watch.js";
+export const extractCommand = defineJsonCommand({
     meta: {
         name: "extract",
         description: "Extract durable insights from native session files (claude-code, opencode) and queue them as proposals. Replaces the legacy session-checkpoint hook.",
@@ -60,68 +63,185 @@ export const extractCommand = defineCommand({
             type: "string",
             description: "Per-session LLM timeout in ms (default 60000).",
         },
+        watch: {
+            type: "boolean",
+            description: "Watch harness session-log directories and run extract on change (debounced). Stays alive until SIGINT/SIGTERM. Falls back to the */30 cron when off.",
+            default: false,
+        },
+        "debounce-ms": {
+            type: "string",
+            description: "Debounce window in ms for --watch (default 2000).",
+        },
     },
     async run({ args }) {
-        await runWithJsonErrors(async () => {
-            const type = typeof args.type === "string" ? args.type.trim() : "";
-            const sessionId = typeof args["session-id"] === "string" ? args["session-id"].trim() : "";
-            const location = typeof args.location === "string" ? args.location.trim() : "";
-            const since = typeof args.since === "string" ? args.since.trim() : "";
-            const auto = args.auto === true;
-            const dryRun = args["dry-run"] === true;
-            const force = args.force === true;
-            const timeoutMs = typeof args["timeout-ms"] === "string" && args["timeout-ms"] !== ""
-                ? Number.parseInt(args["timeout-ms"], 10)
-                : undefined;
-            if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
-                throw new UsageError(`--timeout-ms must be a positive integer (got "${args["timeout-ms"]}").`, "INVALID_FLAG_VALUE");
-            }
-            if (auto && type) {
-                throw new UsageError("--auto and --type are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
-            }
-            if (!auto && !type) {
-                throw new UsageError("--type is required (or pass --auto to try every available harness).", "MISSING_REQUIRED_ARGUMENT");
-            }
-            const commonOptions = {
-                ...(sessionId ? { sessionId } : {}),
-                ...(location ? { location } : {}),
-                ...(since ? { since } : {}),
-                dryRun,
-                force,
-                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-            };
-            if (auto) {
-                const harnesses = getAvailableHarnesses();
-                if (harnesses.length === 0) {
-                    output("extract", {
-                        schemaVersion: 1,
-                        ok: false,
-                        shape: "extract-auto-result",
-                        warnings: ["no available harnesses found on this machine"],
-                        results: [],
-                    });
-                    return;
-                }
-                const results = [];
-                for (const h of harnesses) {
-                    const result = await akmExtract({ type: h.name, ...commonOptions });
-                    results.push(result);
-                }
-                const ok = results.every((r) => r.ok);
-                const totalProposals = results.reduce((sum, r) => sum + r.proposals.length, 0);
+        const type = getStringArg(args, "type") ?? "";
+        const sessionId = getStringArg(args, "session-id") ?? "";
+        const location = getStringArg(args, "location") ?? "";
+        const since = getStringArg(args, "since") ?? "";
+        const auto = args.auto === true;
+        const dryRun = args["dry-run"] === true;
+        const force = args.force === true;
+        const timeoutMs = typeof args["timeout-ms"] === "string" && args["timeout-ms"] !== ""
+            ? Number.parseInt(args["timeout-ms"], 10)
+            : undefined;
+        if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+            throw new UsageError(`--timeout-ms must be a positive integer (got "${args["timeout-ms"]}").`, "INVALID_FLAG_VALUE");
+        }
+        const watch = args.watch === true;
+        const debounceMs = typeof args["debounce-ms"] === "string" && args["debounce-ms"] !== ""
+            ? Number.parseInt(args["debounce-ms"], 10)
+            : 2000;
+        if (watch && (!Number.isFinite(debounceMs) || debounceMs <= 0)) {
+            throw new UsageError(`--debounce-ms must be a positive integer (got "${args["debounce-ms"]}").`, "INVALID_FLAG_VALUE");
+        }
+        if (watch) {
+            await runWatchMode({ debounceMs, dryRun, force, ...(since ? { since } : {}) });
+            return;
+        }
+        if (auto && type) {
+            throw new UsageError("--auto and --type are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
+        }
+        if (!auto && !type) {
+            throw new UsageError("--type is required (or pass --auto to try every available harness).", "MISSING_REQUIRED_ARGUMENT");
+        }
+        const commonOptions = {
+            ...(sessionId ? { sessionId } : {}),
+            ...(location ? { location } : {}),
+            ...(since ? { since } : {}),
+            dryRun,
+            force,
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        };
+        if (auto) {
+            const harnesses = getAvailableHarnesses();
+            if (harnesses.length === 0) {
                 output("extract", {
                     schemaVersion: 1,
-                    ok,
+                    ok: false,
                     shape: "extract-auto-result",
-                    dryRun,
-                    harnessesProcessed: results.length,
-                    totalProposals,
-                    results,
+                    warnings: ["no available harnesses found on this machine"],
+                    results: [],
                 });
                 return;
             }
-            const result = await akmExtract({ type, ...commonOptions });
-            output("extract", result);
-        });
+            const results = [];
+            for (const h of harnesses) {
+                const result = await akmExtract({ type: h.name, ...commonOptions });
+                results.push(result);
+            }
+            const ok = results.every((r) => r.ok);
+            const totalProposals = results.reduce((sum, r) => sum + r.proposals.length, 0);
+            output("extract", {
+                schemaVersion: 1,
+                ok,
+                shape: "extract-auto-result",
+                dryRun,
+                harnessesProcessed: results.length,
+                totalProposals,
+                results,
+            });
+            // Signal failure to callers/cron when every harness failed. output()
+            // only renders; without this the */30 cron exits 0 on a total failure
+            // and the breakage is invisible to exit-code monitoring. process.exitCode
+            // (not process.exit) lets stdout flush and the watcher/timers settle.
+            if (!ok)
+                process.exitCode = EXIT_CODES.GENERAL;
+            return;
+        }
+        const result = await akmExtract({ type, ...commonOptions });
+        output("extract", result);
+        if (!result.ok)
+            process.exitCode = EXIT_CODES.GENERAL;
     },
 });
+/**
+ * A thin {@link WatchEventSource} over `fs.watch` for each configured root.
+ * This adapter is the ONLY place a real `fs.watch` is created (the core stays
+ * injectable + fully unit-tested); it is intentionally not unit-covered.
+ *
+ * `fs.watch(dir, { recursive: true })` is unreliable for recursive mode on some
+ * Node/Bun/Linux combinations — that is acceptable here: missed events degrade
+ * to the unchanged scheduled cron fallback, never worse than today.
+ */
+function createFsWatchEventSource(roots) {
+    return {
+        subscribe(listener) {
+            const watchers = [];
+            for (const root of roots) {
+                try {
+                    const watcher = fs.watch(root, { recursive: true }, (_event, filename) => {
+                        if (!filename)
+                            return;
+                        const filePath = path.isAbsolute(filename.toString())
+                            ? filename.toString()
+                            : path.join(root, filename.toString());
+                        listener({ path: filePath });
+                    });
+                    watchers.push(watcher);
+                }
+                catch {
+                    // A root that can't be watched is skipped; the cron fallback covers it.
+                }
+            }
+            return () => {
+                for (const w of watchers) {
+                    try {
+                        w.close();
+                    }
+                    catch {
+                        // best-effort teardown
+                    }
+                }
+            };
+        },
+    };
+}
+/**
+ * Run `akm extract --watch`: watch every available harness's session-log
+ * roots and run extract (debounced, per-harness) on change. Stays alive until
+ * SIGINT/SIGTERM, then stops cleanly. PROCESS-HYGIENE: stop() removes every
+ * watcher + pending timer before the process exits.
+ */
+async function runWatchMode(opts) {
+    const targets = getWatchTargets();
+    if (targets.length === 0) {
+        output("extract", {
+            schemaVersion: 1,
+            ok: false,
+            shape: "extract-watch-started",
+            warnings: ["no watchable harness session-log directories found on this machine"],
+            watching: [],
+        });
+        return;
+    }
+    const allRoots = targets.flatMap((t) => t.roots);
+    const eventSource = createFsWatchEventSource(allRoots);
+    const handle = akmExtractWatch({
+        roots: targets,
+        eventSource,
+        debounceMs: opts.debounceMs,
+        onTrigger: async (harnessName) => {
+            await akmExtract({
+                type: harnessName,
+                dryRun: opts.dryRun,
+                force: opts.force,
+                ...(opts.since ? { since: opts.since } : {}),
+            });
+        },
+    });
+    output("extract", {
+        schemaVersion: 1,
+        ok: true,
+        shape: "extract-watch-started",
+        debounceMs: opts.debounceMs,
+        watching: allRoots,
+    });
+    await new Promise((resolve) => {
+        const shutdown = () => {
+            handle.stop();
+            resolve();
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    });
+}

package/dist/commands/improve/extract-prompt.js

@@ -21,12 +21,18 @@ import promptTemplate from "../../assets/prompts/extract-session.md" with { type
  *
  * Shape:
  *   {
- *     "candidates": [{type, name, description, when_to_use?, body, confidence, evidence}, ...],
+ *     "candidates": [{type, name, description, when_to_use?, body, confidence, evidence,
+ *                     orderedActions?, outcomeData?}, ...],
  *     "rationale_if_empty"?: string
  *   }
  *
  * `additionalProperties: false` at each level so any hallucinated keys are
  * dropped before parsing.
+ *
+ * `orderedActions` and `outcomeData` are additive fields for #615 procedural
+ * compilation (WS-0 data-capture hook). Source transcripts are external logs
+ * not guaranteed re-extractable; we capture the ordered-action sequence and
+ * outcome now even though the detection/compilation feature is deferred to 0.10+.
  */
 export const EXTRACT_JSON_SCHEMA = {
     type: "object",
@@ -79,6 +85,17 @@ export const EXTRACT_JSON_SCHEMA = {
                         minLength: 5,
                         description: "One-line pointer to the moment in the session that supports this candidate.",
                     },
+                    orderedActions: {
+                        type: "array",
+                        description: "OPTIONAL. Ordered list of discrete actions taken during this episode, as brief imperative phrases (e.g. 'run deploy.sh', 'check VPN status', 'retry with --force'). Capture only when the candidate represents a recurring action sequence that could become a skill or workflow. Omit when the candidate is a standalone fact or observation.",
+                        items: { type: "string", minLength: 3 },
+                        maxItems: 20,
+                    },
+                    outcomeData: {
+                        type: "string",
+                        description: "OPTIONAL. One-sentence description of the outcome when the ordered action sequence completed (e.g. 'deploy succeeded after VPN reconnect', 'build failed with error X'). Required when orderedActions is present; omit otherwise.",
+                        maxLength: 400,
+                    },
                 },
             },
         },
@@ -106,22 +123,36 @@ function formatAlreadyPreserved(inlineRefs) {
     })
         .join("\n");
 }
+/**
+ * Delimiters that fence the untrusted session transcript in the extract prompt.
+ * Mirrors the `=== ASSET N ===` convention (`graph-extract.ts`): everything
+ * between the markers is DATA to analyze, never instructions to obey. The
+ * transcript is external, attacker-influenceable content, so an explicit,
+ * greppable boundary defuses prompt-injection that tries to pose as a command.
+ */
+export const TRANSCRIPT_FENCE_BEGIN = "=== BEGIN UNTRUSTED SESSION TRANSCRIPT ===";
+export const TRANSCRIPT_FENCE_END = "=== END UNTRUSTED SESSION TRANSCRIPT ===";
 /**
  * Format pre-filtered events as a transcript snippet. Each event becomes:
  *   [<role> @ <iso>] <text>
  * Events are already truncated/cleaned by the pre-filter; this is purely
  * a render step.
+ *
+ * Anti-spoof: any occurrence of the fence markers inside the transcript text is
+ * neutralised so a crafted session cannot forge the boundary and "escape" the
+ * fence to inject trusted-looking instructions.
  */
 function formatTranscript(events) {
     if (events.length === 0)
         return "(empty — pre-filter removed all events as noise)";
-    return events
+    const body = events
         .map((e) => {
         const tsLabel = e.ts ? new Date(e.ts).toISOString() : "unknown-ts";
         const roleLabel = e.role ?? "unknown";
         return `[${roleLabel} @ ${tsLabel}] ${e.text}`;
     })
         .join("\n\n");
+    return body.split(TRANSCRIPT_FENCE_BEGIN).join("=== (fence) ===").split(TRANSCRIPT_FENCE_END).join("=== (fence) ===");
 }
 /**
  * Build the user-prompt body for the extract LLM call by interpolating
@@ -132,6 +163,11 @@ export function buildExtractPrompt(input) {
     const ref = input.data.ref;
     const startedAt = ref.startedAt ? new Date(ref.startedAt).toISOString() : "unknown";
     const endedAt = ref.endedAt ? new Date(ref.endedAt).toISOString() : "unknown";
+    // Optional standards block — rendered to the lead-in + body when present,
+    // or an empty string (no section) when absent. Gated on non-empty.
+    const standards = input.standardsContext?.trim()
+        ? `\n## Standards to follow (the rulebook for this target)\n\n${input.standardsContext.trim()}\n`
+        : "";
     return promptTemplate
         .replace("{{HARNESS}}", ref.harness)
         .replace("{{TITLE}}", ref.title ?? "(no title)")
@@ -139,7 +175,8 @@ export function buildExtractPrompt(input) {
         .replace("{{ENDED_AT}}", endedAt)
         .replace("{{PROJECT_HINT}}", ref.projectHint ?? "(no project hint)")
         .replace("{{ALREADY_PRESERVED}}", formatAlreadyPreserved(input.inlineRefs))
-        .replace("{{TRANSCRIPT}}", formatTranscript(input.events));
+        .replace("{{STANDARDS}}", standards)
+        .replace("{{TRANSCRIPT}}", `${TRANSCRIPT_FENCE_BEGIN}\n${formatTranscript(input.events)}\n${TRANSCRIPT_FENCE_END}`);
 }
 /**
  * Parse the LLM's JSON response into a structured {@link ExtractPayload}.
@@ -207,6 +244,20 @@ export function parseExtractPayload(stdout) {
         };
         if (typeof c.when_to_use === "string")
             candidate.when_to_use = c.when_to_use.trim();
+        // #615 WS-0: parse optional ordered-action + outcome fields.
+        // Defensive: silently drop malformed entries rather than rejecting the whole candidate.
+        if (Array.isArray(c.orderedActions) && c.orderedActions.length > 0) {
+            const actions = c.orderedActions
+                .filter((a) => typeof a === "string" && a.trim().length >= 3)
+                .map((a) => a.trim())
+                .slice(0, 20);
+            if (actions.length > 0) {
+                candidate.orderedActions = actions;
+                if (typeof c.outcomeData === "string" && c.outcomeData.trim().length > 0) {
+                    candidate.outcomeData = c.outcomeData.trim().slice(0, 400);
+                }
+            }
+        }
         candidates.push(candidate);
     }
     const result = { candidates };

package/dist/commands/improve/extract-watch.js

@@ -0,0 +1,140 @@
+// 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 { akmExtract } from "./extract.js";
+const DEFAULT_DEBOUNCE_MS = 2000;
+/** Small look-back window for the default trigger's `akmExtract` call. */
+const DEFAULT_TRIGGER_SINCE = "10m";
+/**
+ * Does `filePath` look like a real session file under one of the configured
+ * roots? True only when the path is under a root AND matches that harness's
+ * on-disk session-file shape:
+ *   - claude-code: `<root>/<project>/<id>.jsonl`
+ *   - opencode:    `<root>/<project>/<id>.json`
+ * Anything out-of-root, or in-root with the wrong extension, returns false.
+ */
+export function isSessionFile(filePath, roots) {
+    return matchHarness(filePath, roots) !== undefined;
+}
+/** Normalize a path for prefix comparison (ensure a trailing separator). */
+function withSep(dir) {
+    return dir.endsWith("/") ? dir : `${dir}/`;
+}
+/**
+ * Resolve which harness a path belongs to by longest-prefix match against the
+ * configured roots, then validate the file shape for that harness. Returns the
+ * harness name, or `undefined` when the path is out-of-root or not a session
+ * file. Longest-prefix match guards against the (in practice impossible) case
+ * of nested roots.
+ */
+export function matchHarness(filePath, roots) {
+    let best;
+    let bestLen = -1;
+    for (const target of roots) {
+        for (const root of target.roots) {
+            const prefix = withSep(root);
+            if (filePath.startsWith(prefix) && prefix.length > bestLen) {
+                best = { harnessName: target.harnessName };
+                bestLen = prefix.length;
+            }
+        }
+    }
+    if (!best)
+        return undefined;
+    // Validate the file shape for the resolved harness.
+    if (best.harnessName === "claude-code") {
+        return filePath.endsWith(".jsonl") ? best.harnessName : undefined;
+    }
+    if (best.harnessName === "opencode") {
+        return filePath.endsWith(".json") ? best.harnessName : undefined;
+    }
+    // Unknown harness: accept any file under its root.
+    return best.harnessName;
+}
+/**
+ * Start the watch-mode core. Returns a handle whose `stop()` tears everything
+ * down. The event source is injected, so this never touches the real
+ * filesystem itself.
+ */
+export function akmExtractWatch(options) {
+    const { roots, eventSource, debounceMs = DEFAULT_DEBOUNCE_MS, setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout, isSessionFile: isSessionFileFn = isSessionFile, } = options;
+    const onTrigger = options.onTrigger ??
+        (async (harnessName) => {
+            await akmExtract({ type: harnessName, since: DEFAULT_TRIGGER_SINCE, force: false });
+        });
+    let stopped = false;
+    // Pending debounce timers, keyed by harness name.
+    const pendingTimers = new Map();
+    // Harnesses with an in-flight trigger, and whether a re-run is queued.
+    const inFlight = new Set();
+    const rerunPending = new Set();
+    function runTrigger(harnessName) {
+        if (stopped)
+            return;
+        if (inFlight.has(harnessName)) {
+            // A trigger is already running for this harness; coalesce into a single
+            // re-run after it resolves rather than launching a concurrent extract.
+            rerunPending.add(harnessName);
+            return;
+        }
+        inFlight.add(harnessName);
+        // Invoke synchronously so a synchronous `onTrigger` observes its effect
+        // before control returns (tests advance the clock then assert inline).
+        // Wrap the (possibly async) result in a promise to drive the in-flight
+        // guard's release without forcing the trigger itself into a microtask.
+        let result;
+        try {
+            result = onTrigger(harnessName);
+        }
+        catch (err) {
+            // One failed extract must never kill the watcher (mirrors the non-fatal
+            // handling in collectSessionEvents).
+            console.error(`[akm] extract --watch trigger for "${harnessName}" failed:`, err);
+            inFlight.delete(harnessName);
+            if (rerunPending.delete(harnessName) && !stopped)
+                runTrigger(harnessName);
+            return;
+        }
+        Promise.resolve(result)
+            .catch((err) => {
+            console.error(`[akm] extract --watch trigger for "${harnessName}" failed:`, err);
+        })
+            .finally(() => {
+            inFlight.delete(harnessName);
+            if (rerunPending.delete(harnessName) && !stopped) {
+                runTrigger(harnessName);
+            }
+        });
+    }
+    function onEvent(e) {
+        if (stopped)
+            return;
+        if (!isSessionFileFn(e.path, roots))
+            return;
+        const harnessName = matchHarness(e.path, roots);
+        if (!harnessName)
+            return;
+        const existing = pendingTimers.get(harnessName);
+        if (existing !== undefined)
+            clearTimeoutFn(existing);
+        const timer = setTimeoutFn(() => {
+            pendingTimers.delete(harnessName);
+            if (!stopped)
+                runTrigger(harnessName);
+        }, debounceMs);
+        pendingTimers.set(harnessName, timer);
+    }
+    const unsubscribe = eventSource.subscribe(onEvent);
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            unsubscribe();
+            for (const timer of pendingTimers.values())
+                clearTimeoutFn(timer);
+            pendingTimers.clear();
+            rerunPending.clear();
+        },
+    };
+}