create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/acp/acp-client.js

@@ -0,0 +1,383 @@
+'use strict';
+
+// ACP v1 client (Agent Client Protocol, JSON-RPC 2.0 over an ND-JSON stdio transport).
+//
+// WP-1 of docs/deepseek-harness-acp-agent-2026-10-28.html (§6.2, decisions D-5, D-6, D-7).
+// It is deliberately hand-written and CommonJS: @agentclientprotocol/sdk is ESM-only,
+// removed its client class in v2.0.0 and CTM needs eight methods (D-6 in the decision
+// table). The client owns id correlation, timeouts, the server-request door
+// (session/request_permission) and the capability gate; it renders nothing and knows
+// nothing about transcripts, sessions or the server — WP-2..WP-5 wire those in.
+//
+// UNWIRED: no non-test module requires this file yet (AC-1c).
+//
+// Wire rules:
+//   * every outgoing message carries jsonrpc:'2.0';
+//   * request ids are a per-client monotonically increasing integer starting at 1;
+//   * an unparsable line is logged (truncated to 200 chars) and dropped — never fatal;
+//   * every server request is answered exactly once (P-4), including on cancel/dispose;
+//   * session/prompt has no client timeout — it settles when the turn settles.
+
+const ACP_PROTOCOL_VERSION = 1;
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+const MAX_LOGGED_LINE_CHARS = 200;
+
+/** An ACP-layer failure. `code` is the stable machine token, `data` the structured detail. */
+class AcpError extends Error {
+  constructor(code, data) {
+    // The message always names the machine code; the first human-readable field of `data`
+    // (upstream message, RPC method, or the reason) is appended so a bare log line still
+    // says which method timed out and why a handshake was refused.
+    const detail = ['message', 'method', 'reason']
+      .map((key) => (data && typeof data[key] === 'string' ? data[key] : ''))
+      .find((value) => value !== '');
+    super(detail ? `${code}: ${detail}` : code);
+    this.name = 'AcpError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {{write, onLine, onExit}} opts.transport
+ * @param {(sessionId: string, update: object) => void} [opts.onSessionUpdate]
+ * @param {(params: {sessionId: string, toolCall: object, options: object[]}) =>
+ *          Promise<{outcome: 'selected', optionId: string} | {outcome: 'cancelled'}>} [opts.onRequestPermission]
+ * @param {(entry: {level: 'warn'|'info', msg: string}) => void} [opts.log]   // default no-op
+ * @param {number} [opts.requestTimeoutMs=DEFAULT_REQUEST_TIMEOUT_MS]
+ * @param {{name: string, version: string}} [opts.clientInfo={name:'ctm', version:'1'}]
+ */
+function createAcpClient(opts = {}) {
+  const {
+    transport,
+    onSessionUpdate = () => {},
+    onRequestPermission = async () => ({ outcome: 'cancelled' }),
+    log = () => {},
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+    clientInfo = { name: 'ctm', version: '1' },
+  } = opts;
+  if (!transport) throw new Error('createAcpClient: transport required');
+
+  let nextId = 1;
+  let disposedError = null;
+  let lastInitializeResult = null;
+  const pending = new Map();              // id → { method, resolve, reject, timer, settled }
+  const permissions = new Map();          // id → { id, sessionId, answered }
+  const permissionsBySession = new Map(); // sessionId → Set<id>
+
+  const send = (obj) => transport.write(JSON.stringify(obj));
+
+  function truncate(line) {
+    return line.length > MAX_LOGGED_LINE_CHARS ? line.slice(0, MAX_LOGGED_LINE_CHARS) : line;
+  }
+
+  function request(method, params, timeoutOverride) {
+    return new Promise((resolve, reject) => {
+      if (disposedError) {
+        reject(disposedError);
+        return;
+      }
+      const id = nextId++;
+      const entry = { method, resolve, reject, timer: null, settled: false };
+      pending.set(id, entry);
+      const timeoutMs = timeoutOverride === undefined ? requestTimeoutMs : timeoutOverride;
+      if (typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs >= 0) {
+        entry.timer = setTimeout(() => {
+          if (entry.settled) return;
+          entry.settled = true;
+          pending.delete(id);
+          reject(new AcpError('acp_request_timeout', { method }));
+        }, timeoutMs);
+      }
+      send({ jsonrpc: '2.0', id, method, params: params || {} });
+    });
+  }
+
+  function notify(method, params) {
+    send({ jsonrpc: '2.0', method, params: params || {} });
+  }
+
+  function settleResponse(id, msg) {
+    const entry = pending.get(id);
+    if (!entry) {
+      // Late (already timed out) or unknown — dropped, never fatal (D-5).
+      log({ level: 'warn', msg: `acp-client: dropped response for unknown or settled id ${id}` });
+      return;
+    }
+    pending.delete(id);
+    entry.settled = true;
+    if (entry.timer) {
+      clearTimeout(entry.timer);
+      entry.timer = null;
+    }
+    if (msg.error != null) {
+      entry.reject(new AcpError('acp_rpc_error', {
+        rpcCode: msg.error.code,
+        message: msg.error.message,
+        method: entry.method,
+      }));
+      return;
+    }
+    entry.resolve(msg.result);
+  }
+
+  // --- permissions (D-7, P-4) -------------------------------------------------
+
+  // The record handed in is the same object the handler's late resolution closes over, so
+  // "answered exactly once" is decided by one shared flag (P-4).
+  function trackPermission(record) {
+    permissions.set(record.id, record);
+    let ids = permissionsBySession.get(record.sessionId);
+    if (!ids) {
+      ids = new Set();
+      permissionsBySession.set(record.sessionId, ids);
+    }
+    ids.add(record.id);
+  }
+
+  function releasePermission(record) {
+    permissions.delete(record.id);
+    const ids = permissionsBySession.get(record.sessionId);
+    if (ids) {
+      ids.delete(record.id);
+      if (ids.size === 0) permissionsBySession.delete(record.sessionId);
+    }
+  }
+
+  // The returned object is {outcome:'selected', optionId} or {outcome:'cancelled'}.
+  function normaliseOutcome(outcome) {
+    if (outcome && typeof outcome === 'object' && typeof outcome.outcome === 'string') return outcome;
+    return { outcome: 'cancelled' };
+  }
+
+  function answerPermission(record, outcome) {
+    if (record.answered) return false;
+    record.answered = true;
+    releasePermission(record);
+    send({ jsonrpc: '2.0', id: record.id, result: { outcome } });
+    return true;
+  }
+
+  function handlePermissionRequest(msg) {
+    const params = msg.params || {};
+    const sessionId = params.sessionId;
+    const record = { id: msg.id, sessionId, answered: false };
+    trackPermission(record);
+    const answer = (outcome) => answerPermission(record, normaliseOutcome(outcome));
+    let result;
+    try {
+      result = onRequestPermission({
+        sessionId,
+        toolCall: params.toolCall,
+        options: params.options,
+      });
+    } catch (error) {
+      log({ level: 'warn', msg: `acp-client: permission handler threw (${error && error.message})` });
+      answer({ outcome: 'cancelled' });
+      return;
+    }
+    Promise.resolve(result).then(
+      (outcome) => { answer(outcome); },
+      (error) => {
+        if (record.answered) return;
+        log({ level: 'warn', msg: `acp-client: permission handler rejected (${error && error.message})` });
+        answer({ outcome: 'cancelled' });
+      },
+    );
+  }
+
+  // Settles every pending permission for one session as 'cancelled'. Returns the count.
+  function cancelSessionPermissions(sessionId) {
+    const ids = permissionsBySession.get(sessionId);
+    if (!ids) return 0;
+    let settled = 0;
+    for (const id of [...ids]) {
+      const record = permissions.get(id);
+      if (record && answerPermission(record, { outcome: 'cancelled' })) settled += 1;
+    }
+    return settled;
+  }
+
+  function disposeInternal(error) {
+    if (disposedError) return;
+    // P-4: every server request is answered exactly once, including on cancel/dispose.
+    for (const record of [...permissions.values()]) {
+      answerPermission(record, { outcome: 'cancelled' });
+    }
+    disposedError = error;
+    for (const [id, entry] of [...pending]) {
+      if (entry.timer) {
+        clearTimeout(entry.timer);
+        entry.timer = null;
+      }
+      entry.settled = true;
+      pending.delete(id);
+      entry.reject(error);
+    }
+  }
+
+  // --- inbound line classification (D-5/D-6/D-7) -------------------------------
+
+  function handleServerRequest(msg) {
+    if (msg.method === 'session/request_permission') {
+      handlePermissionRequest(msg);
+      return;
+    }
+    send({ jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: 'Method not found' } });
+  }
+
+  function handleNotification(msg) {
+    if (msg.method === 'session/update') {
+      const params = msg.params || {};
+      try {
+        onSessionUpdate(params.sessionId, params.update);
+      } catch (error) {
+        // A throwing observer must not break the read loop (updates stay in arrival order).
+        log({ level: 'warn', msg: `acp-client: onSessionUpdate threw (${error && error.message})` });
+      }
+      return;
+    }
+    log({ level: 'info', msg: `acp-client: unhandled notification ${msg.method}` });
+  }
+
+  function handleLine(line) {
+    if (disposedError) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch (error) {
+      log({ level: 'warn', msg: `acp-client: unparsable line (${line.length} chars): ${truncate(line)}` });
+      void error;
+      return;
+    }
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) {
+      log({ level: 'warn', msg: `acp-client: non-object message dropped: ${truncate(line)}` });
+      return;
+    }
+    // 1) a response to one of OUR requests — id != null, never truthiness (id 0 is legal).
+    if (msg.id != null && (Object.prototype.hasOwnProperty.call(msg, 'result') || msg.error != null)) {
+      settleResponse(msg.id, msg);
+      return;
+    }
+    // 2) a SERVER-initiated request — approvals live here.
+    if (msg.id != null && typeof msg.method === 'string') {
+      handleServerRequest(msg);
+      return;
+    }
+    // 3) a notification (method, no id).
+    if (typeof msg.method === 'string') {
+      handleNotification(msg);
+      return;
+    }
+    log({ level: 'warn', msg: `acp-client: unrecognised message dropped: ${truncate(line)}` });
+  }
+
+  transport.onLine(handleLine);
+  if (typeof transport.onExit === 'function') {
+    transport.onExit((info) => {
+      disposeInternal(new AcpError('acp_child_exited', {
+        exitCode: info && info.code !== undefined ? info.code : null,
+        signal: info && info.signal !== undefined ? info.signal : null,
+      }));
+    });
+  }
+
+  // --- capability gate (D-6) ---------------------------------------------------
+
+  function incompatibilityReason(result) {
+    if (!result || typeof result !== 'object') return 'initialize returned no result';
+    if (result.protocolVersion !== ACP_PROTOCOL_VERSION) {
+      return `protocolVersion ${JSON.stringify(result.protocolVersion)} is not ${ACP_PROTOCOL_VERSION}`;
+    }
+    if (!result.agentCapabilities || !result.agentCapabilities.sessionCapabilities
+      || !result.agentCapabilities.sessionCapabilities.resume) {
+      return 'agentCapabilities.sessionCapabilities.resume is missing';
+    }
+    return null;
+  }
+
+  async function initialize() {
+    const result = await request('initialize', {
+      protocolVersion: ACP_PROTOCOL_VERSION,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      clientInfo,
+    });
+    const reason = incompatibilityReason(result);
+    if (reason) throw new AcpError('dsh_acp_incompatible', { reason });
+    lastInitializeResult = result;
+    return result;
+  }
+
+  async function newSession({ cwd, mcpServers = [] } = {}) {
+    return request('session/new', { cwd, mcpServers });
+  }
+
+  async function resumeSession({ sessionId, cwd, mcpServers = [] } = {}) {
+    return request('session/resume', { sessionId, cwd, mcpServers });
+  }
+
+  async function listSessions({ cwd } = {}) {
+    return request('session/list', { cwd });
+  }
+
+  // session/prompt carries no client timeout: it settles when the turn settles.
+  async function prompt({ sessionId, text, blocks } = {}) {
+    const promptBlocks = Array.isArray(blocks) ? blocks : [{ type: 'text', text }];
+    try {
+      return await request('session/prompt', { sessionId, prompt: promptBlocks }, null);
+    } catch (error) {
+      if (error instanceof AcpError && error.code === 'acp_rpc_error') {
+        throw new AcpError('acp_turn_failed', {
+          rpcCode: error.data && error.data.rpcCode,
+          message: error.data && error.data.message,
+        });
+      }
+      throw error;
+    }
+  }
+
+  // A notification; also settles this session's pending permissions 'cancelled' (P-4).
+  // Returns how many permissions it answered. Throws once the client is disposed.
+  function cancel({ sessionId } = {}) {
+    if (disposedError) throw disposedError;
+    notify('session/cancel', { sessionId });
+    return cancelSessionPermissions(sessionId);
+  }
+
+  async function closeSession({ sessionId } = {}) {
+    return request('session/close', { sessionId });
+  }
+
+  async function setConfigOption({ sessionId, configId, value } = {}) {
+    return request('session/set_config_option', { sessionId, configId, value });
+  }
+
+  function capabilities() {
+    return lastInitializeResult;
+  }
+
+  function dispose(reason) {
+    disposeInternal(new AcpError('acp_disposed', { reason }));
+  }
+
+  return {
+    initialize,
+    newSession,
+    resumeSession,
+    listSessions,
+    prompt,
+    cancel,
+    closeSession,
+    setConfigOption,
+    capabilities,
+    dispose,
+  };
+}
+
+module.exports = {
+  createAcpClient,
+  AcpError,
+  ACP_PROTOCOL_VERSION,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+};

package/template/coding-task-manager/lib/acp/dsh-context-truth.js

@@ -0,0 +1,176 @@
+'use strict';
+
+// WP-9 step 1 — the DeepSeek Harness context chip (design
+// docs/deepseek-harness-acp-agent-2026-10-28.html §9b C-1/C-2, §5 D-18, T-19).
+//
+// A dsh session's ACP child emits one `session/update` per model response carrying
+// `{ sessionUpdate: 'usage_update', used, size }` — the tokens currently in the model's context and the
+// context window (see tests/fixtures/acp/dsh-0.2.1-rc.2-turn.jsonl). Nothing in CTM read them, so a dsh
+// tab's context chip stayed empty.
+//
+// This module turns each one into runtime context truth over the SAME durable channel a WALL-E coding
+// session uses (`_recordWalleUsageSnapshotRuntimeTruth`, server.js) — and keeps the chip's badge value on
+// the session, so the request-safe (lightweight) broadcast can serve it with no DB read, no transcript
+// append and no reload. Rules, mirroring that precedent:
+//   * only `sessionUpdate === 'usage_update'` is considered;
+//   * `used`/`size` must be non-negative integers, and `used <= 0` is ignored — a 0/0 row must never
+//     stamp over a good prior value;
+//   * an identical repeat for the same session writes nothing (per-session signature);
+//   * ACP carries NO cumulative per-request token count, so `totalTokens` is omitted rather than
+//     invented (`buildRuntimeTokenUsagePayload` resolves a missing total to 0 — the honest "unknown"
+//     for a harness whose wire has context occupancy only) and no cost is ever recorded;
+//   * a recording failure is REPORTED via `recordDiagnostic` and never thrown into the ACP read loop.
+//   * no session_tokens write: db.updateSessionTokens drops an exact write with no cumulative total
+//     (db.js exact/zero-total guard), and ACP has none — the chip reads runtime truth instead.
+
+const { formatTokens } = require('../session-token-usage');
+
+// The `source` stamped on every runtime-truth row this module writes (D-18).
+const DSH_CONTEXT_SOURCE = 'dsh-usage-update';
+
+function _nonNegativeInt(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return null;
+  return Math.round(n);
+}
+
+function _message(error) {
+  return error && error.message ? String(error.message) : String(error || '');
+}
+
+/**
+ * The badge the chip renders for a dsh session, derived ONLY from what the harness reported.
+ *
+ * Field names follow lib/runtime-context-truth.js's public token summary (`ctx`/`window`/`ctxWindow`/
+ * `label`/`ctxPct`/...) so the client chip reads it exactly like a provider-transcript summary or a
+ * runtime-truth row — no client change is needed (D-18 "no chip code changes").
+ *
+ * @param {{contextTokens?: number, contextWindow?: number, model?: string, createdAtMs?: number}} input
+ * @returns {object}
+ */
+function buildDshContextBadge(input = {}) {
+  const ctx = Math.max(0, Math.round(Number(input.contextTokens) || 0));
+  const window = Math.max(0, Math.round(Number(input.contextWindow) || 0));
+  const ctxPct = window > 0 ? Math.round((Math.min(ctx, window) / window) * 100) : null;
+  return {
+    // ACP has no per-request cumulative count: total stays an explicit 0, never a fabricated sum.
+    total: 0,
+    cumulativeTotal: 0,
+    cumulativeLabel: formatTokens(0),
+    totalLabel: formatTokens(0),
+    label: formatTokens(ctx),
+    contextLabel: formatTokens(ctx),
+    ctx,
+    contextTokens: ctx,
+    window,
+    ctxWindow: window,
+    ctxPct,
+    pctLeftNative: ctxPct == null ? null : Math.max(0, 100 - ctxPct),
+    exact: true,
+    headline: 'context',
+    fidelity: 'native',
+    suppressPct: false,
+    windowSource: 'acp-usage-update',
+    source: DSH_CONTEXT_SOURCE,
+    provider: 'dsh',
+    model: String(input.model || ''),
+    compacted: false,
+    created_at_ms: Math.max(0, Number(input.createdAtMs) || 0),
+    diagnostics: { runtimeTruth: true, truthSource: DSH_CONTEXT_SOURCE },
+  };
+}
+
+/**
+ * @param {object} deps
+ * @param {(db: object, input: object) => object|null} [deps.recordRuntimeTokenUsage] // lib/runtime-context-truth.js
+ * @param {object} [deps.db]                              // the owner db client the record is written through
+ * @param {(sessionId: string, event: string, details?: object) => void} [deps.recordDiagnostic]
+ * @param {() => number} [deps.now]
+ * @returns {{onUsageUpdate: (session: object, update: object) => object|null, badgeForSession: (session: object) => object|null}}
+ */
+function createDshContextTruth(deps = {}) {
+  const recordRuntimeTokenUsage = typeof deps.recordRuntimeTokenUsage === 'function' ? deps.recordRuntimeTokenUsage : null;
+  const db = deps.db || null;
+  const recordDiagnostic = typeof deps.recordDiagnostic === 'function' ? deps.recordDiagnostic : () => {};
+  const now = typeof deps.now === 'function' ? deps.now : () => Date.now();
+
+  // REPORT (never throw): a failed truth write must not break the ACP read loop.
+  function _report(session, error) {
+    if (!session || !session.id) return;
+    try {
+      recordDiagnostic(session.id, 'dsh-usage-runtime-truth-record-failed', { error: _message(error) });
+    } catch { /* expected: a diagnostic sink that throws is not this caller's problem */ } // HANDLE: the failure is already reported elsewhere; never re-enter the sink
+  }
+
+  /**
+   * Record one `usage_update` as runtime context truth and remember the chip badge on the session.
+   * Returns the badge when the update was accepted, `null` when it was ignored (not a usage update, a
+   * 0/0 snapshot, or an identical repeat). Never throws.
+   */
+  function onUsageUpdate(session, update) {
+    try {
+      if (!session || typeof session !== 'object' || !session.id) return null;
+      if (!update || typeof update !== 'object' || update.sessionUpdate !== 'usage_update') return null;
+      const contextTokens = _nonNegativeInt(update.used);
+      // The 0/0 guard (mirrors _recordWalleUsageSnapshotRuntimeTruth): a snapshot with no tokens in
+      // context would otherwise stamp a bogus "exact" row over a good prior value.
+      if (contextTokens == null || contextTokens <= 0) return null;
+      const windowHint = _nonNegativeInt(update.size);
+      const contextWindow = windowHint == null ? 0 : windowHint;
+      const model = String(session.model_id || session.model || '');
+      // Per-session signature: an identical repeat (same used/size/model) writes nothing at all.
+      const signature = [contextTokens, contextWindow, model].join(':');
+      if (session._dshUsageUpdateSig === signature) return null;
+      session._dshUsageUpdateSig = signature;
+      const createdAtMs = Math.max(0, Number(now()) || 0);
+      const badge = buildDshContextBadge({ contextTokens, contextWindow, model, createdAtMs });
+      session._dshContextBadge = badge;
+      const agentSessionId = String(
+        session.agentSessionId || session.chatSessionId || session._claudeSessionId || ''
+      );
+      if (recordRuntimeTokenUsage && db) {
+        try {
+          recordRuntimeTokenUsage(db, {
+            ctmSessionId: session.id,
+            agentSessionId,
+            adapter: 'dsh',
+            provider: 'dsh',
+            model: model || null,
+            // No totalTokens/cumulativeTotal: ACP's usage_update carries context occupancy only, so the
+            // honest cumulative value is "unknown", not a guessed sum. No cost field either (D-18).
+            contextTokens,
+            contextWindow,
+            exact: true,
+            source: DSH_CONTEXT_SOURCE,
+            createdAtMs,
+            idempotencyKey: `${DSH_CONTEXT_SOURCE}:${session.id}:${signature}`,
+          });
+        } catch (error) {
+          _report(session, error);
+        }
+      }
+      return badge;
+    } catch (error) {
+      _report(session, error);
+      return null;
+    }
+  }
+
+  // The chip's read seam for a dsh session: what the harness last told us, held in memory. The server's
+  // request-safe (lightweight) broadcast serves this FIRST — it is written the moment the ACP
+  // notification arrives, so it is always at least as fresh as the runtime truth the heartbeat batch
+  // primes — which is what makes a usage_update visible on the next debounced broadcast, with no DB
+  // read, no transcript append and no reload.
+  function badgeForSession(session) {
+    const badge = session && session._dshContextBadge;
+    return badge && typeof badge === 'object' ? badge : null;
+  }
+
+  return { onUsageUpdate, badgeForSession };
+}
+
+module.exports = {
+  DSH_CONTEXT_SOURCE,
+  buildDshContextBadge,
+  createDshContextTruth,
+};