agent-bober 0.12.0 → 0.15.0

package/dist/graph/incidents.js

@@ -0,0 +1,22 @@
+import { appendFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { ensureDir } from "../utils/fs.js";
+// ── IncidentLog ────────────────────────────────────────────────────
+/**
+ * Append-only writer for .bober/graph/incidents.jsonl.
+ *
+ * Each call writes a single newline-terminated JSON object.
+ * The directory is created defensively on each write, in case
+ * GraphArtifactStore.ensureLayout() has not been called yet.
+ */
+export class IncidentLog {
+    path;
+    constructor(projectRoot) {
+        this.path = resolve(projectRoot, ".bober/graph/incidents.jsonl");
+    }
+    async append(e) {
+        await ensureDir(resolve(this.path, ".."));
+        await appendFile(this.path, JSON.stringify(e) + "\n", "utf-8");
+    }
+}
+//# sourceMappingURL=incidents.js.map

package/dist/graph/incidents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incidents.js","sourceRoot":"","sources":["../../src/graph/incidents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AA0B3C,sEAAsE;AAEtE;;;;;;GAMG;AACH,MAAM,OAAO,WAAW;IACL,IAAI,CAAS;IAE9B,YAAY,WAAmB;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,WAAW,EAAE,8BAA8B,CAAC,CAAC;IACnE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,CAAgB;QAC3B,MAAM,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1C,MAAM,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;CACF"}

package/dist/graph/mcp-client.d.ts

@@ -0,0 +1,51 @@
+/**
+ * TokensaveMcpClient — long-lived `tokensave serve` subprocess over JSON-RPC 2.0.
+ *
+ * Responsibilities:
+ *   - Spawn and own exactly ONE `tokensave serve` child per instance.
+ *   - Multiplex concurrent call() invocations via a numeric-id PendingMap.
+ *   - Restart on crash with 3-per-60s circuit breaker (health → 'broken' when
+ *     tripped; subsequent call() rejects immediately).
+ *   - Reject in-flight call() promises on child exit rather than leaving them
+ *     to time out.
+ */
+import type { GraphSection } from "./types.js";
+import type { IncidentLog } from "./incidents.js";
+export type EngineHealth = "starting" | "ready" | "restarting" | "broken";
+export declare class TokensaveMcpClient {
+    private readonly projectRoot;
+    private readonly cfg;
+    private readonly incidents;
+    private readonly binary;
+    childPid: number | null;
+    private child;
+    private healthState;
+    private nextId;
+    private readonly pending;
+    private restartTimestamps;
+    private stdoutBuf;
+    private stopping;
+    constructor(projectRoot: string, cfg: GraphSection, incidents: IncidentLog, binary?: string);
+    health(): EngineHealth;
+    /**
+     * Spawn the child process and wait for the JSON-RPC handshake.
+     * Resolves once health flips to 'ready'.
+     * Rejects within HANDSHAKE_TIMEOUT_MS if the child exits early or the
+     * handshake never arrives.
+     */
+    start(): Promise<void>;
+    /**
+     * SIGTERM the child; wait up to 2000ms; SIGKILL if still alive.
+     */
+    stop(): Promise<void>;
+    /**
+     * Send a JSON-RPC 2.0 request and await the matching response.
+     * Rejects immediately when health is 'broken' or the engine is stopped.
+     */
+    call<T>(tool: string, params: unknown): Promise<T>;
+    private spawnAndHandshake;
+    private handleResponse;
+    private onExit;
+    private rejectAllPending;
+}
+//# sourceMappingURL=mcp-client.d.ts.map

package/dist/graph/mcp-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.d.ts","sourceRoot":"","sources":["../../src/graph/mcp-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAWlD,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,GAAG,QAAQ,CAAC;AAwC1E,qBAAa,kBAAkB;IAa3B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAdzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,iBAAiB,CAAgB;IACzC,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,QAAQ,CAAS;gBAGN,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,YAAY,EACjB,SAAS,EAAE,WAAW,EACtB,MAAM,GAAE,MAAoB;IAG/C,MAAM,IAAI,YAAY;IAMtB;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C3B;;;OAGG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;YA2C1C,iBAAiB;IAmF/B,OAAO,CAAC,cAAc;YAkBR,MAAM;IAmEpB,OAAO,CAAC,gBAAgB;CAOzB"}

package/dist/graph/mcp-client.js

@@ -0,0 +1,285 @@
+/**
+ * TokensaveMcpClient — long-lived `tokensave serve` subprocess over JSON-RPC 2.0.
+ *
+ * Responsibilities:
+ *   - Spawn and own exactly ONE `tokensave serve` child per instance.
+ *   - Multiplex concurrent call() invocations via a numeric-id PendingMap.
+ *   - Restart on crash with 3-per-60s circuit breaker (health → 'broken' when
+ *     tripped; subsequent call() rejects immediately).
+ *   - Reject in-flight call() promises on child exit rather than leaving them
+ *     to time out.
+ */
+import { execa } from "execa";
+import { logger } from "../utils/logger.js";
+// ── Constants ──────────────────────────────────────────────────────
+const BREAKER_WINDOW_MS = 60_000;
+const BREAKER_MAX_RESTARTS = 3;
+const HANDSHAKE_TIMEOUT_MS = 1_000;
+// ── Structured errors ──────────────────────────────────────────────
+function makeGraphError(reason, detail) {
+    const err = new Error(`${reason}: ${detail}`);
+    err.reason = reason;
+    err.detail = detail;
+    return err;
+}
+// ── TokensaveMcpClient ─────────────────────────────────────────────
+export class TokensaveMcpClient {
+    projectRoot;
+    cfg;
+    incidents;
+    binary;
+    // Exposed so pipeline-lifecycle can read the child PID for the PID file
+    childPid = null;
+    child = null;
+    healthState = "starting";
+    nextId = 1;
+    pending = new Map();
+    restartTimestamps = [];
+    stdoutBuf = "";
+    stopping = false;
+    constructor(projectRoot, cfg, incidents, binary = "tokensave") {
+        this.projectRoot = projectRoot;
+        this.cfg = cfg;
+        this.incidents = incidents;
+        this.binary = binary;
+    }
+    health() {
+        return this.healthState;
+    }
+    // ── start ──────────────────────────────────────────────────────
+    /**
+     * Spawn the child process and wait for the JSON-RPC handshake.
+     * Resolves once health flips to 'ready'.
+     * Rejects within HANDSHAKE_TIMEOUT_MS if the child exits early or the
+     * handshake never arrives.
+     */
+    async start() {
+        this.stopping = false;
+        this.healthState = "starting";
+        await this.spawnAndHandshake();
+    }
+    // ── stop ───────────────────────────────────────────────────────
+    /**
+     * SIGTERM the child; wait up to 2000ms; SIGKILL if still alive.
+     */
+    async stop() {
+        this.stopping = true;
+        // Reject any pending calls gracefully
+        this.rejectAllPending(makeGraphError("GRAPH_ERROR", "engine stopped"));
+        const child = this.child;
+        if (!child || child.exitCode !== null) {
+            this.child = null;
+            this.childPid = null;
+            return;
+        }
+        await new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                // Fallback: SIGKILL
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    // Already dead
+                }
+                resolve();
+            }, 2_000);
+            child.once("exit", () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                clearTimeout(timeout);
+                resolve();
+            }
+        });
+        this.child = null;
+        this.childPid = null;
+    }
+    // ── call ───────────────────────────────────────────────────────
+    /**
+     * Send a JSON-RPC 2.0 request and await the matching response.
+     * Rejects immediately when health is 'broken' or the engine is stopped.
+     */
+    async call(tool, params) {
+        if (this.healthState === "broken") {
+            throw makeGraphError("GRAPH_UNAVAILABLE", "engine breaker tripped");
+        }
+        if (this.stopping || !this.child || this.healthState !== "ready") {
+            throw makeGraphError("GRAPH_ERROR", "engine not ready");
+        }
+        const id = this.nextId++;
+        const timeoutMs = this.cfg.queryTimeoutMs ?? 5_000;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(makeGraphError("GRAPH_TIMEOUT", `call to ${tool} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: resolve,
+                reject,
+                timer,
+            });
+            const request = {
+                jsonrpc: "2.0",
+                id,
+                method: tool,
+                params,
+            };
+            try {
+                this.child.stdin.write(JSON.stringify(request) + "\n");
+            }
+            catch (err) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(makeGraphError("GRAPH_ERROR", `stdin write failed: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        });
+    }
+    // ── Private: spawn + handshake ─────────────────────────────────
+    async spawnAndHandshake() {
+        return new Promise((resolve, reject) => {
+            // Spawn without shell — argv array per ADR-10
+            const child = execa(this.binary, ["serve"], {
+                cwd: this.projectRoot,
+                stdio: ["pipe", "pipe", "pipe"],
+                reject: false,
+            });
+            this.child = child;
+            this.childPid = child.pid ?? null;
+            this.stdoutBuf = "";
+            // Route stderr to debug log — never to user stdout
+            child.stderr?.on("data", (chunk) => {
+                logger.debug(`[tokensave-serve stderr] ${String(chunk).trimEnd()}`);
+            });
+            let settled = false;
+            const handshakeTimer = setTimeout(() => {
+                if (!settled) {
+                    settled = true;
+                    reject(new Error("tokensave serve handshake timed out"));
+                }
+            }, HANDSHAKE_TIMEOUT_MS);
+            // Early exit before handshake
+            child.once("exit", (code, signal) => {
+                clearTimeout(handshakeTimer);
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(`tokensave serve exited before handshake (code=${String(code)}, signal=${String(signal)})`));
+                }
+                if (!this.stopping) {
+                    // Async crash handling — don't block handshake promise
+                    void this.onExit(code, signal);
+                }
+            });
+            // Process stdout line by line
+            child.stdout?.on("data", (chunk) => {
+                this.stdoutBuf += String(chunk);
+                const lines = this.stdoutBuf.split("\n");
+                // Keep the last (potentially incomplete) line in the buffer
+                this.stdoutBuf = lines.pop() ?? "";
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    let msg;
+                    try {
+                        msg = JSON.parse(trimmed);
+                    }
+                    catch {
+                        logger.debug(`[tokensave-serve] non-JSON stdout: ${trimmed}`);
+                        continue;
+                    }
+                    // Handshake: accept any valid JSON-RPC 2.0 message that indicates
+                    // the server is ready (notification with no id, or any response)
+                    if (!settled) {
+                        clearTimeout(handshakeTimer);
+                        settled = true;
+                        this.healthState = "ready";
+                        resolve();
+                    }
+                    // Correlation: if it has an id, it's a response to a pending call
+                    if (typeof msg.id === "number") {
+                        this.handleResponse(msg);
+                    }
+                }
+            });
+        });
+    }
+    // ── Private: response dispatch ─────────────────────────────────
+    handleResponse(msg) {
+        const entry = this.pending.get(msg.id);
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        this.pending.delete(msg.id);
+        if ("error" in msg && msg.error) {
+            entry.reject(makeGraphError("GRAPH_ERROR", msg.error.message ?? "JSON-RPC error"));
+        }
+        else {
+            entry.resolve(msg.result);
+        }
+    }
+    // ── Private: crash handling ────────────────────────────────────
+    async onExit(code, signal) {
+        if (this.stopping)
+            return;
+        // 1. Reject every in-flight pending immediately and clear the map
+        this.rejectAllPending(makeGraphError("GRAPH_ERROR", "engine restarted mid-call"));
+        // 2. Log the restart incident
+        try {
+            await this.incidents.append({
+                ts: new Date().toISOString(),
+                event: "restart",
+                pid: this.childPid,
+                exitCode: code,
+                signal: signal ?? null,
+            });
+        }
+        catch {
+            // Incident write failure must not block restart
+        }
+        // 3. Circuit breaker rolling window
+        const now = Date.now();
+        this.restartTimestamps.push(now);
+        this.restartTimestamps = this.restartTimestamps.filter((t) => now - t <= BREAKER_WINDOW_MS);
+        if (this.restartTimestamps.length >= BREAKER_MAX_RESTARTS) {
+            this.healthState = "broken";
+            logger.warn(`[graph] Circuit breaker tripped after ${this.restartTimestamps.length} restarts in ${BREAKER_WINDOW_MS / 1_000}s`);
+            try {
+                await this.incidents.append({
+                    ts: new Date().toISOString(),
+                    event: "breaker-tripped",
+                    restartCount: this.restartTimestamps.length,
+                    windowMs: BREAKER_WINDOW_MS,
+                });
+            }
+            catch {
+                // Incident write failure must not crash
+            }
+            return; // Do NOT respawn
+        }
+        // 4. Attempt restart
+        this.healthState = "restarting";
+        this.child = null;
+        this.childPid = null;
+        try {
+            await this.spawnAndHandshake();
+            this.healthState = "ready";
+        }
+        catch (err) {
+            logger.warn(`[graph] Restart failed: ${err instanceof Error ? err.message : String(err)}`);
+            this.healthState = "broken";
+        }
+    }
+    // ── Private: pending cleanup ───────────────────────────────────
+    rejectAllPending(err) {
+        for (const [id, entry] of this.pending) {
+            clearTimeout(entry.timer);
+            entry.reject(err);
+            this.pending.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=mcp-client.js.map

package/dist/graph/mcp-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.js","sourceRoot":"","sources":["../../src/graph/mcp-client.ts"],"names":[],"mappings":"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"}

package/dist/graph/onboarding-composer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * OnboardingComposer — pure renderer for .bober/onboarding/ markdown artifacts.
+ *
+ * Key design invariants:
+ * - render() is PURE. No I/O. Same inputs → same outputs.
+ * - writeAll() is the ONLY method that touches disk.
+ * - Marker convention guards human edits from being overwritten.
+ * - All markdown output is GFM-compatible (no extensions).
+ */
+import type { OnboardingInputs, OnboardingArtifacts } from "./types.js";
+export declare class OnboardingComposer {
+    /**
+     * Pure renderer. Takes typed inputs, returns 5 markdown strings.
+     * No I/O. No side effects. Deterministic.
+     */
+    render(inputs: OnboardingInputs): OnboardingArtifacts;
+    /**
+     * Write all 5 artifacts to `dir`, creating it if necessary.
+     *
+     * Marker convention:
+     * - File absent → write `${MARKER}\n\n${content}`.
+     * - File with marker → preserve everything above, replace below with `${MARKER}\n\n${content}`.
+     * - File without marker → throw with clear error (refuse to clobber user content).
+     *
+     * @param artifacts Result of render()
+     * @param dir       Target directory (created if missing)
+     */
+    writeAll(artifacts: OnboardingArtifacts, dir: string): Promise<void>;
+}
+//# sourceMappingURL=onboarding-composer.d.ts.map

package/dist/graph/onboarding-composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-composer.d.ts","sourceRoot":"","sources":["../../src/graph/onboarding-composer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAQxE,qBAAa,kBAAkB;IAC7B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,mBAAmB;IAUrD;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,SAAS,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAmB3E"}