@decibelsystems/tools 2.2.0-beta.0 → 3.1.0

package/dist/runtime/circuitBreaker.js

@@ -0,0 +1,178 @@
+/**
+ * Per-facade circuit breaker.
+ *
+ * The failure this exists for: one facade's dependency wedges — Mother's
+ * Postgres stops accepting connections, Supabase hangs, a disk mount goes
+ * away — and every call into that facade sits on a socket until it times out.
+ * With six clients sharing one runtime that is enough to make the whole
+ * runtime feel dead, even though twenty other facades are fine. The breaker
+ * turns a slow, repeated failure into a fast, local one.
+ *
+ * WHAT COUNTS AS A FAULT is the whole design, because Decibel's tools rarely
+ * throw. `senken_trade_summary` catches its own Postgres error and returns
+ * `{isError: true}` (src/tools/senken.ts:117), so a breaker that only counted
+ * exceptions would never trip on the exact case it was built for. But counting
+ * every `isError` is worse: `create_issue` missing a title is an `isError`
+ * too, and five bad calls in a row from one confused agent must not take the
+ * sentinel facade offline for everyone.
+ *
+ * So the signal is *unresponsiveness*, not *unhappiness*:
+ *
+ *   - a thrown exception is always a fault (the handler didn't handle it)
+ *   - an `isError` result that took longer than `slowFailureMs` is a fault
+ *     (a dependency that times out is slow; a rejected argument is not)
+ *   - an `isError` result that came back fast is neither fault nor proof of
+ *     health — it leaves the counters exactly where they were
+ *   - a success closes the circuit and clears the count
+ *
+ * State machine: closed → (threshold consecutive faults) → open → (cooldown
+ * elapses) → half-open → success closes it, fault re-opens it. Half-open
+ * admits exactly one probe; concurrent callers are rejected until it lands, so
+ * a recovering database gets one connection attempt rather than six.
+ *
+ * The breaker never converts a working call into a failure — it only refuses
+ * calls it has good reason to believe would fail slowly.
+ */
+const DEFAULTS = {
+    failureThreshold: 5,
+    cooldownMs: 30_000,
+    slowFailureMs: 2_000,
+};
+export class CircuitBreakerRegistry {
+    circuits = new Map();
+    failureThreshold;
+    cooldownMs;
+    slowFailureMs;
+    now;
+    constructor(opts = {}) {
+        this.failureThreshold = opts.failureThreshold ?? DEFAULTS.failureThreshold;
+        this.cooldownMs = opts.cooldownMs ?? DEFAULTS.cooldownMs;
+        this.slowFailureMs = opts.slowFailureMs ?? DEFAULTS.slowFailureMs;
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * Ask whether a call to `key` may proceed. Transitions open → half_open when
+     * the cooldown has elapsed, and reserves the half-open probe for the caller
+     * it says yes to.
+     */
+    beforeCall(key) {
+        const c = this.circuits.get(key);
+        if (!c || c.state === 'closed')
+            return { allowed: true };
+        if (c.state === 'open') {
+            const elapsed = this.now() - c.openedAt;
+            if (elapsed < this.cooldownMs) {
+                return {
+                    allowed: false,
+                    retryAfterMs: this.cooldownMs - elapsed,
+                    lastError: c.lastError,
+                    openedAt: new Date(c.openedAt).toISOString(),
+                };
+            }
+            // Cooldown elapsed — this caller becomes the probe.
+            c.state = 'half_open';
+            c.probeInFlight = true;
+            return { allowed: true };
+        }
+        // half_open: one probe at a time.
+        if (c.probeInFlight) {
+            return {
+                allowed: false,
+                retryAfterMs: this.cooldownMs,
+                lastError: c.lastError,
+                openedAt: new Date(c.openedAt).toISOString(),
+            };
+        }
+        c.probeInFlight = true;
+        return { allowed: true };
+    }
+    /**
+     * Report what happened. `threw` and `durationMs` decide whether this was a
+     * fault; see the module comment for why `isError` alone is not enough and
+     * not too much.
+     */
+    afterCall(key, outcome) {
+        const fault = outcome.threw || (outcome.isError && outcome.durationMs >= this.slowFailureMs);
+        if (fault) {
+            this.recordFault(key, outcome.error);
+            return;
+        }
+        if (outcome.isError) {
+            // Fast domain error: says nothing about the dependency's health. Release
+            // the probe if we were half-open, but leave the fault count alone.
+            const c = this.circuits.get(key);
+            if (c?.state === 'half_open')
+                this.close(key);
+            else if (c)
+                c.probeInFlight = false;
+            return;
+        }
+        this.recordSuccess(key);
+    }
+    recordSuccess(key) {
+        const c = this.circuits.get(key);
+        if (!c)
+            return;
+        this.close(key);
+    }
+    recordFault(key, error) {
+        const c = this.circuits.get(key) ?? {
+            state: 'closed',
+            faults: 0,
+            openedAt: 0,
+            probeInFlight: false,
+        };
+        c.lastError = error;
+        c.probeInFlight = false;
+        if (c.state === 'half_open') {
+            // The probe failed — straight back to open, full cooldown.
+            c.state = 'open';
+            c.openedAt = this.now();
+            this.circuits.set(key, c);
+            return;
+        }
+        c.faults += 1;
+        if (c.faults >= this.failureThreshold) {
+            c.state = 'open';
+            c.openedAt = this.now();
+        }
+        this.circuits.set(key, c);
+    }
+    state(key) {
+        return this.circuits.get(key)?.state ?? 'closed';
+    }
+    /** Open circuits only — a healthy runtime reports `{}`. */
+    snapshot() {
+        const out = {};
+        for (const [key, c] of this.circuits) {
+            if (c.state === 'closed' && c.faults === 0)
+                continue;
+            out[key] = {
+                state: c.state,
+                consecutive_faults: c.faults,
+                ...(c.state === 'closed' ? {} : {
+                    opened_at: new Date(c.openedAt).toISOString(),
+                    retry_after_ms: Math.max(0, this.cooldownMs - (this.now() - c.openedAt)),
+                }),
+                ...(c.lastError ? { last_error: c.lastError } : {}),
+            };
+        }
+        return out;
+    }
+    reset(key) {
+        if (key === undefined)
+            this.circuits.clear();
+        else
+            this.circuits.delete(key);
+    }
+    close(key) {
+        const c = this.circuits.get(key);
+        if (!c)
+            return;
+        c.state = 'closed';
+        c.faults = 0;
+        c.probeInFlight = false;
+        c.openedAt = 0;
+    }
+}
+//# sourceMappingURL=circuitBreaker.js.map

package/dist/runtime/circuitBreaker.js.map

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

package/dist/runtime/daemonMeta.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Resolved per call rather than captured at import, the way daemonConfig does:
+ * os.homedir() tracks $HOME, and a module-level constant freezes whatever it
+ * was when the file was first loaded — which makes this unverifiable in a test
+ * and wrong in any process that changes HOME.
+ */
+export declare function decibelHome(): string;
+/**
+ * DECIBEL_DAEMON_SIDECAR=<dir> marks a second daemon run beside the real one
+ * (a branch build on another port, decibel-hq ADR-0018 testing). Its pid,
+ * meta and logs live in <dir>, so it never takes over the machine's
+ * advertisement, and server.ts skips the machine singletons (peer broker,
+ * presence, HQ command dispatch, chat). Config, env and projects stay shared.
+ */
+export declare function sidecarDir(): string | null;
+/** Where this daemon's pid, meta and logs live: the sidecar dir, else ~/.decibel. */
+export declare function daemonStateDir(): string;
+export declare function metaPath(): string;
+/** The port the daemon binds when nothing says otherwise. */
+export declare const DEFAULT_DAEMON_PORT = 4888;
+export interface DaemonMeta {
+    started_at: string;
+    crash_count: number;
+    port?: number;
+    pid?: number;
+}
+/**
+ * Is this pid a process that currently exists?
+ *
+ * Signal 0 performs the permission and existence checks without delivering
+ * anything. EPERM means the process is there and owned by someone else, which
+ * is still alive — only ESRCH means gone.
+ */
+export declare function isPidAlive(pid: number | undefined): boolean;
+export declare function readDaemonMeta(): DaemonMeta | null;
+/**
+ * The advertised port, or undefined when there is no usable advertisement.
+ *
+ * An entry whose pid is dead is treated as absent rather than followed. That is
+ * the whole point: a stale port is worse than no port, because callers fall
+ * back to the default when there is nothing to read and dial a corpse when
+ * there is.
+ */
+export declare function advertisedPort(): number | undefined;
+/** Discovery order shared by every client: explicit > env > meta > default. */
+export declare function resolveDaemonPort(explicit?: number): number;
+/**
+ * True when someone else is currently advertising — a live pid that is not us.
+ * Taking discovery from a running daemon is how a second instance silently
+ * breaks the first one's clients, so callers refuse rather than overwrite.
+ */
+export declare function heldByAnotherProcess(): DaemonMeta | null;
+//# sourceMappingURL=daemonMeta.d.ts.map

package/dist/runtime/daemonMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemonMeta.d.ts","sourceRoot":"","sources":["../../src/runtime/daemonMeta.ts"],"names":[],"mappings":"AA6BA;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CAG1C;AAED,qFAAqF;AACrF,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAQ3D;AAED,wBAAgB,cAAc,IAAI,UAAU,GAAG,IAAI,CAOlD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAKnD;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,GAAG,IAAI,CAIxD"}

package/dist/runtime/daemonMeta.js

@@ -0,0 +1,121 @@
+// ============================================================================
+// daemon.meta — machine-global daemon discovery
+// ============================================================================
+//
+// ~/.decibel/daemon.meta is how every client on the machine finds the daemon:
+// the session-init hook, the issue-close hook, the HQ client, ensureRuntime,
+// the CLI. One small JSON file that three modules used to parse for themselves.
+//
+// ISS-0179. Two defects, and the second is the worse one:
+//
+//   1. ANY `--http` run advertised itself here, not just `--daemon`. Starting a
+//      throwaway server on another port — a test, a second checkout, a port
+//      conflict, a demo — silently redirected every hook on the machine to it.
+//
+//   2. Nothing removed a stale entry and no reader checked one. When that
+//      throwaway process died, the entry stayed, and every hook kept dialling a
+//      port with nothing behind it. The failure was silent at every layer: curl
+//      got connection-refused, the hook read empty output as "nothing to do",
+//      and the user saw a successful commit.
+//
+// The entry records the pid that wrote it, which is enough to tell a live
+// advertisement from a dead one. That check lives here, once, because the
+// reason it was missing is that it would have had to be written three times.
+// ============================================================================
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+/**
+ * Resolved per call rather than captured at import, the way daemonConfig does:
+ * os.homedir() tracks $HOME, and a module-level constant freezes whatever it
+ * was when the file was first loaded — which makes this unverifiable in a test
+ * and wrong in any process that changes HOME.
+ */
+export function decibelHome() {
+    return path.join(os.homedir(), '.decibel');
+}
+/**
+ * DECIBEL_DAEMON_SIDECAR=<dir> marks a second daemon run beside the real one
+ * (a branch build on another port, decibel-hq ADR-0018 testing). Its pid,
+ * meta and logs live in <dir>, so it never takes over the machine's
+ * advertisement, and server.ts skips the machine singletons (peer broker,
+ * presence, HQ command dispatch, chat). Config, env and projects stay shared.
+ */
+export function sidecarDir() {
+    const dir = process.env.DECIBEL_DAEMON_SIDECAR;
+    return dir ? path.resolve(dir) : null;
+}
+/** Where this daemon's pid, meta and logs live: the sidecar dir, else ~/.decibel. */
+export function daemonStateDir() {
+    return sidecarDir() ?? decibelHome();
+}
+export function metaPath() {
+    return path.join(daemonStateDir(), 'daemon.meta');
+}
+/** The port the daemon binds when nothing says otherwise. */
+export const DEFAULT_DAEMON_PORT = 4888;
+/**
+ * Is this pid a process that currently exists?
+ *
+ * Signal 0 performs the permission and existence checks without delivering
+ * anything. EPERM means the process is there and owned by someone else, which
+ * is still alive — only ESRCH means gone.
+ */
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+export function readDaemonMeta() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(metaPath(), 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The advertised port, or undefined when there is no usable advertisement.
+ *
+ * An entry whose pid is dead is treated as absent rather than followed. That is
+ * the whole point: a stale port is worse than no port, because callers fall
+ * back to the default when there is nothing to read and dial a corpse when
+ * there is.
+ */
+export function advertisedPort() {
+    const meta = readDaemonMeta();
+    if (!meta || !Number.isInteger(meta.port))
+        return undefined;
+    if (meta.pid !== undefined && !isPidAlive(meta.pid))
+        return undefined;
+    return meta.port;
+}
+/** Discovery order shared by every client: explicit > env > meta > default. */
+export function resolveDaemonPort(explicit) {
+    if (Number.isInteger(explicit) && explicit > 0 && explicit < 65536) {
+        return explicit;
+    }
+    const fromEnv = Number(process.env.DECIBEL_DAEMON_PORT);
+    if (Number.isInteger(fromEnv) && fromEnv > 0 && fromEnv < 65536)
+        return fromEnv;
+    return advertisedPort() ?? DEFAULT_DAEMON_PORT;
+}
+/**
+ * True when someone else is currently advertising — a live pid that is not us.
+ * Taking discovery from a running daemon is how a second instance silently
+ * breaks the first one's clients, so callers refuse rather than overwrite.
+ */
+export function heldByAnotherProcess() {
+    const meta = readDaemonMeta();
+    if (!meta || meta.pid === undefined || meta.pid === process.pid)
+        return null;
+    return isPidAlive(meta.pid) ? meta : null;
+}
+//# sourceMappingURL=daemonMeta.js.map

package/dist/runtime/daemonMeta.js.map

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

package/dist/runtime/ensureRuntime.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ensureRuntime — the one lifecycle primitive.
+ *
+ * Every surface that needs the Decibel runtime (MCP adapters, the CLI, the
+ * VS Code extension, shell hooks) calls this. None of them should carry their
+ * own "is the daemon up? should I start it?" logic — that duplication is how
+ * five subtly different startup behaviours end up in one codebase.
+ *
+ * Two things this deliberately does NOT do:
+ *
+ *   1. It does not use the PID file as the source of truth. `~/.decibel/daemon.pid`
+ *      goes stale — an unclean exit leaves a pid pointing at nothing, or worse,
+ *      at a recycled pid belonging to an unrelated process. A successful
+ *      `/health` response is the only proof the runtime is actually serving.
+ *
+ *   2. It does not check-then-spawn. When six clients start at once, six
+ *      "is it running? no → start it" sequences race and you get six daemons
+ *      fighting over one port. Startup is arbitrated by an atomic O_EXCL lock
+ *      file: exactly one caller wins the right to spawn, and the losers wait
+ *      for the winner's daemon rather than starting their own.
+ */
+/** Default port the daemon binds. Overridden by daemon.meta or DECIBEL_DAEMON_PORT. */
+export declare const DEFAULT_RUNTIME_PORT = 4888;
+export interface RuntimeHealth {
+    status: string;
+    version: string;
+    protocol_version?: string;
+    pid: number;
+    uptime_ms: number;
+    facade_count: number;
+    license_tier: string;
+    [key: string]: unknown;
+}
+export interface RuntimeHandle {
+    /** Base URL, e.g. `http://127.0.0.1:4888`. No trailing slash. */
+    url: string;
+    port: number;
+    /** PID of the serving runtime — reported by /health, not read from a pid file. */
+    pid: number;
+    /** Package version of the running runtime. */
+    version: string;
+    /** Wire protocol the running runtime speaks. */
+    protocolVersion: string;
+    licenseTier: string;
+    /** True when this call started the runtime; false when it was already up. */
+    spawned: boolean;
+    health: RuntimeHealth;
+}
+export interface EnsureRuntimeOptions {
+    /** Protocol version this client requires. Defaults to the compiled-in version. */
+    protocolVersion?: string;
+    /** Port override. Falls back to daemon.meta, then DECIBEL_DAEMON_PORT, then 4888. */
+    port?: number;
+    /** Total time to wait for a runtime to become healthy. */
+    timeoutMs?: number;
+    /**
+     * When false, never spawn — probe only, and throw if nothing is serving.
+     * Used by callers that must not have side effects (status commands, health
+     * checks, anything running inside a hook with a hard timeout).
+     */
+    autoStart?: boolean;
+    /** Absolute path to the runtime entry point. Defaults to this package's dist/server.js. */
+    serverEntry?: string;
+}
+/** Thrown when a runtime is serving but speaks an incompatible protocol. */
+export declare class RuntimeProtocolMismatchError extends Error {
+    readonly serverVersion: string | undefined;
+    readonly clientVersion: string;
+    constructor(serverVersion: string | undefined, clientVersion: string, reason: string);
+}
+/** Thrown when no runtime is serving and one could not be started. */
+export declare class RuntimeUnavailableError extends Error {
+    constructor(port: number, detail: string);
+}
+/**
+ * Resolve the port to talk to, in precedence order:
+ *   explicit option → DECIBEL_DAEMON_PORT → daemon.meta → default.
+ *
+ * daemon.meta is a *hint*, not proof of life — it records the port the daemon
+ * last bound. We still confirm with /health before trusting anything.
+ */
+export declare function resolveRuntimePort(explicit?: number): number;
+/**
+ * GET /health. Returns null when nothing is listening or the response is not a
+ * usable health payload — callers treat null as "no runtime here", never as an
+ * error worth surfacing.
+ */
+export declare function probeRuntime(port: number): Promise<RuntimeHealth | null>;
+/**
+ * Return a handle to a healthy, protocol-compatible runtime, starting one if
+ * needed.
+ *
+ * Throws rather than degrading:
+ *   - RuntimeProtocolMismatchError when something is serving but speaks a
+ *     contract this client does not understand.
+ *   - RuntimeUnavailableError when nothing is serving and none could be started.
+ *
+ * Callers must not silently fall back to doing the work in-process. A client
+ * that quietly becomes a second writer is exactly the failure this runtime
+ * exists to prevent.
+ */
+export declare function ensureRuntime(options?: EnsureRuntimeOptions): Promise<RuntimeHandle>;
+//# sourceMappingURL=ensureRuntime.d.ts.map

package/dist/runtime/ensureRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureRuntime.d.ts","sourceRoot":"","sources":["../../src/runtime/ensureRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAeH,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAczC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,4EAA4E;AAC5E,qBAAa,4BAA6B,SAAQ,KAAK;IAEnD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS;IAC1C,QAAQ,CAAC,aAAa,EAAE,MAAM;gBADrB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,aAAa,EAAE,MAAM,EAC9B,MAAM,EAAE,MAAM;CASjB;AAED,sEAAsE;AACtE,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQzC;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAY5D;AAMD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAW9E;AAgHD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAkExB"}