@nelsonlongxiang/dsh-open-a2a-net 0.6.40 → 0.6.42

package/nexus-stage/src/canvas-wire.ts

@@ -1,164 +1,164 @@
-/**
- * The canvas write face's transport layer (POST /__dsh_a2a/canvas): action
- * sequencing, per-team serialization, and the notice classification that
- * design.md §3.4 mandates (host error text surfaces VERBATIM - the sidebar
- * reference's swallowed `.catch(() => {})` is the anti-pattern here).
- *
- * Classification per request:
- * - `ok:true`                                    → success (silent)
- * - `ok:false` WITH an `error` string            → error notice, verbatim
- * - `ok:false` without `error` → success only when returned members/teams
- *   prove the requested idempotent effect; cap/unknown results are failures
- * - HTTP >= 400                                  → body error verbatim, else `HTTP <status>`
- * - send() throws                                → `画布不可达：<message>`
- * - missing success acknowledgement (including non-JSON transport errors)
- *   → visible failure, never a confirmed join
- *
- * Ops on the same team run through a serial queue (a later gesture waits
- * instead of racing; cross-team ops run in parallel) - mirrors the
- * sidebar's per-team busy keys, minus the rejection hostility. Pure
- * control flow: the transport is injected.
- * @module nexus-stage/canvas-wire
- */
-
-/** One send outcome: HTTP status plus the parsed JSON body (whatever it is). */
-export interface CanvasWireResult {
-  status: number
-  body: { ok?: boolean; error?: string; teams?: readonly string[]; members?: readonly string[]; name?: string }
-}
-
-/** Transport injection: POST the body, resolve with parsed outcome, throw on network failure. */
-export type CanvasSend = (body: unknown) => Promise<CanvasWireResult>
-
-export interface CanvasWireDeps {
-  send: CanvasSend
-  onNotice(kind: 'error' | 'info', text: string): void
-}
-
-export interface CanvasWire {
-  /** create → add-member per id, serial, first failure stops. `created` is
-   * a model-side hint ONLY, never server creation provenance. A failed add
-   * cannot authorize deleting a same-name team; preserve it for retry. */
-  createTeam(name: string, ids: readonly string[], created?: boolean): Promise<boolean>
-  addMembers(team: string, ids: readonly string[]): Promise<boolean>
-  removeMembers(team: string, ids: readonly string[]): Promise<boolean>
-  /** Pre-computed remove/add roster ops (from canvas-ops.reorderOps). */
-  runRosterOps(team: string, ops: ReadonlyArray<{ op: 'remove' | 'add'; id: string }>): Promise<boolean>
-  removeTeam(name: string): Promise<boolean>
-  hasPending(): boolean
-}
-
-type RosterOp = { op: 'remove' | 'add'; id: string }
-
-function errorText(body: CanvasWireResult['body']): string | undefined {
-  return body != null && typeof body.error === 'string' ? body.error : undefined
-}
-
-export function createCanvasWire(deps: CanvasWireDeps): CanvasWire {
-  const queues = new Map<string, Promise<unknown>>()
-  let pending = 0
-
-  /** Serial per-team queue: same key waits, other keys run in parallel. */
-  function enqueue<T>(key: string, task: () => Promise<T>): Promise<T> {
-    pending += 1
-    const prev = queues.get(key) ?? Promise.resolve()
-    const run = async (): Promise<T> => {
-      try {
-        return await task()
-      } finally {
-        pending -= 1 // settles BEFORE the returned promise resolves
-      }
-    }
-    const next = prev.then(run, run) // run regardless of how the predecessor settled
-    queues.set(
-      key,
-      next.then(
-        () => undefined,
-        () => undefined,
-      ),
-    )
-    return next
-  }
-
-  /** One classified request — NEVER enqueues (public ops own the queue). */
-  async function raw(body: Record<string, unknown>): Promise<boolean> {
-    let res: CanvasWireResult
-    try {
-      res = await deps.send(body)
-    } catch (error) {
-      const message = String((error as Error | undefined)?.message ?? error).slice(0, 80)
-      deps.onNotice('error', `画布不可达：${message}`)
-      return false
-    }
-    if (res.status >= 400) {
-      deps.onNotice('error', errorText(res.body) ?? `HTTP ${res.status}`)
-      return false
-    }
-    if (res.body?.ok === true) return true
-    const text = res.body != null && typeof res.body === 'object' ? errorText(res.body) : undefined
-    if (text !== undefined) {
-      deps.onNotice('error', text)
-      return false
-    }
-    // A bare false can mean a capacity refusal, not just an idempotent no-op.
-    // Accept a no-op only when the host's returned state proves the effect.
-    const name = String(body.name ?? ''), id = String(body.id ?? '')
-    const members = res.body?.members, teams = res.body?.teams
-    const memberProof = Array.isArray(members) && members.every(v => typeof v === 'string')
-    const teamProof = Array.isArray(teams) && teams.every(v => typeof v === 'string')
-    if (res.body?.ok === false && (
-      (body.action === 'add-member' && memberProof && members.includes(id)) ||
-      (body.action === 'remove-member' && memberProof && !members.includes(id)) ||
-      (body.action === 'remove' && teamProof && !teams.includes(name))
-    )) return true
-    deps.onNotice('error', '画布操作未确认：' + String(body.action) + '（可能队伍/成员已达上限，请重试）')
-    return false
-  }
-
-  async function serial(body: Record<string, unknown>, ids: readonly string[]): Promise<boolean> {
-    for (const id of ids) {
-      if (!(await raw({ ...body, id }))) return false
-    }
-    return true
-  }
-
-  return {
-    createTeam(name, ids) {
-      return enqueue(name, async () => {
-        if (!(await raw({ action: 'create', name }))) return false
-        for (let i = 0; i < ids.length; i++) {
-          if (!(await raw({ action: 'add-member', name, id: ids[i]! }))) {
-            // Local absence does not prove server-side creation. Never issue
-            // an unconditional compensating remove: an idempotent create may
-            // have reused an existing team (including one already at capacity).
-            return false
-          }
-        }
-        return true
-      })
-    },
-    addMembers(team, ids) {
-      return enqueue(team, () => serial({ action: 'add-member', name: team }, ids))
-    },
-    removeMembers(team, ids) {
-      return enqueue(team, () => serial({ action: 'remove-member', name: team }, ids))
-    },
-    runRosterOps(team, ops) {
-      return enqueue(team, async () => {
-        for (const op of ops) {
-          const body = op.op === 'remove'
-            ? { action: 'remove-member', name: team, id: op.id }
-            : { action: 'add-member', name: team, id: op.id }
-          if (!(await raw(body))) return false
-        }
-        return true
-      })
-    },
-    removeTeam(name) {
-      return enqueue(name, () => raw({ action: 'remove', name }))
-    },
-    hasPending() {
-      return pending > 0
-    },
-  }
-}
+/**
+ * The canvas write face's transport layer (POST /__dsh_a2a/canvas): action
+ * sequencing, per-team serialization, and the notice classification that
+ * design.md §3.4 mandates (host error text surfaces VERBATIM - the sidebar
+ * reference's swallowed `.catch(() => {})` is the anti-pattern here).
+ *
+ * Classification per request:
+ * - `ok:true`                                    → success (silent)
+ * - `ok:false` WITH an `error` string            → error notice, verbatim
+ * - `ok:false` without `error` → success only when returned members/teams
+ *   prove the requested idempotent effect; cap/unknown results are failures
+ * - HTTP >= 400                                  → body error verbatim, else `HTTP <status>`
+ * - send() throws                                → `画布不可达：<message>`
+ * - missing success acknowledgement (including non-JSON transport errors)
+ *   → visible failure, never a confirmed join
+ *
+ * Ops on the same team run through a serial queue (a later gesture waits
+ * instead of racing; cross-team ops run in parallel) - mirrors the
+ * sidebar's per-team busy keys, minus the rejection hostility. Pure
+ * control flow: the transport is injected.
+ * @module nexus-stage/canvas-wire
+ */
+
+/** One send outcome: HTTP status plus the parsed JSON body (whatever it is). */
+export interface CanvasWireResult {
+  status: number
+  body: { ok?: boolean; error?: string; teams?: readonly string[]; members?: readonly string[]; name?: string }
+}
+
+/** Transport injection: POST the body, resolve with parsed outcome, throw on network failure. */
+export type CanvasSend = (body: unknown) => Promise<CanvasWireResult>
+
+export interface CanvasWireDeps {
+  send: CanvasSend
+  onNotice(kind: 'error' | 'info', text: string): void
+}
+
+export interface CanvasWire {
+  /** create → add-member per id, serial, first failure stops. `created` is
+   * a model-side hint ONLY, never server creation provenance. A failed add
+   * cannot authorize deleting a same-name team; preserve it for retry. */
+  createTeam(name: string, ids: readonly string[], created?: boolean): Promise<boolean>
+  addMembers(team: string, ids: readonly string[]): Promise<boolean>
+  removeMembers(team: string, ids: readonly string[]): Promise<boolean>
+  /** Pre-computed remove/add roster ops (from canvas-ops.reorderOps). */
+  runRosterOps(team: string, ops: ReadonlyArray<{ op: 'remove' | 'add'; id: string }>): Promise<boolean>
+  removeTeam(name: string): Promise<boolean>
+  hasPending(): boolean
+}
+
+type RosterOp = { op: 'remove' | 'add'; id: string }
+
+function errorText(body: CanvasWireResult['body']): string | undefined {
+  return body != null && typeof body.error === 'string' ? body.error : undefined
+}
+
+export function createCanvasWire(deps: CanvasWireDeps): CanvasWire {
+  const queues = new Map<string, Promise<unknown>>()
+  let pending = 0
+
+  /** Serial per-team queue: same key waits, other keys run in parallel. */
+  function enqueue<T>(key: string, task: () => Promise<T>): Promise<T> {
+    pending += 1
+    const prev = queues.get(key) ?? Promise.resolve()
+    const run = async (): Promise<T> => {
+      try {
+        return await task()
+      } finally {
+        pending -= 1 // settles BEFORE the returned promise resolves
+      }
+    }
+    const next = prev.then(run, run) // run regardless of how the predecessor settled
+    queues.set(
+      key,
+      next.then(
+        () => undefined,
+        () => undefined,
+      ),
+    )
+    return next
+  }
+
+  /** One classified request — NEVER enqueues (public ops own the queue). */
+  async function raw(body: Record<string, unknown>): Promise<boolean> {
+    let res: CanvasWireResult
+    try {
+      res = await deps.send(body)
+    } catch (error) {
+      const message = String((error as Error | undefined)?.message ?? error).slice(0, 80)
+      deps.onNotice('error', `画布不可达：${message}`)
+      return false
+    }
+    if (res.status >= 400) {
+      deps.onNotice('error', errorText(res.body) ?? `HTTP ${res.status}`)
+      return false
+    }
+    if (res.body?.ok === true) return true
+    const text = res.body != null && typeof res.body === 'object' ? errorText(res.body) : undefined
+    if (text !== undefined) {
+      deps.onNotice('error', text)
+      return false
+    }
+    // A bare false can mean a capacity refusal, not just an idempotent no-op.
+    // Accept a no-op only when the host's returned state proves the effect.
+    const name = String(body.name ?? ''), id = String(body.id ?? '')
+    const members = res.body?.members, teams = res.body?.teams
+    const memberProof = Array.isArray(members) && members.every(v => typeof v === 'string')
+    const teamProof = Array.isArray(teams) && teams.every(v => typeof v === 'string')
+    if (res.body?.ok === false && (
+      (body.action === 'add-member' && memberProof && members.includes(id)) ||
+      (body.action === 'remove-member' && memberProof && !members.includes(id)) ||
+      (body.action === 'remove' && teamProof && !teams.includes(name))
+    )) return true
+    deps.onNotice('error', '画布操作未确认：' + String(body.action) + '（可能队伍/成员已达上限，请重试）')
+    return false
+  }
+
+  async function serial(body: Record<string, unknown>, ids: readonly string[]): Promise<boolean> {
+    for (const id of ids) {
+      if (!(await raw({ ...body, id }))) return false
+    }
+    return true
+  }
+
+  return {
+    createTeam(name, ids) {
+      return enqueue(name, async () => {
+        if (!(await raw({ action: 'create', name }))) return false
+        for (let i = 0; i < ids.length; i++) {
+          if (!(await raw({ action: 'add-member', name, id: ids[i]! }))) {
+            // Local absence does not prove server-side creation. Never issue
+            // an unconditional compensating remove: an idempotent create may
+            // have reused an existing team (including one already at capacity).
+            return false
+          }
+        }
+        return true
+      })
+    },
+    addMembers(team, ids) {
+      return enqueue(team, () => serial({ action: 'add-member', name: team }, ids))
+    },
+    removeMembers(team, ids) {
+      return enqueue(team, () => serial({ action: 'remove-member', name: team }, ids))
+    },
+    runRosterOps(team, ops) {
+      return enqueue(team, async () => {
+        for (const op of ops) {
+          const body = op.op === 'remove'
+            ? { action: 'remove-member', name: team, id: op.id }
+            : { action: 'add-member', name: team, id: op.id }
+          if (!(await raw(body))) return false
+        }
+        return true
+      })
+    },
+    removeTeam(name) {
+      return enqueue(name, () => raw({ action: 'remove', name }))
+    },
+    hasPending() {
+      return pending > 0
+    },
+  }
+}

package/nexus-stage/src/cli-home-picker.ts

@@ -1,42 +1,42 @@
-/** Explicit operator choice only; this form never auto-selects or relaxes home admission. */
-export interface CliHomeOptions { ok: boolean; homes?: string[]; unreadable?: number; held?: boolean; error?: string }
-export function createCliHomePicker(read: () => Promise<CliHomeOptions>, save: (home: string) => Promise<boolean>): HTMLFormElement {
-  const form = document.createElement('form')
-  form.className = 'wb-cli-home'
-  const readButton = document.createElement('button')
-  readButton.type = 'button'; readButton.textContent = '指定 home'; readButton.className = 'wb-member-submit'
-  const select = document.createElement('select')
-  select.className = 'wb-member-pick'; select.setAttribute('aria-label', '选择 CLI home 主机'); select.hidden = true
-  const submit = document.createElement('button')
-  submit.type = 'submit'; submit.textContent = '确认 home'; submit.className = 'wb-member-submit'; submit.hidden = true; submit.disabled = true
-  const note = document.createElement('div')
-  note.className = 'wb-hint'; note.setAttribute('role', 'status'); note.setAttribute('aria-live', 'polite')
-  note.textContent = 'home 未确定；点击指定 home 现读已链接主机名片。'
-  let busy = false
-  readButton.addEventListener('click', async () => {
-    if (busy) return
-    busy = true; readButton.disabled = true; submit.disabled = true; note.textContent = '正在现读主机名片…'
-    try {
-      const result = await read()
-      if (!result.ok) throw Error(result.error ?? '候选读取失败')
-      if (result.held) { readButton.hidden = true; select.hidden = true; submit.hidden = true; select.replaceChildren(); note.textContent = '本机持有，无需指定'; return }
-      select.replaceChildren(new Option('请选择 home 主机…', '', true, true))
-      for (const home of result.homes ?? []) select.appendChild(new Option(home, home))
-      select.hidden = false; submit.hidden = false; readButton.textContent = '刷新候选'
-      const count = result.homes?.length ?? 0
-      note.textContent = (result.unreadable ? '有 ' + result.unreadable + ' 台对端名片读不到；' : '') + (count > 1 ? '多台已链接主机列出该句柄，请显式选择。' : count === 1 ? '找到 1 台已链接主机；仍需你显式确认。' : '当前没有已链接且列出该句柄的可选主机。')
-    } catch (error) { note.textContent = '读取失败：' + String(error); select.hidden = true; submit.hidden = true }
-    finally { busy = false; readButton.disabled = false }
-  })
-  select.addEventListener('change', () => { submit.disabled = busy || select.value === '' })
-  form.addEventListener('submit', async event => {
-    event.preventDefault()
-    if (busy || select.value === '') return
-    busy = true; readButton.disabled = true; select.disabled = true; submit.disabled = true
-    try { note.textContent = await save(select.value) ? 'home 已指定：' + select.value : '指定失败：主机可能已离线或不再列出该句柄，请刷新后重选。' }
-    catch (error) { note.textContent = '指定失败：' + String(error) }
-    finally { busy = false; readButton.disabled = false; select.disabled = false; submit.disabled = select.value === '' }
-  })
-  form.append(readButton, select, submit, note)
-  return form
-}
+/** Explicit operator choice only; this form never auto-selects or relaxes home admission. */
+export interface CliHomeOptions { ok: boolean; homes?: string[]; unreadable?: number; held?: boolean; error?: string }
+export function createCliHomePicker(read: () => Promise<CliHomeOptions>, save: (home: string) => Promise<boolean>): HTMLFormElement {
+  const form = document.createElement('form')
+  form.className = 'wb-cli-home'
+  const readButton = document.createElement('button')
+  readButton.type = 'button'; readButton.textContent = '指定 home'; readButton.className = 'wb-member-submit'
+  const select = document.createElement('select')
+  select.className = 'wb-member-pick'; select.setAttribute('aria-label', '选择 CLI home 主机'); select.hidden = true
+  const submit = document.createElement('button')
+  submit.type = 'submit'; submit.textContent = '确认 home'; submit.className = 'wb-member-submit'; submit.hidden = true; submit.disabled = true
+  const note = document.createElement('div')
+  note.className = 'wb-hint'; note.setAttribute('role', 'status'); note.setAttribute('aria-live', 'polite')
+  note.textContent = 'home 未确定；点击指定 home 现读已链接主机名片。'
+  let busy = false
+  readButton.addEventListener('click', async () => {
+    if (busy) return
+    busy = true; readButton.disabled = true; submit.disabled = true; note.textContent = '正在现读主机名片…'
+    try {
+      const result = await read()
+      if (!result.ok) throw Error(result.error ?? '候选读取失败')
+      if (result.held) { readButton.hidden = true; select.hidden = true; submit.hidden = true; select.replaceChildren(); note.textContent = '本机持有，无需指定'; return }
+      select.replaceChildren(new Option('请选择 home 主机…', '', true, true))
+      for (const home of result.homes ?? []) select.appendChild(new Option(home, home))
+      select.hidden = false; submit.hidden = false; readButton.textContent = '刷新候选'
+      const count = result.homes?.length ?? 0
+      note.textContent = (result.unreadable ? '有 ' + result.unreadable + ' 台对端名片读不到；' : '') + (count > 1 ? '多台已链接主机列出该句柄，请显式选择。' : count === 1 ? '找到 1 台已链接主机；仍需你显式确认。' : '当前没有已链接且列出该句柄的可选主机。')
+    } catch (error) { note.textContent = '读取失败：' + String(error); select.hidden = true; submit.hidden = true }
+    finally { busy = false; readButton.disabled = false }
+  })
+  select.addEventListener('change', () => { submit.disabled = busy || select.value === '' })
+  form.addEventListener('submit', async event => {
+    event.preventDefault()
+    if (busy || select.value === '') return
+    busy = true; readButton.disabled = true; select.disabled = true; submit.disabled = true
+    try { note.textContent = await save(select.value) ? 'home 已指定：' + select.value : '指定失败：主机可能已离线或不再列出该句柄，请刷新后重选。' }
+    catch (error) { note.textContent = '指定失败：' + String(error) }
+    finally { busy = false; readButton.disabled = false; select.disabled = false; submit.disabled = select.value === '' }
+  })
+  form.append(readButton, select, submit, note)
+  return form
+}

package/nexus-stage/src/fault.ts

@@ -1,56 +1,56 @@
-/**
- * The stage's fault surface as pure logic: whoever calls {@link fault}
- * gets the newest message on the sink immediately, while the diagnostic
- * log line is throttled to one per window (the N2 breadcrumb cadence).
- * {@link clear} hides the sink and resets the throttle clock, so the first
- * fault after a healthy stretch logs promptly again.
- *
- * DOM-free on purpose: the browser shell in main.ts supplies the sink, and
- * the unit test supplies fakes — the lifecycle (sink-always-current,
- * log-throttled, clear-resets) is what the regression net owns. This module
- * exists because the incident class it guards against (a catch burying a
- * ReferenceError behind a healthy render loop) shipped once already.
- * @module nexus-stage/fault
- */
-
-/** How long one diagnostic log line suppresses its successors. */
-export const FAULT_LOG_THROTTLE_MS = 60_000
-
-/** Anything the fault reporter can render onto. */
-export interface FaultSink {
-  /** Surface the newest fault; the sink becomes visible with this text. */
-  show(message: string): void
-  /** Retract the sink after a healthy response. */
-  hide(): void
-}
-
-export interface FaultReporter {
-  /** Surface a fault: the sink always updates, the log line throttles. */
-  fault(message: string): void
-  /** A healthy response arrived: hide the sink and reset the throttle. */
-  clear(): void
-}
-
-/**
- * @param sink - render target (DOM badge in the shell, recording fake in tests).
- * @param log - diagnostic channel (console.error in the shell, spy in tests).
- * @param now - injectable clock for deterministic throttle tests. A fault
- *   exactly one window after the previous logs again (window is inclusive).
- */
-export function createFaultReporter(sink: FaultSink, log: (message: string) => void, now: () => number = Date.now): FaultReporter {
-  let lastLoggedAt = -FAULT_LOG_THROTTLE_MS
-  return {
-    fault(message) {
-      const at = now()
-      if (at - lastLoggedAt >= FAULT_LOG_THROTTLE_MS) {
-        log(`[nexus] ${message}`)
-        lastLoggedAt = at
-      }
-      sink.show(message)
-    },
-    clear() {
-      sink.hide()
-      lastLoggedAt = -FAULT_LOG_THROTTLE_MS
-    },
-  }
-}
+/**
+ * The stage's fault surface as pure logic: whoever calls {@link fault}
+ * gets the newest message on the sink immediately, while the diagnostic
+ * log line is throttled to one per window (the N2 breadcrumb cadence).
+ * {@link clear} hides the sink and resets the throttle clock, so the first
+ * fault after a healthy stretch logs promptly again.
+ *
+ * DOM-free on purpose: the browser shell in main.ts supplies the sink, and
+ * the unit test supplies fakes — the lifecycle (sink-always-current,
+ * log-throttled, clear-resets) is what the regression net owns. This module
+ * exists because the incident class it guards against (a catch burying a
+ * ReferenceError behind a healthy render loop) shipped once already.
+ * @module nexus-stage/fault
+ */
+
+/** How long one diagnostic log line suppresses its successors. */
+export const FAULT_LOG_THROTTLE_MS = 60_000
+
+/** Anything the fault reporter can render onto. */
+export interface FaultSink {
+  /** Surface the newest fault; the sink becomes visible with this text. */
+  show(message: string): void
+  /** Retract the sink after a healthy response. */
+  hide(): void
+}
+
+export interface FaultReporter {
+  /** Surface a fault: the sink always updates, the log line throttles. */
+  fault(message: string): void
+  /** A healthy response arrived: hide the sink and reset the throttle. */
+  clear(): void
+}
+
+/**
+ * @param sink - render target (DOM badge in the shell, recording fake in tests).
+ * @param log - diagnostic channel (console.error in the shell, spy in tests).
+ * @param now - injectable clock for deterministic throttle tests. A fault
+ *   exactly one window after the previous logs again (window is inclusive).
+ */
+export function createFaultReporter(sink: FaultSink, log: (message: string) => void, now: () => number = Date.now): FaultReporter {
+  let lastLoggedAt = -FAULT_LOG_THROTTLE_MS
+  return {
+    fault(message) {
+      const at = now()
+      if (at - lastLoggedAt >= FAULT_LOG_THROTTLE_MS) {
+        log(`[nexus] ${message}`)
+        lastLoggedAt = at
+      }
+      sink.show(message)
+    },
+    clear() {
+      sink.hide()
+      lastLoggedAt = -FAULT_LOG_THROTTLE_MS
+    },
+  }
+}