@matuto-ai/opencode-psst-connector 0.0.0-stage → 0.7.0

package/vendor/broker/reference/client.mjs

@@ -0,0 +1,439 @@
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { mkdirSync, readFileSync, openSync, fstatSync, closeSync, constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ApiError, canonical, validateMetadata, validateRegistration, validateMetadataPatch,
+  validateClaim, validateCompletion, validateRenew, validateUuid } from '../src/protocol.mjs';
+import { LocalError } from './errors.mjs';
+import { Inbox, newSessionIdentity } from './inbox.mjs';
+
+const ALLOWED_ERROR_CODES = new Set(['invalid_request', 'unauthenticated', 'forbidden', 'recipient_not_found',
+  'message_not_found', 'history_changed', 'content_unavailable', 'retry_window_elapsed', 'identity_conflict', 'stale_lease_epoch', 'idempotency_conflict', 'metadata_conflict',
+  'claim_conflict', 'registration_upgrade_required', 'session_closed', 'message_expired', 'payload_too_large',
+  'incompatible_receiver_transport', 'receiving_disabled', 'rate_limited', 'mailbox_full',
+  'storage_unavailable', 'not_ready']);
+
+export class BrokerError extends LocalError {
+  constructor(status, value, retryAfter = 0) {
+    super('invalid_response', { effect: 'unknown' });
+    this.name = 'BrokerError';
+    this.status = status;
+    this.retryAfter = retryAfter;
+    const raw = value?.error;
+    const code = ALLOWED_ERROR_CODES.has(raw?.code) ? raw.code : 'invalid_request';
+    // Never reproduce a remote free-text message or details in local tools/logs.
+    this.api = new ApiError(status, code, null, {
+      effect: ['not_applied', 'unknown'].includes(raw?.effect) ? raw.effect : 'unknown',
+      retryable: raw?.retryable === true && [429, 503].includes(status),
+    });
+    this.code = this.api.code;
+    this.message = this.api.message;
+    this.effect = this.api.effect;
+    this.retryable = this.api.retryable;
+  }
+  toJSON() { return this.api.toJSON(null); }
+}
+
+function readSecret(path) {
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.size > 8192
+      || (process.getuid && stat.uid !== process.getuid())) throw new Error('invalid');
+    const token = readFileSync(fd, 'utf8').trim();
+    if (!/^[A-Za-z0-9_-]{43,256}$/.test(token)) throw new Error('invalid');
+    return token;
+  } catch { throw new LocalError('invalid_configuration', { field: 'tokenFile' }); }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+function positiveSeconds(value, fallback) {
+  return Number.isSafeInteger(value) && value > 0 && value <= 365 * 86400 ? value : fallback;
+}
+
+/** HTTPS-only by default. No redirects; no credential-bearing URLs or command-line arguments. */
+export class BrokerClient {
+  constructor({ url, tokenFile, tokenEnvironment, caFile, insecureDevelopment = false, inbox,
+    now = Date.now, random = Math.random, sleep = delay, maxAttempts = 4,
+    maxResponseBytes = 256 * 1024, requestTimeoutMs = 40000, registrationVersion = 1 }) {
+    try { this.base = new URL(url); } catch { throw new LocalError('invalid_configuration', { field: 'url' }); }
+    const host = this.base.hostname.replace(/^\[|\]$/g, '');
+    if (this.base.username || this.base.password || this.base.search || this.base.hash || this.base.pathname !== '/'
+      || !['https:', 'http:'].includes(this.base.protocol)
+      || (this.base.protocol === 'http:' && (!insecureDevelopment || !['127.0.0.1', '::1'].includes(host)))) {
+      throw new LocalError('invalid_configuration', { field: 'url' });
+    }
+    if (!inbox || (!tokenFile && !tokenEnvironment) || (tokenFile && tokenEnvironment)
+      || !Number.isSafeInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 10
+      || !Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1024 || maxResponseBytes > 1048576
+      || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 120000) throw new LocalError('invalid_configuration');
+    if (![1,2].includes(registrationVersion)) throw new LocalError('invalid_configuration');
+    this.registrationVersion = registrationVersion;
+    this.expiredIdentityConfirmed = false;
+    this.inbox = inbox;
+    this.now = now;
+    this.random = random;
+    this.sleep = sleep;
+    this.maxAttempts = maxAttempts;
+    this.maxResponseBytes = maxResponseBytes;
+    this.requestTimeoutMs = requestTimeoutMs;
+    this.tokenFile = tokenFile;
+    this.tokenEnvironment = tokenEnvironment;
+    try { this.ca = caFile ? readFileSync(caFile) : undefined; }
+    catch { throw new LocalError('invalid_configuration', { field: 'caFile' }); }
+    this.clockOffset = 0;
+    this.connectPromise = null;
+  }
+
+  get identity() { return this.inbox.identity; }
+  get attachment() { return this.inbox.getState('attachment') ?? {}; }
+  get policy() { return this.attachment.policy ?? {}; }
+  serverNow() { return this.now() + this.clockOffset; }
+
+  credential() {
+    if (this.tokenFile) return readSecret(this.tokenFile);
+    const token = process.env[this.tokenEnvironment];
+    if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{43,256}$/.test(token)) throw new LocalError('invalid_configuration', { field: 'tokenEnvironment' });
+    return token;
+  }
+
+  async request(method, path, { body, key, session = true, signal, idempotent = false, deadline = Infinity, onError = () => {} } = {}) {
+    if (!/^\/v1\/[A-Za-z0-9_/?=&.%+~-]+$/.test(path)) throw new LocalError('invalid_configuration');
+    for (let attempt = 0; ; attempt++) {
+      if (this.now() >= deadline) throw new LocalError('retry_window_elapsed', { effect: 'unknown' });
+      try { return await this.requestOnce(method, path, { body, key, session, signal, timeoutMs: Math.min(this.requestTimeoutMs, deadline - this.now()) }); }
+      catch (error) {
+        onError(error);
+        if (signal?.aborted) throw new LocalError('request_aborted', { effect: 'unknown' });
+        const retryable = error instanceof BrokerError ? error.retryable
+          : error instanceof LocalError && error.code === 'request_failed';
+        if (!idempotent || !retryable || attempt + 1 >= this.maxAttempts) throw error;
+        const milliseconds = Math.max(error.retryAfter * 1000 || 0, Math.min(10000, 250 * 2 ** attempt) * (0.8 + this.random() * 0.4));
+        if (this.now() + milliseconds >= deadline) throw new LocalError('retry_window_elapsed', { effect: 'unknown' });
+        try { await this.sleep(milliseconds, undefined, { signal }); }
+        catch { throw new LocalError('request_aborted', { effect: 'unknown' }); }
+      }
+    }
+  }
+
+  requestOnce(method, path, { body, key, session, signal, timeoutMs }) {
+    const serialized = body === undefined ? null : canonical(body);
+    if (serialized && Buffer.byteLength(serialized) > 98304) throw new LocalError('invalid_configuration', { field: 'body' });
+    const headers = { Accept: 'application/json', Authorization: `Bearer ${this.credential()}` };
+    if (session) {
+      if (!Number.isSafeInteger(this.attachment.lease_epoch) || this.attachment.lease_epoch < 1) throw new LocalError('session_mismatch');
+      headers['X-Client-ID'] = this.identity.client_id;
+      headers['X-Lease-Epoch'] = String(this.attachment.lease_epoch);
+    }
+    if (key) headers['Idempotency-Key'] = key;
+    if (serialized !== null) { headers['Content-Type'] = 'application/json'; headers['Content-Length'] = Buffer.byteLength(serialized); }
+    const target = new URL(path, this.base);
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let absoluteTimer;
+      const finish = (error, value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(absoluteTimer);
+        if (error) reject(error); else resolve(value);
+      };
+      const transport = target.protocol === 'https:' ? httpsRequest : httpRequest;
+      const request = transport(target, { method, headers, signal, ca: this.ca,
+        rejectUnauthorized: true, timeout: timeoutMs, maxHeaderSize: 16384 }, response => {
+        const chunks = [];
+        let bytes = 0;
+        response.on('data', chunk => {
+          bytes += chunk.length;
+          if (bytes > this.maxResponseBytes) { finish(new LocalError('invalid_response', { effect: 'unknown' })); response.destroy(); }
+          else chunks.push(chunk);
+        });
+        response.on('error', () => finish(new LocalError('request_failed', { effect: 'unknown', retryable: true })));
+        response.on('end', () => {
+          try {
+            const status = response.statusCode;
+            if (status === 204) { finish(null, null); return; }
+            if (!String(response.headers['content-type'] ?? '').toLowerCase().startsWith('application/json')) throw new LocalError('invalid_response', { effect: 'unknown' });
+            const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+            if (status < 200 || status >= 300) {
+              const retryAfter = /^\d+$/.test(String(response.headers['retry-after'] ?? '')) ? Math.min(3600, Number(response.headers['retry-after'])) : 0;
+              finish(new BrokerError(status, value, retryAfter)); return;
+            }
+            if(['true','false'].includes(response.headers['idempotency-replayed']))value.acceptance_replayed=response.headers['idempotency-replayed']==='true';
+            const timestamp = value?.server_time;
+            // Registration/send/completion retries may return their original
+            // stored result. Historical server_time is not a current clock sample.
+            if ((method === 'GET' || path.endsWith('/heartbeat') || method === 'PATCH')
+              && typeof timestamp === 'string' && Number.isFinite(Date.parse(timestamp))) this.clockOffset = Date.parse(timestamp) - this.now();
+            finish(null, value);
+          } catch (error) { finish(error instanceof LocalError ? error : new LocalError('invalid_response', { effect: 'unknown' })); }
+        });
+      });
+      request.on('timeout', () => request.destroy());
+      request.on('error', () => finish(new LocalError(signal?.aborted ? 'request_aborted' : 'request_failed', { effect: 'unknown', retryable: !signal?.aborted })));
+      absoluteTimer = setTimeout(() => request.destroy(), timeoutMs);
+      request.end(serialized);
+    });
+  }
+
+  capabilities(receiveEnabled = true) {
+    return { protocol_version: '1', adapter_version: '0.1.0', client_type: this.identity.client_type,
+      receive_enabled: receiveEnabled, durable_inbox: true };
+  }
+
+  applyRegistration(result, pending) {
+    if (!result || result.client_id !== this.identity.client_id || !Number.isSafeInteger(result.lease_epoch)
+      || ((pending.body.registration_version ?? 1) === 2 ? result.lease_epoch <= pending.body.previous_epoch : result.lease_epoch !== pending.body.previous_epoch + 1) || !Number.isSafeInteger(result.metadata_revision)
+      || result.metadata_revision < 1 || !result.policy) throw new LocalError('invalid_response', { effect: 'unknown' });
+    this.inbox.setState('attachment', { ...this.attachment, ...result, connection_id: pending.body.connection_id });
+    this.inbox.setState('metadata', pending.body.metadata);
+    this.inbox.setState('registration_pending', null);
+    this.inbox.setState('claim_pending', null);
+    return result;
+  }
+
+  async register(metadata, { receiveEnabled = true, signal } = {}) {
+    let pending = this.inbox.getState('registration_pending');
+    if (!pending) {
+      const body = validateRegistration({ protocol_version: '1', ...this.identity, connection_id: randomUUID(),
+        ...(this.registrationVersion === 2 ? { registration_version: 2, requested_at: this.serverNow() } : {}),
+        previous_epoch: this.attachment.lease_epoch ?? 0, metadata: validateMetadata(metadata), capabilities: this.capabilities(receiveEnabled) });
+      pending = { body, retry_until: this.now() + positiveSeconds(this.policy.registration_retry_seconds, 86400) * 1000 };
+      this.inbox.setState('registration_pending', pending);
+    }
+    const result = await this.request('POST', '/v1/sessions', { body: pending.body, session: false,
+      idempotent: true, deadline: pending.retry_until, signal });
+    const state = await this.request('GET', `/v1/sessions/${this.identity.client_id}`, { session: false, idempotent: true, signal });
+    if (state?.client_id !== this.identity.client_id || state.session_instance_id !== this.identity.session_instance_id
+      || state.client_type !== this.identity.client_type || state.connection_id !== pending.body.connection_id
+      || state.lease_epoch !== result?.lease_epoch) throw new LocalError('session_mismatch', { effect: 'unknown' });
+    const confirmed = this.applyRegistration({ ...result, server_time: state.server_time, lease_expires_at: state.lease_expires_at }, pending);
+    if (state.closed === true) throw new BrokerError(410, { error: { code: 'session_closed', effect: 'unknown' } });
+    if (state.connected !== true || Date.parse(state.lease_expires_at) <= this.serverNow()) {
+      throw new BrokerError(409, { error: { code: 'stale_lease_epoch', effect: 'unknown' } });
+    }
+    return confirmed;
+  }
+
+  async reconnect({ verifySession, signal, metadata, receiveEnabled } = {}) {
+    if (this.connectPromise) return this.connectPromise;
+    this.connectPromise = this.reconnectOnce({ verifySession, signal, metadata, receiveEnabled });
+    try { return await this.connectPromise; } finally { this.connectPromise = null; }
+  }
+
+  async reconnectOnce({ verifySession, signal, metadata, receiveEnabled }) {
+    if (typeof verifySession !== 'function' || await verifySession(this.identity) !== true) throw new LocalError('session_mismatch');
+    const local = this.attachment;
+    const pending = this.inbox.getState('registration_pending');
+    let state;
+    try { state = await this.request('GET', `/v1/sessions/${this.identity.client_id}`, { session: false, idempotent: true, signal }); }
+    catch(error) {
+      if(this.registrationVersion === 2 && error instanceof BrokerError && error.status === 404 && error.code === 'recipient_not_found') {
+        this.expiredIdentityConfirmed = true;
+        throw new LocalError('session_expired');
+      }
+      throw error;
+    }
+    if (state.client_id !== this.identity.client_id || state.session_instance_id !== this.identity.session_instance_id
+      || state.client_type !== this.identity.client_type || !Number.isSafeInteger(state.lease_epoch)
+      || ![local.connection_id, pending?.body.connection_id].filter(Boolean).includes(state.connection_id)) throw new LocalError('session_mismatch');
+    if (state.closed === true || state.closed_at != null) throw new BrokerError(410, { error: { code: 'session_closed', effect: 'not_applied' } });
+    // The owned-state read is a reconciliation, not permission to steal a different attachment.
+    this.inbox.setState('attachment', { ...local, lease_epoch: state.lease_epoch, connection_id: state.connection_id,
+      metadata_revision: state.metadata_revision, policy: state.policy ?? local.policy });
+    this.inbox.setState('registration_pending', null);
+    const refreshedMetadata = metadata ?? pending?.body.metadata ?? state.metadata ?? this.inbox.getState('metadata');
+    return this.register(refreshedMetadata, { receiveEnabled: receiveEnabled ?? pending?.body.capabilities.receive_enabled ?? state.capabilities?.receive_enabled ?? false, signal });
+  }
+
+  /** Explicit replacement only; never edits or transfers the old journal. */
+  async createReplacementInbox({ directory, verifySession, signal } = {}) {
+    if(this.registrationVersion !== 2 || !this.expiredIdentityConfirmed || typeof verifySession !== 'function' || await verifySession(this.identity) !== true) throw new LocalError('session_mismatch');
+    try {
+      await this.request('GET', `/v1/sessions/${this.identity.client_id}`, { session:false, idempotent:true, signal });
+      throw new LocalError('session_mismatch');
+    } catch(error) {
+      if(!(error instanceof BrokerError && error.status === 404 && error.code === 'recipient_not_found')) throw error;
+    }
+    // Nonrecursive mkdir refuses every preexisting directory, including another
+    // journal. Parent safety/ownership is still checked by Inbox itself.
+    try { mkdirSync(directory, { mode:0o700 }); }
+    catch { throw new LocalError('invalid_configuration'); }
+    const inbox = new Inbox({directory,identity:newSessionIdentity(this.identity.client_type),now:this.now});
+    this.expiredIdentityConfirmed = false;
+    return inbox;
+  }
+
+  async heartbeat({ signal } = {}) {
+    return this.request('POST', `/v1/sessions/${this.identity.client_id}/heartbeat`, { body: {}, idempotent: true, signal });
+  }
+
+  async closeSession({ signal } = {}) {
+    return this.request('POST', `/v1/sessions/${this.identity.client_id}/close`, { body: {}, idempotent: true, signal });
+  }
+
+  async disconnectSession({ signal } = {}) {
+    return this.request('POST', `/v1/sessions/${this.identity.client_id}/disconnect`, { body: {}, idempotent: true, signal });
+  }
+
+  async presenceEvents(filters = {}, { signal } = {}) {
+    if (Object.keys(filters).some(key => !['limit', 'cursor'].includes(key))) throw new LocalError('invalid_configuration');
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(filters)) query.set(key, String(value));
+    return this.request('GET', `/v1/presence-events${query.size ? `?${query}` : ''}`, { idempotent: true, signal });
+  }
+
+  async acknowledgePresenceEvent(eventId, { signal } = {}) {
+    return this.request('POST', `/v1/presence-events/${validateUuid(eventId)}/ack`, { body: {}, idempotent: true, signal });
+  }
+
+  async listClients(filters = {}, { signal } = {}) {
+    const allowed = ['connected', 'client_type', 'name', 'project', 'limit', 'cursor'];
+    if (Object.keys(filters).some(key => !allowed.includes(key))) throw new LocalError('invalid_configuration');
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(filters)) query.set(key, String(value));
+    return this.request('GET', `/v1/clients${query.size ? `?${query}` : ''}`, { idempotent: true, signal });
+  }
+
+  async updateMetadata(patch, { expectedRevision = this.attachment.metadata_revision, signal } = {}) {
+    const body = validateMetadataPatch({ metadata_patch: patch, expected_metadata_revision: expectedRevision });
+    // CAS is not blindly retried after response loss: read owned state to reconcile first.
+    const result = await this.request('PATCH', `/v1/sessions/${this.identity.client_id}/metadata`, { body, signal });
+    if (!Number.isSafeInteger(result?.metadata_revision)) throw new LocalError('invalid_response', { effect: 'unknown' });
+    this.inbox.setState('attachment', { ...this.attachment, metadata_revision: result.metadata_revision });
+    this.inbox.setState('metadata', { ...this.inbox.getState('metadata'), ...patch });
+    return result;
+  }
+
+  async refreshOwnedMetadata({ signal } = {}) {
+    const state = await this.request('GET', `/v1/sessions/${this.identity.client_id}`, { session: false, idempotent: true, signal });
+    if (state.client_id !== this.identity.client_id || state.session_instance_id !== this.identity.session_instance_id
+      || state.connection_id !== this.attachment.connection_id || state.lease_epoch !== this.attachment.lease_epoch
+      || !Number.isSafeInteger(state.metadata_revision)) throw new LocalError('session_mismatch');
+    const metadata = validateMetadata(state.metadata);
+    this.inbox.setState('attachment', { ...this.attachment, metadata_revision: state.metadata_revision });
+    this.inbox.setState('metadata', metadata);
+    return metadata;
+  }
+
+  operationOptions(options = {}) {
+    const {operationStartedAt,...rest}=options,seconds=positiveSeconds(this.policy.send_retry_seconds,86400);
+    if(operationStartedAt!==undefined&&(!Number.isSafeInteger(operationStartedAt)||operationStartedAt>this.now()+300000||this.now()-operationStartedAt>=seconds*1000))throw new LocalError('retry_window_elapsed',{effect:'unknown'});
+    return {retryWindowSeconds:seconds,issuedAt:Math.trunc((operationStartedAt??this.now())+this.clockOffset),...(operationStartedAt===undefined?{}:{retryUntil:operationStartedAt+seconds*1000}),...rest};
+  }
+
+  prepareSend(request, options = {}) {
+    return this.inbox.prepareSend(request,this.operationOptions(options));
+  }
+
+  async sendPrepared(key, options = {}) { return this.outgoingRequest(key,'send',options); }
+
+  prepareResend(messageId, input = {}, options = {}) {
+    return this.inbox.prepareResend(messageId,input,this.operationOptions(options));
+  }
+
+  async resendPrepared(key, options = {}) { return this.outgoingRequest(key,'resend',options); }
+
+  async outgoingRequest(key, kind, options) {
+    // Shared by clients using this exact journal: concurrent invocations cannot
+    // race a definite rejection against another still-running network attempt.
+    const inflight=this.inbox.outgoingRequests??=new Map();
+    if(inflight.has(key))return inflight.get(key);
+    const work=this.transmitOutgoing(key,kind,options);inflight.set(key,work);
+    try{return await work;}finally{inflight.delete(key);}
+  }
+
+  async transmitOutgoing(key, kind, { signal } = {}) {
+    const operation=this.inbox.outgoing(key);
+    if(!operation||operation.kind!==kind)throw new LocalError('invalid_configuration');
+    if(operation.result)return {...operation.result,acceptance_replayed:true,send_key:key};
+    if(operation.failure)throw new BrokerError(operation.failure.status,operation.failure.value);
+    let priorUnknown=!!operation.uncertain;
+    try{this.inbox.markOutgoingAttempt(key);}catch(error){
+      if(priorUnknown)throw new LocalError('storage_unavailable',{effect:'unknown'});
+      throw error; // a wholly new operation has not reached the network
+    } // crash before/after HTTP stays uncertain
+    const body=kind==='send'?operation.request:Object.fromEntries(Object.entries(operation.request).filter(([k])=>k!=='message_id'));
+    const path=kind==='send'?'/v1/messages':`/v1/messages/${validateUuid(operation.request.message_id)}/resend`;
+    let result;
+    try{
+      result=await this.request('POST',path,{body,key,idempotent:true,deadline:operation.retry_until,signal,onError:error=>{if(error.effect!=='not_applied')priorUnknown=true;}});
+    }catch(error){
+      // A rejection of a later retry is not evidence that an earlier unknown
+      // attempt was rejected. Only a first, wholly known-not-applied operation
+      // may become a durable terminal failure; other intents remain independent.
+      if(!priorUnknown&&error instanceof BrokerError&&error.effect==='not_applied'&&!error.retryable)this.inbox.recordSendFailure(key,{status:error.status,value:error.toJSON()});
+      throw error;
+    }
+    try{validateUuid(result?.message_id);}catch{throw new LocalError('invalid_response',{effect:'unknown'});}
+    try{
+      this.inbox.recordSendResult(key,result);
+      if(kind==='send'&&operation.request.metadata_patch)this.inbox.setState('metadata',{...this.inbox.getState('metadata'),...operation.request.metadata_patch});
+    }catch{
+      // The broker already accepted this operation. A failed local result or
+      // metadata commit describes only the journal, never remote non-delivery.
+      throw new LocalError('storage_unavailable',{effect:'unknown'});
+    }
+    return {...result,send_key:key};
+  }
+
+  async cancelMessage(messageId, { signal } = {}) {
+    return this.request('POST',`/v1/messages/${validateUuid(messageId)}/cancel`,{body:{},idempotent:true,signal});
+  }
+
+  async recoverOutgoing({ limit = 10, signal } = {}) {
+    if(!Number.isSafeInteger(limit)||limit<1||limit>100)throw new LocalError('invalid_configuration');
+    const records=[];
+    const {operations,expiredCount}=this.inbox.outgoingRecovery(limit,this.now());
+    for(const operation of operations){
+      try{
+        const pending=this.inbox.outgoing(operation.key);
+        const value=await (pending.kind==='resend'?this.resendPrepared(operation.key,{signal}):this.sendPrepared(operation.key,{signal}));
+        const {send_key,...result}=value;records.push({operation:pending.kind,result});
+      }catch(error){records.push({error:error instanceof LocalError||error instanceof BrokerError?error.toJSON().error:new LocalError('request_failed',{effect:'unknown'}).toJSON().error});}
+    }
+    if(expiredCount)records.push({...new LocalError('retry_window_elapsed',{effect:'unknown'}).toJSON(),count:expiredCount});
+    return records;
+  }
+
+  async sentHistory(filters = {}, { signal } = {}) {
+    const allowed=['recipient_id','status','accepted_after','accepted_before','limit','cursor'];
+    if(!filters||typeof filters!=='object'||Array.isArray(filters)||Object.keys(filters).some(key=>!allowed.includes(key))) throw new LocalError('invalid_configuration');
+    const query=new URLSearchParams();
+    for(const [key,value] of Object.entries(filters)) query.set(key,String(value));
+    return this.request('GET',`/v1/messages${query.size?`?${query}`:''}`,{idempotent:true,signal});
+  }
+
+  async messageContent(messageId, { signal } = {}) {
+    return this.request('GET',`/v1/messages/${validateUuid(messageId)}/content`,{idempotent:true,signal});
+  }
+
+  async messageStatus(messageId, { signal } = {}) {
+    return this.request('GET', `/v1/messages/${validateUuid(messageId)}`, { idempotent: true, signal });
+  }
+
+  async claim(waitSeconds = 30, { signal } = {}) {
+    let pending = this.inbox.getState('claim_pending');
+    if (!pending) {
+      pending = { key: randomUUID(), body: validateClaim({ wait_seconds: waitSeconds }), lease_epoch: this.attachment.lease_epoch };
+      this.inbox.setState('claim_pending', pending);
+    }
+    if (pending.lease_epoch !== this.attachment.lease_epoch) throw new LocalError('session_mismatch');
+    const result = await this.request('POST', '/v1/mailbox/claim', { body: pending.body, key: pending.key, idempotent: true, signal });
+    if (result === null) this.inbox.setState('claim_pending', null);
+    return result;
+  }
+
+  async complete(messageId, completion, { signal } = {}) {
+    const result = await this.request('POST', `/v1/mailbox/${validateUuid(messageId)}/complete`, {
+      body: validateCompletion(completion), idempotent: true, signal });
+    this.inbox.setState('claim_pending', null);
+    return result;
+  }
+
+  async renew(messageId, claimId, { signal } = {}) {
+    return this.request('POST', `/v1/mailbox/${validateUuid(messageId)}/renew`, {
+      body: validateRenew({ claim_id: claimId }), idempotent: true, signal });
+  }
+}

package/vendor/broker/reference/errors.mjs

@@ -0,0 +1,43 @@
+/** Local errors deliberately never include content, paths, credentials or native responses. */
+const MESSAGES = {
+  invalid_configuration: 'Correct the local adapter configuration before retrying.',
+  session_expired: 'This broker identity is no longer available. Verify the native session and explicitly create a fresh journal; never replay old pending work.',
+  session_mismatch: 'Verify the exact surviving harness session; do not adopt its mailbox.',
+  owner_conflict: 'Another worker owns this session inbox. Stop it before starting another.',
+  storage_unavailable: 'Restore local durable storage before retrying.',
+  inbox_full: 'The local inbox or deduplication budget is full; preserve pending input.',
+  envelope_mismatch: 'A message ID changed its immutable envelope. Pause and inspect the protocol.',
+  envelope_expired: 'The transport deadline passed; do not accept a new inbox item.',
+  invalid_envelope: 'The broker envelope is invalid; no inbox item was accepted.',
+  invalid_response: 'The broker response is invalid. Reconcile the original operation.',
+  request_failed: 'The network result is unknown. Retry only the original idempotent operation.',
+  request_aborted: 'The request was canceled. Reconcile any potentially applied operation.',
+  retry_window_elapsed: 'The automatic retry window ended. Reconcile; do not allocate a replacement key.',
+  send_conflict: 'The local send key already names a different request.',
+  injection_uncertain: 'Native acceptance is uncertain. The local FIFO head is paused for operator review.',
+  unsafe_boundary: 'Keep the input pending until the harness provides a verified safe boundary.',
+  receipt_required: 'A supported native acceptance receipt is required before consumption is recorded.',
+  unknown_tool: 'Use a documented broker tool name.',
+};
+
+export class LocalError extends Error {
+  constructor(code, { effect = 'not_applied', retryable = false, field = null } = {}) {
+    super(MESSAGES[code] ?? MESSAGES.invalid_configuration);
+    this.name = 'LocalError';
+    this.code = code;
+    this.effect = effect;
+    this.retryable = retryable;
+    this.field = field;
+  }
+  toJSON() {
+    return { error: { code: this.code, message: this.message, action: this.message,
+      retryable: this.retryable, effect: this.effect, field: this.field,
+      contract_ref: 'docs/reference.md#local-errors' } };
+  }
+}
+
+export function safeError(error) {
+  if (error instanceof LocalError) return error.toJSON();
+  if (error?.toJSON && error?.name === 'BrokerError') return error.toJSON();
+  return new LocalError('storage_unavailable', { effect: 'unknown' }).toJSON();
+}