create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/acp/dsh-launch-model.js

@@ -0,0 +1,302 @@
+'use strict';
+
+// WP-8 step 3 of docs/deepseek-harness-acp-agent-2026-10-28.html (§6.7, §9b M-15/M-16; D-12/D-13).
+//
+// The live model/effort switch for a DeepSeek Harness (`dsh`) lead tab. dsh is an ACP child, not a
+// PTY, so the journaled Claude/Codex machine (owner tuple + provider thread + history handoff) does
+// not apply and neither does OpenCode's park/relaunch argv dance: the bridge exposes the SAME
+// `configOptions` list `session/new` returned, and the ACP primitive
+// `session/set_config_option { sessionId, configId, value }` is the switch (D-12). Two routes:
+//
+//   SAME route (or no route named) -> ONE `session/set_config_option` on `configId:'model'` (and/or
+//   the bridge-declared effort option). The reply's `configOptions` IS the confirmation, so the
+//   request settles `applied` when its `model` option reads back the pick (D-13: never argv, never
+//   `session.model_id` alone).
+//
+//   DIFFERENT route -> the child holds one route's patch and one session token, so nothing can be
+//   patched in place: the child is STOPPED (intentionally) and the existing restore path starts a
+//   fresh one on the NEW route, resuming the SAME ACP session id (`session/resume`). The new route's
+//   token is minted by `prepareDshRoute`, the old one is released by the runtime's one-shot
+//   `onStopped` hook, and the durable record follows so a later CTM restart resumes on it.
+//
+// What it deliberately does NOT do:
+//   - it never queues a write behind an open turn: the bridge admits ONE in-flight prompt per
+//     session, so a pick made while the harness is answering is refused `dsh_turn_in_flight`;
+//   - it never hand-builds an option value: the opaque value comes from the entry's own
+//     `configOptions`, and a pick the bridge does not offer is refused `dsh_option_unavailable`;
+//   - it never writes a token anywhere but the child's env (D-11): the live `_dshRoute` is
+//     non-enumerable and in-memory only, and nothing here logs or persists it (AC-8c-5).
+//
+// The public request/get/cancel surface is OpenCode's, byte for byte (`publicSessionModelRequest`),
+// so the existing client picker renders a dsh switch without a second code path.
+
+const crypto = require('node:crypto');
+const { publicSessionModelRequest } = require('../session-model-action-preconditions');
+
+const SESSION_NOT_FOUND = 'session_not_found';
+// One entry per session while its pick is being applied; a second request for the same tab is
+// refused with `lead_switch_in_flight` (never queued), exactly like OpenCode's.
+const FLIGHT_KEY = 'relaunching';
+const APPLIED_STATE = 'applied';
+// The request kinds this controller answers. `launch_model` is what the shared picker already sends
+// for an OpenCode tab; `switch_model` is accepted as the same pick under its other name, and an
+// ABSENT kind is accepted so an older client keeps working.
+const ACCEPTED_KINDS = new Set(['launch_model', 'switch_model']);
+const MAX_MODEL_ID_LENGTH = 200;
+const MAX_ROUTE_ID_LENGTH = 200;
+const MAX_CLIENT_REQUEST_ID_LENGTH = 128;
+const MAX_EFFORT_LENGTH = 32;
+
+// The sentence each refusal carries, so every client shows a reason instead of a bare HTTP status.
+const REFUSAL_MESSAGES = Object.freeze({
+  invalid_request_kind: 'This DeepSeek Harness tab can only switch models and effort; reopen the model picker and try again.',
+  invalid_model_id: 'That model was not usable. Reopen the model picker and try again.',
+  invalid_route_id: 'The gateway route this pick carried was not usable. Reopen the model picker and try again.',
+  invalid_effort: 'That effort level was not usable. Reopen the model picker and try again.',
+  invalid_request: 'This model pick was incomplete. Reopen the model picker and try again.',
+  invalid_scope: 'This DeepSeek Harness tab can only switch its own session.',
+  model_owner_changed: 'This DeepSeek Harness tab restarted since the picker opened. Reopen the picker and try again.',
+  lead_switch_in_flight: 'A model switch for this tab is already running.',
+  not_live: 'The DeepSeek Harness process for this tab is not running.',
+  dsh_turn_in_flight: 'DeepSeek Harness is answering right now. Pick again when the turn ends.',
+  dsh_option_unavailable: 'This DeepSeek Harness session does not offer that option.',
+  observed_model_mismatch: 'DeepSeek Harness did not switch to that model.',
+  dsh_start_failed: 'DeepSeek Harness did not restart on the new route.',
+  lead_switch_not_cancellable: 'There is no pending model switch to cancel.',
+});
+
+function refusal(status, code, extra = {}) {
+  const message = REFUSAL_MESSAGES[code];
+  return { ok: false, status, code, ...(message ? { message } : {}), ...extra };
+}
+
+/**
+ * @param {object} deps
+ * @param {(id: string) => ({ agent: string|null, live?: boolean, processGeneration?: number }|null)} deps.getSessionInfo
+ * @param {(id: string) => (object|null)} deps.getSession                      the live session object
+ * @param {object} deps.dshRuntime                                             lib/acp/dsh-session-runtime.js
+ * @param {object} deps.dshSession                                             lib/session-create/dsh-session.js
+ * @param {(frame: object) => void} deps.broadcast
+ * @param {(id: string, kind: string, detail: object) => void} [deps.diagnostic]
+ * @param {() => number} [deps.now]
+ * @param {() => string} [deps.newId]
+ */
+function createDshLaunchModel({
+  getSessionInfo, getSession, dshRuntime, dshSession,
+  broadcast, diagnostic = null,
+  now = Date.now, newId = () => crypto.randomUUID(),
+} = {}) {
+  // One entry per session: a later request for the same tab REPLACES the previous one unless it is
+  // still being applied, so the map is bounded by the number of live dsh tabs.
+  const entries = new Map();
+
+  function frame(entry) {
+    return { type: 'lead-model-request', request: publicSessionModelRequest(entry.req) };
+  }
+
+  function report(entry) {
+    if (typeof diagnostic !== 'function') return;
+    try {
+      diagnostic(entry.req.ctm_session_id, `dsh-launch-model-${entry.req.state}`, {
+        client_request_id: entry.req.client_request_id, model_id: entry.req.model_id,
+        reason: entry.req.reason, detail: entry.req.detail,
+      });
+    } catch { /* expected: a diagnostic sink failure must not change the switch verdict */ }
+  }
+
+  // A refusal that PRE-DATES any child action: nothing was changed, so the placeholder entry must not
+  // survive as a request the client would later read back as its own.
+  function withdraw(entry) {
+    if (entry && entries.get(entry.req.ctm_session_id) === entry) entries.delete(entry.req.ctm_session_id);
+  }
+
+  function settleEntry(entry, state, reason, detail) {
+    entry.req.state = state;
+    entry.req.phase = state;
+    entry.req.reason = reason || null;
+    entry.req.detail = String(detail || '').slice(0, 200);
+    entry.req.cancellable = false;
+    entry.req.settled_at = now();
+    report(entry);
+    broadcast(frame(entry));
+  }
+
+  // The option list the bridge is CURRENTLY advertising for this session: the live runtime entry is
+  // the only truth (it is replaced by every `config_option_update`), with the request-time entry as
+  // the fallback when the child is gone.
+  function configOptionsFor(id) {
+    const live = typeof dshRuntime?.get === 'function' ? dshRuntime.get(id) : null;
+    return (live && Array.isArray(live.configOptions)) ? live.configOptions : null;
+  }
+
+  function turnInFlight(id) {
+    return typeof dshRuntime?.isTurnInFlight === 'function' && dshRuntime.isTurnInFlight(id) === true;
+  }
+
+  /**
+   * The SAME-route half: rewrite the model and/or the effort option in place. Each write is one
+   * `session/set_config_option`, and the pick is confirmed from the list the bridge answered with.
+   * @returns {Promise<{ok: true}|{ok: false, code: string, message: string}>}
+   */
+  async function applyInPlace(id, { modelId, effortProvided, effort }) {
+    const options = configOptionsFor(id);
+    let written = false;
+    if (modelId) {
+      const modelOption = dshSession.findModelOption(options);
+      const value = modelOption ? dshSession.configValueForModelId(modelOption, modelId) : null;
+      if (!value) return { ok: false, code: 'dsh_option_unavailable', message: REFUSAL_MESSAGES.dsh_option_unavailable };
+      const result = await dshRuntime.setModel(id, { value });
+      if (!result || !result.ok) return { ok: false, code: result?.code || 'dsh_option_unavailable', message: REFUSAL_MESSAGES[result?.code] || REFUSAL_MESSAGES.dsh_option_unavailable };
+      written = true;
+      // D-13: the confirmation is the bridge's own answer, never the value we asked for.
+      const observed = dshSession.modelIdFromConfigOptions(result.configOptions);
+      if (observed !== modelId) {
+        return { ok: false, code: 'observed_model_mismatch', message: REFUSAL_MESSAGES.observed_model_mismatch };
+      }
+    }
+    if (effortProvided) {
+      const effortOption = dshSession.findEffortOption(configOptionsFor(id) || options);
+      const value = effortOption ? dshSession.configValueForOptionLevel(effortOption, effort) : null;
+      // The EMPTY level means "the model's own default". A bridge that declares no such entry is not
+      // an error for that pick (it is already the state), but any OTHER level the bridge does not
+      // offer is a refusal, never a hand-built write.
+      if (effortOption && !value && effort !== '') {
+        return { ok: false, code: 'dsh_option_unavailable', message: REFUSAL_MESSAGES.dsh_option_unavailable };
+      }
+      if (effortOption && value) {
+        const result = await dshRuntime.setEffort(id, effort, { configId: effortOption.id, value });
+        if (!result || !result.ok) return { ok: false, code: result?.code || 'dsh_option_unavailable', message: REFUSAL_MESSAGES[result?.code] || REFUSAL_MESSAGES.dsh_option_unavailable };
+        written = true;
+      }
+    }
+    // A pick that carried neither a model nor an effort is a malformed request, not a success.
+    // (`request` already refuses that shape; this keeps the invariant local to the writer.)
+    if (!written && !modelId && effort !== '') return { ok: false, code: 'invalid_request', message: REFUSAL_MESSAGES.invalid_request };
+    return { ok: true };
+  }
+
+  /**
+   * A dsh model/effort pick. Validations run first and the entry is installed SYNCHRONOUSLY once the
+   * cheap refusals are out of the way, so two concurrent picks can never both reach the child.
+   * @returns {Promise<{ ok:true, request: object }|{ ok:false, status:number, code:string, message?:string }>}
+   */
+  async function request(sessionId, body) {
+    const id = String(sessionId || '');
+    const info = getSessionInfo(id);
+    // This controller is only ever reached for a dsh tab; anything else is the runtime's routing bug
+    // and the honest answer is the same 404 the router would have produced.
+    if (!info || info.agent !== 'dsh') return refusal(404, SESSION_NOT_FOUND);
+    const input = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+    // D-12: a dsh pick is in-place; a default-scope write is not something this tab offers.
+    if (input.scope === 'session+default') return refusal(400, 'invalid_scope');
+    if (input.scope !== 'session') return refusal(400, 'invalid_scope');
+    if (input.request_kind != null && !ACCEPTED_KINDS.has(String(input.request_kind))) {
+      return refusal(400, 'invalid_request_kind');
+    }
+    const modelId = typeof input.model_id === 'string' ? input.model_id : '';
+    if (modelId.length > MAX_MODEL_ID_LENGTH) return refusal(400, 'invalid_model_id');
+    const routeId = typeof input.route_id === 'string' ? input.route_id : '';
+    if (routeId.length > MAX_ROUTE_ID_LENGTH) return refusal(400, 'invalid_route_id');
+    const effortProvided = typeof input.effort === 'string';
+    const effort = effortProvided ? input.effort : null;
+    if (effortProvided && effort.length > MAX_EFFORT_LENGTH) return refusal(400, 'invalid_effort');
+    const clientRequestId = input.client_request_id;
+    if (typeof clientRequestId !== 'string' || !clientRequestId.length
+        || clientRequestId.length > MAX_CLIENT_REQUEST_ID_LENGTH) {
+      return refusal(400, 'invalid_request');
+    }
+    if (!modelId && !effortProvided) return refusal(400, 'invalid_model_id');
+    const session = typeof getSession === 'function' ? getSession(id) : null;
+    if (!session) return refusal(404, SESSION_NOT_FOUND);
+    // A parked/childless tab has no ACP child to write to; the honest answer is `not_live`.
+    if (typeof dshRuntime?.isRunning !== 'function' || !dshRuntime.isRunning(id) || session._restoreDeferred === true) {
+      return refusal(409, 'not_live');
+    }
+    // R-3's CAS token, read the same way OpenCode reads it: absent = satisfied.
+    if (String(input.expected_process_generation ?? '') !== '' && String(input.expected_process_generation) !== String(info.processGeneration)) {
+      return refusal(409, 'model_owner_changed');
+    }
+    // Idempotent replay of the SAME request, or a pick already being applied.
+    const existing = entries.get(id);
+    if (existing && existing.req.client_request_id === clientRequestId) {
+      return { ok: true, request: publicSessionModelRequest(existing.req) };
+    }
+    if (existing && existing.req.state === FLIGHT_KEY) return refusal(409, 'lead_switch_in_flight');
+    // The bridge admits ONE in-flight prompt per session, so a write now would be refused by the
+    // child anyway; refuse it here, with the same code, BEFORE installing an entry (nothing queued).
+    if (turnInFlight(id)) return refusal(409, 'dsh_turn_in_flight');
+
+    const entry = {
+      req: {
+        id: newId(), ctm_session_id: id, client_request_id: clientRequestId, agent: 'dsh',
+        model_id: modelId, effort: effortProvided ? effort : null, effort_only: !modelId, scope: 'session',
+        ...(routeId ? { route_id: routeId } : {}),
+        state: FLIGHT_KEY, phase: FLIGHT_KEY, reason: null, detail: '', cancellable: false,
+        requested_at: now(), relaunched_at: null, settled_at: null,
+        observed_model: null, observed_effort: null, observed_source: null,
+      },
+    };
+    // Installed SYNCHRONOUSLY, before any await: a second request arriving in the same tick sees it
+    // (and is told `lead_switch_in_flight`). NOT broadcast yet — a refusal below withdraws it quietly.
+    entries.set(id, entry);
+
+    // D-12: the route the child is ACTUALLY on, held in memory only (non-enumerable, never persisted).
+    const currentAlias = (session._dshRoute && session._dshRoute.alias) || null;
+    const crossRoute = !!routeId && routeId !== currentAlias;
+    let result;
+    try {
+      result = crossRoute
+        ? await dshSession.relaunchDshSession(session, { routeAlias: routeId, model: modelId || null })
+        : await applyInPlace(id, { modelId, effortProvided, effort });
+    } catch (error) {
+      // A throw here is a bug in one of the two paths, and the honest ending is a failed request
+      // rather than an entry that stays `relaunching` forever (which would block this tab).
+      result = { ok: false, code: 'dsh_start_failed', message: (error && error.message) || REFUSAL_MESSAGES.dsh_start_failed };
+    }
+    if (entries.get(id) !== entry) return refusal(409, 'lead_switch_in_flight');
+    if (!result || !result.ok) {
+      const code = (result && result.code) || 'dsh_option_unavailable';
+      settleEntry(entry, 'failed', code, (result && result.message) || REFUSAL_MESSAGES[code] || '');
+      // A malformed request is the caller's fault (400); anything the BRIDGE refused — a busy turn, an
+      // option it does not offer, a restart that did not come up — is a state conflict (409).
+      const malformed = code === 'invalid_request' || code === 'invalid_model_id' || code === 'invalid_effort';
+      return refusal(malformed ? 400 : 409, code, { request: publicSessionModelRequest(entry.req) });
+    }
+    const observed = dshSession.modelIdFromConfigOptions(configOptionsFor(id));
+    entry.req.observed_model = observed || null;
+    entry.req.observed_source = 'dsh:config-option';
+    entry.req.observed_effort = dshSession.effortFromConfigOptions(configOptionsFor(id)) || null;
+    if (crossRoute) entry.req.relaunched_at = now();
+    // The durable route record is the dsh startup task relaunchDshSession just rewrote
+    // (persistDshRouteAlias); the lead-route store is claude/codex-only and is not used for dsh.
+    settleEntry(entry, APPLIED_STATE, null, '');
+    return { ok: true, request: publicSessionModelRequest(entry.req) };
+  }
+
+  /** The public request for this tab, or null. dsh settles from the RPC reply, so nothing polls. */
+  function get(sessionId) {
+    const entry = entries.get(String(sessionId || ''));
+    return entry ? publicSessionModelRequest(entry.req) : null;
+  }
+
+  /** Cancelling an unconfirmed switch abandons the REQUEST; the child keeps whatever it already applied. */
+  function cancel(sessionId) {
+    const entry = entries.get(String(sessionId || ''));
+    if (!entry || entry.req.state !== FLIGHT_KEY) {
+      return refusal(409, 'lead_switch_not_cancellable');
+    }
+    settleEntry(entry, 'cancelled', null, '');
+    return { ok: true, request: publicSessionModelRequest(entry.req) };
+  }
+
+  /**
+   * A model observation for this tab arrived. Nothing to do: a dsh pick is confirmed from the
+   * `session/set_config_option` reply itself (D-13), so there is no `awaiting_turn` state to settle.
+   * Kept because the runtime calls it on every status edge for every controller it routes.
+   */
+  function notifyObservation() {}
+
+  return { request, get, cancel, notifyObservation };
+}
+
+module.exports = { createDshLaunchModel, DSH_LAUNCH_REFUSAL_MESSAGES: REFUSAL_MESSAGES };

package/template/coding-task-manager/lib/acp/dsh-mcp-servers.js

@@ -0,0 +1,194 @@
+'use strict';
+
+// WP-10 step A (docs/deepseek-harness-acp-agent-2026-10-28.html §5 C-6, §6.6 D-16, §9b P-1/P-2,
+// §10 T-21/T-27; OQ-12's MCP half).
+//
+// CTM's ONE normalized MCP server shape (lib/mcp-annotations.js `parseJsonMcpServers`:
+// `{name, command, args, env, url, type}`) -> the ACP `mcpServers` entries a dsh (`--profile acp`)
+// child accepts on `session/new` / `session/resume` (lib/acp/acp-client.js takes them already).
+//
+// dsh validates the list itself before it publishes the tools (the rules below were read out of the
+// packed 0.2.1-rc.2 build's `resolveMcpConfigs`; the OQ-12 step-1 measurement is recorded in the
+// WP-10 report):
+//
+//   * a stdio entry is one WITHOUT a `type` key, and its `command` MUST be absolute --
+//     `if (!("type" in server)) { if (!isAbsolute(server.command)) throw new AcpMcpConfigError(
+//     \`mcpServers[${index}].command must be an absolute path\`) }`;
+//   * `http` is the only other accepted `type`; any other transport (including `sse`) throws
+//     `mcpServers[i] transport <type> is not supported`;
+//   * `env`/`headers` are ordered `[{name, value}]` and a repeated name throws;
+//   * the list is unique after dsh's own name normalization.
+//
+// A declaration dsh would refuse is DROPPED here with ONE log line instead of failing the whole
+// session start: one unusable server must not cost the session its other tools. Every log line names
+// the SERVER and the REASON only -- never an env or header VALUE, so a credential can never reach
+// CTM's logs from this module.
+//
+// PURE: no fs, no child_process, no env reads (main-thread lint scans lib/** and this module runs on
+// the interactive create/restore path). The caller passes the token in; the entries carry it.
+
+const path = require('node:path');
+
+// dsh's own name contract: VALID_SERVER_NAME (a longer/invalid name is normalized by dsh, NOT
+// fatal) plus the fatal control-character rule from normalizeServerName.
+const CONTROL_CHARS_RE = /[\u0000-\u001f\u007f]/;
+
+const STDIO_TYPE = 'stdio';
+const HTTP_TYPE = 'http';
+const SSE_TYPE = 'sse';
+
+const WALL_E_SERVER_NAME = 'wall-e';
+const CTM_SESSION_ID_ENV = 'CTM_SESSION_ID';
+const WALL_E_API_TOKEN_ENV = 'WALL_E_API_TOKEN';
+
+function logLine(log, message) {
+  if (typeof log !== 'function') return;
+  try {
+    log(message);
+  } catch (error) {
+    // expected: a broken log sink must never cost a session its MCP servers.
+    void error;
+  }
+}
+
+// An array of specs, or CTM's name-keyed object (parseJsonMcpServers's shape) -> [{key, spec}].
+function entriesOf(servers) {
+  if (Array.isArray(servers)) return servers.map((spec) => ({ key: '', spec }));
+  if (servers && typeof servers === 'object') {
+    return Object.entries(servers).map(([key, spec]) => ({ key, spec }));
+  }
+  return [];
+}
+
+// The entry's name: its own `name` when set, else the object key it was filed under.
+function serverNameOf(entry) {
+  const spec = entry && entry.spec && typeof entry.spec === 'object' ? entry.spec : {};
+  const named = typeof spec.name === 'string' && spec.name.trim() ? spec.name : '';
+  return (named || String((entry && entry.key) || '')).trim();
+}
+
+// An object map (`{KEY: 'value'}` -- CTM's normalized shape) or an ordered ACP `[{name, value}]`
+// list -> ACP's ordered entries. The first occurrence of a name wins (dsh throws on a repeat);
+// a non-string value is stringified rather than dropped.
+function toNameValueEntries(source) {
+  const out = [];
+  const seen = new Set();
+  const push = (name, value) => {
+    if (typeof name !== 'string' || !name || seen.has(name)) return;
+    seen.add(name);
+    out.push({ name, value: typeof value === 'string' ? value : String(value == null ? '' : value) });
+  };
+  if (Array.isArray(source)) {
+    for (const item of source) {
+      if (item && typeof item === 'object') push(item.name, item.value);
+    }
+  } else if (source && typeof source === 'object') {
+    for (const [name, value] of Object.entries(source)) push(name, value);
+  }
+  return out;
+}
+
+// ONE normalized spec -> ONE ACP entry, or a refusal reason (never a value).
+function convertOne(name, spec) {
+  const type = typeof spec.type === 'string' ? spec.type.trim().toLowerCase() : '';
+  const url = typeof spec.url === 'string' ? spec.url.trim() : '';
+  const command = typeof spec.command === 'string' ? spec.command.trim() : '';
+  // dsh's own branch: no `type` key means stdio. A config that spells `type: 'stdio'` (the Claude
+  // shape in ~/.claude.json) means the same thing here and is normalized to the type-less form.
+  if (type === '' || type === STDIO_TYPE) {
+    if (url && !command) return { ok: false, reason: 'no command (a url without type "http" cannot be forwarded)' };
+    if (!command) return { ok: false, reason: 'no command' };
+    if (!path.isAbsolute(command)) return { ok: false, reason: 'command is not an absolute path' };
+    return {
+      ok: true,
+      // NO `type` key: dsh's stdio branch is the ABSENCE of `type`, and an explicit 'stdio' would
+      // trip its "transport stdio is not supported" refusal.
+      entry: { name, command, args: Array.isArray(spec.args) ? spec.args.map(String) : [], env: toNameValueEntries(spec.env) },
+    };
+  }
+  if (type === HTTP_TYPE) {
+    if (!url) return { ok: false, reason: 'no url' };
+    return { ok: true, entry: { type: HTTP_TYPE, name, url, headers: toNameValueEntries(spec.headers) } };
+  }
+  if (type === SSE_TYPE) return { ok: false, reason: 'sse transport is not supported by dsh' };
+  return { ok: false, reason: `transport ${type} is not supported by dsh` };
+}
+
+/**
+ * CTM's normalized MCP servers -> the ACP `mcpServers` list for `session/new`/`session/resume`.
+ *
+ * ORDER IS PRESERVED (array order, or the object's own key order) and the FIRST of any duplicate
+ * name wins. Every dropped declaration is reported once, by name and reason.
+ *
+ * @param {object|Array<object>} servers  name-keyed map or array of `{name, command, args, env, url, type}`
+ * @param {{log?: (message: string) => void}} [options]
+ * @returns {Array<object>} ACP entries: stdio `{name, command, args, env}` / http `{type:'http', name, url, headers}`
+ */
+function toAcpMcpServers(servers, { log } = {}) {
+  const out = [];
+  const seen = new Set();
+  for (const item of entriesOf(servers)) {
+    const spec = item && item.spec && typeof item.spec === 'object' ? item.spec : {};
+    const name = serverNameOf(item);
+    if (!name) {
+      logLine(log, 'dsh-mcp: dropping an MCP server with no name');
+      continue;
+    }
+    if (CONTROL_CHARS_RE.test(name)) {
+      logLine(log, 'dsh-mcp: dropping an MCP server whose name contains control characters');
+      continue;
+    }
+    if (seen.has(name)) {
+      logLine(log, `dsh-mcp: dropping duplicate MCP server "${name}" (first one wins)`);
+      continue;
+    }
+    const converted = convertOne(name, spec);
+    if (!converted.ok) {
+      logLine(log, `dsh-mcp: dropping MCP server "${name}": ${converted.reason}`);
+      continue;
+    }
+    seen.add(name);
+    out.push(converted.entry);
+  }
+  return out;
+}
+
+/**
+ * Stamp the Wall-E MCP stdio entry with the caller identity its stdio proxy authenticates with
+ * (`wall-e/lib/stdio-proxy-env.js`'s STDIO_PROXY_CALLER_ENV: `CTM_SESSION_ID`, `WALL_E_API_TOKEN`).
+ *
+ * The values are placed in the entry's `env`, i.e. they travel ONLY inside the ACP
+ * `session/new`/`session/resume` JSON-RPC request on the child's stdin -- never on argv, never in a
+ * file, never in CTM's own child env, never in a log line.
+ *
+ * Values for the SAME two keys are replaced; an empty value is not written at all (a stale value
+ * already in the user's own config is left alone rather than blanked to '').
+ *
+ * @param {Array<object>} entries  the list `toAcpMcpServers` returned
+ * @param {{ctmSessionId?: string, walleToken?: string}} caller
+ * @returns {Array<object>} a NEW list; every entry that is not the stdio `wall-e` server is untouched
+ */
+function withWalleCaller(entries, { ctmSessionId = '', walleToken = '' } = {}) {
+  const list = Array.isArray(entries) ? entries : [];
+  return list.map((entry) => {
+    if (!entry || typeof entry !== 'object' || entry.type || entry.name !== WALL_E_SERVER_NAME) return entry;
+    const env = Array.isArray(entry.env) ? [...entry.env] : [];
+    const set = (name, value) => {
+      if (!value) return;
+      const at = env.findIndex((item) => item && item.name === name);
+      if (at >= 0) env[at] = { name, value };
+      else env.push({ name, value });
+    };
+    set(CTM_SESSION_ID_ENV, String(ctmSessionId || ''));
+    set(WALL_E_API_TOKEN_ENV, String(walleToken || ''));
+    return { ...entry, env };
+  });
+}
+
+module.exports = {
+  toAcpMcpServers,
+  withWalleCaller,
+  WALL_E_SERVER_NAME,
+  CTM_SESSION_ID_ENV,
+  WALL_E_API_TOKEN_ENV,
+};