@downcity/agent 1.1.135 → 1.1.148

package/src/session/browse/Browse.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 统一负责 session 列表摘要、session 详情与 history 分页的投影逻辑。
  * - session title 允许为空；浏览层不会再从首条 user message 推导 fallback title。
- * - 面向 SDK / RemoteAgent / Town gateway route 复用，避免在多个入口重复拼列表与分页语义。
+ * - 面向 SDK / RemoteAgent / downcity gateway route 复用，避免在多个入口重复拼列表与分页语义。
  * - 这里不持有运行态状态；执行状态等动态信息通过调用参数显式注入。
  */
 
@@ -33,7 +33,11 @@ import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.j
 import { pickLastSuccessfulChatSendText } from "@/executor/messages/UserVisibleText.js";
 import { getSdkAgentSessionMessagesPath } from "@/session/storage/Paths.js";
 import { getSdkAgentSessionsRootDirPath } from "@/session/storage/Paths.js";
+import { getSdkAgentArchivedSessionsDirPath } from "@/session/storage/Paths.js";
+import { getSdkAgentArchivedSessionMessagesPath } from "@/session/storage/Paths.js";
+import { getSdkAgentArchivedSessionMetaPath } from "@/session/storage/Paths.js";
 import { readSessionMetadata } from "@/session/storage/Metadata.js";
+import { readSessionMetadataFromPath } from "@/session/storage/Metadata.js";
 import {
   ensureSessionTitle,
 } from "@/session/SessionTitle.js";
@@ -470,6 +474,103 @@ export async function listAgentSessionSummaryPage(params: {
   const entries = await fs.readdir(sessionsRoot, { withFileTypes: true });
   const summaries: AgentSessionSummary[] = [];
 
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const sessionId = decodeMaybe(entry.name);
+    if (!sessionId) continue;
+    const metadata = await readSessionMetadataFromPath({
+      filePath: getSdkAgentArchivedSessionMetaPath(
+        params.projectRoot,
+        params.agentId,
+        sessionId,
+      ),
+      sessionId,
+      agentId: params.agentId,
+    });
+    const messages = await loadSessionMessagesFromPath(
+      getSdkAgentArchivedSessionMessagesPath(
+        params.projectRoot,
+        params.agentId,
+        sessionId,
+      ),
+    );
+    // 关键点（中文）：归档 session 不再生成新 title，仅读取已有 meta。
+    const metadataWithTitle = metadata;
+    const info = buildSessionInfo({
+      projectRoot: params.projectRoot,
+      agentId: params.agentId,
+      sessionId,
+      metadata: metadataWithTitle,
+      messages,
+      executing: params.executingSessionIds?.has(sessionId),
+    });
+    const summary: AgentSessionSummary = {
+      agentId: info.agentId,
+      sessionId: info.sessionId,
+      ...(info.title ? { title: info.title } : {}),
+      ...(info.previewText ? { previewText: info.previewText } : {}),
+      messageCount: info.messageCount,
+      ...(typeof info.createdAt === "number" ? { createdAt: info.createdAt } : {}),
+      ...(typeof info.updatedAt === "number" ? { updatedAt: info.updatedAt } : {}),
+      ...(info.modelLabel ? { modelLabel: info.modelLabel } : {}),
+      ...(info.executing ? { executing: true } : {}),
+    };
+
+    if (query) {
+      const haystack = [
+        summary.sessionId,
+        summary.title || "",
+        summary.previewText || "",
+      ]
+        .join("\n")
+        .toLowerCase();
+      if (!haystack.includes(query)) continue;
+    }
+
+    summaries.push(summary);
+  }
+
+  summaries.sort((left, right) => (right.updatedAt || 0) - (left.updatedAt || 0));
+
+  const items = summaries.slice(cursor, cursor + limit);
+  const nextOffset = cursor + items.length;
+  return {
+    items,
+    total: summaries.length,
+    ...(nextOffset < summaries.length
+      ? { nextCursor: encodeCursor(nextOffset) }
+      : {}),
+    hasMore: nextOffset < summaries.length,
+  };
+}
+
+/**
+ * 列出指定 agent 的已归档 session 摘要页。
+ */
+export async function listArchivedAgentSessionSummaryPage(params: {
+  projectRoot: string;
+  agentId: string;
+  input?: AgentListSessionsInput;
+}): Promise<AgentSessionSummaryPage> {
+  const limit = normalizeLimit(params.input?.limit, 50, 500);
+  const cursor = normalizeCursor(params.input?.cursor);
+  const query = String(params.input?.query || "").trim().toLowerCase();
+  const archivedRoot = getSdkAgentArchivedSessionsDirPath(
+    params.projectRoot,
+    params.agentId,
+  );
+
+  if (!(await fs.pathExists(archivedRoot))) {
+    return {
+      items: [],
+      total: 0,
+      hasMore: false,
+    };
+  }
+
+  const entries = await fs.readdir(archivedRoot, { withFileTypes: true });
+  const summaries: AgentSessionSummary[] = [];
+
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const sessionId = decodeMaybe(entry.name);
@@ -496,7 +597,7 @@ export async function listAgentSessionSummaryPage(params: {
       sessionId,
       metadata: metadataWithTitle,
       messages,
-      executing: params.executingSessionIds?.has(sessionId),
+      executing: false,
     });
     const summary: AgentSessionSummary = {
       agentId: info.agentId,
@@ -507,7 +608,6 @@ export async function listAgentSessionSummaryPage(params: {
       ...(typeof info.createdAt === "number" ? { createdAt: info.createdAt } : {}),
       ...(typeof info.updatedAt === "number" ? { updatedAt: info.updatedAt } : {}),
       ...(info.modelLabel ? { modelLabel: info.modelLabel } : {}),
-      ...(info.executing ? { executing: true } : {}),
     };
 
     if (query) {

package/src/session/index.ts

@@ -10,6 +10,11 @@ export { Session } from "./Session.js";
 
 export {
   getSdkAgentDirPath,
+  getSdkAgentArchivedSessionDirPath,
+  getSdkAgentArchivedSessionMessagesDirPath,
+  getSdkAgentArchivedSessionMessagesPath,
+  getSdkAgentArchivedSessionMetaPath,
+  getSdkAgentArchivedSessionsDirPath,
   getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
   getSdkAgentSessionInflightPath,
@@ -25,6 +30,7 @@ export {
   normalizeSessionTitle,
   patchSessionModelLabel,
   readSessionMetadata,
+  readSessionMetadataFromPath,
   resolveSystemTimezone,
   writeSessionMetadata,
 } from "./storage/Metadata.js";
@@ -41,6 +47,7 @@ export {
 export {
   buildSessionHistoryPage,
   buildSessionInfo,
+  listArchivedAgentSessionSummaryPage,
   listAgentSessionSummaryPage,
   loadSessionMessagesFromPath,
   resolveSessionMessagePreview,

package/src/session/runtime/SessionPromptRuntime.ts

@@ -12,11 +12,16 @@ import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
   AgentSessionTurnHandle,
   AgentSessionTurnResult,
 } from "@/types/sdk/AgentSessionTurn.js";
 
+const TURN_STOPPED_MESSAGE = "Turn stopped";
+const QUEUED_PROMPT_CANCELLED_MESSAGE =
+  "Prompt cancelled because session was stopped";
+
 type QueuedPrompt = {
   /**
    * 当前排队中的 prompt 输入。
@@ -62,6 +67,11 @@ interface ActiveTurnState {
    * 当前 turn 完成 Promise 控制器。
    */
   deferredFinished: Deferred<AgentSessionTurnResult>;
+
+  /**
+   * 当前 turn 的取消控制器。
+   */
+  abortController: AbortController;
 }
 
 /**
@@ -92,12 +102,18 @@ export interface SessionPromptRuntimeOptions {
     turnId: string;
     promptInput: AgentSessionPromptInput;
     onStepMerge: () => Promise<SessionUserMessageV1[]>;
+    abortSignal: AbortSignal;
   }) => Promise<{
     text: string;
     success: boolean;
     assistantMessage: SessionMessageV1;
     error?: string;
   }>;
+
+  /**
+   * 请求底层执行器停止当前 run。
+   */
+  stopTurn: () => boolean;
 }
 
 /**
@@ -108,14 +124,17 @@ export class SessionPromptRuntime {
   private readonly publish: SessionPromptRuntimeOptions["publish"];
   private readonly createAndPersistUserMessage: SessionPromptRuntimeOptions["createAndPersistUserMessage"];
   private readonly executeTurn: SessionPromptRuntimeOptions["executeTurn"];
+  private readonly stopTurn: SessionPromptRuntimeOptions["stopTurn"];
   private readonly queue: QueuedPrompt[] = [];
   private processingPromise: Promise<void> | null = null;
+  private activeTurn: ActiveTurnState | null = null;
 
   constructor(options: SessionPromptRuntimeOptions) {
     this.sessionId = String(options.sessionId || "").trim();
     this.publish = options.publish;
     this.createAndPersistUserMessage = options.createAndPersistUserMessage;
     this.executeTurn = options.executeTurn;
+    this.stopTurn = options.stopTurn;
     if (!this.sessionId) {
       throw new Error("SessionPromptRuntime requires a non-empty sessionId");
     }
@@ -147,6 +166,34 @@ export class SessionPromptRuntime {
     return this.processingPromise !== null || this.queue.length > 0;
   }
 
+  /**
+   * 停止当前 turn，并取消尚未被吸收的排队 prompt。
+   */
+  stop(): AgentSessionStopResult {
+    const active_turn = this.activeTurn;
+    const cancelled_queued_prompts = this.cancelQueuedPrompts();
+    let executor_stop_requested = false;
+
+    if (active_turn) {
+      if (!active_turn.abortController.signal.aborted) {
+        active_turn.abortController.abort(new Error(TURN_STOPPED_MESSAGE));
+      }
+      executor_stop_requested = this.stopTurn();
+    }
+
+    const stopped = Boolean(
+      active_turn ||
+        executor_stop_requested ||
+        cancelled_queued_prompts > 0,
+    );
+    return {
+      stopped,
+      ...(active_turn ? { turnId: active_turn.turnId } : {}),
+      cancelledQueuedPrompts: cancelled_queued_prompts,
+      reason: stopped ? "stopped" : "idle",
+    };
+  }
+
   private ensureProcessing(): void {
     if (this.processingPromise) return;
     this.processingPromise = this.processLoop().finally(() => {
@@ -164,6 +211,7 @@ export class SessionPromptRuntime {
 
       const turnId = `turn:${this.sessionId}:${Date.now()}:${nanoid(6)}`;
       const activeTurn = createActiveTurnState(turnId);
+      this.activeTurn = activeTurn;
       this.publish({
         type: "turn-start",
         turnId,
@@ -178,7 +226,11 @@ export class SessionPromptRuntime {
           onStepMerge: async () => {
             return await this.drainQueuedPromptsAsMessages(activeTurn);
           },
+          abortSignal: activeTurn.abortController.signal,
         });
+        if (activeTurn.abortController.signal.aborted) {
+          throw new Error(TURN_STOPPED_MESSAGE);
+        }
         const finalResult: AgentSessionTurnResult = {
           turnId,
           text: result.text,
@@ -196,7 +248,9 @@ export class SessionPromptRuntime {
         });
         activeTurn.deferredFinished.resolve(finalResult);
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = activeTurn.abortController.signal.aborted
+          ? TURN_STOPPED_MESSAGE
+          : error instanceof Error ? error.message : String(error);
         const finalResult: AgentSessionTurnResult = {
           turnId,
           text: "",
@@ -208,10 +262,12 @@ export class SessionPromptRuntime {
           error: message,
         };
         activeTurn.result = finalResult;
-        this.publish({
-          type: "error",
-          message,
-        });
+        if (message !== TURN_STOPPED_MESSAGE) {
+          this.publish({
+            type: "error",
+            message,
+          });
+        }
         this.publish({
           type: "turn-finish",
           turnId,
@@ -220,10 +276,48 @@ export class SessionPromptRuntime {
           error: message,
         });
         activeTurn.deferredFinished.resolve(finalResult);
+      } finally {
+        if (this.activeTurn === activeTurn) {
+          this.activeTurn = null;
+        }
       }
     }
   }
 
+  private cancelQueuedPrompts(): number {
+    if (this.queue.length <= 0) return 0;
+    const cancelled = this.queue.splice(0, this.queue.length);
+    for (const item of cancelled) {
+      const turnId = `turn:${this.sessionId}:cancelled:${Date.now()}:${nanoid(6)}`;
+      const cancelledTurn = createActiveTurnState(turnId);
+      const finalResult: AgentSessionTurnResult = {
+        turnId,
+        text: "",
+        success: false,
+        assistantMessage: buildPromptRuntimeErrorAssistantMessage({
+          sessionId: this.sessionId,
+          message: QUEUED_PROMPT_CANCELLED_MESSAGE,
+        }),
+        error: QUEUED_PROMPT_CANCELLED_MESSAGE,
+      };
+      cancelledTurn.result = finalResult;
+      cancelledTurn.deferredFinished.resolve(finalResult);
+      this.publish({
+        type: "turn-start",
+        turnId,
+      });
+      this.publish({
+        type: "turn-finish",
+        turnId,
+        text: "",
+        success: false,
+        error: QUEUED_PROMPT_CANCELLED_MESSAGE,
+      });
+      item.deferredHandle.resolve(createTurnHandle(cancelledTurn));
+    }
+    return cancelled.length;
+  }
+
   private async drainQueuedPromptsAsMessages(
     activeTurn: ActiveTurnState,
   ): Promise<SessionUserMessageV1[]> {
@@ -286,6 +380,7 @@ function createActiveTurnState(turnId: string): ActiveTurnState {
     turnId,
     result: null,
     deferredFinished: createDeferred<AgentSessionTurnResult>(),
+    abortController: new AbortController(),
   };
 }
 

package/src/session/services/SessionTurnService.ts

@@ -15,6 +15,7 @@ import type {
   AgentSessionUnsubscribe,
 } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import type {
   SessionMessageV1,
@@ -80,13 +81,15 @@ export class SessionTurnService {
           input,
         );
       },
-      executeTurn: async ({ turnId, promptInput, onStepMerge }) => {
+      executeTurn: async ({ turnId, promptInput, onStepMerge, abortSignal }) => {
         return await this.execute_prompt_turn({
           turnId,
           promptInput,
           onStepMerge,
+          abortSignal,
         });
       },
+      stopTurn: () => this.executor.stop(),
     });
   }
 
@@ -125,6 +128,13 @@ export class SessionTurnService {
     });
   }
 
+  /**
+   * 停止当前 turn，并取消尚未被吸收的排队 prompt。
+   */
+  async stop(): Promise<AgentSessionStopResult> {
+    return this.prompt_runtime.stop();
+  }
+
   /**
    * 执行单轮 prompt turn。
    */
@@ -132,6 +142,7 @@ export class SessionTurnService {
     turnId: string;
     promptInput: AgentSessionPromptInput;
     onStepMerge: () => Promise<SessionUserMessageV1[]>;
+    abortSignal?: AbortSignal;
   }): Promise<{
     text: string;
     success: boolean;
@@ -192,6 +203,7 @@ export class SessionTurnService {
       injectedUserMessages: [],
       deferredPersistedUserMessages: [],
       pendingAssistantFileParts: [],
+      ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
     };
     const result = await this.executor.run({
       query: input.promptInput.query,

package/src/session/storage/Metadata.ts

@@ -93,8 +93,30 @@ export async function readSessionMetadata(
     input.agentId,
     input.sessionId,
   );
+  return await readSessionMetadataFromPath({
+    filePath,
+    sessionId: input.sessionId,
+    agentId: input.agentId,
+  });
+}
+
+/**
+ * 从指定路径读取 session meta.json。
+ *
+ * 关键点（中文）
+ * - 供归档 session 等需要脱离默认 `sessions/` 目录的场景复用。
+ * - 路径本身不做校验，调用方需保证可访问。
+ */
+export async function readSessionMetadataFromPath(input: {
+  /** meta.json 文件路径。 */
+  filePath: string;
+  /** 当前 sessionId。 */
+  sessionId: string;
+  /** 当前 agentId。 */
+  agentId: string;
+}): Promise<SessionHistoryMetaV1> {
   try {
-    const raw = (await fs.readJson(filePath)) as Partial<SessionHistoryMetaV1>;
+    const raw = (await fs.readJson(input.filePath)) as Partial<SessionHistoryMetaV1>;
     return {
       v: 1,
       sessionId: input.sessionId,

package/src/session/storage/Paths.ts

@@ -45,6 +45,76 @@ export function getSdkAgentSessionsRootDirPath(
   return path.join(getSdkAgentDirPath(projectRoot, agentId), "sessions");
 }
 
+/**
+ * 单个 agent 的已归档 sessions 根目录路径。
+ *
+ * 关键点（中文）
+ * - `archive_session` 会把整个 session 目录从 `sessions/<sessionId>` 移动到此处。
+ * - `clean_archive` 会永久删除该目录下的全部内容。
+ */
+export function getSdkAgentArchivedSessionsDirPath(
+  projectRoot: string,
+  agentId: string,
+): string {
+  return path.join(getSdkAgentDirPath(projectRoot, agentId), "archived-sessions");
+}
+
+/**
+ * 单个已归档 session 的根目录路径。
+ */
+export function getSdkAgentArchivedSessionDirPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentArchivedSessionsDirPath(projectRoot, agentId),
+    encodeURIComponent(String(sessionId || "").trim()),
+  );
+}
+
+/**
+ * 单个已归档 session 的消息目录路径。
+ */
+export function getSdkAgentArchivedSessionMessagesDirPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentArchivedSessionDirPath(projectRoot, agentId, sessionId),
+    "messages",
+  );
+}
+
+/**
+ * 单个已归档 session 的消息 JSONL 文件路径。
+ */
+export function getSdkAgentArchivedSessionMessagesPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentArchivedSessionMessagesDirPath(projectRoot, agentId, sessionId),
+    "messages.jsonl",
+  );
+}
+
+/**
+ * 单个已归档 session 的 meta.json 路径。
+ */
+export function getSdkAgentArchivedSessionMetaPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentArchivedSessionMessagesDirPath(projectRoot, agentId, sessionId),
+    "meta.json",
+  );
+}
+
 /**
  * 单个 session 根目录路径。
  */

package/src/session/storage/RuntimeSessionPort.ts

@@ -9,6 +9,7 @@
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
   AgentSessionEvent,
   AgentSessionSubscriber,
@@ -32,6 +33,10 @@ export interface CreateRuntimeSessionPortParams {
    * 追加一条新的 session prompt。
    */
   prompt: (input: AgentSessionPromptInput) => Promise<AgentSessionTurnHandle>;
+  /**
+   * 停止当前 turn，并取消尚未被吸收的排队 prompt。
+   */
+  stop: () => Promise<AgentSessionStopResult>;
   /**
    * 订阅当前 session 的 future 事件。
    */
@@ -90,6 +95,10 @@ export function createRuntimeSessionPort(
       await params.ensureReadyForExecution();
       return await params.prompt(input);
     },
+    stop: async () => {
+      await params.ensureReadyForExecution();
+      return await params.stop();
+    },
     subscribe: (subscriber) => {
       return params.subscribe(subscriber);
     },

package/src/types/agent/AgentTypes.ts

@@ -27,6 +27,11 @@ export type {
   RemoteAgentPluginActionResult,
 } from "@/types/agent/RemoteAgentPluginAction.js";
 export type {
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
   AgentCreateSessionInput,
   AgentListSessionsInput,
   AgentSessionConfigSnapshot,
@@ -44,6 +49,7 @@ export type {
   AgentSessionSystemSnapshot,
   AgentSessionTimelineEvent,
 } from "@/types/agent/SessionTypes.js";
+export type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 export type {
   AgentSession,
   AgentSessionActor,

package/src/types/agent/SessionActor.ts

@@ -8,6 +8,11 @@
 
 import type {
   AgentCreateSessionInput,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
   AgentListSessionsInput,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
@@ -23,6 +28,7 @@ import type {
   AgentSessionUnsubscribe,
 } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 
 /**
@@ -30,13 +36,22 @@ import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
  */
 export interface AgentSessionCollection {
   /** 新建一个 session。 */
-  createSession(input?: AgentCreateSessionInput): Promise<AgentSession>;
+  create_session(input?: AgentCreateSessionInput): Promise<AgentSession>;
 
   /** 获取一个已存在的 session。 */
-  getSession(sessionId: string): Promise<AgentSession>;
+  get_session(sessionId: string): Promise<AgentSession>;
 
   /** 列出当前 agent 的 session 摘要页。 */
-  listSessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
+  list_sessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
+
+  /** 归档单个 session。 */
+  archive_session(input: AgentArchiveSessionInput): Promise<AgentArchiveSessionResult>;
+
+  /** 列出已归档的 session 摘要页。 */
+  archive_sessions(input?: AgentArchiveSessionsInput): Promise<AgentArchiveSessionsResult>;
+
+  /** 永久清空已归档 session。 */
+  clean_archive(): Promise<AgentCleanArchiveResult>;
 }
 
 /**
@@ -52,6 +67,9 @@ export interface AgentSessionActor {
   /** 追加一条新的 prompt。 */
   prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
 
+  /** 停止当前 turn，并取消尚未被吸收的排队 prompt。 */
+  stop(): Promise<AgentSessionStopResult>;
+
   /** 订阅当前 session 的未来事件。 */
   subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;