@matuto-ai/claude-code-broker-connector 0.0.0-stage → 0.2.1

package/vendor/psst/reference/inbox.mjs

@@ -0,0 +1,289 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync, lstatSync, statfsSync, readdirSync, chmodSync, realpathSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { canonical, digest, validateEnvelope, validateUuid, validateSend, validateIdempotencyKey, TYPES } from '../src/protocol.mjs';
+import { LocalError } from './errors.mjs';
+
+export function newSessionIdentity(clientType) {
+  if (!TYPES.includes(clientType)) throw new LocalError('invalid_configuration');
+  return { client_id: randomUUID(), session_instance_id: randomUUID(), client_type: clientType };
+}
+
+function identityValue(identity) {
+  if (!identity || Object.keys(identity).sort().join(',') !== 'client_id,client_type,session_instance_id'
+    || !TYPES.includes(identity.client_type)) throw new LocalError('invalid_configuration');
+  return { client_id: validateUuid(identity.client_id), session_instance_id: validateUuid(identity.session_instance_id), client_type: identity.client_type };
+}
+
+/** One session-bound durable journal. A separate SQLite OS lock survives no process crash. */
+export class Inbox {
+  constructor({ directory, identity, now = Date.now, maxPendingCount = 1000,
+    maxPendingBytes = 64 * 1024 * 1024, maxLedgerCount = 50000,
+    maxOutgoingCount = 10000, maxDatabaseBytes = 128 * 1024 * 1024,
+    minFreeBytes = 16 * 1024 * 1024, retentionSeconds = 8 * 86400,
+    diskCheck, failurePoint = () => {} }) {
+    this.identity = identityValue(identity);
+    this.now = now;
+    this.failurePoint = failurePoint;
+    this.retentionSeconds = retentionSeconds;
+    this.limits = { maxPendingCount, maxPendingBytes, maxLedgerCount, maxOutgoingCount, maxDatabaseBytes, minFreeBytes };
+    for (const [key, value] of Object.entries({ ...this.limits, retentionSeconds })) {
+      if (!Number.isSafeInteger(value) || value < (key === 'minFreeBytes' ? 0 : 1)) throw new LocalError('invalid_configuration');
+    }
+    if (retentionSeconds < 7 * 86400) throw new LocalError('invalid_configuration');
+    this.directory = resolve(directory);
+    this.diskCheck = diskCheck;
+    this.closed = false;
+    this.storageUncertain = false;
+    try {
+      mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+      const dir = lstatSync(this.directory);
+      if (!dir.isDirectory() || dir.isSymbolicLink() || realpathSync(this.directory) !== this.directory || (dir.mode & 0o077) !== 0
+        || (process.getuid && dir.uid !== process.getuid())) throw new LocalError('invalid_configuration');
+      for (const name of ['inbox.sqlite', 'owner.sqlite']) {
+        const path = join(this.directory, name);
+        try {
+          const file = lstatSync(path);
+          if (!file.isFile() || file.isSymbolicLink() || (file.mode & 0o077) !== 0) throw new LocalError('invalid_configuration');
+        } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      }
+      this.checkDisk();
+      this.owner = new DatabaseSync(join(this.directory, 'owner.sqlite'));
+      chmodSync(join(this.directory, 'owner.sqlite'), 0o600);
+      try { this.owner.exec('PRAGMA busy_timeout=0; PRAGMA journal_mode=DELETE; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS owner(singleton INTEGER PRIMARY KEY CHECK(singleton=1));'); }
+      catch { throw new LocalError('owner_conflict'); }
+      this.db = new DatabaseSync(join(this.directory, 'inbox.sqlite'));
+      chmodSync(join(this.directory, 'inbox.sqlite'), 0o600);
+      if (this.db.prepare('PRAGMA user_version').get().user_version > 1) throw new LocalError('invalid_configuration');
+      this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA foreign_keys=ON;
+        PRAGMA busy_timeout=0; PRAGMA wal_autocheckpoint=100;
+        CREATE TABLE IF NOT EXISTS state(key TEXT PRIMARY KEY, value TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS inbox(
+          message_id TEXT PRIMARY KEY, sequence INTEGER NOT NULL UNIQUE, digest TEXT NOT NULL,
+          envelope TEXT NOT NULL, bytes INTEGER NOT NULL, state TEXT NOT NULL,
+          received_at INTEGER NOT NULL, retain_until INTEGER NOT NULL,
+          injection_id TEXT, native_receipt TEXT, consumed_at INTEGER);
+        CREATE TABLE IF NOT EXISTS outgoing(
+          key TEXT PRIMARY KEY, digest TEXT NOT NULL, request TEXT NOT NULL,
+          created_at INTEGER NOT NULL, retry_until INTEGER NOT NULL, result TEXT);
+        PRAGMA user_version=1;`);
+      const stored = this.getState('identity');
+      if (stored && canonical(stored) !== canonical(this.identity)) throw new LocalError('session_mismatch');
+      if (!stored) this.setState('identity', this.identity);
+      this.db.prepare("UPDATE inbox SET state='uncertain' WHERE state='injecting'").run();
+    } catch (error) {
+      this.db?.close();
+      this.owner?.close();
+      if (error instanceof LocalError) throw error;
+      throw new LocalError('storage_unavailable');
+    }
+  }
+
+  checkDisk(extra = 0) {
+    this.assertUsable();
+    if (this.closed) throw new LocalError('storage_unavailable');
+    try {
+      if (this.diskCheck && !this.diskCheck(extra)) throw new Error('disk');
+      const disk = statfsSync(this.directory);
+      if ([0x6969, 0x517b, 0xff534d42].includes(Number(disk.type))) throw new Error('unsupported filesystem');
+      const bytes = readdirSync(this.directory).reduce((total, name) => {
+        const stat = lstatSync(join(this.directory, name));
+        return total + (stat.isFile() ? stat.size : 0);
+      }, 0);
+      if (Number(disk.bavail) * Number(disk.bsize) < this.limits.minFreeBytes + extra
+        || bytes + extra > this.limits.maxDatabaseBytes) throw new Error('disk');
+    } catch { throw new LocalError('storage_unavailable', { retryable: true }); }
+  }
+
+  transaction(callback, { growth = 0 } = {}) {
+    this.checkDisk(growth);
+    let commitAttempted = false;
+    let committed = false;
+    try {
+      this.db.exec('BEGIN IMMEDIATE');
+      const result = callback();
+      this.failurePoint('before_commit');
+      commitAttempted = true;
+      this.db.exec('COMMIT');
+      committed = true;
+      this.failurePoint('after_commit');
+      return result;
+    } catch (error) {
+      let rollbackConfirmed = false;
+      try { this.failurePoint('before_rollback'); this.db.exec('ROLLBACK'); rollbackConfirmed = true; } catch { /* The effect may be unknown. */ }
+      const effect = committed || (commitAttempted && !rollbackConfirmed) || !rollbackConfirmed ? 'unknown' : 'not_applied';
+      // A failed rollback can leave uncommitted rows visible on this connection.
+      // Do not allow a later duplicate lookup to ACK those rows. Reopen first.
+      if (!committed && !rollbackConfirmed) this.storageUncertain = true;
+      if (error instanceof LocalError && effect === 'not_applied') throw error;
+      throw new LocalError('storage_unavailable', { retryable: true, effect });
+    }
+  }
+
+  assertUsable() {
+    if (this.closed || this.storageUncertain) throw new LocalError('storage_unavailable', { effect: this.storageUncertain ? 'unknown' : 'not_applied', retryable: true });
+  }
+
+  getState(key) {
+    this.assertUsable();
+    const row = this.db.prepare('SELECT value FROM state WHERE key=?').get(key);
+    return row ? JSON.parse(row.value) : null;
+  }
+
+  setState(key, value) {
+    if (!['identity', 'attachment', 'registration_pending', 'claim_pending', 'metadata'].includes(key)) throw new LocalError('invalid_configuration');
+    const encoded = canonical(value);
+    if (Buffer.byteLength(encoded) > 256 * 1024) throw new LocalError('invalid_configuration');
+    return this.transaction(() => this.db.prepare('INSERT INTO state(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run(key, encoded), { growth: Buffer.byteLength(encoded) + 4096 });
+  }
+
+  accept(rawEnvelope, { serverNow = this.now(), retentionSeconds = this.retentionSeconds, retryWindowSeconds = 86400 } = {}) {
+    this.assertUsable();
+    let envelope;
+    try { envelope = validateEnvelope(rawEnvelope); }
+    catch { throw new LocalError('invalid_envelope'); }
+    if (envelope.recipient_id !== this.identity.client_id) throw new LocalError('session_mismatch');
+    const encoded = canonical(envelope);
+    const hash = digest(envelope);
+    const bytes = Buffer.byteLength(encoded);
+    if (!Number.isSafeInteger(retentionSeconds) || retentionSeconds < 7 * 86400
+      || !Number.isSafeInteger(retryWindowSeconds) || retryWindowSeconds < 1) throw new LocalError('invalid_configuration');
+    const existing = this.db.prepare('SELECT digest FROM inbox WHERE message_id=?').get(envelope.message_id);
+    if (existing) {
+      if (existing.digest !== hash) throw new LocalError('envelope_mismatch');
+      // A late redelivery restarts the local retention guarantee. If extending it
+      // fails, withhold ACK: saying not_stored would contradict this known row.
+      try {
+        this.transaction(() => this.db.prepare('UPDATE inbox SET retain_until=MAX(retain_until,?) WHERE message_id=?')
+          .run(this.now() + Math.max(retentionSeconds, this.retentionSeconds) * 1000, envelope.message_id));
+      } catch { throw new LocalError('storage_unavailable', { effect: 'unknown', retryable: true }); }
+      return { stored: true, duplicate: true, message_id: envelope.message_id };
+    }
+    if (Date.parse(envelope.expires_at) <= serverNow) throw new LocalError('envelope_expired');
+    return this.transaction(() => {
+      const usage = this.stats();
+      if (usage.pending_count >= this.limits.maxPendingCount || usage.pending_bytes + bytes > this.limits.maxPendingBytes
+        || usage.ledger_count >= this.limits.maxLedgerCount) throw new LocalError('inbox_full', { retryable: true });
+      const highest = this.db.prepare('SELECT MAX(sequence) AS sequence FROM inbox').get().sequence ?? 0;
+      const lastSequence = this.getState('attachment')?.highest_received_sequence ?? 0;
+      if (envelope.recipient_sequence <= Math.max(highest, lastSequence)) throw new LocalError('envelope_mismatch');
+      const retainUntil = Math.max(this.now() + Math.max(retentionSeconds, this.retentionSeconds) * 1000,
+        this.now() + Math.max(0, Date.parse(envelope.expires_at) - serverNow) + retryWindowSeconds * 1000);
+      this.db.prepare(`INSERT INTO inbox(message_id,sequence,digest,envelope,bytes,state,received_at,retain_until)
+        VALUES(?,?,?,?,?,'pending',?,?)`).run(envelope.message_id, envelope.recipient_sequence, hash, encoded, bytes, this.now(), retainUntil);
+      const attachment = { ...(this.getState('attachment') ?? {}), highest_received_sequence: envelope.recipient_sequence };
+      this.db.prepare('INSERT INTO state(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run('attachment', canonical(attachment));
+      this.failurePoint('after_inbox_insert');
+      return { stored: true, duplicate: false, message_id: envelope.message_id };
+    }, { growth: bytes * 3 + 16384 });
+  }
+
+  stats() {
+    this.assertUsable();
+    const row = this.db.prepare("SELECT COUNT(*) AS ledger_count, COALESCE(SUM(CASE WHEN state!='consumed' THEN 1 ELSE 0 END),0) AS pending_count, COALESCE(SUM(CASE WHEN state!='consumed' THEN bytes ELSE 0 END),0) AS pending_bytes FROM inbox").get();
+    return { ...row };
+  }
+
+  head() {
+    this.assertUsable();
+    const row = this.db.prepare("SELECT * FROM inbox WHERE state!='consumed' ORDER BY sequence LIMIT 1").get();
+    return row ? { message_id: row.message_id, sequence: row.sequence, state: row.state,
+      envelope: JSON.parse(row.envelope), injection_id: row.injection_id } : null;
+  }
+
+  beginInjection(messageId) {
+    return this.transaction(() => {
+      const head = this.head();
+      if (!head || head.message_id !== messageId) throw new LocalError('unsafe_boundary');
+      if (head.state !== 'pending') throw new LocalError('injection_uncertain');
+      const injectionId = randomUUID();
+      this.db.prepare("UPDATE inbox SET state='injecting', injection_id=? WHERE message_id=?").run(injectionId, messageId);
+      return injectionId;
+    });
+  }
+
+  recordNativeAcceptance(messageId, injectionId, receipt) {
+    if (!receipt || receipt.accepted !== true || typeof receipt.receipt_id !== 'string'
+      || receipt.receipt_id.length < 1 || receipt.receipt_id.length > 256
+      || /[\x00-\x1f\x7f]/.test(receipt.receipt_id)) throw new LocalError('receipt_required', { effect: 'unknown' });
+    return this.transaction(() => {
+      const row = this.db.prepare('SELECT state,injection_id FROM inbox WHERE message_id=?').get(messageId);
+      if (!row || !['injecting', 'uncertain'].includes(row.state) || row.injection_id !== injectionId) throw new LocalError('injection_uncertain');
+      this.db.prepare("UPDATE inbox SET state='consumed', native_receipt=?, consumed_at=? WHERE message_id=?").run(receipt.receipt_id, this.now(), messageId);
+    });
+  }
+
+  recordNativeRejection(messageId, injectionId, { definitelyNotAccepted } = {}) {
+    if (definitelyNotAccepted !== true) throw new LocalError('injection_uncertain', { effect: 'unknown' });
+    return this.transaction(() => {
+      const row = this.db.prepare('SELECT state,injection_id FROM inbox WHERE message_id=?').get(messageId);
+      if (!row || row.state !== 'injecting' || row.injection_id !== injectionId) throw new LocalError('injection_uncertain');
+      this.db.prepare("UPDATE inbox SET state='pending', injection_id=NULL WHERE message_id=?").run(messageId);
+    });
+  }
+
+  /** Operator-only local API. Never expose this through an agent tool. */
+  resolveUncertain(messageId, { resolution, duplicateRiskAcknowledged = false } = {}) {
+    if (!['accepted', 'retry'].includes(resolution) || (resolution === 'retry' && duplicateRiskAcknowledged !== true)) throw new LocalError('injection_uncertain');
+    return this.transaction(() => {
+      const row = this.db.prepare('SELECT state FROM inbox WHERE message_id=?').get(messageId);
+      if (!row || !['injecting', 'uncertain'].includes(row.state)) throw new LocalError('injection_uncertain');
+      if (resolution === 'accepted') this.db.prepare("UPDATE inbox SET state='consumed',native_receipt='operator-confirmed',consumed_at=? WHERE message_id=?").run(this.now(), messageId);
+      else this.db.prepare("UPDATE inbox SET state='pending',injection_id=NULL WHERE message_id=?").run(messageId);
+    });
+  }
+
+  prepareSend(rawRequest, { key = randomUUID(), retryWindowSeconds = 86400 } = {}) {
+    key = validateIdempotencyKey(key);
+    const request = validateSend(rawRequest);
+    const encoded = canonical(request);
+    const hash = digest(request);
+    const existing = this.outgoing(key);
+    if (existing) {
+      if (existing.digest !== hash) throw new LocalError('send_conflict');
+      return key;
+    }
+    if (!Number.isSafeInteger(retryWindowSeconds) || retryWindowSeconds < 1) throw new LocalError('invalid_configuration');
+    this.transaction(() => {
+      if (this.db.prepare('SELECT COUNT(*) AS n FROM outgoing').get().n >= this.limits.maxOutgoingCount) throw new LocalError('inbox_full');
+      this.db.prepare('INSERT INTO outgoing(key,digest,request,created_at,retry_until) VALUES(?,?,?,?,?)').run(key, hash, encoded, this.now(), this.now() + retryWindowSeconds * 1000);
+    }, { growth: Buffer.byteLength(encoded) * 3 + 8192 });
+    return key;
+  }
+
+  outgoing(key) {
+    this.assertUsable();
+    const row = this.db.prepare('SELECT * FROM outgoing WHERE key=?').get(key);
+    return row ? { ...row, request: JSON.parse(row.request), result: row.result ? JSON.parse(row.result) : null } : null;
+  }
+
+  unresolvedSends() {
+    this.assertUsable();
+    return this.db.prepare('SELECT key,created_at,retry_until FROM outgoing WHERE result IS NULL ORDER BY created_at LIMIT 100').all().map(row => ({ ...row }));
+  }
+
+  recordSendResult(key, result) {
+    const encoded = canonical(result);
+    if (Buffer.byteLength(encoded) > 16384) throw new LocalError('invalid_response', { effect: 'unknown' });
+    this.transaction(() => {
+      if (!this.outgoing(key)) throw new LocalError('invalid_configuration');
+      this.db.prepare('UPDATE outgoing SET result=? WHERE key=?').run(encoded, key);
+    }, { growth: Buffer.byteLength(encoded) * 2 + 8192 });
+  }
+
+  collect(limit = 100) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) throw new LocalError('invalid_configuration');
+    return this.transaction(() => {
+      const removedInbox = this.db.prepare("DELETE FROM inbox WHERE message_id IN (SELECT message_id FROM inbox WHERE state='consumed' AND retain_until<? ORDER BY retain_until LIMIT ?)").run(this.now(), limit).changes;
+      const removedSends = this.db.prepare('DELETE FROM outgoing WHERE key IN (SELECT key FROM outgoing WHERE result IS NOT NULL AND retry_until<? ORDER BY retry_until LIMIT ?)').run(this.now(), limit).changes;
+      return { removed_inbox: removedInbox, removed_sends: removedSends };
+    });
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    try { this.db.close(); } finally { this.owner.close(); }
+  }
+}

package/vendor/psst/reference/mcp-stdio.mjs

@@ -0,0 +1,153 @@
+import { StringDecoder } from 'node:string_decoder';
+import { canonical } from '../src/protocol.mjs';
+import { invokeTool } from './tools.mjs';
+import { PROVENANCE_WARNING } from './runtime.mjs';
+
+/** Minimal MCP 2025-06-18 stdio tools only; not HTTP MCP, channels, or a TUI wakeup API. */
+export const MCP_VERSION = '2025-06-18';
+const text = maxLength => ({ type: 'string', maxLength });
+const uuid = { type: 'string', format: 'uuid', maxLength: 36 };
+const object = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const model = object({ provider: { type: ['string', 'null'], maxLength: 128 }, id: { type: ['string', 'null'], maxLength: 256 }, source: { enum: ['unknown', 'observed', 'configured'] } }, ['provider', 'id', 'source']);
+const metadata = object({ name: text(128), model, project: { type: ['string', 'null'], maxLength: 256 } });
+
+export const TOOL_DEFINITIONS = Object.freeze([
+  { name: 'broker_list_clients', description: 'List authorized exact session addresses. Names and models are descriptive, not routing authority.', inputSchema: object({ connected: { type: 'boolean' }, client_type: { enum: ['pi', 'antigravity-cli', 'claude-code', 'opencode'] }, name: text(128), project: text(256), cursor: text(256), limit: { type: 'integer', minimum: 1, maximum: 100 } }) },
+  { name: 'broker_send', description: 'Send opaque untrusted AGENT text to one exact client_id. Acceptance means broker storage only; preserve send_key on uncertain results.', inputSchema: object({ recipient_id: uuid, text: text(65536), ttl_seconds: { type: 'integer', minimum: 60, maximum: 604800 }, correlation_id: text(128), reply_to_message_id: uuid, send_key: text(128) }, ['recipient_id', 'text']) },
+  { name: 'broker_update_metadata', description: 'CAS update of descriptive name/model/project only. Metadata does not grant access or change identity.', inputSchema: object({ metadata_patch: metadata, expected_metadata_revision: { type: 'integer', minimum: 1 } }, ['metadata_patch', 'expected_metadata_revision']) },
+  { name: 'broker_message_status', description: 'Read broker delivery state, never model progress or task completion.', inputSchema: object({ message_id: uuid }, ['message_id']) },
+  { name: 'broker_receive', description: 'Cooperatively peek at the oldest durable AGENT inbox item during this tool call. No unsolicited wakeup or native-consumption receipt; the item remains pending.', inputSchema: object() },
+]);
+
+function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function validArguments(value, schema) {
+  if (!isObject(value)) return false;
+  if (Object.keys(value).some(key => !Object.hasOwn(schema.properties, key))) return false;
+  if (schema.required.some(key => !Object.hasOwn(value, key))) return false;
+  for (const [key, item] of Object.entries(value)) {
+    const rule = schema.properties[key];
+    if (rule.enum && !rule.enum.includes(item)) return false;
+    if (rule.type === 'object' && !validArguments(item, rule)) return false;
+    if (rule.type === 'boolean' && typeof item !== 'boolean') return false;
+    if (rule.type === 'integer' && (!Number.isSafeInteger(item) || item < rule.minimum || item > (rule.maximum ?? Number.MAX_SAFE_INTEGER))) return false;
+    if ((rule.type === 'string' || Array.isArray(rule.type)) && !(item === null && Array.isArray(rule.type) && rule.type.includes('null'))) {
+      if (typeof item !== 'string' || !item.isWellFormed() || [...item].length > rule.maxLength) return false;
+    }
+    if (rule.format === 'uuid' && !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(item)) return false;
+  }
+  return true;
+}
+
+/**
+ * Call with tools from createTools and a host-bound cooperativeBoundary. A fresh
+ * process is a fresh harness incarnation unless its owner independently proves
+ * continuity. Stream write success is never used to consume a local inbox item.
+ * onClose must stop heartbeats/receive work for the departed host. It is invoked
+ * once and is not an agent tool. No credentials are accepted by this interface.
+ */
+export function serveStdio({ input = process.stdin, output = process.stdout, tools, onClose = async () => {},
+  onDiagnostic = () => {}, maxFrameBytes = 128 * 1024, maxResponseBytes = 512 * 1024, maxInflight = 8 } = {}) {
+  if (!tools || !input?.on || !output?.write || !Number.isSafeInteger(maxFrameBytes) || maxFrameBytes < 1024 || maxFrameBytes > 1024 * 1024
+    || !Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1024 || maxResponseBytes > 1024 * 1024
+    || !Number.isSafeInteger(maxInflight) || maxInflight < 1 || maxInflight > 32) throw new Error('invalid_stdio_configuration');
+  let phase = 'new', buffer = '', active = 0, pendingWrites = 0, closed = false;
+  const decoder = new StringDecoder('utf8'), requestIds = new Set();
+  let writes = Promise.resolve(), closeResolve;
+  const done = new Promise(resolve => { closeResolve = resolve; });
+  const diagnostic = code => { try { onDiagnostic({ code }); } catch { /* No raw data. */ } };
+  const close = async code => {
+    if (closed) return done;
+    closed = true; phase = 'closed'; buffer = ''; input.pause?.();
+    input.off('data', onData); diagnostic(code);
+    try { await onClose(); } catch { diagnostic('stdio_close_failed'); }
+    closeResolve(); return done;
+  };
+  function send(message) {
+    if (closed) return;
+    if (pendingWrites >= maxInflight) { void close('stdio_output_backpressure'); return; }
+    let line;
+    try { line = canonical(message) + '\n'; } catch { void close('stdio_invalid_response'); return; }
+    if (Buffer.byteLength(line) > maxResponseBytes) {
+      line = JSON.stringify({ jsonrpc: '2.0', id: message.id ?? null, error: { code: -32603, message: 'Response exceeds the configured byte limit; no native acceptance was recorded.' } }) + '\n';
+    }
+    pendingWrites++;
+    writes = writes.then(() => new Promise(resolve => {
+      if (closed) return resolve();
+      try { output.write(line, error => { if (error) void close('stdio_write_failed'); resolve(); }); }
+      catch { void close('stdio_write_failed'); resolve(); }
+    })).finally(() => { pendingWrites--; });
+  }
+  const error = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
+
+  async function dispatch(request) {
+    const id = request.id;
+    if (request.method === 'ping') { send({ jsonrpc: '2.0', id, result: {} }); return; }
+    if (request.method === 'initialize') {
+      const p = request.params;
+      if (phase !== 'new' || !isObject(p) || typeof p.protocolVersion !== 'string' || p.protocolVersion.length > 100 || !isObject(p.capabilities) || !isObject(p.clientInfo) || typeof p.clientInfo.name !== 'string' || typeof p.clientInfo.version !== 'string') {
+        error(id, -32602, 'Invalid or repeated initialization.'); return;
+      }
+      phase = 'initialized';
+      send({ jsonrpc: '2.0', id, result: { protocolVersion: MCP_VERSION, capabilities: { tools: {} },
+        serverInfo: { name: 'ai-agent-msg-broker', version: '0.1.0' },
+        instructions: `${PROVENANCE_WARNING} broker_receive is cooperative peek only. No permission relay, channels, sampling, or automatic input injection is provided.` } });
+      return;
+    }
+    if (phase !== 'ready') { error(id, -32000, 'Complete initialize and notifications/initialized first.'); return; }
+    if (request.method === 'tools/list') {
+      if (request.params !== undefined && (!isObject(request.params) || Object.keys(request.params).length)) { error(id, -32602, 'Tool pagination is not supported.'); return; }
+      send({ jsonrpc: '2.0', id, result: { tools: TOOL_DEFINITIONS.filter(definition => typeof tools[definition.name] === 'function') } }); return;
+    }
+    if (request.method === 'tools/call') {
+      const p = request.params, definition = TOOL_DEFINITIONS.find(item => item.name === p?.name);
+      if (!isObject(p) || Object.keys(p).some(key => !['name', 'arguments', '_meta'].includes(key)) || !definition || typeof tools[definition.name] !== 'function' || !validArguments(p.arguments ?? {}, definition.inputSchema)) {
+        error(id, -32602, 'Unknown tool or invalid bounded arguments.'); return;
+      }
+      const result = await invokeTool(tools, p.name, p.arguments ?? {});
+      send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: canonical(result) }], isError: Boolean(result?.error) } }); return;
+    }
+    error(id, -32601, 'Method not supported by this tools-only stdio server.');
+  }
+
+  function frame(line) {
+    if (closed) return;
+    let request;
+    try { request = JSON.parse(line); canonical(request); } catch { error(null, -32700, 'Invalid bounded JSON.'); return; }
+    const hasId = isObject(request) && Object.hasOwn(request, 'id');
+    if (!isObject(request) || request.jsonrpc !== '2.0' || typeof request.method !== 'string' || request.method.length > 128
+      || Object.keys(request).some(key => !['jsonrpc', 'id', 'method', 'params'].includes(key))
+      || (hasId && !(typeof request.id === 'string' && request.id.length <= 128 || Number.isSafeInteger(request.id)))) {
+      error(null, -32600, 'Invalid JSON-RPC request.'); return;
+    }
+    if (!hasId) {
+      if (request.method === 'notifications/initialized' && phase === 'initialized') phase = 'ready';
+      // Permission/channel notifications, cancellations and unknown notifications
+      // have no side effects. They cannot acknowledge or authorize an inbox item.
+      return;
+    }
+    const key = `${typeof request.id}:${request.id}`;
+    if (requestIds.has(key)) { error(request.id, -32600, 'Request ID is already in flight; reconcile before retrying.'); return; }
+    if (active >= maxInflight) { void close('stdio_capacity_exceeded'); return; }
+    requestIds.add(key); active++;
+    dispatch(request).catch(() => error(request.id, -32603, 'Tool result unavailable; reconcile the original operation.'))
+      .finally(() => { requestIds.delete(key); active--; });
+  }
+  function onData(chunk) {
+    if (closed) return;
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    // A single oversized read is refused before decoding/concatenating it.
+    if (bytes.length > maxFrameBytes) { void close('stdio_frame_too_large'); return; }
+    buffer += decoder.write(bytes);
+    while (!closed && buffer.includes('\n')) {
+      const index = buffer.indexOf('\n'), line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+      if (Buffer.byteLength(line) > maxFrameBytes) { void close('stdio_frame_too_large'); return; }
+      if (line.trim()) frame(line);
+    }
+    if (Buffer.byteLength(buffer) > maxFrameBytes) void close('stdio_frame_too_large');
+  }
+  input.on('data', onData);
+  input.on('end', () => { const trailing = decoder.end(); void close(buffer.trim() || trailing ? 'stdio_incomplete_frame' : 'stdio_closed'); });
+  input.on('error', () => { void close('stdio_read_failed'); });
+  output.on?.('error', () => { void close('stdio_write_failed'); });
+  return { close: () => close('stdio_closed'), done, flush: () => writes };
+}