create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/acp/dsh-route-patch.js

@@ -0,0 +1,308 @@
+'use strict';
+
+// WP-6 (docs/deepseek-harness-acp-agent-2026-10-28.html §5 D-11/D-21, §6.6, OQ-1/OQ-4/OQ-7).
+//
+// Routed model access for a `dsh` (DeepSeek Harness) conv session. dsh's own `deepseek-official`
+// provider wants a DeepSeek key CTM must never hold (P-5: keys live only in the proxy), so the child
+// is pointed at CTM's loopback model proxy instead:
+//
+//   * the non-secret provider config travels in a `--patch` YAML (mode 0600, NO secret) that declares
+//     pi-ai's BUILT-IN `anthropic` provider with `baseURL http://127.0.0.1:<proxyPort>/r/<alias>` and
+//     every model the route serves (§6.6, proven by OQ-1/OQ-7 against a header-logging stub);
+//   * the session token travels in the child ENVIRONMENT as `ANTHROPIC_AUTH_TOKEN` — the one thing
+//     pi-ai's built-in anthropic provider turns into `Authorization: Bearer …` (§3b OQ-1).
+//
+// The token is minted with the SAME supervisor call a routed Claude lead uses (`registerLeadToken`),
+// so a proxy restart that replays its in-memory lead registry keeps the session working (D-11), and it
+// is NEVER persisted to `session_lead_token`/`session_lead_route` — whose `agent` CHECK is
+// ('claude','codex') (lib/migrations/v46-session-lead-token.js). `releaseDshRoute` revokes it; the
+// patch file is evidence and is NEVER unlinked (D-10's spirit: CTM does not delete artifacts).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ANTHROPIC_MESSAGES_API = 'anthropic-messages';
+// The proxy derives a request's harness from its wire face (oauth-proxy.js `requestHarness`): a dsh
+// child speaks the anthropic-messages face, so its token binds the same harness a routed Claude lead
+// does. A distinct 'dsh-acp' harness (design D-21) would never match that face-derived tuple.
+const DSH_HARNESS = 'claude-code';
+// The literal a create payload may name to keep dsh on its OWN `deepseek-official` provider (no patch,
+// no token) — pre-WP-6 behaviour as an EXPLICIT opt-out, never a silent fallback (D-12).
+const DSH_OWN_KEY_ALIAS = 'dsh-own-key';
+// A dsh session has no PTY generation: a fresh create mints its one routed token at generation 1, and
+// a proxy restart replays that exact registration (D-11).
+const DSH_ROUTE_PROCESS_GENERATION = 1;
+// §6.6: the effort map is fixed (OQ-7) and its VALUES are the wire spellings the proxy accepts
+// (lib/model-proxy/routes.js REASONING_LEVELS low|medium|xhigh|off).
+const DSH_REASONING_EFFORTS = "reasoningEfforts: { off: null, low: low, high: medium, max: xhigh }";
+// OQ-4: today that is a Portkey-served route whose DeepSeek deployment speaks anthropic-messages.
+const DEEPSEEK_MODEL_RE = /deepseek/i;
+const PORTKEY_ALIAS_RE = /portkey/i;
+const READINESS_BUDGET_MS = 12000;
+const SAFE_YAML_ID_RE = /^[@A-Za-z0-9][A-Za-z0-9._:/@+-]{0,159}$/;
+const FACTS_REVISION_RE = /^[a-f0-9]{64}$/;
+
+function _message(error) {
+  return String((error && error.message) || error).slice(0, 200);
+}
+
+/**
+ * The exact directory naming the design fixes: `<dataDir>/dsh/patches/<ctmSessionId>.yml`.
+ * @param {string} ctmSessionId
+ * @param {string} dataDir
+ * @returns {string}
+ */
+function dshPatchPath(ctmSessionId, dataDir) {
+  return path.join(dataDir, 'dsh', 'patches', `${ctmSessionId}.yml`);
+}
+
+// The models a dsh child may send: the route's deployments on the anthropic-messages wire (D-21 —
+// pi-ai's Bearer path exists only on the built-in anthropic provider, so openai-* rows are not offered).
+function anthropicDeployments(row) {
+  const deployments = row && Array.isArray(row.model_deployments) ? row.model_deployments : [];
+  return deployments.filter((d) => d && d.protocol === ANTHROPIC_MESSAGES_API && typeof d.wireModelId === 'string');
+}
+
+function servesAnthropicMessages(row) {
+  const apis = row && Array.isArray(row.upstream_apis) ? row.upstream_apis : [];
+  return apis.includes(ANTHROPIC_MESSAGES_API) && anthropicDeployments(row).length > 0;
+}
+
+/**
+ * OQ-4 default: the first DeepSeek-model route that serves anthropic-messages, preferring a
+ * Portkey-served one. An explicitly named alias is honoured as long as the route serves dsh.
+ * @param {Array<object>} routes redacted route feed (oauth-proxy-supervisor.listWorkerRoutes())
+ * @param {string|null} routeAlias
+ * @returns {{ok:true, row:object}|{ok:false, reason:string, detail:string}}
+ */
+function selectDshRoute(routes, routeAlias) {
+  const rows = (Array.isArray(routes) ? routes : []).filter((row) => row && typeof row.id === 'string' && row.id);
+  if (routeAlias) {
+    const row = rows.find((candidate) => candidate.id === routeAlias);
+    if (!row) return { ok: false, reason: 'dsh_route_unavailable', detail: `unknown route alias: ${routeAlias}` };
+    if (row.enabled === false || row.enabled === 0) return { ok: false, reason: 'dsh_route_unavailable', detail: `route is disabled: ${routeAlias}` };
+    if (!servesAnthropicMessages(row)) {
+      return { ok: false, reason: 'dsh_route_unavailable', detail: `route "${routeAlias}" does not serve ${ANTHROPIC_MESSAGES_API}` };
+    }
+    return { ok: true, row };
+  }
+  const deepseekRoutes = rows
+    .filter(servesAnthropicMessages)
+    .filter((row) => anthropicDeployments(row).some((d) => DEEPSEEK_MODEL_RE.test(d.wireModelId)));
+  const chosen = deepseekRoutes.find((row) => PORTKEY_ALIAS_RE.test(row.id)) || deepseekRoutes[0];
+  if (!chosen) {
+    return {
+      ok: false,
+      reason: 'dsh_route_unavailable',
+      detail: `no route serves ${ANTHROPIC_MESSAGES_API} with a DeepSeek model`,
+    };
+  }
+  return { ok: true, row: chosen };
+}
+
+// The route's model the child runs: an explicit pick when given (and served), else the first
+// DeepSeek model, else the route's first anthropic-messages model.
+function pickDeployment(deployments, model) {
+  if (typeof model === 'string' && model) return deployments.find((d) => d.wireModelId === model) || null;
+  return deployments.find((d) => DEEPSEEK_MODEL_RE.test(d.wireModelId)) || deployments[0] || null;
+}
+
+function describeModel(deployment) {
+  const modalities = Array.isArray(deployment.inputModalities) ? deployment.inputModalities : [];
+  const reasoningLevels = Array.isArray(deployment.reasoningLevels) ? deployment.reasoningLevels : [];
+  return {
+    id: deployment.wireModelId,
+    contextWindow: Number.isSafeInteger(deployment.contextTokens) && deployment.contextTokens > 0 ? deployment.contextTokens : null,
+    acceptsImages: modalities.includes('image'),
+    reasoning: reasoningLevels.length > 0,
+  };
+}
+
+// §6.6's patch, byte for byte: no token, no key, no upstream URL — only the loopback base and the
+// model facts. `ctmSessionId` is part of the PATH, never of the content.
+function renderPatch({ alias, model, models, proxyPort }) {
+  const lines = [
+    '- id: llm-pi-ai',
+    '  config:',
+    '    providers:',
+    '      anthropic:',
+    `        baseURL: 'http://127.0.0.1:${proxyPort}/r/${alias}'`,
+    '        models:',
+  ];
+  for (const entry of models) {
+    lines.push(`          - id: '${entry.id}'`);
+    if (entry.contextWindow) lines.push(`            contextWindow: ${entry.contextWindow}`);
+    if (entry.acceptsImages) lines.push('            input: [text, image]');
+    if (entry.reasoning) lines.push(`            ${DSH_REASONING_EFFORTS}`);
+  }
+  lines.push('- id: acp');
+  lines.push(`  config: { provider: anthropic, model: '${model}' }`);
+  return `${lines.join('\n')}\n`;
+}
+
+async function writePatchFile(patchPath, content) {
+  await fs.promises.mkdir(path.dirname(patchPath), { recursive: true });
+  await fs.promises.writeFile(patchPath, content, { mode: 0o600 });
+  // `mode` on writeFile applies only at CREATION, so an id that is re-created over an existing file
+  // keeps whatever bits were there; re-assert so a patch is never group/world readable.
+  await fs.promises.chmod(patchPath, 0o600);
+}
+
+/**
+ * Prepare a routed dsh launch: resolve the route, run the same readiness sequence a routed lead runs,
+ * mint a lead token, and write the 0600 patch.
+ *
+ * @param {{ ctmSessionId: string, routeAlias?: string|null, model?: string|null, deps?: object }} opts
+ * @returns {Promise<{ok:true, patchPath:string|null, env:object, token:string|null, alias:string, model:string|null, ownKey?:boolean}
+ *                 | {ok:false, reason:string, detail?:string}>}
+ */
+async function prepareDshRoute({ ctmSessionId, routeAlias = null, model = null, deps = null } = {}) {
+  if (typeof ctmSessionId !== 'string' || !ctmSessionId) {
+    return { ok: false, reason: 'dsh_route_unavailable', detail: 'ctmSessionId is required' };
+  }
+  // Explicit opt-out: dsh keeps its own provider and CTM mints nothing (no patch, no token).
+  if (routeAlias === DSH_OWN_KEY_ALIAS) {
+    return { ok: true, ownKey: true, patchPath: null, env: {}, token: null, alias: DSH_OWN_KEY_ALIAS, model: model || null };
+  }
+  const d = deps || {};
+  // `readiness` is resolved through a thunk exactly as server.js hands it to a routed lead
+  // (server.js `readiness: () => …getLeadRouteReadiness()`): the singleton is created at boot by
+  // delegate-worker.configure, so reading it here — per create — is what keeps it from being null.
+  const readiness = typeof d.readiness === 'function' ? d.readiness() : d.readiness;
+  if (typeof d.listRoutes !== 'function' || !d.supervisor || !readiness || typeof d.getDataDir !== 'function') {
+    return { ok: false, reason: 'dsh_route_unavailable', detail: 'routed dsh dependencies are not configured' };
+  }
+  let routes;
+  try {
+    routes = await d.listRoutes();
+  } catch (error) {
+    return { ok: false, reason: 'dsh_route_unavailable', detail: `route feed failed: ${_message(error)}` };
+  }
+  const selected = selectDshRoute(routes, routeAlias);
+  if (!selected.ok) return selected;
+  const row = selected.row;
+  const deployments = anthropicDeployments(row);
+  const deployment = pickDeployment(deployments, model);
+  if (!deployment) {
+    return { ok: false, reason: 'dsh_model_unavailable', detail: `route "${row.id}" does not serve model "${model}" on ${ANTHROPIC_MESSAGES_API}` };
+  }
+  const factsRevision = deployment.factsRevision;
+  if (typeof factsRevision !== 'string' || !FACTS_REVISION_RE.test(factsRevision)) {
+    return { ok: false, reason: 'dsh_route_unavailable', detail: `route "${row.id}" has no model facts revision for "${deployment.wireModelId}"` };
+  }
+  // The patch is single-quoted YAML: an id outside the deployment grammar (quote, newline, whitespace)
+  // could break out of it, so it is refused rather than escaped.
+  const patchModels = deployments.map(describeModel);
+  if (!SAFE_YAML_ID_RE.test(row.id) || !SAFE_YAML_ID_RE.test(deployment.wireModelId)
+      || patchModels.some((entry) => !SAFE_YAML_ID_RE.test(entry.id))) {
+    return { ok: false, reason: 'dsh_route_unavailable', detail: `route "${row.id}" carries an identifier the patch cannot express` };
+  }
+  const proxyPort = typeof d.proxyPort === 'function' ? d.proxyPort() : d.proxyPort;
+  if (!Number.isSafeInteger(proxyPort) || proxyPort <= 0) {
+    return { ok: false, reason: 'proxy_unhealthy', detail: 'the model proxy port is unknown' };
+  }
+
+  // F-5 order, exactly as a routed lead runs it: health -> route push -> upstream probe, all inside
+  // the same budget. A readiness failure is a REFUSAL (D-12), never a silent downgrade to dsh's own key.
+  const supervisor = d.supervisor;
+  if (typeof supervisor.isRunning === 'function' && !supervisor.isRunning()) {
+    const started = supervisor.start();
+    if (started && started.ok === false) {
+      return { ok: false, reason: 'proxy_unhealthy', detail: `could not start oauth-proxy: ${started && started.error}` };
+    }
+  }
+  const startedAt = Date.now();
+  const remaining = () => READINESS_BUDGET_MS - (Date.now() - startedAt);
+  const baseUrl = String(row.base_url || row.baseUrl || '');
+  try {
+    await readiness.waitForProxyHealth(remaining());
+    await readiness.pushRoutesIfNeeded(row.id);
+  } catch (error) {
+    return { ok: false, reason: 'proxy_unhealthy', detail: _message(error) };
+  }
+  try {
+    await readiness.probeUpstream({ alias: row.id, baseUrl, budgetMs: Math.max(0, remaining()) });
+  } catch (error) {
+    return { ok: false, reason: 'probe_failed', detail: _message(error) };
+  }
+
+  let registration;
+  try {
+    registration = await supervisor.registerLeadToken({
+      ctmSessionId,
+      purpose: 'routed-primary',
+      delegateScope: true,
+      aliases: [row.id],
+      bindings: [{
+        alias: row.id,
+        wireModelId: deployment.wireModelId,
+        harness: DSH_HARNESS,
+        metadataRevision: factsRevision,
+      }],
+      processGeneration: DSH_ROUTE_PROCESS_GENERATION,
+      harness: DSH_HARNESS,
+      // WP-9 §9b L-2 (D-19): the mark that makes the proxy append one per-request usage row to
+      // <dataDir>/dsh-usage/<ctmSessionId>.jsonl for this session. ACP has no token counts on the wire,
+      // so this token IS the ledger's only source for dsh spend; every other lead registration omits it.
+      usageLog: 'dsh',
+    });
+  } catch (error) {
+    /* REPORT: registration refused by the supervisor's own validator; only its message is surfaced. */
+    return { ok: false, reason: 'token_failed', detail: _message(error) };
+  }
+  if (!registration || registration.ok !== true || typeof registration.token !== 'string') {
+    return { ok: false, reason: 'token_failed', detail: (registration && registration.reason) || 'registerLeadToken failed' };
+  }
+  const token = registration.token;
+  const patchPath = dshPatchPath(ctmSessionId, d.getDataDir());
+  const content = renderPatch({
+    alias: row.id,
+    model: deployment.wireModelId,
+    models: patchModels,
+    proxyPort,
+  });
+  try {
+    await writePatchFile(patchPath, content);
+  } catch (error) {
+    // A token with no child to use it is a leak: revoke before reporting the failure.
+    await releaseDshRoute({ ctmSessionId, token, deps: d });
+    return { ok: false, reason: 'patch_write_failed', detail: _message(error) };
+  }
+  return { ok: true, patchPath, env: { ANTHROPIC_AUTH_TOKEN: token }, token, alias: row.id, model: deployment.wireModelId };
+}
+
+/**
+ * Revoke a routed dsh token. Idempotent, never throws, and NEVER unlinks the patch file (it holds no
+ * secret — it is evidence of what the child was told).
+ * @param {{ ctmSessionId: string, token: string|null, deps?: object }} opts
+ * @returns {Promise<{ok:boolean, revoked:boolean, reason?:string}>}
+ */
+async function releaseDshRoute({ ctmSessionId, token, deps = null } = {}) {
+  void ctmSessionId;
+  if (typeof token !== 'string' || !token) return { ok: true, revoked: false };
+  const supervisor = deps && deps.supervisor;
+  if (!supervisor || typeof supervisor.revokeLeadToken !== 'function') {
+    return { ok: false, revoked: false, reason: 'release_unconfigured' };
+  }
+  try {
+    const result = await supervisor.revokeLeadToken(token);
+    return { ok: !(result === false || (result && result.ok === false)), revoked: true };
+  } catch (error) {
+    /* REPORT: the supervisor keeps a pending revoke obligation of its own; nothing is thrown here. */
+    return { ok: false, revoked: true, reason: _message(error) };
+  }
+}
+
+module.exports = {
+  DSH_HARNESS,
+  DSH_OWN_KEY_ALIAS,
+  DSH_ROUTE_PROCESS_GENERATION,
+  dshPatchPath,
+  selectDshRoute,
+  describeModel,
+  renderPatch,
+  prepareDshRoute,
+  releaseDshRoute,
+  servesAnthropicMessages,
+  anthropicDeployments,
+};