@downcity/agent 1.1.337 → 1.1.399

package/src/city/runtime/City.ts

@@ -0,0 +1,425 @@
+/**
+ * City：Workspace、Embassy 与统一 transport 的资源容器。
+ *
+ * City 不创建 Agent、Session 或 Plugin。应用创建 Agent 后通过
+ * `city.agents.add(agent)` 加入当前容器；City 管理 Agent 集合、Workspace/Embassy
+ * 资源与统一 transport。
+ */
+
+import { Agent } from "@/agent/Agent.js";
+import { Group } from "@/group/Group.js";
+import {
+  attach_agent_city,
+  attach_agent_storage,
+  attach_group_storage,
+  detach_group_storage,
+  create_workspace_entry,
+  detach_agent_city,
+  get_workspace_entry,
+} from "@/internal/index.js";
+import type { WorkspaceEntry } from "@/agent/WorkspaceEntry.js";
+import type { WorkspaceBase } from "@downcity/workspace";
+import type { StorageProvider } from "@downcity/workspace";
+import { MemoryStorageProvider } from "@downcity/workspace";
+import { CityHTTP } from "@/city/transport/http/CityHTTP.js";
+import { CityRPC } from "@/city/transport/rpc/CityRPC.js";
+import type {
+  CityAgents,
+  CityGroups,
+  CityListenOptions,
+  CityOptions,
+  CityRuntimeOptions,
+  CityWorkspaces,
+} from "@/city/types/City.js";
+
+/** Agent 实例索引与 transport 宿主。 */
+export class City {
+  /** City 持有的底层 Storage；默认是进程内存储。 */
+  readonly storage: StorageProvider;
+  /** 当前 City 引用的 Agent，按稳定 ID 索引。 */
+  private readonly agents_by_id = new Map<string, Agent>();
+
+  /** 当前 City 引用的 Group，按稳定 ID 索引。 */
+  private readonly groups_by_id = new Map<string, Group>();
+
+  /** City 面向应用的 Agent 集合入口。 */
+  readonly agents: CityAgents;
+
+  /** City 面向宿主的 Group 集合入口。 */
+  readonly groups: CityGroups;
+
+  /** City 面向宿主的 Workspace 集合入口。 */
+  readonly workspaces: CityWorkspaces;
+
+  /** City 持有的 Workspace 资源，按稳定 ID 索引。 */
+  private readonly workspaces_by_id = new Map<string, WorkspaceBase>();
+
+  /** City 绑定的 Embassy 服务入口。 */
+  readonly embassy?: CityOptions["embassy"];
+
+  /** 正在解除注册的 Agent；对查询立即不可见，失败后恢复可见。 */
+  private readonly removing_agent_ids = new Set<string>();
+
+  /** 每个 Agent 当前唯一的解除注册流程。 */
+  private readonly removal_promises = new Map<string, Promise<Agent | null>>();
+
+  /** 宿主提供的按需 Workspace 创建能力。 */
+  private readonly resolve_workspace?: CityRuntimeOptions["resolve_workspace"];
+
+  /** 相同 Agent/Workspace 目标当前唯一的进入流程。 */
+  private readonly workspace_entry_promises = new Map<string, Promise<WorkspaceEntry>>();
+
+  /** 当前 City 唯一的 HTTP transport。 */
+  private readonly http_transport: CityHTTP;
+
+  /** 当前 City 唯一的 RPC transport。 */
+  private readonly rpc_transport: CityRPC;
+
+  /** City transport 组合操作的唯一串行链。 */
+  private transport_operation_chain: Promise<void> = Promise.resolve();
+
+  /** City 自身的生命周期状态。 */
+  private city_status: "active" | "closing" | "closed" = "active";
+
+  /** City 关闭流程；并发调用共享同一个 Promise。 */
+  private close_promise?: Promise<void>;
+
+  constructor(options: CityOptions = {}) {
+    this.storage = options.storage || new MemoryStorageProvider();
+    this.embassy = options.embassy;
+    for (const workspace of options.workspaces ?? []) {
+      const workspace_id = String(workspace?.id || "").trim();
+      if (!workspace_id) throw new Error("City requires Workspace with a stable id");
+      if (this.workspaces_by_id.has(workspace_id)) {
+        throw new Error(`Workspace already exists in City: ${workspace_id}`);
+      }
+      this.bind_workspace_shell(workspace);
+      this.workspaces_by_id.set(workspace_id, workspace);
+    }
+    const runtime_options = options.runtime ?? {};
+    this.resolve_workspace = runtime_options.resolve_workspace;
+    this.http_transport = new CityHTTP(this, runtime_options.http);
+    this.rpc_transport = new CityRPC(this, runtime_options.rpc);
+    this.agents = Object.freeze({
+      add: (agent) => this.add_agent(agent),
+      get: (agent_id) => this.get_agent(agent_id),
+      list: () => this.list_agents(),
+      remove: async (agent_id) => await this.remove_agent(agent_id),
+    });
+    this.groups = Object.freeze({
+      add: (group: Group) => this.add_group(group),
+      get: (group_id: string) => this.get_group(group_id),
+      list: () => this.list_groups(),
+      remove: async (group_id: string) => await this.remove_group(group_id),
+    });
+    this.workspaces = Object.freeze({
+      add: (workspace) => this.add_workspace(workspace),
+      get: (workspace_id) => this.get_workspace(workspace_id),
+      list: () => this.list_workspaces(),
+    });
+  }
+
+  /** 按稳定 ID 获取 City 管理的 Group。 */
+  private get_group(group_id_input: string): Group | null {
+    return this.groups_by_id.get(String(group_id_input || "").trim()) ?? null;
+  }
+
+  /** 返回 City 管理的 Group 稳定快照。 */
+  private list_groups(): readonly Group[] {
+    return [...this.groups_by_id.values()];
+  }
+
+  /** 将已创建 Group 加入 City，并校验成员属于当前 City。 */
+  private add_group(group: Group): Group {
+    this.assert_active();
+    if (!group?.id) throw new Error("City requires a Group with a stable ID");
+    const existing = this.groups_by_id.get(group.id);
+    if (existing && existing !== group) throw new Error(`Group already exists in City: ${group.id}`);
+    if (existing) return existing;
+    for (const member of group.members) {
+      if (this.agents_by_id.get(member.id) !== member) {
+        throw new Error(`Group member is not registered in City: ${member.id}`);
+      }
+    }
+    attach_group_storage(group, this.storage, this);
+    this.groups_by_id.set(group.id, group);
+    return group;
+  }
+
+  /** 释放并移除一个 Group。 */
+  private async remove_group(group_id_input: string): Promise<Group | null> {
+    const group_id = String(group_id_input || "").trim();
+    const group = this.groups_by_id.get(group_id) ?? null;
+    if (!group) return null;
+    await group.dispose();
+    await detach_group_storage(group, this);
+    this.groups_by_id.delete(group_id);
+    return group;
+  }
+
+  /** 返回 City 持有的 Workspace；不存在时返回 null。 */
+  /** 内部 AgentCity 协议；用户应使用 `city.workspaces.get()`。 */
+  get_workspace(workspace_id_input: string): WorkspaceBase | null {
+    const workspace_id = String(workspace_id_input || "").trim();
+    return this.workspaces_by_id.get(workspace_id) ?? null;
+  }
+
+  /** 返回 City 持有的 Workspace 稳定快照。 */
+  private list_workspaces(): readonly WorkspaceBase[] {
+    return [...this.workspaces_by_id.values()];
+  }
+
+  /** 返回当前 City 已注册 Agent 的稳定快照。 */
+  private list_agents(): readonly Agent[] {
+    return [...this.agents_by_id.entries()]
+      .filter(([agent_id]) => !this.removing_agent_ids.has(agent_id))
+      .map(([, agent]) => agent);
+  }
+
+  /** 按稳定 ID 返回可直接使用的 Agent；不存在时返回 null。 */
+  private get_agent(agent_id_input: string): Agent | null {
+    const agent_id = String(agent_id_input || "").trim();
+    if (this.removing_agent_ids.has(agent_id)) return null;
+    return this.agents_by_id.get(agent_id) ?? null;
+  }
+
+  /** 按稳定 ID 返回内部 transport 所需 Agent；不存在时抛出明确错误。 */
+  private require_agent(agent_id_input: string): Agent {
+    const agent_id = String(agent_id_input || "").trim();
+    const agent = this.get_agent(agent_id);
+    if (!agent) throw new Error(`Agent not found in City: ${agent_id}`);
+    return agent;
+  }
+
+  /** 按 Agent ID 与 Workspace ID 返回 transport 所需的明确执行作用域。 */
+  require_workspace(agent_id_input: string, workspace_id_input: string): WorkspaceEntry {
+    const agent = this.require_agent(agent_id_input);
+    const workspace_id = String(workspace_id_input || "").trim();
+    if (!workspace_id) throw new Error("City request requires workspace_id");
+    const entry = get_workspace_entry(agent, workspace_id);
+    if (!entry) {
+      throw new Error(`Agent "${agent.id}" has not entered Workspace: ${workspace_id}`);
+    }
+    return entry;
+  }
+
+  /** 按需解析并进入 Workspace；相同目标的并发请求共享一次创建流程。 */
+  async enter_workspace(
+    agent_id_input: string,
+    workspace_id_input: string,
+  ): Promise<WorkspaceEntry> {
+    const agent = this.require_agent(agent_id_input);
+    const workspace_id = String(workspace_id_input || "").trim();
+    if (!workspace_id) throw new Error("City request requires workspace_id");
+    const existing = get_workspace_entry(agent, workspace_id);
+    if (existing) return existing;
+    const city_workspace = this.get_workspace(workspace_id);
+    if (city_workspace) return create_workspace_entry(agent, city_workspace);
+    if (!this.resolve_workspace) {
+      throw new Error(`Agent "${agent.id}" has not entered Workspace: ${workspace_id}`);
+    }
+    const target_key = `${agent.id}/${workspace_id}`;
+    const current = this.workspace_entry_promises.get(target_key);
+    if (current) return await current;
+    const entry_promise = (async () => {
+      const workspace = await this.resolve_workspace!(agent, workspace_id);
+      if (workspace.id !== workspace_id) {
+        await workspace.dispose().catch(() => undefined);
+        throw new Error(
+          `Resolved Workspace ID mismatch: expected ${workspace_id}, received ${workspace.id}`,
+        );
+      }
+      this.add_workspace(workspace);
+      return create_workspace_entry(agent, workspace);
+    })();
+    this.workspace_entry_promises.set(target_key, entry_promise);
+    try {
+      return await entry_promise;
+    } finally {
+      if (this.workspace_entry_promises.get(target_key) === entry_promise) {
+        this.workspace_entry_promises.delete(target_key);
+      }
+    }
+  }
+
+  /** 停止、释放并从 City 移除指定 Agent。 */
+  private async remove_agent(agent_id_input: string): Promise<Agent | null> {
+    const agent_id = String(agent_id_input || "").trim();
+    const existing_removal = this.removal_promises.get(agent_id);
+    if (existing_removal) return await existing_removal;
+    const agent = this.agents_by_id.get(agent_id) ?? null;
+    if (!agent) return null;
+    this.removing_agent_ids.add(agent_id);
+    const removal = (async () => {
+      try {
+        await this.http_transport.detach_agent(agent_id);
+        const dependent_groups = [...this.groups_by_id.values()]
+          .filter((group) => group.members.some((member) => member === agent));
+        await Promise.allSettled(dependent_groups.map(async (group) => {
+          await group.dispose();
+          this.groups_by_id.delete(group.id);
+        }));
+        await agent.dispose();
+        this.release_agent(agent);
+        return agent;
+      } finally {
+        this.removing_agent_ids.delete(agent_id);
+      }
+    })();
+    this.removal_promises.set(agent_id, removal);
+    try {
+      return await removal;
+    } finally {
+      if (this.removal_promises.get(agent_id) === removal) {
+        this.removal_promises.delete(agent_id);
+      }
+    }
+  }
+
+  /** 启动 City 唯一的 HTTP/RPC transport。 */
+  async http(options: Parameters<CityHTTP["listen"]>[0]): Promise<CityHTTP> {
+    this.assert_active();
+    await this.enqueue_transport_operation(async () => {
+      await this.http_transport.listen(options);
+    });
+    return this.http_transport;
+  }
+
+  /** 启动 City 唯一的 RPC transport。 */
+  async rpc(options?: Parameters<CityRPC["listen"]>[0]): Promise<CityRPC> {
+    this.assert_active();
+    await this.enqueue_transport_operation(async () => {
+      await this.rpc_transport.listen(options);
+    });
+    return this.rpc_transport;
+  }
+
+  /** 启动 City 唯一的 HTTP/RPC transport。 */
+  async listen(options: CityListenOptions): Promise<void> {
+    this.assert_active();
+    await this.enqueue_transport_operation(async () => {
+      const started: Array<() => Promise<void>> = [];
+      try {
+        if (options.rpc) {
+          const was_listening = Boolean(this.rpc_transport.binding());
+          await this.rpc_transport.listen(options.rpc);
+          if (!was_listening) started.push(async () => await this.rpc_transport.close());
+        }
+        if (options.http) {
+          const was_listening = Boolean(this.http_transport.binding());
+          await this.http_transport.listen(options.http);
+          if (!was_listening) started.push(async () => await this.http_transport.close());
+        }
+      } catch (error) {
+        await Promise.allSettled(started.reverse().map(async (close) => await close()));
+        throw error;
+      }
+    });
+  }
+
+  /** 幂等关闭 transport，并按依赖顺序释放绑定 Agent 与 City Workspace。 */
+  async close(): Promise<void> {
+    if (this.city_status === "closed") return;
+    if (!this.close_promise) {
+      const close_operation = this.enqueue_transport_operation(async () => {
+        this.city_status = "closing";
+        const results: PromiseSettledResult<unknown>[] = [];
+        results.push(...await Promise.allSettled([
+          this.http_transport.close(),
+          this.rpc_transport.close(),
+        ]));
+        results.push(...await Promise.allSettled(
+          [...this.groups_by_id.values()].map(async (group) => {
+            await group.dispose();
+            await detach_group_storage(group, this);
+          }),
+        ));
+        results.push(...await Promise.allSettled(this.agents.list().map(async (agent) => await agent.dispose())));
+        results.push(...await Promise.allSettled(
+          [...this.workspaces_by_id.values()].map(async (workspace) => await workspace.dispose()),
+        ));
+        results.push(...await Promise.allSettled([
+          this.storage.dispose?.() ?? Promise.resolve(),
+        ]));
+        const errors = results.flatMap((result) =>
+          result.status === "rejected" ? [result.reason] : [],
+        );
+        if (errors.length > 0) {
+          this.city_status = "active";
+          throw new AggregateError(errors, "City transport close failed");
+        }
+        this.agents_by_id.clear();
+        this.groups_by_id.clear();
+        this.workspaces_by_id.clear();
+        this.city_status = "closed";
+      });
+      this.close_promise = close_operation.catch((error) => {
+        this.close_promise = undefined;
+        throw error;
+      });
+    }
+    await this.close_promise;
+  }
+
+  /** 将已创建 Agent 加入集合并建立唯一 City 绑定。 */
+  private add_agent(agent: Agent): Agent {
+    this.assert_active();
+    if (!agent?.id) throw new Error("City requires an Agent with a stable ID");
+    if (this.agents_by_id.has(agent.id) || this.removing_agent_ids.has(agent.id)) {
+      throw new Error(`Agent already exists in City: ${agent.id}`);
+    }
+    attach_agent_city(agent, this);
+    attach_agent_storage(agent, this.storage);
+    this.agents_by_id.set(agent.id, agent);
+    return agent;
+  }
+
+  /** Agent 自行释放时清除 City 运行时引用。 */
+  release_agent(agent: { readonly id: string }): void {
+    const current = this.agents_by_id.get(agent.id);
+    if (!current || current !== agent) return;
+    detach_agent_city(current, this);
+    this.agents_by_id.delete(agent.id);
+    void this.http_transport.detach_agent(agent.id).catch(() => undefined);
+  }
+
+  /** 把宿主按需解析出的 Workspace 纳入 City 资源索引。 */
+  private add_workspace(workspace: WorkspaceBase): WorkspaceBase {
+    this.assert_active();
+    const workspace_id = String(workspace?.id || "").trim();
+    if (!workspace_id) throw new Error("City requires Workspace with a stable id");
+    const existing = this.workspaces_by_id.get(workspace_id);
+    if (existing && existing !== workspace) {
+      throw new Error(`Workspace already exists in City: ${workspace_id}`);
+    }
+    if (existing) return existing;
+    this.bind_workspace_shell(workspace);
+    this.workspaces_by_id.set(workspace_id, workspace);
+    return workspace;
+  }
+
+  /** 将 City 的底层 Storage 绑定到 Workspace 的 Shell 运行目录。 */
+  private bind_workspace_shell(workspace: WorkspaceBase): void {
+    workspace.shell?.bind({
+      root_path: workspace.path,
+      data_path: this.storage.open_scope(["workspaces", workspace.id, "shell"]).root_path,
+    });
+  }
+
+  /** 拒绝在 City 关闭后继续注入运行时资源。 */
+  private assert_active(): void {
+    if (this.city_status !== "active") {
+      throw new Error(`City is ${this.city_status}`);
+    }
+  }
+
+  /** 串行执行一次 City transport 组合操作。 */
+  private enqueue_transport_operation(operation: () => Promise<void>): Promise<void> {
+    const result = this.transport_operation_chain.then(operation);
+    this.transport_operation_chain = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+}

package/src/city/transport/SerializedTransport.ts

@@ -0,0 +1,65 @@
+/**
+ * 串行 transport 生命周期。
+ *
+ * 该对象是 HTTP/RPC Server 状态的唯一拥有者。listen 与 close 按调用顺序执行，
+ * 因此启动过程中收到 close 时，会先完成启动再立即释放，不会留下失联端口。
+ */
+
+import type { SerializedTransportOptions } from "@/city/types/SerializedTransport.js";
+
+/** 管理一个可重复监听和关闭的底层 transport。 */
+export class SerializedTransport<TOptions, TResource, TBinding> {
+  /** transport 操作的唯一串行链。 */
+  private operation_chain: Promise<void> = Promise.resolve();
+
+  /** 当前已经成功启动的底层资源。 */
+  private current_resource: TResource | null = null;
+
+  /** 当前监听地址；未监听时为空。 */
+  private current_binding: TBinding | null = null;
+
+  constructor(
+    /** 创建和释放底层资源的实现。 */
+    private readonly options: SerializedTransportOptions<TOptions, TResource, TBinding>,
+  ) {}
+
+  /** 按调用顺序启动 transport；已监听时返回现有 binding。 */
+  async listen(options: TOptions): Promise<TBinding> {
+    return await this.enqueue(async () => {
+      if (this.current_binding) return this.current_binding;
+      const started = await this.options.start(options);
+      this.current_resource = started.resource;
+      this.current_binding = started.binding;
+      return started.binding;
+    });
+  }
+
+  /** 按调用顺序关闭 transport；没有监听时直接完成。 */
+  async close(): Promise<void> {
+    await this.enqueue(async () => {
+      const resource = this.current_resource;
+      if (!resource) return;
+      await this.options.stop(resource);
+      // 释放成功后才提交 stopped 状态；失败时保留句柄，允许调用方重试收口。
+      if (this.current_resource === resource) {
+        this.current_resource = null;
+        this.current_binding = null;
+      }
+    });
+  }
+
+  /** 返回当前已完成监听的 binding 快照。 */
+  binding(): TBinding | null {
+    return this.current_binding;
+  }
+
+  /** 将一次状态变化接到唯一操作链，并保证失败后后续操作仍可继续。 */
+  private enqueue<TResult>(operation: () => Promise<TResult>): Promise<TResult> {
+    const result = this.operation_chain.then(operation);
+    this.operation_chain = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+}

package/src/city/transport/http/AgentHTTP.ts

@@ -0,0 +1,176 @@
+/**
+ * AgentHTTP：把本地 Agent 暴露为最小 SDK HTTP 面的对外类。
+ *
+ * 关键点（中文）
+ * - 仅承载 RemoteAgent 对应的 SDK transport（`/api/sdk/sessions/*`）。
+ * - `router()` 返回一个 `Hono` 子路由，调用方 `app.route("/", agent_http.router())` 即可挂载。
+ * - `server()` 返回一个独立 HTTP server 句柄，按需自启、自停。
+ * - 同一个实例多次取 router/server 都返回缓存对象，避免重复注册。
+ */
+
+import http from "node:http";
+import { Hono } from "hono";
+import { create_workspace_entry } from "@/internal/index.js";
+import type { Agent } from "@/agent/Agent.js";
+import type { AgentSessionCollection } from "@/types/agent/AgentSessionCollection.js";
+import type { WorkspaceBase } from "@downcity/workspace";
+import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
+import { register_sdk_session_routes } from "@/city/transport/http/routes/SessionRoutes.js";
+import { register_runtime_routes } from "@/city/transport/http/routes/RuntimeRoutes.js";
+import { create_node_http_server } from "@/city/transport/http/NodeHttpAdapter.js";
+import { SerializedTransport } from "@/city/transport/SerializedTransport.js";
+import type {
+  AgentHttpBinding,
+  AgentHttpListenOptions,
+} from "@/city/transport/types/AgentHttpBinding.js";
+import type { AgentHttpRuntimeOptions } from "@/city/transport/types/AgentHttpRuntime.js";
+
+const DEFAULT_HTTP_HOST = "127.0.0.1";
+
+/**
+ * AgentHTTP server 句柄。
+ */
+export interface AgentHttpServerHandle {
+  /** 监听 HTTP 端口。 */
+  listen(options: AgentHttpListenOptions): Promise<AgentHttpBinding>;
+  /** 关闭当前 HTTP server。 */
+  close(): Promise<void>;
+  /** 当前监听绑定信息，未 listen 时为 `null`。 */
+  binding(): AgentHttpBinding | null;
+}
+
+/**
+ * 把一个 `WorkspaceEntry` 暴露为最小 SDK HTTP 面。
+ */
+export class AgentHTTP {
+  private readonly agent: Agent;
+  private readonly workspace?: WorkspaceBase;
+  private readonly plugins: AgentPlugins;
+  private readonly session_collection: AgentSessionCollection;
+  private readonly runtime_options: AgentHttpRuntimeOptions;
+  private cached_router: Hono | null = null;
+  private cached_server: AgentHttpServerHandle | null = null;
+
+  constructor(
+    agent_or_workspace: Agent | { agent: Agent; workspace: WorkspaceBase; plugins: AgentPlugins },
+    workspace_or_options?: WorkspaceBase | AgentHttpRuntimeOptions,
+    runtime_options: AgentHttpRuntimeOptions = {},
+  ) {
+    if (workspace_or_options && "id" in workspace_or_options && "path" in workspace_or_options) {
+      const agent = "agent" in agent_or_workspace ? agent_or_workspace.agent : agent_or_workspace;
+      this.agent = agent;
+      this.workspace = workspace_or_options;
+      this.plugins = "agent" in agent_or_workspace
+        ? agent_or_workspace.plugins
+        : create_workspace_entry(agent, workspace_or_options).plugins;
+      this.session_collection = create_workspace_entry(agent, workspace_or_options).sessions;
+      this.runtime_options = runtime_options;
+      return;
+    }
+      const entry = agent_or_workspace as { agent?: Agent; workspace?: WorkspaceBase; plugins?: AgentPlugins };
+      this.agent = entry.agent || agent_or_workspace as Agent;
+      this.workspace = entry.workspace;
+      this.plugins = entry.plugins || this.agent.plugins as unknown as AgentPlugins;
+      this.session_collection = this.workspace
+        ? create_workspace_entry(this.agent, this.workspace).sessions
+        : this.agent.sessions;
+    this.runtime_options = (workspace_or_options as AgentHttpRuntimeOptions | undefined) ?? {};
+  }
+
+  /**
+   * 返回一个挂载到外部 hono server 用的子路由。
+   *
+   * 说明（中文）
+   * - 多次调用返回同一个 hono 实例，避免重复注册。
+   * - 不在这里附加 CORS / logger，由调用方按需在自己的入口 hono 上挂中间件。
+   */
+  router(): Hono {
+    if (this.cached_router) return this.cached_router;
+    const router = new Hono();
+    register_sdk_session_routes(router, this.session_collection, this.workspace, {
+      resolve_session_model: this.runtime_options.resolve_session_model,
+    });
+    register_runtime_routes(router, this.plugins);
+    this.cached_router = router;
+    return router;
+  }
+
+  /**
+   * 返回独立 HTTP server 句柄。
+   */
+  server(): AgentHttpServerHandle {
+    if (this.cached_server) return this.cached_server;
+    const handle = create_agent_http_server_handle(this.router());
+    this.cached_server = handle;
+    return handle;
+  }
+
+  /**
+   * 关闭通过本实例 `server()` 启动的 HTTP server。
+   *
+   * 说明（中文）
+   * - 仅作用于 `server()` 创建的独立 HTTP server。
+   * - `router()` 挂到外部 hono 的场景由调用方自己管理生命周期。
+   */
+  async close(): Promise<void> {
+    const handle = this.cached_server;
+    if (!handle) return;
+    await handle.close();
+  }
+}
+
+/** 为已装配完成的 Hono Router 创建独立 Node HTTP Server 句柄。 */
+export function create_agent_http_server_handle(app: Hono): AgentHttpServerHandle {
+  const lifecycle = new SerializedTransport<
+    AgentHttpListenOptions,
+    http.Server,
+    AgentHttpBinding
+  >({
+    start: async (options) => {
+      const host = String(options.host || DEFAULT_HTTP_HOST).trim() || DEFAULT_HTTP_HOST;
+      const port = options.port;
+      if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error("AgentHTTP server requires a valid TCP port");
+      }
+      const server = create_node_http_server({ app, host, port });
+      await new Promise<void>((resolve, reject) => {
+        const on_error = (error: Error): void => {
+          server.off("error", on_error);
+          // listen 失败时该 Server 不会进入生命周期对象，立即清理监听器和句柄。
+          try {
+            server.close();
+          } catch {
+            // 未进入监听态时 close 可能抛出 ERR_SERVER_NOT_RUNNING，可安全忽略。
+          }
+          reject(error);
+        };
+        server.once("error", on_error);
+        server.listen(port, host, () => {
+          server.off("error", on_error);
+          resolve();
+        });
+      });
+      return {
+        resource: server,
+        binding: { url: `http://${host}:${port}`, host, port },
+      };
+    },
+    stop: async (server) => {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+      });
+    },
+  });
+
+  return {
+    async listen(options: AgentHttpListenOptions): Promise<AgentHttpBinding> {
+      return await lifecycle.listen(options);
+    },
+    async close(): Promise<void> {
+      await lifecycle.close();
+    },
+    binding(): AgentHttpBinding | null {
+      return lifecycle.binding();
+    },
+  };
+}