@logicseek/hello-cc 1.0.1 → 1.0.2

package/lib/integrations/native/codex.mjs

@@ -0,0 +1,242 @@
+import { JsonRpcProcess } from './jsonrpc.mjs';
+import { createNativeInteractions } from './interactions.mjs';
+import { CODEX_INTERACTION_METHODS, codexInteractionKind, codexInteractionResponse, cancelCodexInteraction, codexInteractiveConfig } from '../codex-interactions.mjs';
+
+const CAPABILITIES = Object.freeze({ create: true, resume: true, send: true, observe: true,
+  steer: true, interrupt: true, close: true, fork: false });
+const TERMINAL_TURN_STATUSES = new Set(['completed', 'interrupted', 'failed']);
+
+function adapterError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+/** Owns a new app-server process; resume IDs must be ownership-checked by the HCC host. */
+export function createCodexAdapter(options = {}) {
+  const { binary = 'codex', cwd, env, timeoutMs = 30_000, onEvent = () => {},
+    rpcFactory = (config) => new JsonRpcProcess(config) } = options;
+  const state = { provider: 'codex', sessionId: null, turnId: null, status: 'new', owned: true };
+  const terminalTurns = new Set();
+  const interruptedTurns = new Set();
+  const turnSubmissions = new Map();
+  const finalMessages = new Map();
+  let rpc;
+  let closed = false;
+  let admission = Promise.resolve();
+  let pendingSubmissionId;
+  let closePromise;
+  const capabilities = { ...CAPABILITIES, approvals: Boolean(options.interactive), userInput: Boolean(options.interactive), mcp: Boolean(options.mcpServers) };
+  const interactions = createNativeInteractions({ executorId: options.executorId,
+    isActive: (sessionId, turnId) => !closed && sessionId === state.sessionId && turnId === state.turnId && !terminalTurns.has(turnId) && !interruptedTurns.has(turnId) && !['error', 'uncertain', 'closed'].includes(state.status),
+    onChange: emit });
+
+  function emit(event) {
+    // Consumer callbacks must not prevent a permission denial or corrupt protocol admission.
+    try {
+      const delivery = onEvent({ provider: 'codex', sessionId: state.sessionId, ...event });
+      delivery?.catch?.(() => {});
+    } catch {}
+  }
+
+  function status(value, details = {}) {
+    state.status = value;
+    emit({ type: 'status', status: value, turnId: state.turnId, ...details });
+  }
+
+  function requireOpen() {
+    if (closed || !rpc || !state.sessionId || ['new', 'opening', 'error', 'uncertain', 'closed'].includes(state.status)) {
+      throw adapterError('NATIVE_SESSION_NOT_OPEN', 'The Codex native session is not open.');
+    }
+  }
+
+  function serial(operation) {
+    const result = admission.then(operation);
+    admission = result.catch(() => {});
+    return result;
+  }
+
+  function notification(method, params = {}) {
+    if (closed || !state.sessionId || params.threadId !== state.sessionId) return;
+    const turnId = params.turn?.id ?? params.turnId;
+    const submissionId = turnSubmissions.get(turnId) ?? pendingSubmissionId;
+    if (method === 'turn/started' && turnId && !terminalTurns.has(turnId)) {
+      if (submissionId) turnSubmissions.set(turnId, submissionId);
+      state.turnId = turnId;
+      status('busy');
+    } else if (method === 'turn/completed' && turnId) {
+      if (terminalTurns.has(turnId)) return;
+      terminalTurns.add(turnId);
+      interruptedTurns.delete(turnId);
+      interactions.expire(turnId);
+      if (terminalTurns.size > 128) {
+        const oldest = terminalTurns.values().next().value;
+        terminalTurns.delete(oldest);
+        turnSubmissions.delete(oldest);
+        finalMessages.delete(oldest);
+      }
+      if (!state.turnId || state.turnId === turnId) {
+        state.turnId = null;
+        status('idle', { completedTurnId: turnId, turnStatus: params.turn?.status });
+      }
+      emit({ type: 'completed', status: params.turn?.status ?? 'completed', turnId, submissionId,
+        text: finalMessages.get(turnId) });
+      if (params.turn?.error) emit({ type: 'error', turnId, error: params.turn.error });
+    } else if (method === 'item/agentMessage/delta') {
+      emit({ type: 'delta', text: params.delta ?? '', turnId, submissionId, itemId: params.itemId });
+    } else if (method === 'item/completed' && params.item?.type === 'agentMessage') {
+      finalMessages.set(turnId, params.item.text ?? '');
+      emit({ type: 'message', text: params.item.text ?? '', turnId, submissionId, itemId: params.item.id });
+    } else if (['item/started', 'item/completed'].includes(method) && ['commandExecution', 'fileChange', 'mcpToolCall'].includes(params.item?.type)) {
+      emit({ type: 'item', phase: method.split('/')[1], item: params.item, turnId, submissionId });
+    } else if (method === 'turn/plan/updated') {
+      emit({ type: 'plan', plan: params.plan, explanation: params.explanation, turnId, submissionId });
+    } else if (method === 'turn/diff/updated') {
+      emit({ type: 'diff', diff: params.diff, turnId, submissionId });
+    } else if (method === 'error') {
+      emit({ type: 'error', turnId, error: params.error ?? params });
+    } else if (method === 'serverRequest/resolved') {
+      interactions.resolved(params.requestId);
+    } else if (method === 'thread/status/changed' && params.status?.type === 'systemError') {
+      interactions.expire();
+      status('error');
+    }
+  }
+
+  function serverRequest(method, params = {}, requestId) {
+    if (!CODEX_INTERACTION_METHODS.has(method)) throw adapterError('NATIVE_SERVER_REQUEST_UNSUPPORTED', `Unsupported Codex server request: ${method}`);
+    if (options.interactive && params.threadId === state.sessionId && params.turnId && !terminalTurns.has(params.turnId)) {
+      // A server request can precede the turn/start admission response.
+      if (!state.turnId && pendingSubmissionId) { state.turnId = params.turnId; status('busy'); }
+      return interactions.request({ requestId, sessionId: params.threadId, turnId: params.turnId,
+        kind: codexInteractionKind(method), method, params,
+        validate: codexInteractionResponse, cancelled: cancelCodexInteraction(method) });
+    }
+    if (method !== 'item/tool/requestUserInput') emit({ type: 'approval', method, turnId: params.turnId,
+      itemId: params.itemId, decision: 'decline', reason: params.reason ?? null });
+    return method === 'mcpServer/elicitation/request' ? { action: 'decline' }
+      : method === 'item/permissions/requestApproval' || method === 'item/tool/requestUserInput'
+        ? cancelCodexInteraction(method) : { decision: 'decline' };
+  }
+
+  function exited(details = {}) {
+    if (closed) return;
+    interactions.expire();
+    state.turnId = null;
+    status('error');
+    emit({ type: 'error', code: 'NATIVE_PROCESS_EXITED', text: 'The owned Codex app-server exited.',
+      exitCode: details?.code ?? null, signal: details?.signal ?? null });
+  }
+
+  function transportError(error) {
+    if (closed) return;
+    interactions.expire();
+    status('error');
+    emit({ type: 'error', code: error.code ?? 'NATIVE_TRANSPORT_ERROR', text: error.message,
+      turnId: state.turnId, extra: { ...error.extra } });
+  }
+
+  async function open({ sessionId, model } = {}) {
+    if (closed || state.status !== 'new') {
+      throw adapterError('NATIVE_SESSION_ALREADY_OPEN', 'This Codex adapter can open only one owned session.');
+    }
+    if (sessionId !== undefined && (typeof sessionId !== 'string' || !sessionId.trim())) {
+      throw adapterError('BAD_ARGS', 'A Codex resume sessionId must be a nonempty string.');
+    }
+    status('opening');
+    try {
+      rpc = rpcFactory({ binary, args: ['app-server', '--stdio'], cwd, env, timeoutMs,
+        onNotification: notification, onRequest: serverRequest, onExit: exited, onError: transportError });
+      await rpc.start();
+      if (closed) throw adapterError('NATIVE_SESSION_CLOSED', 'The Codex session was closed while opening.');
+      await rpc.request('initialize', { clientInfo: { name: 'hello_cc', version: '1.0.1' },
+        capabilities: { experimentalApi: Boolean(options.interactive) } });
+      if (closed) throw adapterError('NATIVE_SESSION_CLOSED', 'The Codex session was closed while opening.');
+      await rpc.notify('initialized', {});
+      if (closed) throw adapterError('NATIVE_SESSION_CLOSED', 'The Codex session was closed while opening.');
+      const config = codexInteractiveConfig(options.mcpServers ? { mcp_servers: options.mcpServers } : {}, Boolean(options.interactive));
+      const params = { sandbox: 'workspace-write', approvalPolicy: 'on-request', approvalsReviewer: 'user',
+        ...(Object.keys(config).length ? { config } : {}),
+        ...(cwd ? { cwd } : {}), ...(model ? { model } : {}), ...(sessionId ? { threadId: sessionId } : {}) };
+      const response = await rpc.request(sessionId ? 'thread/resume' : 'thread/start', params);
+      if (!response?.thread?.id || (sessionId && response.thread.id !== sessionId)) {
+        throw adapterError('NATIVE_PROTOCOL_ERROR', 'Codex returned an invalid native thread identity.');
+      }
+      if (closed) throw adapterError('NATIVE_SESSION_CLOSED', 'The Codex session was closed while opening.');
+      state.sessionId = response.thread.id;
+      const activeTurn = response.thread.turns?.findLast((turn) => turn.status === 'inProgress');
+      state.turnId = activeTurn?.id ?? null;
+      status(state.turnId ? 'busy' : 'idle');
+      return snapshot();
+    } catch (error) {
+      if (!closed) {
+        status('error');
+        emit({ type: 'error', code: error.code, text: error.message, extra: { ...error.extra } });
+      }
+      await rpc?.close();
+      throw error;
+    }
+  }
+
+  function send({ text, submissionId, expectedTurnId } = {}) {
+    return serial(async () => {
+      requireOpen();
+      if (typeof text !== 'string' || !text.trim()) throw adapterError('BAD_ARGS', 'A native message needs nonempty text.');
+      const turnId = state.turnId;
+      if (expectedTurnId !== undefined && expectedTurnId !== turnId) {
+        throw adapterError('NATIVE_TURN_MISMATCH', 'The expected Codex turn is no longer active.');
+      }
+      if (state.status === 'busy' && !turnId) {
+        throw adapterError('NATIVE_TURN_UNKNOWN', 'The active Codex turn identity is unavailable.');
+      }
+      const method = turnId ? 'turn/steer' : 'turn/start';
+      const params = { threadId: state.sessionId, input: [{ type: 'text', text }],
+        ...(submissionId ? { clientUserMessageId: submissionId } : {}),
+        ...(turnId ? { expectedTurnId: expectedTurnId ?? turnId } : {}) };
+      try {
+        pendingSubmissionId = submissionId;
+        const response = await rpc.request(method, params);
+        const acceptedTurnId = turnId ? response?.turnId : response?.turn?.id;
+        if (!acceptedTurnId || (turnId && acceptedTurnId !== turnId)) {
+          throw adapterError('NATIVE_PROTOCOL_ERROR', 'Codex returned an invalid turn admission.');
+        }
+        if (submissionId && !turnSubmissions.has(acceptedTurnId)) turnSubmissions.set(acceptedTurnId, submissionId);
+        if (!closed && !terminalTurns.has(acceptedTurnId)) {
+          const turnStatus = response?.turn?.status;
+          state.turnId = TERMINAL_TURN_STATUSES.has(turnStatus) ? null : acceptedTurnId;
+          status(state.turnId ? 'busy' : 'idle');
+        }
+        return { sessionId: state.sessionId, turnId: acceptedTurnId, status: 'accepted' };
+      } catch (error) {
+        if (!closed && error.code === 'NATIVE_REQUEST_TIMEOUT' && error.extra?.uncertain) status('uncertain');
+        emit({ type: 'error', code: error.code, text: error.message, turnId, extra: { ...error.extra } });
+        // A rejected steer is not retried as a new turn: that would remove its turn precondition.
+        throw error;
+      } finally {
+        pendingSubmissionId = undefined;
+      }
+    });
+  }
+
+  async function interrupt({ turnId = state.turnId } = {}) {
+    requireOpen();
+    if (!turnId) return { sessionId: state.sessionId, turnId: null, status: 'idle' };
+    if (turnId !== state.turnId) throw adapterError('NATIVE_TURN_MISMATCH', 'The requested Codex turn is no longer active.');
+    await rpc.request('turn/interrupt', { threadId: state.sessionId, turnId });
+    interruptedTurns.add(turnId);
+    interactions.expire(turnId, 'interrupted');
+    return { sessionId: state.sessionId, turnId, status: 'accepted' };
+  }
+
+  function close() {
+    if (closePromise) return closePromise;
+    closed = true;
+    interactions.expire();
+    state.turnId = null;
+    status('closed');
+    closePromise = Promise.resolve().then(() => rpc?.close()).then(() => snapshot());
+    return closePromise;
+  }
+
+  function snapshot() { return { ...state, executorId: interactions.executorId, capabilities: { ...capabilities }, pendingApprovals: interactions.snapshot() }; }
+
+  return { capabilities, open, send, interrupt, close, snapshot, respond: interactions.respond };
+}

package/lib/integrations/native/dsh-acp.mjs

@@ -0,0 +1,343 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { createNativeInteractions } from './interactions.mjs';
+import { JsonRpcProcess } from './jsonrpc.mjs';
+
+export const DSH_ACP_BASELINE_VERSION = '0.2.0-rc.2';
+
+// Contract verified against the official @deepseek-ai/dsh-acp baseline above.
+// ACP v1 uses session/prompt requests and session/cancel notifications. Resume
+// and close are advertised session extensions; resume restores the Agent, but
+// does not replay its transcript. turnId identifies this adapter's submission,
+// not a native ACP turn. Updates are committed semantic events, not raw tokens.
+// model, when supplied, is an advertised model configuration option value.
+// This adapter owns a dedicated dsh --profile acp process, never an existing
+// dsh Web service. Its close operation may dispose only that owned process.
+export function createDshAcpAdapter(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  if (!path.isAbsolute(cwd)) throw failure('NATIVE_BAD_CWD', 'ACP requires an absolute workspace directory');
+  const capabilities = {
+    create: true, resume: false, send: true, observe: true,
+    steer: false, interrupt: true, close: false, fork: false, approvals: Boolean(options.interactive), mcp: Boolean(options.mcpServers)
+  };
+  let rpc = null;
+  let sessionId = null;
+  let status = 'new';
+  let active = null;
+  let opening = null;
+  let openingIdentity = null;
+  let closing = null;
+  let runtimeDisposed = false;
+  let lastError = null;
+  const receipts = new Map();
+  const toolCalls = new Map(), toolContextWaiters = new Set();
+  const interactions = createNativeInteractions({ executorId: options.executorId,
+    isActive: (id, turnId) => !closing && !runtimeDisposed && id === sessionId && turnId === active?.turnId && !active?.interrupted, onChange: emit });
+
+  function emit(event) {
+    // A consumer failure must not break ACP parsing or turn a permission
+    // rejection into a transport failure.
+    try {
+      const delivery = options.onEvent?.({ provider: 'dsh', sessionId, ...event });
+      delivery?.catch?.(() => {});
+    } catch {}
+  }
+
+  function snapshot() {
+    return {
+      provider: 'dsh', transport: 'acp', protocolVersion: 1,
+      baselineVersion: DSH_ACP_BASELINE_VERSION,
+      cwd, sessionId, status,
+      turnId: active?.turnId || null,
+      submissionId: active?.submissionId || null,
+      capabilities: { ...capabilities }, executorId: interactions.executorId, pendingApprovals: interactions.snapshot(),
+      error: lastError ? { ...lastError } : null
+    };
+  }
+
+  function clearToolContext() {
+    toolCalls.clear();
+    for (const waiter of [...toolContextWaiters]) waiter.finish(null);
+  }
+
+  function rememberToolCall(update) {
+    if (!active || active.interrupted || !['tool_call', 'tool_call_update'].includes(update.sessionUpdate) ||
+        typeof update.toolCallId !== 'string' || !update.toolCallId || update.toolCallId.length > 256) return;
+    const detail = { ...(toolCalls.get(update.toolCallId) || {}), toolCallId: update.toolCallId };
+    for (const key of ['title', 'kind', 'rawInput', 'locations']) if (Object.hasOwn(update, key)) detail[key] = update[key];
+    if (Object.hasOwn(update, 'rawInput')) delete detail.contextTruncated;
+    const bounded = JSON.stringify(detail).length > 60000
+      ? { toolCallId: update.toolCallId, title: typeof detail.title === 'string' ? detail.title.slice(0, 1024) : undefined, contextTruncated: true }
+      : structuredClone(detail);
+    toolCalls.set(update.toolCallId, bounded);
+    if (toolCalls.size > 128) toolCalls.delete(toolCalls.keys().next().value);
+    if (Object.hasOwn(bounded, 'rawInput') || bounded.contextTruncated) {
+      for (const waiter of [...toolContextWaiters]) if (waiter.toolCallId === update.toolCallId) waiter.finish(bounded);
+    }
+  }
+
+  function waitForToolContext(toolCallId) {
+    if (toolContextWaiters.size >= 64) throw failure('NATIVE_PROTOCOL_ERROR', 'Excessive ACP permission context requests');
+    return new Promise(resolve => {
+      const waiter = { toolCallId, finish(detail) { clearTimeout(timer); toolContextWaiters.delete(waiter); resolve(detail); } };
+      const timer = setTimeout(() => waiter.finish(null), 1000);
+      toolContextWaiters.add(waiter);
+    });
+  }
+
+  function onNotification(method, params) {
+    if (closing || ['closed', 'failed', 'exited'].includes(status) || method !== 'session/update' || params?.sessionId !== sessionId) return;
+    const update = params.update;
+    if (!update || typeof update !== 'object') return;
+    rememberToolCall(update);
+    if (update.sessionUpdate === 'agent_message_chunk' && update.content?.type === 'text' && typeof update.content.text === 'string') {
+      if (active) active.text += update.content.text;
+      emit({ type: 'output', turnId: active?.turnId || null, submissionId: active?.submissionId || null, text: update.content.text });
+    }
+    emit({ type: 'session.update', turnId: active?.turnId || null, submissionId: active?.submissionId || null, update });
+  }
+
+  function onRequest(method, params, requestId) {
+    if (method !== 'session/request_permission') throw failure(-32601, `Unsupported ACP client request: ${method}`);
+    if (closing || params?.sessionId !== sessionId) return { outcome: { outcome: 'cancelled' } };
+    const choices = Array.isArray(params.options) ? params.options : [];
+    const reject = choices.find((option) => option?.kind === 'reject_once')
+      || choices.find((option) => option?.kind === 'reject_always');
+    if (options.interactive && active) {
+      const turn = active, toolCallId = params.toolCall?.toolCallId;
+      if (turn.interrupted) return { outcome: { outcome: 'cancelled' } };
+      const publish = detail => {
+        if (closing || active !== turn || turn.interrupted) return { outcome: { outcome: 'cancelled' } };
+        const toolCall = { ...detail, ...params.toolCall };
+        if (toolCallId && !Object.hasOwn(toolCall, 'rawInput') && !toolCall.contextTruncated) toolCall.contextPending = true;
+        return interactions.request({ requestId, sessionId, turnId: turn.turnId,
+          method, params: { toolCall, options: choices }, cancelled: { outcome: { outcome: 'cancelled' } },
+          validate: (request, response) => {
+            if (!['accept', 'decline', 'cancel'].includes(response.decision) || (request.truncated && response.decision === 'accept')) throw failure('INTERACTION_RESPONSE_INVALID', 'Invalid or truncated ACP permission');
+            if (response.decision === 'accept' && (request.params.toolCall?.contextPending || request.params.toolCall?.contextTruncated)) throw failure('NATIVE_APPROVAL_CONTEXT_MISSING', 'ACP tool input is missing or truncated; only rejection is available');
+            const selected = choices.find(option => option.kind === (response.decision === 'accept' ? 'allow_once' : 'reject_once'));
+            if (response.decision === 'accept' && !selected) throw failure('INTERACTION_RESPONSE_INVALID', 'ACP did not offer approval for this operation');
+            return response.decision === 'cancel' || !selected ? { outcome: { outcome: 'cancelled' } }
+              : { outcome: { outcome: 'selected', optionId: selected.optionId } };
+          } });
+      };
+      const detail = toolCalls.get(toolCallId);
+      if (toolCallId && !Object.hasOwn(params.toolCall, 'rawInput') && !Object.hasOwn(detail || {}, 'rawInput') && !detail?.contextTruncated) {
+        // rc.2 can ask with only an id before publishing the matching tool update.
+        return waitForToolContext(toolCallId).then(value => publish(value || detail));
+      }
+      return publish(detail);
+    }
+    emit({ type: 'permission', decision: 'reject', toolCall: params.toolCall });
+    return reject && typeof reject.optionId === 'string'
+      ? { outcome: { outcome: 'selected', optionId: reject.optionId } }
+      : { outcome: { outcome: 'cancelled' } };
+  }
+
+  function onExit(info) {
+    if (closing || runtimeDisposed || status === 'closed') return;
+    const turn = active;
+    interactions.expire();
+    clearToolContext();
+    active = null;
+    status = 'exited';
+    lastError = { code: 'NATIVE_RUNTIME_EXITED', message: 'The owned dsh ACP runtime exited', uncertain: Boolean(turn) };
+    emit({ type: 'error', status: 'unknown', turnId: turn?.turnId || null, submissionId: turn?.submissionId || null, error: lastError, exit: info });
+  }
+
+  function onTransportError(error) {
+    if (closing || status === 'closed') return;
+    const turn = active;
+    interactions.expire();
+    clearToolContext();
+    active = null;
+    status = 'failed';
+    lastError = { ...describe(error), uncertain: true };
+    emit({ type: 'error', status: 'unknown', turnId: turn?.turnId || null,
+      submissionId: turn?.submissionId || null, error: lastError });
+  }
+
+  async function open(input = {}) {
+    if (input.sessionId !== undefined && (typeof input.sessionId !== 'string' || !input.sessionId.trim())) {
+      throw failure('NATIVE_BAD_SESSION', 'Session identity must be a nonempty string');
+    }
+    if (closing || status === 'closed') throw failure('NATIVE_ADAPTER_CLOSED', 'The dsh ACP adapter is closed');
+    if (['failed', 'exited'].includes(status)) throw failure('NATIVE_NOT_OPEN', 'The dsh ACP runtime cannot be reused after a failed open');
+    if (sessionId) {
+      if (input.sessionId && input.sessionId !== sessionId) throw failure('NATIVE_SESSION_MISMATCH', 'This adapter already owns a different session');
+      return snapshot();
+    }
+    if (opening) {
+      if ((input.sessionId || null) !== openingIdentity) throw failure('NATIVE_SESSION_MISMATCH', 'This adapter is opening a different session');
+      return opening;
+    }
+    if (status !== 'new') throw failure('NATIVE_NOT_OPEN', 'The dsh ACP runtime cannot be reused after a failed open');
+    status = 'opening';
+    openingIdentity = input.sessionId || null;
+    opening = (async () => {
+      try {
+        const config = {
+          binary: options.binary || 'dsh', args: ['--profile', 'acp'],
+          cwd, env: options.env, timeoutMs: options.timeoutMs,
+          onNotification, onRequest, onExit, onError: onTransportError
+        };
+        rpc = options.rpcFactory ? options.rpcFactory(config) : new JsonRpcProcess(config);
+        await rpc.start();
+        const initialized = await rpc.request('initialize', {
+          protocolVersion: 1,
+          clientCapabilities: {},
+          clientInfo: { name: 'hello-cc', version: '1.0.1' }
+        });
+        if (initialized?.protocolVersion !== 1) throw failure('NATIVE_PROTOCOL_MISMATCH', 'The dsh runtime did not negotiate ACP v1');
+        const extensions = initialized.agentCapabilities?.sessionCapabilities || {};
+        capabilities.resume = extensions.resume !== undefined && extensions.resume !== null && extensions.resume !== false;
+        capabilities.close = extensions.close !== undefined && extensions.close !== null && extensions.close !== false;
+        if (input.sessionId && !capabilities.resume) throw failure('NATIVE_UNSUPPORTED', 'This ACP runtime does not advertise session resume');
+        const result = await rpc.request(input.sessionId ? 'session/resume' : 'session/new', {
+          ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+          cwd, mcpServers: Object.entries(options.mcpServers || {}).map(([name, config]) => ({ name, command: config.command, args: config.args,
+            env: Object.entries(config.env || {}).map(([name, value]) => ({ name, value })) }))
+        });
+        const resolvedId = input.sessionId || result?.sessionId;
+        if (typeof resolvedId !== 'string' || !resolvedId.trim() || (input.sessionId && result?.sessionId && result.sessionId !== input.sessionId)) {
+          throw failure('NATIVE_PROTOCOL_ERROR', 'ACP returned an invalid session identity');
+        }
+        sessionId = resolvedId;
+        if (input.model !== undefined) {
+          const model = result?.configOptions?.find((option) => option?.id === 'model');
+          if (!model || !advertisesValue(model.options, input.model)) throw failure('NATIVE_UNSUPPORTED_MODEL', 'Model must match an advertised ACP model option value');
+          await rpc.request('session/set_config_option', { sessionId, configId: 'model', value: input.model });
+        }
+        if (closing || status === 'exited') throw failure('NATIVE_ADAPTER_CLOSED', 'The dsh ACP runtime closed during session initialization');
+        status = 'idle';
+        emit({ type: 'opened', resumed: Boolean(input.sessionId), status });
+        return snapshot();
+      } catch (error) {
+        status = closing ? 'closing' : 'failed';
+        lastError = describe(error);
+        try { await disposeRuntime(); } catch (cleanupError) {
+          throw new AggregateError([error, cleanupError], 'ACP initialization and owned runtime cleanup failed');
+        }
+        throw error;
+      }
+    })();
+    return opening;
+  }
+
+  async function send(input = {}) {
+    if (closing || status === 'closed') throw failure('NATIVE_ADAPTER_CLOSED', 'The dsh ACP adapter is closed');
+    if (!sessionId || !['idle', 'running', 'interrupting'].includes(status)) throw failure('NATIVE_NOT_OPEN', 'Open a dsh ACP session before sending a prompt');
+    if (typeof input.text !== 'string' || !input.text.trim()) throw failure('NATIVE_BAD_PROMPT', 'Prompt text must be a nonempty string');
+    if (input.submissionId !== undefined && (typeof input.submissionId !== 'string' || !input.submissionId.trim())) {
+      throw failure('NATIVE_BAD_SUBMISSION', 'Submission identity must be a nonempty string');
+    }
+    const submissionId = input.submissionId || randomUUID();
+    const previous = receipts.get(submissionId);
+    if (previous) {
+      if (previous.text !== input.text) throw failure('NATIVE_SUBMISSION_CONFLICT', 'A submission identity cannot be reused with different text');
+      return { ...previous.receipt };
+    }
+    if (input.expectedTurnId && input.expectedTurnId !== active?.turnId) throw failure('NATIVE_STALE_TURN', 'The expected ACP submission is no longer active');
+    if (active) throw failure('NATIVE_BUSY', 'ACP permits one in-flight prompt per session and does not support steering');
+    clearToolContext();
+    const turn = { turnId: randomUUID(), submissionId, text: '' };
+    active = turn;
+    status = 'running';
+    lastError = null;
+    const receipt = { sessionId, turnId: turn.turnId, submissionId, status: 'queued' };
+    receipts.set(submissionId, { text: input.text, receipt });
+    if (receipts.size > 256) receipts.delete(receipts.keys().next().value);
+    emit({ type: 'queued', ...receipt });
+    // prompt settles only after Agent idle. Return the local queue receipt now;
+    // only the real RPC response constitutes a completed submission.
+    void Promise.resolve().then(() => {
+      if (closing) throw failure('NATIVE_ADAPTER_CLOSED', 'The adapter closed before prompt submission');
+      return rpc.request('session/prompt', {
+        sessionId, prompt: [{ type: 'text', text: input.text }]
+      }, { timeoutMs: 0 });
+    }).then((result) => {
+      if (active !== turn) return;
+      if (!['end_turn', 'max_tokens', 'max_turn_requests', 'refusal', 'cancelled'].includes(result?.stopReason)) {
+        throw failure('NATIVE_PROTOCOL_ERROR', 'ACP prompt returned an invalid stop reason');
+      }
+      interactions.expire(turn.turnId);
+      clearToolContext();
+      active = null;
+      status = closing ? 'closing' : 'idle';
+      emit({ type: 'completed', status: result.stopReason === 'cancelled' ? 'interrupted' : 'completed',
+        sessionId, turnId: turn.turnId, submissionId, text: turn.text, stopReason: result.stopReason });
+    }).catch((error) => {
+      if (active !== turn) return;
+      interactions.expire(turn.turnId);
+      clearToolContext();
+      active = null;
+      lastError = describe(error);
+      const wireFailure = typeof error?.code === 'number' ||
+        (error?.code === 'NATIVE_RPC_ERROR' && typeof error?.extra?.rpc_code === 'number');
+      status = closing ? 'closing' : wireFailure ? 'idle' : 'failed';
+      emit({ type: wireFailure ? 'completed' : 'error', status: wireFailure ? 'failed' : 'unknown',
+        sessionId, turnId: turn.turnId, submissionId, text: turn.text,
+        error: { ...lastError, uncertain: !wireFailure } });
+    });
+    return receipt;
+  }
+
+  async function interrupt(input = {}) {
+    if (closing || status === 'closed') throw failure('NATIVE_ADAPTER_CLOSED', 'The dsh ACP adapter is closed');
+    if (input.turnId && input.turnId !== active?.turnId) throw failure('NATIVE_STALE_TURN', 'The requested ACP submission is no longer active');
+    if (!active) return { sessionId, turnId: null, status };
+    const turn = active;
+    await rpc.notify('session/cancel', { sessionId });
+    // The prompt remains in flight until its terminal RPC response; late
+    // permission requests must stay cancelled throughout that interval.
+    turn.interrupted = true;
+    interactions.expire(turn.turnId, 'interrupted');
+    clearToolContext();
+    if (active === turn) status = 'interrupting';
+    const receipt = { sessionId, turnId: turn.turnId, submissionId: turn.submissionId, status: 'interrupting' };
+    emit({ type: 'interrupt.requested', ...receipt });
+    return receipt;
+  }
+
+  function close() {
+    if (closing) return closing;
+    closing = (async () => {
+      status = 'closing';
+      interactions.expire();
+      clearToolContext();
+      const errors = [];
+      if (opening) { try { await opening; } catch {} }
+      if (rpc && !runtimeDisposed && sessionId && capabilities.close) {
+        try { await rpc.request('session/close', { sessionId }); } catch (error) { errors.push(error); }
+      }
+      try { await disposeRuntime(); } catch (error) { errors.push(error); }
+      active = null;
+      status = 'closed';
+      emit({ type: 'closed', status });
+      if (errors.length) throw new AggregateError(errors, 'ACP session or owned runtime cleanup failed');
+      return snapshot();
+    })();
+    return closing;
+  }
+
+  async function disposeRuntime() {
+    if (runtimeDisposed) return;
+    runtimeDisposed = true;
+    await rpc?.close();
+  }
+
+  return { capabilities, open, send, interrupt, close, snapshot, respond: interactions.respond };
+}
+
+function failure(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function describe(error) {
+  return { code: error?.code || 'NATIVE_ERROR', message: String(error?.message || error),
+    ...(error?.extra?.uncertain ? { uncertain: true } : {}) };
+}
+
+function advertisesValue(options, value) {
+  return Array.isArray(options) && options.some((option) => option?.value === value || advertisesValue(option?.options, value));
+}

package/lib/integrations/native/index.mjs

@@ -0,0 +1,19 @@
+import { CliError } from '../../shared/errors.mjs';
+
+export const NATIVE_PROVIDERS = Object.freeze(['codex', 'claude', 'dsh']);
+
+export async function createNativeAdapter(provider, options) {
+  if (provider === 'codex') return (await import('./codex.mjs')).createCodexAdapter(options);
+  if (provider === 'claude') return (await import('./claude.mjs')).createClaudeAdapter(options);
+  if (provider === 'dsh') return (await import('./dsh-acp.mjs')).createDshAcpAdapter(options);
+  throw new CliError('BAD_ARGS', `Unsupported native provider: ${provider}`);
+}
+
+export function nativeWorkerEnv(env, ctx, peer, owner) {
+  const clean = Object.fromEntries(Object.entries(env || {}).filter(([key]) =>
+    !key.startsWith('HCC_') && !key.startsWith('CLAUDE_CODE_') &&
+    !['CODEX_THREAD_ID', 'CODEX_SESSION_ID', 'CLAUDE_SESSION_ID', 'CLAUDECODE'].includes(key)));
+  // Explicit, worker-specific coordination identity; provider credentials and
+  // the real HOME are preserved. No global configuration is rewritten.
+  return { ...clean, HCC_ROOT: ctx.root, HCC_DB: ctx.dbPath, HCC_PEER: peer, ...(owner ? { HCC_NATIVE_OWNER: owner } : {}) };
+}

package/lib/integrations/native/interactions.mjs

@@ -0,0 +1,53 @@
+import { randomUUID } from 'node:crypto';
+
+// Only the owning runtime can answer. Answers, including secrets, are never
+// placed in snapshots, events or persistent delivery receipts.
+export function createNativeInteractions({ executorId = randomUUID(), isActive, onChange }) {
+  const pending = new Map(), used = new Set();
+  function snapshot() {
+    return [...pending.values()].map(({ resolve, validate, cancelled, cleanup, ...view }) => structuredClone(view));
+  }
+  function settle(key, result, reason) {
+    const request = pending.get(key);
+    if (!request) return;
+    pending.delete(key); request.cleanup?.();
+    request.resolve(result);
+    onChange?.({ type: 'approval.resolved', requestId: request.requestId, turnId: request.turnId, reason });
+  }
+  function expire(turnId = null, reason = 'expired') {
+    for (const [key, request] of pending) if (!turnId || request.turnId === turnId) settle(key, request.cancelled, reason);
+  }
+  function request({ requestId, sessionId, turnId, kind = 'approval', method, params, validate, cancelled, signal }) {
+    const id = requestId ?? randomUUID(), key = JSON.stringify([typeof id, id]);
+    if (signal?.aborted || !isActive(sessionId, turnId)) return Promise.resolve(cancelled);
+    if (used.has(key) || pending.size >= 64) throw Object.assign(new Error('Duplicate or excessive native interaction requests'), { code: 'NATIVE_PROTOCOL_ERROR' });
+    used.add(key); if (used.size > 256) used.delete(used.values().next().value);
+    let truncated = false, preview = structuredClone(params);
+    if (JSON.stringify(preview).length > 65536) { truncated = true; preview = { preview: JSON.stringify(params).slice(0, 65536) }; }
+    const promise = new Promise(resolve => {
+      const entry = { executorId, requestId: id, sessionId, turnId, kind, method, params: preview,
+        truncated, status: 'pending', createdAt: Date.now(), resolve, validate, cancelled };
+      pending.set(key, entry);
+      if (signal) {
+        const aborted = () => settle(key, cancelled, 'cancelled');
+        signal.addEventListener('abort', aborted, { once: true });
+        entry.cleanup = () => signal.removeEventListener('abort', aborted);
+      }
+      onChange?.({ type: 'approval', ...snapshot().find(value => value.requestId === id) });
+    });
+    return promise;
+  }
+  function respond(input) {
+    const key = JSON.stringify([typeof input.requestId, input.requestId]), entry = pending.get(key);
+    if (!entry || input.executorId !== executorId || input.sessionId !== entry.sessionId || input.turnId !== entry.turnId || !isActive(entry.sessionId, entry.turnId)) {
+      throw Object.assign(new Error('Native interaction expired or belongs to another worker/turn'), { code: 'NATIVE_APPROVAL_MISMATCH' });
+    }
+    const result = entry.validate(entry, input);
+    settle(key, result, 'answered');
+    return { executorId, requestId: entry.requestId, sessionId: entry.sessionId, turnId: entry.turnId, status: 'submitted' };
+  }
+  return { executorId, request, snapshot, respond, expire, resolved(requestId) {
+    const key = JSON.stringify([typeof requestId, requestId]);
+    if (pending.has(key)) settle(key, pending.get(key).cancelled, 'resolved-by-provider');
+  } };
+}