@downcity/agent 1.1.135 → 1.1.148

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,17 +3,12 @@
  *
  * 职责说明（中文）
  * - 这里定义 plugin runtime、plugin、prompt system 共用的统一执行上下文。
- * - `AgentContext` 是一个 class，表达“当前一次执行可见的能力面”，不是宿主状态本体。
+ * - `AgentContext` 是一个 class，表达"当前一次执行可见的能力面"，不是宿主状态本体。
  * - 同一 agent 实例全程共享同一个 context；plugin、session、executor 都基于它读写状态。
- *
- * 边界说明（中文）
- * - `AgentRuntime` 负责保存长期状态；`AgentContext` 负责把这些状态暴露成执行接口。
- * - 这里同时声明类型协议与默认实现；plugin 作者拿到的就是这个 class 的实例。
  */
 
 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,
@@ -21,6 +16,7 @@ import type {
 import type { DowncityConfig } from "@/types/config/DowncityConfig.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,
@@ -31,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,
@@ -97,9 +94,10 @@ export interface SessionExecutorPort {
    * 请求取消当前正在执行的 turn。
    *
    * 关键点（中文）
-   * - 对普通本地 runtime 可不实现。
-   * - ACP runtime 可借此向远端发送 `session/cancel`。
+   * - 返回 `true` 表示已发出取消请求。
+   * - 返回 `false` 表示当前没有可取消的执行。
    */
+  stop(): boolean;
 }
 
 /**
@@ -126,6 +124,10 @@ export interface SessionPort {
    * - 返回值只有在当前输入被绑定到某个 turn 后才会兑现。
    */
   prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
+  /**
+   * 停止当前 turn，并取消尚未被吸收的排队 prompt。
+   */
+  stop(): Promise<AgentSessionStopResult>;
   /**
    * 订阅当前 session 后续产生的 future 事件。
    *
@@ -220,12 +222,10 @@ export interface SessionCollectionPort {
  * AgentContext 构造参数。
  *
  * 关键点（中文）
- * - 装配方负责把 runtime / session / plugins 等上层依赖注入进来。
+ * - 装配方负责把 session / plugins 等上层依赖注入进来。
  * - `env` 必须传入 agent 持有的 mutable 共享对象引用，不要在这里克隆。
  */
 export interface AgentContextOptions {
-  /** 当前执行上下文对应的 agent 状态。 */
-  agent: AgentRuntime;
   /** 当前命令工作目录。 */
   cwd: string;
   /** 当前项目根目录。 */
@@ -248,6 +248,8 @@ export interface AgentContextOptions {
   paths: AgentPathRuntime;
   /** 当前可见的 plugin 配置持久化能力集合。 */
   pluginConfig: AgentPluginConfigRuntime;
+  /** 当前 agent 持有的插件实例集合。 */
+  pluginInstances: Map<string, BasePlugin>;
   /** Session 能力入口。 */
   session: SessionCollectionPort;
   /** Plugin 调用入口。 */
@@ -263,8 +265,6 @@ export interface AgentContextOptions {
  * - `invoke` 是构造期组装的 plugin 调用端口，对外仍以 `InvokePluginPort` 形态暴露。
  */
 export class AgentContext {
-  /** 当前执行上下文对应的 agent 状态。 */
-  readonly agent: AgentRuntime;
   /** 当前命令工作目录。 */
   readonly cwd: string;
   /** 当前项目根目录。 */
@@ -281,6 +281,8 @@ export class AgentContext {
   readonly paths: AgentPathRuntime;
   /** 当前可见的 plugin 配置持久化能力集合。 */
   readonly pluginConfig: AgentPluginConfigRuntime;
+  /** 当前 agent 持有的插件实例集合。 */
+  readonly pluginInstances: Map<string, BasePlugin>;
   /** Session 能力入口。 */
   readonly session: SessionCollectionPort;
   /** Plugin 调用入口。 */
@@ -289,7 +291,6 @@ export class AgentContext {
   readonly invoke: InvokePluginPort;
 
   constructor(options: AgentContextOptions) {
-    this.agent = options.agent;
     this.cwd = options.cwd;
     this.rootPath = options.rootPath;
     this.logger = options.logger;
@@ -298,6 +299,7 @@ export class AgentContext {
     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 = {
@@ -305,6 +307,31 @@ export class AgentContext {
     };
   }
 
+  /**
+   * 读取指定 sessionId 对应的 session 端口。
+   *
+   * 关键点（中文）
+   * - 返回值是统一的 `SessionPort`，而不是裸 `Executor`。
+   * - 这样 HTTP / plugin runtime / chat queue / contact 等入口都能复用同一层会话装配与执行兜底。
+   */
+  getSession(sessionId: string): SessionPort {
+    return this.session.get(sessionId);
+  }
+
+  /**
+   * 返回当前执行中的 sessionId 列表。
+   */
+  listExecutingSessionIds(): string[] {
+    return this.session.listExecutingSessionIds();
+  }
+
+  /**
+   * 返回当前执行中的 session 数量。
+   */
+  getExecutingSessionCount(): number {
+    return this.session.getExecutingSessionCount();
+  }
+
   /**
    * 跨 plugin runtime 调用 action 的内部实现。
    *

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";
+}