@keyou007/agent-bot 0.1.24-alpha.5 → 0.1.24-alpha.6

package/src/proxy/SessionOperationQueue.ts

@@ -0,0 +1,13 @@
+// Serialize settings changes and turn starts across every route bound to a task.
+export class SessionOperationQueue {
+  private readonly tails = new Map<string, Promise<unknown>>();
+
+  run<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
+    const previous = this.tails.get(sessionId) ?? Promise.resolve();
+    const next = previous.catch(() => undefined).then(operation);
+    this.tails.set(sessionId, next);
+    return next.finally(() => {
+      if (this.tails.get(sessionId) === next) this.tails.delete(sessionId);
+    });
+  }
+}

package/src/runtime/AcpRuntimeAdapter.ts

@@ -29,7 +29,7 @@ export class AcpRuntimeAdapter implements AgentRuntime {
   private readonly listeners = new Set<(event: RuntimeEvent) => void>();
   private readonly approvals = new Map<
     string,
-    { sessionId: string; resolve: (value: JsonValue) => void; optionIds: Map<ApprovalDecision, string> }
+    { sessionId: string; turnId: string; resolve: (value: JsonValue) => void; optionIds: Map<ApprovalDecision, string> }
   >();
 
   constructor(private readonly acp: AcpSessionManager) {}
@@ -59,11 +59,12 @@ export class AcpRuntimeAdapter implements AgentRuntime {
               optionIds.set("decline", option.optionId);
             }
           }
-          this.approvals.set(requestId, { sessionId: input.localSessionId, resolve, optionIds });
+          const turnId = active?.turnId ?? "unknown";
+          this.approvals.set(requestId, { sessionId: input.localSessionId, turnId, resolve, optionIds });
           this.emit({
             type: "approval_requested",
             sessionId: input.localSessionId,
-            turnId: active?.turnId ?? "unknown",
+            turnId,
             request: {
               id: requestId,
               title: typeof params.toolCall.title === "string" ? params.toolCall.title : "ACP permission request",
@@ -185,6 +186,7 @@ export class AcpRuntimeAdapter implements AgentRuntime {
     this.approvals.delete(requestId);
     const optionId = pending.optionIds.get(decision) ?? pending.optionIds.get(decision === "cancel" ? "decline" : "accept");
     pending.resolve({ outcome: { outcome: "selected", optionId: optionId ?? decision } });
+    this.emit({ type: "approval_resolved", sessionId, turnId: pending.turnId, requestId, decision });
   }
 
   async listModels(): Promise<ModelOption[]> {

package/src/runtime/types.ts

@@ -34,6 +34,7 @@ export interface RuntimeGoalUpdate {
 export type RuntimePrompt = string | {
   text: string;
   localImagePaths?: string[];
+  collaborationMode?: "default";
 };
 
 export interface PlanStep {
@@ -60,6 +61,7 @@ export interface ToolState {
 export interface ApprovalRequest {
   id: string;
   kind?: "mode_change";
+  automatic?: boolean;
   title: string;
   command?: string;
   reason?: string;
@@ -108,8 +110,8 @@ export type AgentEvent =
   | { type: "tool_updated"; sessionId: string; turnId: string; tool: ToolState }
   | { type: "tool_output_delta"; sessionId: string; turnId: string; toolId: string; delta: string }
   | { type: "approval_requested"; sessionId: string; turnId: string; request: ApprovalRequest }
-  | { type: "approval_resolved"; sessionId: string; turnId: string; requestId: string; decision: ApprovalDecision }
-  | { type: "turn_completed"; sessionId: string; turnId: string; finalResponse: string; durationMs?: number }
+  | { type: "approval_resolved"; sessionId: string; turnId: string; requestId: string; decision: ApprovalDecision; automatic?: boolean }
+  | { type: "turn_completed"; sessionId: string; turnId: string; finalResponse: string; durationMs?: number; approvedPlan?: boolean }
   | { type: "turn_cancelled"; sessionId: string; turnId: string }
   | { type: "turn_failed"; sessionId: string; turnId: string; message: string };
 
@@ -284,6 +286,9 @@ export interface AgentRuntime {
   getThreadWriterLockPath?(remoteSessionId: string): string | undefined;
   createSession(input: CreateRuntimeSessionInput): Promise<RuntimeSession>;
   resumeSession(input: ResumeRuntimeSessionInput): Promise<RuntimeSession>;
+  // Hydrate the saved same-thread snapshot without contacting the old Provider.
+  // The runtime must verify a resume before any subsequent turn or remote operation.
+  prepareSessionForSettings?(input: ResumeRuntimeSessionInput): Promise<RuntimeSession>;
   forkSession?(input: ForkRuntimeSessionInput): Promise<RuntimeSession>;
   getSession(localSessionId: string): RuntimeSession | undefined;
   // Drop local monitoring only; do not interrupt, unsubscribe, or archive remote work.
@@ -302,7 +307,7 @@ export interface AgentRuntime {
   steerTurn(sessionId: string, turnId: string, prompt: RuntimePrompt): Promise<void>;
   cancelTurn(sessionId: string, turnId: string): Promise<void>;
   interruptRemoteTurn?(remoteSessionId: string, turnId: string): Promise<void>;
-  archiveRemoteSession?(remoteSessionId: string): Promise<void>;
+  archiveRemoteSession?(remoteSessionId: string, options?: { allowUnmaterialized?: boolean }): Promise<void>;
   closeSession(sessionId: string): Promise<void>;
   setTitle?(sessionId: string, title: string): Promise<void>;
   getGoal?(sessionId: string): Promise<RuntimeGoal | undefined>;

package/src/state/StateStore.ts

@@ -6,7 +6,17 @@ import path from "node:path";
 import Database from "better-sqlite3";
 import { migrations } from "./migrations.js";
 import type { UpdateCheckSchedule, UpdateNotice } from "../updates/types.js";
-import type { ConversationTurn } from "../runtime/types.js";
+import type { ConversationTurn, RuntimeExecutionSettings } from "../runtime/types.js";
+
+export interface PendingProviderSettings {
+  localSessionId: string;
+  contextKey: string;
+  settings: RuntimeExecutionSettings;
+  messageId?: string;
+  replyMessageId?: string;
+  activeTab?: "provider" | "model" | "thinking" | "permission" | "agent";
+  error?: string;
+}
 
 export type SessionStatus = "starting" | "ready" | "running" | "closed" | "failed";
 
@@ -300,6 +310,27 @@ export class StateStore {
     return row ? JSON.parse(row.value_json) as UpdateCheckSchedule : undefined;
   }
 
+  getPendingProviderSettings(localSessionId: string): PendingProviderSettings | undefined {
+    const row = this.db.prepare("SELECT value_json FROM pending_provider_settings WHERE local_session_id = ?")
+      .get(localSessionId) as { value_json: string } | undefined;
+    return row ? JSON.parse(row.value_json) as PendingProviderSettings : undefined;
+  }
+
+  savePendingProviderSettings(pending: PendingProviderSettings): void {
+    this.db.prepare(`INSERT INTO pending_provider_settings (local_session_id, value_json) VALUES (?, ?)
+      ON CONFLICT(local_session_id) DO UPDATE SET value_json = excluded.value_json`)
+      .run(pending.localSessionId, JSON.stringify(pending));
+  }
+
+  deletePendingProviderSettings(localSessionId: string): void {
+    this.db.prepare("DELETE FROM pending_provider_settings WHERE local_session_id = ?").run(localSessionId);
+  }
+
+  listPendingProviderSettings(): PendingProviderSettings[] {
+    const rows = this.db.prepare("SELECT value_json FROM pending_provider_settings").all() as Array<{ value_json: string }>;
+    return rows.map((row) => JSON.parse(row.value_json) as PendingProviderSettings);
+  }
+
   saveUpdateCheckSchedule(schedule: UpdateCheckSchedule): void {
     this.db.prepare(`INSERT INTO update_check_schedule (id, value_json) VALUES (1, ?)
       ON CONFLICT(id) DO UPDATE SET value_json = excluded.value_json`).run(JSON.stringify(schedule));
@@ -684,6 +715,11 @@ export class StateStore {
     return row ? mapTurnAttempt(row) : undefined;
   }
 
+  hasTurnAttemptsForSession(localSessionId: string): boolean {
+    return Boolean(this.db.prepare("SELECT 1 FROM turn_attempts WHERE local_session_id = ? LIMIT 1")
+      .get(localSessionId));
+  }
+
   findIncompleteTurnAttemptForSession(localSessionId: string): TurnAttemptRecord | undefined {
     const row = this.db.prepare(`
       SELECT * FROM turn_attempts
@@ -982,6 +1018,7 @@ export class StateStore {
   archiveSession(localSessionId: string): void {
     const now = new Date().toISOString();
     const archive = this.db.transaction(() => {
+      this.deletePendingProviderSettings(localSessionId);
       this.db.prepare(`
         UPDATE sessions
         SET status = 'closed', updated_at = ?

package/src/state/TurnPreviewJournal.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { createHash, type Hash } from "node:crypto";
 import type { AgentEvent, ToolState } from "../runtime/types.js";
-import { reduceTurnEvent } from "../presentation/TurnStateReducer.js";
+import { approvalActivityId, continueTurnView, reduceTurnEvent } from "../presentation/TurnStateReducer.js";
 import type { TurnViewState } from "../presentation/turnViewTypes.js";
 
 type TextChange = { key: string; field: string; append: boolean; text: string };
@@ -10,6 +10,7 @@ export type PreviewRecord =
   | { kind: "seed"; state: TurnViewState }
   | { kind: "state"; patch: Partial<TurnViewState> }
   | { kind: "user"; id: string; text: string; images?: string[] }
+  | { kind: "handoff"; turnId: string; startedAt: number }
   | { kind: "event"; event: AgentEvent; texts: TextChange[] };
 type Stream = { length: number; hash: Hash };
 type Writer = { seeded?: boolean; pending: string[]; bytes: number; dirtyDisk?: boolean; streams: Map<string, Stream>; timings: Map<string, number>; timer?: NodeJS.Timeout; error?: unknown };
@@ -29,9 +30,10 @@ export class TurnPreviewJournal {
   has(turnId: string): boolean { return this.writers.has(turnId) || fs.existsSync(this.file(turnId)); }
 
   seed(state: TurnViewState): void {
-    const writer = this.writer(state.turnId);
+    const turnId = state.previewTurnId ?? state.turnId;
+    const writer = this.writer(turnId);
     if (writer.seeded) return;
-    this.append(state.turnId, { kind: "seed", state: { ...state, previewJournal: true } });
+    this.append(turnId, { kind: "seed", state: { ...state, previewJournal: true } });
     writer.seeded = true;
     for (const change of seedTexts(state)) this.track(writer, change);
   }
@@ -42,15 +44,19 @@ export class TurnPreviewJournal {
     const { activities, reasoningItems, fullToolOutputs, fullToolErrors, toolStatuses,
       completedTools, failedTools, activeTool, assistantText, progressText, plan, fileSummary,
       activitiesTruncated, previewCursor, ...patch } = state;
-    this.append(state.turnId, { kind: "state", patch });
+    this.append(state.previewTurnId ?? state.turnId, { kind: "state", patch });
   }
 
   user(turnId: string, id: string, text: string, images?: string[]): void {
     this.append(turnId, { kind: "user", id, text, images });
   }
 
-  event(event: AgentEvent): void {
-    const writer = this.writer(event.turnId);
+  handoff(journalId: string, turnId: string, startedAt: number): void {
+    this.append(journalId, { kind: "handoff", turnId, startedAt });
+  }
+
+  event(event: AgentEvent, journalId = event.turnId): void {
+    const writer = this.writer(journalId);
     const texts: TextChange[] = [];
     const copy = { ...event } as AgentEvent;
     const capture = (key: string, field: string, text: string, append = false) => {
@@ -96,7 +102,7 @@ export class TurnPreviewJournal {
         });
       }
     }
-    this.append(event.turnId, { kind: "event", event: copy, texts });
+    this.append(journalId, { kind: "event", event: copy, texts });
   }
 
   flush(turnId?: string, durable = false): void {
@@ -320,6 +326,10 @@ export class TurnPreviewProjection {
       return;
     }
     if (!this.state) return;
+    if (record.kind === "handoff") {
+      this.state = continueTurnView(this.state, record.turnId, record.startedAt);
+      return;
+    }
     if (record.kind === "state") {
       this.state = { ...this.state, ...record.patch, historyDetail: "full", previewJournal: true };
       return;
@@ -376,6 +386,8 @@ export class TurnPreviewProjection {
     if (event.type === "context_compaction") {
       for (const a of this.state.activities) if (!old.activities.includes(a)) this.changed.add(a.id);
     }
+    if (event.type === "approval_resolved") this.changed.add(approvalActivityId(event.turnId, event.requestId));
+    if (old.approval && !this.state.approval) this.changed.add(approvalActivityId(event.turnId, old.approval.id));
     if (this.details !== true && this.state.reasoningItems) this.state.reasoningItems = this.state.reasoningItems.map((r) => ({ ...r,
       summary: r.summary.map((t) => this.wantsFull(`reasoning:${r.itemId}:`) ? t : t.slice(0, 6000)), content: r.content.map((t) => this.wantsFull(`reasoning:${r.itemId}:`) ? t : t.slice(0, 6000)) }));
     this.state.activitiesTruncated = false;

package/src/state/migrations.ts

@@ -217,4 +217,10 @@ export const migrations = [
     PRIMARY KEY (local_session_id, remote_session_id, context_key, message_id)
   );
   `,
+  `
+  CREATE TABLE IF NOT EXISTS pending_provider_settings (
+    local_session_id TEXT PRIMARY KEY,
+    value_json TEXT NOT NULL
+  );
+  `,
 ] as const;

package/src/supervision/SafeRestartNotifier.ts

@@ -132,6 +132,7 @@ export class SafeRestartNotifier {
         phase: status.phase,
         remainingMs: status.remainingMs,
         pendingFinalDeliveries: status.activity.pendingFinalDeliveries,
+        activeTerminals: status.activity.activeTerminals,
         waitingTasks,
       });
       const cardHash = JSON.stringify(card);

package/src/supervision/SafeRestartScheduler.ts

@@ -1,4 +1,5 @@
 export interface ServerActivityState {
+  activeTerminals?: number;
   runningSessions: number;
   pendingFinalDeliveries: number;
   latestInboundAt?: string;
@@ -49,6 +50,7 @@ export class SafeRestartScheduler {
   private idleInboundAt?: string;
   private scheduleId = 0;
   private restartImmediatelyIfIdle = false;
+  private restartingNow = false;
 
   constructor(private readonly options: SafeRestartSchedulerOptions) {}
 
@@ -56,6 +58,10 @@ export class SafeRestartScheduler {
     return Boolean(this.reason);
   }
 
+  get restarting(): boolean {
+    return this.restartingNow;
+  }
+
   get pendingReason(): string | undefined {
     return this.reason;
   }
@@ -131,14 +137,14 @@ export class SafeRestartScheduler {
     if (!reason) return;
     const scheduleId = this.scheduleId;
     const state = this.options.readActivity();
-    if (state.runningSessions > 0 || state.pendingFinalDeliveries > 0) {
+    if (hasActiveWork(state) || state.pendingFinalDeliveries > 0) {
       this.idleSince = undefined;
       this.idleInboundAt = undefined;
       await this.emitStatus({
         scheduleId,
         reason,
         notificationTargets: this.notificationTargetsSnapshot(),
-        phase: state.runningSessions > 0 ? "waiting_tasks" : "waiting_delivery",
+        phase: hasActiveWork(state) ? "waiting_tasks" : "waiting_delivery",
         activity: state,
       });
       return;
@@ -176,18 +182,18 @@ export class SafeRestartScheduler {
     }
     const confirmed = this.options.readActivity();
     if (
-      confirmed.runningSessions > 0
+      hasActiveWork(confirmed)
       || confirmed.pendingFinalDeliveries > 0
       || (confirmed.latestInboundAt ?? "") !== this.idleInboundAt
     ) {
       this.idleSince = undefined;
       this.idleInboundAt = undefined;
-      if (confirmed.runningSessions > 0 || confirmed.pendingFinalDeliveries > 0) {
+      if (hasActiveWork(confirmed) || confirmed.pendingFinalDeliveries > 0) {
         await this.emitStatus({
           scheduleId,
           reason,
           notificationTargets: this.notificationTargetsSnapshot(),
-          phase: confirmed.runningSessions > 0 ? "waiting_tasks" : "waiting_delivery",
+          phase: hasActiveWork(confirmed) ? "waiting_tasks" : "waiting_delivery",
           activity: confirmed,
         });
       } else {
@@ -206,6 +212,7 @@ export class SafeRestartScheduler {
   }
 
   private async restart(reason: string, scheduleId: number, activity: ServerActivityState): Promise<void> {
+    this.restartingNow = true;
     const notificationTargets = this.notificationTargetsSnapshot();
     this.clear();
     await this.emitStatus({
@@ -216,7 +223,8 @@ export class SafeRestartScheduler {
       activity,
       remainingMs: 0,
     });
-    await this.options.onReady(reason, notificationTargets);
+    try { await this.options.onReady(reason, notificationTargets); }
+    finally { this.restartingNow = false; }
   }
 
   private requestPoll(): void {
@@ -269,6 +277,10 @@ export class SafeRestartScheduler {
   }
 }
 
+function hasActiveWork(state: ServerActivityState): boolean {
+  return state.runningSessions > 0 || (state.activeTerminals ?? 0) > 0;
+}
+
 function normalizedNotificationTarget(
   value: RestartNotificationTarget | undefined,
   reason: string,

package/src/terminal/TerminalCards.ts

@@ -0,0 +1,18 @@
+import { CardRenderer } from "../feishu/CardRenderer.js";
+import { isThreadContextKey } from "../feishu/contextKey.js";
+import type { FeishuOutbound } from "../feishu/types.js";
+import type { TerminalCardView } from "./TerminalServer.js";
+
+export async function sendTerminalAuthorization(
+  outbound: Pick<FeishuOutbound, "sendInteractiveCard" | "replyInteractiveCard">,
+  view: TerminalCardView,
+): Promise<string | undefined> {
+  const card = new CardRenderer().renderTerminalAuthorization(view);
+  if (isThreadContextKey(view.contextKey)) {
+    if (!outbound.replyInteractiveCard || !view.commandCardMessageId) {
+      throw new Error("无法向原话题发送终端授权卡，请重新打开命令卡片。");
+    }
+    return outbound.replyInteractiveCard(view.contextKey, { messageId: view.commandCardMessageId, replyInThread: true }, card);
+  }
+  return outbound.sendInteractiveCard(view.contextKey, card);
+}

package/src/terminal/TerminalLinks.ts

@@ -0,0 +1,61 @@
+import { createHash, createHmac, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+
+const record = z.object({ token: z.string().regex(/^[A-Za-z0-9_-]{8}$/u), jobId: z.string().regex(/^[a-f0-9-]{36}$/u) });
+
+export class TerminalLinks {
+  constructor(private readonly directory: string, private readonly secret: Buffer) {
+    fs.mkdirSync(directory, { recursive: true });
+  }
+
+  create(jobId: string): string {
+    if (!/^[a-f0-9-]{36}$/u.test(jobId)) throw new Error("Invalid terminal job ID.");
+    for (let attempt = 0; attempt < 16; attempt++) {
+      const token = createHmac("sha256", this.secret).update(`terminal:open:${jobId}:${attempt}`).digest("base64url").slice(0, 8);
+      if (this.resolve(token) === jobId) return token;
+      try {
+        fs.writeFileSync(this.filePath(token), JSON.stringify({ token, jobId }), { flag: "wx", mode: 0o600 });
+        return token;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        if (this.resolve(token) === jobId) return token;
+      }
+    }
+    throw new Error("Unable to allocate a terminal short link.");
+  }
+
+  createRecovery(): string {
+    for (let attempt = 0; attempt < 16; attempt++) {
+      const token = randomBytes(6).toString("base64url");
+      try {
+        // Reserve the shared namespace permanently: an expired recovery must never open a new Shell.
+        fs.writeFileSync(this.filePath(token), JSON.stringify({ token, recovery: true }), { flag: "wx", mode: 0o600 });
+        return token;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      }
+    }
+    throw new Error("Unable to allocate a terminal recovery link.");
+  }
+
+  resolve(token: string): string | undefined {
+    if (!/^[A-Za-z0-9_-]{8}$/u.test(token)) return undefined;
+    let content: string;
+    try { content = fs.readFileSync(this.filePath(token), "utf8"); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw error;
+    }
+    let value: unknown;
+    try { value = JSON.parse(content) as unknown; } catch { return undefined; }
+    const parsed = record.safeParse(value);
+    return parsed.success && parsed.data.token === token ? parsed.data.jobId : undefined;
+  }
+
+  private filePath(token: string): string {
+    // Hash filenames so case-sensitive URL tokens also work on Windows filesystems.
+    return path.join(this.directory, `${createHash("sha256").update(token).digest("hex")}.json`);
+  }
+}

package/src/terminal/TerminalPage.ts

@@ -0,0 +1,213 @@
+export function terminalPage(base: string, recovery = false): string {
+  base = base.replaceAll("&", "&amp;").replaceAll(String.fromCharCode(34), "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+  return `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>AgentBot Terminal</title><link rel="stylesheet" href="${base}/assets/xterm.css"><link rel="stylesheet" href="${base}/assets/terminal.css">
+<script defer src="${base}/assets/xterm.js"></script><script defer src="${base}/assets/fit.js"></script><script defer src="${base}/assets/terminal.js"></script></head>
+<body data-base="${base}" data-recovery="${recovery}"><header><strong>AgentBot <span>Terminal</span></strong><div id="status" role="status">尚未连接</div><button id="connect">请求连接</button><button id="interrupt" disabled>Ctrl+C</button><button id="close" disabled>关闭终端</button></header>
+<section id="welcome"><h1>在浏览器中使用本机终端</h1><p>命令在 AgentBot 所在电脑上执行，拥有其系统用户权限。不会自动执行或接管原卡片中的命令。</p><p>点击请求连接，然后返回命令所在的飞书会话或话题，由 AgentBot 所有者核对验证码并授权。不要批准非本人发起的请求。</p><button id="welcome-connect" type="button">请求连接</button><p id="code"></p></section><div id="terminal"></div>
+<footer id="details">前台连接时不因空闲关闭；后台空闲 30 分钟或网页断开 3 分钟后自动关闭 Shell · 成功重连取消断开计时并重置空闲计时 · 可从原会话的终端管理卡打开或关闭终端</footer></body></html>`;
+}
+
+export const TERMINAL_CSS = `
+#welcome-connect{padding:10px 20px;font:inherit}
+:root{color-scheme:dark;font:14px system-ui,sans-serif;background:#10141b;color:#dbe4f1}*{box-sizing:border-box}body{margin:0;height:100dvh;display:flex;flex-direction:column}header{display:flex;gap:12px;align-items:center;padding:12px 18px;background:#191f2b;border-bottom:1px solid #303a4d;flex-wrap:wrap}header strong{font-size:17px}header strong span{font-weight:400;color:#9aacc7}#status{flex:1;color:#adbfdb;font-size:13px}button{background:#25334a;border:1px solid #415775;border-radius:7px;padding:8px 12px;color:#e5efff;cursor:pointer}button:hover{background:#304661}button:disabled{opacity:.45;cursor:default}#close{border-color:#86505a}#welcome{margin:40px auto;max-width:780px;padding:0 24px;line-height:1.8}h1{font-size:25px}#code{font-size:24px;letter-spacing:3px;color:#84c1ff}#terminal{flex:1;min-height:0;padding:12px 14px;display:none}.xterm{height:100%}footer{font-size:12px;color:#8f9eb7;padding:9px 18px;border-top:1px solid #293142}body.connected #welcome{display:none}body.connected #terminal{display:block}@media(max-width:650px){header{padding:10px;gap:8px}#status{min-width:100%}footer{padding:7px 10px}#terminal{padding:6px}}
+`;
+
+export const TERMINAL_SCRIPT = String.raw`(() => {
+  const base = document.body.dataset.base;
+  const status = document.getElementById('status');
+  const connect = document.getElementById('connect');
+  const welcomeConnect = document.getElementById('welcome-connect');
+  const close = document.getElementById('close');
+  const interrupt = document.getElementById('interrupt');
+  const storageKey = 'agentbot-terminal:' + location.pathname;
+  const recovery = document.body.dataset.recovery === 'true';
+  if (recovery) document.querySelector('#welcome h1').textContent = '恢复已有终端';
+  let session, ws, term, observer, retryTimer, socketTimer, checking, visibilityTimer;
+  let socketReady = false;
+  let epoch = 0, failures = 0, stopped = false, pageHidden = false, offline = false, busy = false;
+  try { session = JSON.parse(sessionStorage.getItem(storageKey) || 'null'); } catch {}
+  const awake = () => !pageHidden && !document.hidden && !offline;
+  const post = async (route, data, controller = new AbortController()) => {
+    const timer = setTimeout(() => controller.abort(), 10000);
+    try {
+      const response = await fetch(base + '/api/' + route, { method:'POST', credentials:'omit', cache:'no-store',
+        signal:controller.signal, headers:{'Content-Type':'application/json'}, body:JSON.stringify(data) });
+      let value;
+      try { value = await response.json(); } catch {
+        throw Object.assign(new Error('服务返回了非 JSON 响应'), {httpStatus:response.status});
+      }
+      if (!response.ok) throw Object.assign(new Error(value.error || '请求失败'), {httpStatus:response.status});
+      return value;
+    } finally { clearTimeout(timer); }
+  };
+  function message(error) {
+    if (error?.name === 'AbortError') return '请求超时';
+    if (!error?.httpStatus && (error?.name === 'TypeError' || error?.message === 'Failed to fetch')) return '网络暂时不可用';
+    return error?.message || String(error);
+  }
+  function buttons(retry = false) {
+    for (const button of [connect, welcomeConnect]) {
+      button.textContent = session ? '重新连接' : recovery ? '请求恢复连接' : '请求连接';
+      button.disabled = busy || (!!session && !retry);
+    }
+    close.disabled = busy || !session;
+  }
+  function invalidate() {
+    epoch++; clearTimeout(retryTimer); clearTimeout(socketTimer);
+    clearTimeout(visibilityTimer); socketReady = false;
+    checking?.abort(); checking = undefined;
+    const old = ws; ws = undefined; old?.close(); interrupt.disabled = true;
+    if (term) term.options.disableStdin = true;
+  }
+  function forget() {
+    session = undefined; sessionStorage.removeItem(storageKey);
+    document.getElementById('code').textContent = ''; buttons(true);
+  }
+  function end(text) { stopped = true; invalidate(); forget(); status.textContent = text; }
+  function fail(text) { stopped = true; invalidate(); status.textContent = text; buttons(true); }
+  function schedule(delay) {
+    clearTimeout(retryTimer);
+    if (!stopped && awake() && session) retryTimer = setTimeout(check, delay);
+  }
+  function retry(stage, error) {
+    if (stopped || !session) return;
+    const seconds = Math.min(10, Math.pow(2, Math.min(failures++, 4)));
+    status.textContent = stage + '：' + message(error) + '，' + seconds + ' 秒后自动重试';
+    buttons(true); schedule(seconds * 1000);
+  }
+  function sendSize(cols, rows) {
+    if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify({type:'resize',cols:Math.max(2,Math.min(500,cols)),rows:Math.max(2,Math.min(200,rows))}));
+  }
+  function reportVisibility() {
+    clearTimeout(visibilityTimer);
+    if (stopped || !socketReady || ws?.readyState !== WebSocket.OPEN) return;
+    const foreground = awake();
+    ws.send(JSON.stringify({type:'visibility',foreground}));
+    if (foreground) visibilityTimer = setTimeout(reportVisibility, 30000);
+  }
+  function openSocket() {
+    if (stopped || !awake() || ws || !session) return;
+    const current = session, generation = epoch;
+    const url = new URL(base + '/socket', location.origin); url.protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    let socket;
+    try { socket = new WebSocket(url); } catch (error) { retry('WebSocket 连接失败', error); return; }
+    ws = socket; status.textContent = '授权已通过，正在连接终端…'; buttons();
+    const valid = () => ws === socket && generation === epoch && session === current && !stopped;
+    socketTimer = setTimeout(() => {
+      if (!valid()) return;
+      invalidate(); retry('WebSocket 连接超时', new Error('请检查网络是否支持 WebSocket'));
+    }, 15000);
+    socket.onopen = () => { if (valid()) socket.send(JSON.stringify({type:'auth',requestId:current.requestId,browserKey:current.browserKey})); };
+    socket.onmessage = (event) => {
+      if (!valid()) return;
+      try {
+        const result = JSON.parse(event.data);
+        if (result.type === 'ready') {
+          clearTimeout(socketTimer);
+          socketReady = true; reportVisibility();
+          document.body.classList.add('connected');
+          observer?.disconnect(); term?.dispose();
+          const terminal = new Terminal({cursorBlink:true,fontSize:14,scrollback:5000,disableStdin:result.replay === true,theme:{background:'#10141b'}});
+          term = terminal;
+          const active = () => valid() && term === terminal;
+          terminal.attachCustomKeyEventHandler((event) => {
+            if (event.altKey || event.shiftKey || event.ctrlKey === event.metaKey) return true;
+            const key = event.key.toLowerCase();
+            // Let the browser dispatch native clipboard events, including on HTTP.
+            // xterm handles the selected text and bracketed paste without sending ^C/^V.
+            return !(key === 'v' || (key === 'c' && terminal.hasSelection()));
+          });
+          const fit = new FitAddon.FitAddon(); terminal.loadAddon(fit); terminal.open(document.getElementById('terminal'));
+          terminal.onData((data) => {
+            if (active() && !terminal.options.disableStdin && socket.readyState === WebSocket.OPEN) for (let i=0; i<data.length; i+=4096) socket.send(JSON.stringify({type:'input',data:data.slice(i,i+4096)}));
+          });
+          terminal.onResize(({cols,rows}) => { if (active()) sendSize(cols,rows); });
+          observer = new ResizeObserver(() => { if (active()) fit.fit(); });
+          observer.observe(document.getElementById('terminal'));
+          fit.fit(); sendSize(terminal.cols,terminal.rows); failures = 0; interrupt.disabled = true;
+          status.textContent = '正在恢复终端画面…';
+          const restored = () => {
+            if (!active()) return;
+            terminal.options.disableStdin = false; terminal.focus();
+            status.textContent = '已连接 · ' + result.cwd; interrupt.disabled = false; buttons();
+          };
+          // xterm parses asynchronously. Keep replay silent until its write callback,
+          // before subsequently queued live output is parsed. Startup output is live.
+          if (result.output) terminal.write(result.output, restored); else restored();
+        } else if (result.type === 'data') term?.write(result.data);
+        else if (result.type === 'exit') end(result.message || '终端已结束');
+        else if (result.type === 'error') fail((result.stage === 'spawn' ? 'Shell 启动失败：' : '终端连接被拒绝：') + result.message);
+      } catch (error) { fail('终端界面初始化或消息处理失败：' + message(error)); }
+    };
+    socket.onclose = (event) => {
+      if (!valid()) return;
+      if (event.reason === 'Reconnected from another page') { fail('该终端已在另一页面连接，点击重新连接可恢复。'); return; }
+      invalidate(); retry('WebSocket 已断开', new Error('连接关闭' + (event.code ? '（' + event.code + '）' : '')));
+    };
+    socket.onerror = () => {
+      if (!valid()) return;
+      invalidate(); retry('WebSocket 连接失败', new Error('请检查网络是否支持 WebSocket'));
+    };
+  }
+  async function check() {
+    if (stopped || !awake() || !session || checking || ws || busy) return;
+    clearTimeout(retryTimer);
+    const current = session, generation = epoch, controller = new AbortController(); checking = controller;
+    try {
+      const result = await post('status', current, controller);
+      if (generation !== epoch || current !== session || stopped || !awake()) return;
+      if (result.state === 'approved' || result.state === 'running') openSocket();
+      else if (result.state === 'pending') { failures = 0; status.textContent = '等待原会话中的所有者授权'; buttons(); schedule(1500); }
+      else end(result.message || '授权已失效，请重新请求连接');
+    } catch (error) {
+      if (generation !== epoch || current !== session || stopped || !awake()) return;
+      if ([400,401,404,410].includes(error.httpStatus)) end('授权状态查询失败：' + message(error) + '。请重新请求连接。');
+      else if (error.httpStatus === 403) fail('授权状态查询被拒绝：' + message(error));
+      else retry('暂时无法查询授权状态', error);
+    } finally { if (checking === controller) checking = undefined; }
+  }
+  connect.onclick = welcomeConnect.onclick = async () => {
+    if (busy) return;
+    stopped = false; failures = 0; invalidate();
+    if (session) { status.textContent = '正在恢复已有终端授权…'; buttons(); check(); return; }
+    busy = true; buttons(); status.textContent = '正在请求飞书授权…';
+    try {
+      document.body.classList.remove('connected');
+      if (!globalThis.crypto?.getRandomValues) throw new Error('浏览器不支持安全随机数，请使用新版浏览器。');
+      const browserKey = Array.from(crypto.getRandomValues(new Uint8Array(32)), (n) => n.toString(16).padStart(2,'0')).join('');
+      const result = await post('request', {launch:location.pathname,browserKey});
+      session = {requestId:result.requestId,browserKey,code:result.code}; sessionStorage.setItem(storageKey,JSON.stringify(session));
+      document.getElementById('code').textContent = '验证码：' + result.code;
+      status.textContent = awake() ? '等待原会话中的所有者授权' : '返回网页后将自动查询授权状态';
+    } catch (error) { status.textContent = '请求授权失败：' + message(error); }
+    finally { busy = false; buttons(!session); }
+    check();
+  };
+  interrupt.onclick = () => { if (ws?.readyState === WebSocket.OPEN && !interrupt.disabled) ws.send(JSON.stringify({type:'input',data:String.fromCharCode(3)})); };
+  close.onclick = async () => {
+    if (busy || !session || !confirm('关闭该终端和 Shell？已脱离终端的后台进程可能继续运行。')) return;
+    busy = true; stopped = true; invalidate(); buttons();
+    try { await post('close',session); end('终端已关闭'); }
+    catch (error) {
+      if ([400,401,404,410].includes(error.httpStatus)) end('终端已失效或结束');
+      else status.textContent = '关闭请求失败：' + message(error) + '；未确认关闭，请重试';
+    } finally { busy = false; buttons(true); }
+  };
+  function suspend() {
+    invalidate();
+    if (session && !stopped) { status.textContent = '连接已暂停，返回网页或网络恢复后自动重连'; buttons(true); }
+  }
+  function resume() {
+    if (stopped || !awake() || busy || !session) return;
+    clearTimeout(retryTimer); check();
+  }
+  window.addEventListener('pagehide', () => { pageHidden = true; suspend(); });
+  window.addEventListener('pageshow', () => { pageHidden = false; resume(); });
+  document.addEventListener('visibilitychange', () => { reportVisibility(); if (document.hidden) { if (!ws) suspend(); } else resume(); });
+  window.addEventListener('offline', () => { offline = true; suspend(); });
+  window.addEventListener('online', () => { offline = false; resume(); });
+  window.addEventListener('focus', resume);
+  if (session?.code) document.getElementById('code').textContent = '验证码：' + session.code;
+  buttons(); check();
+})();`;