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

package/src/native-plugin.mjs

@@ -0,0 +1,335 @@
+import packageInfo from '../package.json' with { type: 'json' };
+import { nativeMetadata } from './native-metadata.mjs';
+import { createPresenceReader, presenceDirectory } from './active-presence.mjs';
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { canonical } from '../vendor/broker/src/protocol.mjs';
+import { createOpenCodeAdapter, nativeToolDefinitions } from './opencode-adapter.mjs';
+import { createNativeDelivery, nativeSessionBinding, HOST_VERSION } from './native-delivery.mjs';
+import { openNativeIncarnation } from './native-incarnation.mjs';
+import { openNativeInbox } from './native-inbox.mjs';
+import { withNativeLock } from './native-lock.mjs';
+import { readExistingConnection } from './enrollment.mjs';
+import { SETUP_RPC } from './setup-rpc.mjs';
+import { installationDirectory } from './installation.mjs';
+import { createToolScope } from './tool-scope.mjs';
+import { createNativeSetup, SETUP_TOOLS } from './native-setup.mjs';
+import { recoverHostAnchor, readNativeBindings, assertExistingBinding } from './identity-recovery.mjs';
+
+const validID = value => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,256}$/.test(value);
+const display = value => JSON.stringify(value).replace(/[\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/gu,
+  char => `\\u${char.codePointAt(0).toString(16).padStart(4, '0')}`);
+
+/** Current native OpenCode setup. Never upgrades or mutates the host.
+ * No receive/ack fallback is registered: incoming delivery is native automatic.
+ */
+export async function setupNativePlugin({ ctx, reference, tool, loadSettings, clientFactory,
+  setupOptions = {}, metadataOptions = {}, setupEnabled = true, deliveryFactory = createNativeDelivery, adapterFactory = createOpenCodeAdapter, presenceFactory = createPresenceReader, onDiagnostic = () => {} }) {
+  if (ctx?.app?.version !== HOST_VERSION || ['get', 'synthetic', 'context', 'hook'].some(k => typeof ctx?.session?.[k] !== 'function')
+    || typeof ctx?.storage?.get !== 'function' || typeof ctx?.storage?.set !== 'function' || typeof ctx?.storage?.scan !== 'function'
+    || typeof ctx?.tool?.transform !== 'function' || typeof ctx?.event?.subscribe !== 'function') throw new Error('psst_host_capability_unavailable');
+  const directory = realpathSync(ctx.location.directory);
+  let authorizationExpired = false;
+  const readCurrentSettings = async options => {
+    try { const settings = await loadSettings(options); authorizationExpired = settings?.authorizationExpired === true; return settings; }
+    catch (error) { if (error.code === 'credential_expired') authorizationExpired = true; throw error; }
+  };
+  const hostID = await withNativeLock(setupOptions.directory ?? installationDirectory(), 'host-anchor', async () => {
+    const settings = await readCurrentSettings({ identityRecovery: setupEnabled });
+    authorizationExpired = settings?.authorizationExpired === true;
+    return recoverHostAnchor({ storage: ctx.storage, session: ctx.session, settings, directory, workspaceID: ctx.location.workspaceID });
+  });
+  const registryPrefix = 'psst-v2-session:' + createHash('sha256').update(canonical({ directory, workspaceID: ctx.location.workspaceID ?? null })).digest('hex') + ':';
+  if (!validID(hostID)) throw new Error('psst_host_binding_unavailable');
+  const sessions = new Map(), preparing = new Map(), blocked = new Set(), authorizationBlocked = new Map(), archived = new Set(), controller = new AbortController(), registrations = [], toolScope = createToolScope();
+  let disposed = false, closing, events, setup, presenceTimer, synchronizing;
+  const presence = presenceFactory({ directory: presenceDirectory(setupOptions.directory ?? installationDirectory(), ctx.location, { create: true }) });
+  const selected = sessionID => { try { return presence.selected().has(sessionID); } catch { return false; } };
+  const diagnostic = code => { try { onDiagnostic({ code }); } catch {} };
+  async function getInfo(sessionID, signal = controller.signal) {
+    if (!validID(sessionID) || signal.aborted || disposed) throw new Error('native_session_mismatch');
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(2000)]);
+    let listener;
+    const info = await Promise.race([
+      ctx.session.get({ sessionID }, { signal: bounded }),
+      new Promise((_, reject) => { listener = () => reject(new Error('native_session_unavailable'));
+        if (bounded.aborted) listener(); else bounded.addEventListener('abort', listener, { once: true }); }),
+    ]).finally(() => bounded.removeEventListener('abort', listener));
+    if (bounded.aborted || disposed || info?.id !== sessionID || info.parentID || info.time?.archived
+      || realpathSync(info.location.directory) !== directory || info.location.workspaceID !== ctx.location.workspaceID) throw new Error('native_session_mismatch');
+    return info;
+  }
+  async function close(sessionID, state = sessions.get(sessionID)) {
+    if (!state) return;
+    if (state.closing) return state.closing;
+    state.controller.abort();
+    state.closing = (async () => {
+      await state.starting?.catch(() => {});
+      await state.delivery?.stop();
+      await state.adapter?.stop();
+      if (!state.adapter) state.inbox?.close();
+      state.incarnation?.close();
+      if (sessions.get(sessionID) === state) sessions.delete(sessionID);
+      if (preparing.get(sessionID) === state) preparing.delete(sessionID);
+    })();
+    return state.closing;
+  }
+  async function connect(sessionID, { candidateSettings } = {}) {
+    const target = candidateSettings ? preparing : sessions;
+    if (disposed || blocked.has(sessionID) || !candidateSettings && authorizationBlocked.has(sessionID) || archived.has(sessionID)) throw new Error('native_plugin_closed');
+    if (!selected(sessionID)) throw new Error('native_session_not_selected');
+    let state = target.get(sessionID);
+    if (state) { await state.starting; if (state.closing) throw new Error('native_session_closing'); return state; }
+    if (sessions.size >= 64) throw new Error('native_session_limit');
+    state = { controller: new AbortController(), lifetime: Symbol('native host session') };
+    target.set(sessionID, state);
+    state.starting = (async () => {
+      const info = await getInfo(sessionID, state.controller.signal);
+      const nativeBinding = nativeSessionBinding(info, hostID);
+      const settings = candidateSettings ?? await readCurrentSettings();
+      state.settings = settings;
+      if (!settings || disposed || blocked.has(sessionID) || state.controller.signal.aborted) throw new Error('psst_connect_required');
+      const valid = async () => {
+        if (settings.enrollment && Date.parse(settings.enrollment.expiresAt) <= Date.now()) return null;
+        if (disposed || !selected(sessionID) || blocked.has(sessionID) || state.controller.signal.aborted || sessions.get(sessionID) !== state && preparing.get(sessionID) !== state
+          || settings.enrollment && Date.parse(settings.enrollment.expiresAt) <= Date.now()) return null;
+        try {
+          const now = await getInfo(sessionID, state.controller.signal);
+          return selected(sessionID) && !state.controller.signal.aborted && canonical(nativeSessionBinding(now, hostID)) === canonical(nativeBinding) ? now : null;
+        } catch { return null; }
+      };
+      assertExistingBinding(settings, nativeBinding);
+      state.incarnation = settings.broker.registrationVersion === 2 ? openNativeIncarnation({ reference, settings, binding: nativeBinding }) : null;
+      state.inbox = state.incarnation?.inbox ?? openNativeInbox({ reference, settings, binding: nativeBinding });
+      await ctx.storage.set(registryPrefix + sessionID, { sessionID, binding: nativeBinding, enabled: true });
+      if (blocked.has(sessionID)) await ctx.storage.set(registryPrefix + sessionID, { sessionID, enabled: false });
+      if (!await valid()) throw new Error('native_session_mismatch');
+      for (let attempt = 0; attempt < 2; attempt++) {
+      state.client = clientFactory ? clientFactory(state.inbox) : new reference.BrokerClient({ ...settings.broker, inbox: state.inbox });
+      const binding = { sessionID, directory, worktree: directory, lifetime: state.lifetime, signal: state.controller.signal };
+      state.adapter = adapterFactory({ reference, tool, client: state.client, binding,
+        currentBinding: async () => await valid() ? binding : null, closeSessionOnStop: false,
+        observeMetadata: async () => { const current = await valid(); if (!current) return null; const metadata = nativeMetadata(current, { ...settings, ...metadataOptions });
+          return canonical(metadata) === canonical(state.inbox.getState('metadata')) ? null : metadata; },
+        operationContext: context => ({ operationId: canonical({ hostID, sessionID, messageID: context.messageID, callID: context.callID }), operationStartedAt: context.operationStartedAt }),
+        onDiagnostic: entry => {
+          diagnostic(entry.code);
+          if (entry.code === 'native_binding_unavailable' || entry.code === 'session_expired' && state.delivery) queueMicrotask(() => void close(sessionID, state).catch(() => {}));
+          if (['unauthenticated', 'forbidden', 'registration_upgrade_required', 'retry_window_elapsed'].includes(entry.code)) { if (sessions.get(sessionID) === state) authorizationBlocked.set(sessionID, entry.code); queueMicrotask(() => void close(sessionID, state).catch(() => {})); }
+        } });
+      try { await state.adapter.start(nativeMetadata(info, { ...settings, ...metadataOptions })); break; }
+      catch (error) {
+        if (attempt !== 0 || error.code !== 'session_expired' || !state.incarnation || !state.client.expiredIdentityConfirmed) throw error;
+        await state.adapter.stop();
+        if (!await valid()) throw new Error('native_session_mismatch');
+        state.inbox = await state.incarnation.replace({ client: state.client, verifySession: async () => !!await valid(), signal: state.controller.signal });
+        state.adapter = undefined;
+      }
+      }
+      if (!await valid()) throw new Error('native_session_mismatch');
+      state.delivery = deliveryFactory({ session: ctx.session, client: state.client, inbox: state.inbox, binding: nativeBinding,
+        signal: state.controller.signal, verify: valid, available: () => sessions.get(sessionID) === state && selected(sessionID), onDiagnostic: entry => { state.deliveryStatus = entry.code; diagnostic(entry.code); } });
+      if (!candidateSettings) state.delivery.start();
+      return state;
+    })();
+    try { return await state.starting; }
+    catch (error) {
+      // Storage uncertainty is terminal for automatic restore in this plugin
+      // lifetime. A deliberate restart re-reads the durable pointer first.
+      if (!candidateSettings && error.code === 'native_incarnation_uncertain') blocked.add(sessionID);
+      state.controller.abort(); await state.delivery?.stop(); await state.adapter?.stop();
+      if (!state.adapter) state.inbox?.close();
+      state.incarnation?.close();
+      if (sessions.get(sessionID) === state) sessions.delete(sessionID);
+      if (preparing.get(sessionID) === state) preparing.delete(sessionID);
+      throw error;
+    }
+  }
+  // Prepare the approved candidate without native delivery while the previous
+  // authorization stays live. Only the exact pending-flow CAS promotes it. Old
+  // credential-bound journals remain intact; explicit replacement never adopts
+  // an inbox belonging to another authority.
+  async function activate({ sessionID, connectionFile, commit, signal }) {
+    const settings = await readExistingConnection(connectionFile);
+    const previous = sessions.get(sessionID);
+    await previous?.starting;
+    const same = previous && canonical({ broker: previous.settings.broker, stateDirectory: previous.settings.stateDirectory })
+      === canonical({ broker: settings.broker, stateDirectory: settings.stateDirectory });
+    if (same) { if (signal.aborted) throw new Error('psst_setup_cancelled'); await commit(); return previous; }
+    let candidate;
+    const cancel = () => preparing.get(sessionID)?.controller.abort();
+    signal.addEventListener('abort', cancel, { once: true });
+    try {
+      if (signal.aborted) throw new Error('psst_setup_cancelled');
+      candidate = await connect(sessionID, { candidateSettings: settings });
+      if (signal.aborted || candidate.controller.signal.aborted || !selected(sessionID)) throw new Error('psst_setup_cancelled');
+      await commit();
+      // No await between committed selection and map promotion. Starting native
+      // delivery is synchronous and has no submission side effect until its tick.
+      preparing.delete(sessionID); sessions.set(sessionID, candidate); authorizationBlocked.delete(sessionID); authorizationExpired = false;
+      candidate.delivery.start();
+    } catch (error) {
+      if (candidate && sessions.get(sessionID) !== candidate) await close(sessionID, candidate);
+      throw error;
+    } finally { signal.removeEventListener('abort', cancel); }
+    if (previous) await close(sessionID, previous);
+    return candidate;
+  }
+  const catalog = nativeToolDefinitions(reference.TOOL_DEFINITIONS).filter(def => def.name !== 'broker_receive');
+  function dispose() {
+    if (closing) return closing;
+    // Every caller joins the same drain, including shutdown triggered by the
+    // event subscription. Do not release an owner while its calls still run.
+    closing = Promise.resolve().then(async () => {
+      await setup?.stop();
+      await toolScope.close();
+      await Promise.all([...sessions, ...preparing].map(([id, state]) => close(id, state)));
+      await Promise.all(registrations.map(item => item.dispose()));
+      await events?.catch(() => {});
+    });
+    disposed = true; clearInterval(presenceTimer); controller.abort();
+    for (const state of [...sessions.values(), ...preparing.values()]) state.controller.abort();
+    return closing;
+  }
+  const status = sessionID => {
+    const state = sessions.get(sessionID);
+    const expired = state?.settings ? !!state.settings.enrollment && Date.parse(state.settings.enrollment.expiresAt) <= Date.now() : authorizationExpired;
+    const rejected = ['unauthenticated', 'forbidden'].includes(authorizationBlocked.get(sessionID));
+    const authorization = expired ? 'expired' : rejected ? 'rejected' : authorizationBlocked.has(sessionID) ? 'blocked' : state?.delivery ? 'active' : 'unknown';
+    return { connector_version: packageInfo.version, host_version: HOST_VERSION, mode: 'native_automatic',
+      connected: !disposed && !state?.controller.signal.aborted && !!state?.delivery && selected(sessionID) && authorization === 'active',
+      availability: selected(sessionID) ? 'selected' : 'inactive', authorization_state: authorization,
+      client_id: state?.client?.inbox?.identity?.client_id ?? null,
+      last_delivery_status: state?.deliveryStatus ?? null, receipt_semantics: 'durable_native_admission_not_model_read' };
+  };
+  if (setupEnabled) setup = createNativeSetup({ storage: ctx.storage, verify: async id => { try { if (!selected(id)) return null; const info = await getInfo(id); return selected(id) ? info : null; } catch { return null; } }, connect, activate, status, signal: controller.signal, ...setupOptions });
+  try {
+    if (setup && ctx.rpc?.register) {
+      const invoke = async (name, input, rpcContext) => {
+        if (!selected(input.sessionID)) throw new Error('native_session_not_selected');
+        try { return await setup.invoke(name, name === 'broker_setup' ? { broker_url: input.broker_url }
+          : name === 'broker_setup_status' && input.broker_url ? { broker_url: input.broker_url } : {}, {
+          sessionID: input.sessionID, signal: rpcContext.signal,
+          confirmedReplacement: input.replacement_confirmed === true,
+          replacementRequestId: input.replacement_request_id,
+        }); } catch { return { state: 'setup_blocked', ...status(input.sessionID) }; }
+      };
+      registrations.push(await ctx.rpc.register(SETUP_RPC, {
+        status: (input, context) => invoke('broker_setup_status', input, context),
+        setup: (input, context) => invoke('broker_setup', input, context),
+        cancel: (input, context) => invoke('broker_cancel_setup', input, context),
+      }));
+    }
+    // Read all known tombstones before publishing hooks/tools or starting any
+    // manifest restoration. A disabled session must never be resurrected.
+    let cursor, scanned = 0;
+    do {
+      const saved = await ctx.storage.scan({ prefix: registryPrefix, limit: 64, ...(cursor ? { after: cursor } : {}) });
+      for (const entry of saved.entries) {
+        if (++scanned > 256) throw new Error('native_registry_scan_limit');
+        const record = entry.value;
+        if (record?.enabled === false && validID(record.sessionID)) {
+          if (record.reason === 'archived') archived.add(record.sessionID); else blocked.add(record.sessionID);
+        }
+      }
+      cursor = saved.next;
+    } while (cursor && !disposed);
+    registrations.push(await ctx.tool.transform(editor => {
+      // Preflight the entire catalog before mutating the host editor.
+      for (const definition of [...(setup ? SETUP_TOOLS : []), ...catalog]) if (editor.get(definition.name)) throw new Error('psst_tool_conflict');
+      for (const definition of setup ? SETUP_TOOLS : []) {
+        if (editor.get(definition.name)) throw new Error('psst_tool_conflict');
+        editor.add({ ...definition, async execute(args, context) {
+          try { return { content: display(await setup.invoke(definition.name, args, context)) }; }
+          catch { return { content: display({ state: 'setup_blocked', next_step: 'Check setup status; do not paste credentials or automatically replace the request.' }) }; }
+        } });
+      }
+      for (const definition of catalog) {
+        if (editor.get(definition.name)) throw new Error('psst_tool_conflict');
+        editor.add({ name: definition.name, description: definition.description, input: definition.inputSchema,
+          // CodeMode children share the outer execute ID. Outgoing effects must
+          // use direct native calls, which have durable individual IDs/times.
+          ...(['broker_send', 'broker_resend'].includes(definition.name) ? { options: { codemode: false } } : {}),
+          async execute(args, context) {
+            return toolScope.run(async operationSignal => {
+            try {
+              if (!(context?.signal instanceof AbortSignal) || context.signal.aborted || !validID(context.messageID) || !validID(context.id)) throw new Error('native_session_mismatch');
+              const state = await connect(context.sessionID);
+              let operationStartedAt;
+              if (['broker_send', 'broker_resend'].includes(definition.name)) {
+                const bounded = AbortSignal.any([context.signal, operationSignal, controller.signal, AbortSignal.timeout(2000)]);
+                let listener;
+                const messages = await Promise.race([ctx.session.context({ sessionID: context.sessionID }, { signal: bounded }),
+                  new Promise((_, reject) => { listener = () => reject(new Error('native_context_unavailable')); if (bounded.aborted) listener(); else bounded.addEventListener('abort', listener, { once: true }); })
+                ]).finally(() => bounded.removeEventListener('abort', listener));
+                const message = messages.find(item => item.id === context.messageID && item.type === 'assistant');
+                const call = message?.content?.find(item => item.type === 'tool' && item.id === context.id && item.name === definition.name);
+                operationStartedAt = call?.time?.created;
+                if (!Number.isSafeInteger(operationStartedAt) || operationStartedAt <= 0) throw new Error('native_original_tool_timestamp_unavailable');
+              }
+              const content = await state.adapter.tools[definition.name].execute(args, { sessionID: context.sessionID,
+                messageID: context.messageID, callID: context.id, ...(operationStartedAt ? { operationStartedAt } : {}), directory, worktree: directory, abort: AbortSignal.any([context.signal, operationSignal, controller.signal]) });
+              return { content };
+            } catch { return { content: display({ error: { code: 'session_mismatch', effect: 'unknown' } }) }; }
+            }, context?.signal).catch(() => ({ content: display({ error: { code: 'session_mismatch', effect: 'unknown' } }) }));
+          } });
+      }
+    }));
+    // Prompt observation only, no mutation of human draft, selection or prompt.
+    registrations.push(await ctx.session.hook('prompt', event => { void connect(event.sessionID).catch(() => diagnostic('native_connection_unavailable')); }));
+    events = (async () => {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        if (disposed) break;
+        if (event.type === 'location.shutdown' && event.location?.directory === directory) { void dispose(); break; }
+        const sessionID = event.data?.sessionID;
+        setup?.event(event);
+        const state = sessions.get(sessionID);
+        state?.delivery?.event(event);
+        if (['session.deleted', 'session.archived', 'session.moved'].includes(event.type)) {
+          if (event.type === 'session.archived') archived.add(sessionID); else blocked.add(sessionID); state?.controller.abort();
+          if (validID(sessionID)) await ctx.storage.set(registryPrefix + sessionID, { sessionID, enabled: false, reason: event.type === 'session.archived' ? 'archived' : 'disabled' });
+          await Promise.all([close(sessionID), close(sessionID, preparing.get(sessionID))]);
+        }
+        if (event.type === 'session.unarchived' && archived.has(sessionID) && !blocked.has(sessionID)) {
+          archived.delete(sessionID);
+          await ctx.storage.set(registryPrefix + sessionID, { sessionID, enabled: true });
+        }
+        if (event.type === 'session.created') void connect(sessionID).catch(() => diagnostic('native_connection_unavailable'));
+      }
+      // A clean EOF is still loss of cancellation/lifecycle observation. Polling
+      // native state cannot replace the missed in-flight event boundaries.
+      if (!disposed) throw new Error('native_event_stream_unavailable');
+    })().catch(() => { if (!disposed) { diagnostic('native_event_stream_unavailable'); void dispose().catch(() => diagnostic('native_shutdown_incomplete')); } });
+    // Selection never creates a binding. It only restores an already persisted,
+    // independently checked native identity. New sessions connect through their
+    // verified native prompt/tool/setup context, not through a lease file.
+    const synchronize = async () => {
+      if (disposed || synchronizing) return;
+      synchronizing = (async () => {
+        let active; try { active = presence.selected(); } catch { active = new Set(); diagnostic('native_selection_unavailable'); }
+        await Promise.all([...sessions.keys()].filter(id => !active.has(id)).map(id => close(id)));
+        if (disposed) return;
+        // Candidate recovery is independent of a valid working installation.
+        // A corrupt pending flow cannot suppress restoration of its old mailbox.
+        try { await setup?.resume(); } catch { diagnostic('native_setup_restore_unavailable'); }
+        const settings = await readCurrentSettings();
+        for (const record of readNativeBindings(settings)) {
+          const b = record.binding;
+          if (active.has(b.sessionID) && b.hostID === hostID && b.location.directory === directory
+            && b.location.workspaceID === ctx.location.workspaceID && !blocked.has(b.sessionID)) {
+            if (archived.has(b.sessionID)) {
+              try { await getInfo(b.sessionID); archived.delete(b.sessionID); } catch { continue; }
+            }
+            await connect(b.sessionID).catch(() => diagnostic('native_restore_unavailable'));
+          }
+        }
+      })().catch(() => diagnostic('native_selection_unavailable'));
+      try { await synchronizing; } finally { synchronizing = undefined; }
+    };
+    await synchronize();
+    if (disposed) { await dispose(); throw new Error('native_event_stream_unavailable'); }
+    presenceTimer = setInterval(() => void synchronize(), 500); presenceTimer.unref?.();
+    void setup?.resume().catch(() => diagnostic('native_setup_restore_unavailable'));
+    return { dispose, connect, status, activate };
+  } catch (error) { await dispose(); throw error; }
+}

package/src/native-setup.mjs

@@ -0,0 +1,208 @@
+import { canonical } from '../vendor/broker/src/protocol.mjs';
+import { loadApprovalHelper } from './approval-helper.mjs';
+import { installationDirectory, readSelection, readPending, savePending, updatePending, selectInstallation } from './installation.mjs';
+import { withNativeLock } from './native-lock.mjs';
+import { createToolScope } from './tool-scope.mjs';
+import { setTimeout as delay } from 'node:timers/promises';
+
+const publicState = value => ({ state: value?.state ?? 'setup_needed',
+  ...(value?.requestId ? { request_id: value.requestId } : {}),
+  ...(value?.approvalUrl ? { approval_url: value.approvalUrl } : {}),
+  ...(value?.requestExpiresAt ? { request_expires_at: value.requestExpiresAt } : {}) });
+export const SETUP_TOOLS = [
+  { name: 'broker_setup', description: 'Explicit user-requested URL-only Psst setup. Provide only the HTTPS broker URL. Creates or resumes one private request for human approval. Never call on startup. Replacing an authorization requires confirmation in the native /psst-setup dialog.',
+    input: { type: 'object', properties: { broker_url: { type: 'string', maxLength: 2048 } }, required: ['broker_url'], additionalProperties: false } },
+  { name: 'broker_setup_status', description: 'Read public Psst setup/connection status. Does not create approval requests or disclose credentials/private files.',
+    input: { type: 'object', properties: {}, required: [], additionalProperties: false } },
+  { name: 'broker_cancel_setup', description: 'Pause this session\'s local pending Psst setup. Preserves the prior authorization and durable request; does not revoke credentials.',
+    input: { type: 'object', properties: {}, required: [], additionalProperties: false } },
+];
+
+/** One explicit URL flow per installation. Recovery is read/GET-only. The private
+ * pending record retains the exact native owner across plugin namespace reloads.
+ * Candidate attachment happens before the selection CAS, while the old session
+ * remains working; neither a model tool nor background polling confirms replacement.
+ */
+export function createNativeSetup({ storage, verify, connect, activate, status, signal, directory = installationDirectory(),
+  loadHelper = loadApprovalHelper, select = selectInstallation, pollMs = 2000 }) {
+  if (!Number.isSafeInteger(pollMs) || pollMs < 10) throw new Error('setup_interval_invalid');
+  const scope = createToolScope(), lifetime = new AbortController();
+  let running, owner, blockedFlow, ownerController = new AbortController(), beginning = false, beginningController, beginningSessionID, last = { state: 'setup_needed' }, stopped = false;
+  const alive = () => !stopped && !signal.aborted && !lifetime.signal.aborted;
+  const binding = info => canonical({ id: info.id, projectID: info.projectID, location: info.location, created: info.time.created });
+  const bound = async id => {
+    if (!alive()) return false;
+    const info = await verify(id);
+    return !!info && (!owner?.binding || owner.sessionID !== id || binding(info) === owner.binding);
+  };
+  const savedOwner = async pending => pending?.owner ? { ...pending.owner, flowId: pending.flowId } : await storage.get('psst-v2-setup-owner');
+  async function pauseOwned() {
+    if (owner) updatePending({ directory, flowId: owner.flowId, paused: true });
+  }
+  function block(pending) {
+    blockedFlow = pending.flowId;
+    // Keep the in-memory fence even when storage itself is the fatal failure.
+    try { updatePending({ directory, flowId: pending.flowId, paused: true }); } catch {}
+    last = { ...last, state: 'setup_blocked' };
+  }
+  function remember(result, pending) {
+    last = publicState(result);
+    if (pending?.paused && result?.state === 'pending') last = { ...last, state: 'paused', request_state: 'pending' };
+    if (pending?.paused && result?.state === 'approved' && readSelection(directory)?.connectionFile !== result.connectionFile)
+      last = { ...last, state: 'paused', request_state: 'approved' };
+    return last;
+  }
+  async function finish(result, pending, sessionID, operationSignal, flowController = ownerController) {
+    if (!await bound(sessionID) || flowController.signal.aborted) return;
+    if (operationSignal?.aborted) { await pauseOwned(); return; }
+    const current = readPending(directory);
+    if (!current || current.paused || current.flowId !== pending.flowId) return;
+    if (result.requestId !== pending.requestId) throw new Error('approval_request_mismatch');
+    remember(result, current);
+    if (result.state === 'approved') {
+      const activationSignal = AbortSignal.any([signal, lifetime.signal, flowController.signal, ...(operationSignal ? [operationSignal] : [])]);
+      const commit = () => select({ directory, connectionFile: result.connectionFile, expectedRevision: pending.expectedRevision,
+        pendingFlowId: pending.flowId, verify: () => bound(sessionID), signal: activationSignal });
+      try {
+        if (activate) await activate({ sessionID, connectionFile: result.connectionFile, commit, signal: activationSignal });
+        else { await commit(); if (!activationSignal.aborted && await bound(sessionID)) await connect(sessionID); }
+      } finally { if (activationSignal.aborted) await pauseOwned(); }
+    } else if (result.state !== 'pending') updatePending({ directory, flowId: pending.flowId, paused: true });
+  }
+  function watch(pending, sessionID) {
+    if (running) return;
+    const flowController = ownerController;
+    const task = (async () => {
+      const helper = await loadHelper();
+      while (!flowController.signal.aborted && await bound(sessionID)) {
+        const current = readPending(directory);
+        if (!current || current.flowId !== pending.flowId || current.paused) return;
+        let waitMs = pollMs;
+        try {
+          const result = await helper.pollApproval({ directory, brokerUrl: current.brokerUrl, clientType: 'opencode' });
+          if (flowController.signal.aborted || !await bound(sessionID)) return;
+          await finish(result, current, sessionID, undefined, flowController);
+          if (result.state !== 'pending') return;
+        } catch (error) {
+          if (flowController.signal.aborted) return;
+          if (!error.retryable) { block(pending); return; }
+          waitMs = Math.min(300000, Math.max(pollMs, error.retryAfterMs || pollMs));
+        }
+        await delay(waitMs, undefined, { signal: AbortSignal.any([signal, lifetime.signal, flowController.signal]) }).catch(() => {});
+      }
+    })().catch(() => { if (!flowController.signal.aborted) block(pending); }).finally(() => { if (running === task) running = null; });
+    running = task;
+  }
+  function origin(value) {
+    const url = new URL(value);
+    if (typeof value !== 'string' || value.length > 2048 || /[\x00-\x20\x7f]/.test(value)
+      || url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('https_origin_required');
+    return url;
+  }
+  function requiresReplacement(previous, pending, url) {
+    return !!previous && previous.state !== 'pending' && !(previous.state === 'approved'
+      && pending?.brokerUrl === url && pending.requestId === previous.requestId
+      && readSelection(directory)?.connectionFile !== previous.connectionFile);
+  }
+  async function invoke(name, args, context) {
+    return scope.run(async operationSignal => {
+      if (!(context?.signal instanceof AbortSignal) || context.signal.aborted || !await bound(context.sessionID)) throw new Error('session_mismatch');
+      if (name === 'broker_cancel_setup') {
+        if (beginningSessionID === context.sessionID) { beginningController.abort(); last = { ...last, state: 'paused' }; }
+        if (owner?.sessionID === context.sessionID) { ownerController.abort(); await pauseOwned(); last = { ...last, state: 'paused' }; }
+        return { ...last, ...status(context.sessionID) };
+      }
+      if (name === 'broker_setup_status') {
+        if (args?.broker_url !== undefined) {
+          const url = origin(args.broker_url).href, helper = await loadHelper();
+          const previous = helper.readApprovalState({ directory, brokerUrl: url, clientType: 'opencode' });
+          return { ...publicState(previous), ...status(context.sessionID),
+            replacement_confirmation_required: requiresReplacement(previous, readPending(directory), url) };
+        }
+        return { ...last, ...status(context.sessionID) };
+      }
+      if (name !== 'broker_setup' || !args || Object.keys(args).join(',') !== 'broker_url') throw new Error('invalid_configuration');
+      const url = origin(args.broker_url);
+      const ownedPending = readPending(directory);
+      if (beginning || running || owner && owner.sessionID !== context.sessionID && ownedPending?.flowId === owner.flowId && !ownedPending.paused) throw new Error('setup_owner_conflict');
+      beginning = true; beginningController = new AbortController(); beginningSessionID = context.sessionID;
+      const beginController = beginningController;
+      try { return await withNativeLock(directory, 'setup', async () => {
+        const activePending = readPending(directory), priorOwner = await savedOwner(activePending);
+        if (activePending && (!priorOwner || priorOwner.flowId !== activePending.flowId)) { last = { state: 'setup_owner_recovery_required' }; throw new Error('setup_owner_recovery_required'); }
+        if (activePending && !activePending.paused && priorOwner?.sessionID !== context.sessionID) throw new Error('setup_owner_conflict');
+        const info = await verify(context.sessionID);
+        if (!info || priorOwner?.sessionID === context.sessionID && priorOwner.binding !== binding(info)) throw new Error('session_mismatch');
+        const helper = await loadHelper(), options = { directory, brokerUrl: url.href, clientType: 'opencode' };
+        const previous = helper.readApprovalState(options), selected = readSelection(directory);
+        // An approved but uncommitted candidate is resumed, never replaced. This
+        // also reconciles a crash after private receipt write or failed attachment.
+        const resumeApproved = previous?.state === 'approved' && activePending?.brokerUrl === url.href
+          && activePending.requestId === previous.requestId && selected?.connectionFile !== previous.connectionFile;
+        const replace = previous && previous.state !== 'pending' && !resumeApproved;
+        if (replace && (context.confirmedReplacement !== true || context.replacementRequestId !== previous.requestId)) return { ...publicState(previous), ...status(context.sessionID), replacement_confirmation_required: true };
+        if (beginController.signal.aborted || operationSignal.aborted) throw new Error('setup_cancelled');
+        const sameRequest = !replace && previous?.requestId && activePending?.brokerUrl === url.href && activePending.requestId === previous.requestId;
+        const pending = savePending({ directory, brokerUrl: url.href, expectedRevision: sameRequest ? activePending.expectedRevision : selected?.revision ?? null,
+          requestId: replace ? null : previous?.requestId ?? null, previousRequestId: replace ? previous.requestId : undefined, owner: { sessionID: context.sessionID, binding: binding(info) } });
+        owner = { ...pending.owner, flowId: pending.flowId }; ownerController = new AbortController();
+        const flowController = ownerController;
+        const cancelled = () => operationSignal.aborted || beginController.signal.aborted || flowController.signal.aborted
+          || readPending(directory)?.flowId !== pending.flowId || readPending(directory)?.paused;
+        await storage.set('psst-v2-setup-owner', owner);
+        if (!await bound(context.sessionID) || cancelled()) { await pauseOwned(); throw new Error('setup_cancelled'); }
+        let result;
+        try { result = await helper.beginApproval({ ...options, ...(replace ? { replaceRequestId: previous.requestId } : {}) }); }
+        catch (error) {
+          const saved = helper.readApprovalState(options);
+          if (saved?.requestId) {
+            updatePending({ directory, flowId: pending.flowId, requestId: saved.requestId }); remember(saved);
+            if (error.retryable && await bound(context.sessionID) && !cancelled()) watch({ ...pending, requestId: saved.requestId }, context.sessionID);
+            else if (!error.retryable || !await bound(context.sessionID) || cancelled()) await pauseOwned();
+          }
+          throw error;
+        }
+        if (!replace && previous?.requestId && result.requestId !== previous.requestId) throw new Error('approval_request_mismatch');
+        updatePending({ directory, flowId: pending.flowId, requestId: result.requestId });
+        const current = { ...pending, requestId: result.requestId };
+        if (!await bound(context.sessionID) || cancelled()) { await pauseOwned(); return { state: 'paused', request_id: result.requestId }; }
+        try { await finish(result, current, context.sessionID, operationSignal, flowController); }
+        catch (error) { if (!error.retryable) block(current); throw error; }
+        if (result.state === 'pending') watch(current, context.sessionID);
+        return { ...publicState(result), ...status(context.sessionID) };
+      }); } finally { beginning = false; beginningController = undefined; beginningSessionID = undefined; }
+    }, context?.signal);
+  }
+  async function resume() {
+    if (!alive() || beginning || running) return;
+    try {
+      let pending = readPending(directory);
+      if (!pending || pending.flowId === blockedFlow) return;
+      const saved = await savedOwner(pending);
+      if (!saved || typeof saved.sessionID !== 'string' || saved.flowId !== pending.flowId) { last = { state: 'setup_owner_recovery_required' }; return; }
+      if (owner?.flowId !== saved.flowId) ownerController = new AbortController();
+      owner = saved;
+      const helper = await loadHelper();
+      const result = helper.readApprovalState({ directory, brokerUrl: pending.brokerUrl, clientType: 'opencode' });
+      if (result && pending.requestId && result.requestId !== pending.requestId) { last = { state: 'setup_owner_recovery_required' }; return; }
+      if (!pending.requestId) {
+        if (result?.requestId && result.requestId !== pending.previousRequestId) {
+          updatePending({ directory, flowId: pending.flowId, requestId: result.requestId });
+          pending = { ...pending, requestId: result.requestId };
+        } else {
+          // A crash before helper candidate persistence is not permission for a
+          // startup POST, nor to select the prior approval as the new candidate.
+          updatePending({ directory, flowId: pending.flowId, paused: true });
+          last = { ...publicState(result), state: 'paused' }; return;
+        }
+      }
+      remember(result ?? { state: 'pending', requestId: pending.requestId }, pending);
+      if (!pending.paused && pending.requestId && await bound(saved.sessionID)) watch(pending, saved.sessionID);
+    } catch { last = { state: 'setup_blocked' }; throw new Error('setup_recovery_blocked'); }
+  }
+  return { invoke, resume, event(event) {
+    if (owner?.sessionID === event?.data?.sessionID && ['session.deleted', 'session.archived', 'session.moved'].includes(event.type)) {
+      ownerController.abort(); void pauseOwned().catch(() => {});
+    }
+  }, async stop() { stopped = true; lifetime.abort(); await scope.close(); await running; } };
+}