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

package/src/opencode-adapter.mjs

@@ -0,0 +1,223 @@
+import { createToolScope } from './tool-scope.mjs';
+import { isAbsolute, normalize } from 'node:path';
+
+const TOOL_NAMES = ['broker_list_clients', 'broker_send', 'broker_update_metadata', 'broker_message_status', 'broker_receive', 'broker_sent_history', 'broker_message_content', 'broker_resend', 'broker_cancel'];
+// Reviewed SDK adds two cooperative presence tools. Native OpenCode keeps its
+// existing eight-tool surface; do not accidentally widen it during SDK rollout.
+export function nativeToolDefinitions(definitions) {
+  const known=[...TOOL_NAMES,'broker_presence_events','broker_acknowledge_presence_event'];
+  if(!Array.isArray(definitions)||definitions.length!==known.length||new Set(definitions.map(d=>d.name)).size!==known.length||definitions.some(d=>!known.includes(d.name)))throw new Error('Shared tool catalog changed; review it before enabling this adapter.');
+  return definitions.filter(d=>TOOL_NAMES.includes(d.name));
+}
+const localId = value => typeof value === 'string' && /^[a-zA-Z0-9_.:-]{1,256}$/.test(value);
+const absolute = value => typeof value === 'string' && isAbsolute(value) && normalize(value) === value;
+const 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;
+
+// Adapt the shared bounded tool catalog to OpenCode's documented Zod shape.
+// This is a native tool schema adapter, not another broker wire contract.
+function nativeSchema(z, rule) {
+  const nullableString = Array.isArray(rule.type) && rule.type.length === 2
+    && rule.type.includes('string') && rule.type.includes('null');
+  const allowed = rule.enum ? ['enum'] : rule.type === 'object'
+    ? ['type', 'properties', 'required', 'additionalProperties'] : rule.type === 'integer'
+    ? ['type', 'minimum', 'maximum'] : rule.type === 'boolean' ? ['type'] : ['type', 'maxLength', 'format'];
+  if (Object.keys(rule).some(key => !allowed.includes(key))
+    || Array.isArray(rule.type) && !nullableString
+    || rule.format !== undefined && rule.format !== 'uuid'
+    || rule.maxLength !== undefined && (!Number.isSafeInteger(rule.maxLength) || rule.maxLength < 1)) {
+    throw new Error('Unsupported shared tool schema; update this adapter before enabling it.');
+  }
+  let schema;
+  if (rule.enum) schema = z.enum(rule.enum);
+  else if (rule.type === 'object') schema = z.object(nativeShape(z, rule)).strict();
+  else if (rule.type === 'boolean') schema = z.boolean();
+  else if (rule.type === 'integer') {
+    schema = z.number().int().safe();
+    if (rule.minimum !== undefined) schema = schema.min(rule.minimum);
+    if (rule.maximum !== undefined) schema = schema.max(rule.maximum);
+  } else if (rule.type === 'string' || Array.isArray(rule.type) && rule.type.includes('string')) {
+    schema = z.string().refine(value => value.isWellFormed()
+      && (rule.maxLength === undefined || [...value].length <= rule.maxLength), 'Use bounded, well-formed text.');
+    if (rule.format === 'uuid') schema = schema.refine(value => uuid.test(value), 'Use an exact UUID address.');
+    if (Array.isArray(rule.type) && rule.type.includes('null')) schema = schema.nullable();
+  } else throw new Error('Unsupported shared tool schema; update this adapter before enabling it.');
+  return schema;
+}
+export function nativeShape(z, schema) {
+  if (schema.type !== 'object' || schema.additionalProperties !== false || !schema.properties
+    || !Array.isArray(schema.required) || schema.required.some(key => !Object.hasOwn(schema.properties, key))
+    || Object.keys(schema).some(key => !['type', 'properties', 'required', 'additionalProperties'].includes(key))) {
+    throw new Error('Unsupported shared tool schema; update this adapter before enabling it.');
+  }
+  return Object.fromEntries(Object.entries(schema.properties).map(([key, rule]) => {
+    const value = nativeSchema(z, rule);
+    return [key, schema.required?.includes(key) ? value : value.optional()];
+  }));
+}
+function displayJSON(value) {
+  const result = JSON.stringify(value).replace(/[\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/gu,
+    char => `\\u${char.codePointAt(0).toString(16).padStart(4, '0')}`);
+  if (Buffer.byteLength(result) > 512 * 1024) throw new Error('bounded_result');
+  return result;
+}
+
+/**
+ * Outgoing native tools for ONE verified OpenCode host-session lifetime.
+ * The trusted host owner supplies currentBinding() and aborts binding.signal on
+ * exact host close. Session IDs, a server process, and an idle observation alone
+ * are insufficient lifetime proof. No automatic plugin attachment is implied.
+ */
+export function createOpenCodeAdapter({ reference, tool, binding, currentBinding,
+  client, inbox = client?.inbox, observeMetadata = null, onDiagnostic = () => {}, operationContext = null, closeSessionOnStop = true }) {
+  if (!reference || typeof reference.AdapterRuntime !== 'function' || typeof reference.createTools !== 'function'
+    || typeof reference.invokeTool !== 'function' || typeof reference.safeError !== 'function'
+    || typeof reference.LocalError !== 'function' || !Array.isArray(reference.TOOL_DEFINITIONS)
+    || typeof tool !== 'function' || !tool.schema || !client || !inbox
+    || !binding || !localId(binding.sessionID) || !absolute(binding.directory) || !absolute(binding.worktree)
+    || typeof binding.lifetime !== 'symbol' || !(binding.signal instanceof AbortSignal)
+    || typeof closeSessionOnStop !== 'boolean'
+    || operationContext !== null && typeof operationContext !== 'function'
+    || typeof currentBinding !== 'function' || observeMetadata !== null && typeof observeMetadata !== 'function'
+    || inbox.identity?.client_type !== 'opencode' || client.inbox !== inbox) {
+    throw new Error('Invalid adapter configuration: provide a verified exact host binding and shared broker reference objects.');
+  }
+  const definitions = nativeToolDefinitions(reference.TOOL_DEFINITIONS);
+  if (definitions.length !== TOOL_NAMES.length || definitions.some(definition => !TOOL_NAMES.includes(definition.name))
+    || new Set(definitions.map(definition => definition.name)).size !== TOOL_NAMES.length) {
+    throw new Error('Shared tool catalog changed; review it before enabling this adapter.');
+  }
+  const catalog = definitions.filter(definition => definition.name !== 'broker_receive').map(definition => {
+    const args = nativeShape(tool.schema, definition.inputSchema);
+    return { definition, args, validator: tool.schema.object(args).strict() };
+  });
+  const expected = Object.freeze({ sessionID: binding.sessionID, directory: binding.directory,
+    worktree: binding.worktree, lifetime: binding.lifetime, signal: binding.signal });
+  const identity = Object.freeze({ ...inbox.identity });
+  const toolScope = createToolScope({ closedError: () => new reference.LocalError('session_mismatch', { effect: 'unknown' }), abortedError: () => new reference.LocalError('request_aborted') });
+  const recoveryAbort = new AbortController();
+  let recoveryPromise, metadataTail = Promise.resolve();
+  let started = false, closed = false, startPromise, runtimeStartPromise, stopPromise;
+  const diagnostic = code => { try { onDiagnostic({ code }); } catch { /* No raw exception data. */ } };
+  function sameIdentity(candidate) {
+    return candidate?.client_id === identity.client_id && candidate?.session_instance_id === identity.session_instance_id
+      && candidate?.client_type === identity.client_type;
+  }
+  async function alive() {
+    if (closed || expected.signal.aborted || !sameIdentity(inbox.identity)) return false;
+    let now;
+    try { now = await currentBinding(); } catch { return false; }
+    return !closed && !expected.signal.aborted && sameIdentity(inbox.identity) && now?.sessionID === expected.sessionID
+      && now?.directory === expected.directory && now?.worktree === expected.worktree
+      && now?.lifetime === expected.lifetime && now?.signal === expected.signal;
+  }
+  // The generic reference defaults a failed liveness check to terminal close.
+  // Native navigation/unload is resumable, including that internal stop path.
+  class NativeRuntime extends reference.AdapterRuntime {
+    stop(options = { closeSession: closeSessionOnStop }) { return super.stop(options); }
+    async checkAlive() {
+      const wasClosed = this.closed, alive = await super.checkAlive();
+      if (!alive && !wasClosed) diagnostic('native_binding_unavailable');
+      return alive;
+    }
+  }
+  const runtime = new NativeRuntime({ client, inbox,
+    verifySession: async candidate => sameIdentity(candidate) && await alive(), isAlive: alive,
+    onDiagnostic: entry => diagnostic(entry.code) });
+  async function stop() {
+    if (stopPromise) return stopPromise;
+    closed = true; started = false; recoveryAbort.abort();
+    const toolsClosed = toolScope.close();
+    expected.signal.removeEventListener('abort', onClose);
+    // Fence transport lifetime synchronously, before any deferred tool drain.
+    const runtimeStopped = runtime.stop({ closeSession: false });
+    stopPromise = Promise.resolve().then(async () => {
+      try {
+        await runtimeStopped; // Cancel, but do not close a stale pre-reconnect epoch.
+        await runtimeStartPromise?.catch(() => {});
+        // Registration may have committed after cancellation. Keep
+        // its journal open until a second close fences that exact late lease.
+        await runtime.stop({ closeSession: closeSessionOnStop });
+      } finally { await toolsClosed; await recoveryPromise?.catch(() => {}); inbox.close(); }
+    });
+    return stopPromise;
+  }
+  const onClose = () => { void stop().catch(() => diagnostic('adapter_close_failed')); };
+  expected.signal.addEventListener('abort', onClose, { once: true });
+  if (expected.signal.aborted) onClose();
+
+  async function assertBound(context, effect = 'not_applied') {
+    if (!await alive()) {
+      onClose();
+      throw new reference.LocalError('session_mismatch', { effect });
+    }
+    if (context && (context.sessionID !== expected.sessionID || context.directory !== expected.directory
+      || context.worktree !== expected.worktree || !localId(context.messageID) || !(context.abort instanceof AbortSignal))) {
+      throw new reference.LocalError('session_mismatch', { effect });
+    }
+    if (context?.abort?.aborted) throw new reference.LocalError('request_aborted', { effect });
+  }
+  async function start(metadata) {
+    if (startPromise || started || closed) throw new reference.LocalError('owner_conflict');
+    startPromise = (async () => {
+      await assertBound();
+      try {
+        runtimeStartPromise = runtime.start(metadata);
+        const result = await runtimeStartPromise;
+        await assertBound(undefined, 'unknown');
+        // No durable tool-call ID exists in this pinned ToolContext. Reconcile
+        // private operations after exact-session reattachment, never guess from text/messageID.
+        recoveryPromise = client.recoverOutgoing?.({ limit: 10, signal: AbortSignal.any([recoveryAbort.signal, expected.signal, AbortSignal.timeout(5000)]) });
+        await recoveryPromise?.catch(() => diagnostic('outgoing_recovery_incomplete'));
+        await assertBound(undefined, 'unknown');
+        started = true;
+        return result;
+      } catch (error) {
+        await stop().catch(() => diagnostic('adapter_close_failed'));
+        throw error;
+      }
+    })();
+    return startPromise;
+  }
+  const tools = Object.fromEntries(catalog.map(({ definition, args, validator }) => {
+    return [definition.name, tool({ description: definition.description, args,
+      async execute(arguments_, context) {
+        return toolScope.run(async operationSignal => {
+        try {
+          if (!started || !context) throw new reference.LocalError('session_mismatch');
+          await assertBound(context);
+          const parsed = validator.safeParse(arguments_);
+          if (!parsed.success) throw new reference.LocalError('invalid_configuration', { field: 'arguments' });
+          // Per-invocation closure, never a mutable global current tool context.
+          const scopedClient = { inbox, get attachment() { return client.attachment; },
+            prepareSend: (...args_) => client.prepareSend(...args_),
+            prepareResend: (...args_) => client.prepareResend(...args_) };
+          for (const method of ['listClients', 'sendPrepared', 'updateMetadata', 'messageStatus', 'refreshOwnedMetadata', 'resendPrepared', 'sentHistory', 'messageContent', 'cancelMessage']) {
+            scopedClient[method] = async (...args_) => {
+              await assertBound(context);
+              return client[method](...args_);
+            };
+          }
+          const facade = reference.createTools({ client: scopedClient, inbox, observeMetadata,
+            cooperativeBoundary: async read => { await assertBound(context); return read(); } });
+          const invoke = async () => { await assertBound(context); return reference.invokeTool(facade, definition.name, parsed.data, { ...(operationContext ? operationContext(context) : {}), signal: AbortSignal.any([operationSignal, expected.signal]) }); };
+          // Observed metadata is CAS-versioned. Serialize only metadata-writing
+          // tools within this exact session; distinct sessions remain independent.
+          let result;
+          if (observeMetadata && ['broker_send', 'broker_update_metadata'].includes(definition.name)) {
+            const pending = metadataTail.then(invoke); metadataTail = pending.catch(() => {}); result = await pending;
+          } else result = await invoke();
+          // Unknown/cancelled host results never get repackaged as acceptance.
+          // The private outgoing ledger retains any uncertain operation and its key.
+          try { await assertBound(context, 'unknown'); }
+          catch (error) {
+            const failure = reference.safeError(error);
+            return displayJSON(failure);
+          }
+          return displayJSON(result);
+        } catch (error) { return displayJSON(reference.safeError(error)); }
+        }, context?.abort).catch(error => displayJSON(reference.safeError(error)));
+      },
+    })];
+  }));
+  return Object.freeze({ tools, start, stop, localMode: 'native_automatic' });
+}

package/src/presence-notices.mjs

@@ -0,0 +1,90 @@
+import { randomUUID } from 'node:crypto';
+import { canonical, validateUuid } from '../vendor/broker/src/protocol.mjs';
+
+// Copy only bounded transport metadata. Never interpret peer content as instructions.
+export function presencePayload(event) {
+  const uuid = value => { if (typeof value !== 'string') throw Error('presence_event_invalid'); return validateUuid(value); };
+  const date = value => { if (typeof value !== 'string' || value.length > 32 || !Number.isFinite(Date.parse(value))) throw Error('presence_event_invalid'); return new Date(value).toISOString(); };
+  if (event?.type !== 'recipient_offline' || event.presence_state !== 'disconnected'
+    || !Array.isArray(event.messages) || event.messages.length < 1 || event.messages.length > 10
+    || typeof event.has_more_messages !== 'boolean') throw Error('presence_event_invalid');
+  const metadata = { event_id: uuid(event.event_id), recipient_id: uuid(event.recipient_id),
+    last_heartbeat_at: date(event.last_heartbeat_at), created_at: date(event.created_at), observed_at: date(event.observed_at),
+    presence_state: 'disconnected', messages: event.messages.map(message => {
+      if (!['queued', 'claimed'].includes(message.delivery_state) || typeof message.delivery_uncertain !== 'boolean') throw Error('presence_event_invalid');
+      return { message_id: uuid(message.message_id), delivery_state: message.delivery_state, delivery_uncertain: message.delivery_uncertain };
+    }), has_more_messages: event.has_more_messages };
+  return { text: 'Psst transport notice: recipient was offline beyond the broker grace while delivery remained pending at the observation time. '
+    + 'This is not a reply timeout or proof of non-receipt. No message was resent, cancelled or closed. Current state may have changed.\n' + canonical(metadata),
+  description: 'Psst: recipient offline, delivery pending', metadata: { source: 'psst', presence_event_id: metadata.event_id, format: 'psst-presence-v1' } };
+}
+
+/** Uses the existing session journal/owner. Persist before mutation; never retry a
+ * potentially admitted synthetic ID. Only exact promoted context permits ACK. */
+export function createPresenceNotices({ client, inbox, session, binding, call, permitted, diagnostic, now = Date.now }) {
+  inbox.transaction(() => inbox.db.exec(`CREATE TABLE IF NOT EXISTS v2_presence_notices (
+    event_id TEXT PRIMARY KEY, native_id TEXT NOT NULL UNIQUE, payload TEXT NOT NULL,
+    presented INTEGER NOT NULL DEFAULT 0, acknowledged INTEGER NOT NULL DEFAULT 0, acknowledged_at INTEGER)`));
+  let due = 0, cursor;
+  const get = eventID => inbox.db.prepare('SELECT * FROM v2_presence_notices WHERE event_id=?').get(eventID);
+  async function reconcile(row) {
+    if (!row.presented) {
+      const context = await call(session.context.bind(session), { sessionID: binding.sessionID });
+      if (!Array.isArray(context) || !context.some(message => message?.id === row.native_id && message.type === 'synthetic'
+        && canonical({ text: message.text, description: message.description, metadata: message.metadata }) === row.payload)) return;
+      if (!await permitted()) return;
+      inbox.transaction(() => inbox.db.prepare('UPDATE v2_presence_notices SET presented=1 WHERE event_id=?').run(row.event_id));
+    }
+    if (!await permitted()) return;
+    let receipt;
+    try { receipt = await call((_, options) => client.acknowledgePresenceEvent(row.event_id, options), {}); }
+    catch (error) {
+      // A verified broker 404 means a reconnect/expiry retired this event. A
+      // generic network/permission failure must never be treated as completion.
+      if (error?.code !== 'message_not_found' || error.status !== 404) throw error;
+      receipt = { event_id: row.event_id, acknowledged: true };
+    }
+    if (receipt?.event_id !== row.event_id || receipt.acknowledged !== true || !await permitted()) return;
+    inbox.transaction(() => inbox.db.prepare('UPDATE v2_presence_notices SET acknowledged=1,acknowledged_at=? WHERE event_id=?').run(now(), row.event_id));
+    diagnostic('native_presence_presented');
+  }
+  return { async tick() {
+    if (client?.policy?.presence_events !== true || typeof client.presenceEvents !== 'function'
+      || typeof client.acknowledgePresenceEvent !== 'function' || now() < due || !await permitted()) return;
+    due = now() + 60000;
+    // Retry durable presentations independently: a successfully applied ACK
+    // with a lost response already removed the event from subsequent pages.
+    const presented = inbox.db.prepare('SELECT * FROM v2_presence_notices WHERE presented=1 AND acknowledged=0 ORDER BY rowid LIMIT 10').all();
+    for (const row of presented) { if (!await permitted()) return; await reconcile(row); }
+    inbox.transaction(() => inbox.db.prepare('DELETE FROM v2_presence_notices WHERE acknowledged=1 AND acknowledged_at<=?').run(now() - 8 * 86400000));
+    const page = await call((_, options) => client.presenceEvents({ limit: 10, ...(cursor ? { cursor } : {}) }, options), {});
+    if (!Array.isArray(page?.events) || page.events.length > 10 || Buffer.byteLength(JSON.stringify(page)) > 65536
+      || page.next_cursor !== null && (typeof page.next_cursor !== 'string' || !/^(0|[1-9][0-9]{0,15})$/.test(page.next_cursor))) throw Error('presence_page_invalid');
+    // One bounded page per minute, including empty continuations. Restart at the
+    // beginning after each scan so newly added events are never skipped forever.
+    cursor = page.next_cursor ?? undefined;
+    for (const event of page.events) {
+      const payload = presencePayload(event), eventID = payload.metadata.presence_event_id;
+      if (!await permitted()) return;
+      let row = get(eventID);
+      if (row) { if (!row.acknowledged) await reconcile(row); continue; }
+      // Keep confirmed tombstones eight days. At capacity, fail closed rather
+      // than evicting an uncertain record and duplicating a native notice.
+      if (inbox.db.prepare('SELECT count(*) n FROM v2_presence_notices').get().n >= 10000) { diagnostic('native_presence_capacity'); return; }
+      const nativeID = 'msg_psst_notice_' + randomUUID().replaceAll('-', ''), serialized = canonical(payload);
+      inbox.transaction(() => inbox.db.prepare('INSERT INTO v2_presence_notices(event_id,native_id,payload) VALUES(?,?,?)').run(eventID, nativeID, serialized),
+        { growth: Buffer.byteLength(serialized) * 2 + 8192 });
+      let invoked = false;
+      try {
+        if (!await permitted()) return;
+        await call((input, options) => { invoked = true; return session.synthetic(input, options); }, {
+          sessionID: binding.sessionID, id: nativeID, ...payload, delivery: 'queue', resume: true });
+        if (await permitted()) await reconcile(get(eventID));
+      } finally {
+        // Only proven non-invocation permits removal. A lost/mismatched receipt
+        // stays pinned across restart and can only reconcile through context.
+        if (!invoked) inbox.transaction(() => inbox.db.prepare('DELETE FROM v2_presence_notices WHERE event_id=?').run(eventID));
+      }
+    }
+  } };
+}

package/src/project-metadata.mjs

@@ -0,0 +1,21 @@
+import { basename } from 'node:path';
+
+export const DEFAULT_PROJECT_ENV = 'AI_AGENTS_SANDBOX_PROJECT_NAME';
+const unsafe = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/u;
+function label(value) {
+  if (value === undefined || value === null || value === '') return null;
+  if (typeof value !== 'string' || !value.isWellFormed() || [...value].length > 256 || unsafe.test(value)) throw Error('invalid_project_metadata');
+  return value.trim() || null;
+}
+/** Local operator settings only; never accept an environment selector from a peer/tool. */
+export function projectMetadata(config = {}, env = process.env, cwd) {
+  const explicit = label(config.project);
+  if (explicit !== null) return explicit;
+  const key = env.PSST_PROJECT_ENV ?? config.projectEnv ?? DEFAULT_PROJECT_ENV;
+  if (typeof key !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key)) throw Error('invalid_project_environment');
+  const selected = label(env[key]);
+  if (selected !== null) return selected;
+  if (typeof cwd !== 'string') return null;
+  const fallback = label(basename(cwd.replaceAll('\\', '/')));
+  return fallback === '.' || fallback === '..' ? null : fallback;
+}

package/src/reference-pin.mjs

@@ -0,0 +1,21 @@
+import { readFileSync, lstatSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { createHash } from 'node:crypto';
+export const REFERENCE_COMMIT = 'f32ddc79ec7b812062ed3f6de7b9a0c12a7128f3';
+const HASHES = Object.freeze({
+  "reference/inbox.mjs": "fbf0fa6096996cb9bc3f928e55f3eca496420880a03460e993dda3417b32ad88",
+  "reference/client.mjs": "e8ab94e6de6b5afb17b1dded9839fefa26481fef87ed715b041c09d41dbc93d5",
+  "reference/runtime.mjs": "8fdaa105b2e81aeaabb628131671989f951148f602844bca6819af827269f2c3",
+  "reference/tools.mjs": "e1836d5c33ed80a9e15c1ca9d07888c9db3caf40aeb2a115c813f74a45077c6e",
+  "reference/mcp-stdio.mjs": "88c61c995f9285ef7e22c401d7f0cf50fefc7dd6c76ae79c6bcc94097a33a5c3",
+  "reference/errors.mjs": "85b0d0736c5a439f7c66697c3b1ce6cee998cda744dd3169c856ebf2b82bd2a7",
+  "src/protocol.mjs": "651f7d99987b58621070c5f24107ac621a09e325880506bc2e73cfe998d5b6aa"
+});
+/** Verify reviewed source bytes before importing any trusted local module. */
+export function verifyReference(directory) {
+  if (typeof directory !== 'string' || !isAbsolute(directory)) throw new Error('absolute_reference_required');
+  for (const [file, digest] of Object.entries(HASHES)) {
+    const path = join(directory, file), stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024 || createHash('sha256').update(readFileSync(path)).digest('hex') !== digest) throw new Error('reference_snapshot_mismatch');
+  }
+}

package/src/reference.mjs

@@ -0,0 +1,20 @@
+import { verifyReference } from './reference-pin.mjs';
+import { isAbsolute, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export const BROKER_REFERENCE_COMMIT = 'f32ddc79ec7b812062ed3f6de7b9a0c12a7128f3';
+
+/** Trusted operator path to a pinned broker checkout; never a model argument. */
+export async function loadBrokerReference(directory = fileURLToPath(new URL('../vendor/broker', import.meta.url))) {
+  if (typeof directory !== 'string' || !isAbsolute(directory)) throw new Error('Use an absolute path to the pinned broker reference checkout.');
+  verifyReference(directory);
+  const load = file => import(pathToFileURL(join(directory, file)).href);
+  const [inbox, client, runtime, tools, stdio, errors] = await Promise.all([
+    load('reference/inbox.mjs'), load('reference/client.mjs'), load('reference/runtime.mjs'),
+    load('reference/tools.mjs'), load('reference/mcp-stdio.mjs'), load('reference/errors.mjs'),
+  ]);
+  return { Inbox: inbox.Inbox, newSessionIdentity: inbox.newSessionIdentity,
+    BrokerClient: client.BrokerClient, AdapterRuntime: runtime.AdapterRuntime,
+    createTools: tools.createTools, invokeTool: tools.invokeTool,
+    TOOL_DEFINITIONS: stdio.TOOL_DEFINITIONS, LocalError: errors.LocalError, safeError: errors.safeError };
+}

package/src/setup-rpc.mjs

@@ -0,0 +1,16 @@
+// Portable OpenCode 2.2.5 RPC definition. Plain JSON Schema deliberately avoids
+// pulling the server SDK (and its Effect runtime) into the native TUI bundle.
+const sessionID = { type: 'string', minLength: 1, maxLength: 256 };
+const brokerURL = { type: 'string', minLength: 1, maxLength: 2048 };
+const input = (properties = {}, required = []) => ({ type: 'object', properties: { sessionID, ...properties }, required: ['sessionID', ...required], additionalProperties: false });
+const output = { type: 'object', additionalProperties: true };
+export const SETUP_RPC = {
+  id: 'matuto.psst.setup',
+  methods: {
+    status: { input: input({ broker_url: brokerURL }), output },
+    setup: { input: input({ broker_url: brokerURL, replacement_confirmed: { type: 'boolean' }, replacement_request_id: { type: 'string', minLength: 1, maxLength: 128 } }, ['broker_url']), output },
+    cancel: { input: input(), output },
+  },
+  events: {},
+};
+export default SETUP_RPC;

package/src/tool-schema.mjs

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+
+// The native facade needs only a schema builder and an identity definition helper.
+export function tool(definition) { return definition; }
+tool.schema = z;

package/src/tool-scope.mjs

@@ -0,0 +1,26 @@
+/** An owner's admitted tool calls must settle before its private ledger closes. */
+export function createToolScope({ closedError = () => new Error('tool_scope_closed'), abortedError = () => new Error('tool_call_aborted') } = {}) {
+  const controller = new AbortController(), pending = new Set();
+  let closed = false, closing;
+  return Object.freeze({
+    run(task, callerSignal) {
+      if (closed) return Promise.reject(closedError());
+      const signal = callerSignal instanceof AbortSignal
+        ? AbortSignal.any([controller.signal, callerSignal]) : controller.signal;
+      const operation = Promise.resolve().then(() => {
+        if (closed) throw closedError();
+        if (signal.aborted) throw abortedError();
+        return task(signal);
+      });
+      pending.add(operation);
+      void operation.then(() => pending.delete(operation), () => pending.delete(operation));
+      return operation;
+    },
+    close() {
+      if (closing) return closing;
+      closed = true; controller.abort();
+      closing = Promise.allSettled([...pending]).then(() => {});
+      return closing;
+    },
+  });
+}

package/vendor/broker/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Orsolon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/broker/ORIGIN.md

@@ -0,0 +1,12 @@
+# Pinned Psst runtime candidate
+
+Seven runtime/protocol files are copied byte-for-byte from Psst candidate commit
+`f32ddc79ec7b812062ed3f6de7b9a0c12a7128f3` and verified by `src/reference-pin.mjs`. This is a local, unreleased
+candidate, not evidence of registry publication or deployed broker support.
+Source repository: https://github.com/matuto-ai/psst . MIT license retained.
+
+The new outgoing history/content/resend/cancel APIs require the matching broker
+candidate. Existing protocol-v1 send/receive remains compatible. Older brokers
+return an explicit unsupported HTTP error for new routes; no local success is fabricated.
+Approval/enrollment helpers and test-only broker fixtures retain their separate
+original pins. Connector display and read acknowledgment changes live in `src/`.