dexterm-cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,153 @@
+// @dexterm/agents — the proposal store (task-1345, tier 2 interface; tier 3 enriches it).
+//
+// An agent can only ever create a PROPOSAL: a draft alert / order plan / watchlist add, labelled with the
+// agent that made it, that the user confirms with a physical keypress. The store NEVER confirms a proposal
+// on an agent's behalf (`confirm`/`dismiss` are user actions, keyed by a separate caller), enforces
+// idempotency (the same agent + key returns the same proposal instead of a second one), and firewalls the
+// agent-authored display text before it reaches the terminal or the roster. Nothing here arms, signs or
+// sends anything; an order-plan proposal is a draft with `armed: false`, full stop.
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { firewallText } from '../../data/src/index.js';
+export const TOOL_TO_KIND = Object.freeze({
+    propose_alert: 'alert', propose_order_plan: 'order_plan', add_to_watchlist: 'watchlist',
+});
+const fw = (s, max = 200) => firewallText(s === undefined || s === null ? '' : String(s), { max }).text.replace(/\s+/g, ' ').trim();
+/** Build the firewalled summary + detail for a proposal. Pure. */
+export function proposalView(kind, mint, args) {
+    const short = mint.slice(0, 6);
+    if (kind === 'alert') {
+        const when = fw(args.when, 120);
+        return { summary: `alert ${short}… when ${when}`, detail: { mint, when, note: fw(args.note) } };
+    }
+    if (kind === 'order_plan') {
+        const side = args.side === 'sell' ? 'sell' : 'buy';
+        const size = fw(args.size, 40);
+        const triggers = Array.isArray(args.triggers) ? args.triggers.slice(0, 8).map((t) => fw(t, 80)) : [];
+        return { summary: `PAPER ${side} ${short}… size ${size} (DRAFT — not armed)`, detail: { mint, side, size, triggers, note: fw(args.note), armed: false } };
+    }
+    return { summary: `watchlist add ${short}…`, detail: { mint, note: fw(args.note) } };
+}
+export class MemoryProposalStore {
+    rows = [];
+    seq = 0;
+    now;
+    constructor(opts = {}) { this.now = opts.now ?? (() => Date.now()); }
+    create(session, tool, args) {
+        const kind = TOOL_TO_KIND[tool];
+        if (!kind)
+            throw new Error(`not a proposal tool: ${tool}`);
+        const key = String(args.idempotency_key);
+        const existing = this.rows.find((p) => p.agentId === session.agentId && p.idempotencyKey === key);
+        if (existing)
+            return { proposal: { ...existing }, duplicate: true };
+        const mint = String(args.mint);
+        const { summary, detail } = proposalView(kind, mint, args);
+        const proposal = {
+            id: `prop_${(++this.seq).toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+            agentId: session.agentId, agentName: session.agentName, kind, mint, idempotencyKey: key,
+            createdAt: this.now(), status: 'pending', summary, detail, armed: false,
+        };
+        this.rows.push(proposal);
+        return { proposal: { ...proposal }, duplicate: false };
+    }
+    list(filter = {}) {
+        const out = [];
+        for (let i = this.rows.length - 1; i >= 0 && out.length < (filter.limit ?? 100); i--) {
+            const p = this.rows[i];
+            if (filter.agentId && p.agentId !== filter.agentId)
+                continue;
+            if (filter.status && p.status !== filter.status)
+                continue;
+            out.push({ ...p });
+        }
+        return out;
+    }
+    get(id) { const p = this.rows.find((x) => x.id === id); return p ? { ...p } : undefined; }
+    setStatus(id, status) {
+        const p = this.rows.find((x) => x.id === id);
+        if (!p)
+            return undefined;
+        p.status = status; // confirming NEVER arms: an order plan still needs a physical keypress in the signer flow
+        return { ...p };
+    }
+    close() { }
+}
+/**
+ * Persistent store in the shared dexterm SQLite DB so the TUI roster, `dexterm agent proposals` and a
+ * later confirm flow read the same rows across processes. The UNIQUE (agent_id, idempotency_key) index
+ * makes idempotency a database guarantee, not just a scan. Display strings are firewalled before insert.
+ */
+export class SqliteProposalStore {
+    db;
+    now;
+    seq = 0;
+    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_proposal (
+        id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, agent_name TEXT NOT NULL, kind TEXT NOT NULL,
+        mint TEXT NOT NULL, idem TEXT NOT NULL, created_at INTEGER NOT NULL, status TEXT NOT NULL,
+        summary TEXT NOT NULL, detail TEXT NOT NULL
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS agent_proposal_idem ON agent_proposal(agent_id, idem);
+      CREATE INDEX IF NOT EXISTS agent_proposal_agent ON agent_proposal(agent_id, created_at);
+    `);
+    }
+    row(r) {
+        return { id: String(r.id), agentId: String(r.agent_id), agentName: String(r.agent_name), kind: r.kind, mint: String(r.mint), idempotencyKey: String(r.idem), createdAt: Number(r.created_at), status: r.status, summary: String(r.summary), detail: JSON.parse(String(r.detail)), armed: false };
+    }
+    create(session, tool, args) {
+        const kind = TOOL_TO_KIND[tool];
+        if (!kind)
+            throw new Error(`not a proposal tool: ${tool}`);
+        const key = String(args.idempotency_key);
+        const existingRow = this.db.prepare('SELECT * FROM agent_proposal WHERE agent_id = ? AND idem = ?').get(session.agentId, key);
+        if (existingRow)
+            return { proposal: this.row(existingRow), duplicate: true };
+        const mint = String(args.mint);
+        const { summary, detail } = proposalView(kind, mint, args);
+        const id = `prop_${(++this.seq).toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        const createdAt = this.now();
+        try {
+            this.db.prepare('INSERT INTO agent_proposal (id, agent_id, agent_name, kind, mint, idem, created_at, status, summary, detail) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+                .run(id, session.agentId, session.agentName, kind, mint, key, createdAt, 'pending', summary, JSON.stringify(detail));
+        }
+        catch {
+            // a concurrent insert won the UNIQUE race: return the row that landed
+            const r = this.db.prepare('SELECT * FROM agent_proposal WHERE agent_id = ? AND idem = ?').get(session.agentId, key);
+            if (r)
+                return { proposal: this.row(r), duplicate: true };
+            throw new Error('proposal insert failed');
+        }
+        return { proposal: { id, agentId: session.agentId, agentName: session.agentName, kind, mint, idempotencyKey: key, createdAt, status: 'pending', summary, detail, armed: false }, duplicate: false };
+    }
+    list(filter = {}) {
+        const where = [];
+        const params = [];
+        if (filter.agentId) {
+            where.push('agent_id = ?');
+            params.push(filter.agentId);
+        }
+        if (filter.status) {
+            where.push('status = ?');
+            params.push(filter.status);
+        }
+        const sql = `SELECT * FROM agent_proposal${where.length ? ' WHERE ' + where.join(' AND ') : ''} ORDER BY created_at DESC LIMIT ?`;
+        return this.db.prepare(sql).all(...params, Math.max(1, Math.min(filter.limit ?? 100, 500))).map((r) => this.row(r));
+    }
+    get(id) { const r = this.db.prepare('SELECT * FROM agent_proposal WHERE id = ?').get(id); return r ? this.row(r) : undefined; }
+    setStatus(id, status) {
+        this.db.prepare('UPDATE agent_proposal SET status = ? WHERE id = ?').run(status, id);
+        return this.get(id);
+    }
+    close() { try {
+        this.db.close();
+    }
+    catch { /* ignore */ } }
+}

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

@@ -0,0 +1,87 @@
+// @dexterm/agents — a small, total JSON-schema checker for tool arguments (task-1345).
+//
+// Covers the subset the dexterm tool table uses: object/string/integer/number/boolean, enum, minimum,
+// maximum, maxLength, required, additionalProperties:false, nested objects. Anything the schema does
+// not mention is an error (schemas are closed: `additionalProperties` defaults to false for agent
+// calls even when a schema omits it). Pure and never throws.
+const MAX_STRING = 2000;
+const MAX_DEPTH = 6;
+const MAX_KEYS = 32;
+export function validateArgs(schema, value, path = 'args', depth = 0) {
+    if (depth > MAX_DEPTH)
+        return `${path}: too deeply nested`;
+    if (!schema)
+        return value === undefined || (typeof value === 'object' && value !== null && !Array.isArray(value) && Object.keys(value).length === 0) ? null : `${path}: this tool takes no arguments`;
+    const t = schema.type ?? (schema.properties ? 'object' : undefined);
+    if (schema.enum && !schema.enum.includes(value))
+        return `${path}: must be one of ${schema.enum.map((v) => JSON.stringify(v)).join(', ')}`;
+    switch (t) {
+        case 'object': {
+            if (typeof value !== 'object' || value === null || Array.isArray(value))
+                return `${path}: must be an object`;
+            const obj = value;
+            const keys = Object.keys(obj);
+            if (keys.length > MAX_KEYS)
+                return `${path}: too many fields`;
+            const props = schema.properties ?? {};
+            for (const k of keys) {
+                if (k === '__proto__' || k === 'constructor' || k === 'prototype')
+                    return `${path}.${k}: not allowed`;
+                if (!Object.hasOwn(props, k))
+                    return `${path}.${k}: unknown field`;
+            }
+            for (const r of schema.required ?? [])
+                if (!Object.hasOwn(obj, r) || obj[r] === undefined)
+                    return `${path}.${r}: required`;
+            for (const k of keys) {
+                const err = validateArgs(props[k], obj[k], `${path}.${k}`, depth + 1);
+                if (err)
+                    return err;
+            }
+            return null;
+        }
+        case 'string': {
+            if (typeof value !== 'string')
+                return `${path}: must be a string`;
+            const max = Math.min(schema.maxLength ?? MAX_STRING, MAX_STRING);
+            if (value.length > max)
+                return `${path}: longer than ${max} characters`;
+            if (schema.minLength !== undefined && value.length < schema.minLength)
+                return `${path}: shorter than ${schema.minLength} characters`;
+            if (schema.pattern && !new RegExp(schema.pattern).test(value))
+                return `${path}: does not match the expected format`;
+            // eslint-disable-next-line no-control-regex
+            if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/.test(value))
+                return `${path}: control characters are not allowed`;
+            return null;
+        }
+        case 'integer':
+        case 'number': {
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                return `${path}: must be a finite number`;
+            if (t === 'integer' && !Number.isInteger(value))
+                return `${path}: must be an integer`;
+            if (schema.minimum !== undefined && value < schema.minimum)
+                return `${path}: below ${schema.minimum}`;
+            if (schema.maximum !== undefined && value > schema.maximum)
+                return `${path}: above ${schema.maximum}`;
+            return null;
+        }
+        case 'boolean':
+            return typeof value === 'boolean' ? null : `${path}: must be true or false`;
+        case 'array': {
+            if (!Array.isArray(value))
+                return `${path}: must be an array`;
+            if (value.length > (schema.maxItems ?? 64))
+                return `${path}: too many items`;
+            for (let i = 0; i < value.length; i++) {
+                const err = validateArgs(schema.items ?? {}, value[i], `${path}[${i}]`, depth + 1);
+                if (err)
+                    return err;
+            }
+            return null;
+        }
+        default:
+            return value === undefined ? null : `${path}: unexpected value`;
+    }
+}

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

@@ -0,0 +1,140 @@
+// @dexterm/agents/sdk — the small TypeScript SDK (task-1345, tier 2). A bring-your-own-agent connects to
+// a running dexterm's loopback bus with its registered name + token, lists the tools its tier allows,
+// calls read/navigation tools, subscribes to live topics, and creates proposals the user confirms. Uses
+// Node's built-in global `WebSocket` client (Node ≥ 22) so the SDK ships with zero dependencies. It can
+// never arm, sign, send or raise a cap — those tools do not exist and the server refuses the shape.
+//
+// Usage:
+//   const agent = await connectAgent({ name: 'scanbot', token: process.env.DEXTERM_AGENT_TOKEN! });
+//   const tools = await agent.listTools();
+//   const rows = await agent.call('screener_query', { preset: 'new', limit: 8 });
+//   const off = agent.on('new_pairs', (ev) => console.log(ev.data));
+//   await agent.subscribe(['new_pairs']);
+//   await agent.propose('propose_alert', { mint, when: 'mcap crosses 1M', idempotency_key: 'k-'+Date.now() });
+//   agent.close();
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+/** Read the bus discovery file a running dexterm writes (<home>/agent-bus.json). */
+export function loadBusDiscovery(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? (env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm'));
+    try {
+        const d = JSON.parse(readFileSync(join(home, 'agent-bus.json'), 'utf8'));
+        return typeof d.port === 'number' && d.port > 0 ? { port: d.port } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export class DextermAgent {
+    ws;
+    pending = new Map();
+    listeners = new Map();
+    seq = 0;
+    closed = false;
+    hello = null;
+    constructor(ws) {
+        this.ws = ws;
+        ws.addEventListener('message', (e) => this.onMessage(String(e.data)));
+        ws.addEventListener('close', () => { this.closed = true; for (const p of this.pending.values())
+            p.reject(new Error('connection closed')); this.pending.clear(); });
+    }
+    static async connect(opts) {
+        let port = opts.port;
+        let url = opts.url;
+        if (!url) {
+            if (!port) {
+                const d = loadBusDiscovery({ home: opts.home });
+                if (!d)
+                    throw new Error('no --port/--url and no agent-bus.json discovery file: is dexterm running with the agent bus enabled?');
+                port = d.port;
+            }
+            url = `ws://127.0.0.1:${port}`;
+        }
+        const ws = new WebSocket(url);
+        await new Promise((resolve, reject) => {
+            const to = setTimeout(() => reject(new Error('timed out opening the bus socket')), opts.timeoutMs ?? 5000);
+            ws.addEventListener('open', () => { clearTimeout(to); resolve(); }, { once: true });
+            ws.addEventListener('error', () => { clearTimeout(to); reject(new Error('could not open the bus socket')); }, { once: true });
+        });
+        const agent = new DextermAgent(ws);
+        const hello = await agent.request('hello', { name: opts.name, token: opts.token, tier: opts.tier, client: opts.client }, opts.timeoutMs);
+        agent.hello = hello;
+        return agent;
+    }
+    onMessage(text) {
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (msg.method === 'event' && msg.params) {
+            const ev = msg.params;
+            for (const l of this.listeners.get(ev.topic) ?? []) {
+                try {
+                    l(ev);
+                }
+                catch { /* ignore */ }
+            }
+            return;
+        }
+        if (typeof msg.id === 'number') {
+            const p = this.pending.get(msg.id);
+            if (!p)
+                return;
+            this.pending.delete(msg.id);
+            if (msg.error) {
+                const err = new Error(msg.error.message ?? 'bus error');
+                err.data = msg.error.data;
+                p.reject(err);
+            }
+            else
+                p.resolve(msg.result ?? {});
+        }
+    }
+    request(method, params, timeoutMs = 10_000) {
+        if (this.closed)
+            return Promise.reject(new Error('connection closed'));
+        const id = ++this.seq;
+        return new Promise((resolve, reject) => {
+            const to = setTimeout(() => { this.pending.delete(id); reject(new Error(`timed out waiting for ${method}`)); }, timeoutMs);
+            this.pending.set(id, { resolve: (v) => { clearTimeout(to); resolve(v); }, reject: (e) => { clearTimeout(to); reject(e); } });
+            this.ws.send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
+        });
+    }
+    /** List the tools this agent's tier may call. */
+    async listTools() {
+        const r = await this.request('tools/list', {});
+        return r.tools ?? [];
+    }
+    /** Call a read or navigation tool and return its result (or an object with an `error` field). */
+    async call(name, args = {}) {
+        return this.request('tools/call', { name, arguments: args });
+    }
+    /** Create a proposal the user must confirm. Alias of call() with a clearer name. */
+    async propose(name, args) {
+        return this.call(name, args);
+    }
+    async whoami() { return this.call('agent_whoami'); }
+    /** Register a listener for a topic. Call subscribe() to actually start the server-side stream. */
+    on(topic, listener) {
+        let set = this.listeners.get(topic);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(topic, set);
+        }
+        set.add(listener);
+        return () => set.delete(listener);
+    }
+    async subscribe(topics) { const r = await this.call('subscribe', { topics }); return r.subscribed ?? []; }
+    async unsubscribe(topics) { const r = await this.call('unsubscribe', topics ? { topics } : {}); return r.subscribed ?? []; }
+    async ping() { const r = await this.request('ping', {}); return r.pong === true; }
+    close() { this.closed = true; try {
+        this.ws.close();
+    }
+    catch { /* ignore */ } }
+}
+export function connectAgent(opts) { return DextermAgent.connect(opts); }

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

@@ -0,0 +1,114 @@
+// @dexterm/agents — capability tiers (task-1345, design task-1295 §2).
+//
+// Three tiers, strictly ordered, enforced SERVER-SIDE per agent identity by the gate (gate.ts). The
+// tier an agent has comes from the user's registry (identity.ts), never from anything the agent sends:
+// a client may only ask to run BELOW its granted tier.
+//
+//   observe   read tools and live streams
+//   annotate  + non-financial UI navigation on the user's screen, agent-owned notes/tags on coins
+//   propose   + proposals: alerts, order plans, watchlist adds — they appear labelled with the agent and
+//               need the user's keypress; nothing an agent proposes is ever applied by itself
+//
+// NEVER, for any agent at any tier (ROADMAP hard rule, SPEC §6.0): arm, sign, confirm, send, raise or
+// change a cap, change the confirmation gate, touch the wallet, a mandate or the signer. No such tool
+// exists in the table below, and `neverAllowed()` refuses the *shape* of such a request before any
+// lookup, so a future tool with a dangerous name cannot be added by accident.
+export const TIERS = ['observe', 'annotate', 'propose'];
+export const TIER_RANK = { observe: 0, annotate: 1, propose: 2 };
+export function isTier(x) {
+    return typeof x === 'string' && TIERS.includes(x);
+}
+/** True when `have` is at least `need`. */
+export function tierAtLeast(have, need) {
+    return TIER_RANK[have] >= TIER_RANK[need];
+}
+/** The lower of two tiers (a client may request to run below its grant, never above). */
+export function lowerTier(a, b) {
+    return TIER_RANK[a] <= TIER_RANK[b] ? a : b;
+}
+/**
+ * Every tool or bus method an agent may call, with the minimum tier. Anything absent is refused as
+ * `unknown-tool`. The TUI's own analyst keeps its separate task-1313 channel; this table governs
+ * external agents only (bus and bridged MCP).
+ */
+export const TOOL_TIERS = Object.freeze({
+    // ---- observe: read tools (the task-1302/1314/1315 MCP surface) + bus reads
+    screen_state: 'observe',
+    screener_query: 'observe',
+    get_token: 'observe',
+    get_dossier: 'observe',
+    get_holders: 'observe',
+    get_trades: 'observe',
+    get_candles: 'observe',
+    rugcheck: 'observe',
+    get_dev_history: 'observe',
+    kb_lookup: 'observe',
+    kb_search: 'observe',
+    case_lookup: 'observe',
+    get_links: 'observe',
+    fetch_page: 'observe',
+    check_domain: 'observe',
+    check_github: 'observe',
+    agent_whoami: 'observe',
+    list_proposals: 'observe',
+    subscribe: 'observe',
+    unsubscribe: 'observe',
+    // ---- annotate: non-financial navigation + agent-owned annotations
+    open_token: 'annotate',
+    show_in_screener: 'annotate',
+    switch_feed: 'annotate',
+    agent_note: 'annotate',
+    // ---- propose: proposals the user must confirm with a keypress
+    propose_alert: 'propose',
+    propose_order_plan: 'propose',
+    add_to_watchlist: 'propose',
+});
+/** Tools that are proposals (write-shaped): they need an idempotency key and count against the proposal quota. */
+export const PROPOSAL_TOOLS = new Set(['propose_alert', 'propose_order_plan', 'add_to_watchlist']);
+/** UI-navigation tools (count against the shared ACTION_RATE window like the analyst's). */
+export const NAVIGATION_TOOLS = new Set(['open_token', 'show_in_screener', 'switch_feed']);
+/**
+ * Names and name-shapes no agent may ever reach, whatever the table says. Checked FIRST. Deliberately
+ * broad: a false positive costs an agent one odd tool name; a false negative is money.
+ */
+export const NEVER_PATTERNS = [
+    /\barm\b|arm_|_arm|arming/i,
+    /\bsign\b|sign_|_sign|signer|signature/i,
+    /\bconfirm\b|confirm_|_confirm/i,
+    /\bsend\b|send_|_send|submit|broadcast/i,
+    /\bswap\b|swap_|_swap|transfer|withdraw|deposit|approve/i,
+    /\bcap\b|caps?_|_caps?|raise|limit_set|set_limit|budget_set|set_budget|ceiling/i,
+    /\bgate\b|gate_|_gate|keypress|opt_?out|less_?safe/i,
+    /mandate|wallet|panic|resume_live|go_?live|set_?mode|live_mode|mainnet/i,
+    /\bkey\b|keys?_|_keys?|secret|seed|mnemonic|private|credential|token_?file|helius/i,
+    /\bexec\b|exec_|shell|spawn|eval|file|path|read_?dir|env|process/i,
+    /\bticket\b|ticket_|_ticket|execute|trade_now|buy_now|sell_now|\bfill\b/i,
+    /set_tier|grant|escalate|promote|admin|sudo|root|kick|pause_agent|unpause/i,
+];
+/** True when a requested tool/method name is on the never-list (refused before any lookup). */
+export function neverAllowed(name) {
+    if (typeof name !== 'string')
+        return true;
+    if (name.length > 64)
+        return true;
+    if (!/^[a-z][a-z0-9_./-]*$/i.test(name))
+        return true; // odd shapes are refused, never parsed
+    if (name in TOOL_TIERS)
+        return false; // table names are vetted by hand and tested below the never-list
+    return NEVER_PATTERNS.some((re) => re.test(name));
+}
+/** The minimum tier for a tool, or null when it is not a tool an agent may call at all. */
+export function tierFor(name) {
+    if (neverAllowed(name))
+        return null;
+    return Object.hasOwn(TOOL_TIERS, name) ? TOOL_TIERS[name] : null;
+}
+/** Tools a tier may call (for `tools/list` filtering and the roster's tier legend). */
+export function toolsForTier(tier) {
+    return Object.keys(TOOL_TIERS).filter((t) => tierAtLeast(tier, TOOL_TIERS[t]));
+}
+export const TIER_LEGEND = {
+    observe: 'read tools + streams',
+    annotate: 'navigation, notes, tags',
+    propose: 'alerts, order plans, watch adds — as proposals',
+};

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

@@ -0,0 +1,69 @@
+// @dexterm/agents — the agent tool table (task-1345, tier 2). One source of truth for what an external
+// agent may call over the bus or a bridged MCP child: the advertised name + description + closed input
+// schema + minimum tier. The gate validates arguments against these schemas; `tools/list` filters them
+// to the session's tier. Every tool here is read-only, navigation, or a PROPOSAL (user confirms with a
+// keypress). Nothing here builds, signs, sends, arms, raises a cap, or touches a wallet/mandate/signer —
+// the never-list (tiers.ts) refuses that shape before this table is ever consulted.
+import { TOOL_TIERS } from "./tiers.js";
+const MINT = { type: 'string', pattern: '^[1-9A-HJ-NP-Za-km-z]{32,44}$', maxLength: 44 };
+const SYMBOL = { type: 'string', maxLength: 32 };
+const IDEMPOTENCY = { type: 'string', minLength: 8, maxLength: 64, pattern: '^[A-Za-z0-9_.:-]+$' };
+const URL = { type: 'string', maxLength: 512, pattern: '^https?://' };
+/** Advertised tool table. Order is the order `tools/list` returns. */
+const TOOLS_DEF = [
+    // ---------------------------------------------------------------- observe: bus-native
+    { name: 'agent_whoami', tier: 'observe', description: 'Who am I to the server: my name, granted tier, the tools my tier may call, my current rate/quota usage, and my live subscriptions. Identity and tier come from the server, never from me.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { name: 'subscribe', tier: 'observe', description: 'Subscribe to live topics. Each pushed event is server-authored and firewalled. Topics: new_pairs, trades, alerts, screen. Events arrive as JSON-RPC notifications with method "event".', inputSchema: { type: 'object', properties: { topics: { type: 'array', items: { type: 'string', enum: ['new_pairs', 'trades', 'alerts', 'screen'] }, maxItems: 4 } }, required: ['topics'], additionalProperties: false } },
+    { name: 'unsubscribe', tier: 'observe', description: 'Stop receiving events for the given topics (or all when topics is omitted).', inputSchema: { type: 'object', properties: { topics: { type: 'array', items: { type: 'string', enum: ['new_pairs', 'trades', 'alerts', 'screen'] }, maxItems: 4 } }, additionalProperties: false } },
+    { name: 'list_proposals', tier: 'observe', description: 'List the proposals this agent has created and their status (pending / confirmed / dismissed). An agent can never confirm a proposal itself; the user confirms with a keypress.', inputSchema: { type: 'object', properties: { limit: { type: 'integer', minimum: 1, maximum: 100 } }, additionalProperties: false } },
+    // ---------------------------------------------------------------- observe: read tools (mirror of the MCP surface)
+    { name: 'screen_state', tier: 'observe', description: 'What is on screen in dexterm right now: screen, filter, sort, selected token, visible mints, watchlist. Gives you the same context the user has.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { name: 'screener_query', tier: 'observe', description: 'Screener rows with provenance. preset: "new" (youngest), "trending" (volume), "all".', inputSchema: { type: 'object', properties: { preset: { type: 'string', enum: ['new', 'trending', 'all'] }, limit: { type: 'integer', minimum: 1, maximum: 50 } }, additionalProperties: false } },
+    { name: 'get_token', tier: 'observe', description: 'Token + Pair + Stats + Audit for a mint or symbol, each with source and age. Ambiguous symbols return candidates.', inputSchema: { type: 'object', properties: { mint: MINT, symbol: SYMBOL }, additionalProperties: false } },
+    { name: 'get_dossier', tier: 'observe', description: 'One pre-assembled dossier (market, holders, security, candles, tape, creator) for a mint or symbol in a single round trip. Read `availability` for which sections are present.', inputSchema: { type: 'object', properties: { mint: MINT, symbol: SYMBOL, interval: { type: 'string', enum: ['1m', '5m', '15m', '1h', '4h', '1d'] } }, additionalProperties: false } },
+    { name: 'get_holders', tier: 'observe', description: 'Top holders (≤50) with the top10 share excluding LP.', inputSchema: { type: 'object', properties: { mint: MINT, top: { type: 'integer', minimum: 1, maximum: 50 } }, required: ['mint'], additionalProperties: false } },
+    { name: 'get_trades', tier: 'observe', description: 'Recent trades of the most liquid pool with buy/sell aggregates and a wash signal.', inputSchema: { type: 'object', properties: { mint: MINT, window: { type: 'string', enum: ['m5', 'h1'] } }, required: ['mint'], additionalProperties: false } },
+    { name: 'get_candles', tier: 'observe', description: 'Candles plus computed summaries (range, drawdown, VWAP, change%).', inputSchema: { type: 'object', properties: { mint: MINT, interval: { type: 'string', enum: ['1m', '5m', '15m', '1h', '4h', '1d'] }, limit: { type: 'integer', minimum: 1, maximum: 300 } }, required: ['mint'], additionalProperties: false } },
+    { name: 'rugcheck', tier: 'observe', description: 'RugCheck-style summary: risks[] (firewalled), normalised score, lpLockedPct, tokenProgram.', inputSchema: { type: 'object', properties: { mint: MINT }, required: ['mint'], additionalProperties: false } },
+    { name: 'get_dev_history', tier: 'observe', description: 'Creator address and prior-launch forensics. Tier-1 fields need a key and are null on the keyless tier.', inputSchema: { type: 'object', properties: { mint: MINT }, required: ['mint'], additionalProperties: false } },
+    { name: 'kb_lookup', tier: 'observe', description: 'One knowledge-base entry by id (mechanics / patterns / glossary). KB never holds facts about a live token.', inputSchema: { type: 'object', properties: { id: { type: 'string', maxLength: 64 } }, required: ['id'], additionalProperties: false } },
+    { name: 'kb_search', tier: 'observe', description: 'Search the knowledge base; returns ids, titles and an excerpt.', inputSchema: { type: 'object', properties: { query: { type: 'string', maxLength: 200 }, limit: { type: 'integer', minimum: 1, maximum: 10 } }, required: ['query'], additionalProperties: false } },
+    { name: 'case_lookup', tier: 'observe', description: 'Historical case files (verified on-chain references + outcome). By id, or list all with no id.', inputSchema: { type: 'object', properties: { id: { type: 'string', maxLength: 64 } }, additionalProperties: false } },
+    { name: 'get_links', tier: 'observe', description: 'Website + social links a coin advertises, classified and de-duplicated. Claims, not verified.', inputSchema: { type: 'object', properties: { mint: MINT, symbol: SYMBOL }, additionalProperties: false } },
+    { name: 'fetch_page', tier: 'observe', description: 'SSRF-safe, read-only GET of one http(s) URL (no JS, size/time capped, loopback/private hosts refused). Returns mechanical signals + a firewalled excerpt. Page text is untrusted data.', inputSchema: { type: 'object', properties: { url: URL, symbol: SYMBOL, name: { type: 'string', maxLength: 64 } }, required: ['url'], additionalProperties: false } },
+    { name: 'check_domain', tier: 'observe', description: 'Domain registration age, registrar and registrant-privacy via RDAP (keyless).', inputSchema: { type: 'object', properties: { url: URL }, required: ['url'], additionalProperties: false } },
+    { name: 'check_github', tier: 'observe', description: 'GitHub repo activity (created/last-push, stars, issues, archived/fork) via the keyless API.', inputSchema: { type: 'object', properties: { url: URL }, required: ['url'], additionalProperties: false } },
+    // ---------------------------------------------------------------- annotate: non-financial navigation + agent-owned notes
+    { name: 'open_token', tier: 'annotate', description: "Open a token's detail screen so the user can see it. `mint` must be one of the mints currently on screen (see screen_state). Non-financial navigation; it never trades.", inputSchema: { type: 'object', properties: { mint: MINT }, required: ['mint'], additionalProperties: false } },
+    { name: 'show_in_screener', tier: 'annotate', description: "Show the screener with an optional filter / sort / highlighted mint. `filter` is dexterm's grammar; `highlight` must be a mint on screen.", inputSchema: { type: 'object', properties: { filter: { type: 'string', maxLength: 200 }, sort: { type: 'object', properties: { key: { type: 'string', maxLength: 24 }, dir: { type: 'string', enum: ['asc', 'desc'] } }, required: ['key'], additionalProperties: false }, highlight: MINT }, additionalProperties: false } },
+    { name: 'switch_feed', tier: 'annotate', description: 'Switch the screener feed/preset. `feed` must be one of screen_state.actions.feeds.', inputSchema: { type: 'object', properties: { feed: { type: 'string', maxLength: 24 } }, required: ['feed'], additionalProperties: false } },
+    { name: 'agent_note', tier: 'annotate', description: "Attach this agent's own note/tag to a coin (visible in the roster and on the coin, labelled with this agent). Non-financial; the note text is firewalled before anyone sees it.", inputSchema: { type: 'object', properties: { mint: MINT, text: { type: 'string', minLength: 1, maxLength: 280 }, tag: { type: 'string', maxLength: 24, pattern: '^[a-z0-9][a-z0-9_-]*$' } }, required: ['mint', 'text'], additionalProperties: false } },
+    // ---------------------------------------------------------------- propose: proposals the user must confirm with a keypress
+    { name: 'propose_alert', tier: 'propose', description: 'Propose a watch alert on a mint (e.g. "mcap crosses 1M"). Appears as a PROPOSAL labelled with this agent; the user confirms with a keypress. You can never arm or fire it. Needs idempotency_key.', inputSchema: { type: 'object', properties: { mint: MINT, when: { type: 'string', minLength: 1, maxLength: 120 }, note: { type: 'string', maxLength: 200 }, idempotency_key: IDEMPOTENCY }, required: ['mint', 'when', 'idempotency_key'], additionalProperties: false } },
+    { name: 'propose_order_plan', tier: 'propose', description: 'Propose a PAPER order plan (side, size, triggers) as a DRAFT proposal labelled with this agent. It is never armed, signed or sent; arming needs a physical keypress by the user and signer-side caps still apply. Needs idempotency_key.', inputSchema: { type: 'object', properties: { mint: MINT, side: { type: 'string', enum: ['buy', 'sell'] }, size: { type: 'string', maxLength: 40 }, triggers: { type: 'array', items: { type: 'string', maxLength: 80 }, maxItems: 8 }, note: { type: 'string', maxLength: 200 }, idempotency_key: IDEMPOTENCY }, required: ['mint', 'side', 'size', 'idempotency_key'], additionalProperties: false } },
+    { name: 'add_to_watchlist', tier: 'propose', description: "Propose adding a token to the user's watchlist. Appears as a PROPOSAL labelled with this agent. Needs idempotency_key.", inputSchema: { type: 'object', properties: { mint: MINT, note: { type: 'string', maxLength: 200 }, idempotency_key: IDEMPOTENCY }, required: ['mint', 'idempotency_key'], additionalProperties: false } },
+];
+export const AGENT_TOOLS = Object.freeze(TOOLS_DEF);
+const BY_NAME = new Map(AGENT_TOOLS.map((t) => [t.name, t]));
+/** The closed input schema the gate validates a call's arguments against, or undefined for an unknown tool. */
+export function toolSchema(name) {
+    return BY_NAME.get(name)?.inputSchema;
+}
+export function agentTool(name) {
+    return BY_NAME.get(name);
+}
+/** The advertised tools a tier may call (for `tools/list`). */
+export function toolsForTierList(have, rank = { observe: 0, annotate: 1, propose: 2 }) {
+    return AGENT_TOOLS.filter((t) => rank[have] >= rank[t.tier]);
+}
+// Belt-and-braces: the advertised table and the tier table (tiers.ts) must not drift. Every advertised
+// tool must carry the same tier the gate reads; a mismatch would let a call pass the gate at the wrong
+// tier. Checked once at module load (throws loudly in tests / at startup rather than mis-serving).
+for (const t of AGENT_TOOLS) {
+    if (TOOL_TIERS[t.name] !== t.tier)
+        throw new Error(`agent tool "${t.name}" tier ${t.tier} disagrees with TOOL_TIERS ${TOOL_TIERS[t.name]}`);
+}
+for (const name of Object.keys(TOOL_TIERS)) {
+    if (!BY_NAME.has(name))
+        throw new Error(`TOOL_TIERS has "${name}" but AGENT_TOOLS does not advertise it`);
+}