@downcity/agent 1.1.74 → 1.1.79

package/src/rpc/server/InternalHandlers.ts

@@ -0,0 +1,230 @@
+/**
+ * RPC internal handlers。
+ *
+ * 关键点（中文）
+ * - 只处理 `internal.*` 方法。
+ * - 这些方法服务 Town 本机管理通道，不属于 RemoteAgent 的用户 SDK 面。
+ */
+
+import fs from "fs-extra";
+import { dirname } from "node:path";
+import type { SystemModelMessage } from "ai";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
+import type { RpcRequest } from "@/types/rpc/RpcProtocol.js";
+import type {
+  RpcRequestHandlerOptions,
+  RpcWriteSuccess,
+} from "@/rpc/server/ServerTypes.js";
+import {
+  getDowncityChatHistoryPath,
+  getDowncitySessionMessagesPath,
+} from "@/config/Paths.js";
+import { resolveSessionSystemMessages } from "@/executor/composer/system/default/SystemDomain.js";
+import {
+  controlPluginState,
+  listPluginStates,
+} from "@/plugin/core/PluginStateController.js";
+import { parsePluginCommandRequestBody } from "@/plugin/core/PluginCommandRequest.js";
+import { runPluginCommand } from "@/plugin/core/PluginActionRunner.js";
+
+/**
+ * 处理 internal RPC 请求。
+ */
+export async function handleInternalRpcRequest(params: {
+  /** 当前 RPC 请求。 */
+  request: RpcRequest;
+  /** handler 依赖。 */
+  options: RpcRequestHandlerOptions;
+  /** 成功帧写入函数。 */
+  write_success: RpcWriteSuccess;
+}): Promise<boolean> {
+  const { request, options, write_success } = params;
+
+  switch (request.method) {
+    case "internal.status.get": {
+      write_success(request.id, { status: "ok" });
+      return true;
+    }
+    case "internal.sessions.clear_messages": {
+      const runtime = requireAgentRuntime(options);
+      const session_id = String(request.params.sessionId || "").trim();
+      if (!session_id) throw new Error("Missing sessionId");
+      const messages_path = getDowncitySessionMessagesPath(
+        runtime.rootPath,
+        runtime.paths.agentId,
+        session_id,
+      );
+      await fs.remove(dirname(messages_path));
+      runtime.getSession(session_id).clearExecutor();
+      write_success(request.id, {
+        sessionId: session_id,
+        cleared: true,
+      });
+      return true;
+    }
+    case "internal.sessions.clear_chat_history": {
+      const runtime = requireAgentRuntime(options);
+      const session_id = String(request.params.sessionId || "").trim();
+      if (!session_id) throw new Error("Missing sessionId");
+      await fs.remove(getDowncityChatHistoryPath(runtime.rootPath, session_id));
+      write_success(request.id, {
+        sessionId: session_id,
+        cleared: true,
+      });
+      return true;
+    }
+    case "internal.sessions.resolve_system_prompt": {
+      const runtime = requireAgentRuntime(options);
+      const context = requireAgentContext(options);
+      const session_id =
+        String(request.params.sessionId || "").trim() || "consoleui-chat-main";
+      const system_messages = await resolveSessionSystemMessages({
+        projectRoot: runtime.rootPath,
+        sessionId: session_id,
+        profile: "chat",
+        staticSystemPrompts: runtime.systems,
+        context,
+      });
+      write_success(request.id, {
+        sessionId: session_id,
+        ...toSystemPromptPayload(system_messages),
+      });
+      return true;
+    }
+    case "internal.plugins.catalog": {
+      const context = requireAgentContext(options);
+      write_success(request.id, {
+        plugins: context.plugins.list(),
+      });
+      return true;
+    }
+    case "internal.plugins.list": {
+      const context = requireAgentContext(options);
+      write_success(request.id, {
+        plugins: listPluginStates({ context }),
+      });
+      return true;
+    }
+    case "internal.plugins.control": {
+      const context = requireAgentContext(options);
+      const result = await controlPluginState({
+        pluginName: request.params.pluginName,
+        action: request.params.action,
+        context,
+      });
+      write_success(request.id, result);
+      return true;
+    }
+    case "internal.plugins.command": {
+      const context = requireAgentContext(options);
+      const body = parsePluginCommandRequestBody(request.params);
+      const result = await runPluginCommand({
+        pluginName: body.pluginName,
+        command: body.command,
+        payload: body.payload,
+        schedule: body.schedule,
+        context,
+      });
+      write_success(request.id, result);
+      return true;
+    }
+    case "internal.plugins.availability": {
+      const context = requireAgentContext(options);
+      const availability = await context.plugins.availability(
+        request.params.pluginName,
+      );
+      write_success(request.id, {
+        pluginName: request.params.pluginName,
+        availability,
+      });
+      return true;
+    }
+    case "internal.plugins.action": {
+      const context = requireAgentContext(options);
+      const result = await context.plugins.runAction({
+        plugin: request.params.pluginName,
+        action: request.params.actionName,
+        payload: request.params.payload,
+      });
+      write_success(request.id, {
+        ...result,
+        pluginName: request.params.pluginName,
+        actionName: request.params.actionName,
+      });
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+
+function requireAgentContext(options: RpcRequestHandlerOptions): AgentContext {
+  const context = options.getAgentContext?.();
+  if (!context) {
+    throw new Error("Agent RPC server was started without AgentContext");
+  }
+  return context;
+}
+
+function requireAgentRuntime(options: RpcRequestHandlerOptions): AgentRuntime {
+  const runtime = options.getAgentRuntime?.();
+  if (!runtime) {
+    throw new Error("Agent RPC server was started without AgentRuntime");
+  }
+  return runtime;
+}
+
+function normalizeSystemText(input: string | null | undefined): string {
+  return String(input || "").trim();
+}
+
+function toSystemMessageText(message: SystemModelMessage): string {
+  const content = message.content as unknown;
+  if (typeof content === "string") return normalizeSystemText(content);
+  if (!Array.isArray(content)) return "";
+  const parts = content as Array<{ text?: unknown }>;
+  const texts: string[] = [];
+  for (const part of parts) {
+    if (!part || typeof part !== "object") continue;
+    const text = normalizeSystemText(String(part.text || ""));
+    if (!text) continue;
+    texts.push(text);
+  }
+  return texts.join("\n").trim();
+}
+
+/**
+ * 把 system messages 转成 Console/Town 可直接渲染的结构。
+ */
+function toSystemPromptPayload(messages: SystemModelMessage[]): {
+  sections: Array<{
+    key: string;
+    title: string;
+    items: Array<{ index: number; content: string }>;
+  }>;
+  totalMessages: number;
+  totalChars: number;
+} {
+  const items = messages
+    .map((message, index) => ({
+      index: index + 1,
+      content: toSystemMessageText(message),
+    }))
+    .filter((item) => item.content);
+  const totalChars = items.reduce(
+    (acc, item) => acc + String(item.content || "").length,
+    0,
+  );
+  return {
+    sections: [
+      {
+        key: "resolved",
+        title: "Resolved System Messages",
+        items,
+      },
+    ],
+    totalMessages: items.length,
+    totalChars,
+  };
+}

package/src/rpc/server/RequestDispatcher.ts

@@ -0,0 +1,67 @@
+/**
+ * RPC request dispatcher。
+ *
+ * 关键点（中文）
+ * - Server.ts 不直接包含业务 switch，只负责把已解析请求交给这里。
+ * - dispatcher 按命名空间分发，避免 SDK 与 Town internal 方法混在一起。
+ */
+
+import type { RpcRequest } from "@/types/rpc/RpcProtocol.js";
+import type {
+  RpcRequestHandlerOptions,
+  RpcSocketSubscription,
+  RpcWriteError,
+  RpcWriteEvent,
+  RpcWriteSuccess,
+} from "@/rpc/server/ServerTypes.js";
+import { handleSdkSessionRpcRequest } from "@/rpc/server/SdkSessionHandlers.js";
+import { handleInternalRpcRequest } from "@/rpc/server/InternalHandlers.js";
+
+/**
+ * 分发并执行单个 RPC 请求。
+ */
+export async function dispatchRpcRequest(params: {
+  /** 当前 RPC 请求。 */
+  request: RpcRequest;
+  /** handler 依赖。 */
+  options: RpcRequestHandlerOptions;
+  /** 当前 socket 的订阅表。 */
+  subscriptions: Map<string, RpcSocketSubscription>;
+  /** 成功帧写入函数。 */
+  write_success: RpcWriteSuccess;
+  /** 失败帧写入函数。 */
+  write_error: RpcWriteError;
+  /** 事件帧写入函数。 */
+  write_event: RpcWriteEvent;
+}): Promise<void> {
+  const {
+    request,
+    options,
+    subscriptions,
+    write_success,
+    write_error,
+    write_event,
+  } = params;
+
+  try {
+    const handled_by_sdk = await handleSdkSessionRpcRequest({
+      request,
+      options,
+      subscriptions,
+      write_success,
+      write_event,
+    });
+    if (handled_by_sdk) return;
+
+    const handled_by_internal = await handleInternalRpcRequest({
+      request,
+      options,
+      write_success,
+    });
+    if (handled_by_internal) return;
+
+    throw new Error(`Unsupported RPC method: ${request.method}`);
+  } catch (error) {
+    write_error(request.id, error);
+  }
+}

package/src/rpc/server/SdkSessionHandlers.ts

@@ -0,0 +1,106 @@
+/**
+ * RPC SDK session handlers。
+ *
+ * 关键点（中文）
+ * - 只处理 `sdk.sessions.*` 方法。
+ * - 这些方法是 RemoteAgent RPC transport 的稳定 SDK 面。
+ */
+
+import type { RpcRequest } from "@/types/rpc/RpcProtocol.js";
+import type {
+  RpcSocketSubscription,
+  RpcWriteEvent,
+  RpcWriteSuccess,
+  RpcRequestHandlerOptions,
+} from "@/rpc/server/ServerTypes.js";
+
+/**
+ * 处理 SDK session RPC 请求。
+ */
+export async function handleSdkSessionRpcRequest(params: {
+  /** 当前 RPC 请求。 */
+  request: RpcRequest;
+  /** handler 依赖。 */
+  options: RpcRequestHandlerOptions;
+  /** 当前 socket 的订阅表。 */
+  subscriptions: Map<string, RpcSocketSubscription>;
+  /** 成功帧写入函数。 */
+  write_success: RpcWriteSuccess;
+  /** 事件帧写入函数。 */
+  write_event: RpcWriteEvent;
+}): Promise<boolean> {
+  const { request, options, subscriptions, write_success, write_event } = params;
+
+  switch (request.method) {
+    case "sdk.sessions.list": {
+      const page = await options.sessionCollection.listSessions(request.params);
+      write_success(request.id, { page });
+      return true;
+    }
+    case "sdk.sessions.create": {
+      const session = await options.sessionCollection.createSession(request.params);
+      write_success(request.id, { session: await session.getInfo() });
+      return true;
+    }
+    case "sdk.sessions.get": {
+      const session = await options.sessionCollection.getSession(request.params.sessionId);
+      write_success(request.id, { session: await session.getInfo() });
+      return true;
+    }
+    case "sdk.sessions.prompt": {
+      const session = await options.sessionCollection.getSession(request.params.sessionId);
+      const turn = await session.prompt(request.params.input);
+      write_success(request.id, { turn: { id: turn.id } });
+      return true;
+    }
+    case "sdk.sessions.history": {
+      const session = await options.sessionCollection.getSession(request.params.sessionId);
+      const history = await session.history(request.params.input);
+      write_success(request.id, { history });
+      return true;
+    }
+    case "sdk.sessions.system": {
+      const session = await options.sessionCollection.getSession(request.params.sessionId);
+      write_success(request.id, { system: await session.system() });
+      return true;
+    }
+    case "sdk.sessions.fork": {
+      const session = await options.sessionCollection.getSession(request.params.sessionId);
+      const forked = await session.fork(request.params.messageId);
+      write_success(request.id, { session: await forked.getInfo() });
+      return true;
+    }
+    case "sdk.sessions.subscribe": {
+      const session = await options.sessionCollection.getSession(request.params.sessionId);
+      const subscription_id = [
+        request.params.sessionId,
+        Date.now(),
+        Math.random().toString(36).slice(2, 10),
+      ].join(":");
+      const unsubscribe = session.subscribe((event) => {
+        write_event({
+          type: "event",
+          subscriptionId: subscription_id,
+          event,
+        });
+      });
+      subscriptions.set(subscription_id, {
+        sessionId: request.params.sessionId,
+        unsubscribe,
+      });
+      write_success(request.id, { subscriptionId: subscription_id });
+      return true;
+    }
+    case "sdk.sessions.unsubscribe": {
+      const subscription = subscriptions.get(request.params.subscriptionId);
+      if (subscription) {
+        subscription.unsubscribe();
+        subscriptions.delete(request.params.subscriptionId);
+      }
+      write_success(request.id, { unsubscribed: true });
+      return true;
+    }
+    default:
+      return false;
+  }
+}

package/src/rpc/server/ServerTypes.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent RPC server 内部类型。
+ *
+ * 关键点（中文）
+ * - 这里描述 handler 需要的依赖，不承载 socket 生命周期。
+ * - Server.ts 负责网络，handler 负责把协议方法转成 Agent 操作。
+ */
+
+import type { AgentSessionCollection } from "@/types/agent/AgentTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
+import type { RpcEventFrame } from "@/types/rpc/RpcProtocol.js";
+
+/**
+ * RPC Server 启动参数。
+ */
+export interface RpcServerStartOptions {
+  /** RPC 服务监听端口。 */
+  port: number;
+  /** RPC 服务监听主机。 */
+  host: string;
+  /** Session 集合访问口。 */
+  sessionCollection: AgentSessionCollection;
+  /** Agent 上下文访问口。 */
+  getAgentContext?: () => AgentContext;
+  /** Agent 运行态访问口。 */
+  getAgentRuntime?: () => AgentRuntime;
+}
+
+/**
+ * RPC request handler 依赖。
+ */
+export interface RpcRequestHandlerOptions {
+  /** Session 集合访问口。 */
+  sessionCollection: AgentSessionCollection;
+  /** Agent 上下文访问口。 */
+  getAgentContext?: () => AgentContext;
+  /** Agent 运行态访问口。 */
+  getAgentRuntime?: () => AgentRuntime;
+}
+
+/**
+ * 单个 socket 上的 session 订阅。
+ */
+export interface RpcSocketSubscription {
+  /** 被订阅的 session id。 */
+  sessionId: string;
+  /** 取消订阅函数。 */
+  unsubscribe: () => void;
+}
+
+/**
+ * 写入 RPC 成功帧。
+ */
+export type RpcWriteSuccess = (id: string, data?: unknown) => void;
+
+/**
+ * 写入 RPC 失败帧。
+ */
+export type RpcWriteError = (id: string, error: unknown) => void;
+
+/**
+ * 写入 RPC 事件帧。
+ */
+export type RpcWriteEvent = (frame: RpcEventFrame) => void;

package/src/{runtime/sandbox → sandbox}/MacOsSeatbeltSandbox.ts

@@ -13,7 +13,7 @@ import fs from "fs-extra";
 import type {
   SandboxSpawnParams,
   SandboxSpawnResult,
-} from "@/runtime/sandbox/types/SandboxRuntime.js";
+} from "@/sandbox/types/SandboxRuntime.js";
 
 const DEFAULT_PATH_VALUE =
   "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";

package/src/{runtime/sandbox → sandbox}/SandboxConfigResolver.ts

@@ -9,7 +9,7 @@
 
 import path from "node:path";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { ResolvedSandboxConfig } from "@/runtime/sandbox/types/SandboxRuntime.js";
+import type { ResolvedSandboxConfig } from "@/sandbox/types/SandboxRuntime.js";
 
 const DEFAULT_ENV_ALLOWLIST = [
   "PATH",

package/src/{runtime/sandbox → sandbox}/SandboxRunner.ts

@@ -8,9 +8,9 @@
  */
 
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { SandboxSpawnResult } from "@/runtime/sandbox/types/SandboxRuntime.js";
-import { resolveSandboxConfig, resolveSandboxCwd } from "@/runtime/sandbox/SandboxConfigResolver.js";
-import { spawnMacOsSeatbeltSandbox } from "@/runtime/sandbox/MacOsSeatbeltSandbox.js";
+import type { SandboxSpawnResult } from "@/sandbox/types/SandboxRuntime.js";
+import { resolveSandboxConfig, resolveSandboxCwd } from "@/sandbox/SandboxConfigResolver.js";
+import { spawnMacOsSeatbeltSandbox } from "@/sandbox/MacOsSeatbeltSandbox.js";
 
 /**
  * 启动 shell 子进程。

package/src/{runtime/sandbox → sandbox}/types/SandboxRuntime.ts

@@ -8,8 +8,8 @@
  */
 
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import type { SandboxConfig } from "@/runtime/sandbox/types/Sandbox.js";
-import type { SandboxNetworkMode } from "@/runtime/sandbox/types/Sandbox.js";
+import type { SandboxConfig } from "@/sandbox/types/Sandbox.js";
+import type { SandboxNetworkMode } from "@/sandbox/types/Sandbox.js";
 
 /**
  * sandbox 会话状态。

package/src/session/Session.ts

@@ -40,6 +40,7 @@ import {
 import {
   getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
+  getSdkAgentSessionInflightPath,
 } from "@/session/index.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import {
@@ -187,6 +188,11 @@ export class Session implements AgentSession {
           this.agentId,
           this.id,
         ),
+        inflightFilePath: getSdkAgentSessionInflightPath(
+          this.projectRoot,
+          this.agentId,
+          this.id,
+        ),
       },
     });
     this.historyComposer = new JsonlSessionHistoryComposer({

package/src/session/browse/Browse.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 统一负责 session 列表摘要、session 详情与 history 分页的投影逻辑。
  * - session title 允许为空；浏览层不会再从首条 user message 推导 fallback title。
- * - 面向 SDK / RemoteAgent / HTTP route 复用，避免在多个入口重复拼列表与分页语义。
+ * - 面向 SDK / RemoteAgent / Town gateway route 复用，避免在多个入口重复拼列表与分页语义。
  * - 这里不持有运行态状态；执行状态等动态信息通过调用参数显式注入。
  */
 
@@ -322,20 +322,39 @@ export function toSessionTimelineEvents(
 export async function loadSessionMessagesFromPath(
   filePath: string,
 ): Promise<SessionMessageV1[]> {
-  if (!(await fs.pathExists(filePath))) return [];
-  const raw = await fs.readFile(filePath, "utf-8");
-  const lines = raw.split("\n").filter(Boolean);
   const messages: SessionMessageV1[] = [];
-  for (const line of lines) {
+  if (await fs.pathExists(filePath)) {
+    const raw = await fs.readFile(filePath, "utf-8");
+    const lines = raw.split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        const parsed = JSON.parse(line) as SessionMessageV1;
+        if (!parsed || typeof parsed !== "object") continue;
+        if (parsed.role !== "user" && parsed.role !== "assistant") continue;
+        messages.push(parsed);
+      } catch {
+        // 关键点（中文）：单行损坏不影响整个 session 的可读性。
+      }
+    }
+  }
+
+  const inflight_path = filePath.replace(/messages\.jsonl$/, "inflight.json");
+  if (await fs.pathExists(inflight_path)) {
     try {
-      const parsed = JSON.parse(line) as SessionMessageV1;
-      if (!parsed || typeof parsed !== "object") continue;
-      if (parsed.role !== "user" && parsed.role !== "assistant") continue;
-      messages.push(parsed);
+      const parsed = (await fs.readJson(inflight_path)) as SessionMessageV1;
+      if (
+        parsed &&
+        typeof parsed === "object" &&
+        parsed.role === "assistant" &&
+        Array.isArray(parsed.parts)
+      ) {
+        messages.push(parsed);
+      }
     } catch {
-      // 关键点（中文）：单行损坏不影响整个 session 的可读性。
+      // ignore invalid inflight snapshot
     }
   }
+
   return messages;
 }
 

package/src/session/index.ts

@@ -12,6 +12,7 @@ export {
   getSdkAgentDirPath,
   getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
+  getSdkAgentSessionInflightPath,
   getSdkAgentSessionMessagesDirPath,
   getSdkAgentSessionMessagesPath,
   getSdkAgentSessionMetaPath,

package/src/session/storage/Paths.ts

@@ -114,3 +114,22 @@ export function getSdkAgentSessionArchiveDirPath(
     "archive",
   );
 }
+
+/**
+ * 单个 session 的 inflight assistant 路径。
+ *
+ * 关键点（中文）
+ * - 运行中的 assistant 只保留一份增量快照。
+ * - step / tool 过程会持续重写这个文件，避免中途中断后过程完全丢失。
+ * - 完成后再把最终 assistant 合并进 `messages.jsonl`，并清理该文件。
+ */
+export function getSdkAgentSessionInflightPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId),
+    "inflight.json",
+  );
+}