@downcity/agent 1.1.129 → 1.1.148

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;
 

package/src/types/agent/SessionTypes.ts

@@ -333,3 +333,71 @@ export interface AgentSessionForkInput {
    */
   messageId?: string;
 }
+
+/**
+ * 归档单个 session 的输入参数。
+ */
+export interface AgentArchiveSessionInput {
+  /**
+   * 要归档的 session id。
+   *
+   * 关键点（中文）
+   * - 必须指向当前 agent 下已存在的未归档 session。
+   * - 正在执行中的 session 不允许归档。
+   */
+  id: string;
+}
+
+/**
+ * 列出已归档 session 的输入参数。
+ */
+export interface AgentArchiveSessionsInput {
+  /**
+   * 当前页返回上限。
+   *
+   * 说明（中文）
+   * - 省略时由 SDK 使用默认值。
+   */
+  limit?: number;
+
+  /**
+   * 分页游标。
+   *
+   * 说明（中文）
+   * - 当前使用 SDK 自身生成的透明字符串游标。
+   * - 调用方只负责透传，不应自行解析其内部格式。
+   */
+  cursor?: string;
+
+  /**
+   * 关键词过滤。
+   *
+   * 说明（中文）
+   * - 推荐用于匹配 `sessionId`、标题与预览文本。
+   * - 属于轻量包含匹配，不承诺复杂搜索语义。
+   */
+  query?: string;
+}
+
+/**
+ * 归档单个 session 的结果。
+ */
+export interface AgentArchiveSessionResult {
+  /** 被归档的 session id。 */
+  sessionId: string;
+  /** 归档时间戳（ms）。 */
+  archivedAt: number;
+}
+
+/**
+ * 列出已归档 session 的结果。
+ */
+export interface AgentArchiveSessionsResult extends AgentSessionSummaryPage {}
+
+/**
+ * 清空归档目录的结果。
+ */
+export interface AgentCleanArchiveResult {
+  /** 被永久删除的归档 session id 列表。 */
+  removedSessionIds: string[];
+}

package/src/types/config/DowncityConfig.ts

@@ -135,7 +135,7 @@ export interface DowncityConfig {
   id: string;
   version: string;
   /**
-   * Runtime startup configuration used by `town agent start`.
+   * Runtime startup configuration used by `downcity agent start`.
    * CLI flags (if provided) take precedence over this config.
    */
   start?: {

package/src/types/executor/SessionRunContext.ts

@@ -66,6 +66,15 @@ export interface SessionRunContext {
    */
   onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
 
+  /**
+   * 当前 turn 的取消信号。
+   *
+   * 关键点（中文）
+   * - `session.stop()` 会触发该 signal。
+   * - 模型流、tool-loop 与长耗时 composer 应优先监听它，尽快结束当前 turn。
+   */
+  abortSignal?: AbortSignal;
+
   /**
    * 本轮运行中待并入下一 step 的 user 消息。
    *

package/src/types/platform/Store.ts

@@ -2,8 +2,8 @@
  * 平台存储类型定义。
  *
  * 关键点（中文）
- * - Town 只保存平台级 env、channel account 与安全配置。
- * - 模型能力由 City AIService 暴露，Town 不再声明 provider/model 存储类型。
+ * - downcity 只保存平台级 env、channel account 与安全配置。
+ * - 模型能力由 City AIService 暴露，downcity 不再声明 provider/model 存储类型。
  */
 
 /**

package/src/types/rpc/RpcProtocol.ts

@@ -4,13 +4,19 @@
  * 关键点（中文）
  * - 该文件只描述本机 RPC 的线协议，不包含 socket 或业务执行逻辑。
  * - Client 与 Server 共享同一份 request/frame 类型，避免协议两边漂移。
- * - 字段名保持现有协议格式，兼容已发布的 Town 托管 runtime 调用。
+ * - 字段名保持现有协议格式，兼容已发布的 downcity 托管 runtime 调用。
  */
 
 import type {
   AgentCreateSessionInput,
   AgentListSessionsInput,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
   AgentSessionHistoryInput,
+  AgentSessionStopResult,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/AgentTypes.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
@@ -24,13 +30,13 @@ import type { ShellApprovalMode } from "@downcity/shell";
  *
  * 关键点（中文）
  * - `sdk.*` 面向 RemoteAgent 的稳定会话 SDK。
- * - `internal.*` 面向 Town 本机管理通道。
+ * - `internal.*` 面向 downcity 本机管理通道。
  */
 export type RpcRequest =
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
-      /** 列出 session。 */
+      /** 列出 sessions。 */
       method: "sdk.sessions.list";
       /** 列表过滤与分页参数。 */
       params?: AgentListSessionsInput;
@@ -46,7 +52,7 @@ export type RpcRequest =
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
-      /** 读取 session 信息。 */
+      /** 获取 session。 */
       method: "sdk.sessions.get";
       /** 目标 session 参数。 */
       params: {
@@ -54,6 +60,31 @@ export type RpcRequest =
         sessionId: string;
       };
     }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 归档 session。 */
+      method: "sdk.sessions.archive";
+      /** 归档参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 列出已归档 sessions。 */
+      method: "sdk.sessions.archived.list";
+      /** 列表过滤与分页参数。 */
+      params?: AgentArchiveSessionsInput;
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 清空已归档 sessions。 */
+      method: "sdk.sessions.archived.clean";
+    }
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
@@ -67,6 +98,17 @@ export type RpcRequest =
         input: AgentSessionPromptInput;
       };
     }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 停止当前 session turn。 */
+      method: "sdk.sessions.stop";
+      /** 停止参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+      };
+    }
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;

package/src/types/runtime/agent/AgentContext.ts

@@ -3,23 +3,20 @@
  *
  * 职责说明（中文）
  * - 这里定义 plugin runtime、plugin、prompt system 共用的统一执行上下文。
- * - `AgentContext` 表达的是“当前一次执行可见的能力面”，不是宿主状态本体。
- *
- * 边界说明（中文）
- * - `AgentRuntime` 负责保存长期状态；`AgentContext` 负责把这些状态暴露成执行接口。
- * - 这里只定义协议，不负责任何上下文装配逻辑。
+ * - `AgentContext` 是一个 class，表达"当前一次执行可见的能力面"，不是宿主状态本体。
+ * - 同一 agent 实例全程共享同一个 context；plugin、session、executor 都基于它读写状态。
  */
 
 import type { LanguageModel } from "ai";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type {
   AgentPathRuntime,
   AgentPluginConfigRuntime,
 } from "@/types/agent/AgentRuntimeAssembly.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { JsonValue } from "@/types/common/Json.js";
 import type { AgentPlugins } from "@/plugin/types/Plugin.js";
+import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type {
   SessionMetadataV1,
   SessionMessageV1,
@@ -30,6 +27,7 @@ import type {
 } from "@/executor/types/SessionRun.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,
@@ -96,9 +94,10 @@ export interface SessionExecutorPort {
    * 请求取消当前正在执行的 turn。
    *
    * 关键点（中文）
-   * - 对普通本地 runtime 可不实现。
-   * - ACP runtime 可借此向远端发送 `session/cancel`。
+   * - 返回 `true` 表示已发出取消请求。
+   * - 返回 `false` 表示当前没有可取消的执行。
    */
+  stop(): boolean;
 }
 
 /**
@@ -125,6 +124,10 @@ export interface SessionPort {
    * - 返回值只有在当前输入被绑定到某个 turn 后才会兑现。
    */
   prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
+  /**
+   * 停止当前 turn，并取消尚未被吸收的排队 prompt。
+   */
+  stop(): Promise<AgentSessionStopResult>;
   /**
    * 订阅当前 session 后续产生的 future 事件。
    *
@@ -216,61 +219,145 @@ export interface SessionCollectionPort {
 }
 
 /**
- * 统一执行上下文。
+ * AgentContext 构造参数。
+ *
+ * 关键点（中文）
+ * - 装配方负责把 session / plugins 等上层依赖注入进来。
+ * - `env` 必须传入 agent 持有的 mutable 共享对象引用，不要在这里克隆。
  */
-export interface AgentContext {
-  /**
-   * 当前执行上下文对应的 agent 状态。
-   */
-  agent: AgentRuntime;
-  /**
-   * 当前命令工作目录。
-   */
+export interface AgentContextOptions {
+  /** 当前命令工作目录。 */
   cwd: string;
-  /**
-   * 当前项目根目录。
-   */
+  /** 当前项目根目录。 */
   rootPath: string;
-  /**
-   * 统一日志器。
-   */
+  /** 统一日志器。 */
   logger: Logger;
-  /**
-   * 当前运行时已解析配置。
-   */
+  /** 当前运行时已解析配置。 */
   config: DowncityConfig;
   /**
-   * 当前项目环境变量快照。
+   * 当前 agent env 共享对象引用。
+   *
+   * 关键点（中文）
+   * - 必须是 Agent 持有的同一个 mutable 引用，不要克隆后再传入。
+   * - 通过 `agent.setEnv` / `agent.patchEnv` 原地更新会被本 context 立即感知。
    */
   env: Record<string, string>;
-  /**
-   * 当前生效的 system 文本集合。
-   */
+  /** 当前生效的 system 文本集合。 */
   systems: string[];
-  /**
-   * 当前可见的路径能力集合。
-   */
+  /** 当前可见的路径能力集合。 */
   paths: AgentPathRuntime;
-  /**
-   * 当前可见的 plugin 配置持久化能力集合。
-   */
+  /** 当前可见的 plugin 配置持久化能力集合。 */
   pluginConfig: AgentPluginConfigRuntime;
+  /** 当前 agent 持有的插件实例集合。 */
+  pluginInstances: Map<string, BasePlugin>;
+  /** Session 能力入口。 */
+  session: SessionCollectionPort;
+  /** Plugin 调用入口。 */
+  plugins: AgentPlugins;
+}
+
+/**
+ * 统一执行上下文。
+ *
+ * 关键点（中文）
+ * - 字段全部 readonly，构造一次后语义稳定，避免 plugin 误改。
+ * - `env` 引用 agent 级共享 mutable 对象，`...ctx.env` / `ctx.env.FOO` 直接可用。
+ * - `invoke` 是构造期组装的 plugin 调用端口，对外仍以 `InvokePluginPort` 形态暴露。
+ */
+export class AgentContext {
+  /** 当前命令工作目录。 */
+  readonly cwd: string;
+  /** 当前项目根目录。 */
+  readonly rootPath: string;
+  /** 统一日志器。 */
+  readonly logger: Logger;
+  /** 当前运行时已解析配置。 */
+  readonly config: DowncityConfig;
+  /** 当前项目环境变量共享视图。 */
+  readonly env: Record<string, string>;
+  /** 当前生效的 system 文本集合。 */
+  readonly systems: string[];
+  /** 当前可见的路径能力集合。 */
+  readonly paths: AgentPathRuntime;
+  /** 当前可见的 plugin 配置持久化能力集合。 */
+  readonly pluginConfig: AgentPluginConfigRuntime;
+  /** 当前 agent 持有的插件实例集合。 */
+  readonly pluginInstances: Map<string, BasePlugin>;
+  /** Session 能力入口。 */
+  readonly session: SessionCollectionPort;
+  /** Plugin 调用入口。 */
+  readonly plugins: AgentPlugins;
+  /** 跨 plugin runtime 调用主入口。 */
+  readonly invoke: InvokePluginPort;
+
+  constructor(options: AgentContextOptions) {
+    this.cwd = options.cwd;
+    this.rootPath = options.rootPath;
+    this.logger = options.logger;
+    this.config = options.config;
+    this.env = options.env;
+    this.systems = options.systems;
+    this.paths = options.paths;
+    this.pluginConfig = options.pluginConfig;
+    this.pluginInstances = options.pluginInstances;
+    this.session = options.session;
+    this.plugins = options.plugins;
+    this.invoke = {
+      invoke: (params) => this.invoke_plugin_action(params),
+    };
+  }
+
   /**
-   * Session 能力入口。
+   * 读取指定 sessionId 对应的 session 端口。
    *
    * 关键点（中文）
-   * - plugin runtime 与 plugin 都通过这里访问 session 执行与持久化能力。
-   * - 内外统一使用 `sessionId` 语义。
+   * - 返回值是统一的 `SessionPort`，而不是裸 `Executor`。
+   * - 这样 HTTP / plugin runtime / chat queue / contact 等入口都能复用同一层会话装配与执行兜底。
    */
-  session: SessionCollectionPort;
+  getSession(sessionId: string): SessionPort {
+    return this.session.get(sessionId);
+  }
+
   /**
-   * 跨 plugin runtime 调用主入口。
+   * 返回当前执行中的 sessionId 列表。
    */
-  invoke: InvokePluginPort;
+  listExecutingSessionIds(): string[] {
+    return this.session.listExecutingSessionIds();
+  }
+
   /**
-   * Plugin 调用入口。
+   * 返回当前执行中的 session 数量。
    */
-  plugins: AgentPlugins;
+  getExecutingSessionCount(): number {
+    return this.session.getExecutingSessionCount();
+  }
+
+  /**
+   * 跨 plugin runtime 调用 action 的内部实现。
+   *
+   * 关键点（中文）
+   * - 统一把 `runAction` 的成功/失败结果归一化为 `InvokePluginResult`。
+   * - 这里替代了原 `createAgentContext` 工厂里的胶水匿名函数。
+   */
+  private async invoke_plugin_action(
+    params: InvokePluginParams,
+  ): Promise<InvokePluginResult> {
+    const result = await this.plugins.runAction({
+      plugin: params.plugin,
+      action: params.action,
+      ...(params.payload !== undefined ? { payload: params.payload } : {}),
+    });
+    if (!result.success) {
+      return {
+        success: false,
+        error: result.error || result.message || "plugin action failed",
+      };
+    }
+    return {
+      success: true,
+      ...(result.data !== undefined ? { data: result.data } : {}),
+    };
+  }
 }
 
 /**

package/src/types/runtime/platform/Platform.ts

@@ -27,7 +27,7 @@ export interface PlatformAgentOption {
   projectRoot: string;
 
   /**
-   * 当前 Town 托管的 Agent 进程是否存活。
+   * 当前 downcity 托管的 Agent 进程是否存活。
    */
   running: boolean;
 
@@ -62,12 +62,12 @@ export interface PlatformAgentOption {
   stoppedAt?: string;
 
   /**
-   * 当前读取到的 Town 托管进程 pid（仅 running=true 时有值）。
+   * 当前读取到的 downcity 托管进程 pid（仅 running=true 时有值）。
    */
   daemonPid?: number;
 
   /**
-   * Town 托管进程日志路径（用于排障展示）。
+   * downcity 托管进程日志路径（用于排障展示）。
    */
   logPath?: string;
 
@@ -168,7 +168,7 @@ export interface PlatformAgentDirectoryInspection {
   knownAgent: boolean;
 
   /**
-   * 若已登记，当前 Town 托管进程是否运行中。
+   * 若已登记，当前 downcity 托管进程是否运行中。
    */
   running: boolean;
 
@@ -356,7 +356,7 @@ export interface ManagedAgentRegistryEntry {
   projectRoot: string;
 
   /**
-   * registry 最近一次记录的 Town 托管进程 pid。
+   * registry 最近一次记录的 downcity 托管进程 pid。
    */
   pid: number;
 
@@ -402,7 +402,7 @@ export interface ManagedAgentRegistryV1 {
 }
 
 /**
- * `town agent list --running` 输出可复用的受管 agent 运行态视图。
+ * `downcity agent list --running` 输出可复用的受管 agent 运行态视图。
  */
 export interface ManagedAgentProcessView {
   /**
@@ -416,7 +416,7 @@ export interface ManagedAgentProcessView {
   registeredPid: number;
 
   /**
-   * 当前实际存活的 Town 托管进程 pid。
+   * 当前实际存活的 downcity 托管进程 pid。
    */
   daemonPid: number;
 
@@ -436,7 +436,7 @@ export interface ManagedAgentProcessView {
   updatedAt: string;
 
   /**
-   * Town 托管进程日志文件路径。
+   * downcity 托管进程日志文件路径。
    */
   logPath: string;
 }

package/src/types/runtime/platform/PlatformGateway.ts

@@ -106,12 +106,12 @@ export interface PlatformAgentShipPluginsConfig {
  */
 export interface PlatformAgentShipStartConfig {
   /**
-   * Town Agent HTTP gateway host。
+   * downcity Agent HTTP gateway host。
    */
   host?: unknown;
 
   /**
-   * Town Agent HTTP gateway port。
+   * downcity Agent HTTP gateway port。
    */
   port?: unknown;
 }

package/src/types/sdk/AgentSessionStop.ts

@@ -0,0 +1,39 @@
+/**
+ * Agent Session stop 类型定义。
+ *
+ * 关键点（中文）
+ * - `session.stop()` 用于停止当前正在执行的 turn。
+ * - 尚未被当前 turn 吸收的排队 prompt 会被取消，不会自动开启下一轮。
+ */
+
+/**
+ * Session stop 的最终结果。
+ */
+export interface AgentSessionStopResult {
+  /**
+   * 本次调用是否实际停止了活跃 turn 或取消了排队 prompt。
+   */
+  stopped: boolean;
+
+  /**
+   * 被停止的当前 turn 标识。
+   *
+   * 说明（中文）
+   * - 当前没有活跃 turn 时不会返回该字段。
+   * - 如果只是清空尚未启动的队列，也不会返回该字段。
+   */
+  turnId?: string;
+
+  /**
+   * 本次 stop 取消的未绑定 prompt 数量。
+   *
+   * 说明（中文）
+   * - 已经被当前 turn 吸收的 prompt 不计入这里，它们会随当前 turn 一起结束。
+   */
+  cancelledQueuedPrompts: number;
+
+  /**
+   * 本次 stop 的归因。
+   */
+  reason: "stopped" | "idle";
+}