create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/acp/dsh-session-runtime.js

@@ -0,0 +1,522 @@
+'use strict';
+
+// WP-2 of docs/deepseek-harness-acp-agent-2026-10-28.html (§6.3; decisions D-1, D-2, D-5, D-6, D-9, D-10).
+//
+// One CTM dsh session owns exactly ONE child process (D-2) driven over the Agent Client Protocol on
+// pipes — never node-pty (D-1). This module owns the child, the ACP client and the stop sequence; it
+// renders nothing, writes no transcript (that is WP-3) and knows nothing about WebSockets (the caller
+// injects `onUpdate`/`onRequestPermission`/`onExit`). Prompts, approvals and status are WP-4; restore
+// after a CTM restart is WP-5 and spawns through `start({ resumeAcpSessionId })`.
+//
+// Everything that touches the outside world is a dep so a test never spawns the real binary (D-14):
+// `resolveCliCommand` (the CLI cache), `realpath`, `execPath` (CTM's pinned Node), `spawnFn` (the
+// ND-JSON transport's), the log sink and the timers.
+
+const { spawnNdjsonTransport } = require('./ndjson-stdio-transport');
+const { createAcpClient, AcpError } = require('./acp-client');
+const { AGENT_DEFINITIONS } = require('../agent-definitions');
+
+// WP-12: the name `dsh` is not unique (homebrew's `dsh` is the unrelated "Dancer's shell"), so a
+// resolved binary is spawned only when its REALPATH is inside the @deepseek-ai/dsh package -- the
+// same installIdentity rule the version service applies (lib/agent-version-service.js).
+const DSH_INSTALL_IDENTITY = AGENT_DEFINITIONS.dsh.installIdentity;
+
+const DSH_STOP_GRACE_MS = 5000;    // SIGTERM this long after stdin end
+const DSH_KILL_GRACE_MS = 1000;    // SIGKILL this long after SIGTERM
+const DSH_CLOSE_TIMEOUT_MS = 3000; // session/close budget before stdin end
+const STDERR_TAIL_BYTES = 64 * 1024;
+// WP-14: the bounded assistant text a completed turn leaves behind (see accumulateFinalText). Well
+// above any real report, and small next to the 64 KB stderr ring.
+const FINAL_TEXT_MAX_CHARS = 256 * 1024;
+// A start failure names the child's exit in ONE line, so the tail it quotes is bounded well below the
+// 64 KB ring it is cut from.
+const STDERR_MESSAGE_CHARS = 400;
+// D-1: a `.js`/`.cjs`/`.mjs` realpath is an npm entrypoint, not an executable — spawn it under the
+// interpreter CTM pins (dsh needs Node >= 24.9) rather than whatever `node` PATH resolves to.
+const JS_ENTRYPOINT_RE = /\.(?:js|cjs|mjs)$/i;
+// WP-6 (§6.6, D-11): a ROUTED child talks to CTM's loopback proxy and carries the session token as
+// its only credential, so every other provider credential or base URL inherited from the launch env
+// is removed — otherwise pi-ai's own provider resolution (or a stale DEEPSEEK_API_KEY the user still
+// has exported) could quietly win over the `--patch`.
+const DSH_ROUTE_ENV_KEYS = Object.freeze([
+  'DEEPSEEK_API_KEY',
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_BASE_URL',
+  'ANTHROPIC_OAUTH_TOKEN',
+]);
+
+/**
+ * @param {object} deps
+ * @param {(cmd: string) => string} deps.resolveCliCommand   // lib/agent-cli-cache.js's resolver
+ * @param {(p: string) => Promise<string>|string} deps.realpath  // async in production (no sync fs on the main loop)
+ * @param {string} deps.execPath                              // process.execPath
+ * @param {Function} [deps.spawnFn]                           // child_process.spawn stand-in for tests
+ * @param {Function} [deps.now]
+ * @param {Function} [deps.log]                               // ({level, msg}) => void
+ * @param {(ctmSessionId: string, update: object) => void} [deps.onUpdate]
+ * @param {(ctmSessionId: string, configOptions: Array<object>|null) => void} [deps.onConfigOptions]
+ * @param {(ctmSessionId: string, params: object) => Promise<object>} [deps.onRequestPermission]
+ * @param {(ctmSessionId: string, info: object) => void} [deps.onExit]
+ * @param {Function} [deps.setTimeout]
+ * @param {Function} [deps.clearTimeout]
+ */
+function createDshSessionRuntime(deps = {}) {
+  const {
+    resolveCliCommand = (cmd) => cmd,
+    realpath = (p) => p,
+    execPath = process.execPath,
+    spawnFn,
+    log = () => {},
+  } = deps;
+  const setTimeoutFn = deps.setTimeout || setTimeout;
+  const clearTimeoutFn = deps.clearTimeout || clearTimeout;
+
+  const entries = new Map(); // ctmSessionId → entry (ONE per id, D-2)
+
+  function logLine(level, msg) {
+    try {
+      log({ level, msg });
+    } catch (error) {
+      // expected: a broken log sink must never take down a session's start/stop path.
+      void error;
+    }
+  }
+
+  // The bounded stderr tail (D-5). Byte-trimmed so a chatty child cannot grow it without limit; the
+  // tail is diagnostic only and is NEVER logged at info (it can carry the child's own error text).
+  function trimTail(text) {
+    if (Buffer.byteLength(text, 'utf8') <= STDERR_TAIL_BYTES) return text;
+    return Buffer.from(text, 'utf8').subarray(-STDERR_TAIL_BYTES).toString('utf8');
+  }
+
+  function appendTail(state, line) {
+    state.stderrTail = trimTail(state.stderrTail ? `${state.stderrTail}\n${line}` : String(line));
+  }
+
+  function describeExit(info, tail) {
+    const code = info && info.code !== undefined && info.code !== null ? info.code : null;
+    const signal = info && info.signal ? info.signal : null;
+    const detail = code === null && !signal
+      ? 'dsh exited during startup'
+      : `dsh exited during startup (code ${code}${signal ? `, signal ${signal}` : ''})`;
+    const quoted = String(tail || '').slice(-STDERR_MESSAGE_CHARS);
+    return quoted ? `${detail}: ${quoted}` : detail;
+  }
+
+  function scheduleSigkillEscalation(entry) {
+    const timer = setTimeoutFn(() => {
+      if (!entry.exited) entry.transport.kill('SIGKILL');
+    }, DSH_KILL_GRACE_MS);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+    return timer;
+  }
+
+  // The child is gone: drop the registry row, release anyone waiting on the stop, and report the exit
+  // to the caller exactly once. An exit this runtime caused itself (stop, or a failed start) is
+  // either reported as intentional or not reported at all — never both.
+  function onChildExit(ctmSessionId, entry, info) {
+    if (entry.exited) return;
+    entry.exited = true;
+    entry.exitInfo = info || null;
+    if (entries.get(ctmSessionId) === entry) entries.delete(ctmSessionId);
+    if (typeof entry.resolveExit === 'function') entry.resolveExit();
+    // Before the handshake completes the child belongs to start(), which reports the failure itself.
+    if (!entry.started) return;
+    // WP-6: the routed token is released exactly ONCE per started child, on whichever path the child
+    // died (a stop, or a crash): `entry.exited` above already makes this a one-shot, and clearing the
+    // hook means a later re-entry can never fire it a second time.
+    if (typeof entry.onStopped === 'function') {
+      const release = entry.onStopped;
+      entry.onStopped = null;
+      try {
+        release();
+      } catch (error) {
+        // expected: a release observer must never break the transport's own teardown.
+        void error;
+      }
+    }
+    const report = deps.onExit;
+    if (typeof report !== 'function') return;
+    try {
+      report(ctmSessionId, {
+        code: info && info.code !== undefined ? info.code : null,
+        signal: info && info.signal !== undefined ? info.signal : null,
+        stderrTail: entry.stderrTail,
+        intentional: entry.stopping === true,
+      });
+    } catch (error) {
+      // expected: an exit observer must never break the transport's own teardown.
+      void error;
+    }
+  }
+
+  // WP-8 (§9b M-16, D-12/D-13): a `config_option_update` notification carries the bridge's WHOLE
+  // `configOptions` list — the same shape `session/new`/`session/resume` returned — so it replaces the
+  // entry's copy (which `get()` serves) and is handed to the caller's observer, which records the
+  // model-owner row. Any other update kind is passed through untouched, and a throwing observer can
+  // never break the ACP read loop that called it.
+  function acceptConfigOptions(ctmSessionId, entry, update) {
+    if (!update || update.sessionUpdate !== 'config_option_update') return;
+    const next = Array.isArray(update.configOptions) ? update.configOptions
+      : (update.configOption && typeof update.configOption === 'object' ? [update.configOption] : null);
+    if (next) entry.configOptions = next;
+    if (typeof entry.onConfigOptions !== 'function') return;
+    try {
+      entry.onConfigOptions(ctmSessionId, entry.configOptions);
+    } catch (error) {
+      logLine('warn', `dsh-runtime: config-option observer failed for ${ctmSessionId} (${(error && error.message) || 'error'})`);
+    }
+  }
+
+  // WP-14 (docs/deepseek-harness-acp-agent-2026-10-28.html §9b W-3, §6.4): the LAST assistant text the
+  // child produced, which is what a delegated dsh worker's report IS (its brief turn's final answer;
+  // the transcript writer appends the same chunks). The ACP wire has no "final message" field — the
+  // text arrives as `agent_message_chunk` updates — so this accumulates them per `messageId` and keeps
+  // the last id seen: a new id starts a new assistant message, exactly the grouping
+  // lib/acp/dsh-transcript.js's chunk writer uses (`pending.messageId`). Bounded, so a runaway child
+  // cannot grow the entry without limit; only text chunks count (thinking chunks are not an answer).
+  function accumulateFinalText(entry, update) {
+    if (!update || update.sessionUpdate !== 'agent_message_chunk') return;
+    const messageId = typeof update.messageId === 'string' && update.messageId ? update.messageId : entry.finalTextMessageId;
+    const content = update.content;
+    const text = typeof content === 'string' ? content
+      : content && typeof content.text === 'string' ? content.text : '';
+    if (!text) return;
+    if (messageId !== entry.finalTextMessageId) {
+      entry.finalTextMessageId = messageId;
+      entry.finalText = '';
+    }
+    entry.finalText = `${entry.finalText}${text}`.slice(-FINAL_TEXT_MAX_CHARS);
+  }
+
+  // WP-10 step A (C-6/D-16): `mcpServers` are the ACP entries the child mounts for THIS session
+  // (lib/acp/dsh-mcp-servers.js converts CTM's normalized map into them). They ride the
+  // `session/new`/`session/resume` JSON-RPC request -- never argv, never the child's process env --
+  // and an absent list is an empty one, so a session with no MCP profile is byte-for-byte what it
+  // was before WP-10.
+  async function start({ ctmSessionId, cwd, env, resumeAcpSessionId = null, patchPath = null, mcpServers = [], onStopped = null, onConfigOptions = null } = {}) {
+    if (entries.has(ctmSessionId)) {
+      return {
+        ok: false,
+        code: 'dsh_already_running',
+        message: `A DeepSeek Harness process is already running for session ${ctmSessionId}.`,
+      };
+    }
+    const bin = resolveCliCommand('dsh');
+    // `resolveCliCommand` returns its input unchanged when the CLI is not on this host (an absolute
+    // path it cannot find also comes back bare).
+    if (!bin || bin === 'dsh') {
+      return { ok: false, code: 'dsh_not_found', message: 'DeepSeek Harness (dsh) was not found on PATH' };
+    }
+    let real = bin;
+    try {
+      real = (await realpath(bin)) || bin;
+    } catch (error) {
+      // expected: the CLI cache can point at a path that has since been removed; spawn reports that
+      // as a start failure through the transport's exit channel, so no throw is needed here.
+      void error;
+    }
+    if (!DSH_INSTALL_IDENTITY.test(String(real))) {
+      return { ok: false, code: 'dsh_not_found', message: 'The dsh on PATH is not the DeepSeek Harness (@deepseek-ai/dsh)' };
+    }
+    const args = ['--profile', 'acp'];
+    if (patchPath) args.push('--patch', patchPath);
+    const isJsEntrypoint = JS_ENTRYPOINT_RE.test(real);
+    const command = isJsEntrypoint ? execPath : real;
+    const spawnArgs = isJsEntrypoint ? [real, ...args] : args;
+    const childEnv = { ...(env || {}) };
+    // WP-6 (§6.6): a routed child's provider comes from the patch and its credential is the session
+    // token; every other provider key/base URL in the launch env is dropped (see DSH_ROUTE_ENV_KEYS).
+    if (patchPath) for (const key of DSH_ROUTE_ENV_KEYS) delete childEnv[key];
+    // The bridge's own permission mode. Passed THROUGH to the child; never read back by CTM and never
+    // logged (it is launch context, not a CTM flag).
+    if (childEnv.DSH_PERMISSION_MODE === undefined) childEnv.DSH_PERMISSION_MODE = 'workspace-write';
+
+    const entry = {
+      acpSessionId: null,
+      client: null,
+      transport: null,
+      pid: undefined,
+      configOptions: null,
+      agentInfo: null,
+      // WP-11 (D-20): the child's LIVE image capability, read from the ACP `initialize` result
+      // (`agentCapabilities.promptCapabilities.image`). Absent/false means the bridge cannot accept
+      // an image content block, and the prompt lane refuses such a prompt rather than sending one.
+      imageInput: false,
+      // WP-14: the last assistant text seen for this child (accumulateFinalText above), and the
+      // messageId that text belongs to.
+      finalText: '',
+      finalTextMessageId: null,
+      stderrTail: '',
+      started: false,
+      startFailed: false,
+      stopping: false,
+      stopReason: '',
+      stopPromise: null,
+      exited: false,
+      exitInfo: null,
+      resolveExit: null,
+      exitPromise: null,
+      // WP-6: the caller's one-shot release hook (see onChildExit). Never called for a child whose
+      // start failed -- that child belongs to start(), which releases its own token.
+      onStopped: typeof onStopped === 'function' ? onStopped : null,
+      // WP-8: the caller's model-owner observer (see acceptConfigOptions). Fires for every
+      // `config_option_update` the child emits, including ones that arrive before the handshake ends.
+      onConfigOptions: typeof onConfigOptions === 'function' ? onConfigOptions : null,
+    };
+    entry.exitPromise = new Promise((resolve) => { entry.resolveExit = resolve; });
+
+    const transport = spawnNdjsonTransport({
+      command,
+      args: spawnArgs,
+      cwd,
+      env: childEnv,
+      ...(spawnFn ? { spawnFn } : {}),
+      onStderrLine: (line) => appendTail(entry, line),
+    });
+    entry.transport = transport;
+    entry.pid = transport.pid;
+    transport.onExit((info) => onChildExit(ctmSessionId, entry, info));
+
+    const client = createAcpClient({
+      transport,
+      onSessionUpdate: (sessionId, update) => {
+        acceptConfigOptions(ctmSessionId, entry, update);
+        accumulateFinalText(entry, update);
+        if (typeof deps.onUpdate === 'function') deps.onUpdate(ctmSessionId, update);
+        else logLine('info', `dsh-runtime: session update for ${sessionId} dropped (no observer)`);
+      },
+      onRequestPermission: (params) => (typeof deps.onRequestPermission === 'function'
+        ? deps.onRequestPermission(ctmSessionId, params)
+        : Promise.resolve({ outcome: 'cancelled' })),
+      log: (entryLog) => logLine(entryLog.level, entryLog.msg),
+    });
+    entry.client = client;
+
+    try {
+      const initResult = await client.initialize();
+      const acpMcpServers = Array.isArray(mcpServers) ? mcpServers : [];
+      const sessionResult = resumeAcpSessionId
+        ? await client.resumeSession({ sessionId: resumeAcpSessionId, cwd, mcpServers: acpMcpServers })
+        : await client.newSession({ cwd, mcpServers: acpMcpServers });
+      const acpSessionId = (sessionResult && (sessionResult.sessionId || sessionResult.session_id))
+        || resumeAcpSessionId
+        || null;
+      entry.acpSessionId = acpSessionId;
+      entry.configOptions = (sessionResult && sessionResult.configOptions) || null;
+      entry.agentInfo = (initResult && initResult.agentInfo) || null;
+      // WP-11 (D-20): the child's own answer to "can you take an image?". Read from the SAME
+      // initialize result the handshake gate above already validated; an absent or non-`true` value
+      // is false (a bridge that does not advertise image prompts cannot be given one).
+      entry.imageInput = !!(
+        initResult
+        && initResult.agentCapabilities
+        && initResult.agentCapabilities.promptCapabilities
+        && initResult.agentCapabilities.promptCapabilities.image === true
+      );
+      entry.started = true;
+      entries.set(ctmSessionId, entry);
+      return {
+        ok: true,
+        acpSessionId,
+        configOptions: entry.configOptions,
+        agentInfo: entry.agentInfo,
+        imageInput: entry.imageInput,
+      };
+    } catch (error) {
+      // Nothing was registered, so the child must not outlive this call.
+      entry.startFailed = true;
+      transport.kill('SIGTERM');
+      entry.sigkillTimer = scheduleSigkillEscalation(entry);
+      if (error instanceof AcpError && error.code === 'dsh_acp_incompatible') {
+        return { ok: false, code: 'dsh_acp_incompatible', message: error.message };
+      }
+      if (entry.exited || (error instanceof AcpError && error.code === 'acp_child_exited')) {
+        return { ok: false, code: 'dsh_start_failed', message: describeExit(entry.exitInfo, entry.stderrTail) };
+      }
+      return {
+        ok: false,
+        code: 'dsh_start_failed',
+        message: error && error.message ? String(error.message) : 'DeepSeek Harness failed to start',
+      };
+    }
+  }
+
+  // D-10: session/close (bounded), stdin end, SIGTERM after DSH_STOP_GRACE_MS, SIGKILL
+  // DSH_KILL_GRACE_MS later if the child is still alive. Files are never touched.
+  // `closeAcpSession:false` (§6.7 cross-route relaunch) skips session/close: the SAME ACP session is
+  // resumed by the next child, so it must stay open.
+  async function stop(ctmSessionId, { reason, closeAcpSession = true } = {}) {
+    const entry = entries.get(ctmSessionId);
+    if (!entry) return { ok: true, alreadyStopped: true };
+    if (entry.stopPromise) return entry.stopPromise;
+    entry.stopping = true;
+    entry.stopReason = reason || '';
+    entry.stopPromise = (async () => {
+      if (closeAcpSession) {
+        try {
+          await Promise.race([
+            entry.client.closeSession({ sessionId: entry.acpSessionId }),
+            new Promise((resolve) => {
+              const timer = setTimeoutFn(resolve, DSH_CLOSE_TIMEOUT_MS);
+              if (timer && typeof timer.unref === 'function') timer.unref();
+            }),
+          ]);
+        } catch (error) {
+          // The child may already be gone, or the bridge may not implement session/close (its
+          // capability is optional); the SIGTERM ladder below is the real guarantee.
+          logLine('warn', `dsh-runtime: session/close failed for ${ctmSessionId} (${(error && error.code) || 'error'})`);
+        }
+      }
+      entry.transport.endInput();
+      const termTimer = setTimeoutFn(() => {
+        if (!entry.exited) entry.transport.kill('SIGTERM');
+      }, DSH_STOP_GRACE_MS);
+      const killTimer = setTimeoutFn(() => {
+        if (!entry.exited) entry.transport.kill('SIGKILL');
+      }, DSH_STOP_GRACE_MS + DSH_KILL_GRACE_MS);
+      if (termTimer && typeof termTimer.unref === 'function') termTimer.unref();
+      if (killTimer && typeof killTimer.unref === 'function') killTimer.unref();
+      await entry.exitPromise;
+      clearTimeoutFn(termTimer);
+      clearTimeoutFn(killTimer);
+      return { ok: true };
+    })();
+    return entry.stopPromise;
+  }
+
+  function isRunning(ctmSessionId) {
+    const entry = entries.get(ctmSessionId);
+    return !!entry && !entry.exited;
+  }
+
+  // WP-8 step 3 (§6.7): the bridge admits ONE in-flight prompt per session, so a config-option write
+  // that arrived while a turn is open must be REFUSED, never queued (the caller's pick is a
+  // point-in-time choice, and a queued write would silently apply to a later turn). The predicate is
+  // injected (the prompt lane owns the turn registry) — absent a predicate nothing is ever in flight.
+  function isTurnInFlight(ctmSessionId) {
+    if (typeof deps.isTurnInFlight !== 'function') return false;
+    try {
+      return deps.isTurnInFlight(ctmSessionId) === true;
+    } catch (error) {
+      logLine('warn', `dsh-runtime: turn-in-flight probe failed for ${ctmSessionId} (${(error && error.message) || 'error'})`);
+      return false;
+    }
+  }
+
+  // The ONE config-option write (§6.7). `value` is the OPAQUE option value the bridge itself
+  // advertised — never a hand-built string — so the caller must have found it in the entry's own
+  // `configOptions`. On success the returned list replaces the entry's copy and the SAME observer
+  // path `acceptConfigOptions` uses is invoked, so the model-owner row re-binds from one place.
+  async function applyConfigOption(ctmSessionId, configId, value) {
+    const entry = entries.get(ctmSessionId);
+    if (!entry || entry.exited) return { ok: false, code: 'acp_child_exited' };
+    if (!configId || typeof value !== 'string' || !value) return { ok: false, code: 'dsh_option_unavailable' };
+    if (isTurnInFlight(ctmSessionId)) return { ok: false, code: 'dsh_turn_in_flight' };
+    if (typeof entry.client?.setConfigOption !== 'function') return { ok: false, code: 'dsh_option_unavailable' };
+    let result;
+    try {
+      result = await entry.client.setConfigOption({
+        sessionId: entry.acpSessionId, configId, value,
+      });
+    } catch (error) {
+      // A child that died mid-write is reported as exited; anything else is the bridge refusing the
+      // option, which is exactly the `dsh_option_unavailable` the caller shows the user.
+      if (entry.exited) return { ok: false, code: 'acp_child_exited' };
+      logLine('warn', `dsh-runtime: set_config_option ${configId} failed for ${ctmSessionId} (${(error && error.code) || 'error'})`);
+      return { ok: false, code: 'dsh_option_unavailable' };
+    }
+    const next = result && Array.isArray(result.configOptions) ? result.configOptions : null;
+    if (next) {
+      entry.configOptions = next;
+      if (typeof entry.onConfigOptions === 'function') {
+        try {
+          entry.onConfigOptions(ctmSessionId, entry.configOptions);
+        } catch (error) {
+          logLine('warn', `dsh-runtime: config-option observer failed for ${ctmSessionId} (${(error && error.message) || 'error'})`);
+        }
+      }
+    }
+    return { ok: true, configOptions: entry.configOptions };
+  }
+
+  /**
+   * §6.7: switch the ACP `model` option. `value` is the OPAQUE value from the entry's `configOptions`
+   * (the caller unwraps the entry's JSON pair; this layer never builds one).
+   */
+  async function setModel(ctmSessionId, { value } = {}) {
+    return applyConfigOption(ctmSessionId, 'model', value);
+  }
+
+  /** §6.7: switch the bridge-declared effort option (`reasoning_effort`), same contract as setModel. */
+  async function setEffort(ctmSessionId, level, { configId = 'reasoning_effort', value = null } = {}) {
+    return applyConfigOption(ctmSessionId, configId, value == null ? level : value);
+  }
+
+  function get(ctmSessionId) {
+    const entry = entries.get(ctmSessionId);
+    if (!entry) return null;
+    return {
+      acpSessionId: entry.acpSessionId,
+      client: entry.client,
+      pid: entry.pid,
+      configOptions: entry.configOptions,
+      // WP-11 (D-20): the live image capability of THIS child (`initialize`'s
+      // `agentCapabilities.promptCapabilities.image`). Absent reads false — a gone child reads
+      // `null` for the whole entry, which the prompt lane already treats as "not running".
+      imageInput: entry.imageInput === true,
+      stderrTail: () => entry.stderrTail,
+      // WP-14 (§9b W-3): the report source for a delegated dsh worker — `observer?.finalText ||
+      // runtime?.finalText` in delegate-worker.js's getWorkerStatus reads this through
+      // lib/session-create/dsh-session.js's `_dshFinalText` accessor. Empty until the child has
+      // produced assistant text; '' (never null) so a caller never has to type-check it.
+      finalText: entry.finalText || '',
+    };
+  }
+
+  /**
+   * WP-14 (§9b W-2): put ONE prompt on the wire for a caller that is not the interactive prompt lane
+   * — the delegated dsh worker's brief, which has no argv to ride. Returns the ACP prompt promise
+   * (the turn's own settle/status/cancel behaviour stays the prompt lane's business, exactly as it is
+   * for an interactive turn); a session with no live child is refused rather than throwing.
+   * `resetFinalText` starts the report's text from THIS turn: without it a run whose first turn was
+   * empty would report the previous turn's answer.
+   *
+   * @param {string} ctmSessionId
+   * @param {{text: string}} prompt
+   * @returns {Promise<{ok: true, prompt: Promise<any>}|{ok: false, code: string, message: string}>}
+   */
+  function prompt(ctmSessionId, { text = '' } = {}) {
+    const entry = entries.get(ctmSessionId);
+    if (!entry || !entry.client || typeof entry.client.prompt !== 'function' || !entry.acpSessionId) {
+      return Promise.resolve({
+        ok: false,
+        code: 'dsh_not_running',
+        message: `No DeepSeek Harness process is running for session ${ctmSessionId}.`,
+      });
+    }
+    entry.finalText = '';
+    entry.finalTextMessageId = null;
+    let pending;
+    try {
+      pending = entry.client.prompt({ sessionId: entry.acpSessionId, text: String(text) });
+    } catch (error) {
+      return Promise.resolve({
+        ok: false,
+        code: 'dsh_prompt_failed',
+        message: (error && error.message) ? String(error.message) : 'DeepSeek Harness refused the prompt',
+      });
+    }
+    return Promise.resolve({ ok: true, prompt: Promise.resolve(pending) });
+  }
+
+  return { start, stop, isRunning, get, prompt, setModel, setEffort, isTurnInFlight };
+}
+
+module.exports = {
+  createDshSessionRuntime,
+  DSH_STOP_GRACE_MS,
+  DSH_KILL_GRACE_MS,
+  DSH_CLOSE_TIMEOUT_MS,
+  DSH_ROUTE_ENV_KEYS,
+};