@hope_phenom/dsh-plugin-remote-use 0.0.0-stage → 0.2.24

package/lib/core/task-registry.js

@@ -0,0 +1,238 @@
+/**
+ * The host-side registry of remote runs.
+ *
+ * WHY THIS EXISTS: a remote run has no local child session, so DSH writes no
+ * `subagent/catalog` entry for it (DESIGN §2.2 C3). `list_agents` and
+ * `listChildren` therefore cannot see remote work at all. This registry is that
+ * missing visibility channel: the `remote_agents` tool reads it, and the host
+ * injects a summary of it into the model's runtime context so the model does not
+ * "forget" what it dispatched.
+ *
+ * State is in-memory plus an optional JSON snapshot, because a remote run is only
+ * meaningful while the process that owns the ACP connection is alive.
+ *
+ * @module dsh-plugin-remote-use/task-registry
+ */
+
+/** Terminal states settle a task; nothing may move it out of them. */
+const TERMINAL = new Set(['completed', 'error', 'aborted', 'refusal', 'max-tokens', 'cancelled'])
+
+/**
+ * How much of a settled task's answer to keep, in characters.
+ *
+ * WHY THIS EXISTS AT ALL: without it a background delegation was a dead end — the task ran,
+ * the state was visible, and the ANSWER was unreachable, because the registry kept progress
+ * metrics and nothing else (PITFALLS F15). A result you cannot read is not a result.
+ *
+ * WHY IT IS CAPPED: the registry lives for the whole process and holds up to `maxTasks` entries,
+ * so retention has to be bounded or a chatty worker grows it without limit. The cap is generous
+ * (64k chars is a long report) and truncation is REPORTED rather than silent, so a reader can
+ * tell "this is all of it" from "this is the first 64k".
+ */
+export const OUTPUT_LIMIT = 64_000
+
+/**
+ * @typedef {object} RemoteTask
+ * @property {string} taskId
+ * @property {string} peerId
+ * @property {string} label                 short human label from the delegation call
+ * @property {string} promptDigest          first N chars of the prompt, for display
+ * @property {string} cwd
+ * @property {string} state                 queued | running | <terminal>
+ * @property {number} startedAt
+ * @property {number} [endedAt]
+ * @property {string} [stopReason]
+ * @property {string} [diagnostic]
+ * @property {number} toolCallCount
+ * @property {string[]} recentTools         last few tool names, for at-a-glance status
+ * @property {boolean} waitingForApproval
+ * @property {{used:number,size:number}} [usage]
+ * @property {string} [output]              the worker's answer, capped at OUTPUT_LIMIT
+ * @property {number} [outputChars]         the answer's full length before capping
+ */
+
+/** @returns {string} a short, sortable, unique-enough task id */
+function makeTaskId() {
+  const t = Date.now().toString(36)
+  const r = Math.floor(Math.random() * 0x10000).toString(36).padStart(3, '0')
+  return `rtask_${t}_${r}`
+}
+
+export class TaskRegistry {
+  /** @param {{ maxTasks?: number, snapshotPath?: string, now?: () => number }} [opts] */
+  constructor(opts = {}) {
+    this.maxTasks = opts.maxTasks ?? 200
+    this.snapshotPath = opts.snapshotPath ?? ''
+    /** @type {Map<string, RemoteTask>} */
+    this.tasks = new Map()
+    this.now = opts.now ?? (() => Date.now())
+    this.seq = 0
+  }
+
+  /**
+   * Create a task in the `queued` state.
+   * @param {{ peerId: string, label?: string, prompt: string, cwd: string }} input
+   * @returns {RemoteTask}
+   */
+  create(input) {
+    this.#evict()
+    const task = {
+      taskId: makeTaskId(),
+      peerId: input.peerId,
+      label: input.label ?? '',
+      promptDigest: (input.prompt ?? '').slice(0, 160),
+      cwd: input.cwd ?? '',
+      state: 'queued',
+      startedAt: this.now(),
+      toolCallCount: 0,
+      recentTools: [],
+      waitingForApproval: false,
+    }
+    this.tasks.set(task.taskId, task)
+    return task
+  }
+
+  /** @param {string} taskId */
+  get(taskId) {
+    return this.tasks.get(taskId)
+  }
+
+  /** Mark a task as actually started (the worker accepted it). */
+  markRunning(taskId) {
+    const t = this.tasks.get(taskId)
+    if (t !== undefined && !TERMINAL.has(t.state)) t.state = 'running'
+    return t
+  }
+
+  /**
+   * Record one observed tool call.
+   * @param {string} taskId
+   * @param {string} toolName
+   */
+  noteToolCall(taskId, toolName) {
+    const t = this.tasks.get(taskId)
+    if (t === undefined) return
+    t.toolCallCount += 1
+    t.recentTools.push(toolName)
+    if (t.recentTools.length > 5) t.recentTools.shift()
+  }
+
+  /** @param {string} taskId */
+  setWaitingForApproval(taskId, waiting) {
+    const t = this.tasks.get(taskId)
+    if (t !== undefined) t.waitingForApproval = waiting === true
+  }
+
+  /** @param {string} taskId */
+  setUsage(taskId, usage) {
+    const t = this.tasks.get(taskId)
+    if (t !== undefined && usage !== undefined) t.usage = usage
+  }
+
+  /**
+   * Settle a task. The first settlement wins — a late ACP event must not reopen
+   * a finished task.
+   *
+   * `final.output` is the worker's answer text. It is the ONLY thing that makes a background
+   * delegation useful after the fact, so it is retained here rather than only being handed
+   * back through the provider's result promise (which a background caller has already
+   * stopped awaiting).
+   *
+   * @param {string} taskId
+   * @param {{ state: string, stopReason?: string, diagnostic?: string, output?: string }} final
+   */
+  settle(taskId, final) {
+    const t = this.tasks.get(taskId)
+    if (t === undefined) return t
+    if (TERMINAL.has(t.state)) return t
+    t.state = TERMINAL.has(final.state) ? final.state : 'error'
+    t.stopReason = final.stopReason ?? t.state
+    if (final.diagnostic !== undefined) t.diagnostic = final.diagnostic
+    if (typeof final.output === 'string' && final.output !== '') {
+      t.output = final.output.length > OUTPUT_LIMIT ? final.output.slice(0, OUTPUT_LIMIT) : final.output
+      t.outputChars = final.output.length
+    }
+    t.endedAt = this.now()
+    t.waitingForApproval = false
+    return t
+  }
+
+  /** @returns {RemoteTask[]} newest first */
+  list() {
+    return [...this.tasks.values()].sort((a, b) => b.startedAt - a.startedAt)
+  }
+
+  /**
+   * Tasks as the settings page needs them: state and progress, WITHOUT the answer text.
+   *
+   * The page polls its route on a timer and renders a five-column table. Sending every retained
+   * answer with every poll would put megabytes on the wire for data nothing draws, so the bulky
+   * field is dropped here rather than at the route (which would have to know the field's name).
+   * The model still reads answers through `remote_agents`, straight off the registry.
+   *
+   * @param {number} [limit]  how many tasks to return, newest first
+   * @returns {object[]}
+   */
+  listForUi(limit = 50) {
+    return this.list().slice(0, limit).map((t) => ({
+      taskId: t.taskId,
+      peerId: t.peerId,
+      label: t.label,
+      promptDigest: t.promptDigest,
+      cwd: t.cwd,
+      state: t.state,
+      startedAt: t.startedAt,
+      endedAt: t.endedAt,
+      stopReason: t.stopReason,
+      diagnostic: t.diagnostic,
+      toolCallCount: t.toolCallCount,
+      recentTools: t.recentTools,
+      waitingForApproval: t.waitingForApproval,
+      usage: t.usage,
+      // Not the answer itself, but its size: the page can say "this run produced something"
+      // without shipping it.
+      outputChars: t.outputChars,
+    }))
+  }
+
+  /** @param {string} [peerId] */
+  listByPeer(peerId) {
+    return this.list().filter((t) => peerId === undefined || t.peerId === peerId)
+  }
+
+  /** Running or queued tasks — what the model needs to remember. */
+  active() {
+    return this.list().filter((t) => !TERMINAL.has(t.state))
+  }
+
+  /** @returns {number} count of active tasks for a peer (used for the serial queue) */
+  activeCountForPeer(peerId) {
+    return this.active().filter((t) => t.peerId === peerId).length
+  }
+
+  /**
+   * A compact multi-line summary for runtime-context injection. Returns '' when
+   * there is nothing to report, so callers can skip injecting an empty section.
+   */
+  summary() {
+    const act = this.active()
+    if (act.length === 0) return ''
+    const lines = act.map((t) => {
+      const age = Math.round((this.now() - t.startedAt) / 1000)
+      const tools = t.recentTools.length === 0 ? '' : ` tools=[${t.recentTools.join(',')}]`
+      const wait = t.waitingForApproval ? ' WAITING-FOR-APPROVAL' : ''
+      return `- ${t.taskId} peer=${t.peerId} state=${t.state} ${age}s tools=${t.toolCallCount}${tools}${wait}${t.label === '' ? '' : ` label="${t.label}"`}`
+    })
+    return [`Remote tasks in flight (${act.length}):`, ...lines].join('\n')
+  }
+
+  /** Drop the oldest settled tasks once the cap is exceeded. */
+  #evict() {
+    if (this.tasks.size < this.maxTasks) return
+    const settled = this.list().filter((t) => TERMINAL.has(t.state)).reverse()
+    while (this.tasks.size >= this.maxTasks && settled.length > 0) {
+      const victim = settled.shift()
+      if (victim !== undefined) this.tasks.delete(victim.taskId)
+    }
+  }
+}

package/lib/core/toolcall-cache.js

@@ -0,0 +1,206 @@
+/**
+ * `toolCallId` → `{ toolName, rawInput, status }` 缓存（INTERFACES.md 【A】）。
+ *
+ * 纯内存、无依赖、无 I/O。
+ *
+ * 为什么这是必需品（DESIGN §10.0.1 实测）：ACP 的 `session/request_permission`
+ * **只带 `toolCallId`**，不带工具名、参数，也不带申请的沙箱档位。主机的档位检查
+ * （`review-engine`）只能从 `tool_call` / `tool_call_update` 通知里提前缓存下来的
+ * `rawInput.sandbox_permissions` 取值。缓存未命中 → 审批无法判断 → 必须拒绝。
+ *
+ * 因此本类把两件事做成**可观测事实**：未命中计数 `misses` 与淘汰计数 `evictions`。
+ */
+
+/** 默认容量上限（INTERFACES.md 规定默认 512）。 */
+const DEFAULT_MAX_ENTRIES = 512
+
+/** 通知里没带 status 时的占位值（ACP 的初始状态即 pending）。 */
+const DEFAULT_STATUS = 'pending'
+
+/**
+ * @typedef {object} ToolCallRecord
+ * @property {string | undefined} toolName 来自 `tool_call` 通知的 `title`
+ * @property {unknown} rawInput            完整参数（档位检查的唯一数据来源）
+ * @property {string} status               `pending` | `in_progress` | `completed` | `failed` | 未知名
+ */
+
+/**
+ * `toolCallId` 缓存。容量满时按 LRU（最久未使用）淘汰。
+ *
+ * 最近使用顺序：`note()` / `update()` 写入的记录移到队尾；`get()` 命中也把记录移到队尾。
+ * 理由是一次审批往往发生在 `tool_call` 之后的若干个 `tool_call_update` 之后。
+ */
+export class ToolCallCache {
+  /** @type {Map<string, ToolCallRecord>} */
+  #entries
+
+  /** @type {number} */
+  #maxEntries
+
+  /** @type {number} */
+  #misses
+
+  /** @type {number} */
+  #evictions
+
+  /**
+   * @param {{ maxEntries?: number }} [opts] 容量上限，默认 512；非正整数按默认处理
+   */
+  constructor(opts) {
+    const max = isPlainObject(opts) ? opts.maxEntries : undefined
+    this.#maxEntries = Number.isInteger(max) && max > 0 ? max : DEFAULT_MAX_ENTRIES
+    this.#entries = new Map()
+    this.#misses = 0
+    this.#evictions = 0
+  }
+
+  /**
+   * 容量上限（只读，便于审计/配置页展示）。
+   * @returns {number}
+   */
+  get maxEntries() {
+    return this.#maxEntries
+  }
+
+  /**
+   * 累计未命中次数：`get()` 查不到记录（含非法 `toolCallId`）就 +1。
+   * 这是审计告警位——命中率低意味着审批决策拿不到判断依据。**不因 `clear()` 归零**。
+   * @returns {number}
+   */
+  get misses() {
+    return this.#misses
+  }
+
+  /**
+   * 当前记录条数。
+   * @returns {number}
+   */
+  get size() {
+    return this.#entries.size
+  }
+
+  /**
+   * 累计因容量上限淘汰的条数（「把淘汰记为可观测事实」）。**不因 `clear()` 归零**。
+   * @returns {number}
+   */
+  get evictions() {
+    return this.#evictions
+  }
+
+  /**
+   * 从 ACP 的 `tool_call` 通知记录一条：`title` 即工具名。
+   *
+   * 重复 `note` 同一个 id 时按「只覆盖显式给出的字段」合并，避免空通知把已有
+   * `title` / `rawInput` 抹掉（那会让后续档位检查失效）。
+   *
+   * 兼容性别名：同时接受 `toolName`（INTERFACES【B】的 `UpdateEvent.tool` 用的就是
+   * 这个名字，见 `bridge/acp-bridge.js` 的 `#toolView`）。契约字段是 `title`，
+   * 两者任一有效即可，避免调用方传错字段名时**静默**丢掉工具名。
+   *
+   * @param {string} toolCallId 非空字符串，否则抛 `TypeError`（调用方 bug，尽早暴露）
+   * @param {{ title?: string, toolName?: string, rawInput?: unknown, status?: string }} [patch]
+   * @returns {void}
+   */
+  note(toolCallId, patch = {}) {
+    const id = requireId(toolCallId, 'note')
+    this.#merge(id, patch)
+  }
+
+  /**
+   * 从 `tool_call_update` 更新 `status` / 补丁：**不覆盖** `title` / `rawInput`，
+   * 除非本次显式给出。未知 `toolCallId` 时按同样的合并语义新建一条记录
+   * （丢弃比丢失事实更糟；即使只有 status，`rawInput` 仍为 `undefined`，
+   * 审批侧照样按缓存缺失拒绝）。
+   *
+   * 注意：`update()` 未命中**不计入** `misses`——`misses` 只统计审批查询（`get`）失败。
+   *
+   * @param {string} toolCallId 非空字符串，否则抛 `TypeError`
+   * @param {{ status?: string, title?: string, toolName?: string, rawInput?: unknown }} [patch]
+   * @returns {void}
+   */
+  update(toolCallId, patch = {}) {
+    const id = requireId(toolCallId, 'update')
+    this.#merge(id, patch)
+  }
+
+  /**
+   * 读取缓存。**命中会把记录移到 LRU 队尾**。返回副本，调用方改动不影响缓存内部。
+   *
+   * @param {unknown} toolCallId
+   * @returns {ToolCallRecord | undefined} 未命中返回 `undefined`（同时 `misses` +1）
+   */
+  get(toolCallId) {
+    if (typeof toolCallId !== 'string' || toolCallId === '') {
+      this.#misses += 1
+      return undefined
+    }
+    const record = this.#entries.get(toolCallId)
+    if (record === undefined) {
+      this.#misses += 1
+      return undefined
+    }
+    this.#entries.delete(toolCallId)
+    this.#entries.set(toolCallId, record)
+    return { ...record }
+  }
+
+  /**
+   * 清空全部记录。**不**重置 `misses` / `evictions`（审计计数器是累计的）。
+   * @returns {void}
+   */
+  clear() {
+    this.#entries.clear()
+  }
+
+  /**
+   * 合并写入 + 维持 LRU 与容量上限。
+   * @param {string} id
+   * @param {{ title?: string, toolName?: string, rawInput?: unknown, status?: string }} patch
+   * @returns {void}
+   */
+  #merge(id, patch) {
+    const safe = isPlainObject(patch) ? patch : {}
+    const existing = this.#entries.get(id)
+    const name = [safe.title, safe.toolName].find(
+      (value) => typeof value === 'string' && value.trim() !== '',
+    )
+    /** @type {ToolCallRecord} */
+    const record = {
+      toolName: name ?? existing?.toolName,
+      rawInput: safe.rawInput !== undefined ? safe.rawInput : existing?.rawInput,
+      status:
+        typeof safe.status === 'string' && safe.status.trim() !== ''
+          ? safe.status
+          : (existing?.status ?? DEFAULT_STATUS),
+    }
+    if (existing !== undefined) this.#entries.delete(id)
+    this.#entries.set(id, record)
+    while (this.#entries.size > this.#maxEntries) {
+      const oldest = this.#entries.keys().next()
+      if (oldest.done === true) break
+      this.#entries.delete(oldest.value)
+      this.#evictions += 1
+    }
+  }
+}
+
+/**
+ * 校验 `toolCallId`。
+ * @param {unknown} toolCallId
+ * @param {string} method
+ * @returns {string}
+ */
+function requireId(toolCallId, method) {
+  if (typeof toolCallId !== 'string' || toolCallId === '') {
+    throw new TypeError(`ToolCallCache.${method}(): toolCallId must be a non-empty string`)
+  }
+  return toolCallId
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/lib/core/transfer-queue.js

@@ -0,0 +1,58 @@
+/**
+ * One serial lane per peer, for file transfers.
+ *
+ * WHY THIS IS NOT THE TASK QUEUE. `RemoteProvider`'s `serialQueue` exists because a desktop is an
+ * exclusive resource: two tasks driving one mouse fight, so they run one at a time. Transfers must
+ * NOT share that lane, because a 2 GiB copy would then occupy the worker's GUI slot and block the
+ * visual work it was meant to support -- and the whole point of moving bytes over the relay's HTTP
+ * surface instead of through the ACP session is that a copy never touches the GUI at all.
+ *
+ * They still need *a* lane of their own: two transfers to one peer make the disk seek between two
+ * streams and halve both. So: one transfer at a time per peer, on a queue of its own.
+ *
+ * A failed transfer must not poison the lane. The stored chain swallows the rejection -- the caller
+ * still sees its own error from `run`'s return value -- because an unhandled rejection left on a
+ * shared chain would fail the *next* transfer for a reason that has nothing to do with it.
+ */
+export function makeTransferQueue() {
+  /** @type {Map<string, Promise<void>>} */
+  const lanes = new Map()
+  /** @type {Map<string, number>} */
+  const busy = new Map()
+
+  const settle = (peerId) => () => {
+    const left = (busy.get(peerId) ?? 1) - 1
+    if (left <= 0) busy.delete(peerId)
+    else busy.set(peerId, left)
+  }
+
+  return {
+    /**
+     * Run `job` after everything already queued for this peer.
+     *
+     * @template T
+     * @param {string} peerId
+     * @param {() => Promise<T>} job
+     * @returns {Promise<T>} rejects with the job's own error, if it has one
+     */
+    run(peerId, job) {
+      busy.set(peerId, (busy.get(peerId) ?? 0) + 1)
+      const previous = lanes.get(peerId) ?? Promise.resolve()
+      // `then(job, job)`: the next job runs whether the previous one resolved or rejected.
+      const next = previous.then(job, job)
+      lanes.set(peerId, next.then(() => {}, () => {}))
+      return next.finally(settle(peerId))
+    },
+
+    /**
+     * How many transfers are queued or running for a peer.
+     *
+     * Read BEFORE `run` to report "waited behind N transfers". Without that number a slow copy is
+     * indistinguishable from a broken one -- the operator watches a tool call hang and cannot tell
+     * whether it is queued, transferring, or stuck.
+     */
+    depth(peerId) {
+      return busy.get(peerId) ?? 0
+    },
+  }
+}