akm-cli 0.8.0-rc2 → 0.8.1

package/dist/integrations/lockfile.js

@@ -1,6 +1,11 @@
+// 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 fs from "node:fs";
 import path from "node:path";
 import { writeFileAtomic } from "../core/common";
+import { rethrowIfTestIsolationError } from "../core/errors";
+import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock";
 import { getDataDir } from "../core/paths";
 // ── Paths ───────────────────────────────────────────────────────────────────
 const LOCKFILE_NAME = "akm.lock";
@@ -16,64 +21,26 @@ function getLockSentinelPath() {
 }
 async function acquireLockSentinel() {
     const sentinelPath = getLockSentinelPath();
-    // Ensure the directory exists before attempting to create the sentinel
+    // Ensure the directory exists before attempting to create the sentinel.
     fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
     for (let attempt = 0; attempt < LOCK_MAX_RETRIES; attempt++) {
-        try {
-            fs.writeFileSync(sentinelPath, String(process.pid), { flag: "wx" });
-            return true; // Sentinel created — we own the lock
+        if (tryAcquireLockSync(sentinelPath, String(process.pid))) {
+            return true; // Sentinel created — we own the lock.
         }
-        catch (err) {
-            if (err.code !== "EEXIST")
-                throw err;
-            // Check for stale lock — if the owning PID is no longer running, reclaim it
-            if (tryReclaimStaleSentinel(sentinelPath)) {
-                continue; // Sentinel removed — retry immediately
-            }
-            // Another process holds the lock — wait briefly before retrying
-            if (attempt < LOCK_MAX_RETRIES - 1) {
-                await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
-            }
+        if (probeLock(sentinelPath).state === "stale") {
+            releaseLock(sentinelPath);
+            continue; // Reclaimed — retry immediately.
         }
-    }
-    // Best-effort: proceed without the lock rather than failing the install
-    return false;
-}
-/**
- * Check if the sentinel was left by a dead process and remove it if so.
- * Returns true if the sentinel was reclaimed (removed).
- */
-function tryReclaimStaleSentinel(sentinelPath) {
-    try {
-        const content = fs.readFileSync(sentinelPath, "utf8").trim();
-        const pid = parseInt(content, 10);
-        if (Number.isNaN(pid) || pid <= 0) {
-            // Invalid PID in sentinel — reclaim it
-            fs.unlinkSync(sentinelPath);
-            return true;
-        }
-        // Check if the process is still alive (signal 0 doesn't kill, just checks)
-        try {
-            process.kill(pid, 0);
-            return false; // Process is alive — lock is valid
-        }
-        catch {
-            // Process is dead — reclaim the stale lock
-            fs.unlinkSync(sentinelPath);
-            return true;
+        // Another process holds the lock — wait briefly before retrying.
+        if (attempt < LOCK_MAX_RETRIES - 1) {
+            await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
         }
     }
-    catch {
-        return false; // Can't read or remove — leave it alone
-    }
+    // Best-effort: proceed without the lock rather than failing the install.
+    return false;
 }
 function releaseLockSentinel() {
-    try {
-        fs.unlinkSync(getLockSentinelPath());
-    }
-    catch {
-        /* ignore — sentinel may already be gone */
-    }
+    releaseLock(getLockSentinelPath());
 }
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {
@@ -84,7 +51,11 @@ export function readLockfile() {
             return [];
         return raw.filter(isValidLockfileEntry);
     }
-    catch {
+    catch (err) {
+        // Defense-in-depth: getLockfilePath() is outside this try block, but a
+        // future refactor that pushes a getDataDir() call inside must not mask
+        // the bun-test isolation guard as "empty lockfile".
+        rethrowIfTestIsolationError(err);
         return [];
     }
 }

package/dist/integrations/session-logs/index.js

@@ -1,5 +1,9 @@
+// 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 { ClaudeCodeProvider } from "./providers/claude-code";
 import { OpenCodeProvider } from "./providers/opencode";
+export { extractInlineRefMentions } from "./inline-refs";
 const HARNESSES = [new ClaudeCodeProvider(), new OpenCodeProvider()];
 const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENOENT|timeout/i;
 /**

package/dist/integrations/session-logs/inline-refs.js

@@ -0,0 +1,35 @@
+// 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/.
+const REMEMBER_RE = /\bakm\s+remember\s+(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)')/g;
+const FEEDBACK_RE = /\bakm\s+feedback\s+(\S+)(?:\s+--[a-z-]+)*\s+(?:--note|-n)\s+(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)')/g;
+export function extractInlineRefMentions(text, ts) {
+    if (!text || text.length < 10)
+        return [];
+    const out = [];
+    REMEMBER_RE.lastIndex = 0;
+    for (const m of text.matchAll(REMEMBER_RE)) {
+        const body = m[1] ?? m[2] ?? "";
+        if (!body.trim())
+            continue;
+        out.push({
+            kind: "remember",
+            text: body,
+            ...(ts !== undefined ? { ts } : {}),
+        });
+    }
+    FEEDBACK_RE.lastIndex = 0;
+    for (const m of text.matchAll(FEEDBACK_RE)) {
+        const ref = m[1] ?? "";
+        const note = m[2] ?? m[3] ?? "";
+        if (!ref)
+            continue;
+        out.push({
+            kind: "feedback",
+            ref,
+            text: note,
+            ...(ts !== undefined ? { ts } : {}),
+        });
+    }
+    return out;
+}

package/dist/integrations/session-logs/pre-filter.js

@@ -0,0 +1,152 @@
+// 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/.
+/** Default cap for any single event's text length. Head+tail summary applies above this. */
+export const DEFAULT_MAX_EVENT_LENGTH = 2000;
+/**
+ * Default cap on total transcript characters fed to the LLM. Chosen for a
+ * 32K-token context model with room for the prompt scaffolding (~3K chars)
+ * and JSON output (~4K chars). Adjust via {@link PreFilterOptions.maxTotalChars}
+ * when targeting larger-context models.
+ */
+export const DEFAULT_MAX_TOTAL_CHARS = 80_000;
+/**
+ * `akm` subcommands that are read-only / introspective — their invocations
+ * are operational noise, not engineering signal. Mutating commands (remember,
+ * feedback, accept, reject, extract, import, save, ...) are kept.
+ */
+export const DEFAULT_AKM_READONLY_OPS = new Set([
+    "show",
+    "search",
+    "curate",
+    "history",
+    "info",
+    "hints",
+    "help",
+    "list",
+    "completions",
+    "lessons",
+    "graph",
+    "db",
+    "events",
+    "config",
+    "health",
+]);
+/**
+ * Regex patterns that identify post-compact / activity-log noise. Conservative
+ * — only matches text that's clearly transcript pollution, not engineering
+ * content that happens to contain similar words.
+ */
+const NOISE_PATTERNS = [
+    // Claude Code injects this caveat block before every bash invocation result.
+    /<local-command-caveat>/i,
+    // Post-compact dumps embed analysis/summary XML blocks pasted from prior context.
+    /<analysis>[\s\S]{200,}<\/analysis>/i,
+    /<summary>[\s\S]{200,}<\/summary>/i,
+    // System reminders the harness injects every few turns — never carry signal.
+    /<system-reminder>/i,
+    // Opencode tool-event aggregate dumps look like repeated `akm_search unknown` blocks.
+    /^(##\s+\d+.*akm_search unknown\s*\n){3,}/im,
+];
+/**
+ * Apply the drop+truncate rules to a single event. Returns `undefined` when
+ * the event should be dropped, or the (possibly truncated) event when kept.
+ * The third return tracks why dropped, for stats.
+ */
+function classifyEvent(event, akmReadOnlyOps, maxLen) {
+    const text = event.text ?? "";
+    if (text.trim().length < 10)
+        return { keep: false, reason: "too-short" };
+    // Rule 1: read-only akm meta-ops. The flattened tool_use shape from the
+    // claude-code provider looks like: `[tool:Bash] akm show knowledge:foo`.
+    // Match the verb directly after `akm ` (with or without the `[tool:...]`
+    // prefix, since some platforms surface the command differently).
+    const akmCallMatch = text.match(/\bakm\s+(\w[\w-]*)\b/);
+    if (akmCallMatch) {
+        const op = (akmCallMatch[1] ?? "").toLowerCase();
+        if (akmReadOnlyOps.has(op)) {
+            return { keep: false, reason: `akm-readonly-${op}` };
+        }
+    }
+    // Rule 2-5: noise patterns
+    for (const pattern of NOISE_PATTERNS) {
+        if (pattern.test(text)) {
+            return { keep: false, reason: `noise-pattern-${pattern.source.slice(0, 24)}` };
+        }
+    }
+    // Rule 6: bare system events that are pure boilerplate (no engineering content).
+    // Heuristic: role=system AND short, OR role=system AND just contains `caveat`/`reminder` markers.
+    if (event.role === "system" && (text.length < 200 || /caveat|reminder/i.test(text))) {
+        return { keep: false, reason: "system-boilerplate" };
+    }
+    // Truncate long events to head + tail summary.
+    if (text.length > maxLen) {
+        const headLen = Math.floor(maxLen * 0.7);
+        const tailLen = maxLen - headLen - 32; // 32 chars for the marker
+        const truncated = text.slice(0, headLen) +
+            `\n... [truncated ${text.length - headLen - tailLen} chars] ...\n` +
+            text.slice(text.length - tailLen);
+        return { keep: true, event: { ...event, text: truncated }, truncated: true };
+    }
+    return { keep: true, event, truncated: false };
+}
+export function preFilterSession(data, options = {}) {
+    const akmReadOnlyOps = options.akmReadOnlyOps ?? DEFAULT_AKM_READONLY_OPS;
+    const maxLen = options.maxEventTextLength ?? DEFAULT_MAX_EVENT_LENGTH;
+    const maxTotalChars = options.maxTotalChars ?? DEFAULT_MAX_TOTAL_CHARS;
+    const droppedByRule = {};
+    const kept = [];
+    let truncatedCount = 0;
+    const candidates = [];
+    for (const event of data.events) {
+        const verdict = classifyEvent(event, akmReadOnlyOps, maxLen);
+        if (!verdict.keep) {
+            droppedByRule[verdict.reason] = (droppedByRule[verdict.reason] ?? 0) + 1;
+            continue;
+        }
+        candidates.push({
+            event: verdict.event,
+            truncated: verdict.truncated,
+            chars: verdict.event.text.length,
+        });
+    }
+    // Second pass: total-budget cap. Walk from the END (most recent first) and
+    // accept events until the budget is exhausted. The remaining (head) events
+    // are dropped — insight typically emerges later in a session, so this
+    // recency-bias is the cheapest sampling heuristic that respects context
+    // limits. Maintains original timestamp order in the output.
+    let totalChars = 0;
+    let budgetDroppedCount = 0;
+    const keptIdxFromTail = [];
+    for (let i = candidates.length - 1; i >= 0; i--) {
+        const c = candidates[i];
+        if (!c)
+            continue;
+        if (totalChars + c.chars > maxTotalChars && keptIdxFromTail.length > 0) {
+            budgetDroppedCount += 1;
+            continue;
+        }
+        keptIdxFromTail.push(i);
+        totalChars += c.chars;
+    }
+    keptIdxFromTail.reverse(); // restore timestamp order
+    for (const idx of keptIdxFromTail) {
+        const c = candidates[idx];
+        if (!c)
+            continue;
+        kept.push(c.event);
+        if (c.truncated)
+            truncatedCount += 1;
+    }
+    return {
+        events: kept,
+        stats: {
+            inputCount: data.events.length,
+            outputCount: kept.length,
+            droppedByRule,
+            truncatedCount,
+            totalChars,
+            budgetDroppedCount,
+        },
+    };
+}

package/dist/integrations/session-logs/providers/claude-code.js

@@ -1,7 +1,80 @@
+// 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 fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { extractInlineRefMentions } from "../inline-refs";
 const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
+/**
+ * Parse a single Claude Code JSONL event into a normalized {@link SessionEvent}.
+ * Returns `undefined` for events that don't carry textual content (file
+ * snapshots, attachments, queue metadata). Tool calls are flattened from the
+ * `message.content` array into a stable text representation so downstream
+ * consumers don't need to know the Anthropic-tool-call shape.
+ */
+function parseClaudeEvent(entry, sessionId, filePath, fallbackTsMs) {
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    const e = entry;
+    const tsRaw = e.timestamp;
+    const ts = typeof tsRaw === "number" ? tsRaw : typeof tsRaw === "string" ? Date.parse(tsRaw) || fallbackTsMs : fallbackTsMs;
+    const message = e.message ?? undefined;
+    const role = typeof message?.role === "string"
+        ? message.role
+        : (e.type ?? "unknown");
+    const content = message?.content;
+    let text = "";
+    if (typeof content === "string") {
+        text = content;
+    }
+    else if (Array.isArray(content)) {
+        // Assistant messages: array of content blocks. Flatten text/thinking/tool_use
+        // into a stable representation. tool_use entries become `[tool: <name>] <input>`
+        // so the inline-ref scanner can detect `akm remember` / `akm feedback` calls.
+        const parts = [];
+        for (const block of content) {
+            if (!block || typeof block !== "object")
+                continue;
+            const b = block;
+            if (b.type === "text" && typeof b.text === "string")
+                parts.push(b.text);
+            else if (b.type === "thinking" && typeof b.thinking === "string")
+                parts.push(b.thinking);
+            else if (b.type === "tool_use") {
+                const toolName = typeof b.name === "string" ? b.name : "tool";
+                // For shell-like tools, surface the `command` field directly so
+                // inline-ref detection can match `akm remember "..."` without
+                // JSON-quote escaping mangling the regex.
+                const inputObj = b.input;
+                let inputText = "";
+                if (inputObj && typeof inputObj === "object") {
+                    const cmd = inputObj.command;
+                    inputText = typeof cmd === "string" ? cmd : JSON.stringify(inputObj);
+                }
+                else if (typeof inputObj === "string") {
+                    inputText = inputObj;
+                }
+                parts.push(`[tool:${toolName}] ${inputText}`);
+            }
+            else if (b.type === "tool_result") {
+                const out = typeof b.content === "string" ? b.content : JSON.stringify(b.content ?? "");
+                parts.push(`[tool_result] ${out}`);
+            }
+        }
+        text = parts.join("\n");
+    }
+    if (!text || text.length < 1)
+        return undefined;
+    return {
+        harness: "claude-code",
+        text,
+        ts,
+        sessionId,
+        role,
+        filePath,
+    };
+}
 export class ClaudeCodeProvider {
     name = "claude-code";
     isAvailable() {
@@ -39,6 +112,159 @@ export class ClaudeCodeProvider {
             return;
         }
     }
+    listSessions(input = {}) {
+        const root = input.location ?? CLAUDE_PROJECTS_DIR;
+        const sinceMs = input.sinceMs ?? 0;
+        const summaries = [];
+        try {
+            for (const jsonlPath of this.#walkJsonl(root)) {
+                let stat;
+                try {
+                    stat = fs.statSync(jsonlPath);
+                }
+                catch {
+                    continue;
+                }
+                if (stat.mtimeMs < sinceMs)
+                    continue;
+                const sessionId = path.basename(jsonlPath, ".jsonl");
+                const projectHint = path.basename(path.dirname(jsonlPath));
+                // Peek first + last non-empty line to derive start/end timestamps and
+                // title. Reading the whole file would be wasteful for listing.
+                const peek = this.#peekJsonl(jsonlPath);
+                summaries.push({
+                    harness: this.name,
+                    sessionId,
+                    filePath: jsonlPath,
+                    startedAt: peek.firstTsMs ?? stat.ctimeMs,
+                    endedAt: peek.lastTsMs ?? stat.mtimeMs,
+                    projectHint,
+                    ...(peek.title ? { title: peek.title } : {}),
+                });
+            }
+        }
+        catch {
+            // Root missing or unreadable — return what we have.
+        }
+        return summaries.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0));
+    }
+    readSession(ref) {
+        const stat = fs.statSync(ref.filePath);
+        const lines = fs.readFileSync(ref.filePath, "utf8").split("\n").filter(Boolean);
+        const events = [];
+        const inlineRefs = [];
+        let title;
+        let firstTsMs;
+        let lastTsMs;
+        const projectHint = path.basename(path.dirname(ref.filePath));
+        for (const line of lines) {
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!entry)
+                continue;
+            if (entry.type === "custom-title" && typeof entry.customTitle === "string") {
+                title = entry.customTitle;
+                continue;
+            }
+            const parsed = parseClaudeEvent(entry, ref.sessionId, ref.filePath, stat.mtimeMs);
+            if (!parsed)
+                continue;
+            events.push(parsed);
+            if (firstTsMs === undefined || (parsed.ts ?? 0) < firstTsMs)
+                firstTsMs = parsed.ts;
+            if (lastTsMs === undefined || (parsed.ts ?? 0) > lastTsMs)
+                lastTsMs = parsed.ts;
+            // Extract inline akm-remember/feedback invocations from this event's text.
+            inlineRefs.push(...extractInlineRefMentions(parsed.text, parsed.ts));
+        }
+        return {
+            ref: {
+                harness: this.name,
+                sessionId: ref.sessionId,
+                filePath: ref.filePath,
+                startedAt: firstTsMs ?? stat.ctimeMs,
+                endedAt: lastTsMs ?? stat.mtimeMs,
+                projectHint,
+                ...(title ? { title } : {}),
+            },
+            events,
+            inlineRefs,
+        };
+    }
+    /**
+     * Cheap metadata peek — reads the first ~4KB to grab the `custom-title`
+     * event (always early in the file) and the first event timestamp, then
+     * reads the tail (~4KB) for the last timestamp. Avoids slurping multi-MB
+     * session files during `listSessions`.
+     */
+    #peekJsonl(filePath) {
+        const result = {};
+        try {
+            const fd = fs.openSync(filePath, "r");
+            try {
+                const stat = fs.fstatSync(fd);
+                const headSize = Math.min(stat.size, 4096);
+                const head = Buffer.alloc(headSize);
+                fs.readSync(fd, head, 0, headSize, 0);
+                const headLines = head.toString("utf8").split("\n").filter(Boolean);
+                // Walk head: track title, first timestamp, and (if file fits in head)
+                // also the last timestamp seen — saves a tail read for small files.
+                for (const line of headLines) {
+                    try {
+                        const e = JSON.parse(line);
+                        if (e.type === "custom-title" && typeof e.customTitle === "string") {
+                            result.title = e.customTitle;
+                        }
+                        if (typeof e.timestamp === "string") {
+                            const t = Date.parse(e.timestamp);
+                            if (!Number.isNaN(t)) {
+                                if (result.firstTsMs === undefined)
+                                    result.firstTsMs = t;
+                                result.lastTsMs = t;
+                            }
+                        }
+                    }
+                    catch {
+                        // partial line at buffer boundary — fine, skip
+                    }
+                }
+                // Large-file tail read overrides lastTsMs with a value closer to EOF.
+                if (stat.size > 4096) {
+                    const tailSize = Math.min(stat.size, 4096);
+                    const tail = Buffer.alloc(tailSize);
+                    fs.readSync(fd, tail, 0, tailSize, stat.size - tailSize);
+                    const tailLines = tail.toString("utf8").split("\n").filter(Boolean);
+                    for (let i = tailLines.length - 1; i >= 0; i--) {
+                        try {
+                            const e = JSON.parse(tailLines[i] ?? "");
+                            if (typeof e.timestamp === "string") {
+                                const t = Date.parse(e.timestamp);
+                                if (!Number.isNaN(t)) {
+                                    result.lastTsMs = t;
+                                    break;
+                                }
+                            }
+                        }
+                        catch {
+                            // skip partial lines from buffer boundary
+                        }
+                    }
+                }
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            // unreadable / vanished file — caller falls back to stat times
+        }
+        return result;
+    }
     *#walkJsonl(dir) {
         try {
             for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {