dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/agents/src/audit.js

@@ -0,0 +1,122 @@
+// @dexterm/agents — the audit log (task-1345). Every agent connection, call, refusal, proposal and
+// roster action is one row. Two stores behind one interface: in memory (tests, --fixtures) and
+// node:sqlite in the shared dexterm DB (live / replay), so `dexterm agent audit` and the roster popup
+// read the same rows. Detail strings are firewalled at write time (agent-supplied text can never carry
+// an escape sequence or a 10 KB payload into the terminal or a model).
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { firewallText } from '../../data/src/index.js';
+export const AUDIT_DETAIL_MAX = 160;
+/** Make a detail string safe for the terminal and the log: firewall, single line, capped. */
+export function auditDetail(s) {
+    const r = firewallText(s === undefined || s === null ? '' : String(s), { max: AUDIT_DETAIL_MAX, keepUrls: false });
+    return r.text.replace(/\s+/g, ' ').trim();
+}
+export class MemoryAuditLog {
+    rows = [];
+    seq = 0;
+    now;
+    cap;
+    constructor(opts = {}) { this.now = opts.now ?? (() => Date.now()); this.cap = opts.cap ?? 5000; }
+    append(e) {
+        const row = { ...e, id: ++this.seq, t: e.t ?? this.now(), detail: auditDetail(e.detail), agentName: auditDetail(e.agentName).slice(0, 24), tool: auditDetail(e.tool).slice(0, 64) };
+        this.rows.push(row);
+        if (this.rows.length > this.cap)
+            this.rows.splice(0, this.rows.length - this.cap);
+        return row;
+    }
+    recent(limit = 50, filter = {}) {
+        const out = [];
+        for (let i = this.rows.length - 1; i >= 0 && out.length < limit; i--) {
+            const r = this.rows[i];
+            if (filter.agentId && r.agentId !== filter.agentId)
+                continue;
+            if (filter.agentName && r.agentName !== filter.agentName)
+                continue;
+            if (filter.kind && r.kind !== filter.kind)
+                continue;
+            if (filter.since !== undefined && r.t < filter.since)
+                continue;
+            out.push({ ...r });
+        }
+        return out;
+    }
+    counts(agentId) {
+        let calls = 0, refused = 0, proposals = 0, lastAt = null;
+        for (const r of this.rows) {
+            if (r.agentId !== agentId)
+                continue;
+            if (r.kind === 'call')
+                calls++;
+            else if (r.kind === 'refused')
+                refused++;
+            else if (r.kind === 'proposal')
+                proposals++;
+            if (lastAt === null || r.t > lastAt)
+                lastAt = r.t;
+        }
+        return { calls, refused, proposals, lastAt };
+    }
+    close() { }
+}
+export class SqliteAuditLog {
+    db;
+    now;
+    constructor(path, opts = {}) {
+        if (path !== ':memory:')
+            mkdirSync(dirname(path), { recursive: true });
+        this.db = new DatabaseSync(path);
+        this.now = opts.now ?? (() => Date.now());
+        this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      CREATE TABLE IF NOT EXISTS agent_audit (
+        id INTEGER PRIMARY KEY AUTOINCREMENT, t INTEGER NOT NULL, agent_id TEXT, agent_name TEXT NOT NULL, session TEXT,
+        kind TEXT NOT NULL, tool TEXT NOT NULL, detail TEXT NOT NULL, ok INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS agent_audit_agent ON agent_audit(agent_id, t);
+    `);
+    }
+    append(e) {
+        const t = e.t ?? this.now();
+        const detail = auditDetail(e.detail);
+        const name = auditDetail(e.agentName).slice(0, 24);
+        const tool = auditDetail(e.tool).slice(0, 64);
+        const r = this.db.prepare('INSERT INTO agent_audit (t, agent_id, agent_name, session, kind, tool, detail, ok) VALUES (?, ?, ?, ?, ?, ?, ?, ?)')
+            .run(t, e.agentId, name, e.session, e.kind, tool, detail, e.ok ? 1 : 0);
+        return { ...e, id: Number(r.lastInsertRowid), t, detail, agentName: name, tool };
+    }
+    recent(limit = 50, filter = {}) {
+        const where = [];
+        const params = [];
+        if (filter.agentId) {
+            where.push('agent_id = ?');
+            params.push(filter.agentId);
+        }
+        if (filter.agentName) {
+            where.push('agent_name = ?');
+            params.push(filter.agentName);
+        }
+        if (filter.kind) {
+            where.push('kind = ?');
+            params.push(filter.kind);
+        }
+        if (filter.since !== undefined) {
+            where.push('t >= ?');
+            params.push(filter.since);
+        }
+        const sql = `SELECT id, t, agent_id, agent_name, session, kind, tool, detail, ok FROM agent_audit${where.length ? ' WHERE ' + where.join(' AND ') : ''} ORDER BY id DESC LIMIT ?`;
+        const rows = this.db.prepare(sql).all(...params, Math.max(1, Math.min(limit, 2000)));
+        return rows.map((r) => ({ id: Number(r.id), t: Number(r.t), agentId: r.agent_id ?? null, agentName: String(r.agent_name), session: r.session ?? null, kind: r.kind, tool: String(r.tool), detail: String(r.detail), ok: Number(r.ok) === 1 }));
+    }
+    counts(agentId) {
+        const r = this.db.prepare(`SELECT
+      SUM(CASE WHEN kind = 'call' THEN 1 ELSE 0 END) AS calls, SUM(CASE WHEN kind = 'refused' THEN 1 ELSE 0 END) AS refused,
+      SUM(CASE WHEN kind = 'proposal' THEN 1 ELSE 0 END) AS proposals, MAX(t) AS last FROM agent_audit WHERE agent_id = ?`).get(agentId);
+        return { calls: Number(r.calls ?? 0), refused: Number(r.refused ?? 0), proposals: Number(r.proposals ?? 0), lastAt: r.last === null || r.last === undefined ? null : Number(r.last) };
+    }
+    close() { try {
+        this.db.close();
+    }
+    catch { /* ignore */ } }
+}

package/dist/packages/agents/src/bus.js

@@ -0,0 +1,394 @@
+// @dexterm/agents — the loopback agent bus (task-1345, tier 2). A WebSocket + JSON-RPC 2.0 server on
+// 127.0.0.1 that external agents connect to. Every connection authenticates once with a registered name
+// + token (identity.ts); every call passes the gate (gate.ts) before any execution; every connect, call,
+// refusal, proposal and disconnect is one audit row. Agents can subscribe to live topics (new pairs,
+// trades, alerts, screen) and create proposals the user must confirm. No bus path can arm, sign, send,
+// raise a cap, change the gate, or touch a wallet/mandate/signer — the gate's never-list sees to that.
+import { writeFileSync, rmSync, mkdirSync, chmodSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createWsServer } from "./ws.js";
+import { AgentGate } from "./gate.js";
+import { AgentRegistry, dextermHome, looksLikeToken, AGENT_NAME_RE } from "./identity.js";
+import { lowerTier, isTier, toolsForTier } from "./tiers.js";
+import { toolSchema, agentTool, toolsForTierList } from "./tools.js";
+import { isTopic, scrubStrings } from "./executor.js";
+import { TOOL_TO_KIND } from "./proposals.js";
+import { firewallText } from '../../data/src/index.js';
+export const BUS_PROTOCOL = 'dexterm-agent-bus/1';
+/** A connection that does not authenticate within this window is closed. */
+export const HELLO_TIMEOUT_MS = 10_000;
+/** Hard cap on simultaneous un-authenticated sockets (a connect flood cannot exhaust memory). */
+export const MAX_PENDING = 16;
+export class AgentBus {
+    server = null;
+    conns = new Set();
+    registry;
+    audit;
+    executor;
+    proposals;
+    feed;
+    gate;
+    now;
+    paused = new Set();
+    discoveryPath;
+    feedOff = null;
+    sessionSeq = 0;
+    constructor(opts) {
+        this.registry = opts.registry;
+        this.audit = opts.audit;
+        this.executor = opts.executor;
+        this.proposals = opts.proposals;
+        this.feed = opts.feed ?? null;
+        this.now = opts.now ?? (() => Date.now());
+        this.discoveryPath = opts.discoveryPath === undefined ? join(dextermHome(opts.env), 'agent-bus.json') : opts.discoveryPath;
+        this.gate = new AgentGate({
+            audit: this.audit,
+            now: this.now,
+            isPaused: (id) => this.paused.has(id),
+            onFlood: (id, name) => { this.audit.append({ agentId: id, agentName: name, session: null, kind: 'pause', tool: '-', detail: 'auto-paused by the flood breaker', ok: false }); },
+        });
+    }
+    get port() { return this.server?.port ?? 0; }
+    get connectionCount() { return this.conns.size; }
+    async start() {
+        this.server = await createWsServer({ port: undefined, onConnection: (ws) => this.onConnection(ws) });
+        if (this.feed)
+            this.feedOff = this.feed.on((ev) => this.fanout(ev));
+        this.writeDiscovery();
+        return this.server.port;
+    }
+    async close() {
+        this.feedOff?.();
+        this.feedOff = null;
+        for (const c of [...this.conns]) {
+            try {
+                c.ws.close(1001);
+            }
+            catch { /* ignore */ }
+        }
+        this.conns.clear();
+        if (this.discoveryPath) {
+            try {
+                rmSync(this.discoveryPath);
+            }
+            catch { /* ignore */ }
+        }
+        if (this.server) {
+            await this.server.close();
+            this.server = null;
+        }
+    }
+    // ----- roster/CLI actions (user side; never reachable from an agent path) -----
+    pauseAgent(name) {
+        const a = this.registry.get(name);
+        if (!a)
+            return false;
+        this.paused.add(a.id);
+        this.registry.setPaused(name, true);
+        this.audit.append({ agentId: a.id, agentName: name, session: null, kind: 'pause', tool: '-', detail: 'paused by the user', ok: false });
+        return true;
+    }
+    resumeAgent(name) {
+        const a = this.registry.get(name);
+        if (!a)
+            return false;
+        this.paused.delete(a.id);
+        this.registry.setPaused(name, false);
+        this.gate.clearFlood(a.id);
+        this.audit.append({ agentId: a.id, agentName: name, session: null, kind: 'resume', tool: '-', detail: 'resumed by the user', ok: true });
+        return true;
+    }
+    /** Kick: close every live session for an agent now (the token keeps working — use `rotate`/`remove` to revoke it). */
+    kickAgent(name) {
+        const a = this.registry.get(name);
+        if (!a)
+            return 0;
+        let n = 0;
+        for (const c of [...this.conns])
+            if (c.session && c.session.agentId === a.id) {
+                c.session.closed = true;
+                c.session.closedReason = 'kicked';
+                try {
+                    c.ws.close(4003);
+                }
+                catch { /* ignore */ }
+                n++;
+            }
+        this.audit.append({ agentId: a.id, agentName: name, session: null, kind: 'kick', tool: '-', detail: `kicked ${n} session(s)`, ok: true });
+        return n;
+    }
+    /** For the roster (tier 4): live sessions + usage per connected agent. */
+    roster() {
+        const byAgent = new Map();
+        for (const c of this.conns) {
+            const s = c.session;
+            if (!s)
+                continue;
+            const cur = byAgent.get(s.agentId) ?? { name: s.agentName, tier: s.tier, sessions: 0, client: s.client, lastActivity: 0, topics: new Set() };
+            cur.sessions++;
+            cur.lastActivity = Math.max(cur.lastActivity, s.lastActivity);
+            for (const t of s.topics)
+                cur.topics.add(t);
+            byAgent.set(s.agentId, cur);
+        }
+        return [...byAgent].map(([agentId, v]) => ({ agentId, name: v.name, tier: v.tier, sessions: v.sessions, client: v.client, lastActivity: v.lastActivity, topics: [...v.topics], usage: this.gate.usage(agentId), counts: this.audit.counts(agentId), paused: this.paused.has(agentId) }));
+    }
+    // ----- connection lifecycle -----
+    onConnection(ws) {
+        if (this.conns.size >= MAX_PENDING + 64) {
+            ws.close(1013);
+            return;
+        } // overall cap (pending + authed)
+        const conn = { ws, session: null, helloTimer: null };
+        this.conns.add(conn);
+        conn.helloTimer = setTimeout(() => { if (!conn.session) {
+            try {
+                ws.close(4001);
+            }
+            catch { /* ignore */ }
+        } }, HELLO_TIMEOUT_MS);
+        conn.helloTimer.unref?.();
+        ws.onMessage = (text) => this.onMessage(conn, text);
+        ws.onClose = () => this.onClose(conn);
+    }
+    onClose(conn) {
+        if (conn.helloTimer)
+            clearTimeout(conn.helloTimer);
+        if (conn.session)
+            this.audit.append({ agentId: conn.session.agentId, agentName: conn.session.agentName, session: conn.session.id, kind: 'disconnect', tool: '-', detail: 'socket closed', ok: true });
+        this.conns.delete(conn);
+    }
+    reply(conn, id, result) { conn.ws.send({ jsonrpc: '2.0', id, result }); }
+    fail(conn, id, code, message, data) { conn.ws.send({ jsonrpc: '2.0', id, error: { code, message, ...(data ? { data } : {}) } }); }
+    onMessage(conn, text) {
+        if (text.length > 256 * 1024) {
+            conn.ws.close(1009);
+            return;
+        }
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            this.fail(conn, null, -32700, 'parse error');
+            return;
+        }
+        if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+            this.fail(conn, msg?.id ?? null, -32600, 'invalid request');
+            return;
+        }
+        const id = msg.id ?? null;
+        const params = (msg.params && typeof msg.params === 'object' && !Array.isArray(msg.params)) ? msg.params : {};
+        if (msg.method === 'hello') {
+            void this.onHello(conn, id, params);
+            return;
+        }
+        if (msg.method === 'ping') {
+            this.reply(conn, id, { pong: true, t: this.now() });
+            return;
+        }
+        if (!conn.session) {
+            this.fail(conn, id, -32001, 'say hello first (authenticate with your agent name + token)');
+            return;
+        }
+        if (msg.method === 'tools/list') {
+            this.reply(conn, id, { tools: this.visibleToolDefs(conn.session) });
+            return;
+        }
+        if (msg.method === 'tools/call') {
+            void this.onCall(conn, id, params);
+            return;
+        }
+        this.fail(conn, id, -32601, `method not found: ${String(msg.method).slice(0, 40)}`);
+    }
+    async onHello(conn, id, params) {
+        if (conn.session) {
+            this.fail(conn, id, -32002, 'already authenticated on this connection');
+            return;
+        }
+        const name = params.name;
+        const token = params.token;
+        if (typeof name !== 'string' || !AGENT_NAME_RE.test(name) || !looksLikeToken(token)) {
+            this.audit.append({ agentId: null, agentName: typeof name === 'string' ? name.slice(0, 24) : '?', session: null, kind: 'refused', tool: 'hello', detail: 'bad credentials', ok: false });
+            this.fail(conn, id, -32010, 'authentication failed');
+            try {
+                conn.ws.close(4002);
+            }
+            catch { /* ignore */ }
+            return;
+        }
+        const rec = this.registry.verify(name, token);
+        if (!rec) {
+            this.audit.append({ agentId: null, agentName: name.slice(0, 24), session: null, kind: 'refused', tool: 'hello', detail: 'unknown agent or wrong token', ok: false });
+            this.fail(conn, id, -32010, 'authentication failed');
+            try {
+                conn.ws.close(4002);
+            }
+            catch { /* ignore */ }
+            return;
+        }
+        // connection cap per agent
+        const limits = this.gate.limitsFor(rec.id);
+        const live = [...this.conns].filter((c) => c.session && c.session.agentId === rec.id).length;
+        if (live >= limits.connections) {
+            this.fail(conn, id, -32011, `too many connections for this agent (max ${limits.connections})`);
+            try {
+                conn.ws.close(4009);
+            }
+            catch { /* ignore */ }
+            return;
+        }
+        // requested tier can only LOWER the granted one; a bogus request is ignored
+        const reqTier = isTier(params.tier) ? params.tier : rec.tier;
+        const tier = lowerTier(rec.tier, reqTier);
+        const client = firewallText(params.client, { max: 40 }).text.replace(/\s+/g, ' ').trim() || 'unknown';
+        if (rec.paused)
+            this.paused.add(rec.id);
+        this.gate.setAgentLimits(rec.id, rec.limits);
+        const scope = rec.scope && rec.scope.length ? new Set(rec.scope) : null;
+        const session = { id: `sess_${(++this.sessionSeq).toString(36)}`, agentId: rec.id, agentName: rec.name, tier, transport: 'bus', openedAt: this.now(), lastActivity: this.now(), closed: false, closedReason: null, client, topics: new Set(), scope };
+        conn.session = session;
+        if (conn.helloTimer) {
+            clearTimeout(conn.helloTimer);
+            conn.helloTimer = null;
+        }
+        this.audit.append({ agentId: rec.id, agentName: rec.name, session: session.id, kind: 'connect', tool: '-', detail: `tier ${tier}${scope ? ` · mandate[${[...scope].join(',')}]` : ''} · ${client} · ${conn.ws.remote}`, ok: true });
+        this.reply(conn, id, { protocol: BUS_PROTOCOL, agent: rec.name, tier, grantedTier: rec.tier, tools: this.visibleTools(session), mandate: scope ? [...scope] : null, paused: rec.paused });
+    }
+    async onCall(conn, id, params) {
+        const session = conn.session;
+        if (!session) {
+            this.fail(conn, id, -32001, 'say hello first');
+            return;
+        }
+        const name = typeof params.name === 'string' ? params.name : '';
+        const args = (params.arguments && typeof params.arguments === 'object' && !Array.isArray(params.arguments)) ? params.arguments : {};
+        const g = this.gate.check(session, { tool: name, args, schema: toolSchema(name) });
+        if (!g.ok) {
+            this.fail(conn, id, -32020, g.error, { code: g.code });
+            return;
+        }
+        try {
+            // bus-native observe
+            if (name === 'agent_whoami') {
+                this.reply(conn, id, this.whoami(session));
+                return;
+            }
+            if (name === 'subscribe') {
+                this.reply(conn, id, this.subscribe(conn, args));
+                return;
+            }
+            if (name === 'unsubscribe') {
+                this.reply(conn, id, this.unsubscribe(session, args));
+                return;
+            }
+            if (name === 'list_proposals') {
+                const limit = Math.min(Number(args.limit ?? 50), 100);
+                this.gate.record(session, name, `listed proposals`, 'call');
+                this.reply(conn, id, { proposals: this.proposals.list({ agentId: session.agentId, limit }) });
+                return;
+            }
+            // proposals
+            if (TOOL_TO_KIND[name]) {
+                const { proposal, duplicate } = this.proposals.create(session, name, args);
+                if (duplicate)
+                    this.gate.refundProposal(session.agentId);
+                this.audit.append({ agentId: session.agentId, agentName: session.agentName, session: session.id, kind: 'proposal', tool: name, detail: `${duplicate ? 'duplicate ' : ''}${proposal.summary}`, ok: true });
+                this.reply(conn, id, { proposal, duplicate, note: 'This is a PROPOSAL. The user confirms it with a keypress; you can never arm, confirm or send it.' });
+                return;
+            }
+            // read / navigation / note → executor. Scrub every string leaf of the result before it reaches the
+            // agent (belt-and-braces over the source firewall): no escape/bidi/zero-width can pass through.
+            const result = scrubStrings(await this.executor.exec(session, name, args));
+            const isErr = typeof result.error === 'string';
+            this.gate.record(session, name, isErr ? `error: ${String(result.error).slice(0, 80)}` : summarise(name, args), name === 'agent_note' ? 'note' : 'call');
+            this.reply(conn, id, result);
+            return;
+        }
+        catch (e) {
+            this.fail(conn, id, -32000, 'internal error', { detail: e.message.slice(0, 80) });
+        }
+    }
+    whoami(session) {
+        return { agent: session.agentName, tier: session.tier, mandate: session.scope ? [...session.scope] : null, tools: this.visibleTools(session).map((t) => ({ name: t, tier: agentTool(t)?.tier })), usage: this.gate.usage(session.agentId), subscriptions: [...session.topics], note: 'Your identity, tier and mandate come from the server. You cannot change them.' };
+    }
+    /** Tool names this session may call: its tier surface, narrowed by a mandate (+ agent_whoami, always). */
+    visibleTools(session) {
+        const all = toolsForTier(session.tier);
+        if (!session.scope)
+            return all;
+        return all.filter((t) => t === 'agent_whoami' || session.scope.has(t));
+    }
+    /** The advertised tool DEFINITIONS for tools/list, narrowed the same way. */
+    visibleToolDefs(session) {
+        const defs = toolsForTierList(session.tier);
+        if (!session.scope)
+            return defs;
+        return defs.filter((t) => t.name === 'agent_whoami' || session.scope.has(t.name));
+    }
+    subscribe(conn, args) {
+        const session = conn.session;
+        const topics = Array.isArray(args.topics) ? args.topics.filter(isTopic) : [];
+        const limit = this.gate.limitsFor(session.agentId).maxTopics;
+        const added = [];
+        for (const t of topics) {
+            if (session.topics.size >= limit)
+                break;
+            if (!session.topics.has(t)) {
+                session.topics.add(t);
+                added.push(t);
+            }
+        }
+        this.audit.append({ agentId: session.agentId, agentName: session.agentName, session: session.id, kind: 'subscribe', tool: 'subscribe', detail: `+[${added.join(',')}]`, ok: true });
+        // push an immediate snapshot per newly-added topic, if the feed offers one
+        if (this.feed?.snapshot)
+            for (const t of added) {
+                const snap = this.feed.snapshot(t);
+                if (snap)
+                    conn.ws.send({ jsonrpc: '2.0', method: 'event', params: scrubStrings({ topic: t, seq: 0, t: this.now(), data: snap, snapshot: true }) });
+            }
+        return { subscribed: [...session.topics] };
+    }
+    unsubscribe(session, args) {
+        const topics = Array.isArray(args.topics) ? args.topics.filter(isTopic) : null;
+        if (topics === null)
+            session.topics.clear();
+        else
+            for (const t of topics)
+                session.topics.delete(t);
+        return { subscribed: [...session.topics] };
+    }
+    /** Fan a feed event out to every session subscribed to its topic. */
+    fanout(ev) {
+        for (const c of this.conns) {
+            const s = c.session;
+            if (!s || s.closed || this.paused.has(s.agentId))
+                continue;
+            if (s.topics.has(ev.topic))
+                c.ws.send({ jsonrpc: '2.0', method: 'event', params: scrubStrings(ev) });
+        }
+    }
+    writeDiscovery() {
+        if (!this.discoveryPath)
+            return;
+        try {
+            mkdirSync(dirname(this.discoveryPath), { recursive: true, mode: 0o700 });
+            writeFileSync(this.discoveryPath, JSON.stringify({ protocol: BUS_PROTOCOL, port: this.port, pid: process.pid, startedAt: this.now() }, null, 2) + '\n', { mode: 0o600 });
+            try {
+                chmodSync(this.discoveryPath, 0o600);
+            }
+            catch { /* ignore */ }
+        }
+        catch { /* discovery is best-effort; the port can also be passed explicitly */ }
+    }
+}
+function summarise(name, args) {
+    const mint = typeof args.mint === 'string' ? args.mint.slice(0, 6) + '…' : '';
+    if (mint)
+        return `${name} ${mint}`;
+    if (typeof args.query === 'string')
+        return `${name} "${args.query.slice(0, 24)}"`;
+    if (typeof args.preset === 'string')
+        return `${name} ${args.preset}`;
+    return name;
+}