dsh-ntr 0.2.1 → 0.3.0

package/lib/impl.js

@@ -514,6 +514,22 @@ export function validateConfig(raw) {
     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,
@@ -524,6 +540,9 @@ export function validateConfig(raw) {
         cancelFallbackMs,
         staleCancelRetryDelayMs,
         staleCancelMaxRetries,
+        turnStallMs,
+        turnStallToolMs,
+        turnStallTickMs,
     };
 }
 // ---- Workspace guard ----
@@ -1499,6 +1518,19 @@ export class PermissionLedger {
     sessionIds() {
         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) {
+        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
@@ -1734,6 +1766,21 @@ export async function dispatchRpc(manager, endpoint, 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', 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', current: '' }));
+            }
             case 'agent/stop':
                 await manager.stopAgent(str(body, 'agentId', 64));
                 return ok({ done: true });

package/lib/index.js

@@ -4,8 +4,9 @@
  * them down with the plugin fiber. Named exports only (a default export would
  * hide the loader metadata — see harness postmortem 0001).
  */
-import { ACP_PRESET_ID, AcpLlmAdapter, BridgeManager } from "./bridge.js";
+import { ACP_PRESET_ID, AcpLlmAdapter, BridgeManager, PLUGIN_VERSION } from "./bridge.js";
 import { EventHub, dispatchRpc, permissionReplayFrames, sessionAgentPreset, sessionAgentPresetFromLog, validateConfig } from "./impl.js";
+import { UpdateService } from "./update.js";
 export const name = 'dsh-ntr';
 // Deliberately minimal: every other host service is probed structurally
 // (`ctx.get` + a late `ctx.inject`) so a deployment without one still loads
@@ -28,8 +29,21 @@ export function apply(ctx, config) {
         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),
+        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/lib/types/bridge.d.ts

@@ -9,7 +9,15 @@
 import { type InitializeResponse } from '@agentclientprotocol/sdk';
 import { EventHub, PermissionLedger, Transcript } from './impl.ts';
 import type { AcpToolCallSnapshot, PendingPermissionView, RosterPresetRow } from './impl.ts';
-import type { AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, GenerateOptions, LlmAdapterLike, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, ApprovalDeadlineKey, ApprovalDeadlinePatch, PermissionTimeoutMode, PreparedAdapterCall, SessionView, StreamChunk } from './protocol.ts';
+import type { AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, GenerateOptions, LlmAdapterLike, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, ApprovalDeadlineKey, ApprovalDeadlinePatch, PermissionTimeoutMode, PluginUpdateState, PreparedAdapterCall, SessionView, StreamChunk } from './protocol.ts';
+import { UpdateService } from './update.ts';
+/**
+ * Version of this installed package, read from the shipped `package.json` —
+ * one level above both `src/` at test time and `lib/` at runtime. The settings
+ * badge and the ACP handshake's `clientInfo` both report it; a copied literal
+ * would go stale on every release.
+ */
+export declare const PLUGIN_VERSION: string;
 interface LiveSession {
     /** Host-minted id (stable across an agent restart; the ACP id is per-connection). */
     sessionId: string;
@@ -37,6 +45,20 @@ interface LiveSession {
     closed: boolean;
     /** The agent process died; the session awaits a `session/load` resume. */
     released: boolean;
+    /**
+     * When the agent last showed ANY sign of life on this session: an update, a
+     * permission ask (arrival or answer), or a turn start. The stall watchdog
+     * measures silence from here rather than from the prompt, which may
+     * legitimately be followed by a long tool run.
+     */
+    lastAgentActivityAt: number;
+    /**
+     * Tool calls the agent announced and has not finished, by ACP `toolCallId`.
+     * A SET, not a flag: parallel calls finish independently, and one sibling's
+     * `completed` must not clear the long tool window while another is still
+     * running. Non-empty = the agent is working on its own clock.
+     */
+    activeToolCalls: Set<string>;
     /**
      * Owning DSH chat session id, when the session was opened through the LLM
      * adapter (`AcpLlmAdapter`). It is what the conversation's permission card
@@ -90,6 +112,36 @@ interface LiveSession {
      * that answer means the message was silently dropped.
      */
     cancelRequestedAtTurn?: number;
+    /**
+     * The {@link turnSeq} of a turn the stall watchdog force-finalized while the
+     * agent still held its `session/prompt`. The agent is presumed wedged, so the
+     * NEXT prompt reclaims the process (`BridgeManager.prepareStalledSession`)
+     * instead of queueing behind a turn that may never answer. Cleared when the
+     * late response lands or when the reclaim replaces the process.
+     */
+    orphanPromptTurnSeq?: number;
+    /**
+     * The {@link turnSeq} of a turn a reclaim (`prepareStalledSession`) ended by
+     * closing the connection while the agent still held its `session/prompt`.
+     * The close rejects that request, and the caller's catch would broadcast a
+     * second `turn/end` for a turn already finalized: this marker tells the
+     * late `then`/`catch` to drop the answer instead. Set by the reclaim, cleared
+     * when that answer lands, at every new turn start, and by a resume.
+     */
+    reclaimedTurnSeq?: number;
+    /**
+     * The controller of the turn currently streaming through this session.
+     *
+     * Chat turns are ALSO indexed by chat id ({@link BridgeManager}'s
+     * `turnStreams`) because their continuation steps arrive as fresh
+     * `streamPrompt` calls that look the turn up by chat id. An EPHEMERAL turn
+     * (`options.sessionId === undefined`) has no chat id to index under, so this
+     * attachment is the only way the stall watchdog can find its controller —
+     * without it a silent ephemeral turn falls into the `/acp` branch, which
+     * leaves the driver's segment queue open instead of finishing it. Cleared by
+     * the controller's own `retire` when it still points at it.
+     */
+    turnController?: TurnStreamController;
     transcript: Transcript;
 }
 /** Reliability tuning, threaded from `AcpPluginConfig` through the manager. */
@@ -155,6 +207,23 @@ export interface BridgeTuning {
      * racing a concurrent `session/prompt` into the agent.
      */
     turnSettleMs?: number;
+    /**
+     * How long a turn may stay SILENT — no update, no ask, no turn start — before
+     * the watchdog force-finalizes it as stalled. The turn is only watched while
+     * the agent is the one holding the floor (a segment on air, no pending ask),
+     * and the process survives: the next message reclaims it.
+     *
+     * `0` disables the watchdog.
+     */
+    turnStallMs?: number;
+    /**
+     * The longer silence window used while an ACP tool call is in progress: the
+     * agent runs the tool on its own clock, so the plain turn window would call
+     * a healthy long-running tool stalled. `0` falls back to `turnStallMs`.
+     */
+    turnStallToolMs?: number;
+    /** How often the watchdog scans for silent turns. */
+    turnStallTickMs?: number;
     /**
      * Default idle-release window for agents without their own
      * `AcpAgentDef.idleTimeoutMs`: a READY process that holds no live session
@@ -248,8 +317,19 @@ export declare class AgentBridge {
     private lastActivityAt;
     /** Throwaway catalog probes in flight — they hold no live session of their own. */
     private pendingProbes;
-    /** Host→agent session commands in flight (mode / config); not turns. */
-    private pendingCommands;
+    /**
+     * Host→agent session commands in flight (mode / config); not turns. Counted
+     * PER SESSION: a command the wedged agent never answers must not pin the
+     * bridge against reclaiming THAT session (it is exactly the state the
+     * watchdog is recovering from), while another session's command still does.
+     */
+    private readonly pendingCommands;
+    /**
+     * `session/new` requests in flight. The session does not exist in `sessions`
+     * yet, so nothing else would tell a teardown (`releaseAll` / idle release)
+     * that a caller is waiting on the child it is about to kill.
+     */
+    private pendingCreates;
     /**
      * Whether a REAL session has ever been registered on this bridge. Probes
      * bypass session bookkeeping, so a bridge that has never hosted anything was
@@ -383,6 +463,12 @@ export declare class AgentBridge {
      * @returns the settler (idempotent; also used by connection loss).
      */
     beginTurn(session: LiveSession): () => void;
+    /**
+     * Open a session's settle gate without owning its turn stream: the turn's
+     * stream is gone (a resume, a release) but the next prompt still waits on
+     * this promise, and nothing is left that could ever resolve it.
+     */
+    private openSettleGate;
     view(): AgentView;
     /**
      * Work a teardown would interrupt: a turn in flight (or one the agent is
@@ -390,6 +476,18 @@ export declare class AgentBridge {
      * probe, a resume, or a start. A registered-but-idle session is NOT work.
      */
     private hasActiveWork;
+    /**
+     * Active work on this bridge EXCEPT `session`'s own — what a restart-carrying
+     * reclaim (the stall watchdog's follow-up) would destroy. Killing this child
+     * restarts every ACP session on the connection, so a live conversation that
+     * is mid-turn, mid-resume, or waiting on a human pins the process: its
+     * context is the one thing a restart cannot give back.
+     *
+     * `session`'s OWN mode/config command is deliberately not counted: an agent
+     * that ignores `session/set_mode` would otherwise make its own stall
+     * unrecoverable — the command's counter is exactly the evidence of the wedge.
+     */
+    hasOtherActiveWork(session: LiveSession): boolean;
     /**
      * Nothing depends on this child's identity right now: no live session and no
      * work. This is the WORKSPACE MOVE's predicate. It stays stricter than the
@@ -398,6 +496,13 @@ export declare class AgentBridge {
      * state for a restart on every cross-workspace turn.
      */
     private isQuiet;
+    /**
+     * A turn is in flight (or the agent has not settled its response yet) on any
+     * of this bridge's sessions. `settled` only stays non-undefined while the
+     * agent's answer is outstanding — the settler clears it on completion — so
+     * this is real work, not an idle session.
+     */
+    hasActiveTurn(): boolean;
     /**
      * An idle teardown is safe when nothing is WORKING. Idle live sessions do not
      * block it: `releaseAll` parks them as `released` (never closed), and the next
@@ -437,6 +542,8 @@ export declare class AgentBridge {
      * @param spawnCwd - where the agent PROCESS should run; see `ensureReady`.
      */
     createSession(cwd: string | undefined, extraRoots?: readonly string[], spawnCwd?: string): Promise<LiveSession>;
+    /** The body of {@link createSession}; the caller keeps `pendingCreates` for it. */
+    private openSession;
     /**
      * Spawn a throwaway ACP session purely to read its `configOptions` (the
      * model catalog probe). Deliberately bypasses the live-session bookkeeping
@@ -482,6 +589,17 @@ export declare class AgentBridge {
      * successor — so a moved-on {@link LiveSession.turnSeq} disarms it.
      */
     private armCancelFallback;
+    /**
+     * Force the local end of one turn whose agent never acknowledged it: clear
+     * `running`, open the settle gate, and broadcast the turn end with `turnId:
+     * ''` (there is no agent response to attribute it to). Shared by the cancel
+     * fallback and the stall watchdog.
+     *
+     * Generation-guarded: a turn that already ended — or that a later turn
+     * superseded — is not this call's to finalize. Returns whether it acted; a
+     * `false` means the caller was late and must leave the session alone.
+     */
+    finalizeTurn(session: LiveSession, turnGen: number, message: string): boolean;
     /**
      * Bring a released session back on a fresh agent process via
      * `session/load` ("send to recover"). Concurrent callers share one inflight
@@ -512,6 +630,18 @@ export declare class AgentBridge {
     hasSession(sessionId: string): LiveSession | undefined;
     /** Kill the child and drop every local session bound to this connection. */
     stop(reason?: 'closed' | 'agent-stopped' | 'agent-died'): Promise<void>;
+    /**
+     * Drop every live session record and kill the child WITHOUT asking the agent
+     * to close them. `stop` sends `session/close` per session, and a wedged agent
+     * that ignores it would hang the caller (the stall reclaim) — the very agent
+     * this teardown exists to get rid of. The local teardown is what frees the
+     * sessions, so it runs unconditionally and immediately.
+     *
+     * Deliberately does NOT clear `released`: those records are constraint 10's
+     * — a released session survives a process death and is resumed by its next
+     * message. This is a stop, not a discard.
+     */
+    forceReset(reason: 'agent-stopped'): void;
     private killChild;
     /**
      * Answer one ACP permission ask.
@@ -838,6 +968,7 @@ type TurnSettle = {
 } | {
     kind: 'error';
     message: string;
+    code?: string;
 };
 /**
  * The state of ONE ACP prompt, shared across every driver step of the turn.
@@ -875,6 +1006,8 @@ declare class TurnStreamController {
     get replayCursor(): number;
     /** Whether the agent already settled its `session/prompt` for this turn. */
     get hasSettled(): boolean;
+    /** Whether a segment is on air — the agent is expected to speak into a live driver step. */
+    get hasOpenSegment(): boolean;
     /** Generation guard: a controller whose turn has been superseded must not touch the session. */
     get stale(): boolean;
     /**
@@ -894,6 +1027,13 @@ declare class TurnStreamController {
     abortActiveSegment(): void;
     /** Stop observing and release the manager's index. Idempotent. */
     dispose(): void;
+    /**
+     * Stop observing and release the manager's index WITHOUT touching the
+     * process-wide tool-output waiters. A late settle of a superseded turn must
+     * use this: those waiters now belong to the turn on air, and waking them
+     * early would hand the guard a "no output" answer for a tool still running.
+     */
+    retire(): void;
     private finishSegment;
     /** A segment opened on an already-settled turn: replay, then close it out. */
     private finishAfterSettle;
@@ -1016,6 +1156,28 @@ export declare class BridgeManager {
     forgetTurnStream(controller: TurnStreamController): void;
     /** Tear down the turn streams of every session of one bridge (close/release/stop). */
     private disposeTurnStreamsOf;
+    /**
+     * The stall watchdog's scan loop. Armed lazily at the first turn start and
+     * DROPPED once nothing anywhere is running: a manager that never runs a turn
+     * never holds a timer, and one that goes quiet does not keep the host awake.
+     */
+    private stallTimer?;
+    private armStallTimer;
+    /**
+     * Force-finalize turns the agent has gone silent in.
+     *
+     * "Silent" is scoped to the stretch where the AGENT owes the turn a word: a
+     * running session with a segment on air and no pending ask. A turn waiting on
+     * the host (tool cards executing between segments) or on a human (an
+     * unanswered permission) is not stuck and is skipped.
+     *
+     * Firing does NOT kill the process (see `LiveSession.orphanPromptTurnSeq`):
+     * the session, its transcript and its binding survive, and the next message
+     * reclaims the process. The turn's streaming face ends through its own
+     * controller when there is one, so the driver step on air closes with an
+     * error instead of being torn down mid-stream.
+     */
+    private reapStalledTurns;
     constructor(defs: readonly AcpAgentDef[], hub: EventHub, transcriptMax: number, configStoragePath?: string | undefined, catalogStoragePath?: string | undefined, 
     /** Auto-probe agents for model catalogs (boot + lazy); manual probes always run. */
     probeModelsOnBoot?: boolean, tuning?: BridgeTuning);
@@ -1252,6 +1414,23 @@ export declare class BridgeManager {
      * the block rather than claiming the preset is gone.
      */
     presetStatus(): Promise<AcpPresetStatus | undefined>;
+    /** The installed package's version (the settings page's badge). */
+    pluginVersion(): string;
+    /** Wire the built-in updater (host entry only; absent in pure tests). */
+    setUpdateService(service?: UpdateService): void;
+    /** Registry check for the settings card; `unsupported` when no updater is wired. */
+    pluginUpdateCheck(): Promise<PluginUpdateState>;
+    /** Delegate one install to the host plugin manager; never touches files itself. */
+    pluginUpdateApply(version: string): Promise<PluginUpdateState>;
+    /**
+     * Whether any ACP work is in flight. An update install may restart the host,
+     * so check/apply describe the host as busy while a turn is running.
+     *
+     * Segmented turn streams count even between steps (the host is still
+     * continuing that turn); `running` / `settled` on a session covers `/acp`
+     * turns and the window between a prompt and the agent's acknowledgement.
+     */
+    hasActiveTurns(): boolean;
     private getStoragePath;
     /**
      * Read the agent registry file.
@@ -1522,6 +1701,8 @@ export declare class BridgeManager {
     prompt(sessionId: string, text: string): Promise<{
         turnId: string;
     }>;
+    /** The late answer landed (or failed): the turn is no longer an orphan. */
+    private clearOrphanPrompt;
     cancel(sessionId: string): Promise<void>;
     closeSession(sessionId: string): Promise<void>;
     setMode(sessionId: string, modeId: string): Promise<void>;
@@ -1539,6 +1720,11 @@ export declare class BridgeManager {
     shutdownAll(): Promise<void>;
     /** Host-side reader of the harness preset roster (`ctx.agentPresets`), for `presetStatus`. */
     private presetRosterReader?;
+    /**
+     * The built-in updater, wired by the host entry. Absent in pure bridge tests —
+     * the update RPCs then answer `unsupported` instead of inventing a source.
+     */
+    private updateService?;
     /**
      * The plugin's own default ACP agent (the panel's ★ gesture): which agent an
      * ACP-mode conversation starts on. Host-side state in the agent registry
@@ -1633,6 +1819,22 @@ export declare class BridgeManager {
      */
     private seedChatChoiceFromCatalog;
     getOrCreateDshSession(dshSessionId: string | undefined, agentId: string, cwd?: string): Promise<LiveSession>;
+    /**
+     * Take the agent process back from a turn the stall watchdog abandoned.
+     *
+     * The wedged agent still holds its `session/prompt`, so the next message
+     * cannot simply be sent: it would queue behind a turn that may never answer.
+     * The process is restarted instead — unless another conversation on the same
+     * connection is doing real work, because killing the child destroys THEIR
+     * context too, and "retry after they finish" is the honest answer.
+     *
+     * A restart that can `session/load` costs the conversation nothing: the
+     * session is parked `released` and the normal acquisition path resumes it, so
+     * chat keeps its lock / `applyChatChoice` semantics and `/acp` keeps
+     * `locateOrResume`. An agent without resume support is reset instead, and the
+     * user is told the context is gone.
+     */
+    private prepareStalledSession;
     streamPrompt(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }
 export declare class AcpLlmAdapter implements LlmAdapterLike {

package/lib/types/client/store.d.ts

@@ -5,7 +5,7 @@
  *
  * Deliberately framework-free: React binds through `useSyncExternalStore`.
  */
-import type { AcpApprovalDeadlines, AcpConversationChoice, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentSavePayload, AgentTestResult, AgentView, ChatSessionView, DetectedAgentInfo, PermissionTimeoutMode, SessionView } from '../protocol.ts';
+import type { AcpApprovalDeadlines, AcpConversationChoice, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentSavePayload, AgentTestResult, AgentView, ChatSessionView, DetectedAgentInfo, PermissionTimeoutMode, PluginUpdateState, SessionView } from '../protocol.ts';
 /** One slash command the ACP agent declared, whole row (the menu draws name, description and `input.hint`). */
 export type AgentCommand = NonNullable<ChatSessionView['availableCommands']>[number];
 /** The unary RPC face (narrowed `ctx.connection.rpc.call`). */
@@ -304,6 +304,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;
@@ -375,6 +387,22 @@ export declare class AcpStore {
     private readonly cachedModelReads;
     /** Counts behind the last successful explicit re-detect, so a locale switch can re-render its summary. */
     private detectCounts;
+    /** When {@link UiState.pluginUpdate} was last read from the host (epoch ms). */
+    private pluginUpdateFetchedAt;
+    /**
+     * 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?;
+    /** Re-entry guard for `plugin/update-apply` (a double click is one install). */
+    private pluginUpdateApplying;
+    /**
+     * 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;
     constructor(rpc: RpcCall, locale: (zh: string, en: string) => string);
     subscribe(listener: Listener): () => void;
     getSnapshot(): UiState;
@@ -398,6 +426,31 @@ export declare class AcpStore {
     private call;
     /** Snapshot refresh used on panel open and after a stream outage. */
     resync(): Promise<void>;
+    /**
+     * 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.
+     */
+    checkPluginUpdate(force?: boolean): Promise<PluginUpdateState | undefined>;
+    private readPluginUpdate;
+    /**
+     * 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.
+     */
+    applyPluginUpdate(version: string): Promise<PluginUpdateState | undefined>;
     detectAgents(): Promise<void>;
     private detectSummaryOf;
     saveAgent(payload: AgentSavePayload): Promise<void>;

package/lib/types/impl.d.ts

@@ -5,7 +5,7 @@
  * fakes.
  */
 import { randomUUID } from './ids.ts';
-import type { AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpMcpServerDef, AcpPluginConfig, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ApprovalDeadlineKey, ApprovalDeadlinePatch, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, PermissionOptionView, PermissionOutcome, PermissionTimeoutMode, RpcResult } from './protocol.ts';
+import type { AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpMcpServerDef, AcpPluginConfig, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ApprovalDeadlineKey, ApprovalDeadlinePatch, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, PermissionOptionView, PermissionOutcome, PermissionTimeoutMode, PluginUpdateState, RpcResult } from './protocol.ts';
 export { randomUUID };
 /** Structured failure the RPC layer converts to `{ok:false, error}` and `apply()` surfaces at boot. */
 export declare class AcpError extends Error {
@@ -605,6 +605,13 @@ export declare class PermissionLedger {
         requestId: string;
         sessionId: string;
     }>;
+    /**
+     * 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;
     /**
      * Outstanding asks WITH the view the browser was shown, for the reconnect
      * replay. Entries created without a view are skipped: replaying a frame the
@@ -808,6 +815,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>;
 }
 /** Dispatch one decoded `/acp` channel call. Never rejects; protocol errors come back as `ok:false`. */
 export declare function dispatchRpc(manager: AcpManager, endpoint: string, payload: unknown): Promise<RpcResult<unknown>>;

package/lib/types/protocol.d.ts

@@ -229,6 +229,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;
 }
 export type AgentProcessState = 'stopped' | 'starting' | 'ready' | 'error';
 /** Agent facts the browser may render (never includes env/argv secrets beyond argv itself, which is config-visible). */
@@ -669,6 +713,35 @@ export interface DefaultAgentSetPayload {
 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`
  * pulses the halo at the speed below; `steady` shows a constant glow.