@downcity/agent 1.1.74 → 1.1.81

package/src/types/plugin/PluginState.ts

@@ -0,0 +1,82 @@
+/**
+ * Plugin 状态类型。
+ *
+ * 关键点（中文）
+ * - 只描述 plugin 生命周期状态与控制结果。
+ * - 不包含 command/action/hook 等执行协议，避免状态类型被运行时细节污染。
+ */
+
+/**
+ * Plugin 运行状态。
+ *
+ * 说明（中文）
+ * - `starting` / `stopping` 仅用于生命周期过渡态。
+ * - `error` 表示最近一次 lifecycle / command / action 执行失败后留下的状态标记。
+ */
+export type PluginState =
+  | "running"
+  | "stopped"
+  | "starting"
+  | "stopping"
+  | "error";
+
+/**
+ * 单个 plugin 实例内部持有的状态记录。
+ */
+export interface PluginStateRecord {
+  /** 当前运行状态。 */
+  state: PluginState;
+  /** 最近一次状态更新时间（毫秒时间戳）。 */
+  updatedAt: number;
+  /** 最近一次错误信息。 */
+  lastError?: string;
+  /** 最近一次执行的命令名。 */
+  lastCommand?: string;
+  /** 最近一次执行命令的时间（毫秒时间戳）。 */
+  lastCommandAt?: number;
+  /** 当前串行控制链。 */
+  chain: Promise<void>;
+}
+
+/**
+ * 单个 plugin 状态的对外快照。
+ */
+export interface PluginStateSnapshot {
+  /** plugin 名称。 */
+  name: string;
+  /** 当前运行状态。 */
+  state: PluginState;
+  /** 最近一次状态更新时间（毫秒时间戳）。 */
+  updatedAt: number;
+  /** 最近一次错误信息。 */
+  lastError?: string;
+  /** 最近一次执行的命令名。 */
+  lastCommand?: string;
+  /** 最近一次执行命令的时间（毫秒时间戳）。 */
+  lastCommandAt?: number;
+  /** 是否支持主动生命周期。 */
+  supportsLifecycle: boolean;
+  /** 是否支持 command/action。 */
+  supportsCommand: boolean;
+}
+
+/**
+ * plugin 状态控制动作。
+ */
+export type PluginStateControlAction =
+  | "start"
+  | "stop"
+  | "restart"
+  | "status";
+
+/**
+ * plugin 状态控制结果。
+ */
+export interface PluginStateControlResult {
+  /** 控制动作是否成功。 */
+  success: boolean;
+  /** 成功或失败后返回的最新 plugin 快照。 */
+  plugin?: PluginStateSnapshot;
+  /** 失败时的错误信息。 */
+  error?: string;
+}

package/src/types/rpc/RpcProtocol.ts

@@ -0,0 +1,361 @@
+/**
+ * Agent RPC 协议类型。
+ *
+ * 关键点（中文）
+ * - 该文件只描述本机 RPC 的线协议，不包含 socket 或业务执行逻辑。
+ * - Client 与 Server 共享同一份 request/frame 类型，避免协议两边漂移。
+ * - 字段名保持现有协议格式，兼容已发布的 Town 托管 runtime 调用。
+ */
+
+import type {
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  AgentSessionHistoryInput,
+  AgentSessionSystemSnapshot,
+} from "@/types/agent/AgentTypes.js";
+import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { PluginStateControlAction } from "@/plugin/types/Plugin.js";
+
+/**
+ * RPC 请求。
+ *
+ * 关键点（中文）
+ * - `sdk.*` 面向 RemoteAgent 的稳定会话 SDK。
+ * - `internal.*` 面向 Town 本机管理通道。
+ */
+export type RpcRequest =
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 列出 session。 */
+      method: "sdk.sessions.list";
+      /** 列表过滤与分页参数。 */
+      params?: AgentListSessionsInput;
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 创建 session。 */
+      method: "sdk.sessions.create";
+      /** 创建参数。 */
+      params?: AgentCreateSessionInput;
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 读取 session 信息。 */
+      method: "sdk.sessions.get";
+      /** 目标 session 参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 向 session 发送 prompt。 */
+      method: "sdk.sessions.prompt";
+      /** prompt 参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+        /** SDK prompt 输入。 */
+        input: AgentSessionPromptInput;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 读取 session history。 */
+      method: "sdk.sessions.history";
+      /** history 查询参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+        /** history 分页与视图参数。 */
+        input?: AgentSessionHistoryInput;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 读取 session system snapshot。 */
+      method: "sdk.sessions.system";
+      /** 目标 session 参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 分叉 session。 */
+      method: "sdk.sessions.fork";
+      /** 分叉参数。 */
+      params: {
+        /** 源 session id。 */
+        sessionId: string;
+        /** 可选源消息 id。 */
+        messageId?: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 订阅 session 事件。 */
+      method: "sdk.sessions.subscribe";
+      /** 订阅参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 取消 session 事件订阅。 */
+      method: "sdk.sessions.unsubscribe";
+      /** 取消订阅参数。 */
+      params: {
+        /** 当前订阅 id。 */
+        subscriptionId: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 读取 Agent 内部状态。 */
+      method: "internal.status.get";
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 清空 session messages。 */
+      method: "internal.sessions.clear_messages";
+      /** 目标 session 参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 清空 chat history。 */
+      method: "internal.sessions.clear_chat_history";
+      /** 目标 session 参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 解析 session system prompt。 */
+      method: "internal.sessions.resolve_system_prompt";
+      /** 目标 session 参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 列出 plugin catalog。 */
+      method: "internal.plugins.catalog";
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 列出 plugin 状态。 */
+      method: "internal.plugins.list";
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 控制 plugin 生命周期。 */
+      method: "internal.plugins.control";
+      /** plugin 控制参数。 */
+      params: {
+        /** plugin 名称。 */
+        pluginName: string;
+        /** 控制动作。 */
+        action: PluginStateControlAction;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 执行 plugin command。 */
+      method: "internal.plugins.command";
+      /** plugin command 参数。 */
+      params: {
+        /** plugin 名称。 */
+        pluginName: string;
+        /** command 名称。 */
+        command: string;
+        /** command payload。 */
+        payload?: JsonValue;
+        /** 可选调度 payload。 */
+        schedule?: JsonValue;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 检查 plugin 可用性。 */
+      method: "internal.plugins.availability";
+      /** plugin 参数。 */
+      params: {
+        /** plugin 名称。 */
+        pluginName: string;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 执行 plugin action。 */
+      method: "internal.plugins.action";
+      /** plugin action 参数。 */
+      params: {
+        /** plugin 名称。 */
+        pluginName: string;
+        /** action 名称。 */
+        actionName: string;
+        /** action payload。 */
+        payload?: JsonValue;
+      };
+    };
+
+/**
+ * RPC 成功响应帧。
+ */
+export interface RpcSuccessFrame {
+  /** 请求 id。 */
+  id: string;
+  /** 成功标记。 */
+  success: true;
+  /** 响应数据。 */
+  data?: unknown;
+}
+
+/**
+ * RPC 失败响应帧。
+ */
+export interface RpcErrorFrame {
+  /** 请求 id。 */
+  id: string;
+  /** 失败标记。 */
+  success: false;
+  /** 错误信息。 */
+  error: string;
+}
+
+/**
+ * RPC 普通响应帧。
+ */
+export type RpcResponseFrame = RpcSuccessFrame | RpcErrorFrame;
+
+/**
+ * RPC 订阅 ready 帧。
+ */
+export interface RpcReadyFrame {
+  /** 帧类型。 */
+  type: "ready";
+  /** 当前订阅 id。 */
+  subscriptionId: string;
+}
+
+/**
+ * RPC 事件帧。
+ */
+export interface RpcEventFrame {
+  /** 帧类型。 */
+  type: "event";
+  /** 当前订阅 id。 */
+  subscriptionId: string;
+  /** session 事件。 */
+  event: AgentSessionEvent;
+}
+
+/**
+ * RPC server 可写帧。
+ */
+export type RpcServerFrame = RpcSuccessFrame | RpcErrorFrame | RpcEventFrame;
+
+/**
+ * RPC client 可读帧。
+ */
+export type RpcClientFrame = RpcResponseFrame | RpcReadyFrame | RpcEventFrame;
+
+/**
+ * RPC endpoint。
+ */
+export interface RpcClientEndpoint {
+  /** RPC host。 */
+  host: string;
+  /** RPC port。 */
+  port: number;
+}
+
+/**
+ * RPC Session 订阅句柄。
+ */
+export interface RpcSessionSubscription {
+  /** 当前订阅 id。 */
+  subscription_id: string;
+  /** 取消订阅。 */
+  unsubscribe(): Promise<void>;
+}
+
+/**
+ * RPC system prompt 分段条目。
+ */
+export interface RpcSystemPromptSectionItem {
+  /** 消息序号。 */
+  index: number;
+  /** system message 文本内容。 */
+  content: string;
+}
+
+/**
+ * RPC system prompt 分段。
+ */
+export interface RpcSystemPromptSection {
+  /** 分段稳定 key。 */
+  key: string;
+  /** 分段展示标题。 */
+  title: string;
+  /** 分段内消息条目。 */
+  items: RpcSystemPromptSectionItem[];
+}
+
+/**
+ * RPC system prompt 响应。
+ */
+export interface RpcSystemPromptPayload {
+  /** 请求是否成功。 */
+  success?: boolean;
+  /** 当前 session id。 */
+  sessionId: string;
+  /** system message 总数。 */
+  totalMessages: number;
+  /** system message 总字符数。 */
+  totalChars: number;
+  /** system message 分段。 */
+  sections: RpcSystemPromptSection[];
+}
+
+/**
+ * RPC session system snapshot 响应。
+ */
+export interface RpcSessionSystemResult {
+  /** system snapshot。 */
+  system: AgentSessionSystemSnapshot;
+}

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

@@ -16,7 +16,7 @@ import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type {
   AgentPathRuntime,
   AgentPluginConfigRuntime,
-} from "@/types/runtime/host/AgentHost.js";
+} from "@/types/agent/AgentRuntimeAssembly.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type { PluginPort } from "@/plugin/types/Plugin.js";

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

@@ -15,7 +15,7 @@ import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type {
   AgentPathRuntime,
   AgentPluginConfigRuntime,
-} from "@/types/runtime/host/AgentHost.js";
+} from "@/types/agent/AgentRuntimeAssembly.js";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 

package/src/types/session/SessionComposerOptions.ts

@@ -0,0 +1,107 @@
+/**
+ * Session Composer 配置类型。
+ *
+ * 关键点（中文）
+ * - Composer 是 session 执行阶段的可替换策略对象。
+ * - 调用方可以传入现成实例，也可以传入 factory 为每个 session 创建独立实例。
+ * - factory 适合 history/system 等可能绑定 sessionId、historyStore 或 session 元信息的 composer。
+ */
+
+import type { Tool } from "ai";
+import type { SessionCompactionComposer } from "@/executor/composer/compaction/SessionCompactionComposer.js";
+import type { SessionContextComposer } from "@/executor/composer/context/SessionContextComposer.js";
+import type { SessionHistoryComposer } from "@/executor/composer/history/SessionHistoryComposer.js";
+import type { SessionSystemComposer } from "@/executor/composer/system/SessionSystemComposer.js";
+import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+
+/**
+ * 单个 session 创建 Composer 时可读取的稳定上下文。
+ */
+export interface SessionComposerFactoryContext {
+  /**
+   * 当前 agent 的稳定标识。
+   */
+  agentId: string;
+
+  /**
+   * 当前 agent 绑定的项目根目录。
+   */
+  projectRoot: string;
+
+  /**
+   * 当前 session 唯一标识。
+   */
+  sessionId: string;
+
+  /**
+   * 当前 session 对应的 history 事实源。
+   *
+   * 关键点（中文）
+   * - history composer 和 compaction composer 通常需要基于它读取或压缩历史。
+   * - factory 每次收到的都是当前 session 自己的 store。
+   */
+  historyStore: SessionHistoryStore;
+
+  /**
+   * 当前 agent 默认工具集合读取器。
+   */
+  getTools: () => Record<string, Tool>;
+
+  /**
+   * 读取当前 SDK 调用方传入的 instruction system blocks。
+   */
+  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+
+  /**
+   * 读取当前 agent 显式注入的受托管 plugin system blocks。
+   */
+  getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 读取当前 agent 显式注册 plugin 的 system blocks。
+   */
+  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 读取当前 session 首次创建时间（ms）。
+   */
+  getSessionCreatedAt: () => number;
+
+  /**
+   * 读取当前 session 初始化时解析到的系统时区。
+   */
+  getSessionTimezone: () => string;
+}
+
+/**
+ * 可直接传入 composer 实例，也可传入按 session 创建 composer 的 factory。
+ */
+export type SessionComposerInput<TComposer> =
+  | TComposer
+  | ((context: SessionComposerFactoryContext) => TComposer);
+
+/**
+ * Session Composer 覆盖项。
+ */
+export interface SessionComposerOptions {
+  /**
+   * 覆盖本轮 system messages 的 composer。
+   */
+  systemComposer?: SessionComposerInput<SessionSystemComposer>;
+
+  /**
+   * 覆盖本轮 history messages 的 composer。
+   */
+  historyComposer?: SessionComposerInput<SessionHistoryComposer>;
+
+  /**
+   * 覆盖本轮 tools、step hooks、fallback assistant message 等运行上下文 composer。
+   */
+  contextComposer?: SessionComposerInput<SessionContextComposer>;
+
+  /**
+   * 覆盖本轮上下文压缩 composer。
+   */
+  compactionComposer?: SessionComposerInput<SessionCompactionComposer>;
+}

package/src/types/session/SessionLocalState.ts

@@ -0,0 +1,40 @@
+/**
+ * SessionLocalState：本地 Session 运行态快照。
+ *
+ * 关键点（中文）
+ * - 这里承载本地 Session 在内存中的可变运行态。
+ * - state / turn / view 三类 service 通过共享该对象协作，避免彼此复制状态。
+ * - 这里只保存运行态，不承载行为逻辑。
+ */
+
+import type { AgentSessionConfigSnapshot } from "@/types/agent/AgentTypes.js";
+
+/**
+ * 本地 Session 内存状态。
+ */
+export interface SessionLocalState {
+  /**
+   * 当前 session 配置快照。
+   */
+  sessionConfig: AgentSessionConfigSnapshot;
+
+  /**
+   * 当前 session 创建时间（毫秒时间戳）。
+   */
+  createdAt: number;
+
+  /**
+   * 当前 session 参考时区。
+   */
+  timezone: string;
+
+  /**
+   * initialize() 过程中的并发复用 Promise。
+   */
+  initializePromise: Promise<void> | null;
+
+  /**
+   * ensureReadyForExecution() 过程中的并发复用 Promise。
+   */
+  ensureConfiguredPromise: Promise<void> | null;
+}

package/src/types/session/SessionOptions.ts

@@ -0,0 +1,99 @@
+/**
+ * Session 构造参数类型。
+ *
+ * 关键点（中文）
+ * - 这里描述 Agent 创建本地 Session 时传入的稳定上下文。
+ * - 默认 Session 和自定义 Session 类都应使用这组参数。
+ * - Composer 仍然是 Session 级能力，不向 Agent 的执行策略层泄漏。
+ */
+
+import type { Tool } from "ai";
+import type { AgentSession } from "@/types/agent/SessionActor.js";
+import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { SessionComposerOptions } from "@/types/session/SessionComposerOptions.js";
+
+/**
+ * Agent 可管理的本地 Session 实例。
+ */
+export interface AgentManagedSession extends AgentSession {
+  /**
+   * 初始化当前 session。
+   */
+  initialize(): Promise<this>;
+
+  /**
+   * 返回供 plugin/runtime 使用的 session 端口。
+   */
+  getRuntimePort(): SessionPort;
+
+  /**
+   * 返回当前 session 是否正在执行。
+   */
+  isExecuting(): boolean;
+}
+
+/**
+ * 本地 Session 构造参数。
+ */
+export interface SessionOptions {
+  /**
+   * 当前 agent 稳定标识。
+   */
+  agentId: string;
+
+  /**
+   * 当前项目根目录。
+   */
+  projectRoot: string;
+
+  /**
+   * 当前 sessionId。
+   */
+  sessionId: string;
+
+  /**
+   * 当前 agent 默认工具集合。
+   */
+  tools: Record<string, Tool>;
+
+  /**
+   * 统一日志器。
+   */
+  logger: {
+    /**
+     * 记录普通信息。
+     */
+    info(message: string, details?: Record<string, unknown>): void;
+
+    /**
+     * 记录警告信息。
+     */
+    warn(message: string, details?: Record<string, unknown>): void;
+  };
+
+  /**
+   * 读取当前 SDK 调用方传入的 instruction system blocks。
+   */
+  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+
+  /**
+   * 读取当前 agent 显式注入的受托管 plugin system blocks。
+   */
+  getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 读取当前 agent 显式注册 plugin 的 system blocks。
+   */
+  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 在执行前确保当前 session 已完成宿主侧默认配置。
+   */
+  ensureConfigured?: (session: AgentManagedSession) => Promise<void>;
+
+  /**
+   * 当前 session 的 Composer 覆盖项。
+   */
+  composers?: SessionComposerOptions;
+}