@downcity/agent 1.1.129 → 1.1.148

package/src/agent/remote/transports/HttpRemoteAgentTransport.ts

@@ -2,19 +2,25 @@
  * RemoteAgent HTTP transport。
  *
  * 关键点（中文）
- * - 只适配 Town Agent HTTP gateway 的 SDK routes。
+ * - 只适配 downcity Agent HTTP gateway 的 SDK routes。
  * - 不处理 RemoteSession 的 turn lifecycle，避免 transport 与 actor 逻辑混在一起。
  */
 
 import type {
   AgentCreateSessionInput,
   AgentListSessionsInput,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
   AgentSessionForkInput,
   AgentSessionHistoryInput,
   AgentSessionHistoryPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
+  AgentSessionStopResult,
   RemoteAgentPluginActionInput,
   RemoteAgentPluginActionResult,
 } from "@/types/agent/AgentTypes.js";
@@ -39,7 +45,7 @@ type SdkEventsReadyFrame = {
 };
 
 /**
- * Town HTTP gateway transport。
+ * downcity HTTP gateway transport。
  */
 export class HttpRemoteAgentTransport implements RemoteAgentTransport {
   private readonly base_url: string;
@@ -118,6 +124,23 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     return { id };
   }
 
+  async stop(session_id: string): Promise<AgentSessionStopResult> {
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      result?: AgentSessionStopResult;
+    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/stop`, {
+      method: "POST",
+      headers: this.headers({
+        "Content-Type": "application/json",
+      }),
+    });
+    if (!payload.success || !payload.result) {
+      throw new Error(String(payload.error || "Remote session stop failed"));
+    }
+    return payload.result;
+  }
+
   async subscribe(params: {
     session_id: string;
     on_ready: () => void;
@@ -250,6 +273,81 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     return payload.page;
   }
 
+  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 payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      sessionId?: string;
+      archivedAt?: number;
+    }>(
+      `${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/archive`,
+      {
+        method: "POST",
+        headers: this.headers({
+          "Content-Type": "application/json",
+        }),
+      },
+    );
+    if (!payload.success || !payload.sessionId) {
+      throw new Error(String(payload.error || "Remote session archive failed"));
+    }
+    return {
+      sessionId: payload.sessionId,
+      archivedAt:
+        typeof payload.archivedAt === "number" && Number.isFinite(payload.archivedAt)
+          ? payload.archivedAt
+          : Date.now(),
+    };
+  }
+
+  async archive_sessions(
+    input?: AgentArchiveSessionsInput,
+  ): Promise<AgentArchiveSessionsResult> {
+    const query = new URLSearchParams();
+    if (input?.limit !== undefined) query.set("limit", String(input.limit));
+    if (input?.cursor) query.set("cursor", input.cursor);
+    if (input?.query) query.set("query", input.query);
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      page?: AgentArchiveSessionsResult;
+    }>(
+      `${this.base_url}/api/sdk/archived-sessions${query.size > 0 ? `?${query.toString()}` : ""}`,
+      {
+        headers: this.headers(),
+      },
+    );
+    if (!payload.success || !payload.page) {
+      throw new Error(String(payload.error || "Remote archived sessions list failed"));
+    }
+    return payload.page;
+  }
+
+  async clean_archive(): Promise<AgentCleanArchiveResult> {
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      removedSessionIds?: string[];
+    }>(`${this.base_url}/api/sdk/archived-sessions`, {
+      method: "DELETE",
+      headers: this.headers(),
+    });
+    if (!payload.success) {
+      throw new Error(String(payload.error || "Remote clean archive failed"));
+    }
+    return {
+      removedSessionIds: Array.isArray(payload.removedSessionIds)
+        ? payload.removedSessionIds
+        : [],
+    };
+  }
+
   async run_plugin_action(
     input: RemoteAgentPluginActionInput,
   ): Promise<RemoteAgentPluginActionResult> {

package/src/agent/remote/transports/RpcRemoteAgentTransport.ts

@@ -9,12 +9,18 @@
 import type {
   AgentCreateSessionInput,
   AgentListSessionsInput,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
   AgentSessionForkInput,
   AgentSessionHistoryInput,
   AgentSessionHistoryPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
+  AgentSessionStopResult,
   RemoteAgentPluginActionInput,
   RemoteAgentPluginActionResult,
 } from "@/types/agent/AgentTypes.js";
@@ -62,6 +68,10 @@ export class RpcRemoteAgentTransport implements RemoteAgentTransport {
     });
   }
 
+  async stop(session_id: string): Promise<AgentSessionStopResult> {
+    return await this.client.stop_session(session_id);
+  }
+
   async subscribe(params: {
     session_id: string;
     on_ready: () => void;
@@ -111,6 +121,22 @@ export class RpcRemoteAgentTransport implements RemoteAgentTransport {
     return await this.client.list_sessions(input);
   }
 
+  async archive_session(
+    input: AgentArchiveSessionInput,
+  ): Promise<AgentArchiveSessionResult> {
+    return await this.client.archive_session(input);
+  }
+
+  async archive_sessions(
+    input?: AgentArchiveSessionsInput,
+  ): Promise<AgentArchiveSessionsResult> {
+    return await this.client.archive_sessions(input);
+  }
+
+  async clean_archive(): Promise<AgentCleanArchiveResult> {
+    return await this.client.clean_archive();
+  }
+
   async run_plugin_action(
     input: RemoteAgentPluginActionInput,
   ): Promise<RemoteAgentPluginActionResult> {

package/src/config/AgentInitializer.ts

@@ -2,12 +2,12 @@
  * Agent 项目初始化模块。
  *
  * 职责说明（中文）
- * - CLI `town agent create` 与 Console 共用同一套初始化逻辑，避免模板与目录结构分叉。
+ * - CLI `downcity agent create` 与 Console 共用同一套初始化逻辑，避免模板与目录结构分叉。
  * - 负责创建项目骨架、静态 prompt、默认 `downcity.json`、基础目录与 schema 文件。
  * - 负责把用户在创建阶段提供的最小执行配置与渠道配置写入项目。
  *
  * 边界说明（中文）
- * - 这里只处理“初始化一个新项目”所需的静态文件与目录，不处理 Town 托管进程启停。
+ * - 这里只处理“初始化一个新项目”所需的静态文件与目录，不处理 downcity 托管进程启停。
  * - 这里只校验项目创建阶段依赖的最小平台条件，不承担后续运行时配置合并职责。
  */
 

package/src/executor/Executor.ts

@@ -109,6 +109,7 @@ export class Executor implements SessionExecutor {
   private readonly core_engine_runner: CoreEngineRunner;
 
   private executing = false;
+  private abort_controller: AbortController | null = null;
 
   constructor(options: ExecutorOptions) {
     const sessionId = String(options.sessionId || "").trim();
@@ -162,6 +163,17 @@ export class Executor implements SessionExecutor {
     return this.executing;
   }
 
+  /**
+   * 请求停止当前执行。
+   */
+  stop(): boolean {
+    if (!this.executing || !this.abort_controller) return false;
+    if (!this.abort_controller.signal.aborted) {
+      this.abort_controller.abort(new Error("Turn stopped"));
+    }
+    return true;
+  }
+
   /**
    * 获取当前 session 的 history 事实源。
    */
@@ -260,6 +272,22 @@ export class Executor implements SessionExecutor {
     };
     run_context.onAssistantStepCallback = wrappedOnAssistantStepCallback;
 
+    const upstream_abort_signal = run_context.abortSignal;
+    const abort_controller = new AbortController();
+    const abort_from_upstream = () => {
+      if (!abort_controller.signal.aborted) {
+        abort_controller.abort(upstream_abort_signal?.reason);
+      }
+    };
+    if (upstream_abort_signal?.aborted) {
+      abort_from_upstream();
+    } else {
+      upstream_abort_signal?.addEventListener("abort", abort_from_upstream, {
+        once: true,
+      });
+    }
+    this.abort_controller = abort_controller;
+    run_context.abortSignal = abort_controller.signal;
     this.executing = true;
     this.recovery_policy.reset_run_state();
     try {
@@ -308,6 +336,10 @@ export class Executor implements SessionExecutor {
       return result;
     } finally {
       this.recovery_policy.reset_run_state();
+      if (this.abort_controller === abort_controller) {
+        this.abort_controller = null;
+      }
+      upstream_abort_signal?.removeEventListener("abort", abort_from_upstream);
       this.executing = false;
     }
   }
@@ -397,6 +429,7 @@ export class Executor implements SessionExecutor {
       ...(typeof input?.onUiMessageChunkCallback === "function"
         ? { onUiMessageChunkCallback: input.onUiMessageChunkCallback }
         : {}),
+      ...(input?.abortSignal ? { abortSignal: input.abortSignal } : {}),
       injectedUserMessages: Array.isArray(input?.injectedUserMessages)
         ? [...input.injectedUserMessages]
         : [],

package/src/executor/composer/system/default/InitPrompts.ts

@@ -1,5 +1,5 @@
 /**
- * InitPrompts：`town agent create` 默认 prompt 资产加载器。
+ * InitPrompts：`downcity agent create` 默认 prompt 资产加载器。
  *
  * 职责说明（中文）
  * - 统一管理 create 生成的 `PROFILE.md` / `SOUL.md` 默认内容。

package/src/executor/composer/system/default/SystemDomain.ts

@@ -74,7 +74,7 @@ export function buildContextSystemPrompt(input: {
   const outputRules = [
     "Task-run output rules:",
     "- This is a task execution context, not an interactive chat turn.",
-    "- Do NOT send external channel messages via `town chat send` unless explicitly required by the task itself.",
+    "- Do NOT send external channel messages via `downcity chat send` unless explicitly required by the task itself.",
     "- Reply with result-oriented content; do NOT paste raw tool outputs or JSON logs.",
     "- Keep output compact and avoid unnecessary conversational fillers.",
   ].join("\n");
@@ -173,7 +173,7 @@ export async function loadManagedPluginSystemPrompts(input: {
       .filter(Boolean),
   );
 
-  for (const plugin of input.context.agent.pluginInstances.values()) {
+  for (const plugin of input.context.pluginInstances.values()) {
     if (disabledPluginNames.has(plugin.name)) continue;
     if (typeof plugin.system !== "function") continue;
     try {

package/src/executor/core-engine/CoreEngineRunner.ts

@@ -43,6 +43,8 @@ import type {
 } from "@/executor/types/SessionRun.js";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 
+const TURN_STOPPED_MESSAGE = "Turn stopped";
+
 /**
  * 生成 file part 去重 key。
  */
@@ -200,6 +202,7 @@ export class CoreEngineRunner {
           prepareStep: prepare_step,
           messages: message_state.modelMessages,
           tools,
+          abortSignal: input.run_context.abortSignal,
           providerOptions: buildOpenAIResponsesProviderOptions(),
           onError: async ({ error }) => {
             last_observed_stream_error = error;
@@ -405,6 +408,24 @@ export class CoreEngineRunner {
         ],
       };
     } catch (error) {
+      if (input.run_context.abortSignal?.aborted) {
+        const error_text = TURN_STOPPED_MESSAGE;
+        await this.logger.log("info", "[agent] stopped", {
+          sessionId: session_id,
+        });
+        return {
+          success: false,
+          error: error_text,
+          assistantMessage: this.context_composer.buildFallbackAssistantMessage(
+            error_text,
+            input.run_context,
+          ),
+          deferredPersistedUserMessages: [
+            ...input.run_context.deferredPersistedUserMessages,
+          ],
+        };
+      }
+
       if (this.should_compact_on_error(error)) {
         throw error;
       }

package/src/executor/messages/ChatMessageMarkupTypes.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 统一描述 chat plugin runtime 中可见的消息协议：frontmatter metadata + `<file>` 标签。
- * - direct 模式、`town chat send`、入站附件注入、渠道出站解析都应复用本类型。
+ * - direct 模式、`downcity chat send`、入站附件注入、渠道出站解析都应复用本类型。
  */
 
 /**

package/src/executor/store/history/jsonl/JsonlSessionHistoryStore.ts

@@ -493,6 +493,28 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     });
   }
 
+  /**
+   * 批量追加消息。
+   *
+   * 关键点（中文）
+   * - 一次锁、一次 IO，适合 fork 等需要拷贝整段历史的场景。
+   * - 不处理 inflight，调用方需自行确保历史已经收口。
+   */
+  async appendMany(messages: SessionMessageV1[]): Promise<void> {
+    if (!Array.isArray(messages) || messages.length === 0) return;
+    const normalized_list = messages
+      .map((message) => this.normalizePersistedMessage(message))
+      .filter((message): message is SessionMessageV1 => message !== null);
+    if (normalized_list.length === 0) return;
+
+    const payload = normalized_list
+      .map((message) => `${JSON.stringify(message)}\n`)
+      .join("");
+    await this.withWriteLock(async () => {
+      await fs.appendFile(this.getMessagesFilePath(), payload, "utf8");
+    });
+  }
+
   async readInflight(): Promise<SessionMessageV1 | null> {
     await this.ensureLayout();
     return this.readInflightUnsafe();

package/src/executor/types/SessionExecutor.ts

@@ -21,9 +21,10 @@ export interface SessionExecutor {
    * 请求取消当前正在执行的 turn。
    *
    * 关键点（中文）
-   * - 主要给 ACP 执行器使用，对应协议侧 `session/cancel`。
+   * - `session.stop()` 会调用这里终止当前模型流与 tool-loop。
    * - 返回 `true` 表示本次请求已发出；`false` 表示当前没有可取消的 turn。
    */
+  stop(): boolean;
 
   /**
    * 释放执行器持有的资源。

package/src/index.ts

@@ -17,6 +17,11 @@ export {
   normalizeAgentModel,
 } from "./model/CityModelAdapter.js";
 export type {
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
   AgentSessionCollection,
   AgentModel,
   AgentManagedSession,
@@ -26,11 +31,6 @@ export type {
   AgentCreateSessionInput,
   AgentListSessionsInput,
   AgentOptions,
-  AgentRpcBinding,
-  AgentRpcStartOptions,
-  AgentStartOptions,
-  AgentStartResult,
-  AgentStopResult,
   RemoteAgentOptions,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
@@ -56,13 +56,14 @@ export type {
   AgentSessionUnsubscribe,
 } from "./types/sdk/AgentSessionEvent.js";
 export type { AgentSessionPromptInput } from "./types/sdk/AgentSessionPrompt.js";
+export type { AgentSessionStopResult } from "./types/sdk/AgentSessionStop.js";
 export type {
   AgentSessionTurnHandle,
   AgentSessionTurnResult,
 } from "./types/sdk/AgentSessionTurn.js";
-export type { AgentRuntime, AgentRuntimeBase } from "./types/runtime/agent/AgentRuntime.js";
+export { AgentContext } from "./types/runtime/agent/AgentContext.js";
 export type {
-  AgentContext,
+  AgentContextOptions,
   InvokePluginPort,
   SessionCollectionPort,
   SessionPort,
@@ -130,9 +131,6 @@ export {
   registerPluginActionCommandsForCli,
 } from "./plugin/core/PluginCommand.js";
 
-// Agent RPC 集成
-export { startRpcServer } from "./rpc/Server.js";
-
 // Runtime plugin 运行集成
 export {
   startAllPlugins,

package/src/plugin/core/Activation.ts

@@ -9,7 +9,6 @@
 import { readProjectPluginEnabled } from "@/plugin/core/ProjectConfigStore.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { AgentRuntimeBase } from "@/types/runtime/agent/AgentRuntime.js";
 
 /**
  * 读取当前项目配置下的 plugin 启用态。
@@ -17,12 +16,11 @@ import type { AgentRuntimeBase } from "@/types/runtime/agent/AgentRuntime.js";
 export function isPluginEnabled(params: {
   plugin: Plugin;
   context?: Pick<AgentContext, "config">;
-  runtime?: Pick<AgentRuntimeBase, "config">;
 }): boolean {
   const pluginName = String(params.plugin.name || "").trim();
   if (!pluginName) return false;
   return readProjectPluginEnabled({
     pluginName,
-    config: params.context?.config || params.runtime?.config,
+    config: params.context?.config,
   });
 }

package/src/plugin/core/PluginCommandRequest.ts

@@ -2,7 +2,7 @@
  * PluginCommandRequest：统一 plugin runtime command 请求解析模块。
  *
  * 关键点（中文）
- * - 统一收口 Town gateway command 入口的请求体解析。
+ * - 统一收口 downcity gateway command 入口的请求体解析。
  * - plugin runtime 远程调用统一走 runtime command 协议，不再让 action 自带 HTTP route。
  * - ActionSchedule 参数（`schedule` / `delay` / `time`）也在这里一次性归一化。
  */

package/src/plugin/core/PluginStateController.ts

@@ -3,7 +3,6 @@
  */
 
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type {
   PluginLifecycle,
   PluginState,
@@ -27,16 +26,11 @@ function resolveLifecycle(plugin: BasePlugin): PluginLifecycle | undefined {
  */
 export function listPluginInstances(input?: {
   context?: AgentContext;
-  runtime?: AgentRuntime;
 }): BasePlugin[] {
-  const contextPlugins = input?.context?.agent?.pluginInstances;
+  const contextPlugins = input?.context?.pluginInstances;
   if (contextPlugins instanceof Map && contextPlugins.size > 0) {
     return [...contextPlugins.values()];
   }
-  const runtimePlugins = input?.runtime?.pluginInstances;
-  if (runtimePlugins instanceof Map && runtimePlugins.size > 0) {
-    return [...runtimePlugins.values()];
-  }
   return [];
 }
 
@@ -47,7 +41,6 @@ export function resolvePluginByName(
   name: string,
   input?: {
     context?: AgentContext;
-    runtime?: AgentRuntime;
   },
 ): BasePlugin | null {
   const key = String(name || "").trim();
@@ -136,7 +129,6 @@ export function markPluginCommand(
  */
 export function listPluginStates(input?: {
   context?: AgentContext;
-  runtime?: AgentRuntime;
 }): PluginStateSnapshot[] {
   return listPluginInstances(input)
     .map((plugin) =>
@@ -152,7 +144,6 @@ export function isPluginRunning(
   pluginName: string,
   input?: {
     context?: AgentContext;
-    runtime?: AgentRuntime;
   },
 ): boolean {
   const plugin = resolvePluginByName(pluginName, input);

package/src/plugin/types/PluginApi.ts

@@ -2,7 +2,7 @@
  * plugin catalog / availability / action API 类型。
  *
  * 关键点（中文）
- * - 统一描述 Town CLI -> Agent runtime 的 plugin 管理协议。
+ * - 统一描述 downcity CLI -> Agent runtime 的 plugin 管理协议。
  * - 当前阶段支持 list / availability / action 三类调用。
  */
 

package/src/rpc/Client.ts

@@ -11,9 +11,15 @@ import net from "node:net";
 import type {
   AgentCreateSessionInput,
   AgentListSessionsInput,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
   AgentSessionHistoryInput,
   AgentSessionHistoryPage,
   AgentSessionInfo,
+  AgentSessionStopResult,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/AgentTypes.js";
@@ -104,6 +110,48 @@ export class RpcClient {
     return data.session;
   }
 
+  /**
+   * 归档远程 session。
+   */
+  async archive_session(
+    input: AgentArchiveSessionInput,
+  ): Promise<AgentArchiveSessionResult> {
+    const data = await this.request<{ result: AgentArchiveSessionResult }>({
+      method: "sdk.sessions.archive",
+      params: {
+        sessionId: input.id,
+      },
+    });
+    return data.result;
+  }
+
+  /**
+   * 列出远程已归档 session。
+   */
+  async archive_sessions(
+    input?: AgentArchiveSessionsInput,
+  ): Promise<AgentArchiveSessionsResult> {
+    const data = await this.request<{ page: AgentArchiveSessionsResult }>({
+      method: "sdk.sessions.archived.list",
+      params: input,
+    });
+    return data.page;
+  }
+
+  /**
+   * 清空远程已归档 session。
+   */
+  async clean_archive(): Promise<AgentCleanArchiveResult> {
+    const data = await this.request<{ removedSessionIds: string[] }>({
+      method: "sdk.sessions.archived.clean",
+    });
+    return {
+      removedSessionIds: Array.isArray(data.removedSessionIds)
+        ? data.removedSessionIds
+        : [],
+    };
+  }
+
   /**
    * 获取远程 session 信息。
    */
@@ -134,6 +182,19 @@ export class RpcClient {
     return data.turn;
   }
 
+  /**
+   * 停止远程 session 当前 turn。
+   */
+  async stop_session(session_id: string): Promise<AgentSessionStopResult> {
+    const data = await this.request<{ result: AgentSessionStopResult }>({
+      method: "sdk.sessions.stop",
+      params: {
+        sessionId: session_id,
+      },
+    });
+    return data.result;
+  }
+
   /**
    * 读取 history。
    */

package/src/session/Session.ts

@@ -36,6 +36,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 { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
 import { SessionStateService } from "@/session/services/SessionStateService.js";
@@ -189,6 +190,13 @@ export class Session implements AgentSession {
     return await this.turnService.prompt(input);
   }
 
+  /**
+   * 停止当前 turn，并取消尚未被吸收的排队 prompt。
+   */
+  async stop(): Promise<AgentSessionStopResult> {
+    return await this.turnService.stop();
+  }
+
   /**
    * 订阅当前 Session 的未来事件。
    */
@@ -269,6 +277,7 @@ export class Session implements AgentSession {
       sessionId: this.id,
       getExecutor: () => this.executor.getExecutor(),
       prompt: async (input) => await this.prompt(input),
+      stop: async () => await this.stop(),
       subscribe: (subscriber) => this.subscribe(subscriber),
       publishEvent: (event) => {
         this.eventHub.publish(event);