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

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

@@ -1,7 +1,7 @@
 import type { Logger } from "pino";
 import { CardRenderer } from "../feishu/CardRenderer.js";
 import { isThreadContextKey } from "../feishu/contextKey.js";
-import type { FeishuOutbound } from "../feishu/types.js";
+import type { CardAction, FeishuOutbound } from "../feishu/types.js";
 import type { StateStore } from "../state/StateStore.js";
 import type { RestartNotificationTarget, SafeRestartStatus } from "./SafeRestartScheduler.js";
 
@@ -9,11 +9,15 @@ const DEFAULT_INITIAL_CARD_DELAY_MS = 3_000;
 
 export interface SafeRestartNotifierOptions {
   initialCardDelayMs?: number;
+  ownerId?(): string | undefined;
+  isCurrentSchedule?(scheduleId: number): boolean;
+  stopTerminal?(terminalId: string, userId: string): Promise<boolean>;
 }
 
 export class SafeRestartNotifier {
   private readonly messageIds = new Map<string, string>();
   private readonly cardHashes = new Map<string, string>();
+  private readonly cardTerminalIds = new Map<string, Set<string>>();
   private readonly notificationTargets = new Map<string, RestartNotificationTarget>();
   private activeScheduleId?: number;
   private terminalScheduleId?: number;
@@ -55,6 +59,7 @@ export class SafeRestartNotifier {
       this.activeScheduleId = status.scheduleId;
       this.messageIds.clear();
       this.cardHashes.clear();
+      this.cardTerminalIds.clear();
       this.notificationTargets.clear();
       this.clearInitialCardTimer();
       this.pendingInitialStatus = status;
@@ -90,6 +95,25 @@ export class SafeRestartNotifier {
     return [...this.notificationTargets.values()].map((target) => ({ ...target }));
   }
 
+  async stopTerminal(action: CardAction): Promise<string> {
+    const ownerId = this.options.ownerId?.();
+    if (!ownerId || action.userId !== ownerId) throw new Error("仅 AgentBot 所有者可结束终端。");
+    const scheduleId = Number(action.value.scheduleId);
+    const terminalId = typeof action.value.terminalId === "string" ? action.value.terminalId : "";
+    if (!Number.isSafeInteger(scheduleId) || scheduleId <= 0 || !/^[a-f0-9]{32}$/u.test(terminalId)) {
+      throw new Error("安全重启卡片无效，请使用最新的状态卡片。");
+    }
+    if (scheduleId !== this.activeScheduleId || !this.options.isCurrentSchedule?.(scheduleId)
+      || !this.lastStatus || ["cancelled", "restarting"].includes(this.lastStatus.phase)
+      || !action.messageId || this.messageIds.get(action.contextKey) !== action.messageId
+      || !this.cardTerminalIds.get(action.contextKey)?.has(terminalId)) {
+      throw new Error("该安全重启卡片或终端操作已失效，请查看最新状态卡片。");
+    }
+    if (!this.options.stopTerminal) throw new Error("网页终端未启用。");
+    const stopped = await this.options.stopTerminal(terminalId, ownerId);
+    return stopped ? "已请求结束对应终端，安全重启将继续等待其余阻塞项。" : "该终端已结束或正在关闭，无需重复操作。";
+  }
+
   private publishPendingInitialStatus(): Promise<void> {
     this.clearInitialCardTimer();
     const status = this.pendingInitialStatus;
@@ -132,6 +156,9 @@ export class SafeRestartNotifier {
         phase: status.phase,
         remainingMs: status.remainingMs,
         pendingFinalDeliveries: status.activity.pendingFinalDeliveries,
+        activeTerminals: status.activity.activeTerminals,
+        terminalBlockers: status.activity.terminalBlockers,
+        contextKey,
         waitingTasks,
       });
       const cardHash = JSON.stringify(card);
@@ -140,12 +167,17 @@ export class SafeRestartNotifier {
         if (this.cardHashes.get(contextKey) === cardHash) return;
         try {
           await this.outbound.updateInteractiveCard(messageId, card);
-          this.cardHashes.set(contextKey, cardHash);
+          if (this.activeScheduleId === status.scheduleId && this.messageIds.get(contextKey) === messageId) {
+            this.cardHashes.set(contextKey, cardHash);
+            this.cardTerminalIds.set(contextKey, new Set((status.activity.terminalBlockers ?? []).map((terminal) => terminal.terminalId)));
+          }
           return;
         } catch (error) {
           this.logger.warn({ error, contextKey, messageId }, "Failed to update safe restart status card; sending a replacement.");
+          if (this.activeScheduleId !== status.scheduleId) return;
           this.messageIds.delete(contextKey);
           this.cardHashes.delete(contextKey);
+          this.cardTerminalIds.delete(contextKey);
         }
       }
       try {
@@ -169,6 +201,7 @@ export class SafeRestartNotifier {
           if (this.activeScheduleId === status.scheduleId) {
             this.messageIds.set(contextKey, created);
             this.cardHashes.set(contextKey, cardHash);
+            this.cardTerminalIds.set(contextKey, new Set((status.activity.terminalBlockers ?? []).map((terminal) => terminal.terminalId)));
           } else {
             await this.stopCard(created, status, reason ?? status.reason);
           }

package/src/supervision/SafeRestartScheduler.ts

@@ -1,4 +1,8 @@
+import type { ActiveTerminal } from "../terminal/TerminalServer.js";
+
 export interface ServerActivityState {
+  activeTerminals?: number;
+  terminalBlockers?: ActiveTerminal[];
   runningSessions: number;
   pendingFinalDeliveries: number;
   latestInboundAt?: string;
@@ -49,6 +53,7 @@ export class SafeRestartScheduler {
   private idleInboundAt?: string;
   private scheduleId = 0;
   private restartImmediatelyIfIdle = false;
+  private restartingNow = false;
 
   constructor(private readonly options: SafeRestartSchedulerOptions) {}
 
@@ -56,10 +61,18 @@ export class SafeRestartScheduler {
     return Boolean(this.reason);
   }
 
+  get restarting(): boolean {
+    return this.restartingNow;
+  }
+
   get pendingReason(): string | undefined {
     return this.reason;
   }
 
+  isCurrentSchedule(scheduleId: number): boolean {
+    return this.scheduled && !this.restartingNow && this.scheduleId === scheduleId;
+  }
+
   schedule(
     reason: string,
     notificationTarget?: RestartNotificationTarget,
@@ -131,14 +144,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 +189,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 +219,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 +230,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 +284,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/TerminalCommandTracker.ts

@@ -0,0 +1,74 @@
+import { randomBytes } from "node:crypto";
+
+export interface TerminalCommandState {
+  status: "unknown" | "idle" | "running";
+  command?: string;
+  source?: "shell" | "process";
+}
+
+export class TerminalCommandTracker {
+  readonly nonce = randomBytes(16).toString("hex");
+  private readonly prefix = String.fromCharCode(27) + "]777;agentbot;" + this.nonce + ";";
+  private pending = "";
+  private current: TerminalCommandState = { status: "unknown" };
+
+  snapshot(): TerminalCommandState { return { ...this.current }; }
+
+  consume(data: string): string {
+    this.pending += data;
+    let output = "";
+    while (this.pending) {
+      const start = this.pending.indexOf(this.prefix);
+      if (start < 0) {
+        let retained = Math.min(this.prefix.length - 1, this.pending.length);
+        while (retained && !this.prefix.startsWith(this.pending.slice(-retained))) retained--;
+        output += this.pending.slice(0, this.pending.length - retained);
+        this.pending = this.pending.slice(this.pending.length - retained);
+        break;
+      }
+      output += this.pending.slice(0, start); this.pending = this.pending.slice(start);
+      const end = this.pending.indexOf("\u0007", this.prefix.length);
+      if (end < 0 && this.pending.length <= 32_768) break;
+      if (end < 0 || end > 32_768) {
+        output += this.pending[0]; this.pending = this.pending.slice(1); continue;
+      }
+      const payload = this.pending.slice(this.prefix.length, end);
+      if (payload === "idle") this.current = { status: "idle", source: "shell" };
+      else if (payload.startsWith("command;") && /^[A-Za-z0-9+/]*={0,2}$/u.test(payload.slice(8))) {
+        const command = Buffer.from(payload.slice(8), "base64").toString("utf8")
+          .replace(/[\u0000-\u0008\u000b-\u001f\u007f]/gu, "").trim();
+        this.current = { status: "running", source: "shell", command: command.slice(0, 2_000) || undefined };
+      } else this.current = { status: "unknown" };
+      this.pending = this.pending.slice(end + 1);
+    }
+    return output;
+  }
+}
+
+export function powerShellTrackingScript(nonce: string): string {
+  if (!/^[a-f0-9]{32}$/u.test(nonce)) throw new Error("Invalid terminal tracking nonce.");
+  // Wrap the accepted line, not the history hook (which skips duplicate commands).
+  // Leave editing/history policy intact and call the original prompt/readline before altering $?.
+  return [
+    "$global:__AgentBotPrompt = $function:prompt",
+    "$global:__AgentBotMarker = [char]27 + ']777;agentbot;" + nonce + ";'",
+    "try {",
+    "  Import-Module PSReadLine -ErrorAction Stop",
+    "  $global:__AgentBotReadLine = $function:PSConsoleHostReadLine",
+    "  if ($null -eq $global:__AgentBotReadLine) { throw 'PSConsoleHostReadLine unavailable' }",
+    "  function global:PSConsoleHostReadLine {",
+    "    $line = & $global:__AgentBotReadLine",
+    "    if (-not [string]::IsNullOrWhiteSpace($line)) {",
+    "      $text = if ($line.Length -gt 2000) { $line.Substring(0, 2000) } else { $line }",
+    "      [Console]::Write($global:__AgentBotMarker + 'command;' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($text)) + [char]7)",
+    "    }",
+    "    return $line",
+    "  }",
+    "  function global:prompt {",
+    "    $text = & $global:__AgentBotPrompt",
+    "    [Console]::Write($global:__AgentBotMarker + 'idle' + [char]7)",
+    "    return $text",
+    "  }",
+    "} catch { [Console]::Write($global:__AgentBotMarker + 'unknown' + [char]7) }",
+  ].join("\n");
+}

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`);
+  }
+}