@downcity/agent 1.1.135 → 1.1.149

package/scripts/city-model-tool-loop.test.mjs

@@ -230,7 +230,7 @@ test("CityModel uses direct LanguageModel path and sends tool result back", asyn
     const city = new City({
       role: "user",
       city_url: `http://127.0.0.1:${String(address.port)}`,
-      town_id: "town_demo",
+      city_id: "city_demo",
       user_token: "ub_test",
     });
     const catalog = await city.ai.listModels();
@@ -266,7 +266,7 @@ test("CityModel uses direct LanguageModel path and sends tool result back", asyn
     assert.equal(tool_executed, true);
     assert.equal(stream_requests, 0);
     assert.equal(agent_requests.length, 2);
-    assert.equal(requests.every((request) => request?.town_id === "town_demo"), true);
+    assert.equal(requests.every((request) => request?.city_id === "city_demo"), true);
     assert.equal(agent_requests[0]?.model, "mock-model");
 
     const second_request_messages = Array.isArray(agent_requests[1]?.messages)

package/scripts/session-prompt-runtime.test.mjs

@@ -98,6 +98,7 @@ test("SessionPromptRuntime merges queued prompts at the next step boundary", asy
         assistantMessage: createAssistantMessage("done", 1),
       };
     },
+    stopTurn: () => false,
   });
 
   const firstTurn = await runtime.prompt({ query: "first" });
@@ -159,6 +160,7 @@ test("SessionPromptRuntime moves unmerged prompts into the next turn", async ()
         ),
       };
     },
+    stopTurn: () => false,
   });
 
   const firstTurn = await runtime.prompt({ query: "first" });
@@ -185,3 +187,60 @@ test("SessionPromptRuntime moves unmerged prompts into the next turn", async ()
     ["turn-start", "turn-finish", "turn-start", "turn-finish"],
   );
 });
+
+test("SessionPromptRuntime stops current turn and cancels unmerged queued prompts", async () => {
+  const events = [];
+  const executionFinished = createDeferred();
+  let stopRequested = false;
+
+  const runtime = new SessionPromptRuntime({
+    sessionId: "test",
+    publish: (event) => {
+      events.push(event);
+    },
+    createAndPersistUserMessage: async (input) => {
+      return createUserMessage(input.query, events.length + 1);
+    },
+    executeTurn: async (input) => {
+      await new Promise((resolve) => {
+        input.abortSignal.addEventListener("abort", resolve, { once: true });
+      });
+      await executionFinished.promise;
+      return {
+        text: "should-not-succeed",
+        success: true,
+        assistantMessage: createAssistantMessage("should-not-succeed", 1),
+      };
+    },
+    stopTurn: () => {
+      stopRequested = true;
+      executionFinished.resolve();
+      return true;
+    },
+  });
+
+  const firstTurn = await runtime.prompt({ query: "first" });
+  const secondTurnPromise = runtime.prompt({ query: "second" });
+  await waitUntil(() => runtime.isActive());
+
+  const stopResult = runtime.stop();
+  const secondTurn = await secondTurnPromise;
+  const firstResult = await firstTurn.finished;
+  const secondResult = await secondTurn.finished;
+
+  assert.equal(stopRequested, true);
+  assert.equal(stopResult.stopped, true);
+  assert.equal(stopResult.turnId, firstTurn.id);
+  assert.equal(stopResult.cancelledQueuedPrompts, 1);
+  assert.equal(firstResult.success, false);
+  assert.equal(firstResult.error, "Turn stopped");
+  assert.equal(secondResult.success, false);
+  assert.equal(
+    secondResult.error,
+    "Prompt cancelled because session was stopped",
+  );
+  assert.deepEqual(
+    events.map((event) => event.type),
+    ["turn-start", "turn-start", "turn-finish", "turn-finish"],
+  );
+});

package/src/agent/local/Agent.ts

@@ -9,17 +9,12 @@
 
 import type { Tool } from "ai";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type {
-  AgentCreateSessionInput,
-  AgentListSessionsInput,
   AgentModel,
   AgentOptions,
-  AgentSession,
   AgentSessionCollection,
-  AgentSessionSummaryPage,
 } from "@/types/agent/AgentTypes.js";
 import type {
   ShellApprovalMode,
@@ -50,7 +45,6 @@ export class Agent {
   readonly plugins: AgentPlugins;
 
   private readonly logger: Logger;
-  private readonly runtime: AgentRuntime;
   private readonly agentContext: AgentContext;
   private readonly pluginRegistry: PluginRegistry;
   private readonly config: DowncityConfig;
@@ -89,7 +83,6 @@ export class Agent {
     this.tools = assembly.tools;
     this.plugins = assembly.plugins;
     this.logger = assembly.logger;
-    this.runtime = assembly.runtime;
     this.agentContext = assembly.agent_context;
     this.pluginRegistry = assembly.plugin_registry;
     this.config = assembly.config;
@@ -107,29 +100,6 @@ export class Agent {
     });
   }
 
-  /**
-   * 新建一个 session。
-   */
-  async createSession(input?: AgentCreateSessionInput): Promise<AgentSession> {
-    return await this.sessionManager.create_session(input);
-  }
-
-  /**
-   * 获取一个已存在的 session。
-   */
-  async getSession(sessionId: string): Promise<AgentSession> {
-    return await this.sessionManager.get_session(sessionId);
-  }
-
-  /**
-   * 列出当前 agent 的 session 摘要页。
-   */
-  async listSessions(
-    input?: AgentListSessionsInput,
-  ): Promise<AgentSessionSummaryPage> {
-    return await this.sessionManager.list_sessions(input);
-  }
-
   /**
    * 等待 Agent 后台能力启动完成。
    *
@@ -267,13 +237,6 @@ export class Agent {
     return this.logger;
   }
 
-  /**
-   * 返回当前 agent runtime。
-   */
-  getRuntime(): AgentRuntime {
-    return this.runtime;
-  }
-
   /**
    * 返回当前 agent context。
    */
@@ -282,9 +245,9 @@ export class Agent {
   }
 
   /**
-   * 返回当前 session collection。
+   * 返回当前 session collection 入口。
    */
-  getSessionCollection(): AgentSessionCollection {
+  session_collection(): AgentSessionCollection {
     return this.sessionManager.get_session_collection();
   }
 
@@ -303,8 +266,7 @@ export class Agent {
       project_root: this.path || assembly.path,
       tools: this.tools || assembly.tools,
       logger: this.logger || assembly.logger,
-      runtime: this.runtime || assembly.runtime,
-      get_agent_context: () => this.agentContext || assembly.agent_context,
+      get_agent_context: () => this.agentContext ?? assembly.agent_context,
       get_instruction: () => this.instruction,
       plugin_instances: assembly.plugin_instances,
       default_model: this.defaultModel,

package/src/agent/local/ProjectSetup.ts

@@ -30,14 +30,14 @@ function ensureContextFiles(projectRoot: string): void {
   // Check if initialized（启动入口一次性确认工程根目录与关键文件）
   if (!fs.existsSync(getProfileMdPath(projectRoot))) {
     console.error(
-      '❌ Project not initialized. Please run "town agent create" first',
+      '❌ Project not initialized. Please run "downcity agent create" first',
     );
     process.exit(1);
   }
 
   if (!fs.existsSync(getDowncityJsonPath(projectRoot))) {
     console.error(
-      '❌ downcity.json does not exist. Please run "town agent create" first',
+      '❌ downcity.json does not exist. Please run "downcity agent create" first',
     );
     process.exit(1);
   }

package/src/agent/local/services/AgentAssemblyService.ts

@@ -2,7 +2,7 @@
  * AgentAssemblyService：本地 Agent 装配服务。
  *
  * 关键点（中文）
- * - 统一装配 logger、config、env、runtime、context 与 plugin registry。
+ * - 统一装配 logger、config、env、context 与 plugin registry。
  * - 该服务只负责一次性长期对象装配，不负责 session 缓存和生命周期启动。
  * - session/lifecycle service 通过它暴露的长期对象协作，避免在 facade 中重复拼装。
  */
@@ -10,7 +10,6 @@
 import type { LanguageModel, Tool } from "ai";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type { AgentOptions } from "@/types/agent/AgentTypes.js";
@@ -25,8 +24,9 @@ import {
   createAgentPluginRegistry,
 } from "@/agent/local/AgentPluginFactory.js";
 import {
-  createAgentRuntime,
-} from "@/agent/local/AgentRuntimeFactory.js";
+  createAgentPathRuntime,
+  createAgentPluginConfigRuntime,
+} from "@/agent/local/AgentRuntimeAssembly.js";
 import {
   plugin_tools,
   setPluginToolRuntime,
@@ -113,11 +113,6 @@ export interface AgentAssemblyResult {
    */
   plugins: AgentPlugins;
 
-  /**
-   * 当前 agent runtime。
-   */
-  runtime: AgentRuntime;
-
   /**
    * 当前 agent context。
    */
@@ -166,24 +161,12 @@ export class AgentAssemblyService {
     logger.bindProjectRoot(path);
     // 关键点（中文）
     // - 这里产出的 env 是 agent 全生命周期共享的 mutable 对象引用。
-    // - runtime / context / shell 都持有同一引用；后续 `agent.setEnv()` 会原地修改它。
+    // - context / shell 都持有同一引用；后续 `agent.setEnv()` 会原地修改它。
     const env = resolveAgentEnv(path, this.options.env);
     const instruction = normalizeInstructionInput(this.options.instruction);
     const config = this.load_config(id, path);
     const plugin_instances = new Map<string, BasePlugin>();
 
-    const runtime = createAgentRuntime({
-      agent_id: id,
-      project_root: path,
-      logger,
-      config,
-      env,
-      systems: instruction,
-      plugin_instances,
-      get_session_port: this.get_session_port,
-      list_cached_sessions: this.list_cached_sessions,
-    });
-
     this.register_plugins(plugin_instances, this.options.plugins || []);
 
     // 关键点（中文）
@@ -204,20 +187,27 @@ export class AgentAssemblyService {
       tools.plugin_call = tools.plugin_call || plugin_tools.plugin_call;
     }
     const resolve_session_model = this.resolve_session_model;
+    const paths = createAgentPathRuntime(path, id);
+    const pluginConfig = createAgentPluginConfigRuntime(path);
     agent_context = new AgentContext({
-      agent: runtime,
       cwd: path,
       rootPath: path,
       logger,
       config,
       env,
       systems: instruction,
-      paths: runtime.paths,
-      pluginConfig: runtime.pluginConfig,
+      paths,
+      pluginConfig,
+      pluginInstances: plugin_instances,
       session: {
         get: (session_id) => this.get_session_port(session_id),
-        listExecutingSessionIds: () => runtime.listExecutingSessionIds(),
-        getExecutingSessionCount: () => runtime.getExecutingSessionCount(),
+        listExecutingSessionIds: () =>
+          this.list_cached_sessions()
+            .filter((session) => session.isExecuting())
+            .map((session) => session.id),
+        getExecutingSessionCount: () =>
+          this.list_cached_sessions()
+            .filter((session) => session.isExecuting()).length,
         resolveModel: async (session_id) =>
           await resolve_session_model(session_id),
       },
@@ -251,7 +241,6 @@ export class AgentAssemblyService {
       plugin_instances,
       plugin_registry,
       plugins,
-      runtime,
       agent_context: agent_context!,
       ...(shell ? { shell } : {}),
     };

package/src/agent/local/services/AgentSessionManager.ts

@@ -13,6 +13,11 @@ import type { Tool } from "ai";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type {
   AgentCreateSessionInput,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
   AgentListSessionsInput,
   AgentManagedSession,
   AgentModel,
@@ -24,16 +29,26 @@ import type {
 } from "@/types/agent/AgentTypes.js";
 import { Session } from "@/session/Session.js";
 import {
+  getSdkAgentArchivedSessionDirPath,
+  getSdkAgentArchivedSessionsDirPath,
   getSdkAgentSessionDirPath,
+  listArchivedAgentSessionSummaryPage,
   listAgentSessionSummaryPage,
 } from "@/session/index.js";
-import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
 import { createInstructionSystemBlocks } from "@/agent/local/AgentInstructions.js";
 
+function decodeMaybe(input: string): string {
+  try {
+    return decodeURIComponent(input);
+  } catch {
+    return input;
+  }
+}
+
 type AgentSessionManagerOptions = {
   /**
    * 当前 agent 稳定标识。
@@ -55,13 +70,11 @@ type AgentSessionManagerOptions = {
    */
   logger: Logger;
 
-  /**
-   * 当前 agent runtime。
-   */
-  runtime: AgentRuntime;
-
   /**
    * 延迟读取当前 agent context。
+   *
+   * 关键点（中文）
+   * - 装配期通过 getter 拿到 context，避免循环引用。
    */
   get_agent_context: () => AgentContext;
 
@@ -94,7 +107,6 @@ export class AgentSessionManager {
   private readonly project_root: string;
   private readonly tools: Record<string, Tool>;
   private readonly logger: Logger;
-  private readonly runtime: AgentRuntime;
   private readonly get_agent_context: AgentSessionManagerOptions["get_agent_context"];
   private readonly get_instruction: AgentSessionManagerOptions["get_instruction"];
   private readonly plugin_instances: Map<string, BasePlugin>;
@@ -109,16 +121,18 @@ export class AgentSessionManager {
     this.project_root = options.project_root;
     this.tools = options.tools;
     this.logger = options.logger;
-    this.runtime = options.runtime;
     this.get_agent_context = options.get_agent_context;
     this.get_instruction = options.get_instruction;
     this.plugin_instances = options.plugin_instances;
     this.default_model = options.default_model;
     this.SessionClass = options.SessionClass || Session;
     this.session_collection = {
-      createSession: async (input) => await this.create_session(input),
-      getSession: async (session_id) => await this.get_session(session_id),
-      listSessions: async (input) => await this.list_sessions(input),
+      create_session: async (input) => await this.create_session(input),
+      get_session: async (session_id) => await this.get_session(session_id),
+      list_sessions: async (input) => await this.list_sessions(input),
+      archive_session: async (input) => await this.archive_session(input),
+      archive_sessions: async (input) => await this.archive_sessions(input),
+      clean_archive: async () => await this.clean_archive(),
     };
   }
 
@@ -180,7 +194,7 @@ export class AgentSessionManager {
   async get_session(session_id: string): Promise<AgentSession> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
-      throw new Error("getSession requires a non-empty sessionId");
+      throw new Error("get_session requires a non-empty sessionId");
     }
     const session_dir_path = getSdkAgentSessionDirPath(
       this.project_root,
@@ -211,10 +225,110 @@ export class AgentSessionManager {
       projectRoot: this.project_root,
       agentId: this.agent_id,
       input,
-      executingSessionIds: new Set(this.runtime.listExecutingSessionIds()),
+      executingSessionIds: new Set(this.get_agent_context().listExecutingSessionIds()),
     });
   }
 
+  /**
+   * 归档单个 session。
+   */
+  async archive_session(
+    input: AgentArchiveSessionInput,
+  ): Promise<AgentArchiveSessionResult> {
+    const session_id = String(input?.id || "").trim();
+    if (!session_id) {
+      throw new Error("archive_session requires a non-empty id");
+    }
+
+    const executing_session_ids = new Set(
+      this.get_agent_context().listExecutingSessionIds(),
+    );
+    if (executing_session_ids.has(session_id)) {
+      throw new Error(`Session "${session_id}" is currently executing`);
+    }
+
+    const source_path = getSdkAgentSessionDirPath(
+      this.project_root,
+      this.agent_id,
+      session_id,
+    );
+    if (!(await fs.pathExists(source_path))) {
+      throw new Error(`Session "${session_id}" not found`);
+    }
+
+    const target_path = getSdkAgentArchivedSessionDirPath(
+      this.project_root,
+      this.agent_id,
+      session_id,
+    );
+    if (await fs.pathExists(target_path)) {
+      throw new Error(`Archived session "${session_id}" already exists`);
+    }
+
+    await fs.ensureDir(getSdkAgentArchivedSessionsDirPath(
+      this.project_root,
+      this.agent_id,
+    ));
+    await fs.move(source_path, target_path);
+
+    // 关键点（中文）：归档后清理缓存，避免后续操作访问已移动目录。
+    this.sessions_by_id.delete(session_id);
+    this.configured_session_ids.delete(session_id);
+
+    return {
+      sessionId: session_id,
+      archivedAt: Date.now(),
+    };
+  }
+
+  /**
+   * 列出当前 agent 的已归档 session 摘要页。
+   */
+  async archive_sessions(
+    input?: AgentArchiveSessionsInput,
+  ): Promise<AgentArchiveSessionsResult> {
+    return await listArchivedAgentSessionSummaryPage({
+      projectRoot: this.project_root,
+      agentId: this.agent_id,
+      input,
+    });
+  }
+
+  /**
+   * 永久清空已归档 session。
+   */
+  async clean_archive(): Promise<AgentCleanArchiveResult> {
+    const archived_root = getSdkAgentArchivedSessionsDirPath(
+      this.project_root,
+      this.agent_id,
+    );
+    if (!(await fs.pathExists(archived_root))) {
+      return {
+        removedSessionIds: [],
+      };
+    }
+
+    const entries = await fs.readdir(archived_root, { withFileTypes: true });
+    const removed_session_ids: string[] = [];
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const session_id = decodeMaybe(entry.name);
+      if (!session_id) continue;
+      const session_path = getSdkAgentArchivedSessionDirPath(
+        this.project_root,
+        this.agent_id,
+        session_id,
+      );
+      await fs.remove(session_path);
+      removed_session_ids.push(session_id);
+    }
+
+    return {
+      removedSessionIds: removed_session_ids,
+    };
+  }
+
   private get_or_create_session(input?: {
     /**
      * 可选指定 session id。

package/src/agent/remote/RemoteAgent.ts

@@ -8,9 +8,7 @@
  */
 
 import type {
-  AgentCreateSessionInput,
-  AgentListSessionsInput,
-  AgentSessionSummaryPage,
+  AgentSessionCollection,
   RemoteAgentPluginActionInput,
   RemoteAgentPluginActionResult,
   RemoteAgentOptions,
@@ -42,37 +40,6 @@ export class RemoteAgent {
     this.transport = create_remote_agent_transport(url, options.token);
   }
 
-  /**
-   * 新建一个远程 session。
-   */
-  async createSession(
-    input?: AgentCreateSessionInput,
-  ): Promise<RemoteAgentSession> {
-    const info = await this.transport.create_session(input);
-    return new RemoteSession(this.transport, info.sessionId);
-  }
-
-  /**
-   * 获取一个已存在的远程 session。
-   */
-  async getSession(sessionId: string): Promise<RemoteAgentSession> {
-    const resolved_session_id = String(sessionId || "").trim();
-    if (!resolved_session_id) {
-      throw new Error("getSession requires a non-empty sessionId");
-    }
-    const info = await this.transport.get_info(resolved_session_id);
-    return new RemoteSession(this.transport, info.sessionId);
-  }
-
-  /**
-   * 列出远程 agent 的 session 摘要页。
-   */
-  async listSessions(
-    input?: AgentListSessionsInput,
-  ): Promise<AgentSessionSummaryPage> {
-    return await this.transport.list_sessions(input);
-  }
-
   /**
    * 执行远程 Agent runtime 内的 plugin action。
    *
@@ -153,4 +120,28 @@ export class RemoteAgent {
   async close(): Promise<void> {
     await this.transport.close?.();
   }
+
+  /**
+   * 返回当前远程 session collection 入口。
+   *
+   * 关键点（中文）
+   * - `RemoteAgentTransport` 只负责协议传输，不直接等价于 `AgentSessionCollection`。
+   * - 这里把 transport 包装为 `AgentSessionCollection`，`create_session` / `get_session` 返回 `RemoteSession` 实例。
+   */
+  session_collection(): AgentSessionCollection {
+    return {
+     create_session: async (input) => {
+       const info = await this.transport.create_session(input);
+        return new RemoteSession(this.transport, info);
+      },
+      get_session: async (session_id) => {
+        const info = await this.transport.get_info(session_id);
+        return new RemoteSession(this.transport, info);
+      },
+      list_sessions: async (input) => await this.transport.list_sessions(input),
+      archive_session: async (input) => await this.transport.archive_session(input),
+      archive_sessions: async (input) => await this.transport.archive_sessions(input),
+      clean_archive: async () => await this.transport.clean_archive(),
+    };
+  }
 }

package/src/agent/remote/RemoteSession.ts

@@ -7,14 +7,16 @@
  */
 
 import type {
+  AgentSession,
+  AgentSessionConfigSnapshot,
   AgentSessionForkInput,
   AgentSessionHistoryInput,
   AgentSessionHistoryPage,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSystemSnapshot,
-  RemoteAgentSession,
 } from "@/types/agent/AgentTypes.js";
+import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
   AgentSessionEvent,
   AgentSessionSubscriber,
@@ -50,8 +52,10 @@ type RemoteTurnLifecycle = {
 /**
  * 远程 Session 客户端。
  */
-export class RemoteSession implements RemoteAgentSession {
+export class RemoteSession implements AgentSession {
   readonly id: string;
+  readonly agentId: string;
+  readonly config: AgentSessionConfigSnapshot;
 
   private readonly transport: RemoteSessionTransport;
   private readonly event_hub = new SessionEventHub();
@@ -62,9 +66,12 @@ export class RemoteSession implements RemoteAgentSession {
   private event_subscriber_count = 0;
   private event_subscription: TransportSubscription | null = null;
 
-  constructor(transport: RemoteSessionTransport, session_id: string) {
+  constructor(transport: RemoteSessionTransport, info: AgentSessionInfo) {
     this.transport = transport;
-    this.id = session_id;
+    this.id = info.sessionId;
+    this.agentId = info.agentId;
+    // 远程 session 不暴露服务端模型实例，config 返回空快照。
+    this.config = {} as AgentSessionConfigSnapshot;
   }
 
   /**
@@ -98,6 +105,14 @@ export class RemoteSession implements RemoteAgentSession {
     return create_turn_handle(lifecycle);
   }
 
+  /**
+   * 停止当前远程 session turn，并取消未吸收队列。
+   */
+  async stop(): Promise<AgentSessionStopResult> {
+    await this.ensure_event_pump();
+    return await this.transport.stop(this.id);
+  }
+
   /**
    * 订阅当前远程 session 的 future 事件。
    */
@@ -134,9 +149,9 @@ export class RemoteSession implements RemoteAgentSession {
   /**
    * 分叉远程 session。
    */
-  async fork(input?: AgentSessionForkInput | string): Promise<RemoteAgentSession> {
+  async fork(input?: AgentSessionForkInput | string): Promise<AgentSession> {
     const info = await this.transport.fork(this.id, input);
-    return new RemoteSession(this.transport, info.sessionId);
+    return new RemoteSession(this.transport, info);
   }
 
   private async ensure_event_pump(): Promise<void> {