dexterm-cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,177 @@
+// @dexterm/agents — the tool executor and the live feed (task-1345, tier 2).
+//
+// The bus gates every call (identity, tier, closed schema, rate/quota) and ONLY THEN hands a read or
+// navigation call to an AgentExecutor. Keeping execution behind an interface means the running TUI can
+// back it with the real @dexterm/data layer (via the MCP tools) while tests and the fixture demo back it
+// with deterministic data and never touch the network. The executor never sees a token, never signs, and
+// cannot widen a capability — it only runs the name the gate already approved.
+import { firewallText } from '../../data/src/index.js';
+/** Topics an agent may subscribe to. Each pushed event is server-authored and firewalled. */
+export const TOPICS = ['new_pairs', 'trades', 'alerts', 'screen'];
+export function isTopic(x) { return typeof x === 'string' && TOPICS.includes(x); }
+// ---------------------------------------------------------------------------------------------------
+// Outbound scrub (task-1345, tier 3): a belt-and-braces net over EVERY string an agent receives. The
+// executor/source already firewalls untrusted token text (symbols, names, risk strings) into <untrusted>
+// blocks, but the bus strips terminal-escape / C0-C1 / bidi / zero-width characters from every string
+// leaf of a tool result and a pushed event too, so a buggy or compromised source can never carry an ANSI
+// clear-screen, a right-to-left override, or a zero-width-join obfuscation into the agent (or, if the
+// agent echoes it, into a terminal). Strip-only: it never truncates or re-wraps legitimate data.
+// First remove whole ANSI escape sequences (CSI `ESC [ … letter` and OSC `ESC ] … BEL/ST`), so no printable
+// payload like `[2J` is left behind, then strip any remaining C0/C1 control, bidi-override and zero-width.
+const ANSI_SEQ = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[@-Z\\-_]/g;
+const UNSAFE_CHARS = /[\u0000-\u001F\u007F-\u009F​-‏‪-‮⁦-⁩]/g;
+export function stripControl(s) { return s.replace(ANSI_SEQ, '').replace(UNSAFE_CHARS, ''); }
+export function scrubStrings(v, depth = 0) {
+    if (depth > 8)
+        return v;
+    if (typeof v === 'string')
+        return stripControl(v);
+    if (Array.isArray(v))
+        return v.map((x) => scrubStrings(x, depth + 1));
+    if (v && typeof v === 'object') {
+        const out = {};
+        for (const [k, val] of Object.entries(v))
+            out[stripControl(k).slice(0, 128)] = scrubStrings(val, depth + 1);
+        return out;
+    }
+    return v;
+}
+// ---------------------------------------------------------------------------------------------------
+// Fixtures: deterministic, offline, used by the bus tests, `dexterm agent serve --fixtures` and the
+// worked demo. Numbers are seeded and stable; symbols/names go through the firewall like live data.
+const FIXTURE_ROWS = [
+    { mint: 'FixtMintAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA', symbol: 'TROLL', name: 'Troll Cat', launchpad: 'pump.fun', ageSec: 240, priceUsd: 0.00042, mcap: 420_000, liquidityUsd: 38_000, volH1: 120_000, holderCount: 410, organicScore: 62, freeze: false, mintAuth: false, lpLockedPct: 100, top10Pct: 18, rugScore: 12 },
+    { mint: 'FixtMintBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB', symbol: 'MOONER', name: 'Mooner', launchpad: 'raydium', ageSec: 5400, priceUsd: 0.0131, mcap: 2_100_000, liquidityUsd: 190_000, volH1: 540_000, holderCount: 1900, organicScore: 71, freeze: false, mintAuth: false, lpLockedPct: 100, top10Pct: 22, rugScore: 8 },
+    { mint: 'FixtMintCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC', symbol: 'RUGME', name: 'Totally Safe Inu 🚀', launchpad: 'pump.fun', ageSec: 90, priceUsd: 0.0000008, mcap: 15_000, liquidityUsd: 3200, volH1: 60_000, holderCount: 42, organicScore: 9, freeze: true, mintAuth: true, lpLockedPct: 0, top10Pct: 71, rugScore: 86 },
+    { mint: 'FixtMintDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD', symbol: 'GIGA', name: 'Gigabrain', launchpad: 'meteora', ageSec: 12_600, priceUsd: 0.21, mcap: 8_800_000, liquidityUsd: 760_000, volH1: 1_200_000, holderCount: 6100, organicScore: 80, freeze: false, mintAuth: false, lpLockedPct: 100, top10Pct: 14, rugScore: 5 },
+];
+function fw(s) { return firewallText(s, { max: 48 }).text; }
+const now = () => Date.now();
+export class FixtureExecutor {
+    /** agent_note writes land here so the fixture demo / tests can read them back. */
+    notes = [];
+    /** navigation requests land here (the "app" would apply them). */
+    navigation = [];
+    async exec(session, tool, args) {
+        const byMint = (m) => FIXTURE_ROWS.find((r) => r.mint === m);
+        switch (tool) {
+            case 'screen_state':
+                return { screen: 'screener', filter: '', sort: 'vol24:desc', selected: { mint: FIXTURE_ROWS[0].mint, symbol: FIXTURE_ROWS[0].symbol }, visibleMints: FIXTURE_ROWS.map((r) => r.mint), watchlist: [], actions: { enabled: true, mints: FIXTURE_ROWS.map((r) => r.mint), feeds: ['new', 'trending', 'all'], sortKeys: ['vol24', 'mcap', 'age', 'liq'] }, now: now() };
+            case 'screener_query': {
+                const preset = args.preset ?? 'trending';
+                const rows = preset === 'new' ? [...FIXTURE_ROWS].sort((a, b) => a.ageSec - b.ageSec) : [...FIXTURE_ROWS].sort((a, b) => b.volH1 - a.volH1);
+                const limit = Math.min(Number(args.limit ?? 20), 50);
+                return { preset, now: now(), rows: rows.slice(0, limit).map((r) => ({ mint: r.mint, symbol: fw(r.symbol), launchpad: r.launchpad, tokenAgeSec: r.ageSec, priceUsd: r.priceUsd, mcap: r.mcap, liquidityUsd: r.liquidityUsd, volH1: r.volH1, holderCount: r.holderCount, organicScore: r.organicScore, audit: { mintAuthority: r.mintAuth, freezeAuthority: r.freeze, top10Pct: r.top10Pct, lpLockedPct: r.lpLockedPct, rugScore: r.rugScore }, source: 'fixtures', ageSec: 3 })) };
+            }
+            case 'get_token': {
+                const r = byMint(args.mint) ?? FIXTURE_ROWS.find((x) => x.symbol.toUpperCase() === String(args.symbol ?? '').replace(/^\$/, '').toUpperCase());
+                if (!r)
+                    return { error: 'unknown token (fixtures)' };
+                return { token: { mint: r.mint, symbol: fw(r.symbol), name: fw(r.name), launchpad: r.launchpad }, pair: { priceUsd: r.priceUsd, mcap: r.mcap, liquidityUsd: r.liquidityUsd, source: 'fixtures', ageSec: 3 }, stats: { holderCount: r.holderCount, organicScore: r.organicScore }, audit: { mintAuthority: r.mintAuth, freezeAuthority: r.freeze, top10Pct: r.top10Pct, lpLockedPct: r.lpLockedPct, rugScore: r.rugScore }, now: now() };
+            }
+            case 'rugcheck': {
+                const r = byMint(args.mint);
+                if (!r)
+                    return { error: 'unknown token (fixtures)' };
+                const risks = [];
+                if (r.freeze)
+                    risks.push({ name: 'freeze authority enabled', level: 'danger' });
+                if (r.mintAuth)
+                    risks.push({ name: 'mint authority enabled', level: 'danger' });
+                if (r.lpLockedPct < 100)
+                    risks.push({ name: 'LP not fully locked', level: 'warn' });
+                if (r.top10Pct > 40)
+                    risks.push({ name: 'top-10 holders concentrated', level: 'warn' });
+                return { mint: r.mint, scoreNormalised: r.rugScore, lpLockedPct: r.lpLockedPct, tokenProgram: 'Tokenkeg', risks, source: 'fixtures', ageSec: 3 };
+            }
+            case 'get_dev_history': {
+                const r = byMint(args.mint);
+                if (!r)
+                    return { error: 'unknown token (fixtures)' };
+                return { mint: r.mint, creator: 'FixtDev1111111111111111111111111111111111111', creators: ['FixtDev1111111111111111111111111111111111111'], devHistory: null, snipers: null, bundledPct: null, tier: 'needs-key', note: 'prior-launch forensics need a key; keyless tier (fixtures)' };
+            }
+            case 'get_holders': {
+                const r = byMint(args.mint);
+                if (!r)
+                    return { error: 'unknown token (fixtures)' };
+                return { mint: r.mint, top10PctExLp: r.top10Pct, holderCount: r.holderCount, holders: [], supply: 1e9, decimals: 6, source: 'fixtures', ageSec: 3 };
+            }
+            case 'get_trades': {
+                const r = byMint(args.mint);
+                if (!r)
+                    return { error: 'unknown token (fixtures)' };
+                const washy = r.rugScore > 50;
+                return { mint: r.mint, window: args.window ?? 'h1', count: 180, buys: 100, sells: 80, buyUsd: Math.round(r.volH1 * 0.55), sellUsd: Math.round(r.volH1 * 0.45), distinctWallets: washy ? 6 : 140, top2WalletVolumeSharePct: washy ? 68 : 9, source: 'fixtures', ageSec: 3 };
+            }
+            case 'get_candles': {
+                const r = byMint(args.mint);
+                if (!r)
+                    return { error: 'unknown token (fixtures)' };
+                return { mint: r.mint, interval: args.interval ?? '1h', bars: 24, summary: { first: r.priceUsd * 0.8, last: r.priceUsd, high: r.priceUsd * 1.2, low: r.priceUsd * 0.7, changePct: 25, drawdownFromHighPct: -16.7, vwap: r.priceUsd * 0.95 }, source: 'fixtures', ageSec: 3 };
+            }
+            case 'get_dossier': {
+                const r = byMint(args.mint) ?? FIXTURE_ROWS.find((x) => x.symbol.toUpperCase() === String(args.symbol ?? '').replace(/^\$/, '').toUpperCase());
+                if (!r)
+                    return { error: 'unknown token (fixtures)' };
+                const [token, rug, trades] = await Promise.all([this.exec(session, 'get_token', { mint: r.mint }), this.exec(session, 'rugcheck', { mint: r.mint }), this.exec(session, 'get_trades', { mint: r.mint, window: 'h1' })]);
+                return { mint: r.mint, interval: args.interval ?? '1h', token, rugcheck: rug, trades, availability: { market: true, security: true, tape: true, canVerdict: true } };
+            }
+            case 'open_token':
+            case 'show_in_screener':
+            case 'switch_feed':
+                this.navigation.push({ agent: session.agentName, tool, args });
+                return { ok: true, note: 'The app applies this and shows "<agent> did X". You cannot confirm, size, or send a trade.' };
+            case 'agent_note': {
+                const text = fw(String(args.text ?? ''));
+                const tag = args.tag ? fw(String(args.tag)) : null;
+                this.notes.push({ agent: session.agentName, mint: String(args.mint), text, tag, t: now() });
+                return { ok: true, note: 'note attached and labelled with your agent name', text, tag };
+            }
+            default:
+                return { error: `fixture executor has no handler for ${tool}` };
+        }
+    }
+}
+/** A feed that tests/the demo drive by calling emit(); an optional timer makes it tick on its own. */
+export class FixtureFeed {
+    listeners = new Set();
+    seq = 0;
+    timer = null;
+    on(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+    snapshot(topic) {
+        if (topic === 'screen')
+            return { screen: 'screener', filter: '', selected: FIXTURE_ROWS[0].mint };
+        return null;
+    }
+    emit(topic, data) {
+        const ev = { topic, seq: ++this.seq, t: now(), data };
+        for (const l of this.listeners) {
+            try {
+                l(ev);
+            }
+            catch { /* one bad listener never stops the fan-out */ }
+        }
+        return ev;
+    }
+    /** Start a deterministic cycle of events (for the demo). Unref'd so it never keeps the process alive. */
+    start(intervalMs = 1500) {
+        if (this.timer)
+            return;
+        let i = 0;
+        this.timer = setInterval(() => {
+            const r = FIXTURE_ROWS[i % FIXTURE_ROWS.length];
+            i++;
+            if (i % 3 === 0)
+                this.emit('new_pairs', { mint: r.mint, symbol: fw(r.symbol), launchpad: r.launchpad, ageSec: 5 });
+            else if (i % 3 === 1)
+                this.emit('trades', { mint: r.mint, side: i % 2 ? 'buy' : 'sell', usd: 1200 + i * 10, priceUsd: r.priceUsd });
+            else
+                this.emit('alerts', { mint: r.mint, kind: 'volume_spike', note: fw(`${r.symbol} volume spiked`) });
+        }, intervalMs);
+        this.timer.unref?.();
+    }
+    stop() { if (this.timer) {
+        clearInterval(this.timer);
+        this.timer = null;
+    } }
+}

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

@@ -0,0 +1,176 @@
+// @dexterm/agents — the gate (task-1345). ONE function every agent call passes, on every transport
+// (bus method or bridged MCP tool call), before anything is looked up or executed:
+//
+//   1. the session must be open (not kicked) and its agent not paused;
+//   2. the tool name must not be on the never-list (arm / sign / caps / gate / wallet / mandate / keys …)
+//      and must exist in the tier table — anything else is `unknown-tool`;
+//   3. the agent's GRANTED tier must reach the tool's tier (the tier comes from the registry at hello,
+//      never from the request; a request field named `tier`, `agent` or `session` is refused as spoofing);
+//   4. the arguments must validate against the tool's closed schema and fit the size cap;
+//   5. the per-agent rate limits and quotas must have room (reads/min, navigation per 10 s, proposals/h);
+//   6. a proposal must carry an idempotency key.
+//
+// Every refusal is written to the audit log with a short reason. Sustained refusals trip a per-agent
+// breaker (`flood`): the agent is auto-paused for FLOOD_PAUSE_MS and the roster shows why.
+import { ACTION_RATE } from '../../data/src/index.js';
+import { tierAtLeast, tierFor, neverAllowed, PROPOSAL_TOOLS, NAVIGATION_TOOLS } from "./tiers.js";
+import { validateArgs } from "./schema.js";
+export const DEFAULT_LIMITS = Object.freeze({
+    readsPerMin: 120,
+    proposalsPerHour: 20,
+    navPer10s: ACTION_RATE.max,
+    maxArgsBytes: 16 * 1024,
+    maxTopics: 8,
+    connections: 2,
+});
+/** Refusals in FLOOD_WINDOW_MS that trip the breaker, and how long the auto-pause lasts. */
+export const FLOOD_REFUSALS = 40;
+export const FLOOD_WINDOW_MS = 60_000;
+export const FLOOD_PAUSE_MS = 5 * 60_000;
+/** Fields an agent must never be able to set on a request: identity and capability come from the server. */
+const SPOOF_FIELDS = ['agent', 'agent_id', 'agentId', 'agent_name', 'agentName', 'tier', 'session', 'session_id', 'sessionId', 'token', 'as', 'on_behalf_of', 'impersonate'];
+export class AgentGate {
+    audit;
+    now;
+    base;
+    onFlood;
+    isPausedExt;
+    reads = new Map();
+    nav = new Map();
+    proposals = new Map();
+    refusals = new Map();
+    floodUntil = new Map();
+    perAgent = new Map();
+    constructor(opts) {
+        this.audit = opts.audit;
+        this.now = opts.now ?? (() => Date.now());
+        this.base = { ...DEFAULT_LIMITS, ...(opts.limits ?? {}) };
+        this.onFlood = opts.onFlood;
+        this.isPausedExt = opts.isPaused ?? (() => false);
+    }
+    /** Per-agent overrides from the registry (`limits` in agents.json). */
+    setAgentLimits(agentId, l) {
+        if (!l) {
+            this.perAgent.delete(agentId);
+            return;
+        }
+        const o = {};
+        if (l.readsPerMin !== undefined)
+            o.readsPerMin = l.readsPerMin;
+        if (l.proposalsPerHour !== undefined)
+            o.proposalsPerHour = l.proposalsPerHour;
+        if (l.connections !== undefined)
+            o.connections = l.connections;
+        this.perAgent.set(agentId, o);
+    }
+    limitsFor(agentId) { return { ...this.base, ...(this.perAgent.get(agentId) ?? {}) }; }
+    /** Current usage for the roster ("12/min", "3/20 proposals this hour"). */
+    usage(agentId) {
+        const t = this.now();
+        const count = (m, win) => { const w = m.get(agentId); if (!w)
+            return 0; return w.times.filter((x) => t - x < win).length; };
+        const until = this.floodUntil.get(agentId) ?? null;
+        return { readsPerMin: count(this.reads, 60_000), proposalsPerHour: count(this.proposals, 3_600_000), navPer10s: count(this.nav, ACTION_RATE.windowMs), floodPausedUntil: until !== null && until > t ? until : null, limits: this.limitsFor(agentId) };
+    }
+    /** The gate. Pure apart from the windows and the audit row it writes. */
+    check(session, req) {
+        const t = this.now();
+        const refuse = (code, error) => {
+            this.audit.append({ agentId: session.agentId, agentName: session.agentName, session: session.id, kind: 'refused', tool: String(req.tool).slice(0, 64), detail: `${code}: ${error}`, ok: false });
+            this.noteRefusal(session, t);
+            return { ok: false, code, error };
+        };
+        if (session.closed)
+            return refuse('session-closed', `session closed${session.closedReason ? ` (${session.closedReason})` : ''}`);
+        const fu = this.floodUntil.get(session.agentId);
+        if (fu !== undefined && fu > t)
+            return refuse('flood-paused', `auto-paused after repeated refusals; resumes in ${Math.ceil((fu - t) / 1000)} s or when the user resumes it`);
+        if (this.isPausedExt(session.agentId))
+            return refuse('agent-paused', 'the user paused this agent');
+        const name = req.tool;
+        if (typeof name !== 'string' || neverAllowed(name))
+            return refuse('never', 'no agent may do that at any tier');
+        const need = tierFor(name);
+        if (need === null)
+            return refuse('unknown-tool', `unknown tool ${JSON.stringify(String(name).slice(0, 40))}`);
+        if (!tierAtLeast(session.tier, need))
+            return refuse('tier', `${name} needs tier ${need}; this agent is ${session.tier}`);
+        // spoofing: identity / capability fields in the arguments are never honoured
+        const args = req.args === undefined ? {} : req.args;
+        if (typeof args === 'object' && args !== null && !Array.isArray(args)) {
+            for (const f of SPOOF_FIELDS)
+                if (Object.hasOwn(args, f))
+                    return refuse('spoof', `argument "${f}" is not yours to set: identity and tier come from the server`);
+        }
+        let bytes = 0;
+        try {
+            bytes = Buffer.byteLength(JSON.stringify(args));
+        }
+        catch {
+            return refuse('bad-args', 'arguments are not serialisable');
+        }
+        if (bytes > this.limitsFor(session.agentId).maxArgsBytes)
+            return refuse('too-large', `arguments exceed ${this.limitsFor(session.agentId).maxArgsBytes} bytes`);
+        const schemaErr = validateArgs(req.schema, args);
+        if (schemaErr)
+            return refuse('bad-args', schemaErr);
+        // quotas
+        const limits = this.limitsFor(session.agentId);
+        if (PROPOSAL_TOOLS.has(name)) {
+            const key = args.idempotency_key;
+            if (typeof key !== 'string' || key.length < 8 || key.length > 64 || !/^[A-Za-z0-9_.:-]+$/.test(key))
+                return refuse('idempotency-key', 'proposals need idempotency_key (8–64 chars: letters, digits, _ . : -)');
+            if (!this.take(this.proposals, session.agentId, 3_600_000, limits.proposalsPerHour, t))
+                return refuse('quota', `proposal quota reached (${limits.proposalsPerHour}/hour)`);
+        }
+        else if (NAVIGATION_TOOLS.has(name)) {
+            if (!this.take(this.nav, session.agentId, ACTION_RATE.windowMs, limits.navPer10s, t))
+                return refuse('rate-limited', `navigation is limited to ${limits.navPer10s} per ${ACTION_RATE.windowMs / 1000} s`);
+        }
+        else if (name !== 'subscribe' && name !== 'unsubscribe') {
+            if (!this.take(this.reads, session.agentId, 60_000, limits.readsPerMin, t))
+                return refuse('rate-limited', `read rate limit reached (${limits.readsPerMin}/min)`);
+        }
+        session.lastActivity = t;
+        return { ok: true, tool: name, tier: need };
+    }
+    /** Record a successful call (the owner calls this after executing so the detail can name the target). */
+    record(session, tool, detail, kind = 'call') {
+        this.audit.append({ agentId: session.agentId, agentName: session.agentName, session: session.id, kind, tool, detail, ok: true });
+    }
+    /** A proposal's quota slot is returned when the proposal turned out to be an idempotent repeat. */
+    refundProposal(agentId) { const w = this.proposals.get(agentId); if (w)
+        w.times.pop(); }
+    /** Clear the breaker (user resume). */
+    clearFlood(agentId) { this.floodUntil.delete(agentId); this.refusals.delete(agentId); }
+    take(m, agentId, windowMs, max, t) {
+        let w = m.get(agentId);
+        if (!w) {
+            w = { times: [] };
+            m.set(agentId, w);
+        }
+        while (w.times.length && t - w.times[0] >= windowMs)
+            w.times.shift();
+        if (w.times.length >= max)
+            return false;
+        w.times.push(t);
+        return true;
+    }
+    noteRefusal(session, t) {
+        let w = this.refusals.get(session.agentId);
+        if (!w) {
+            w = { times: [] };
+            this.refusals.set(session.agentId, w);
+        }
+        while (w.times.length && t - w.times[0] >= FLOOD_WINDOW_MS)
+            w.times.shift();
+        w.times.push(t);
+        if (w.times.length >= FLOOD_REFUSALS && !(this.floodUntil.get(session.agentId) > t)) {
+            const until = t + FLOOD_PAUSE_MS;
+            this.floodUntil.set(session.agentId, until);
+            w.times.length = 0;
+            this.audit.append({ agentId: session.agentId, agentName: session.agentName, session: session.id, kind: 'flood', tool: '-', detail: `${FLOOD_REFUSALS} refusals in ${FLOOD_WINDOW_MS / 1000} s: auto-paused ${FLOOD_PAUSE_MS / 60_000} min`, ok: false });
+            this.onFlood?.(session.agentId, session.agentName, until);
+        }
+    }
+}

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

@@ -0,0 +1,179 @@
+// @dexterm/agents — per-agent identity (task-1345).
+//
+// The user registers each agent once (`dexterm agent add NAME --tier T`); the agent gets a bearer token
+// that is shown exactly once and stored only as a salted SHA-256 hash in `<dexterm home>/agents.json`
+// (mode 0600). Every connection (bus `hello`, or a bridged `dexterm mcp` child) presents the name and the
+// token; the registry verifies the hash with a constant-time compare and hands back the GRANTED tier.
+// The agent never states its own tier. Tokens are rotated with `dexterm agent rotate NAME`; a rotated or
+// removed token fails verification at once, so a kicked agent cannot reconnect with the old secret.
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { isTier } from "./tiers.js";
+export const AGENT_NAME_RE = /^[a-z][a-z0-9-]{0,23}$/;
+export const TOKEN_PREFIX = 'dxa_';
+/** Hard cap on registered agents (a flood of `agent add` is still bounded). */
+export const MAX_AGENTS = 32;
+export function dextermHome(env = process.env) {
+    return env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+}
+export function registryPath(env = process.env) {
+    return join(dextermHome(env), 'agents.json');
+}
+export function hashToken(salt, token) {
+    return createHash('sha256').update(salt + ':' + token, 'utf8').digest('hex');
+}
+function newToken() { return TOKEN_PREFIX + randomBytes(32).toString('base64url'); }
+function newId() { return randomBytes(6).toString('hex'); }
+/** Fail-closed token shape check before any hashing (also what the bus/MCP use to reject junk early). */
+export function looksLikeToken(t) {
+    return typeof t === 'string' && t.startsWith(TOKEN_PREFIX) && t.length >= 20 && t.length <= 128 && /^[A-Za-z0-9_-]+$/.test(t.slice(TOKEN_PREFIX.length));
+}
+export class AgentRegistry {
+    path;
+    now;
+    agents = [];
+    constructor(opts = {}) {
+        this.path = opts.path ?? registryPath(opts.env);
+        this.now = opts.now ?? (() => Date.now());
+        this.load();
+    }
+    get file() { return this.path; }
+    load() {
+        // An in-memory registry keeps whatever add()/rotate() built: re-reading would wipe it (there is no file).
+        if (this.path === ':memory:')
+            return;
+        if (!existsSync(this.path)) {
+            this.agents = [];
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.path, 'utf8'));
+        }
+        catch {
+            this.agents = [];
+            return;
+        }
+        const f = parsed;
+        const list = Array.isArray(f?.agents) ? f.agents : [];
+        // Defensive re-validation: a hand-edited file cannot grant a tier outside the three or a bad name.
+        this.agents = list.filter((a) => !!a && typeof a === 'object' && typeof a.id === 'string' && typeof a.name === 'string' && AGENT_NAME_RE.test(a.name)
+            && isTier(a.tier) && typeof a.tokenHash === 'string' && typeof a.salt === 'string').map((a) => ({ ...a, paused: a.paused === true, rotatedAt: typeof a.rotatedAt === 'number' ? a.rotatedAt : null }));
+    }
+    save() {
+        if (this.path === ':memory:')
+            return;
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        const tmp = `${this.path}.${process.pid}.tmp`;
+        const body = { version: 1, agents: this.agents };
+        writeFileSync(tmp, JSON.stringify(body, null, 2) + '\n', { mode: 0o600 });
+        try {
+            chmodSync(tmp, 0o600);
+        }
+        catch { /* best effort on odd filesystems */ }
+        renameSync(tmp, this.path);
+    }
+    list() { return this.agents.map((a) => ({ ...a })); }
+    get(name) { return this.agents.find((a) => a.name === name); }
+    byId(id) { return this.agents.find((a) => a.id === id); }
+    /** Register an agent. Returns the record and the ONE-TIME plaintext token (never stored). */
+    add(name, tier, opts = {}) {
+        if (!AGENT_NAME_RE.test(name))
+            throw new Error(`agent name must match ${AGENT_NAME_RE} (lowercase letters, digits, dashes; ≤ 24 chars)`);
+        if (!isTier(tier))
+            throw new Error('tier must be observe, annotate or propose');
+        if (this.get(name))
+            throw new Error(`agent "${name}" already exists (rotate its token with: dexterm agent rotate ${name})`);
+        if (this.agents.length >= MAX_AGENTS)
+            throw new Error(`at most ${MAX_AGENTS} agents can be registered`);
+        const token = newToken();
+        const salt = randomBytes(12).toString('hex');
+        const agent = { id: newId(), name, tier, tokenHash: hashToken(salt, token), salt, createdAt: this.now(), paused: false, rotatedAt: null };
+        if (opts.note)
+            agent.note = String(opts.note).slice(0, 80);
+        if (opts.limits)
+            agent.limits = sanitizeLimits(opts.limits);
+        this.agents.push(agent);
+        this.save();
+        return { agent: { ...agent }, token };
+    }
+    remove(name) {
+        const n = this.agents.length;
+        this.agents = this.agents.filter((a) => a.name !== name);
+        if (this.agents.length === n)
+            return false;
+        this.save();
+        return true;
+    }
+    /** Replace the token; the old one fails from this moment. Returns the new one-time token. */
+    rotate(name) {
+        const a = this.get(name);
+        if (!a)
+            throw new Error(`no agent "${name}"`);
+        const token = newToken();
+        a.salt = randomBytes(12).toString('hex');
+        a.tokenHash = hashToken(a.salt, token);
+        a.rotatedAt = this.now();
+        this.save();
+        return token;
+    }
+    setTier(name, tier) {
+        const a = this.get(name);
+        if (!a)
+            throw new Error(`no agent "${name}"`);
+        if (!isTier(tier))
+            throw new Error('tier must be observe, annotate or propose');
+        a.tier = tier;
+        this.save();
+    }
+    setPaused(name, paused) {
+        const a = this.get(name);
+        if (!a)
+            throw new Error(`no agent "${name}"`);
+        a.paused = paused;
+        this.save();
+    }
+    setLimits(name, limits) {
+        const a = this.get(name);
+        if (!a)
+            throw new Error(`no agent "${name}"`);
+        a.limits = sanitizeLimits(limits);
+        this.save();
+    }
+    /**
+     * Verify a presented name + token. Constant-time on the hash; the same `null` for an unknown name,
+     * a bad token shape and a wrong token (no oracle). Re-reads the file first so a rotate / remove from
+     * another process (the CLI) takes effect on the next connection.
+     */
+    verify(name, token) {
+        this.load();
+        if (typeof name !== 'string' || !AGENT_NAME_RE.test(name) || !looksLikeToken(token))
+            return null;
+        const a = this.get(name);
+        if (!a)
+            return null;
+        const got = Buffer.from(hashToken(a.salt, token), 'hex');
+        const want = Buffer.from(a.tokenHash, 'hex');
+        if (got.length !== want.length || !timingSafeEqual(got, want))
+            return null;
+        return { ...a };
+    }
+    /** Re-read from disk (the TUI calls this before rendering the roster so CLI edits show up). */
+    reload() { this.load(); }
+}
+function sanitizeLimits(l) {
+    const out = {};
+    const num = (v, lo, hi) => (typeof v === 'number' && Number.isFinite(v) && v >= lo && v <= hi ? Math.floor(v) : undefined);
+    const r = num(l.readsPerMin, 1, 600);
+    if (r !== undefined)
+        out.readsPerMin = r;
+    const p = num(l.proposalsPerHour, 0, 200);
+    if (p !== undefined)
+        out.proposalsPerHour = p;
+    const c = num(l.connections, 1, 8);
+    if (c !== undefined)
+        out.connections = c;
+    return out;
+}

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

@@ -0,0 +1,15 @@
+// @dexterm/agents — public surface (task-1345). Nothing in this package can arm, sign, confirm, send,
+// raise a cap, change the confirmation gate, or touch a wallet, a mandate or the signer: the tier table
+// has no such tool and the gate refuses the shape of such a request before any lookup.
+export * from "./tiers.js";
+export * from "./identity.js";
+export * from "./audit.js";
+export * from "./schema.js";
+export * from "./gate.js";
+// tier 2 (task-1345): transports — the tool table, the loopback WebSocket, the bus, the executor/feed,
+// the proposal store. The SDK is a separate entry point (./sdk) so an external agent imports only it.
+export * from "./tools.js";
+export * from "./ws.js";
+export * from "./executor.js";
+export * from "./proposals.js";
+export * from "./bus.js";