dsh-ntr 0.2.1 → 0.3.1

package/src/client/store.ts

@@ -6,7 +6,7 @@
  * Deliberately framework-free: React binds through `useSyncExternalStore`.
  */
 
-import type { AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentSavePayload, AgentTestResult, AgentView, ChatSessionView, ChatTranscriptView, ApprovalDeadlinesSetPayload, ApprovalDeadlinesResult, DetectedAgentInfo, PermissionTimeoutMode, SessionView } from '../protocol.ts'
+import type { AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentSavePayload, AgentTestResult, AgentView, ChatSessionView, ChatTranscriptView, ApprovalDeadlinesSetPayload, ApprovalDeadlinesResult, DetectedAgentInfo, PermissionTimeoutMode, PluginUpdateState, PluginVersionResult, SessionView } from '../protocol.ts'
 import { DEFAULT_TAG_HALO } from '../protocol.ts'
 
 /** One slash command the ACP agent declared, whole row (the menu draws name, description and `input.hint`). */
@@ -135,6 +135,22 @@ export interface ChatTranscript {
   seq: number
 }
 
+/**
+ * One line of the settings page's ACP runtime log. Agent-side notices and
+ * session-release reasons land here (bounded, append order oldest→newest);
+ * failures of the settings page's OWN actions stay in {@link UiState.notice}.
+ */
+export interface AcpLogEntry {
+  id: number
+  at: number
+  level: 'info' | 'error'
+  text: string
+  agentId?: string
+}
+
+/** Cap on retained runtime-log lines; older entries fall off the front. */
+export const LOG_MAX_ENTRIES = 200
+
 export interface UiState {
   open: boolean
   /**
@@ -156,7 +172,15 @@ export interface UiState {
   blocks: Block[]
   permissions: PendingPermission[]
   busy: boolean
+  /**
+   * The settings page's one-line banner for its OWN action failures. Agent-side
+   * runtime messages do not land here; they append to {@link logs} instead.
+   */
   notice?: string
+  /** Agent-side runtime log, append order oldest→newest, capped at {@link LOG_MAX_ENTRIES}. */
+  logs: AcpLogEntry[]
+  /** Lines appended since the user last opened the log; reset by {@link AcpStore.markLogsRead}. */
+  logUnread: number
   /**
    * The plugin's OWN default ACP agent (the panel's ★ gesture) — which agent a
    * new ACP-mode conversation starts on. NOT the deployment default model: that
@@ -298,6 +322,18 @@ export interface UiState {
    * (`preset/status` answering `null`), in which case the panel hides the block.
    */
   preset?: AcpPresetStatus
+  /**
+   * The installed host package's version (`plugin/version`), rendered as the
+   * settings page badge. Absent on a host half without the endpoint, which
+   * hides the badge rather than naming a version this browser invented.
+   */
+  pluginVersion?: string
+  /**
+   * The running version and its update status (`plugin/update-check`). Absent
+   * on a host half without the endpoint, which hides the update entry instead
+   * of offering an install this browser cannot perform.
+   */
+  pluginUpdate?: PluginUpdateState
 }
 
 interface Listener { (): void }
@@ -309,6 +345,13 @@ const MAX_WATCHED = 6
 /** Raw JSON budget for one event block; the cut is marked. */
 const RAW_MAX = 256_000
 
+/**
+ * How long a fetched update state stays fresh. The settings panel asks on every
+ * mount; without this, every open would hit the registry. A forced check (the
+ * card's own button) always goes out.
+ */
+const PLUGIN_UPDATE_TTL_MS = 10 * 60 * 1000
+
 /** Pretty-printed JSON of an agent message (never throws, cuts only at {@link RAW_MAX} with a marker). */
 export function jsonText(value: unknown): string {
   let text: string
@@ -531,6 +574,14 @@ export const DEFAULT_KNOWN_PRESETS: DetectedAgentInfo[] = [
     defaultCommand: 'opencode',
     defaultArgs: ['acp'],
   },
+  {
+    id: 'cursor',
+    name: 'Cursor CLI',
+    description: 'Cursor CLI — run as `agent acp` over stdio (legacy alias `cursor-agent acp`)',
+    detected: false,
+    defaultCommand: 'agent',
+    defaultArgs: ['acp'],
+  },
   {
     id: 'qwen',
     name: 'Qwen Code',
@@ -576,6 +627,8 @@ export class AcpStore {
     blocks: [],
     permissions: [],
     busy: false,
+    logs: [],
+    logUnread: 0,
     detectedAgents: [...DEFAULT_KNOWN_PRESETS],
     detecting: false,
     modelCatalogs: {},
@@ -598,6 +651,8 @@ export class AcpStore {
 
   private readonly listeners = new Set<Listener>()
   private source?: EventSource
+  /** Monotonic id source for {@link AcpLogEntry}s (never reset by `clearLogs`). */
+  private logSeq = 0
   private readonly lastSeq = new Map<string, number>()
   /** Sessions with a finalized turn (dedups the cancel-fallback + late real turn/end pair). */
   private readonly openTurns = new Set<string>()
@@ -646,6 +701,22 @@ export class AcpStore {
   private readonly cachedModelReads = new Set<string>()
   /** Counts behind the last successful explicit re-detect, so a locale switch can re-render its summary. */
   private detectCounts: { total: number; installed: number } | undefined
+  /** When {@link UiState.pluginUpdate} was last read from the host (epoch ms). */
+  private pluginUpdateFetchedAt = 0
+  /**
+   * The shared in-flight `plugin/update-check`. The settings section mounts
+   * twice (both entries) and the update popover asks too; without this, two
+   * mounts in the same tick each fire their own registry read.
+   */
+  private pluginUpdateInflight?: Promise<PluginUpdateState | undefined>
+  /** Re-entry guard for `plugin/update-apply` (a double click is one install). */
+  private pluginUpdateApplying = false
+  /**
+   * Update read generation. An apply bumps it so a check that was already in
+   * flight (started before the install) cannot land afterwards and overwrite
+   * the install's verdict with the pre-install `available`.
+   */
+  private pluginUpdateGeneration = 0
 
   constructor(private readonly rpc: RpcCall, private readonly locale: (zh: string, en: string) => string) {}
 
@@ -669,6 +740,24 @@ export class AcpStore {
     for (const listener of [...this.listeners]) listener()
   }
 
+  /**
+   * Build the log patch for one line. Does NOT mutate: the caller merges it
+   * into the single `mutate` call it was already making for the same event.
+   */
+  private logPatch(level: 'info' | 'error', text: string, agentId?: string): Pick<UiState, 'logs' | 'logUnread'> {
+    const entry: AcpLogEntry = {
+      id: ++this.logSeq,
+      at: Date.now(),
+      level,
+      text,
+      ...(agentId === undefined ? {} : { agentId }),
+    }
+    return {
+      logs: [...this.state.logs, entry].slice(-LOG_MAX_ENTRIES),
+      logUnread: this.state.logUnread + 1,
+    }
+  }
+
   // ---- Streaming update coalescing ----
 
   /**
@@ -783,7 +872,7 @@ export class AcpStore {
   /** Snapshot refresh used on panel open and after a stream outage. */
   async resync(): Promise<void> {
     try {
-      const [{ agents }, { sessions }, defaultAgentInfo, detectResult, presetResult, tagHaloResult, deadlinesResult] = await Promise.all([
+      const [{ agents }, { sessions }, defaultAgentInfo, detectResult, presetResult, tagHaloResult, deadlinesResult, versionResult] = await Promise.all([
         this.call<{ agents: AgentView[] }>('agents/list'),
         this.call<{ sessions: SessionView[] }>('sessions/list'),
         // The plugin's OWN default ACP agent — a plugin-private id, not a DSH
@@ -797,6 +886,9 @@ export class AcpStore {
         // `undefined` (older half) hides the deadline card instead of showing a
         // number this browser made up.
         this.call<ApprovalDeadlinesResult>('ui/approval-deadlines').catch(() => ({ deadlines: undefined })),
+        // The settings badge's data source; older halves answer `unknown
+        // endpoint`, which hides the badge.
+        this.call<PluginVersionResult>('plugin/version').catch(() => null),
       ])
       const detectedAgents = (detectResult && detectResult.agents.length > 0)
         ? detectResult.agents
@@ -811,6 +903,7 @@ export class AcpStore {
         preset: presetResult?.preset ?? undefined,
         tagHalo: tagHaloResult?.halo ?? { ...DEFAULT_TAG_HALO },
         approvalDeadlines: deadlinesResult.deadlines,
+        pluginVersion: versionResult?.version !== undefined && versionResult.version !== '' ? versionResult.version : undefined,
       })
       const active = this.state.activeSessionId ?? sessions[0]?.sessionId
       if (active !== undefined) await this.loadTranscript(active)
@@ -819,6 +912,103 @@ export class AcpStore {
     }
   }
 
+  /**
+   * Read the plugin's update state (`plugin/update-check`). Throttled to ten
+   * minutes unless `force`: the settings panel asks on mount, and every
+   * remount must not hit the registry.
+   *
+   * An older host serves no such endpoint (`unknown endpoint`). That is a
+   * normal degradation, not an error worth a notice: the answer is `undefined`
+   * and the panel simply keeps its update entry hidden.
+   */
+  async checkPluginUpdate(force = false): Promise<PluginUpdateState | undefined> {
+    // One read for every caller while it is in flight, force included: the
+    // settings page and the popover mounting together must not hit the
+    // registry twice.
+    if (this.pluginUpdateInflight !== undefined) return this.pluginUpdateInflight
+    const current = this.state.pluginUpdate
+    if (!force && current !== undefined && Date.now() - this.pluginUpdateFetchedAt < PLUGIN_UPDATE_TTL_MS) {
+      return current
+    }
+    const generation = this.pluginUpdateGeneration
+    const inflight = this.readPluginUpdate(generation)
+    this.pluginUpdateInflight = inflight
+    try {
+      return await inflight
+    } finally {
+      this.pluginUpdateInflight = undefined
+    }
+  }
+
+  private async readPluginUpdate(generation: number): Promise<PluginUpdateState | undefined> {
+    try {
+      const pluginUpdate = await this.call<PluginUpdateState>('plugin/update-check')
+      // An install started while this read was in flight: its answer is
+      // already stale, and the install's verdict owns the state now.
+      if (generation !== this.pluginUpdateGeneration) return undefined
+      this.pluginUpdateFetchedAt = Date.now()
+      this.mutate({ pluginUpdate })
+      return pluginUpdate
+    } catch {
+      return undefined
+    }
+  }
+
+  /**
+   * Install one exact version (`plugin/update-apply`). The status flips to
+   * `applying` first so the badge answers the click; the host's answer then
+   * becomes the state.
+   *
+   * A failed call does NOT prove the install did not happen: on an HMR host
+   * the update uninstalls the plugin before reinstalling it, which can cut the
+   * response. Whatever the error, the disk may already carry the new version,
+   * so the state becomes `restart-required` (the one neutral verdict for "the
+   * running code is not the disk's") with `installed` dropped (unknown, not a
+   * fact to display) and the notice asks for a reload rather than restoring
+   * `available` and pretending nothing changed.
+   */
+  async applyPluginUpdate(version: string): Promise<PluginUpdateState | undefined> {
+    if (this.pluginUpdateApplying) return undefined
+    this.pluginUpdateApplying = true
+    // Any check already in flight predates the install; its answer must not
+    // land on top of the install's verdict.
+    this.pluginUpdateGeneration += 1
+    const previous = this.state.pluginUpdate
+    if (previous !== undefined) {
+      this.mutate({ pluginUpdate: { ...previous, status: 'applying' } })
+    }
+    try {
+      const pluginUpdate = await this.call<PluginUpdateState>('plugin/update-apply', { version })
+      this.pluginUpdateFetchedAt = Date.now()
+      this.mutate({ pluginUpdate })
+      return pluginUpdate
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      // The disk state is UNKNOWN here: the install may have completed before
+      // the response was cut. Keep `latest` for display, drop `installed` so no
+      // surface can claim a disk version we never read, and reset the throttle
+      // so the next check actually asks the host instead of serving this
+      // unknown verdict for ten minutes.
+      const interrupted: PluginUpdateState = previous !== undefined
+        ? { ...previous, status: 'restart-required', installed: undefined, message }
+        : { status: 'restart-required', current: this.state.pluginVersion ?? '?', message }
+      this.pluginUpdateFetchedAt = 0
+      this.mutate({
+        pluginUpdate: interrupted,
+        notice: this.locale(
+          '更新请求已中断；请刷新页面确认当前版本。',
+          'The update request was interrupted. Reload the page to confirm the installed version.',
+        ),
+      })
+      return undefined
+    } finally {
+      // Invalidate reads that STARTED during the install: their "applying"
+      // answer would otherwise land on top of this call's final verdict.
+      this.pluginUpdateGeneration += 1
+      this.pluginUpdateApplying = false
+    }
+  }
+
   async detectAgents(): Promise<void> {
     this.mutate({ detecting: true })
     try {
@@ -1751,6 +1941,17 @@ export class AcpStore {
     this.mutate({ notice: undefined })
   }
 
+  /** Drop every retained runtime-log line (the unread counter restarts too). */
+  clearLogs(): void {
+    this.mutate({ logs: [], logUnread: 0 })
+  }
+
+  /** The user looked at the log: clear the unread badge. */
+  markLogsRead(): void {
+    if (this.state.logUnread === 0) return
+    this.mutate({ logUnread: 0 })
+  }
+
   private flashError(error: unknown): void {
     this.mutate({ notice: error instanceof Error ? error.message : String(error) })
   }
@@ -1760,7 +1961,7 @@ export class AcpStore {
   private applyEvent(event: AcpEvent): Promise<void> {
     switch (event.type) {
       case 'agent/notice': {
-        this.mutate({ notice: event.text })
+        this.mutate(this.logPatch(event.level, event.text, event.agentId))
         return Promise.resolve()
       }
       case 'agent/status': {
@@ -1790,6 +1991,7 @@ export class AcpStore {
         return Promise.resolve()
       }
       case 'session/closed': {
+        const closingSession = this.state.sessions.find(s => s.sessionId === event.sessionId)
         const sessions = this.state.sessions.filter(s => s.sessionId !== event.sessionId)
         const active = this.state.activeSessionId === event.sessionId ? sessions[0]?.sessionId : this.state.activeSessionId
         this.openTurns.delete(event.sessionId)
@@ -1805,7 +2007,9 @@ export class AcpStore {
           chatTranscripts: closedTranscripts,
           ...(chatSessions.length !== this.state.chatSessions.length ? { chatSessions } : {}),
           permissions: this.state.permissions.filter(p => p.sessionId !== event.sessionId),
-          ...(event.reason === 'agent-died' ? { notice: this.locale('会话因 agent 进程退出而终止', 'session ended: agent process died') } : {}),
+          ...(event.reason === 'agent-died'
+            ? this.logPatch('error', this.locale('会话因 agent 进程退出而终止', 'session ended: agent process died'), closingSession?.agentId)
+            : {}),
         })
         return Promise.resolve()
       }
@@ -1822,6 +2026,31 @@ export class AcpStore {
         const chatSessions = this.state.chatSessions.some(s => s.sessionId === event.sessionId)
           ? this.state.chatSessions.map(s => (s.sessionId === event.sessionId ? { ...s, released: true } : s))
           : this.state.chatSessions
+        // One runtime-log line per release cause; `idle` stays silent on
+        // purpose (an expected lifecycle transition, not a fault).
+        const cause = event.cause ?? 'died'
+        let log: Partial<Pick<UiState, 'logs' | 'logUnread'>> = {}
+        if (cause === 'workspace') {
+          log = this.logPatch('info', this.locale(
+            'agent 为切换工作区重启，会话已挂起；再次发送消息将自动恢复。',
+            'agent restarted for its workspace; the session is paused and will resume on your next message.',
+          ), event.session.agentId)
+        } else if (cause === 'resume-failed') {
+          log = this.logPatch('error', this.locale(
+            '会话恢复失败；再次发送消息将重试恢复。',
+            'session resume failed; your next message will retry it.',
+          ), event.session.agentId)
+        } else if (cause === 'stalled') {
+          log = this.logPatch('error', this.locale(
+            'agent 未响应卡死的回合，会话已挂起；再次发送消息将自动恢复。',
+            'agent did not acknowledge the stalled turn; the session is paused and will resume on your next message.',
+          ), event.session.agentId)
+        } else if (cause === 'died') {
+          log = this.logPatch('error', this.locale(
+            'agent 进程已退出，会话已挂起；再次发送消息将自动恢复。',
+            'agent process died; the session is paused and will resume on your next message.',
+          ), event.session.agentId)
+        }
         this.mutate({
           sessions,
           ...(chatSessions !== this.state.chatSessions ? { chatSessions } : {}),
@@ -1829,10 +2058,7 @@ export class AcpStore {
           // An observed transcript keeps its buffer but flips to released, so
           // the ACP view can say "会恢复" instead of silently looking dead.
           ...this.watchedSessionPatch(event.sessionId, event.session),
-          notice: this.locale(
-            'agent 进程已退出，会话已挂起；再次发送消息将自动恢复。',
-            'agent process died; the session is paused and will resume on your next message.',
-          ),
+          ...log,
         })
         return Promise.resolve()
       }

package/src/impl.ts

@@ -8,7 +8,7 @@
 import { randomUUID } from './ids.ts'
 import type {
   AcpAgentCatalog, AcpAgentDef, AcpCatalogOption, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpMcpServerDef, AcpPluginConfig, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult,
-  AgentView, ApprovalDeadlineKey, ApprovalDeadlinePatch, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, PermissionOptionView, PermissionOutcome, PermissionTimeoutMode, RpcResult,
+  AgentView, ApprovalDeadlineKey, ApprovalDeadlinePatch, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, PermissionOptionView, PermissionOutcome, PermissionTimeoutMode, PluginUpdateState, RpcResult,
 } from './protocol.ts'
 import { DEFAULT_TAG_HALO } from './protocol.ts'
 
@@ -535,6 +535,22 @@ export function validateConfig(raw: unknown): AcpPluginConfig {
   if (typeof staleCancelMaxRetries !== 'number' || !Number.isInteger(staleCancelMaxRetries) || staleCancelMaxRetries < 0 || staleCancelMaxRetries > 5) {
     throw new AcpError('bad_config', 'acp: staleCancelMaxRetries must be an integer in [0, 5]')
   }
+  // Stall-recovery windows (inactivity watchdog). Two lengths on purpose: a
+  // silent turn with the floor is a stuck agent, but a turn waiting on a TOOL
+  // call is a working agent, and the tool half may take as long as the guard's
+  // own tool-output wait. `0` means "off" / "fall back", never "expire now".
+  const turnStallMs = value.turnStallMs ?? 600_000
+  if (typeof turnStallMs !== 'number' || !Number.isInteger(turnStallMs) || turnStallMs < 0 || turnStallMs > 86_400_000) {
+    throw new AcpError('bad_config', 'acp: turnStallMs must be an integer in [0, 86400000] (0 = disable the watchdog)')
+  }
+  const turnStallToolMs = value.turnStallToolMs ?? 1_800_000
+  if (typeof turnStallToolMs !== 'number' || !Number.isInteger(turnStallToolMs) || turnStallToolMs < 0 || turnStallToolMs > 86_400_000) {
+    throw new AcpError('bad_config', 'acp: turnStallToolMs must be an integer in [0, 86400000] (0 = fall back to turnStallMs)')
+  }
+  const turnStallTickMs = value.turnStallTickMs ?? 30_000
+  if (typeof turnStallTickMs !== 'number' || !Number.isInteger(turnStallTickMs) || turnStallTickMs < 1 || turnStallTickMs > 60_000) {
+    throw new AcpError('bad_config', 'acp: turnStallTickMs must be an integer in [1, 60000]')
+  }
   return {
     agents,
     transcriptMaxEntries: max,
@@ -545,6 +561,9 @@ export function validateConfig(raw: unknown): AcpPluginConfig {
     cancelFallbackMs,
     staleCancelRetryDelayMs,
     staleCancelMaxRetries,
+    turnStallMs,
+    turnStallToolMs,
+    turnStallTickMs,
   }
 }
 
@@ -1649,6 +1668,19 @@ export class PermissionLedger {
     return [...this.pending.values()].map(e => ({ requestId: e.requestId, sessionId: e.sessionId }))
   }
 
+  /**
+   * Whether ANY outstanding ask belongs to `sessionId`, a HOST session id
+   * (`LiveSession.sessionId`) — NOT the ACP protocol session id. Used by the
+   * stall watchdog: a turn blocked on a human is not a silent turn, so the
+   * session with a pending permission must not be finalized as stalled.
+   */
+  hasPendingFor(sessionId: string): boolean {
+    for (const entry of this.pending.values()) {
+      if (entry.sessionId === sessionId) return true
+    }
+    return false
+  }
+
   /**
    * Outstanding asks WITH the view the browser was shown, for the reconnect
    * replay. Entries created without a view are skipped: replaying a frame the
@@ -1874,6 +1906,24 @@ export interface AcpManager {
    * the registry service), which hides the panel block instead of guessing.
    */
   presetStatus?(): Promise<AcpPresetStatus | undefined>
+  /**
+   * The installed host package's version, reported for the settings page's
+   * badge. `undefined` on a host half that predates the endpoint, which hides
+   * the badge rather than showing a number the browser invented.
+   */
+  pluginVersion?(): string | undefined
+  /**
+   * Ask the host's plugin manager what is published for this package. Read-only
+   * toward the installation: never downloads, never swaps files, never restarts
+   * the host. Absent on a host half from before the updater existed.
+   */
+  pluginUpdateCheck?(): Promise<PluginUpdateState>
+  /**
+   * Install one exact stable version THROUGH the host's plugin manager. The
+   * manager owns download/restart semantics; this plugin only relays. Absent on
+   * an older host half.
+   */
+  pluginUpdateApply?(version: string): Promise<PluginUpdateState>
 }
 
 function ok<T>(value: T): RpcResult<T> {
@@ -2038,6 +2088,21 @@ export async function dispatchRpc(manager: AcpManager, endpoint: string, payload
       }
       case 'preset/status':
         return ok({ preset: await manager.presetStatus?.() ?? null })
+      case 'plugin/version':
+        // Absent on a host half from before the badge existed: the browser
+        // hides it instead of naming a version it cannot know.
+        return ok({ version: manager.pluginVersion?.() })
+      case 'plugin/update-check':
+        // An older host half answers `unsupported` rather than failing: the
+        // settings card then hides the update section.
+        return ok(await (manager.pluginUpdateCheck?.() ?? { status: 'unsupported' as const, current: '' }))
+      case 'plugin/update-apply': {
+        const version = str(body, 'version', 64)
+        if (!/^\d+\.\d+\.\d+$/.test(version)) {
+          throw new AcpError('bad_payload', 'acp: version must be a stable semver (x.y.z)')
+        }
+        return ok(await (manager.pluginUpdateApply?.(version) ?? { status: 'unsupported' as const, current: '' }))
+      }
       case 'agent/stop':
         await manager.stopAgent(str(body, 'agentId', 64)); return ok({ done: true })
       case 'default/agent':

package/src/index.ts

@@ -8,10 +8,12 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type { ConnectionRpcHandler, HostConnectionHandle } from '@deepseek-ai/dsh-client-connection'
-import { ACP_PRESET_ID, AcpLlmAdapter, BridgeManager } from './bridge.ts'
+import { ACP_PRESET_ID, AcpLlmAdapter, BridgeManager, PLUGIN_VERSION } from './bridge.ts'
 import { EventHub, dispatchRpc, permissionReplayFrames, sessionAgentPreset, sessionAgentPresetFromLog, validateConfig } from './impl.ts'
 import type { AcpEvent, ApprovalDeadlineKey } from './protocol.ts'
 import type { RosterPresetRow, SessionLogLike } from './impl.ts'
+import { UpdateService } from './update.ts'
+import type { UpdateManagerLike } from './update.ts'
 
 export const name = 'dsh-ntr'
 // Deliberately minimal: every other host service is probed structurally
@@ -86,9 +88,22 @@ export function apply(ctx: Context, config?: unknown): void {
       cancelFallbackMs: resolved.cancelFallbackMs,
       staleCancelRetryDelayMs: resolved.staleCancelRetryDelayMs,
       staleCancelMaxRetries: resolved.staleCancelMaxRetries,
+      turnStallMs: resolved.turnStallMs,
+      turnStallToolMs: resolved.turnStallToolMs,
+      turnStallTickMs: resolved.turnStallTickMs,
     },
   )
   const adapter = new AcpLlmAdapter(manager)
+  // Built-in update: the plugin never downloads or swaps files itself. The
+  // harness plugin manager owns the install; this only relays its facts.
+  // `resolveManager` re-probes on every call so a late-loading service is
+  // picked up without an `inject` dependency (a host without it must still
+  // load this plugin, and then reports `unsupported`).
+  manager.setUpdateService(new UpdateService({
+    resolveManager: () => (typeof ctx.get === 'function' ? ctx.get('pluginManager') : undefined) as UpdateManagerLike | undefined,
+    currentVersion: PLUGIN_VERSION,
+    isBusy: () => manager.hasActiveTurns(),
+  }))
   // The RAW patch-file deadlines, before validation filled the defaults in.
   // `validateConfig` returns a number for every knob, so the validated object
   // cannot tell "the deployment asked for 10 minutes" from "the deployment said

package/src/protocol.ts

@@ -238,6 +238,50 @@ export interface AcpPluginConfig {
    * up and reports the `cancelled` stop as-is. Default 2.
    */
   staleCancelMaxRetries?: number
+  /**
+   * Inactivity watchdog for a turn the agent owes an answer: how long the turn
+   * may stay SILENT before the host finalizes it as stalled.
+   *
+   * The clock is `LiveSession.lastAgentActivityAt`, refreshed by ANY
+   * `session/update`, at every turn start, at each segment start (the host
+   * handing the turn back after a card), and when a permission ask arrives or
+   * is resolved. The watchdog only READS it while the turn is watched: an OPEN
+   * agent segment (always true on the `/acp`-RPC path, which has no driver
+   * stream) and no pending approval. The host-card execution phase and an
+   * unanswered ask are exempt by that gate, not because the clock is frozen —
+   * they legitimately move it too.
+   *
+   * Firing finalizes the TURN only (an `agent/notice` plus the usual turn
+   * end); it does NOT kill the agent process. The wedged `session/prompt` is
+   * abandoned, and the next message reclaims the session: parked with
+   * `releaseAll` and resumed with `session/load`, or reset outright when the
+   * agent declares no `loadSession` (the context is gone and the user is
+   * told).
+   *
+   * Default 600000 ms (10 minutes); `0` disables the WHOLE watchdog, the tool
+   * window included.
+   */
+  turnStallMs?: number
+  /**
+   * The longer silence window applied while ANY ACP tool call is still active
+   * by `toolCallId` — parallel calls are tracked as a set, so the window lasts
+   * until the LAST of them finishes. The agent is working on its own clock in
+   * there, so the plain turn window would call a healthy long-running tool
+   * stalled.
+   *
+   * Default 1800000 ms (30 minutes); `0` falls back to
+   * {@link AcpPluginConfig.turnStallMs}. It matches
+   * `TOOL_OUTPUT_WAIT_MS = 30 * 60 * 1000` in `presets/acp/acp-guard.mjs`, so
+   * the two halves of one turn agree on how long a tool may take.
+   */
+  turnStallToolMs?: number
+  /**
+   * How often the watchdog scans for silent turns, in milliseconds. A tuning /
+   * test knob only: NO settings-page control exists for it — and none for the
+   * two windows above either; the whole watchdog is configured in the patch
+   * file. Default 30000 ms.
+   */
+  turnStallTickMs?: number
 }
 
 // ---- Host → browser events (`/api/acp/stream`, SSE) ----
@@ -288,6 +332,12 @@ export interface AgentView {
   idleTimeoutMs?: number
 }
 
+/**
+ * Why the host released a session's agent process. The browser turns this into
+ * one runtime-log line per cause; `idle` stays silent (expected lifecycle).
+ */
+export type AcpReleaseCause = 'idle' | 'workspace' | 'resume-failed' | 'stalled' | 'died'
+
 export type AcpEvent =
   | { type: 'agent/status'; agentId: string; state: AgentProcessState; error?: string; agent?: AgentView }
   | { type: 'agent/notice'; agentId: string; level: 'info' | 'error'; text: string }
@@ -300,6 +350,8 @@ export type AcpEvent =
     sessionId: string
     session: SessionView
     reason: string
+    /** Host's release-cause classification; absent on an older host half. */
+    cause?: AcpReleaseCause
   }
   | {
     /**
@@ -564,6 +616,38 @@ export interface AgentIdPayload { agentId: string }
 export interface DefaultAgentSetPayload { agentId?: string }
 /** `default/agent`: the plugin's own default agent id, or `undefined` when unset. */
 export type DefaultAgentResult = { agentId?: string }
+/** `plugin/version`: the installed host package's version, for the settings badge. */
+export type PluginVersionResult = { version?: string }
+
+/**
+ * Where the plugin's own update check stands. The host half only ever reports
+ * facts it can read from the harness plugin manager and the npm registry — it
+ * never downloads, swaps files, or restarts itself.
+ */
+export type PluginUpdateStatus =
+  | 'unsupported' | 'not-installed' | 'source-install' | 'managed'
+  | 'current' | 'available' | 'applying' | 'busy'
+  | 'applied' | 'restart-required' | 'failed'
+
+/**
+ * One update-check answer, shared by `plugin/update-check` and
+ * `plugin/update-apply`.
+ */
+export interface PluginUpdateState {
+  status: PluginUpdateStatus
+  /** 运行中（内存里）的插件版本 */
+  current: string
+  /** 磁盘上装着的版本（listBundles().version），可读时才有 */
+  installed?: string
+  /** profile registry 链上最新的稳定版 */
+  latest?: string
+  /** latest 的 npm 发布时间 ISO */
+  publishedAt?: string
+  /** 实际按顺序问过的 registry */
+  registries?: string[]
+  /** 失败/额外说明（英文技术信息，UI 自己负责本地化） */
+  message?: string
+}
 
 /**
  * How the composer-edge agent tag shows liveness (the blue halo). `breath`