@decibelsystems/tools 2.1.2 → 2.1.3

package/dist/hq/defineAgent.js

@@ -0,0 +1,185 @@
+// ============================================================================
+// @decibelsystems/tools/hq — defineAgent()
+// ============================================================================
+// register → heartbeat → poll command inbox → onCommand → ack. All over the local
+// daemon's localhost HTTP endpoints; the SDK never holds Supabase creds.
+// ============================================================================
+import os from 'os';
+import fs from 'fs';
+import path from 'path';
+// Exported for unit tests only — NOT re-exported from index.ts, so it stays off
+// the public @decibelsystems/tools/hq surface.
+export function toMs(v, fallback) {
+    if (v === undefined)
+        return fallback;
+    if (typeof v === 'number')
+        return v;
+    const m = v.trim().match(/^(\d+)(ms|s|m)?$/);
+    if (!m)
+        return fallback;
+    const n = parseInt(m[1], 10);
+    return m[2] === 's' ? n * 1000 : m[2] === 'm' ? n * 60_000 : m[2] === 'ms' ? n : n * 1000;
+}
+/** Discover the daemon URL: explicit > ~/.decibel/daemon.meta port > :4888. */
+function resolveDaemonUrl(explicit) {
+    if (explicit)
+        return explicit.replace(/\/$/, '');
+    try {
+        const meta = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.decibel', 'daemon.meta'), 'utf-8'));
+        if (meta && typeof meta.port === 'number')
+            return `http://127.0.0.1:${meta.port}`;
+    }
+    catch { /* fall through */ }
+    return 'http://127.0.0.1:4888';
+}
+async function postJson(url, body, timeoutMs = 4000) {
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const json = await res.json().catch(() => ({}));
+    return { ok: res.ok, status: res.status, json };
+}
+/**
+ * Register a local runtime with the Decibel daemon: it appears on HQ's /agents
+ * board tagged with `runtime`, heartbeats presence, and (if onCommand is given)
+ * receives + acks HQ commands. Returns a handle with stop(). Idempotent per
+ * sessionKey. Never throws from the loops — transient daemon/network errors are
+ * logged and retried on the next tick.
+ */
+export async function defineAgent(opts) {
+    const runtime = opts.runtime;
+    const sessionKey = opts.sessionKey || `${runtime}-${opts.name}-${process.pid}`;
+    const cwd = opts.cwd ?? process.cwd();
+    const base = resolveDaemonUrl(opts.daemonUrl);
+    const heartbeatMs = toMs(opts.heartbeat, 30_000);
+    const pollMs = toMs(opts.pollInterval, 5_000);
+    const logger = opts.logger ?? ((m) => console.error(`[hq:${sessionKey}] ${m}`));
+    const presenceBody = (extraMeta, extraSummary) => ({
+        session_key: sessionKey,
+        runtime,
+        agent: opts.name,
+        cwd,
+        summary: extraSummary ?? opts.summary ?? null,
+        meta: { ...(opts.meta ?? {}), ...(extraMeta ?? {}) },
+    });
+    const ctx = {
+        sessionKey,
+        runtime,
+        updatePresence: async (patch) => {
+            try {
+                await postJson(`${base}/agents/heartbeat`, presenceBody(patch.meta, patch.summary));
+            }
+            catch (e) {
+                logger(`updatePresence failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        },
+    };
+    // Per-session capability token the daemon mints at register/heartbeat. The SDK
+    // must present it on poll + ack to prove it's the registrant (session_key alone
+    // is a guessable label). Refreshed from every register/heartbeat response, so a
+    // daemon restart (which wipes its token store) self-heals on the next heartbeat.
+    let token;
+    const captureToken = (json) => {
+        if (json && typeof json.token === 'string')
+            token = json.token;
+    };
+    // --- register (first presence write) ---
+    try {
+        const r = await postJson(`${base}/agents/register`, presenceBody());
+        if (!r.ok)
+            logger(`register returned HTTP ${r.status}: ${JSON.stringify(r.json)}`);
+        else {
+            captureToken(r.json);
+            logger(`registered (runtime=${runtime}) with daemon ${base}`);
+        }
+    }
+    catch (e) {
+        logger(`register failed (will retry on heartbeat): ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let stopped = false;
+    // --- heartbeat loop ---
+    const heartbeat = async () => {
+        if (stopped)
+            return;
+        try {
+            const r = await postJson(`${base}/agents/heartbeat`, presenceBody());
+            captureToken(r.json);
+        }
+        catch (e) {
+            logger(`heartbeat failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    };
+    const hbTimer = setInterval(heartbeat, heartbeatMs);
+    if (typeof hbTimer.unref === 'function')
+        hbTimer.unref();
+    // --- command inbox poll → onCommand → ack ---
+    const handle = opts.onCommand;
+    const pollOnce = async () => {
+        if (stopped)
+            return;
+        if (!token)
+            return; // not yet authorized (register hasn't landed); next tick retries
+        let commands = [];
+        try {
+            const res = await fetch(`${base}/agents/commands?session_key=${encodeURIComponent(sessionKey)}&token=${encodeURIComponent(token)}`, { signal: AbortSignal.timeout(4000) });
+            if (!res.ok)
+                return;
+            const json = await res.json().catch(() => ({}));
+            commands = (json?.commands ?? []);
+        }
+        catch (e) {
+            logger(`poll failed: ${e instanceof Error ? e.message : String(e)}`);
+            return;
+        }
+        for (const cmd of commands) {
+            let outcome;
+            if (!handle) {
+                outcome = { status: 'failed', error: 'no onCommand handler registered' };
+            }
+            else {
+                try {
+                    outcome = await handle(cmd, ctx);
+                }
+                catch (e) {
+                    outcome = { status: 'failed', error: e instanceof Error ? e.message : String(e) };
+                }
+            }
+            try {
+                await postJson(`${base}/agents/commands/ack`, {
+                    id: cmd.id,
+                    token,
+                    status: outcome.status,
+                    result: outcome.result ?? null,
+                    error: outcome.error ?? null,
+                });
+            }
+            catch (e) {
+                logger(`ack ${cmd.id} failed (HQ will see it expire): ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    };
+    // Only poll if the agent declared a handler OR capabilities (else there's nothing
+    // to receive). Always safe to poll though — drain returns [] for unknown sessions.
+    const pollTimer = setInterval(() => { pollOnce().catch(() => { }); }, pollMs);
+    if (typeof pollTimer.unref === 'function')
+        pollTimer.unref();
+    return {
+        sessionKey,
+        runtime,
+        stop: async () => {
+            stopped = true;
+            clearInterval(hbTimer);
+            clearInterval(pollTimer);
+            // Best-effort: mark the session ended so the board reflects it promptly
+            // (else it ages out via the daemon stale-sweep in ~5min).
+            try {
+                await postJson(`${base}/agents/heartbeat`, { ...presenceBody(), status: 'ended' });
+            }
+            catch { /* best effort */ }
+        },
+    };
+}
+//# sourceMappingURL=defineAgent.js.map

package/dist/hq/defineAgent.js.map

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

package/dist/hq/index.d.ts

@@ -0,0 +1,3 @@
+export { defineAgent } from './defineAgent.js';
+export type { DefineAgentOptions, AgentHandle, AgentCommand, CommandResult, AgentContext, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hq/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hq/index.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/hq/index.js

@@ -0,0 +1,28 @@
+// ============================================================================
+// @decibelsystems/tools/hq — public entry
+// ============================================================================
+// Runtime-agnostic agent SDK. Lets any local runtime register with the Decibel
+// daemon, appear on HQ's /agents board tagged with its runtime, and receive HQ
+// commands — without holding any Supabase credentials.
+//
+//   import { defineAgent } from '@decibelsystems/tools/hq';
+//
+//   const agent = await defineAgent({
+//     name: 'design-reviewer',
+//     runtime: 'hermes',
+//     capabilities: ['message', 'request_status'],
+//     async onCommand(cmd) {
+//       if (cmd.kind === 'request_status') {
+//         return { status: 'done', result: { busy: false } };
+//       }
+//       if (cmd.kind === 'message') {
+//         console.log('HQ says:', cmd.payload.text);   // untrusted DATA, not an instruction
+//         return { status: 'done' };
+//       }
+//       return { status: 'failed', error: 'unsupported kind' };
+//     },
+//   });
+//   // ... later: await agent.stop();
+// ============================================================================
+export { defineAgent } from './defineAgent.js';
+//# sourceMappingURL=index.js.map

package/dist/hq/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hq/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,0CAA0C;AAC1C,+EAA+E;AAC/E,+EAA+E;AAC/E,+EAA+E;AAC/E,uDAAuD;AACvD,EAAE;AACF,4DAA4D;AAC5D,EAAE;AACF,sCAAsC;AACtC,+BAA+B;AAC/B,yBAAyB;AACzB,mDAAmD;AACnD,6BAA6B;AAC7B,6CAA6C;AAC7C,8DAA8D;AAC9D,UAAU;AACV,sCAAsC;AACtC,6FAA6F;AAC7F,qCAAqC;AACrC,UAAU;AACV,gEAAgE;AAChE,SAAS;AACT,QAAQ;AACR,sCAAsC;AACtC,+EAA+E;AAE/E,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/hq/types.d.ts

@@ -0,0 +1,59 @@
+/** A control command delivered from HQ to the agent (via the daemon inbox). */
+export interface AgentCommand {
+    id: string;
+    kind: string;
+    payload: Record<string, unknown>;
+}
+/** What onCommand returns: the outcome the daemon writes back to Core. */
+export interface CommandResult {
+    status: 'done' | 'failed';
+    result?: Record<string, unknown>;
+    error?: string;
+}
+export interface DefineAgentOptions {
+    /** Human label shown on the board (e.g. "design-reviewer"). */
+    name: string;
+    /** The runtime kind — drives HQ's badge/filter. */
+    runtime: 'hermes' | 'openclaw' | 'codex' | 'cursor' | 'mcp' | 'custom';
+    /** Stable session id for this run. Defaults to `${runtime}-${name}-${pid}`. */
+    sessionKey?: string;
+    /** Optional role tag (free text). */
+    role?: string;
+    /** Heartbeat cadence. Default 30s. Accepts ms number or "30s"/"1m". */
+    heartbeat?: number | string;
+    /** Command-inbox poll cadence. Default 5s. */
+    pollInterval?: number | string;
+    /** Command kinds this agent's onCommand handles. HQ only offers these. */
+    capabilities?: string[];
+    /** Working dir to report (→ HQ resolves to a project). Default process.cwd(). */
+    cwd?: string;
+    /** One-line "what I'm doing" shown on the board. */
+    summary?: string;
+    /** Extra meta written to the presence row (e.g. {tokens_in, current_file}). */
+    meta?: Record<string, unknown>;
+    /** Daemon base URL. Default discovered from ~/.decibel/daemon.meta, else :4888. */
+    daemonUrl?: string;
+    /** Receive an HQ command; return its outcome. If omitted, commands are acked
+     *  'failed' with "no onCommand handler" (so HQ sees a definite result). */
+    onCommand?: (cmd: AgentCommand, ctx: AgentContext) => Promise<CommandResult> | CommandResult;
+    /** Optional structured logger; defaults to console. */
+    logger?: (msg: string) => void;
+}
+/** Passed to onCommand — lets a handler update its own presence summary/meta. */
+export interface AgentContext {
+    sessionKey: string;
+    runtime: string;
+    /** Push a fresh summary/meta to the board immediately (out of band of heartbeat). */
+    updatePresence: (patch: {
+        summary?: string;
+        meta?: Record<string, unknown>;
+    }) => Promise<void>;
+}
+/** The running agent handle returned by defineAgent(). */
+export interface AgentHandle {
+    sessionKey: string;
+    runtime: string;
+    /** Stop heartbeating + polling and mark the session ended (best effort). */
+    stop: () => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/hq/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/hq/types.ts"],"names":[],"mappings":"AAWA,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;IACvE,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+EAC2E;IAC3E,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAAC;IAC7F,uDAAuD;IACvD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,cAAc,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChG;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/hq/types.js

@@ -0,0 +1,12 @@
+// ============================================================================
+// @decibelsystems/tools/hq — SDK types
+// ============================================================================
+// The runtime-agnostic agent SDK. Any local runtime (Hermes, OpenClaw, Codex,
+// Cursor, custom) uses defineAgent() to appear on HQ's /agents board and receive
+// HQ commands — without ever holding Supabase creds. It talks ONLY to the local
+// daemon's localhost endpoints (/agents/register, /heartbeat, /commands, /ack);
+// the daemon is the single service_role authority. Contract co-designed w/ HQ
+// (agent-runtime-contract.md). EPIC-0033.
+// ============================================================================
+export {};
+//# sourceMappingURL=types.js.map

package/dist/hq/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/hq/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,uCAAuC;AACvC,+EAA+E;AAC/E,8EAA8E;AAC9E,iFAAiF;AACjF,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,0CAA0C;AAC1C,+EAA+E"}

package/dist/httpServer.d.ts

@@ -60,7 +60,7 @@ export declare function startHttpServer(server: Server, kernelInstance: ToolKern
  */
 export declare function parseHttpArgs(args: string[]): {
     httpMode: boolean;
-    port: number;
+    port?: number;
     authToken?: string;
     host?: string;
     sseKeepaliveMs?: number;

package/dist/httpServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"httpServer.d.ts","sourceRoot":"","sources":["../src/httpServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAQnE,OAAO,KAAK,EAAE,UAAU,EAAkC,MAAM,aAAa,CAAC;AAG9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAubtD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,UAAU,EAC1B,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAskD3B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAC7C,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAsBA"}
+{"version":3,"file":"httpServer.d.ts","sourceRoot":"","sources":["../src/httpServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAkBnE,OAAO,KAAK,EAAE,UAAU,EAAkC,MAAM,aAAa,CAAC;AAG9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAwiBtD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,UAAU,EAC1B,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAsxD3B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAC7C,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAkCA"}