dsh-ntr 0.1.4 → 0.1.6

package/lib/bridge.js

@@ -12,17 +12,69 @@ import { delimiter, dirname, join } from 'node:path';
 import { Writable, Readable } from 'node:stream';
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { client, methods, ndJsonStream, PROTOCOL_VERSION, RequestError, } from '@agentclientprotocol/sdk';
-import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, isAcpToolContinuation, isUnderPath, mergeCatalogShape, parseCatalogOptions, usableConfigOptions, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, } from "./impl.js";
+import { AcpError, EventHub, PermissionLedger, Transcript, acpToolCallDelta, acpToolCallFromUpdate, buildAdapterModelId, childEnv, isAcpToolContinuation, isUnderPath, mergeCatalogShape, parseCatalogOptions, usableConfigOptions, pickAutoOption, quoteCommandToken, randomUUID, resolveFsPath, resolveSessionCwd, selectForwardPrompt, acpPresetStatusFromRoster, splitAdapterModelId, updateContentToText, describeUnhandledUpdate, BOOKKEEPING_UPDATES, validateAgentDef, validateTagHalo, validateApprovalDeadlines, validatePermissionTimeoutMode, normalizeApprovalWindow, } from "./impl.js";
 import { DEFAULT_TAG_HALO } from "./protocol.js";
 const STDERR_TAIL_LINES = 40;
 /** Single fs/read_text_file answer cap — agents reading huge files must page via `line`/`limit`. */
 const FS_MAX_READ_BYTES = 2 * 1024 * 1024;
 /** Single fs/write_text_file payload cap. */
 const FS_MAX_WRITE_BYTES = 2 * 1024 * 1024;
+/**
+ * The plugin's normalized MCP server shape → the ACP wire shape.
+ *
+ * THE WIRE SHAPE IS ASYMMETRIC, and getting it wrong is SILENT:
+ *
+ *  - the stdio variant carries NO `type` field — an entry that carries
+ *    `type:'stdio'` is accepted by the agent and then never connected
+ *    (measured against codebuddy: the server never appeared, the agent just
+ *    reported the tool as missing);
+ *  - http/sse DO carry `type`;
+ *  - `env` / `headers` are `[{name,value}]` arrays on the wire, while the
+ *    plugin stores them as records (like `AcpAgentDef.env`).
+ *
+ * So the conversion lives here, once, and each branch is annotated with the
+ * SDK's OWN variant type — a wrong conversion does not compile. (The bare
+ * `McpServer` union is too loose to catch it: its excess-property check
+ * accepts any member's keys, so a stdio entry carrying `type:'stdio'` would
+ * type-check against the http variant and only fail at runtime, inside the
+ * agent, as a server that never connects.)
+ */
+function toAcpMcpServers(defs) {
+    if (defs === undefined)
+        return [];
+    return defs.map(def => {
+        if (def.transport === 'stdio') {
+            // NO `type` here — see the note above.
+            const server = {
+                name: def.name,
+                command: def.command,
+                args: def.args ?? [],
+                env: Object.entries(def.env ?? {}).map(([name, value]) => ({ name, value })),
+            };
+            return server;
+        }
+        if (def.transport === 'http') {
+            const server = {
+                type: 'http',
+                name: def.name,
+                url: def.url,
+                headers: Object.entries(def.headers ?? {}).map(([name, value]) => ({ name, value })),
+            };
+            return server;
+        }
+        const server = {
+            type: 'sse',
+            name: def.name,
+            url: def.url,
+            headers: Object.entries(def.headers ?? {}).map(([name, value]) => ({ name, value })),
+        };
+        return server;
+    });
+}
 const DEFAULT_TUNING = {
     startupTimeoutMs: 60_000,
-    permissionTimeoutMs: 0,
-    permissionFallbackTimeoutMs: 300_000,
+    permissionTimeoutMs: 300_000,
+    permissionTimeoutMode: 'wait',
     cancelFallbackMs: 15_000,
     staleCancelRetryDelayMs: 600,
     staleCancelMaxRetries: 2,
@@ -63,8 +115,17 @@ export class AgentBridge {
      */
     ledgerFallbacks = new Map;
     startupTimeoutMs;
+    /**
+     * The ONE approval deadline, and the mode it settles with. Neither is
+     * readonly, unlike their neighbors: the settings page rewrites them on a
+     * running bridge ({@link AgentBridge.applyApprovalDeadlines}), so a user
+     * editing the card does not have to kill every live session to see it take
+     * effect. Both are read per ask, so a reassignment reaches every ask from
+     * that moment on. An ask already holding an armed timer keeps the window it
+     * was started with.
+     */
     permissionTimeoutMs;
-    permissionFallbackTimeoutMs;
+    permissionTimeoutMode;
     cancelFallbackMs;
     staleCancelRetryDelayMs;
     staleCancelMaxRetries;
@@ -131,8 +192,10 @@ export class AgentBridge {
         this.sessionWorkspace = sessionWorkspace;
         const merged = { ...DEFAULT_TUNING, ...tuning };
         this.startupTimeoutMs = merged.startupTimeoutMs;
-        this.permissionTimeoutMs = merged.permissionTimeoutMs;
-        this.permissionFallbackTimeoutMs = merged.permissionFallbackTimeoutMs;
+        this.permissionTimeoutMode = merged.permissionTimeoutMode;
+        // 不等待 (0) is the `auto` mode's business; under `abort` it would refuse
+        // every ask on arrival, so the window is floored to the shortest real wait.
+        this.permissionTimeoutMs = normalizeApprovalWindow(this.permissionTimeoutMode, merged.permissionTimeoutMs);
         this.cancelFallbackMs = merged.cancelFallbackMs;
         this.staleCancelRetryDelayMs = merged.staleCancelRetryDelayMs;
         this.staleCancelMaxRetries = merged.staleCancelMaxRetries;
@@ -140,6 +203,26 @@ export class AgentBridge {
         this.defaultIdleTimeoutMs = merged.idleTimeoutMs;
         this.probeIdleTimeoutMs = merged.probeIdleTimeoutMs;
     }
+    /**
+     * Adopt a rewritten approval deadline or mode (the settings page's write).
+     * Only the window and the mode live here; every other tuning value is
+     * fixed at construction, because a live bridge cannot meaningfully adopt a
+     * new startup or cancel window mid-flight.
+     *
+     * Deliberately does NOT re-arm anything: an ask that already holds a timer
+     * keeps the window it was started with, and the next ask reads the new value.
+     * Re-arming would move the goalposts under a human who is already deciding.
+     */
+    applyApprovalDeadlines(patch) {
+        if (patch.permissionTimeoutMs !== undefined)
+            this.permissionTimeoutMs = patch.permissionTimeoutMs;
+        if (patch.mode !== undefined)
+            this.permissionTimeoutMode = patch.mode;
+        // A mode switch can leave a window behind that the new mode cannot run
+        // (不等待 under `abort`): floor it, so the ask waits instead of refusing
+        // on arrival.
+        this.permissionTimeoutMs = normalizeApprovalWindow(this.permissionTimeoutMode, this.permissionTimeoutMs);
+    }
     /**
      * The idle-release window this agent honors for its CHAT process: its own
      * field, else the host default. This is the number the panel prefills and
@@ -528,7 +611,7 @@ export class AgentBridge {
         if (conn === undefined)
             throw new AcpError('agent_unreachable', 'acp: connection is not open');
         const resolved = resolveSessionCwd(this.def, cwd, p => realpathSync(p), extraRoots);
-        const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.new, { cwd: resolved, mcpServers: [] }), 'session/new');
+        const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.new, { cwd: resolved, mcpServers: toAcpMcpServers(this.def.mcpServers) }), 'session/new');
         // An empty `configOptions` answer is a non-answer — see `usableConfigOptions`.
         if (this.onCatalog !== undefined && usableConfigOptions(result.configOptions)) {
             this.onCatalog(this.def.id, result.configOptions);
@@ -573,6 +656,15 @@ export class AgentBridge {
      * Spawn a throwaway ACP session purely to read its `configOptions` (the
      * model catalog probe). Deliberately bypasses the live-session bookkeeping
      * so probe sessions never surface in the browser session list.
+     *
+     * THE PROBE SENDS THE AGENT'S OWN MCP LIST, not an empty one. Measured
+     * against codebuddy: the servers handed to `session/new` land in the
+     * agent PROCESS's dynamic MCP scope, so a probe that sent an empty list
+     * would REPLACE that scope and drop the MCP servers of the live sessions
+     * on the same connection (the agent logged
+     * `serverManager.delete("injected")` and the live session's
+     * `mcp__injected__*` tools disappeared). One list per agent process is the
+     * only shape that keeps every session of that process consistent.
      */
     async probeConfigOptions() {
         // A probe is the reason an agent process can be resident with NOTHING else
@@ -585,7 +677,7 @@ export class AgentBridge {
             if (conn === undefined)
                 throw new AcpError('agent_unreachable', 'acp: connection is not open');
             const resolved = resolveSessionCwd(this.def, undefined, p => realpathSync(p));
-            const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.new, { cwd: resolved, mcpServers: [] }), 'session/new');
+            const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.new, { cwd: resolved, mcpServers: toAcpMcpServers(this.def.mcpServers) }), 'session/new');
             await conn.agent.request(methods.agent.session.close, { sessionId: result.sessionId }).catch(() => { });
             return Array.isArray(result.configOptions) ? result.configOptions : [];
         }
@@ -640,6 +732,13 @@ export class AgentBridge {
         // own turn apart from a later one.
         session.cancelRequestedAtTurn = session.turnSeq;
         await this.conn.agent.notify(methods.agent.session.cancel, { sessionId: session.acpSessionId }).catch(() => { });
+        // The ACP spec's counterpart to the notification we just sent: a client that
+        // cancels MUST answer every pending `session/request_permission` with
+        // `cancelled`. Leaving them open would hold the agent's tool call blocked on
+        // an answer that can no longer arrive — the turn is over, the human's
+        // decision is "stop". OmniTerm does the same from `AcpClient::cancel`
+        // (`PermissionManager::cancel_all`).
+        this.settlePermissions(session);
         this.armCancelFallback(session);
     }
     /**
@@ -733,7 +832,7 @@ export class AgentBridge {
             // is in flight, and let the browser drop its blocks/watermark first.
             this.acpIndex.set(session.acpSessionId, session);
             this.hub.broadcast({ type: 'session/reset', sessionId: session.sessionId, session: snapshot(session) });
-            const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.load, { sessionId: session.acpSessionId, cwd: resolved, mcpServers: [] }), 'session/load');
+            const result = await this.withStartupTimeout(conn.agent.request(methods.agent.session.load, { sessionId: session.acpSessionId, cwd: resolved, mcpServers: toAcpMcpServers(this.def.mcpServers) }), 'session/load');
             if (this.onCatalog !== undefined && usableConfigOptions(result.configOptions)) {
                 this.onCatalog(this.def.id, result.configOptions);
             }
@@ -956,6 +1055,23 @@ export class AgentBridge {
             this.touch();
             return native.response;
         }
+        // Deadline: how long this ask may sit unanswered. ONE window for every
+        // route — an ask that never reached the conversation included. They have
+        // no other answer entry, so exempting them would be the very invisible
+        // hang this mechanism exists to bound.
+        //
+        // What happens when it fires is the MODE's business: refused, answered
+        // with the option the agent's own kinds imply, or (in `wait`) never.
+        // The mode is read once, here, for the same reason the window is: an ask
+        // that started under one mode keeps it.
+        const mode = this.permissionTimeoutMode;
+        const timeoutMs = this.permissionTimeoutMs;
+        // 不等待（0）只属自动推进：请求到达即按那一档收场，不建 ledger 条目、不发卡
+        // ——问都来不及问。超时中止没有这一档（它会立刻拒绝每一问，agent 在每个门口
+        // 都停住），它的窗口最短是真实等待。
+        if (mode === 'auto' && timeoutMs === 0) {
+            return this.settleExpiredAsk(session, mode, toolCall, options, 0);
+        }
         return new Promise(resolve => {
             let timer;
             const requestId = this.permissions.create(session.sessionId, (outcome) => {
@@ -971,32 +1087,38 @@ export class AgentBridge {
                 resolve(outcome.outcome === 'selected'
                     ? { outcome: { outcome: 'selected', optionId: outcome.optionId } }
                     : { outcome: { outcome: 'cancelled' } });
+            }, {
+                // Kept for the reconnect replay: a client that connects after the ask
+                // was broadcast must be re-shown the very card it has to answer.
+                toolCall,
+                options: options.map((o) => ({ optionId: o.optionId, name: o.name, kind: o.kind })),
             });
-            // Deadline (`permissionTimeoutMs`): an approval left unanswered is
-            // answered `cancelled` on the human's behalf instead of hanging the turn
-            // forever. Off by default — approvals belong to a person. The one
-            // exception is a DEGRADED native route: the conversation just failed to
-            // show the question, so waiting forever would hang the turn behind an
-            // ask nobody can see there, and the fallback deadline applies instead
-            // (see `BridgeTuning.permissionFallbackTimeoutMs`).
-            const timeoutMs = this.permissionTimeoutMs > 0
-                ? this.permissionTimeoutMs
-                : native.reason === 'unavailable' ? this.permissionFallbackTimeoutMs : 0;
             // Recorded before the broadcast: the hub is synchronous, and the chat
             // line `streamPrompt` folds from this frame words itself by the path
             // this ask actually took.
-            this.ledgerFallbacks.set(requestId, { reason: native.reason, timeoutMs });
-            if (timeoutMs > 0) {
+            this.ledgerFallbacks.set(requestId, { reason: native.reason, timeoutMs, mode });
+            if (timeoutMs > 0 && mode !== 'wait') {
                 timer = setTimeout(() => {
                     if (!this.permissions.has(requestId))
                         return;
+                    const picked = mode === 'auto'
+                        ? pickAutoOption(options.map(option => ({ optionId: option.optionId, name: option.name, kind: option.kind })))
+                        : undefined;
+                    const tool = permissionToolName(toolCall);
                     this.hub.broadcast({
                         type: 'agent/notice',
                         agentId: this.def.id,
                         level: 'info',
-                        text: `acp: permission request timed out after ${String(Math.round(timeoutMs / 1000))}s; answered "cancelled"`,
+                        // Name what was missed and what was done about it, the way a human
+                        // needs it: which operation sat unanswered, and what the plugin
+                        // answered instead (OmniTerm's reaper writes the same notice).
+                        text: picked === undefined
+                            ? `acp: permission request for "${tool}" timed out after ${String(Math.round(timeoutMs / 1000))}s; refused`
+                            : `acp: permission request for "${tool}" timed out after ${String(Math.round(timeoutMs / 1000))}s; answered "${picked.name}"`,
                     });
-                    this.permissions.respond(requestId, { outcome: 'cancelled' });
+                    this.permissions.respond(requestId, picked === undefined
+                        ? { outcome: 'cancelled' }
+                        : { outcome: 'selected', optionId: picked.optionId });
                 }, timeoutMs);
                 timer.unref?.();
             }
@@ -1025,8 +1147,19 @@ export class AgentBridge {
      * open turn, so a session started over `/acp` (no chat turn) cannot be
      * routed and must stay on the ledger path.
      *
-     * No `permissionTimeoutMs` timer is armed here on purpose: the human answers
-     * inside the conversation, and a host-side deadline would answer for them.
+     * The ask is raced against {@link BridgeTuning.permissionTimeoutMs}. A
+     * routed ask has exactly one answer entry — the composer takeover — and no
+     * broadcast at all, so a host that takes the question and never renders it
+     * would leave the turn hanging behind something invisible. Past the deadline
+     * the ask is settled RIGHT THERE, by
+     * {@link BridgeTuning.permissionTimeoutMode}: refused (`abort`), answered
+     * with the option the agent's own kinds imply (`auto`), or never expiring
+     * at all (`wait`).
+     *
+     * It is NOT handed somewhere else. An earlier revision withdrew the ask and
+     * re-asked it on the settings ledger, which made the question travel to a
+     * page the user was not looking at — and then cancelled it there a few
+     * minutes later anyway. A deadline now ends the ask where it was asked.
      *
      * @returns the agent-facing response, or the reason the ask must fall back
      * to the ledger (see {@link LedgerFallbackReason}).
@@ -1037,20 +1170,73 @@ export class AgentBridge {
             return { reason: 'no-requester' };
         if (session.dshSessionId === undefined)
             return { reason: 'no-chat-session' };
+        // The mode is read ONCE, here: it decides both whether a deadline exists
+        // and what happens when it fires. An ask that started under one mode keeps
+        // it — the same rule the window follows (an ask already holding a timer
+        // keeps the one it started with).
+        const mode = this.permissionTimeoutMode;
+        // 不等待（0）只属自动推进：没有问人的必要。直接按那一档收场，composer 接管
+        // 根本不必出现——它只会闪一下就没了，问了也来不及答。超时中止没有这一档。
+        if (mode === 'auto' && this.permissionTimeoutMs === 0) {
+            return { response: this.settleExpiredAsk(session, mode, toolCall, options, 0) };
+        }
+        // One signal carries both withdrawals: the agent's own cancel (whatever
+        // aborted the ACP request) and the deadline. The host's waterfall races its
+        // answerers against this signal, so aborting is a clean withdrawal rather
+        // than a leak.
+        const withdraw = new AbortController();
+        const askSignal = signal === undefined ? withdraw.signal : AbortSignal.any([signal, withdraw.signal]);
+        let timer;
+        let timedOut = false;
+        // `wait` never expires, so it never arms a timer at all. A window of `0`
+        // never reaches here: 不等待 was already settled above.
+        const windowMs = this.permissionTimeoutMs;
+        const deadline = mode !== 'wait' && windowMs > 0
+            ? new Promise(resolve => {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    withdraw.abort();
+                    resolve({ timedOut: true });
+                }, windowMs);
+                timer.unref?.();
+            })
+            : undefined;
         let outcome;
         try {
-            outcome = await requester({
+            const row = (typeof toolCall === 'object' && toolCall !== null ? toolCall : {});
+            const asked = requester({
                 dshSessionId: session.dshSessionId,
                 agentId: this.def.id,
                 toolName: permissionToolName(toolCall),
-                ...(signal === undefined ? {} : { signal }),
+                reason: permissionAskReason(toolCall),
+                // The ACP call id is the id the adapter streamed on the host tool card
+                // (`TurnStreamController` fills `tool-call` blocks from
+                // `snapshot.callId`), so the host's approval detail slot can attach
+                // the operation's own card to this ask.
+                ...(typeof row.toolCallId === 'string' && row.toolCallId !== '' ? { callId: row.toolCallId } : {}),
+                signal: askSignal,
             });
+            // A withdrawn ask settles on the host's own schedule; dropping it here
+            // must not surface as an unhandled rejection later.
+            asked.catch(() => { });
+            const settled = deadline === undefined
+                ? await asked.then(o => ({ outcome: o }))
+                : await Promise.race([asked.then(o => ({ outcome: o })), deadline]);
+            // The flag, not the race winner, decides: the host may settle `cancelled`
+            // from the very abort the deadline caused, and that is still a timeout.
+            if (timedOut || 'timedOut' in settled) {
+                return { response: this.settleExpiredAsk(session, mode, toolCall, options, windowMs) };
+            }
+            outcome = settled.outcome;
         }
         catch {
             // Synchronous throw or rejection, either way: the ask falls back to the
             // ledger. An approval failure must never break the agent's turn.
             outcome = 'unavailable';
         }
+        finally {
+            clearTimeout(timer);
+        }
         if (outcome === 'unavailable')
             return { reason: 'unavailable' };
         const response = nativeOutcomeResponse(outcome, options);
@@ -1068,6 +1254,57 @@ export class AgentBridge {
         });
         return { response };
     }
+    /**
+     * Settle an ask whose deadline fired, WHERE IT WAS ASKED.
+     *
+     * `abort` refuses it — the operation does not happen and the agent carries
+     * on with that answer. `auto` answers it with the option the agent's own
+     * kinds imply ({@link pickAutoOption}) so the agent CONTINUES; it says which
+     * option it picked, because an unattended approval nobody looked at has to
+     * be visible afterwards. A mode that cannot pick an option (no options, or
+     * none with a usable id) degrades to `abort`: refusing is safer than
+     * guessing, and hanging is worse than either.
+     *
+     * The `permission/resolved` frame keeps the event stream symmetric with the
+     * ledger path, so the browser drops any card it may hold for this session.
+     */
+    settleExpiredAsk(session, mode, toolCall, options, timeoutMs) {
+        const picked = mode === 'auto'
+            ? pickAutoOption(options.map(option => ({ optionId: option.optionId, name: option.name, kind: option.kind })))
+            : undefined;
+        const response = picked === undefined
+            ? { outcome: { outcome: 'cancelled' } }
+            : { outcome: { outcome: 'selected', optionId: picked.optionId } };
+        const tool = permissionToolName(toolCall);
+        // 不等待（0）不是「等了 0 秒」，是没等：两种说法的区别就在这里。
+        const waited = timeoutMs > 0
+            ? `timed out after ${String(Math.round(timeoutMs / 1000))}s`
+            : 'was not waited for';
+        this.hub.broadcast({
+            type: 'agent/notice',
+            agentId: this.def.id,
+            level: 'info',
+            // Name what was missed and what was done about it — the way a human
+            // needs it: which operation sat unanswered, and what the plugin answered
+            // instead. OmniTerm's reaper writes the same "you missed this" notice.
+            text: picked === undefined
+                ? `acp: permission request for "${tool}" ${waited}; refused`
+                : `acp: permission request for "${tool}" ${waited}; answered "${picked.name}"`,
+        });
+        // The conversation's only trace of the expiry: the composer card is going
+        // away and nothing else says why.
+        this.hub.broadcast({
+            type: 'permission/expired',
+            sessionId: session.sessionId,
+            toolCall,
+            timeoutMs,
+            outcome: response.outcome.outcome === 'selected'
+                ? { outcome: 'selected', optionId: response.outcome.optionId }
+                : { outcome: 'cancelled' },
+            ...(picked === undefined ? {} : { optionName: picked.name }),
+        });
+        return response;
+    }
     settlePermissions(session) {
         this.permissions.settleFor(p => p.sessionId === session.sessionId);
     }
@@ -1179,9 +1416,84 @@ export class AgentBridge {
     }
 }
 /** Human-facing identity of an ACP tool call (the approval headline). */
-function permissionToolName(toolCall) {
+/**
+ * Human-facing name of the tool an ask is about, for the chat line and the
+ * timeout notice.
+ *
+ * The ACP `toolCall.title` is the declared field, but it is OPTIONAL and real
+ * agents omit it: codebuddy puts the name in `_meta["codebuddy.ai/toolName"]`
+ * (observed live — without the fallback the notice reads `for "tool call"`,
+ * which tells the human nothing about what they missed). So read `title` first,
+ * then any `_meta` key whose last segment is `toolName`, then the standard
+ * `kind`, and only then give up with the generic phrase. Nothing is invented:
+ * every step reads a key the agent itself declared.
+ */
+export function permissionToolName(toolCall) {
+    const row = (typeof toolCall === 'object' && toolCall !== null ? toolCall : {});
+    if (typeof row.title === 'string' && row.title !== '')
+        return row.title;
+    const meta = (typeof row._meta === 'object' && row._meta !== null ? row._meta : {});
+    for (const [key, value] of Object.entries(meta)) {
+        const segment = key.split('/').at(-1) ?? key;
+        if (segment.toLowerCase() === 'toolname' && typeof value === 'string' && value !== '')
+            return value;
+    }
+    if (typeof row.kind === 'string' && row.kind !== '')
+        return row.kind;
+    return 'tool call';
+}
+/** Longest reason line the approval card headline carries. */
+const APPROVAL_REASON_MAX = 240;
+/** Input keys that name the operation in one string, most specific first. */
+const APPROVAL_REASON_INPUT_KEYS = [
+    'command',
+    'cmd',
+    'path',
+    'file_path',
+    'filePath',
+    'pattern',
+    'query',
+    'url',
+    'description',
+];
+/**
+ * One line saying WHAT the native approval card is about.
+ *
+ * WHY: the host renders `reason ?? "工具 <name> 请求越权执行"`. Without a
+ * reason the human only sees the tool's NAME ("Bash") and cannot judge the
+ * request; the ACP tool call already declares the missing half — its title and
+ * (for execute/edit tools) a short scalar in `rawInput`. Only ONE declared
+ * string is used, never a serialized object or a whole file, and the line is
+ * capped so a pathological input cannot fill the card or the audit log.
+ */
+export function permissionAskReason(toolCall) {
     const row = (typeof toolCall === 'object' && toolCall !== null ? toolCall : {});
-    return typeof row.title === 'string' && row.title !== '' ? row.title : 'tool call';
+    const title = permissionToolName(toolCall);
+    const raw = row.rawInput;
+    const input = raw !== null && typeof raw === 'object' && !Array.isArray(raw)
+        ? raw
+        : typeof raw === 'string' && raw.length <= APPROVAL_REASON_MAX * 4
+            // Some agents send the arguments as a JSON string; read one scalar out
+            // of it instead of echoing the blob.
+            ? (() => {
+                try {
+                    const parsed = JSON.parse(raw);
+                    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+                        ? parsed
+                        : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            })()
+            : undefined;
+    const detail = input === undefined
+        ? undefined
+        : APPROVAL_REASON_INPUT_KEYS
+            .map(key => input[key])
+            .find((value) => typeof value === 'string' && value !== '');
+    const line = detail === undefined || detail === title ? title : `${title} · ${detail}`;
+    return line.length > APPROVAL_REASON_MAX ? `${line.slice(0, APPROVAL_REASON_MAX - 1)}…` : line;
 }
 /**
  * Translate a native approval outcome into the ACP option the agent must see.
@@ -2141,24 +2453,36 @@ class TurnStreamController {
         }
         else if (row.type === 'permission/request') {
             const typed = event;
-            const seg = this.segment;
-            const line = this.permissionLine(typed);
-            if (seg === undefined || seg.finished) {
-                if (line !== '')
-                    this.pendingProse.push(line);
-                return;
-            }
-            if (seg.hasCard) {
-                // The card must stay the segment's last block: park the line for the
-                // next segment instead of streaming it below the card.
-                this.pendingProse.push(line);
-                this.finishSegment(seg, { kind: 'stop' });
-                return;
-            }
-            if (line !== '')
-                this.emitProse(seg, 'reasoning', line);
+            this.pushProse(this.permissionLine(typed));
+        }
+        else if (row.type === 'permission/expired') {
+            const typed = event;
+            this.pushProse(this.expiredLine(typed));
         }
     }
+    /**
+     * Put one narrative line into the turn's prose stream.
+     *
+     * A card-bearing segment must stay the segment's LAST block, so a line that
+     * arrives while a card is open is parked for the next segment instead of
+     * streaming below the card. A line that arrives between segments waits for
+     * the next one to open.
+     */
+    pushProse(line) {
+        if (line === '')
+            return;
+        const seg = this.segment;
+        if (seg === undefined || seg.finished) {
+            this.pendingProse.push(line);
+            return;
+        }
+        if (seg.hasCard) {
+            this.pendingProse.push(line);
+            this.finishSegment(seg, { kind: 'stop' });
+            return;
+        }
+        this.emitProse(seg, 'reasoning', line);
+    }
     /** Events that arrive between segments: recorded, replayed into the next one. */
     recordWithoutSegment(update) {
         const kind = String(update.sessionUpdate ?? '');
@@ -2298,14 +2622,44 @@ class TurnStreamController {
             : 'permission';
         // The line must not point at a place with no answer entry, and the bridge
         // knows which path this ask took (`ledgerFallbackOf`, recorded before the
-        // frame was broadcast). On the DESIGNED ledger paths the settings panel's
-        // card is the answer entry. A DEGRADED native route carries a deadline.
+        // frame was broadcast). On the ledger paths the settings panel's card is
+        // the answer entry. A DEGRADED native route has to say why the
+        // conversation is not showing the question — as an OBSERVED FACT, not a
+        // guessed cause.
+        //
+        // The last clause says what happens if nobody answers, and it follows the
+        // MODE: refused, answered automatically, or (in `wait`) nothing at all.
         const fallback = this.bridge.ledgerFallbackOf(event.requestId);
-        return fallback?.reason === 'unavailable'
-            ? fallback.timeoutMs > 0
-                ? `\n> 🔐 [Permission Required: ${title}] - the approval service is unavailable; approve in Settings within ${String(Math.round(fallback.timeoutMs / 1000))}s or this request is cancelled\n`
-                : `\n> 🔐 [Permission Required: ${title}] - the approval service is unavailable; please approve in Settings\n`
-            : `\n> 🔐 [Permission Required: ${title}] - please approve in Settings\n`;
+        const why = fallback?.reason === 'unavailable' ? 'the approval service is unavailable' : undefined;
+        const lead = why === undefined ? 'please approve in Settings' : `${why}; approve in Settings`;
+        if (fallback === undefined || fallback.timeoutMs <= 0 || fallback.mode === 'wait') {
+            return `\n> 🔐 [Permission Required: ${title}] - ${lead}\n`;
+        }
+        const otherwise = fallback.mode === 'auto'
+            ? 'this request is answered automatically'
+            : 'this request is cancelled';
+        return `\n> 🔐 [Permission Required: ${title}] - ${lead} within ${String(Math.round(fallback.timeoutMs / 1000))}s or ${otherwise}\n`;
+    }
+    /**
+     * The line for an ask the plugin settled itself when its deadline fired.
+     *
+     * The composer card is disappearing, so the conversation has to say what
+     * happened to the question — otherwise the user is left with a vanished
+     * card and no explanation. The wording follows the outcome: refused, or
+     * answered with the option the agent's own kinds implied.
+     */
+    expiredLine(event) {
+        const title = typeof event.toolCall?.title === 'string'
+            ? String(event.toolCall.title)
+            : 'permission';
+        const waited = event.timeoutMs > 0
+            ? `no answer within ${String(Math.round(event.timeoutMs / 1000))}s`
+            : 'not waited for';
+        if (event.outcome.outcome === 'selected') {
+            const picked = event.optionName === undefined ? event.outcome.optionId : event.optionName;
+            return `\n> 🔐 [Permission Required: ${title}] - ${waited}; answered "${picked}" automatically, continuing\n`;
+        }
+        return `\n> 🔐 [Permission Required: ${title}] - ${waited}; refused\n`;
     }
 }
 /** Chunk text shared by the controller's fold (string / object / array forms). */
@@ -2343,13 +2697,59 @@ export class BridgeManager {
     configStoragePath;
     catalogStoragePath;
     probeModelsOnBoot;
-    tuning;
     bridges = new Map();
     defsMap = new Map();
     /** The plugin's own default ACP agent id (persisted; see `persistAgents`). */
     defaultAgentId;
     /** The agent tag's halo preference (persisted; see `persistAgents`). */
     tagHaloSetting = { ...DEFAULT_TAG_HALO };
+    /**
+     * What `cordis.patch.yml` asked for — ONLY if it actually named the key.
+     * This is the deployment baseline, kept apart from
+     * {@link deadlineOverride} so the settings card can tell the user which of
+     * the two is winning. Empty when the file says nothing about the window, in
+     * which case {@link baselineDeadline} (the built-in default) applies.
+     */
+    configuredDeadlines = {};
+    /**
+     * The mode the config file named, if it named one. Kept apart from the
+     * override for the same reason the window is: the card has to be able
+     * to say "the file asks for `abort`, the value set here wins".
+     */
+    configuredMode;
+    /**
+     * The window before any override — the tuning this manager was constructed
+     * with, which already carries the validated config file (the host entry
+     * passes `validateConfig`'s output) or the built-in default.
+     *
+     * Held separately from {@link configuredDeadlines} because the two answer
+     * different questions: this one is what RUNS when nothing is overridden, that
+     * one is what the config file NAMED (which the card shows as the reset target
+     * and a bare default does not deserve). A manager built without tuning at all
+     * — a direct consumer, a test — gets `DEFAULT_TUNING` here and stays correct.
+     */
+    baselineDeadline;
+    /**
+     * The mode before any override — the tuning this manager was constructed
+     * with, which already carries the validated config file (the host entry
+     * passes `validateConfig`'s output) or the built-in default.
+     */
+    baselineMode;
+    /**
+     * The settings page's own write, persisted with the agent registry. Merged
+     * OVER {@link baselineDeadline}: once a user picks a window in the UI, that
+     * pick is what runs, and the config file becomes the value the reset button
+     * returns to. Without this split a hand-edited `cordis.patch.yml` and a UI
+     * write would fight with no way to tell which one is live.
+     */
+    deadlineOverride = {};
+    /**
+     * Tuning in force, defaults applied. The approval deadline is rewritten
+     * IN PLACE by {@link applyDeadlineTuning}, which is why this is a live object
+     * rather than the constructor's parameter: every bridge built afterwards
+     * inherits the rewrite instead of the boot-time value.
+     */
+    tuning;
     /**
      * The in-flight (or just-settled) segmented turn of one DSH chat session.
      * Keyed by chat session id because the continuation steps of a segmented
@@ -2396,7 +2796,16 @@ export class BridgeManager {
         this.configStoragePath = configStoragePath;
         this.catalogStoragePath = catalogStoragePath;
         this.probeModelsOnBoot = probeModelsOnBoot;
-        this.tuning = tuning;
+        // Held as a live object rather than the raw parameter: the two approval
+        // deadlines are rewritten in place when the settings page writes them (see
+        // `applyDeadlineTuning`), and every bridge built afterwards must inherit
+        // the rewrite instead of the boot-time value.
+        this.tuning = { ...DEFAULT_TUNING, ...tuning };
+        // The pre-override deadline value, snapshotted before anything can rewrite
+        // it. Everything else in `tuning` is fixed for the manager's lifetime, so
+        // only this needs a snapshot.
+        this.baselineDeadline = this.tuning.permissionTimeoutMs;
+        this.baselineMode = this.tuning.permissionTimeoutMode;
         for (const def of defs) {
             this.defsMap.set(def.id, def);
         }
@@ -2409,6 +2818,9 @@ export class BridgeManager {
         }
         this.loadPersistedAgents();
         this.loadPersistedCatalogs();
+        // A persisted deadline override must reach the tuning the bridges are built
+        // from, not just the settings card's readout.
+        this.applyDeadlineTuning();
         // The request-path rewrite falls back to this default for a conversation
         // the user never bound explicitly — the same agent the composer chip shows.
         routeBindingRegistry().defaultModel = this.defaultAgent();
@@ -2429,6 +2841,19 @@ export class BridgeManager {
     approvalRouting() {
         return this.approvalRequester !== undefined;
     }
+    /**
+     * Every outstanding ledger ask, across all agents, with the view the browser
+     * was shown it — the source of the reconnect replay (see
+     * `permissionReplayFrames`). Asks on the native route are deliberately
+     * absent: they broadcast nothing and their answer entry is the composer
+     * takeover the client already holds.
+     */
+    pendingPermissionViews() {
+        const views = [];
+        for (const bridge of this.bridges.values())
+            views.push(...bridge.permissions.pendingViews());
+        return views;
+    }
     /**
      * Let the host resolve a chat session's workspace root — the sidebar's
      * selected workspace, which the agent's session and its process both run in.
@@ -3213,6 +3638,41 @@ export class BridgeManager {
                 catch {
                     this.tagHaloSetting = { ...DEFAULT_TAG_HALO };
                 }
+                // The settings page's approval-deadline override. Re-validated on every
+                // boot because the state file is user- and version-editable: an
+                // unreadable value must not poison the deadline, and a value the
+                // validator accepts must be the value that runs (a UI write that did
+                // not survive a restart would read as a broken setting).
+                try {
+                    const raw = parsed.approvalDeadlines ?? {};
+                    // The OLD card wrote the two legacy windows, and its 「关」 preset
+                    // wrote a zero — which then meant "this window never fires". The only
+                    // way to say that now is the `wait` MODE (a zero means 不等待 today),
+                    // so a legacy zero carries over as the mode instead of silently
+                    // turning "wait forever" into "answer immediately".
+                    const legacy = raw;
+                    const legacyWindow = legacy.nativeApprovalTimeoutMs ?? legacy.permissionFallbackTimeoutMs;
+                    const legacyNever = legacyWindow === 0;
+                    const window = legacyNever
+                        ? undefined
+                        : validateApprovalDeadlines(raw).permissionTimeoutMs;
+                    const mode = legacyNever
+                        ? 'wait'
+                        : (raw.mode === undefined
+                            ? undefined
+                            : validatePermissionTimeoutMode(raw.mode, 'bad_payload'));
+                    // A stored window must be legal for the mode it runs under: 不等待
+                    // (0) belongs to `auto`; under `abort` it would refuse every ask on
+                    // arrival, so it floors to the shortest real wait.
+                    const effectiveMode = mode ?? this.baselineMode;
+                    this.deadlineOverride = {
+                        ...(window === undefined ? {} : { permissionTimeoutMs: normalizeApprovalWindow(effectiveMode, window) }),
+                        ...(mode === undefined ? {} : { mode }),
+                    };
+                }
+                catch {
+                    this.deadlineOverride = {};
+                }
                 this.loadPersistedChoices(parsed.conversations);
             }
         }
@@ -3267,6 +3727,11 @@ export class BridgeManager {
                 ...(this.defaultAgentId === undefined ? {} : { defaultAgentId: this.defaultAgentId }),
                 tagHalo: this.tagHaloSetting,
                 agents: [...this.defsMap.values()],
+                // The settings page's approval deadlines. Absent while none was ever
+                // written, so a fresh deployment's state file stays exactly as it was.
+                ...(Object.keys(this.deadlineOverride).length === 0
+                    ? {}
+                    : { approvalDeadlines: { ...this.deadlineOverride } }),
                 // The per-conversation picks: agent + model + thought level + mode +
                 // extra config values chosen in the composer, including for
                 // conversations with no live session yet.
@@ -4260,6 +4725,99 @@ export class BridgeManager {
         this.tagHaloSetting = validateTagHalo(halo);
         this.persistAgents();
     }
+    /**
+     * Declare the deployment baseline for the approval deadline — the values
+     * `cordis.patch.yml` names, passed RAW (only the keys it actually contains).
+     *
+     * Kept separate from the validated tuning because "the file says 600000" and
+     * "the file says nothing, so 300000 applies" are different facts: the settings
+     * card shows the first as the reset target and the second as a built-in
+     * default. Called once by the host entry, before any bridge exists — and it
+     * also moves the baseline, so a manager built without tuning (a direct
+     * consumer, a test) still runs what the deployment asked for.
+     */
+    setConfiguredApprovalDeadlines(values, mode) {
+        // The baseline must be legal for the mode it runs under, or the card would
+        // advertise a number the deployment cannot actually run (不等待 under
+        // `abort`) and the reset button would restore it.
+        const effectiveMode = mode ?? this.configuredMode ?? this.baselineMode;
+        const raw = values.permissionTimeoutMs;
+        const window = raw === undefined ? undefined : normalizeApprovalWindow(effectiveMode, raw);
+        this.configuredDeadlines = window === undefined ? {} : { permissionTimeoutMs: window };
+        if (window !== undefined)
+            this.baselineDeadline = window;
+        if (mode !== undefined) {
+            this.configuredMode = mode;
+            this.baselineMode = mode;
+        }
+        this.applyDeadlineTuning();
+    }
+    /**
+     * The approval deadline in force, plus the facts that explain a value the
+     * user did not pick: the config-file baseline an override is outranking. The
+     * mode rides along with its own baseline, for the same reason: the card has
+     * to be able to say "the file asks for `abort`, the value set here wins".
+     *
+     * Everything is reported only when it is actually in play, so the card can
+     * stay silent about a plain default.
+     */
+    approvalDeadlines() {
+        const deadlines = {
+            permissionTimeoutMs: this.tuning.permissionTimeoutMs,
+            mode: this.tuning.permissionTimeoutMode,
+        };
+        if (Object.keys(this.configuredDeadlines).length > 0)
+            deadlines.configured = { ...this.configuredDeadlines };
+        if (this.configuredMode !== undefined)
+            deadlines.configuredMode = this.configuredMode;
+        return deadlines;
+    }
+    /**
+     * Write the approval deadline, or the mode (omitted keys keep their value),
+     * or drop the persisted override with `reset` so the config-file baseline —
+     * or the built-in default — applies again.
+     *
+     * HOT: the rewrite reaches every live bridge, so a user changing the window
+     * never has to kill a running session to see it take effect (the one thing an
+     * `agent/save`-style restart would cost them). Only asks armed AFTER the
+     * write see the new window; an ask already holding a timer keeps the one it
+     * started with.
+     */
+    async setApprovalDeadlines(patch, reset = false) {
+        // Merged BEFORE validating, so the whole resulting override passes the same
+        // gate the config file does (an override written by an older build is
+        // re-gated here rather than trusted). The validators also drop unknown
+        // keys, which is what keeps a stale payload from poisoning state.
+        const merged = reset ? {} : { ...this.deadlineOverride, ...patch };
+        const window = validateApprovalDeadlines(merged).permissionTimeoutMs;
+        const mode = merged.mode === undefined
+            ? undefined
+            : validatePermissionTimeoutMode(merged.mode, 'bad_payload');
+        // The stored override must be legal for the mode it runs under, not just
+        // legal on its own: 不等待 (0) belongs to `auto`, and a mode switch can
+        // leave it behind. Flooring it HERE (not only in the running value) keeps
+        // the card's number and the running number the same number.
+        const effectiveMode = mode ?? this.baselineMode;
+        this.deadlineOverride = {
+            ...(window === undefined ? {} : { permissionTimeoutMs: normalizeApprovalWindow(effectiveMode, window) }),
+            ...(mode === undefined ? {} : { mode }),
+        };
+        this.applyDeadlineTuning();
+        this.persistAgents();
+    }
+    /**
+     * Recompute the deadline and the mode from override → deployment baseline,
+     * and push the result to every live bridge.
+     */
+    applyDeadlineTuning() {
+        const permissionTimeoutMode = this.deadlineOverride.mode ?? this.baselineMode;
+        const permissionTimeoutMs = normalizeApprovalWindow(permissionTimeoutMode, this.deadlineOverride.permissionTimeoutMs ?? this.baselineDeadline);
+        this.tuning.permissionTimeoutMs = permissionTimeoutMs;
+        this.tuning.permissionTimeoutMode = permissionTimeoutMode;
+        const patch = { permissionTimeoutMs, mode: permissionTimeoutMode };
+        for (const bridge of this.bridges.values())
+            bridge.applyApprovalDeadlines(patch);
+    }
     dshSessionMap = new Map();
     /**
      * What each DSH chat session has chosen for its ACP agent — the agent itself