@matuto-ai/opencode-broker-connector 0.0.0-stage → 0.1.0

package/src/native-plugin.mjs

@@ -0,0 +1,105 @@
+import { ACK_DEFINITION } from './tool-catalog.mjs';
+import { mkdtempSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { createOpenCodeAdapter, nativeShape } from './opencode-adapter.mjs';
+import { privateDirectory } from './config.mjs';
+
+const validId = value => typeof value === 'string' && /^[a-zA-Z0-9_.:-]{1,256}$/.test(value);
+/** Native, session-keyed cooperative tools. Does not attach to or control a TUI. */
+export async function createNativePlugin({ native, tool, reference, config, clientFactory,
+  adapterFactory = createOpenCodeAdapter }) {
+  const directory = realpathSync(native.directory), worktree = realpathSync(native.worktree);
+  const runDirectory = mkdtempSync(join(privateDirectory(config.stateDirectory), 'opencode-'));
+  const sessions = new Map();
+  let disposed = false;
+  async function sessionInfo(id, signal) {
+    if (!validId(id)) throw new reference.LocalError('session_mismatch');
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(2000)]);
+    let listener;
+    const result = await Promise.race([
+      Promise.resolve().then(() => native.client.session.get({ path: { id } }, { signal: bounded })),
+      new Promise((_, reject) => {
+        listener = () => reject(new reference.LocalError('session_mismatch'));
+        if (bounded.aborted) listener(); else bounded.addEventListener('abort', listener, { once: true });
+      }),
+    ]).finally(() => bounded.removeEventListener('abort', listener));
+    if (disposed || bounded.aborted || result?.error || result?.data?.id !== id
+      || realpathSync(result.data.directory) !== directory) throw new reference.LocalError('session_mismatch');
+    return result.data;
+  }
+  async function close(id) {
+    const state = sessions.get(id);
+    if (!state) return;
+    state.controller.abort();
+    if (state.closing) return state.closing;
+    state.closing = (async () => {
+      await state.starting?.catch(() => {});
+      await state.adapter?.stop();
+      if (sessions.get(id) === state) sessions.delete(id);
+    })();
+    return state.closing;
+  }
+  async function getSession(id) {
+    if (disposed || !validId(id)) throw new reference.LocalError('session_mismatch');
+    let state = sessions.get(id);
+    if (state?.closing) { await state.closing; state = undefined; }
+    if (state) { await state.starting; return state; }
+    if (sessions.size >= 64) throw new reference.LocalError('owner_conflict');
+    state = { controller: new AbortController(), lifetime: Symbol('opencode plugin session'), adapter: null };
+    sessions.set(id, state);
+    state.starting = (async () => {
+      await sessionInfo(id, state.controller.signal);
+      if (state.controller.signal.aborted) throw new reference.LocalError('session_mismatch');
+      const identity = reference.newSessionIdentity('opencode');
+      const inbox = new reference.Inbox({ directory: join(runDirectory, createHash('sha256').update(id).digest('hex') + '-' + identity.session_instance_id), identity });
+      const binding = { sessionID: id, directory, worktree, lifetime: state.lifetime, signal: state.controller.signal };
+      const currentBinding = async () => {
+        if (disposed || state.controller.signal.aborted || sessions.get(id) !== state) return null;
+        try { await sessionInfo(id, state.controller.signal); } catch { return null; }
+        return !disposed && !state.controller.signal.aborted && sessions.get(id) === state ? binding : null;
+      };
+      try {
+        const client = clientFactory ? clientFactory(inbox) : new reference.BrokerClient({ ...config.broker, inbox });
+        state.adapter = adapterFactory({ reference, tool, client, binding, currentBinding, cooperativeAck: true });
+        await state.adapter.start({ name: config.name ?? 'OpenCode', model: { provider: null, id: null, source: 'unknown' }, project: null });
+        if (!await currentBinding()) throw new reference.LocalError('session_mismatch');
+      } catch (error) { if (state.adapter) await state.adapter.stop(); else inbox.close(); throw error; }
+      return state;
+    })();
+    try { return await state.starting; }
+    catch (error) { if (sessions.get(id) === state) sessions.delete(id); throw error; }
+  }
+  const catalog = [...reference.TOOL_DEFINITIONS, ACK_DEFINITION];
+  const proxies = Object.fromEntries(catalog.map(definition => [definition.name, tool({
+    description: definition.description,
+    args: nativeShape(tool.schema, definition.inputSchema),
+    async execute(args, context) {
+      try {
+        if (!context || !validId(context.messageID) || !(context.abort instanceof AbortSignal)
+          || context.abort.aborted || realpathSync(context.directory) !== directory || realpathSync(context.worktree) !== worktree) throw new reference.LocalError('session_mismatch');
+        const state = await getSession(context.sessionID);
+        return await state.adapter.tools[definition.name].execute(args, context);
+      } catch (error) { return JSON.stringify(reference.safeError(error)); }
+    },
+  })]));
+  async function dispose() {
+    if (disposed) return;
+    disposed = true;
+    await Promise.all([...sessions.keys()].map(close));
+  }
+  return {
+    tool: proxies,
+    async event({ event }) {
+      if (event.type === 'session.deleted') await close(event.properties?.info?.id);
+      if (event.type === 'server.instance.disposed') await dispose();
+    },
+    async 'chat.message'(input, output) {
+      if (output?.message?.role === 'user' && output.message.sessionID === input.sessionID) {
+        // A missing broker must never prevent the user's ordinary chat.
+        void getSession(input.sessionID).catch(() => {}); // Non-blocking warm-up; tools await their own binding.
+      }
+    },
+    dispose,
+  };
+}

package/src/opencode-adapter.mjs

@@ -0,0 +1,189 @@
+import { createCooperativeInbox } from './cooperative-inbox.mjs';
+import { ACK_DEFINITION } from './tool-catalog.mjs';
+import { isAbsolute, normalize } from 'node:path';
+
+const TOOL_NAMES = ['broker_list_clients', 'broker_send', 'broker_update_metadata', 'broker_message_status', 'broker_receive'];
+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;
+}
+
+/**
+ * Cooperative 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 = () => {}, cooperativeAck = false }) {
+  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 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 = 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, ...(cooperativeAck ? [ACK_DEFINITION] : [])].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 });
+  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;
+  }
+  const runtime = new reference.AdapterRuntime({ 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;
+    expected.signal.removeEventListener('abort', onClose);
+    stopPromise = Promise.resolve().then(async () => {
+      try {
+        await runtime.stop({ closeSession: false }); // 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();
+      } finally { inbox.close(); }
+    });
+    return stopPromise;
+  }
+  const cooperativeInbox = cooperativeAck ? createCooperativeInbox({ inbox, isActive: () => started && !closed && !expected.signal.aborted }) : null;
+  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');
+        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) {
+        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_) };
+          for (const method of ['listClients', 'sendPrepared', 'updateMetadata', 'messageStatus', 'refreshOwnedMetadata']) {
+            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(); } });
+          if (cooperativeInbox) Object.assign(facade, cooperativeInbox);
+          const result = await reference.invokeTool(facade, definition.name, parsed.data);
+          // Unknown/cancelled host results never get repackaged as acceptance.
+          // A write may already have committed; retain its stable send key.
+          try { await assertBound(context, 'unknown'); }
+          catch (error) {
+            const failure = reference.safeError(error);
+            const sendKey = result?.send_key ?? parsed.data.send_key;
+            if (definition.name === 'broker_send' && typeof sendKey === 'string') failure.send_key = sendKey;
+            return displayJSON(failure);
+          }
+          return displayJSON(result);
+        } catch (error) { return displayJSON(reference.safeError(error)); }
+      },
+    })];
+  }));
+  return Object.freeze({ tools, start, stop, localMode: 'cooperative_pull' });
+}

package/src/owned-run.mjs

@@ -0,0 +1,193 @@
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, lstatSync, realpathSync, unlinkSync, openSync, closeSync, fstatSync, constants, renameSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { loadBrokerReference } from './reference.mjs';
+import { createOpenCodeAdapter, nativeShape } from './opencode-adapter.mjs';
+
+export const OWNED_VERSION = '1.19.4';
+export const LINUX_X64_SHA256 = '538fcb1b6408c8d4608822acee19f7ff5b3a3eb3383c0633c4f06170857312a7';
+const fail = () => { throw new Error('owned_run_configuration_invalid'); };
+const plain = value => value && typeof value === 'object' && !Array.isArray(value);
+function privateJSON(path) {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.mode & 0o077 || stat.size > 32768
+      || process.getuid && stat.uid !== process.getuid()) fail();
+    const text = readFileSync(fd, 'utf8');
+    if (Buffer.byteLength(text) > 32768) fail();
+    const value = JSON.parse(text);
+    if (!plain(value)) fail();
+    return value;
+  } finally { closeSync(fd); }
+}
+export function processIncarnation(pid = process.pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) fail();
+  const text = readFileSync(`/proc/${pid}/stat`, 'utf8');
+  const fields = text.slice(text.lastIndexOf(')') + 2).trim().split(/\s+/);
+  if (!/^[0-9]+$/.test(fields[19]) || fields[0] === 'Z') fail();
+  return { pid, starttime: fields[19], bootId: readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim() };
+}
+function sameProcess(expected) {
+  if (!plain(expected)) return false;
+  try { const actual = processIncarnation(expected.pid); return actual.starttime === expected.starttime && actual.bootId === expected.bootId; }
+  catch { return false; }
+}
+export function ownedArguments(prompt, model) {
+  if (typeof prompt !== 'string' || !prompt.trim() || !prompt.isWellFormed() || Buffer.byteLength(prompt) > 65536
+    || model !== undefined && (typeof model !== 'string' || !/^[A-Za-z0-9_][A-Za-z0-9_.:/-]{0,255}$/.test(model))) fail();
+  return ['run', '--format', 'json', ...(model ? ['--model', model] : []), '--', prompt];
+}
+export function ownedEnvironment(env, pluginPath, recordPath, nonce) {
+  let overlay = {};
+  if (env.OPENCODE_CONFIG_CONTENT) {
+    try { overlay = JSON.parse(env.OPENCODE_CONFIG_CONTENT); } catch { throw new Error('existing_config_content_must_be_json_preserve_it_before_launch'); }
+    if (!plain(overlay) || overlay.plugin !== undefined && !Array.isArray(overlay.plugin)) fail();
+  }
+  return { ...env, OPENCODE_CONFIG_CONTENT: JSON.stringify({ ...overlay,
+    plugin: [...(overlay.plugin ?? []), pathToFileURL(pluginPath).href] }),
+    OPENCODE_REVIEW_RUN_FILE: recordPath, OPENCODE_REVIEW_RUN_NONCE: nonce };
+}
+function readOwnedRecord(path, nonce) {
+  const value = privateJSON(path);
+  if (value.version !== 1 || value.nonce !== nonce || typeof nonce !== 'string' || nonce.length !== 36
+    || value.opencodeVersion !== OWNED_VERSION || !isAbsolute(value.directory) || !isAbsolute(value.referenceDirectory)
+    || !isAbsolute(value.inboxDirectory) || !plain(value.identity) || value.identity.client_type !== 'opencode'
+    || !plain(value.broker) || !Number.isFinite(value.createdAt)
+    || value.child?.pid !== process.pid || !sameProcess(value.child) || !sameProcess(value.launcher)) fail();
+  return value;
+}
+
+/** A normal native plugin, enabled ONLY by our private fresh-run launcher. */
+export async function createOwnedHooks({ native, tool, recordPath, nonce,
+  reference: suppliedReference, clientFactory, adapterFactory = createOpenCodeAdapter }) {
+  const record = readOwnedRecord(recordPath, nonce);
+  if (realpathSync(native.directory) !== record.directory) fail();
+  const reference = suppliedReference ?? await loadBrokerReference(record.referenceDirectory);
+  const lifetime = Symbol('owned-opencode-run');
+  const controller = new AbortController();
+  let rootId, seenRootId, disposed = false, adapter, bindingPromise, inbox, stopPromise;
+  const stop = () => stopPromise ??= (async () => { disposed = true; controller.abort(); await bindingPromise?.catch(() => {}); await adapter?.stop(); })();
+  async function sessionInfo(id) {
+    const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(2000)]);
+    let onAbort;
+    const result = await Promise.race([
+      Promise.resolve().then(() => native.client.session.get({ path: { id } }, { signal })),
+      new Promise((_, reject) => {
+        onAbort = () => reject(new reference.LocalError('session_mismatch'));
+        if (signal.aborted) onAbort(); else signal.addEventListener('abort', onAbort, { once: true });
+      }),
+    ]).finally(() => signal.removeEventListener('abort', onAbort));
+    const info = result?.data;
+    if (result?.error || !info || info.id !== id || info.parentID || realpathSync(info.directory) !== record.directory
+      || !Number.isFinite(info.time?.created) || info.time.created < record.createdAt) throw new reference.LocalError('session_mismatch');
+    return info;
+  }
+  async function currentBinding() {
+    if (disposed || controller.signal.aborted || !rootId) return null;
+    try { readOwnedRecord(recordPath, nonce); await sessionInfo(rootId); readOwnedRecord(recordPath, nonce); if (disposed || controller.signal.aborted) return null; }
+    catch { return null; }
+    return { sessionID: rootId, directory: native.directory, worktree: native.worktree, lifetime, signal: controller.signal };
+  }
+  const proxies = Object.fromEntries(reference.TOOL_DEFINITIONS.map(definition => [definition.name, tool({
+    description: definition.description, args: nativeShape(tool.schema, definition.inputSchema),
+    async execute(args, context) {
+      if (disposed || !adapter || context?.sessionID !== rootId) return JSON.stringify(new reference.LocalError('session_mismatch').toJSON());
+      return adapter.tools[definition.name].execute(args, context);
+    },
+  })]));
+  return {
+    tool: proxies,
+    async event({ event }) {
+      if (event.type === 'session.created' && !event.properties?.info?.parentID) {
+        const id = event.properties?.info?.id;
+        if (seenRootId && seenRootId !== id) { await stop(); return; }
+        seenRootId = id;
+      }
+      if (event.type === 'session.deleted' && event.properties?.info?.id === rootId) await stop();
+    },
+    async 'chat.message'(input, output) {
+      if (disposed || output?.message?.role !== 'user' || output.message.sessionID !== input.sessionID
+        || !seenRootId || seenRootId !== input.sessionID) throw new reference.LocalError('session_mismatch');
+      if (rootId && rootId !== input.sessionID) throw new reference.LocalError('session_mismatch');
+      if (bindingPromise) return bindingPromise;
+      rootId = input.sessionID;
+      bindingPromise = (async () => {
+        await sessionInfo(rootId);
+        if (disposed) throw new reference.LocalError('session_mismatch');
+        inbox = new reference.Inbox({ directory: record.inboxDirectory, identity: record.identity });
+        try {
+          const client = clientFactory ? clientFactory(inbox) : new reference.BrokerClient({ ...record.broker, inbox });
+          adapter = adapterFactory({ reference, tool, client, binding: { sessionID: rootId, directory: native.directory,
+            worktree: native.worktree, lifetime, signal: controller.signal }, currentBinding });
+          await adapter.start({ name: 'OpenCode owned run', model: { provider: null, id: null, source: 'unknown' }, project: null });
+          if (!await currentBinding()) throw new reference.LocalError('session_mismatch');
+          writeFileSync(`${recordPath}.bound`, JSON.stringify({ nonce, child: record.child, rootId }), { mode: 0o600, flag: 'wx' });
+        } catch (error) { controller.abort(); if (adapter) await adapter.stop(); else inbox.close(); throw error; }
+      })();
+      return bindingPromise;
+    },
+    dispose: stop,
+  };
+}
+
+/** Fixed fresh headless process only; never attach, resume, change permissions or inject a prompt into another host. */
+export async function launchOwnedRun({ configPath, prompt, env = process.env, cwd = process.cwd(), spawnImpl = spawn }) {
+  const config = privateJSON(configPath);
+  if (Object.keys(config).some(key => !['opencodeExecutable', 'referenceDirectory', 'stateDirectory', 'broker', 'model'].includes(key))
+    || !isAbsolute(config.opencodeExecutable) || !isAbsolute(config.referenceDirectory) || !isAbsolute(config.stateDirectory)
+    || !plain(config.broker) || Object.keys(config.broker).some(key => !['url', 'tokenFile', 'caFile'].includes(key))
+    || !isAbsolute(config.broker.tokenFile)) fail();
+  const binary = realpathSync(config.opencodeExecutable);
+  if (process.platform !== 'linux' || process.arch !== 'x64'
+    || createHash('sha256').update(readFileSync(binary)).digest('hex') !== LINUX_X64_SHA256) throw new Error('unsupported_opencode_binary_use_verified_linux_x64_1_19_4');
+  const reference = await loadBrokerReference(config.referenceDirectory);
+  const args = ownedArguments(prompt, config.model);
+  mkdirSync(config.stateDirectory, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(config.stateDirectory);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o077 || realpathSync(config.stateDirectory) !== config.stateDirectory || process.getuid && stat.uid !== process.getuid()) fail();
+  const runDirectory = mkdtempSync(join(config.stateDirectory, 'run-'));
+  const recordPath = join(runDirectory, 'owner.json'), nonce = randomUUID();
+  const record = { version: 1, nonce, opencodeVersion: OWNED_VERSION, createdAt: Date.now(), directory: realpathSync(cwd),
+    launcher: processIncarnation(), child: null, referenceDirectory: config.referenceDirectory, inboxDirectory: join(runDirectory, 'inbox'), identity: reference.newSessionIdentity('opencode'), broker: config.broker };
+  writeFileSync(recordPath, JSON.stringify(record), { mode: 0o600, flag: 'wx' });
+  const pluginPath = new URL('../plugin/owned-run.ts', import.meta.url);
+  let child;
+  try {
+    const childEnv = ownedEnvironment(env, fileURLToPath(pluginPath), recordPath, nonce);
+    child = spawnImpl(binary, args, { cwd: record.directory, env: childEnv, stdio: ['ignore', 'inherit', 'inherit'] });
+    if (child.pid) {
+      record.child = processIncarnation(child.pid);
+      const next = `${recordPath}.next`;
+      writeFileSync(next, JSON.stringify(record), { mode: 0o600, flag: 'wx' });
+      renameSync(next, recordPath);
+    }
+    const result = await new Promise((resolve, reject) => {
+      child.once('error', reject); child.once('exit', (code, signal) => resolve({ code, signal }));
+    });
+    if (result.code === 0) {
+      let proof;
+      try { proof = privateJSON(`${recordPath}.bound`); } catch { throw new Error('owned_native_broker_unavailable'); }
+      if (proof.nonce !== nonce || JSON.stringify(proof.child) !== JSON.stringify(record.child)
+        || typeof proof.rootId !== 'string' || !proof.rootId) throw new Error('owned_native_broker_unavailable');
+    }
+    return result;
+  } finally {
+    // Revoke the private lifetime marker. Durable inbox content is never deleted.
+    try { unlinkSync(recordPath); } catch {}
+    try { unlinkSync(`${recordPath}.bound`); } catch {}
+    // Native dispose normally closes the lease. A killed child cannot; after exit
+    // its SQLite ownership lock is released, so the same exact identity can close.
+    if (child && (child.exitCode !== null || child.signalCode)) {
+      let journal;
+      try {
+        journal = new reference.Inbox({ directory: record.inboxDirectory, identity: record.identity });
+        const client = new reference.BrokerClient({ ...record.broker, inbox: journal, maxAttempts: 1, requestTimeoutMs: 5000 });
+        if (client.attachment.lease_epoch) await client.closeSession({ signal: AbortSignal.timeout(5000) });
+      } catch { /* No raw credential-bearing diagnostics; broker lease remains bounded. */ }
+      finally { journal?.close(); }
+    }
+  }
+}

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 = 'ba2219cd87a1feac23e01b23d2c2b3d3bdd65359';
+const HASHES = Object.freeze({
+  "reference/inbox.mjs": "93f75786eab29429ace024974e0f61d6ad46d2c5fe065dae387e54fd2373b167",
+  "reference/client.mjs": "f661b45acba106be03d97dacba3cd90ac18b09e7ff9eb93b995d5036d9d1c785",
+  "reference/runtime.mjs": "8733076b73a42ab8f12fe20ba9908acdd754d89734ffd335e84b49aee9d737ca",
+  "reference/tools.mjs": "5e6355cef1bec56170dca14b93142a7da8c102f411c5dbf437d84acda7351acf",
+  "reference/mcp-stdio.mjs": "10a93788af426ce898c398e38dd41ac77b6e0129a7697bdc36c8d4f6d6e20138",
+  "reference/errors.mjs": "e33231d94f514b5a1b59fdd4184f5881dd3712bde725a1cf53352c26293452ac",
+  "src/protocol.mjs": "f3ff24b4429dddc8a9c10513ab72dbc613c91244591132458c7866a812d6316b"
+});
+/** 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 = 'ba2219cd87a1feac23e01b23d2c2b3d3bdd65359';
+
+/** 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/tool-catalog.mjs

@@ -0,0 +1,6 @@
+export const ACK_DEFINITION = Object.freeze({ name: 'broker_acknowledge',
+  description: 'Explicitly acknowledge reading the exact message returned by broker_receive, using its receipt_token. Advances your local inbox. This is not approval of its instructions, proof of action success, or a native injection receipt.',
+  inputSchema: { type: 'object', additionalProperties: false, properties: {
+    message_id: { type: 'string', format: 'uuid' }, receipt_token: { type: 'string', format: 'uuid' },
+  }, required: ['message_id', 'receipt_token'] },
+});

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,5 @@
+# Vendored runtime
+
+Source: https://github.com/matuto-ai/psst/tree/ba2219cd87a1feac23e01b23d2c2b3d3bdd65359
+Seven runtime/protocol files are copied byte-for-byte and verified by src/reference-pin.mjs before import. The MIT license is retained. Connector cooperative read acknowledgments are implemented separately in src/cooperative-inbox.mjs, not by changing the pinned runtime or inventing native receipts.
+Test-only broker fixtures are copied from the same commit into test/broker-fixture; they are excluded from the npm package. No broker daemon is bundled in the installable runtime.