@downcity/agent 1.1.66 → 1.1.69

package/src/agent/RemoteAgent.ts

@@ -115,6 +115,10 @@ type RemoteAgentTransport = RemoteSessionTransport & {
    * 列出 sessions。
    */
   list_sessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
+  /**
+   * 关闭 transport 持有的长期连接。
+   */
+  close?(): Promise<void>;
 };
 
 type SdkEventsReadyFrame = {
@@ -336,7 +340,7 @@ export class RemoteAgent {
     if (!url) {
       throw new Error("RemoteAgent requires a non-empty url");
     }
-    this.transport = create_remote_agent_transport(url);
+    this.transport = create_remote_agent_transport(url, options.token);
   }
 
   /**
@@ -369,13 +373,34 @@ export class RemoteAgent {
   ): Promise<AgentSessionSummaryPage> {
     return await this.transport.list_sessions(input);
   }
+
+  /**
+   * 关闭远程 transport。
+   *
+   * 关键点（中文）
+   * - `rpc://` 会关闭底层长连接。
+   * - `http://` / `https://` 没有常驻连接，调用时是安全 no-op。
+   */
+  async close(): Promise<void> {
+    await this.transport.close?.();
+  }
 }
 
 class HttpRemoteAgentTransport implements RemoteAgentTransport {
   private readonly base_url: string;
+  private readonly token: string;
 
-  constructor(url: string) {
+  constructor(url: string, token?: string) {
     this.base_url = url.replace(/\/+$/, "");
+    this.token = String(token || "").trim();
+  }
+
+  private headers(input?: Record<string, string>): Headers {
+    const headers = new Headers(input);
+    if (this.token) {
+      headers.set("Authorization", `Bearer ${this.token}`);
+    }
+    return headers;
   }
 
   async create_session(input?: AgentCreateSessionInput): Promise<AgentSessionInfo> {
@@ -385,9 +410,9 @@ class HttpRemoteAgentTransport implements RemoteAgentTransport {
       session?: AgentSessionInfo;
     }>(`${this.base_url}/api/sdk/sessions`, {
       method: "POST",
-      headers: {
+      headers: this.headers({
         "Content-Type": "application/json",
-      },
+      }),
       body: JSON.stringify({
         ...(input?.sessionId ? { sessionId: input.sessionId } : {}),
       }),
@@ -403,7 +428,9 @@ class HttpRemoteAgentTransport implements RemoteAgentTransport {
       success?: boolean;
       error?: string;
       session?: AgentSessionInfo;
-    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}`);
+    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}`, {
+      headers: this.headers(),
+    });
     if (!payload.success || !payload.session?.sessionId) {
       throw new Error(String(payload.error || "Remote session info failed"));
     }
@@ -422,9 +449,9 @@ class HttpRemoteAgentTransport implements RemoteAgentTransport {
       };
     }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/prompt`, {
       method: "POST",
-      headers: {
+      headers: this.headers({
         "Content-Type": "application/json",
-      },
+      }),
       body: JSON.stringify({
         query: input.query,
       }),
@@ -451,6 +478,7 @@ class HttpRemoteAgentTransport implements RemoteAgentTransport {
     const response = await fetch(
       `${this.base_url}/api/sdk/sessions/${encodeURIComponent(params.session_id)}/events`,
       {
+        headers: this.headers(),
         signal: abort_controller.signal,
       },
     );
@@ -495,6 +523,9 @@ class HttpRemoteAgentTransport implements RemoteAgentTransport {
       `${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/history${
         query.size > 0 ? `?${query.toString()}` : ""
       }`,
+      {
+        headers: this.headers(),
+      },
     );
     if (!payload.success || !payload.history || !Array.isArray(payload.history.items)) {
       throw new Error(String(payload.error || "Remote session history failed"));
@@ -507,7 +538,9 @@ class HttpRemoteAgentTransport implements RemoteAgentTransport {
       success?: boolean;
       error?: string;
       system?: AgentSessionSystemSnapshot;
-    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/system`);
+    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/system`, {
+      headers: this.headers(),
+    });
     if (!payload.success || !payload.system || !Array.isArray(payload.system.blocks)) {
       throw new Error(String(payload.error || "Remote session system failed"));
     }
@@ -528,9 +561,9 @@ class HttpRemoteAgentTransport implements RemoteAgentTransport {
       session?: AgentSessionInfo;
     }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/fork`, {
       method: "POST",
-      headers: {
+      headers: this.headers({
         "Content-Type": "application/json",
-      },
+      }),
       body: JSON.stringify({
         ...(message_id ? { messageId: message_id } : {}),
       }),
@@ -552,6 +585,9 @@ class HttpRemoteAgentTransport implements RemoteAgentTransport {
       page?: AgentSessionSummaryPage;
     }>(
       `${this.base_url}/api/sdk/sessions${query.size > 0 ? `?${query.toString()}` : ""}`,
+      {
+        headers: this.headers(),
+      },
     );
     if (!payload.success || !payload.page) {
       throw new Error(String(payload.error || "Remote sessions list failed"));
@@ -633,11 +669,18 @@ class RpcRemoteAgentTransport implements RemoteAgentTransport {
   async list_sessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage> {
     return await this.client.list_sessions(input);
   }
+
+  async close(): Promise<void> {
+    await this.client.close();
+  }
 }
 
-function create_remote_agent_transport(url: string): RemoteAgentTransport {
+function create_remote_agent_transport(
+  url: string,
+  token?: string,
+): RemoteAgentTransport {
   if (/^https?:\/\//i.test(url)) {
-    return new HttpRemoteAgentTransport(url);
+    return new HttpRemoteAgentTransport(url, token);
   }
   if (/^rpc:\/\//i.test(url)) {
     return new RpcRemoteAgentTransport(url);

package/src/rpc/Client.ts

@@ -17,6 +17,16 @@ import type {
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/AgentTypes.js";
+import type { JsonValue } from "@/types/common/Json.js";
+import type {
+  PluginActionResult,
+  PluginAvailability,
+  PluginCommandResult,
+  PluginStateControlAction,
+  PluginStateControlResult,
+  PluginStateSnapshot,
+  PluginView,
+} from "@/plugin/types/Plugin.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 
@@ -82,6 +92,52 @@ type RpcClientRequest =
       params: {
         subscriptionId: string;
       };
+    }
+  | {
+      id: string;
+      method: "internal.status.get";
+    }
+  | {
+      id: string;
+      method: "internal.plugins.catalog";
+    }
+  | {
+      id: string;
+      method: "internal.plugins.list";
+    }
+  | {
+      id: string;
+      method: "internal.plugins.control";
+      params: {
+        pluginName: string;
+        action: PluginStateControlAction;
+      };
+    }
+  | {
+      id: string;
+      method: "internal.plugins.command";
+      params: {
+        pluginName: string;
+        command: string;
+        payload?: JsonValue;
+        schedule?: JsonValue;
+      };
+    }
+  | {
+      id: string;
+      method: "internal.plugins.availability";
+      params: {
+        pluginName: string;
+      };
+    }
+  | {
+      id: string;
+      method: "internal.plugins.action";
+      params: {
+        pluginName: string;
+        actionName: string;
+        payload?: JsonValue;
+      };
     };
 
 type RpcResponseFrame = {
@@ -288,6 +344,112 @@ export class RpcClient {
     };
   }
 
+  /**
+   * 读取 Agent 内部状态。
+   */
+  async get_internal_status(): Promise<{ status: string }> {
+    return await this.request<{ status: string }>({
+      method: "internal.status.get",
+    });
+  }
+
+  /**
+   * 列出 Agent runtime 注册的 plugin catalog。
+   */
+  async list_internal_plugin_catalog(): Promise<PluginView[]> {
+    const data = await this.request<{ plugins: PluginView[] }>({
+      method: "internal.plugins.catalog",
+    });
+    return Array.isArray(data.plugins) ? data.plugins : [];
+  }
+
+  /**
+   * 列出 Agent runtime 内 plugin 状态。
+   */
+  async list_internal_plugin_states(): Promise<PluginStateSnapshot[]> {
+    const data = await this.request<{ plugins: PluginStateSnapshot[] }>({
+      method: "internal.plugins.list",
+    });
+    return Array.isArray(data.plugins) ? data.plugins : [];
+  }
+
+  /**
+   * 控制 Agent runtime 内 plugin 生命周期。
+   */
+  async control_internal_plugin(params: {
+    plugin_name: string;
+    action: PluginStateControlAction;
+  }): Promise<PluginStateControlResult> {
+    return await this.request<PluginStateControlResult>({
+      method: "internal.plugins.control",
+      params: {
+        pluginName: params.plugin_name,
+        action: params.action,
+      },
+    });
+  }
+
+  /**
+   * 执行 Agent runtime 内 plugin command。
+   */
+  async run_internal_plugin_command(params: {
+    plugin_name: string;
+    command: string;
+    payload?: JsonValue;
+    schedule?: JsonValue;
+  }): Promise<PluginCommandResult & { plugin?: PluginStateSnapshot }> {
+    return await this.request<PluginCommandResult & { plugin?: PluginStateSnapshot }>({
+      method: "internal.plugins.command",
+      params: {
+        pluginName: params.plugin_name,
+        command: params.command,
+        ...(params.payload !== undefined ? { payload: params.payload } : {}),
+        ...(params.schedule !== undefined ? { schedule: params.schedule } : {}),
+      },
+    });
+  }
+
+  /**
+   * 检查 Agent runtime 内 plugin 可用性。
+   */
+  async get_internal_plugin_availability(
+    plugin_name: string,
+  ): Promise<PluginAvailability> {
+    const data = await this.request<{
+      availability: PluginAvailability;
+    }>({
+      method: "internal.plugins.availability",
+      params: {
+        pluginName: plugin_name,
+      },
+    });
+    return data.availability;
+  }
+
+  /**
+   * 执行 Agent runtime 内 plugin action。
+   */
+  async run_internal_plugin_action(params: {
+    plugin_name: string;
+    action_name: string;
+    payload?: JsonValue;
+  }): Promise<PluginActionResult<JsonValue> & {
+    pluginName?: string;
+    actionName?: string;
+  }> {
+    return await this.request<PluginActionResult<JsonValue> & {
+      pluginName?: string;
+      actionName?: string;
+    }>({
+      method: "internal.plugins.action",
+      params: {
+        pluginName: params.plugin_name,
+        actionName: params.action_name,
+        ...(params.payload !== undefined ? { payload: params.payload } : {}),
+      },
+    });
+  }
+
   /**
    * 关闭底层连接。
    */

package/src/rpc/Server.ts

@@ -14,6 +14,15 @@ import type {
 } from "@/types/agent/AgentTypes.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { JsonValue } from "@/types/common/Json.js";
+import type { PluginStateControlAction } from "@/plugin/types/Plugin.js";
+import {
+  controlPluginState,
+  listPluginStates,
+} from "@/plugin/core/PluginStateController.js";
+import { parsePluginCommandRequestBody } from "@/plugin/core/PluginCommandRequest.js";
+import { runPluginCommand } from "@/plugin/core/PluginActionRunner.js";
 
 type RpcSessionRequest =
   | {
@@ -84,6 +93,52 @@ type RpcSessionRequest =
       params: {
         subscriptionId: string;
       };
+    }
+  | {
+      id: string;
+      method: "internal.status.get";
+    }
+  | {
+      id: string;
+      method: "internal.plugins.catalog";
+    }
+  | {
+      id: string;
+      method: "internal.plugins.list";
+    }
+  | {
+      id: string;
+      method: "internal.plugins.control";
+      params: {
+        pluginName: string;
+        action: PluginStateControlAction;
+      };
+    }
+  | {
+      id: string;
+      method: "internal.plugins.command";
+      params: {
+        pluginName: string;
+        command: string;
+        payload?: JsonValue;
+        schedule?: JsonValue;
+      };
+    }
+  | {
+      id: string;
+      method: "internal.plugins.availability";
+      params: {
+        pluginName: string;
+      };
+    }
+  | {
+      id: string;
+      method: "internal.plugins.action";
+      params: {
+        pluginName: string;
+        actionName: string;
+        payload?: JsonValue;
+      };
     };
 
 type RpcSuccessFrame = {
@@ -119,6 +174,8 @@ export interface RpcServerStartOptions {
   host: string;
   /** Session 集合访问口。 */
   sessionCollection: AgentSessionCollection;
+  /** Agent 上下文访问口。 */
+  getAgentContext?: () => AgentContext;
 }
 
 /**
@@ -143,7 +200,9 @@ export interface RpcServerInstance {
 export async function startRpcServer(
   options: RpcServerStartOptions,
 ): Promise<RpcServerInstance> {
+  const sockets = new Set<net.Socket>();
   const server = net.createServer((socket) => {
+    sockets.add(socket);
     const subscriptions = new Map<string, SocketSubscription>();
     let buffered = "";
 
@@ -241,6 +300,72 @@ export async function startRpcServer(
             writeSuccess(request.id, { unsubscribed: true });
             return;
           }
+          case "internal.status.get": {
+            writeSuccess(request.id, { status: "ok" });
+            return;
+          }
+          case "internal.plugins.catalog": {
+            const context = requireAgentContext(options);
+            writeSuccess(request.id, {
+              plugins: context.plugins.list(),
+            });
+            return;
+          }
+          case "internal.plugins.list": {
+            const context = requireAgentContext(options);
+            writeSuccess(request.id, {
+              plugins: listPluginStates({ context }),
+            });
+            return;
+          }
+          case "internal.plugins.control": {
+            const context = requireAgentContext(options);
+            const result = await controlPluginState({
+              pluginName: request.params.pluginName,
+              action: request.params.action,
+              context,
+            });
+            writeSuccess(request.id, result);
+            return;
+          }
+          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,
+            });
+            writeSuccess(request.id, result);
+            return;
+          }
+          case "internal.plugins.availability": {
+            const context = requireAgentContext(options);
+            const availability = await context.plugins.availability(
+              request.params.pluginName,
+            );
+            writeSuccess(request.id, {
+              pluginName: request.params.pluginName,
+              availability,
+            });
+            return;
+          }
+          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,
+            });
+            writeSuccess(request.id, {
+              ...result,
+              pluginName: request.params.pluginName,
+              actionName: request.params.actionName,
+            });
+            return;
+          }
         }
       } catch (error) {
         writeError(request.id, error);
@@ -273,6 +398,7 @@ export async function startRpcServer(
       cleanupSubscriptions();
     });
     socket.on("close", () => {
+      sockets.delete(socket);
       cleanupSubscriptions();
     });
     socket.on("end", () => {
@@ -294,9 +420,22 @@ export async function startRpcServer(
     url: `rpc://${options.host}:${options.port}`,
     server,
     async stop(): Promise<void> {
+      // 关键点（中文）：RPC 是长连接；停止 server 时必须主动关闭现有 socket。
+      for (const socket of sockets) {
+        socket.destroy();
+      }
+      sockets.clear();
       await new Promise<void>((resolve) => {
         server.close(() => resolve());
       });
     },
   };
 }
+
+function requireAgentContext(options: RpcServerStartOptions): AgentContext {
+  const context = options.getAgentContext?.();
+  if (!context) {
+    throw new Error("Agent RPC server was started without AgentContext");
+  }
+  return context;
+}

package/src/session/SessionTitle.ts

@@ -3,8 +3,8 @@
  *
  * 关键点（中文）
  * - session title 是 `meta.json` 顶层字段，列表与详情都以它为准。
- * - 首次用户消息出现后优先使用模型生成标题，失败时回退到首条用户消息截断。
- * - 老 session 缺失 title 时可在读取列表/详情时补写 fallback title。
+ * - title 默认允许为空；只有模型成功生成标题时才会写入。
+ * - 当 title 仍为空时，后续执行链路可以再次尝试生成。
  */
 
 import { generateText, type LanguageModel } from "ai";
@@ -16,7 +16,6 @@ import {
   writeSessionMetadata,
 } from "@/session/storage/Metadata.js";
 
-const FALLBACK_SESSION_TITLE_MAX_CHARS = 60;
 const GENERATED_SESSION_TITLE_MAX_CHARS = 24;
 
 /**
@@ -100,20 +99,6 @@ function normalizeGeneratedTitle(input: string): string | undefined {
     : undefined;
 }
 
-/**
- * 从首条用户消息推导 fallback 标题。
- */
-export function resolveFallbackSessionTitle(
-  messages: SessionMessageV1[],
-): string | undefined {
-  const firstUserText = resolveFirstUserText(messages);
-  const title = truncateTitle(
-    firstUserText,
-    FALLBACK_SESSION_TITLE_MAX_CHARS,
-  );
-  return normalizeSessionTitle(title);
-}
-
 async function generateSessionTitle(input: {
   /**
    * 当前模型实例。
@@ -154,32 +139,18 @@ export async function ensureSessionTitle(
   if (current.title) return current;
 
   const firstUserText = resolveFirstUserText(input.messages);
-  const fallbackTitle = resolveFallbackSessionTitle(input.messages);
-  if (!fallbackTitle) return current;
-
-  const fallbackMeta: SessionHistoryMetaV1 = {
-    ...current,
-    title: fallbackTitle,
-  };
-  await writeSessionMetadata({
-    projectRoot: input.projectRoot,
-    agentId: input.agentId,
-    sessionId: input.sessionId,
-    meta: fallbackMeta,
-  });
-
   if (input.generate !== true || !input.model || !firstUserText) {
-    return fallbackMeta;
+    return current;
   }
 
   const generatedTitle = await generateSessionTitle({
     model: input.model,
     firstUserText,
   });
-  if (!generatedTitle) return fallbackMeta;
+  if (!generatedTitle) return current;
 
   const generatedMeta: SessionHistoryMetaV1 = {
-    ...fallbackMeta,
+    ...current,
     title: generatedTitle,
   };
   await writeSessionMetadata({

package/src/session/browse/Browse.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 统一负责 session 列表摘要、session 详情与 history 分页的投影逻辑。
- * - 老 session 缺失持久化 title 时，会在列表读取阶段补写 fallback title。
+ * - session title 允许为空；浏览层不会再从首条 user message 推导 fallback title。
  * - 面向 SDK / RemoteAgent / HTTP route 复用，避免在多个入口重复拼列表与分页语义。
  * - 这里不持有运行态状态；执行状态等动态信息通过调用参数显式注入。
  */
@@ -36,7 +36,6 @@ import { getSdkAgentSessionsRootDirPath } from "@/session/storage/Paths.js";
 import { readSessionMetadata } from "@/session/storage/Metadata.js";
 import {
   ensureSessionTitle,
-  resolveFallbackSessionTitle,
 } from "@/session/SessionTitle.js";
 
 type AnyUiPart = UIMessagePart<Record<string, never>, Record<string, never>>;
@@ -185,13 +184,6 @@ export function resolveSessionMessagePreview(message: SessionMessageV1): string
   return extractAssistantToolSummary(message);
 }
 
-/**
- * 推导当前 session 的可读标题。
- */
-export function resolveSessionTitle(messages: SessionMessageV1[]): string | undefined {
-  return resolveFallbackSessionTitle(messages);
-}
-
 function resolveToolName(part: ToolPartCompatShape, aiToolName?: string): string {
   const fromAi = String(aiToolName || "").trim();
   if (fromAi) return fromAi;

package/src/session/index.ts

@@ -29,7 +29,6 @@ export {
 } from "./storage/Metadata.js";
 export {
   ensureSessionTitle,
-  resolveFallbackSessionTitle,
 } from "./SessionTitle.js";
 export {
   persistSdkAssistantResult,
@@ -44,6 +43,5 @@ export {
   listAgentSessionSummaryPage,
   loadSessionMessagesFromPath,
   resolveSessionMessagePreview,
-  resolveSessionTitle,
   toSessionTimelineEvents,
 } from "./browse/Browse.js";

package/src/types/agent/AgentTypes.ts

@@ -196,6 +196,15 @@ export interface RemoteAgentOptions {
    * 或 `rpc://127.0.0.1:5314`
    */
   url: string;
+
+  /**
+   * 访问远程 HTTP Agent 时使用的 Bearer token。
+   *
+   * 关键点（中文）
+   * - 仅 `http://` / `https://` transport 会携带该 token。
+   * - `rpc://` 是本机内部直连通道，不读取也不发送 token。
+   */
+  token?: string;
 }
 
 /**