@ours.network/codex 1.1.1 → 1.2.0-nightly.1

package/src/hooks/runner.mjs

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { sendControlCommand } from '../control-server.mjs';
 import { resolveDaemonProfile } from '../profile.mjs';
+import { createHostSessionFactory } from '../network-proxy.mjs';
+import { attachOursClient } from '@ours.network/sdk';
+import { hostProfileFromEnv } from '../../../core/src/host-client/index.ts';
 
 async function defaultFindPin(cwd) {
   let dir = resolve(cwd || process.cwd());
@@ -31,11 +35,13 @@ const safeUnread = (value) => (Array.isArray(value?.identities) ? value.identiti
   return [{ name: entry.name, count, files, recent }];
 });
 
-async function applicationIdentityNames(env, stateDir) {
+async function applicationIdentityNames(env, selection) {
   const path = env.OURS_MCP_CONFIG || join(homedir(), '.ours-mcp', 'config.json');
   const value = JSON.parse(await readFile(path, 'utf8'));
   if (value?.version !== 1 || !value.daemons || typeof value.daemons !== 'object') return new Set();
-  const identities = value.daemons[resolve(stateDir)]?.identities;
+  const identities = selection.instanceId
+    ? value.instances?.[selection.instanceId]?.identities
+    : value.daemons[resolve(selection.stateDir)]?.identities;
   return new Set(Array.isArray(identities) ? identities.filter((name) => typeof name === 'string') : []);
 }
 
@@ -54,7 +60,16 @@ function renderContext(unread, pin) {
   return lines.join('\n');
 }
 
-export async function handleHook(payload, { env = process.env, fetch: fetchImpl = globalThis.fetch, send = sendControlCommand, findPin = defaultFindPin } = {}) {
+function applicationIdentitiesFromResource(value) {
+  const text = value?.contents?.find((item) => item?.uri === 'ours://application-identities')?.text;
+  const parsed = JSON.parse(text);
+  if (!Array.isArray(parsed?.identities) || parsed.identities.some((name) => typeof name !== 'string')) {
+    throw new Error('invalid application identity resource');
+  }
+  return new Set(parsed.identities);
+}
+
+export async function handleHook(payload, { env = process.env, fetch: fetchImpl = globalThis.fetch, send = sendControlCommand, findPin = defaultFindPin, profileResolver = resolveDaemonProfile, clientFactory = attachOursClient, networkSessionFactory = createHostSessionFactory } = {}) {
   try {
     const event = payload?.hook_event_name;
     const socket = env.OURS_CODEX_CONTROL_SOCKET;
@@ -75,21 +90,53 @@ export async function handleHook(payload, { env = process.env, fetch: fetchImpl
     let port = env.OURS_PORT || '3050';
     let selectedStateDir = resolve(env.OURS_STATE_DIR || join(homedir(), '.ours'));
     let selectedToken = env.OURS_API_TOKEN || '';
+    let hostProfile;
+    try { hostProfile = hostProfileFromEnv(env); }
+    catch { return { continue: true }; }
+    if (hostProfile) {
+      const nativeSessionId = payload.session_id;
+      if (typeof nativeSessionId !== 'string' || !nativeSessionId) return { continue: true };
+      const appPath = env.OURS_MCP_CONFIG || join(env.HOME || homedir(), '.ours-mcp', 'config.json');
+      let session;
+      try {
+        const factory = networkSessionFactory({ profile: hostProfile, hostRecordRoot: dirname(appPath), send: async () => {} });
+        session = await factory(nativeSessionId);
+        const resource = await session.request({ method: 'resources/read', params: { uri: 'ours://application-identities' } });
+        const visible = applicationIdentitiesFromResource(resource);
+        const unread = safeUnread(await session.fileClient.unread()).filter((entry) => visible.has(entry.name));
+        const pin = await findPin(payload.cwd || process.cwd());
+        const context = renderContext(unread, pin);
+        return context ? { continue: true, hookSpecificOutput: { hookEventName: event, additionalContext: context } } : { continue: true };
+      } finally { await session?.close(); }
+    }
     // Standard Codex does not pass through ours-codex's resolved environment.
     // Resolve the same coherent SDK selection here so SessionStart and
     // UserPromptSubmit inspect the same daemon as the stdio proxy.
     try {
-      const selected = await resolveDaemonProfile({ env, fetch: fetchImpl });
+      const selected = await profileResolver({ env, fetch: fetchImpl });
+      if (selected.profile) {
+        let client;
+        try {
+          client = await clientFactory({ ...selected.profile, sessionMode: 'external', leaseToken: `codex-hook-${process.pid}`, env: {} });
+          const visible = await applicationIdentityNames(env, { instanceId: selected.profile.expectedInstanceId });
+          const unread = safeUnread(await client.unread()).filter((entry) => visible.has(entry.name));
+          const pin = await findPin(payload.cwd || process.cwd());
+          const context = renderContext(unread, pin);
+          return context ? { continue: true, hookSpecificOutput: { hookEventName: event, additionalContext: context } } : { continue: true };
+        } finally { await client?.close(); }
+      }
       port = String(selected.port);
       selectedToken = selected.token || '';
       selectedStateDir = resolve(selected.stateDir);
-    } catch { /* proxy/launcher owns diagnostics; hooks emit a benign no-op */ }
+    } catch {
+      /* proxy/launcher owns legacy diagnostics; hooks emit a benign no-op */
+    }
     const headers = selectedToken ? { 'x-ours-api-token': selectedToken } : {};
     let unread = [];
     try {
       const response = await fetchImpl(`http://127.0.0.1:${port}/unread`, { headers, signal: AbortSignal.timeout(1500) });
       if (response.ok) {
-        const visible = await applicationIdentityNames(env, selectedStateDir);
+        const visible = await applicationIdentityNames(env, { stateDir: selectedStateDir });
         unread = safeUnread(await response.json()).filter((entry) => visible.has(entry.name));
       }
     } catch { /* daemon diagnostics belong to launcher/proxy */ }
@@ -102,7 +149,7 @@ export async function handleHook(payload, { env = process.env, fetch: fetchImpl
 
 async function main() {
   let payload = {};
-  try { payload = JSON.parse(await readFile(0, 'utf8')); } catch { /* noop */ }
+  try { payload = JSON.parse(readFileSync(0, 'utf8')); } catch { /* noop */ }
   process.stdout.write(JSON.stringify(await handleHook(payload)));
 }
 

package/src/launcher.mjs

@@ -6,7 +6,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
 import { once } from 'node:events';
-import { resolveDaemonProfile } from './profile.mjs';
+import { resolveDaemonProfile } from '../dist/profile.mjs';
 import { connectAppServer } from './app-server-client.mjs';
 import { AtomicStateStore, ControlServer } from './control-server.mjs';
 import { MonitorWatcher } from './watcher.mjs';
@@ -23,19 +23,23 @@ export const remoteTuiArgs = (url, codexArgs) => ['--remote', url, ...codexArgs]
 export function launcherEnvironment(env, profile, control) {
   const out = {
     ...env,
-    OURS_PORT: String(profile.port),
     OURS_CONFIG: profile.configPath,
-    OURS_AUTOSTART: '0',
     OURS_CODEX_CONTROL_SOCKET: control.socketPath,
     OURS_CODEX_CAPABILITY: control.capability,
     OURS_CODEX_LIVE: '1',
     // One stable owner pid for the MCP proxy, hooks, and launcher's own cleanup
     // call. The bin shim preserves an explicit value instead of replacing it
     // with whichever child happened to spawn it.
-    OURS_CLIENT_PID: String(process.pid),
   };
-  if (profile.token) out.OURS_API_TOKEN = profile.token;
-  else delete out.OURS_API_TOKEN;
+  if (profile.profile) {
+    for (const key of ['OURS_PORT', 'OURS_API_TOKEN', 'OURS_STATE_DIR', 'OURS_CLIENT_PID', 'OURS_AUTOSTART', 'OURS_DAEMON_ID']) delete out[key];
+  } else {
+    out.OURS_PORT = String(profile.port);
+    out.OURS_AUTOSTART = '0';
+    out.OURS_CLIENT_PID = String(process.pid);
+    if (profile.token) out.OURS_API_TOKEN = profile.token;
+    else delete out.OURS_API_TOKEN;
+  }
   return out;
 }
 
@@ -53,6 +57,12 @@ export function sessionRegistrationFromNotification(message, cwd) {
     : null;
 }
 
+export function sessionEndPayload(profile, state) {
+  return profile.profile && typeof state?.threadId === 'string' && state.threadId
+    ? `${JSON.stringify({ session_id: state.threadId })}\n`
+    : null;
+}
+
 async function freePort() {
   const server = createServer();
   await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
@@ -75,6 +85,16 @@ function waitExit(child) {
   return once(child, 'exit').then(([code, signal]) => ({ code, signal }));
 }
 
+function waitCleanupExit(child) {
+  if (child.exitCode != null || child.signalCode != null) return Promise.resolve({ kind: 'exit', code: child.exitCode, signal: child.signalCode });
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (outcome) => { if (!settled) { settled = true; resolve(outcome); } };
+    child.once('error', (error) => finish({ kind: 'error', error }));
+    child.once('exit', (code, signal) => finish({ kind: 'exit', code, signal }));
+  });
+}
+
 export async function runLauncher({
   argv = process.argv.slice(2), env = process.env, platform = process.platform,
   spawn = nodeSpawn, fetch: fetchImpl = globalThis.fetch,
@@ -96,23 +116,37 @@ export async function runLauncher({
   let watcher;
   const sessionEndShim = join(dirname(dirname(fileURLToPath(import.meta.url))), 'bin', 'proxy.mjs');
   const cleanup = async () => {
-    watcher?.stop();
+    await watcher?.stop();
+    const retainedState = control?.state;
     await control?.close().catch(() => {});
     client?.close();
     // The TUI exit is an authoritative normal session end. Run the same lease
     // DELETE seam as the native hook while the shared daemon is still reachable;
     // duplicate hook+launcher cleanup is intentionally idempotent.
+    const input = sessionEndPayload(profile, retainedState);
+    if (profile.profile && input === null) {
+      if (tui && tui.exitCode == null) tui.kill('SIGTERM');
+      if (appServer && appServer.exitCode == null) appServer.kill('SIGTERM');
+      await rm(runtimeDir, { recursive: true, force: true });
+      return;
+    }
     const end = spawn(process.execPath, [sessionEndShim, 'session-end'], {
       env: processEnvs.appServer,
-      stdio: 'ignore',
+      stdio: input === null ? 'ignore' : ['pipe', 'ignore', 'inherit'],
     });
-    end.once('error', () => {});
+    if (input !== null) end.stdin?.end(input);
     let cleanupDeadline;
-    await Promise.race([
-      waitExit(end),
-      new Promise((resolve) => { cleanupDeadline = setTimeout(resolve, 30_000); }),
-    ]).catch(() => {}).finally(() => clearTimeout(cleanupDeadline));
-    if (end.exitCode == null) end.kill('SIGTERM');
+    const cleanupOutcome = await Promise.race([
+      waitCleanupExit(end),
+      new Promise((resolve) => { cleanupDeadline = setTimeout(() => resolve({ kind: 'timeout' }), 30_000); }),
+    ]).finally(() => clearTimeout(cleanupDeadline));
+    if (end.exitCode == null && end.signalCode == null) end.kill('SIGTERM');
+    let cleanupFailure;
+    if (cleanupOutcome.kind === 'error') cleanupFailure = `spawn error: ${cleanupOutcome.error.message}`;
+    else if (cleanupOutcome.kind === 'timeout') cleanupFailure = 'timed out';
+    else if (cleanupOutcome.signal) cleanupFailure = `signal ${cleanupOutcome.signal}`;
+    else if ((cleanupOutcome.code ?? 0) !== 0) cleanupFailure = `exit ${cleanupOutcome.code}`;
+    if (cleanupFailure) process.stderr.write(`ours: SessionEnd cleanup failed: ${cleanupFailure}\n`);
     if (tui && tui.exitCode == null) tui.kill('SIGTERM');
     if (appServer && appServer.exitCode == null) appServer.kill('SIGTERM');
     await rm(runtimeDir, { recursive: true, force: true });
@@ -129,7 +163,7 @@ export async function runLauncher({
       throw new Error(`ours monitor cannot answer ${message.method}`);
     });
     watcher = new MonitorWatcher({
-      baseUrl: profile.baseUrl, token: profile.token, fetch: fetchImpl, appServer: client,
+      baseUrl: profile.baseUrl, token: profile.token, profile: profile.profile, fetch: fetchImpl, appServer: client,
       stateStore: new AtomicStateStore(join(runtimeDir, 'cursor.json')),
     });
     control = new ControlServer({

package/src/monitor-mcp.mjs

@@ -2,10 +2,13 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
+import { hostProfileFromEnv } from '../../core/src/host-client/index.ts';
 import { sendControlCommand } from './control-server.mjs';
 
 const require = createRequire(import.meta.url);
+const networkWatchPath = fileURLToPath(new URL('../bin/network-watch.mjs', import.meta.url));
 export const monitorToolNames = ['arm_monitor', 'foreground_monitor', 'disarm_monitor', 'monitor_status'];
 const content = (text, isError = false) => ({ content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) });
 
@@ -20,7 +23,16 @@ const foregroundOffer = (identity) =>
   `Only after an explicit yes, call get_messages once to drain existing unread mail, then ` +
   `call foreground_monitor({ identity: ${JSON.stringify(identity)} }).`;
 
-export function foregroundWatchProcess(identity) {
+export function foregroundWatchProcess(identity, nativeSessionId, env = process.env) {
+  if (hostProfileFromEnv(env)) {
+    if (typeof nativeSessionId !== 'string' || !nativeSessionId.trim()) {
+      throw new Error('Native session metadata is required for host-profile monitoring.');
+    }
+    return {
+      command: process.execPath,
+      args: [networkWatchPath, identity, nativeSessionId],
+    };
+  }
   try {
     const cliPath = require.resolve('@ours.network/mcp/dist/cli.js');
     return { command: process.execPath, args: [cliPath, 'watch', identity] };
@@ -48,7 +60,7 @@ export async function handleMonitorCommand(command, args = {}, { env = process.e
     : `Live ours monitor is available but not armed${state.boundIdentity ? `; current binding is "${state.boundIdentity}"` : '; bind an identity first'}.` };
 }
 
-export function waitForForegroundMail(identity, {
+export function waitForForegroundMail(identity, nativeSessionId, {
   env = process.env,
   spawnImpl = spawn,
   signal,
@@ -57,16 +69,17 @@ export function waitForForegroundMail(identity, {
   if (typeof identity !== 'string' || !identity.trim()) return Promise.reject(new Error('identity is required'));
 
   return new Promise((resolve, reject) => {
-    const invocation = commandFor(identity);
+    const invocation = commandFor(identity, nativeSessionId, env);
     const child = spawnImpl(invocation.command, invocation.args, {
-      env,
-      stdio: ['ignore', 'pipe', 'pipe'],
+      env: invocation.env ?? env,
+      stdio: [invocation.stdin ?? 'ignore', 'pipe', 'pipe'],
     });
     let stdout = '';
     let stderr = '';
     let settled = false;
 
     const stop = () => {
+      if (invocation.stdin === 'pipe') child.stdin?.end();
       if (!child.killed) child.kill('SIGTERM');
     };
     const finish = (fn, value) => {
@@ -109,7 +122,7 @@ export function createMonitorMcpServer(deps = {}) {
     identity: z.string().min(1).describe('The already-bound ours identity to monitor.'),
   }, async ({ identity }, extra) => {
     try {
-      const event = await waitForForegroundMail(identity, { ...deps, signal: extra?.signal });
+      const event = await waitForForegroundMail(identity, extra?._meta?.threadId, { ...deps, signal: extra?.signal });
       return content(`Foreground ours monitor received a body-free arrival event: ${event}\nCall get_messages now. After handling the mail, call foreground_monitor again without asking if monitoring should remain armed.`);
     } catch (error) {
       if (extra?.signal?.aborted) return content('Foreground ours monitor stopped. It is no longer armed.');

package/src/network-proxy.mjs

@@ -0,0 +1,308 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport, StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ErrorCode, McpError, ResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+  completeHostFileCall,
+  endNativeSessionAtRoot,
+  hostProfileFromEnv,
+  nativeClientForAtRoot,
+  nativeSessionRecordPath,
+  prepareHostFileCall,
+} from '../../core/src/host-client/index.ts';
+
+class NetworkTransportError extends Error {
+  constructor(cause) {
+    super(`Network transport failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    this.name = 'NetworkTransportError';
+  }
+}
+
+function isMcpSessionLoss(error) {
+  return error instanceof NetworkTransportError
+    || error instanceof StreamableHTTPError
+    || (error instanceof McpError && error.code === ErrorCode.ConnectionClosed);
+}
+
+function threadSelector(frame) {
+  const value = frame?.params?._meta?.threadId;
+  if (typeof value !== 'string' || !value || value.trim() !== value) {
+    throw new Error('Native session metadata is missing or invalid for this host-profile tool call.');
+  }
+  return value;
+}
+
+function defaultSessionSelector(frame) {
+  return frame.method === 'tools/call' ? threadSelector(frame) : '__discovery__';
+}
+
+export function createNetworkBridge({ sessionFactory, send, selectorFor = defaultSessionSelector }) {
+  const sessions = new Map();
+  const inFlight = new Map();
+  const sessionFor = async (selector) => {
+    let promise = sessions.get(selector);
+    if (!promise) {
+      promise = Promise.resolve(sessionFactory(selector, {
+        onClose: () => { if (sessions.get(selector) === promise) sessions.delete(selector); },
+      }));
+      sessions.set(selector, promise);
+      promise.catch(() => { if (sessions.get(selector) === promise) sessions.delete(selector); });
+    }
+    return promise;
+  };
+  const evictSession = async (selector, session) => {
+    const cached = sessions.get(selector);
+    if (cached && await cached.catch(() => undefined) === session && sessions.get(selector) === cached) {
+      sessions.delete(selector);
+    }
+    await session.close().catch(() => {});
+  };
+  const reply = (id, value, error = false) => send(error
+    ? { jsonrpc: '2.0', id, error: { code: -32000, message: value instanceof Error ? value.message : String(value) } }
+    : { jsonrpc: '2.0', id, result: value });
+  const handle = async (frame) => {
+    if (!frame || typeof frame !== 'object' || Array.isArray(frame)) return;
+    if (frame.method === 'notifications/initialized') return;
+    if (frame.method === 'notifications/cancelled') {
+      inFlight.get(frame.params?.requestId)?.abort(frame.params?.reason);
+      return;
+    }
+    if (frame.id === undefined || frame.id === null) {
+      const session = await sessionFor(selectorFor(frame));
+      await session.notification(frame);
+      return;
+    }
+    const controller = new AbortController();
+    inFlight.set(frame.id, controller);
+    try {
+      const selector = selectorFor(frame);
+      const session = await sessionFor(selector);
+      controller.signal.throwIfAborted();
+      if (frame.method === 'initialize') {
+        await reply(frame.id, session.initializeResult);
+        return;
+      }
+      const requestFrame = frame.method === 'tools/call' && session.fileClient
+        ? await prepareHostFileCall(session.fileClient, frame, controller.signal)
+        : frame;
+      controller.signal.throwIfAborted();
+      let result;
+      try {
+        result = await session.request(
+          { method: requestFrame.method, params: requestFrame.params ?? {} },
+          { signal: controller.signal },
+        );
+      } catch (error) {
+        if (isMcpSessionLoss(error)) await evictSession(selector, session);
+        throw error;
+      }
+      controller.signal.throwIfAborted();
+      let response = { jsonrpc: '2.0', id: frame.id, result };
+      if (frame.method === 'tools/call' && session.fileClient) {
+        response = await completeHostFileCall(session.fileClient, frame, response, controller.signal);
+      }
+      controller.signal.throwIfAborted();
+      await send(response);
+    } catch (error) {
+      await reply(frame.id, error, true);
+    } finally {
+      if (inFlight.get(frame.id) === controller) inFlight.delete(frame.id);
+    }
+  };
+  const close = async () => {
+    for (const controller of inFlight.values()) controller.abort('stdio closed');
+    await Promise.allSettled([...sessions.values()].map(async (session) => (await session).close()));
+    sessions.clear();
+  };
+  return { handle, close };
+}
+
+export async function runNetworkProxy({
+  env = process.env,
+  input = process.stdin,
+  stdio = new StdioServerTransport(),
+  profile: profileValue,
+  hostRecordRoot: hostRecordRootValue,
+  sessionFactory: sessionFactoryValue,
+  selectorFor,
+  installSignalHandlers = true,
+} = {}) {
+  const profile = profileValue ?? hostProfileFromEnv(env);
+  if (!profile && !sessionFactoryValue) throw new Error('A selected host network profile is required.');
+  const configPath = env.OURS_MCP_CONFIG || join(env.HOME || homedir(), '.ours-mcp', 'config.json');
+  const hostRecordRoot = hostRecordRootValue ?? dirname(configPath);
+  const sessionFactory = sessionFactoryValue ?? createHostSessionFactory({
+    profile,
+    hostRecordRoot,
+    send: (frame) => stdio.send(frame),
+  });
+  const bridge = createNetworkBridge({ sessionFactory, send: (frame) => stdio.send(frame), selectorFor });
+  const tasks = new Set();
+  const accept = (raw) => {
+    const values = Array.isArray(raw) ? raw : [raw];
+    const task = Promise.all(values.map((frame) => bridge.handle(frame)))
+      .catch((error) => process.stderr.write(`ours: network proxy failed: ${error.message}\n`))
+      .finally(() => tasks.delete(task));
+    tasks.add(task);
+  };
+  stdio.onmessage = accept;
+  stdio.onerror = (error) => process.stderr.write(`ours: network stdio failed: ${error.message}\n`);
+  await stdio.start();
+
+  await new Promise((resolve) => {
+    let stopped = false;
+    const finish = () => {
+      if (stopped) return;
+      stopped = true;
+      input.off('end', finish);
+      input.off('close', finish);
+      if (installSignalHandlers) {
+        process.off('SIGINT', finish);
+        process.off('SIGTERM', finish);
+      }
+      resolve();
+    };
+    input.once('end', finish);
+    input.once('close', finish);
+    if (installSignalHandlers) {
+      process.once('SIGINT', finish);
+      process.once('SIGTERM', finish);
+    }
+  });
+  await bridge.close();
+  await Promise.allSettled([...tasks]);
+  await stdio.close();
+}
+export { hostProfileFromEnv };
+
+export function networkFetchForOwner(profile, ownerInstanceId, { fetchImpl = globalThis.fetch } = {}) {
+  return async (input, init = {}) => {
+    const token = readFileSync(profile.credentialPath, 'utf8').trim();
+    if (!token) throw new Error(`Credential file ${profile.credentialPath} is empty.`);
+    const headers = new Headers(init.headers);
+    headers.set('x-ours-api-token', token);
+    headers.set('x-ours-lease-token', ownerInstanceId);
+    headers.set('x-ours-session-mode', 'external');
+    try {
+      return await fetchImpl(input, { ...init, headers, redirect: 'error' });
+    } catch (error) {
+      throw new NetworkTransportError(error);
+    }
+  };
+}
+
+export async function createMcpNetworkSession({
+  profile,
+  ownerInstanceId,
+  fileClient,
+  onNotification,
+  onClose,
+  ClientClass = Client,
+  TransportClass = StreamableHTTPClientTransport,
+  resultSchema = ResultSchema,
+  clientInfo = { name: 'ours-codex', version: '2.0.0' },
+}) {
+  const client = new ClientClass(clientInfo);
+  client.fallbackNotificationHandler = async (notification) => onNotification?.(notification);
+  let invalidated = false;
+  let closing;
+  const evict = () => {
+    if (invalidated) return;
+    invalidated = true;
+    onClose?.();
+  };
+  const invalidate = async () => {
+    evict();
+    closing ??= Promise.resolve(client.close()).catch(() => {});
+    await closing;
+  };
+  client.onclose = evict;
+  client.onerror = (error) => { if (isMcpSessionLoss(error)) void invalidate(); };
+  const ownerHeaders = {
+    'x-ours-lease-token': ownerInstanceId,
+    'x-ours-session-mode': 'external',
+  };
+  const endpoint = new URL('/mcp', profile.endpoint);
+  const transport = new TransportClass(endpoint, {
+    fetch: networkFetchForOwner(profile, ownerInstanceId),
+    requestInit: { headers: ownerHeaders, redirect: 'error' },
+    reconnectionOptions: {
+      initialReconnectionDelay: 1000,
+      maxReconnectionDelay: 30_000,
+      reconnectionDelayGrowFactor: 1.5,
+      maxRetries: 5,
+    },
+  });
+  await client.connect(transport);
+  const instructions = client.getInstructions?.();
+  const initializeResult = {
+    protocolVersion: '2025-03-26',
+    capabilities: client.getServerCapabilities?.() ?? {},
+    serverInfo: client.getServerVersion?.() ?? { name: 'ours', version: 'unknown' },
+    ...(instructions ? { instructions } : {}),
+  };
+  return {
+    client,
+    fileClient,
+    initializeResult,
+    request: async (request, options) => {
+      try {
+        return await client.request(request, resultSchema, options);
+      } catch (error) {
+        if (isMcpSessionLoss(error)) await invalidate();
+        throw error;
+      }
+    },
+    notification: (notification) => client.notification(notification),
+    close: invalidate,
+  };
+}
+
+async function nativeOwnerForAtRoot(profile, nativeSessionId, hostRecordRoot) {
+  const path = nativeSessionRecordPath(hostRecordRoot, profile.expectedInstanceId, nativeSessionId);
+  const record = JSON.parse(readFileSync(path, 'utf8'));
+  if (record?.state !== 'active' || typeof record.ownerInstanceId !== 'string') {
+    throw new Error(`Native session record at ${path} is not active.`);
+  }
+  return record.ownerInstanceId;
+}
+
+export function createHostSessionFactory({
+  profile,
+  hostRecordRoot,
+  send,
+  nativeClientForImpl = nativeClientForAtRoot,
+  ownerForImpl = nativeOwnerForAtRoot,
+  createSessionImpl = createMcpNetworkSession,
+}) {
+  return async (selector, { onClose } = {}) => {
+    const discovery = selector === '__discovery__';
+    const fileClient = discovery
+      ? undefined
+      : await nativeClientForImpl(profile, selector, hostRecordRoot);
+    const ownerInstanceId = discovery
+      ? randomUUID()
+      : await ownerForImpl(profile, selector, hostRecordRoot);
+    return createSessionImpl({
+      profile,
+      ownerInstanceId,
+      fileClient,
+      onNotification: send,
+      onClose,
+    });
+  };
+}
+
+export async function endNetworkNativeSession({
+  profile,
+  nativeSessionId,
+  hostRecordRoot,
+  endImpl = endNativeSessionAtRoot,
+}) {
+  await endImpl(profile, nativeSessionId, hostRecordRoot);
+}

package/src/network-watch.mjs

@@ -0,0 +1,45 @@
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { hostProfileFromEnv, nativeClientForAtRoot } from '../../core/src/host-client/index.ts';
+
+export async function runNetworkWatch({
+  identity,
+  nativeSessionId,
+  env = process.env,
+  profile: profileValue,
+  hostRecordRoot: hostRecordRootValue,
+  clientFor = nativeClientForAtRoot,
+  write = (value) => process.stdout.write(value),
+  installSignalHandlers = true,
+} = {}) {
+  if (typeof identity !== 'string' || !identity.trim()) throw new Error('identity is required');
+  if (typeof nativeSessionId !== 'string' || !nativeSessionId.trim()) throw new Error('native session id is required');
+  const profile = profileValue ?? hostProfileFromEnv(env);
+  if (!profile) throw new Error('A selected host network profile is required.');
+  const appPath = env.OURS_MCP_CONFIG || join(env.HOME || homedir(), '.ours-mcp', 'config.json');
+  const hostRecordRoot = hostRecordRootValue ?? dirname(appPath);
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  if (installSignalHandlers) {
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+  }
+  let client;
+  try {
+    client = await clientFor(profile, nativeSessionId, hostRecordRoot);
+    for await (const event of client.watchNotifications(identity, { kinds: ['inbound'], signal: controller.signal })) {
+      const summary = event?.event === 'file_received'
+        ? `[${identity}] new file ${event.filename ?? '?'} from ${event.from ?? '?'}`
+        : `[${identity}] new message from ${event?.from ?? '?'}`;
+      write(`${summary}\n`);
+      return;
+    }
+  } finally {
+    if (installSignalHandlers) {
+      process.off('SIGINT', stop);
+      process.off('SIGTERM', stop);
+    }
+    await client?.close();
+  }
+}