akm-cli 0.9.0-beta.5 → 0.9.0-beta.51

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

@@ -14,11 +14,14 @@
  * Output is the AkmExtractResult JSON envelope (or an aggregated one when
  * `--auto` runs multiple harnesses).
  */
+import fs from "node:fs";
+import path from "node:path";
 import { defineCommand } from "citty";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { EXIT_CODES, output, runWithJsonErrors } 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";
+import { akmExtractWatch } from "./extract-watch.js";
 export const extractCommand = defineCommand({
     meta: {
         name: "extract",
@@ -60,6 +63,15 @@ 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 () => {
@@ -76,6 +88,17 @@ export const extractCommand = defineCommand({
             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");
             }
@@ -118,10 +141,109 @@ export const extractCommand = defineCommand({
                     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",
@@ -55,7 +61,7 @@ export const EXTRACT_JSON_SCHEMA = {
                         type: "string",
                         minLength: 20,
                         maxLength: 400,
-                        description: "One-sentence summary of the candidate. Must be a complete sentence; do not end mid-clause.",
+                        description: "One-sentence summary of the candidate. Must be a complete sentence in active voice. Do NOT start with 'When', 'If', 'How', 'Use', or 'Avoid'. Do NOT end with ':', ';', or ','. Do NOT use heading-fragment text ('Summary', 'Overview', 'Key finding:'). Minimum 20 characters, maximum 400 characters.",
                     },
                     when_to_use: {
                         type: "string",
@@ -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,
+                    },
                 },
             },
         },
@@ -132,6 +149,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,6 +161,7 @@ export function buildExtractPrompt(input) {
         .replace("{{ENDED_AT}}", endedAt)
         .replace("{{PROJECT_HINT}}", ref.projectHint ?? "(no project hint)")
         .replace("{{ALREADY_PRESERVED}}", formatAlreadyPreserved(input.inlineRefs))
+        .replace("{{STANDARDS}}", standards)
         .replace("{{TRANSCRIPT}}", formatTranscript(input.events));
 }
 /**
@@ -207,6 +230,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();
+        },
+    };
+}