@downcity/agent 1.1.338 → 1.1.400

package/src/city/transport/rpc/server/SdkSessionHandlers.ts

@@ -0,0 +1,166 @@
+/**
+ * RPC SDK session handlers。
+ *
+ * 关键点（中文）
+ * - 只处理 `sdk.sessions.*` 方法。
+ * - 这些方法是 RemoteAgent RPC transport 的稳定 SDK 面。
+ */
+
+import type { RpcRequest } from "@/city/transport/types/RpcProtocol.js";
+import type {
+  RpcSocketSubscription,
+  RpcWriteEvent,
+  RpcWriteSuccess,
+  RpcRequestHandlerOptions,
+} from "@/city/transport/rpc/server/ServerTypes.js";
+import { resolve_remote_session_set_input } from "@/city/transport/session/RemoteSessionConfig.js";
+
+/**
+ * 处理 SDK session RPC 请求。
+ */
+export async function handle_sdk_session_rpc_request(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.sessions.list(request.params);
+      write_success(request.id, { page });
+      return true;
+    }
+    case "sdk.sessions.create": {
+      const session = await options.sessions.create(request.params);
+      write_success(request.id, { session: await session.get_info() });
+      return true;
+    }
+    case "sdk.sessions.get": {
+      const session = await options.sessions.get(request.params.session_id);
+      write_success(request.id, { session: await session.get_info() });
+      return true;
+    }
+    case "sdk.sessions.prompt": {
+      const session = await options.sessions.get(request.params.session_id);
+      const turn = await session.prompt(request.params.input);
+      write_success(request.id, { turn: { id: turn.id } });
+      return true;
+    }
+    case "sdk.sessions.stop": {
+      const session = await options.sessions.get(request.params.session_id);
+      const result = await session.stop();
+      write_success(request.id, { result });
+      return true;
+    }
+    case "sdk.sessions.compact": {
+      const session = await options.sessions.get(request.params.session_id);
+      const compact = await session.compact();
+      write_success(request.id, { compact: { id: compact.id } });
+      return true;
+    }
+    case "sdk.sessions.messages": {
+      const session = await options.sessions.get(request.params.session_id);
+      const messages = await session.messages(request.params.input);
+      write_success(request.id, { messages });
+      return true;
+    }
+    case "sdk.sessions.interactions": {
+      const session = await options.sessions.get(request.params.session_id);
+      write_success(request.id, { interactions: await session.interactions() });
+      return true;
+    }
+    case "sdk.sessions.status": {
+      const session = await options.sessions.get(request.params.session_id);
+      write_success(request.id, { status: await session.status() });
+      return true;
+    }
+    case "sdk.sessions.set": {
+      const session = await options.sessions.get(request.params.session_id);
+      const input = await resolve_remote_session_set_input({
+        config: request.params.input,
+        resolve_session_model: options.resolve_session_model,
+      });
+      await session.set(input, request.params.options);
+      write_success(request.id, { queued: true });
+      return true;
+    }
+    case "sdk.sessions.respond": {
+      const session = await options.sessions.get(request.params.session_id);
+      write_success(request.id, {
+        result: await session.respond(request.params.input),
+      });
+      return true;
+    }
+    case "sdk.sessions.system": {
+      const session = await options.sessions.get(request.params.session_id);
+      write_success(request.id, { system: await session.system() });
+      return true;
+    }
+    case "sdk.sessions.fork": {
+      const session = await options.sessions.get(request.params.session_id);
+      const forked = await session.fork(request.params.message_id ? {
+        message_id: request.params.message_id,
+        include_message: request.params.include_message,
+      } : undefined);
+      write_success(request.id, { session: await forked.get_info() });
+      return true;
+    }
+    case "sdk.sessions.subscribe": {
+      const session = await options.sessions.get(request.params.session_id);
+      const subscription_id = [
+        request.params.session_id,
+        Date.now(),
+        Math.random().toString(36).slice(2, 10),
+      ].join(":");
+      const unsubscribe = session.subscribe((event) => {
+        write_event({
+          type: "event",
+          subscription_id: subscription_id,
+          event,
+        });
+      });
+      subscriptions.set(subscription_id, {
+        session_id: request.params.session_id,
+        unsubscribe,
+      });
+      write_success(request.id, { subscription_id: subscription_id });
+      return true;
+    }
+    case "sdk.sessions.unsubscribe": {
+      const subscription = subscriptions.get(request.params.subscription_id);
+      if (subscription) {
+        subscription.unsubscribe();
+        subscriptions.delete(request.params.subscription_id);
+      }
+      write_success(request.id, { unsubscribed: true });
+      return true;
+    }
+    case "sdk.sessions.archive": {
+      const result = await options.sessions.archive({
+        id: request.params.session_id,
+      });
+      write_success(request.id, { result });
+      return true;
+    }
+    case "sdk.sessions.archived.list": {
+      const page = await options.sessions.archived(request.params);
+      write_success(request.id, { page });
+      return true;
+    }
+    case "sdk.sessions.archived.clean": {
+      const result = await options.sessions.clean_archive();
+      write_success(request.id, { removed_session_ids: result.removed_session_ids });
+      return true;
+    }
+    default:
+      return false;
+  }
+}

package/src/city/transport/rpc/server/ServerTypes.ts

@@ -0,0 +1,103 @@
+/**
+ * Agent RPC server 内部类型。
+ *
+ * 关键点（中文）
+ * - 这里描述 handler 需要的依赖，不承载 socket 生命周期。
+ * - `RpcServer.ts` 负责网络层，handler 把协议方法转成 Agent 操作。
+ */
+
+import type { AgentSessionCollection } from "@/types/agent/AgentSessionCollection.js";
+import type { Agent } from "@/agent/Agent.js";
+import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
+import type { PluginSnapshot } from "@/types/plugin/PluginState.js";
+import type { WorkspaceBase } from "@downcity/workspace";
+import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { RpcEventFrame } from "@/city/transport/types/RpcProtocol.js";
+import type { AgentSessionModelResolver } from "@/city/transport/types/AgentSessionModelResolver.js";
+
+/**
+ * RPC server 启动参数。
+ */
+export interface RpcServerStartOptions {
+  /** RPC 服务监听端口。 */
+  port: number;
+  /** RPC 服务监听主机。 */
+  host: string;
+  /** Session 集合访问口。 */
+  sessions: AgentSessionCollection;
+  /** 当前请求对应的 Agent 执行能力。 */
+  get_agent_context?: () => RpcAgentContext;
+  /** 将远程模型 ID 解析为当前宿主可执行的模型实例。 */
+  resolve_session_model?: AgentSessionModelResolver;
+  /** 由宿主重新加载并提交 Workspace Env 的能力。 */
+  reload_workspace_env?: () => Record<string, string> | Promise<Record<string, string>>;
+  /** 按请求选择 Agent 级 handler 依赖；CityRPC 使用该入口完成多 Agent 路由。 */
+  resolve_request_options?: (
+    request: import("@/city/transport/types/RpcProtocol.js").RpcRequest,
+  ) => RpcRequestHandlerOptions | Promise<RpcRequestHandlerOptions>;
+}
+
+/**
+ * RPC request handler 依赖。
+ */
+export interface RpcRequestHandlerOptions {
+  /** Session 集合访问口。 */
+  sessions: AgentSessionCollection;
+  /** 当前请求对应的 Agent 执行能力。 */
+  get_agent_context?: () => RpcAgentContext;
+  /** 将远程模型 ID 解析为当前宿主可执行的模型实例。 */
+  resolve_session_model?: AgentSessionModelResolver;
+  /** 由宿主重新加载并提交 Workspace Env 的能力。 */
+  reload_workspace_env?: () => Record<string, string> | Promise<Record<string, string>>;
+  /** 返回 City 宿主身份；仅 CityRPC 提供。 */
+  get_city_status?: () => {
+    /** 当前 City 加载的 Agent ID。 */
+    agent_ids: string[];
+  };
+  /** 请求当前宿主优雅退出。 */
+  shutdown_city?: () => void | Promise<void>;
+}
+
+/**
+ * RPC internal handler 所需的最小 Agent 能力集合。
+ *
+ * 这是传输层的依赖投影，不是新的领域对象，也不拥有 Agent 或 Session。
+ */
+export interface RpcAgentContext {
+  /** 当前 Agent 实例。 */
+  agent: Agent;
+  /** 当前请求绑定的 Workspace。 */
+  workspace: WorkspaceBase;
+  /** 当前 Agent 唯一的 Session 集合。 */
+  sessions: AgentSessionCollection;
+  /** 当前 Agent 在 Workspace 中可用的 Plugin 调用面。 */
+  plugins: AgentPlugins;
+  /** 读取当前 Agent 的 Plugin 状态。 */
+  list_plugin_states: () => PluginSnapshot[];
+  /** 解析当前 Session 的 system messages。 */
+  resolve_system_messages: (input: {
+    /** 目标 Session ID。 */
+    session_id: string;
+    /** system message profile。 */
+    profile?: "chat" | "task";
+  }) => Promise<SessionSystemMessage[]>;
+}
+
+/**
+ * 单个 socket 上的 session 订阅。
+ */
+export interface RpcSocketSubscription {
+  /** 被订阅的 session id。 */
+  session_id: 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/city/transport/session/RemoteSessionConfig.ts

@@ -0,0 +1,34 @@
+/**
+ * 远程 Session 配置解析器。
+ *
+ * 负责把 transport 上可序列化的配置转换为本地 Session 输入；模型目录仍由宿主拥有。
+ */
+
+import type {
+  AgentSessionSetInput,
+  RemoteSessionSetInput,
+} from "@/index.js";
+import type { AgentSessionModelResolver } from "@/city/transport/types/AgentSessionModelResolver.js";
+
+/** 把远程配置输入解析为本地 Session 可执行输入。 */
+export async function resolve_remote_session_set_input(input: {
+  /** 远程 transport 收到的可序列化配置。 */
+  config: RemoteSessionSetInput;
+  /** 宿主提供的模型解析能力。 */
+  resolve_session_model?: AgentSessionModelResolver;
+}): Promise<AgentSessionSetInput> {
+  const model_id = String(input.config.model_id || "").trim();
+  if (!model_id && !input.config.security) {
+    throw new Error("remote session.set requires model_id or security");
+  }
+  if (model_id && !input.resolve_session_model) {
+    throw new Error("Remote Session model switching is not configured by the host");
+  }
+  const model = model_id
+    ? await input.resolve_session_model?.(model_id)
+    : undefined;
+  return {
+    ...(model ? { model } : {}),
+    ...(input.config.security ? { security: input.config.security } : {}),
+  };
+}

package/src/city/transport/types/AgentHttpBinding.ts

@@ -0,0 +1,25 @@
+/**
+ * AgentHTTP server 监听绑定类型。
+ */
+
+/**
+ * AgentHTTP server 监听绑定信息。
+ */
+export interface AgentHttpBinding {
+  /** 完整 HTTP 访问 URL。 */
+  url: string;
+  /** 当前监听主机。 */
+  host: string;
+  /** 当前监听端口。 */
+  port: number;
+}
+
+/**
+ * AgentHTTP server 监听参数。
+ */
+export interface AgentHttpListenOptions {
+  /** 监听主机，默认 `127.0.0.1`。 */
+  host?: string;
+  /** 监听端口（必填）。 */
+  port: number;
+}

package/src/city/transport/types/AgentHttpRuntime.ts

@@ -0,0 +1,13 @@
+/**
+ * Agent HTTP 宿主运行时能力类型。
+ *
+ * 这里只声明 SDK HTTP transport 需要宿主补充的解析能力。
+ */
+
+import type { AgentSessionModelResolver } from "@/city/transport/types/AgentSessionModelResolver.js";
+
+/** Agent HTTP 宿主运行时能力。 */
+export interface AgentHttpRuntimeOptions {
+  /** 将远程模型 ID 解析为当前宿主可执行的模型实例。 */
+  resolve_session_model?: AgentSessionModelResolver;
+}

package/src/city/transport/types/AgentRpcBinding.ts

@@ -0,0 +1,28 @@
+/**
+ * AgentRPC 监听绑定类型。
+ *
+ * 关键点（中文）
+ * - 仅描述监听后的可观测信息，不暴露底层 net.Server。
+ */
+
+/**
+ * AgentRPC 监听绑定信息。
+ */
+export interface AgentRpcBinding {
+  /** 完整 RPC 访问 URL，例如 `rpc://127.0.0.1:15314`。 */
+  url: string;
+  /** 当前监听主机。 */
+  host: string;
+  /** 当前监听端口。 */
+  port: number;
+}
+
+/**
+ * AgentRPC 监听参数。
+ */
+export interface AgentRpcListenOptions {
+  /** 监听主机，默认 `127.0.0.1`。 */
+  host?: string;
+  /** 监听端口，默认 `15314`。 */
+  port?: number;
+}

package/src/city/transport/types/AgentRpcRuntime.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent RPC 宿主运行时能力类型。
+ *
+ * 该类型只投影 internal 管理命令需要的宿主能力，不让 RPC Server 理解 City 的配置文件位置。
+ */
+
+import type { AgentSessionModelResolver } from "@/city/transport/types/AgentSessionModelResolver.js";
+
+/** Agent RPC 宿主运行时能力。 */
+export interface AgentRpcRuntimeOptions {
+  /** 将远程模型 ID 解析为当前宿主可执行的模型实例。 */
+  resolve_session_model?: AgentSessionModelResolver;
+
+  /**
+   * 从宿主事实源重新解析 Workspace Env，并把完整快照提交给 Workspace。
+   *
+   * 返回值用于 RPC 响应确认，调用方不得把 Env 明文写入日志。
+   */
+  reload_workspace_env?: () => Record<string, string> | Promise<Record<string, string>>;
+}

package/src/city/transport/types/AgentSessionModelResolver.ts

@@ -0,0 +1,13 @@
+/**
+ * Agent transport 的 Session 模型解析能力。
+ *
+ * Transport 只接收远程协议中的模型 ID；具体目录、鉴权和运行时模型创建由宿主实现。
+ */
+
+import type { AgentModel } from "@/index.js";
+
+/** 把宿主模型 ID 解析为 Agent 可执行模型实例。 */
+export type AgentSessionModelResolver = (
+  /** 远程调用方请求的宿主模型 ID。 */
+  model_id: string,
+) => AgentModel | Promise<AgentModel>;

package/src/city/transport/types/CityHttpRuntime.ts

@@ -0,0 +1,45 @@
+/**
+ * City HTTP 宿主运行时能力类型。
+ *
+ * City transport 先按 Agent ID 选中 Agent，再把模型解析等宿主能力投影给单
+ * Agent HTTP router，避免路由层理解本地 Store 的实现。
+ */
+
+import type { AgentSessionModelResolver } from "@/city/transport/types/AgentSessionModelResolver.js";
+import type { Agent } from "@/index.js";
+import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
+import type { WorkspaceBase } from "@downcity/workspace";
+import type { Hono } from "hono";
+
+/** 宿主为一个 Agent 提供的 HTTP 扩展。 */
+export interface CityAgentHttpExtension {
+  /** 已组合 SDK Router 的 Agent 子路由。 */
+  router: Hono;
+
+  /** CityHTTP 关闭时需要同步释放的宿主资源。 */
+  dispose?(): void | Promise<void>;
+}
+
+/** City HTTP transport 所需的宿主能力。 */
+export interface CityHttpRuntimeOptions {
+  /** 为指定 Agent 创建远程 Session 所需的模型解析器。 */
+  resolve_session_model?: (
+    agent_id: string,
+    workspace_id: string,
+    model_id: string,
+  ) => ReturnType<AgentSessionModelResolver>;
+
+  /** 为一个 Agent 组合 Auth、控制台和应用专属路由。 */
+  create_agent_extension?: (input: {
+    /** 当前路由对应的本地 Agent。 */
+    agent: Agent;
+    /** 当前路由对应的 Agent Workspace 执行作用域。 */
+    workspace: WorkspaceBase;
+    plugins: AgentPlugins;
+    /** City 提供的标准 RemoteAgent SDK Router。 */
+    sdk_router: Hono;
+  }) => CityAgentHttpExtension;
+
+  /** 挂载到 City HTTP 根路径的宿主扩展 Router。 */
+  city_router?: Hono;
+}

package/src/city/transport/types/CityRpcRuntime.ts

@@ -0,0 +1,27 @@
+/**
+ * City RPC 宿主运行时能力类型。
+ *
+ * 所有回调都显式接收 Agent ID，使 transport 不依赖任何持久化层，也不会把
+ * 多 Agent 的运行时配置复制成第二份事实源。
+ */
+
+import type { AgentSessionModelResolver } from "@/city/transport/types/AgentSessionModelResolver.js";
+
+/** City RPC transport 所需的宿主能力。 */
+export interface CityRpcRuntimeOptions {
+  /** 处理宿主关闭请求；调用方负责安排实际进程退出。 */
+  shutdown?: () => void | Promise<void>;
+
+  /** 为指定 Agent 创建远程 Session 所需的模型解析器。 */
+  resolve_session_model?: (
+    agent_id: string,
+    workspace_id: string,
+    model_id: string,
+  ) => ReturnType<AgentSessionModelResolver>;
+
+  /** 从事实源重新加载指定 Agent 的 Workspace Env。 */
+  reload_workspace_env?: (
+    agent_id: string,
+    workspace_id: string,
+  ) => Record<string, string> | Promise<Record<string, string>>;
+}

package/src/city/transport/types/RpcProtocol.ts

@@ -0,0 +1,32 @@
+/**
+ * City transport 内部使用的 RPC 协议类型 re-export。
+ *
+ * 关键点（中文）
+ * - Agent 请求复用 `@/index.js` 的公开 RPC 协议。
+ * - City 宿主控制方法只在本包扩展，不进入单 Agent SDK。
+ */
+
+export type {
+  RpcEventFrame,
+  RpcServerFrame,
+} from "@/index.js";
+
+import type { RpcRequest as AgentRpcRequest } from "@/index.js";
+
+/** City 宿主自身的 RPC 控制请求。 */
+export type CityControlRpcRequest =
+  | {
+      /** 请求 ID，用于匹配响应。 */
+      id: string;
+      /** 读取 City 宿主进程状态。 */
+      method: "internal.city.status";
+    }
+  | {
+      /** 请求 ID，用于匹配响应。 */
+      id: string;
+      /** 请求 City 宿主优雅退出。 */
+      method: "internal.city.shutdown";
+    };
+
+/** City transport 接受单 Agent 请求和 City 控制请求。 */
+export type RpcRequest = AgentRpcRequest | CityControlRpcRequest;

package/src/city/types/City.ts

@@ -0,0 +1,99 @@
+/**
+ * City 生命周期类型。
+ *
+ * City 维护 Agent 集合与 transport，并协调已加入 Agent 的运行时生命周期。
+ */
+
+import type { CityHttpRuntimeOptions } from "@/city/transport/types/CityHttpRuntime.js";
+import type { CityRpcRuntimeOptions } from "@/city/transport/types/CityRpcRuntime.js";
+import type { Agent } from "@/index.js";
+import type { Embassy } from "@downcity/federation";
+import type { WorkspaceBase } from "@downcity/workspace";
+import type { StorageProvider } from "@downcity/workspace";
+import type { Group } from "@/group/Group.js";
+
+/** City 的资源容器构造参数。 */
+export interface CityOptions {
+  /** City 为 Agent 提供的底层存储；省略时使用进程内存储。 */
+  storage?: StorageProvider;
+
+  /** City 使用的 Federation Embassy；Plugin 只通过窄服务借用其能力。 */
+  embassy?: Embassy;
+
+  /** City 持有的 Workspace 资源集合；每个 Workspace ID 必须唯一。 */
+  workspaces?: readonly WorkspaceBase[];
+
+  /** HTTP/RPC transport 与宿主扩展配置；仅供宿主装配层使用。 */
+  runtime?: CityRuntimeOptions;
+}
+
+/** City 构造时可注入的 transport 扩展能力。 */
+export interface CityRuntimeOptions {
+  /** 按需为 Agent 创建指定 Workspace；City 不读取任何持久化配置。 */
+  resolve_workspace?: (
+    agent: Agent,
+    workspace_id: string,
+  ) => WorkspaceBase | Promise<WorkspaceBase>;
+
+  /** HTTP transport 的模型解析和宿主扩展路由。 */
+  http?: CityHttpRuntimeOptions;
+
+  /** RPC transport 的模型解析与环境刷新能力。 */
+  rpc?: CityRpcRuntimeOptions;
+}
+
+/** City 管理的 Agent 集合。 */
+export interface CityAgents {
+  /**
+   * 添加一个已经实例化的 Agent，并建立它与当前 City 的资源绑定。
+   * 重复 Agent ID 或已属于其他 City 时必须失败。
+   */
+  add(agent: Agent): Agent;
+  /** 按稳定 ID 获取 Agent；不存在或正在移除时返回 null。 */
+  get(agent_id: string): Agent | null;
+  /** 返回当前 City 管理的 Agent 稳定快照。 */
+  list(): readonly Agent[];
+  /** 停止、释放并移除 Agent；不存在时返回 null。 */
+  remove(agent_id: string): Promise<Agent | null>;
+}
+
+/** City 管理的 Group 集合。 */
+export interface CityGroups {
+  /** 加入一个已经创建的 Group；成员必须已经加入当前 City。 */
+  add(group: Group): Group;
+  /** 按稳定 ID 获取 Group。 */
+  get(group_id: string): Group | null;
+  /** 返回当前 City 管理的 Group 稳定快照。 */
+  list(): readonly Group[];
+  /** 释放并移除 Group。 */
+  remove(group_id: string): Promise<Group | null>;
+}
+
+/** City 管理的 Workspace 集合。 */
+export interface CityWorkspaces {
+  /** 添加一个 Workspace 并交由 City 管理；重复实例直接返回，重复 ID 的其他实例失败。 */
+  add(workspace: WorkspaceBase): WorkspaceBase;
+  /** 按稳定 ID 获取 Workspace；不存在时返回 null。 */
+  get(workspace_id: string): WorkspaceBase | null;
+  /** 返回当前 City 管理的 Workspace 稳定快照。 */
+  list(): readonly WorkspaceBase[];
+}
+
+/** City 同时启动 HTTP 与 RPC transport 的监听参数。 */
+export interface CityListenOptions {
+  /** HTTP transport 监听参数；省略时不启动 HTTP。 */
+  http?: {
+    /** HTTP 监听地址。 */
+    host?: string;
+    /** HTTP 监听端口。 */
+    port: number;
+  };
+
+  /** RPC transport 监听参数；省略时不启动 RPC。 */
+  rpc?: {
+    /** RPC 监听地址。 */
+    host?: string;
+    /** RPC 监听端口。 */
+    port?: number;
+  };
+}

package/src/city/types/PluginHostContext.ts

@@ -0,0 +1,40 @@
+/**
+ * City 提供给 Agent Plugin factory 的宿主装配上下文。
+ *
+ * 设计边界（中文）：
+ * - City 负责读取 Profile、创建上下文并调用 factory；
+ * - factory 只负责创建一个新的 Plugin 实例；
+ * - Agent 负责接管实例后的运行、Action 与生命周期；
+ * - Agent 不反向依赖 City，也不读取 Plugin 安装目录。
+ */
+
+import type { JsonObject, Logger } from "@/index.js";
+
+/** City 可以为未来宿主能力增加的显式扩展集合。 */
+export type PluginHostExtensions = Readonly<Record<string, unknown>>;
+
+/** Agent Plugin factory 的宿主装配上下文。 */
+export interface PluginHostContext {
+  /** 当前 Plugin 的稳定 ID。 */
+  readonly plugin_id: string;
+
+  /** City 读取并校验后的 Plugin profile。 */
+  readonly profile: JsonObject;
+
+  /** Plugin 运行时私有数据目录；不用于存放 City 管理的 profile 配置。 */
+  readonly data_path: string;
+
+  /** City 提供的宿主日志器。 */
+  readonly logger: Logger;
+
+  /** City 为未来宿主能力保留的显式扩展区。 */
+  readonly extensions: PluginHostExtensions;
+}
+
+/** `plugin.json.agent` 指向的 Agent Plugin 模块。 */
+export interface AgentPluginModule<Plugin = unknown> {
+  /** 根据 City 宿主上下文创建一个新的 Agent Plugin 实例。 */
+  readonly default: (
+    context: PluginHostContext,
+  ) => Plugin | Promise<Plugin>;
+}

package/src/city/types/SerializedTransport.ts

@@ -0,0 +1,19 @@
+/** 串行 transport 生命周期内部类型。 */
+
+/** 启动 transport 后由生命周期对象持有的资源和 binding。 */
+export interface SerializedTransportStartResult<TResource, TBinding> {
+  /** 本次启动创建、关闭时需要释放的底层资源。 */
+  resource: TResource;
+
+  /** 对调用方可见的监听地址快照。 */
+  binding: TBinding;
+}
+
+/** 串行 transport 生命周期的依赖。 */
+export interface SerializedTransportOptions<TOptions, TResource, TBinding> {
+  /** 根据监听参数创建并启动底层资源。 */
+  start(options: TOptions): Promise<SerializedTransportStartResult<TResource, TBinding>>;
+
+  /** 释放一个已经成功启动的底层资源。 */
+  stop(resource: TResource): Promise<void>;
+}