@matuto-ai/opencode-broker-connector 0.3.0 → 0.4.0

package/vendor/broker/reference/inbox.mjs

@@ -2,7 +2,7 @@ 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 { canonical, digest, validateEnvelope, validateUuid, validateSend, validateIdempotencyKey, validateResend, TYPES } from '../src/protocol.mjs';
 import { LocalError } from './errors.mjs';
 
 export function newSessionIdentity(clientType) {
@@ -68,6 +68,12 @@ export class Inbox {
           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;`);
+      if(!this.db.prepare('PRAGMA table_info(outgoing)').all().some(c=>c.name==='kind'))this.db.exec("ALTER TABLE outgoing ADD COLUMN kind TEXT NOT NULL DEFAULT 'send'");
+      for(const [name,type] of [['failure','TEXT'],['uncertain','INTEGER NOT NULL DEFAULT 0'],['operation_id','TEXT']]){
+        if(!this.db.prepare('PRAGMA table_info(outgoing)').all().some(c=>c.name===name))this.db.exec(`ALTER TABLE outgoing ADD COLUMN ${name} ${type}`);
+      }
+      this.db.exec('CREATE UNIQUE INDEX IF NOT EXISTS outgoing_operation ON outgoing(operation_id) WHERE operation_id IS NOT NULL');
+      this.db.exec('CREATE INDEX IF NOT EXISTS outgoing_recovery ON outgoing(retry_until,created_at,key) WHERE result IS NULL AND failure IS NULL');
       const stored = this.getState('identity');
       if (stored && canonical(stored) !== canonical(this.identity)) throw new LocalError('session_mismatch');
       if (!stored) this.setState('identity', this.identity);
@@ -234,33 +240,62 @@ export class Inbox {
     });
   }
 
-  prepareSend(rawRequest, { key = randomUUID(), retryWindowSeconds = 86400 } = {}) {
-    key = validateIdempotencyKey(key);
-    const request = validateSend(rawRequest);
+  prepareSend(rawRequest, options = {}) {
+    return this.prepareOperation('send',validateSend(rawRequest),options);
+  }
+
+  prepareResend(messageId, input = {}, options = {}) {
+    const validated=validateResend(input);
+    return this.prepareOperation('resend',{message_id:validateUuid(messageId),...(input.ttl_seconds===undefined?{}:validated)},options);
+  }
+
+  prepareOperation(kind, request, { key, operationId, issuedAt=this.now(), retryUntil, retryWindowSeconds = 86400 } = {}) {
+    if(operationId!==undefined&&(typeof operationId!=='string'||!/^[a-f0-9]{64}$/.test(operationId)))throw new LocalError('invalid_configuration');
+    const mapped=operationId?this.outgoingForOperation(operationId):null;
+    key = validateIdempotencyKey(key??mapped?.key??`op_${issuedAt}_${randomUUID().replaceAll('-','')}`);
     const encoded = canonical(request);
     const hash = digest(request);
     const existing = this.outgoing(key);
     if (existing) {
-      if (existing.digest !== hash) throw new LocalError('send_conflict');
+      if (existing.digest !== hash || existing.kind !== kind) throw new LocalError('send_conflict');
       return key;
     }
+    const started=/^op_([0-9]{13})_/.exec(key);
+    if(started&&issuedAt-Number(started[1])>=retryWindowSeconds*1000)throw new LocalError('retry_window_elapsed',{effect:'unknown'});
+    if(retryUntil!==undefined&&(!Number.isSafeInteger(retryUntil)||retryUntil<=this.now()))throw new LocalError('retry_window_elapsed',{effect:'unknown'});
     if (!Number.isSafeInteger(retryWindowSeconds) || retryWindowSeconds < 1) throw new LocalError('invalid_configuration');
     this.transaction(() => {
+      this.db.prepare('DELETE FROM outgoing WHERE key IN (SELECT key FROM outgoing WHERE (result IS NOT NULL OR failure IS NOT NULL) AND retry_until<? LIMIT 100)').run(this.now());
       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);
+      this.db.prepare('INSERT INTO outgoing(key,digest,request,created_at,retry_until,kind,operation_id) VALUES(?,?,?,?,?,?,?)').run(key, hash, encoded, this.now(), Math.min(retryUntil??Infinity,this.now()+retryWindowSeconds*1000),kind,operationId??null);
     }, { growth: Buffer.byteLength(encoded) * 3 + 8192 });
     return key;
   }
 
+  outgoingForOperation(operationId) {
+    const row=this.db.prepare('SELECT key FROM outgoing WHERE operation_id=?').get(operationId);
+    return row?this.outgoing(row.key):null;
+  }
+
   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;
+    return row ? { ...row, request: JSON.parse(row.request), result: row.result ? JSON.parse(row.result) : null, failure: row.failure ? JSON.parse(row.failure) : 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 }));
+    return this.db.prepare('SELECT key,created_at,retry_until FROM outgoing WHERE result IS NULL AND failure IS NULL ORDER BY created_at LIMIT 100').all().map(row => ({ ...row }));
+  }
+
+  outgoingRecovery(limit = 10, now = this.now()) {
+    this.assertUsable();
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(now)) throw new LocalError('invalid_configuration');
+    // Filter before LIMIT: retained, expired unknowns must never starve live retries.
+    // Earliest deadline first uses the partial index without sorting/scanning old rows.
+    const operations = this.db.prepare('SELECT key,created_at,retry_until FROM outgoing WHERE result IS NULL AND failure IS NULL AND retry_until>? ORDER BY retry_until,created_at,key LIMIT ?').all(now, limit).map(row => ({ ...row }));
+    const expiredCount = this.db.prepare('SELECT count(*) AS n FROM outgoing WHERE result IS NULL AND failure IS NULL AND retry_until<=?').get(now).n;
+    return { operations, expiredCount };
   }
 
   recordSendResult(key, result) {
@@ -268,15 +303,25 @@ export class Inbox {
     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);
+      this.db.prepare('UPDATE outgoing SET result=?,failure=NULL,uncertain=0 WHERE key=?').run(encoded, key);
     }, { growth: Buffer.byteLength(encoded) * 2 + 8192 });
   }
 
+  markOutgoingAttempt(key) {
+    this.transaction(()=>this.db.prepare('UPDATE outgoing SET uncertain=1 WHERE key=?').run(key));
+  }
+
+  recordSendFailure(key, failure) {
+    const encoded=canonical(failure);
+    if(Buffer.byteLength(encoded)>16384)throw new LocalError('invalid_response',{effect:'unknown'});
+    this.transaction(()=>this.db.prepare('UPDATE outgoing SET failure=?,uncertain=0 WHERE key=? AND result IS NULL').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;
+      const removedSends = this.db.prepare('DELETE FROM outgoing WHERE key IN (SELECT key FROM outgoing WHERE (result IS NOT NULL OR failure IS NOT NULL) AND retry_until<? ORDER BY retry_until LIMIT ?)').run(this.now(), limit).changes;
       return { removed_inbox: removedInbox, removed_sends: removedSends };
     });
   }

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

@@ -13,8 +13,12 @@ const metadata = object({ name: text(128), model, project: { type: ['string', 'n
 
 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_send', description: 'Send opaque untrusted AGENT text to one exact client_id. Acceptance means broker storage only; internal operation identity handles technical retries.', 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 }, ['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_sent_history', description: 'Read only this exact session’s outgoing metadata, newest first. Default 10, maximum 100, 32768-byte cap. No content. Preserve filters on continuation; restart on history_changed.', inputSchema: object({ recipient_id: uuid, status: { enum: ['queued','claimed','delivered','expired','failed','cancelled'] }, accepted_after: text(24), accepted_before: text(24), cursor: text(1024), limit: { type: 'integer', minimum: 1, maximum: 100 } }) },
+  { name: 'broker_message_content', description: 'Explicitly retrieve the original content and current transport receipt of one owned outgoing message.', inputSchema: object({ message_id: uuid }, ['message_id']) },
+  { name: 'broker_resend', description: 'Explicit new delivery of an owned retained message, with a new message ID. May duplicate a prior delivery; never an automatic technical retry.', inputSchema: object({ message_id: uuid, ttl_seconds: { type: 'integer', minimum: 60, maximum: 604800 } }, ['message_id']) },
+  { name: 'broker_cancel', description: 'Stop further pending delivery of one owned message. Cannot undo inbox content; inspect uncertainty and cancel_result.', inputSchema: object({ message_id: uuid }, ['message_id']) },
   { 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() },
 ]);

package/vendor/broker/reference/tools.mjs

@@ -1,15 +1,25 @@
+import { digest } from '../src/protocol.mjs';
 import { LocalError, safeError } from './errors.mjs';
 import { provenance } from './runtime.mjs';
 
 /** Native host tool facade, not an MCP transport or a generic TUI injection API. */
 export function createTools({ client, inbox = client?.inbox, observeMetadata = null, cooperativeBoundary = null }) {
   if (!client || !inbox) throw new LocalError('invalid_configuration');
+  const internalOperation=(kind,context)=>{
+    if(context?.operationId!==undefined){
+      if(typeof context.operationId!=='string'||!context.operationId||context.operationId.length>1024)throw new LocalError('invalid_configuration');
+      const operationId=digest({kind,operation_id:context.operationId}),existing=inbox.outgoingForOperation(operationId);
+      return {operationId,...(existing?{key:existing.key}:{}),...(context.operationStartedAt===undefined?{}:{operationStartedAt:context.operationStartedAt})};
+    }
+    return {};
+  };
+  const publicResult=value=>{const {send_key,...result}=value;return result;};
   return {
-    async broker_list_clients(arguments_ = {}) { return client.listClients(arguments_); },
-    async broker_send(arguments_) {
+    async broker_list_clients(arguments_ = {}, context = {}) { return client.listClients(arguments_,{signal:context.signal}); },
+    async broker_send(arguments_, context = {}) {
       if (!arguments_ || typeof arguments_ !== 'object' || Array.isArray(arguments_)
-        || Object.keys(arguments_).some(key => !['recipient_id', 'text', 'ttl_seconds', 'correlation_id', 'reply_to_message_id', 'send_key'].includes(key))) throw new LocalError('invalid_configuration');
-      let key = arguments_.send_key;
+        || Object.keys(arguments_).some(key => !['recipient_id', 'text', 'ttl_seconds', 'correlation_id', 'reply_to_message_id'].includes(key))) throw new LocalError('invalid_configuration');
+      const operation=internalOperation('send',context);let key=operation.key;
       try {
         const request = { recipient_id: arguments_.recipient_id, content: { type: 'text/plain', text: arguments_.text } };
         for (const field of ['ttl_seconds', 'correlation_id', 'reply_to_message_id']) if (Object.hasOwn(arguments_, field)) request[field] = arguments_[field];
@@ -21,21 +31,35 @@ export function createTools({ client, inbox = client?.inbox, observeMetadata = n
         } else if (!original && observeMetadata) {
           const observed = await observeMetadata();
           if (observed) {
-            await client.refreshOwnedMetadata();
+            await client.refreshOwnedMetadata({signal:context.signal});
             request.metadata_patch = observed; request.expected_metadata_revision = client.attachment.metadata_revision;
           }
         }
-        key = client.prepareSend(request, key ? { key } : {});
-        return await client.sendPrepared(key);
-      } catch (error) { return { ...safeError(error), send_key: key ?? null }; }
+        key = client.prepareSend(request,operation);
+        return publicResult(await client.sendPrepared(key,{signal:context.signal}));
+      } catch (error) { return safeError(error); }
     },
-    async broker_update_metadata(arguments_) {
+    async broker_update_metadata(arguments_, context = {}) {
       if (!arguments_ || Object.keys(arguments_).some(key => !['metadata_patch', 'expected_metadata_revision'].includes(key))) throw new LocalError('invalid_configuration');
-      return client.updateMetadata(arguments_.metadata_patch, { expectedRevision: arguments_.expected_metadata_revision });
+      return client.updateMetadata(arguments_.metadata_patch, { expectedRevision: arguments_.expected_metadata_revision, signal:context.signal });
+    },
+    async broker_sent_history(arguments_ = {}, context = {}) { return client.sentHistory(arguments_,{signal:context.signal}); },
+    async broker_resend(arguments_, context = {}) {
+      if(!arguments_||Object.keys(arguments_).some(key=>!['message_id','ttl_seconds'].includes(key)))throw new LocalError('invalid_configuration');
+      const operation=internalOperation('resend',context),{message_id,...input}=arguments_;
+      return publicResult(await client.resendPrepared(client.prepareResend(message_id,input,operation),{signal:context.signal}));
+    },
+    async broker_cancel(arguments_, context = {}) {
+      if(!arguments_||Object.keys(arguments_).join(',')!=='message_id')throw new LocalError('invalid_configuration');
+      return client.cancelMessage(arguments_.message_id,{signal:context.signal});
+    },
+    async broker_message_content(arguments_, context = {}) {
+      if(!arguments_||Object.keys(arguments_).join(',')!=='message_id') throw new LocalError('invalid_configuration');
+      return client.messageContent(arguments_.message_id,{signal:context.signal});
     },
-    async broker_message_status(arguments_) {
+    async broker_message_status(arguments_, context = {}) {
       if (!arguments_ || Object.keys(arguments_).join(',') !== 'message_id') throw new LocalError('invalid_configuration');
-      return client.messageStatus(arguments_.message_id);
+      return client.messageStatus(arguments_.message_id,{signal:context.signal});
     },
     async broker_receive(arguments_ = {}) {
       if (Object.keys(arguments_).length || typeof cooperativeBoundary !== 'function') throw new LocalError('unsafe_boundary');
@@ -52,8 +76,8 @@ export function createTools({ client, inbox = client?.inbox, observeMetadata = n
   };
 }
 
-export async function invokeTool(tools, name, arguments_) {
+export async function invokeTool(tools, name, arguments_, context = {}) {
   if (!Object.hasOwn(tools, name) || typeof tools[name] !== 'function') return new LocalError('unknown_tool').toJSON();
-  try { return await tools[name](arguments_); }
+  try { return await tools[name](arguments_,context); }
   catch (error) { return safeError(error); }
 }

package/vendor/broker/src/protocol.mjs

@@ -17,6 +17,9 @@ const ERROR_TEXT = Object.freeze({
   forbidden: ['This operation is not authorized.', 'Check the enrolled adapter permissions.'],
   recipient_not_found: ['The recipient is not available.', 'Select an exact authorized client ID from discovery.'],
   message_not_found: ['The message is not available.', 'Use a message ID owned by this principal.'],
+  retry_window_elapsed: ['The operation recovery record has expired.', 'Reconcile the existing receipt; only an explicit new send or resend may create another delivery.'],
+  history_changed: ['History changed while paging.', 'Restart the listing without a cursor; no continuation was silently skipped.'],
+  content_unavailable: ['The original content is no longer retained.', 'Use the receipt; unavailable content cannot be reconstructed.'],
   identity_conflict: ['The session identity conflicts with an existing registration.', 'Do not adopt another session; verify the local session identity.'],
   stale_lease_epoch: ['Reconnect this session before retrying.', 'Read owned registration state and reconnect; do not blindly replay a mutation.'],
   idempotency_conflict: ['This key was already used for a different request.', 'Reconcile the original request; do not change an uncertain request.'],
@@ -297,3 +300,19 @@ export function canonical(value) {
 export function digest(value) {
   return createHash('sha256').update(canonical(value), 'utf8').digest('hex');
 }
+
+export function validateResend(value, { limits = {} } = {}) {
+  object(value, ['ttl_seconds'], [], 'body');
+  const merged = { ...DEFAULTS, ...limits };
+  return { ttl_seconds: value.ttl_seconds === undefined ? merged.default_ttl_seconds : integer(value.ttl_seconds, Math.max(60, merged.min_ttl_seconds), Math.min(604800, merged.max_ttl_seconds), 'body.ttl_seconds') };
+}
+
+/** New internal keys carry a timestamp; legacy keys retain their bounded v1 guarantee. */
+export function validateOperationTime(key, now, retryWindowSeconds) {
+  if(!key.startsWith('op_'))return;
+  const match=/^op_([0-9]{13})_([A-Za-z0-9_-]{16,96})$/.exec(key);
+  if(!match)throw new ApiError(400,'invalid_request','headers.Idempotency-Key');
+  const started=Number(match[1]);
+  if(started>now+300000)throw new ApiError(400,'invalid_request','headers.Idempotency-Key');
+  if(now-started>=retryWindowSeconds*1000)throw new ApiError(410,'retry_window_elapsed','headers.Idempotency-Key');
+}