@downcity/agent 1.1.13 → 1.1.15

package/src/sdk/AgentSdkTypes.ts

@@ -13,6 +13,9 @@ import type { JsonValue } from "@/types/common/Json.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 import type { AgentPlatformRuntime } from "@/types/host/AgentHost.js";
+import type { LocalRpcServerHandle } from "@/types/rpc/LocalRpc.js";
+import type { ServerInstance } from "@/server/http/Server.js";
+import type { Session } from "@/sdk/Session.js";
 
 /**
  * 本地 Agent 构造参数。
@@ -61,6 +64,15 @@ export interface AgentOptions {
    */
   services?: BaseService[];
 
+  /**
+   * 是否自动装配全部内建 service。
+   *
+   * 关键点（中文）
+   * - 适合 city 这类宿主进程直接 `new Agent(...)` 的场景。
+   * - 未开启时，默认只使用显式传入的 `services`。
+   */
+  useBuiltinServices?: boolean;
+
   /**
    * 当前 agent 显式注册的 plugin 定义集合。
    *
@@ -71,6 +83,15 @@ export interface AgentOptions {
    */
   plugins?: Plugin[];
 
+  /**
+   * 是否自动装配全部内建 plugin。
+   *
+   * 关键点（中文）
+   * - 适合 city 这类宿主进程直接 `new Agent(...)` 的场景。
+   * - 未开启时，默认只使用显式传入的 `plugins`。
+   */
+  useBuiltinPlugins?: boolean;
+
   /**
    * 当前 agent 显式注入的平台能力集合。
    *
@@ -79,6 +100,143 @@ export interface AgentOptions {
    * - 推荐由宿主产品显式传入，避免 SDK 本地实例隐式依赖 city。
    */
   platform?: AgentPlatformRuntime;
+
+  /**
+   * 在 session 初始化后执行的宿主配置钩子。
+   *
+   * 关键点（中文）
+   * - SDK 不负责默认模型策略，宿主可在这里统一为 session 注入 model 等运行配置。
+   * - 该钩子只在 session 首次创建时触发一次，适合做实例级默认装配。
+   */
+  configureSession?: (session: Session) => Promise<void> | void;
+}
+
+/**
+ * Agent 启动参数。
+ */
+export interface AgentStartOptions {
+  /**
+   * 是否启动 HTTP 服务。
+   *
+   * 关键点（中文）
+   * - `false` 表示不启动。
+   * - 传对象时会按给定 host/port 启动。
+   * - 省略时默认不启动，避免 SDK 本地嵌入场景误开端口。
+   */
+  http?: false | AgentHttpStartOptions;
+
+  /**
+   * 是否启动本地 RPC 服务。
+   *
+   * 关键点（中文）
+   * - `true` 时启动主 local RPC server。
+   * - 省略或 `false` 时不启动。
+   */
+  rpc?: boolean;
+
+  /**
+   * 是否启动当前 agent 的 services。
+   *
+   * 关键点（中文）
+   * - 默认 `true`。
+   * - `false` 适合只需要 session 能力、不希望启动后台能力的嵌入场景。
+   */
+  services?: boolean;
+}
+
+/**
+ * Agent 停止结果快照。
+ */
+export interface AgentStopResult {
+  /**
+   * 本次是否实际停止了 HTTP 服务。
+   */
+  httpStopped: boolean;
+
+  /**
+   * 本次是否实际停止了本地 RPC 服务。
+   */
+  rpcStopped: boolean;
+
+  /**
+   * 本次是否实际停止了 services。
+   */
+  servicesStopped: boolean;
+}
+
+/**
+ * Agent 启动后的状态快照。
+ */
+export interface AgentStartResult {
+  /**
+   * 当前 agent 是否已启动 HTTP 服务。
+   */
+  http?: AgentHttpBinding;
+
+  /**
+   * 当前 agent 是否已启动本地 RPC 服务。
+   */
+  rpc?: AgentRpcBinding;
+
+  /**
+   * 当前 agent 是否已启动 services。
+   */
+  servicesStarted: boolean;
+}
+
+/**
+ * Agent HTTP 启动参数。
+ */
+export interface AgentHttpStartOptions {
+  /**
+   * HTTP 监听主机。
+   */
+  host?: string;
+
+  /**
+   * HTTP 监听端口。
+   */
+  port?: number;
+}
+
+/**
+ * Agent HTTP 绑定信息。
+ */
+export interface AgentHttpBinding {
+  /**
+   * 对外访问地址。
+   */
+  baseUrl: string;
+
+  /**
+   * 当前 host。
+   */
+  host: string;
+
+  /**
+   * 当前 port。
+   */
+  port: number;
+
+  /**
+   * HTTP server 句柄。
+   */
+  server: ServerInstance;
+}
+
+/**
+ * Agent RPC 绑定信息。
+ */
+export interface AgentRpcBinding {
+  /**
+   * 当前本地 RPC endpoint。
+   */
+  endpoint: string;
+
+  /**
+   * 本地 RPC server 句柄。
+   */
+  server: LocalRpcServerHandle;
 }
 
 /**

package/src/sdk/RemoteAgent.ts

@@ -2,7 +2,7 @@
  * RemoteAgent：远程 SDK 客户端。
  *
  * 关键点（中文）
- * - 面向已启动 `agent.http.start()` 的远程/本地 HTTP 服务。
+ * - 面向已通过 `agent.start({ http: { ... } })` 暴露出来的远程/本地 HTTP 服务。
  * - 与本地 `Agent` 尽量保持同一套 session 使用面。
  */
 

package/src/sdk/Session.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
- * - 统一收口消息落盘、默认模型配置、run/stream/fork 等高层 API。
+ * - 统一收口消息落盘、session 级模型配置、run/stream/fork 等高层 API。
  * - 内部继续复用 `Executor` / `JsonlSessionHistoryComposer` / `Runner`。
  */
 
@@ -34,19 +34,19 @@ import {
   readSessionMetadata,
   resolveSystemTimezone,
   writeSessionMetadata,
-} from "@/sdk/SessionMetadata.js";
+} from "@/sdk/session/index.js";
 import {
   getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
-} from "@/sdk/Paths.js";
+} from "@/sdk/session/index.js";
 import { AsyncQueue } from "@/sdk/AsyncQueue.js";
-import type { SessionPort } from "@/runtime/AgentContextTypes.js";
+import type { SessionPort } from "@/core/AgentContextTypes.js";
 import { pushUiMessageChunkAsSdkEvent } from "@/sdk/StreamEvents.js";
 import {
   persistSdkAssistantResult,
   touchSessionMetadata,
-} from "@/sdk/SessionPersistence.js";
-import { createSessionServicePort } from "@/sdk/SessionServicePort.js";
+} from "@/sdk/session/index.js";
+import { createSessionServicePort } from "@/sdk/session/index.js";
 
 type SessionOptions = {
   /**
@@ -332,6 +332,11 @@ export class Session {
     if (!query) {
       throw new Error("session.run requires a non-empty query");
     }
+    if (!this.sessionConfig.model) {
+      throw new Error(
+        `Session "${this.id}" requires a configured model. Call session.set({ model }) first or let the host configure the session during creation.`,
+      );
+    }
     await this.appendUserMessage({ text: query });
     const result = await this.executor.run({
       query,
@@ -355,6 +360,11 @@ export class Session {
     if (!query) {
       throw new Error("session.stream requires a non-empty query");
     }
+    if (!this.sessionConfig.model) {
+      throw new Error(
+        `Session "${this.id}" requires a configured model. Call session.set({ model }) first or let the host configure the session during creation.`,
+      );
+    }
     const queue = new AsyncQueue<AgentSessionStreamEvent>();
     const toolNameByCallId = new Map<string, string>();
     await this.appendUserMessage({ text: query });

package/src/sdk/{SessionMetadata.ts → session/Metadata.ts}

@@ -12,7 +12,7 @@ import type {
   SessionHistoryMetaV1,
   SessionHistorySdkConfigV1,
 } from "@/session/types/SessionHistoryMeta.js";
-import { getSdkAgentSessionMetaPath } from "@/sdk/Paths.js";
+import { getSdkAgentSessionMetaPath } from "@/sdk/session/Paths.js";
 
 type ReadSessionMetadataInput = {
   /**

package/src/sdk/{Paths.ts → session/Paths.ts}

@@ -1,5 +1,5 @@
 /**
- * SDK Session 落盘路径规则。
+ * SDK Session 路径规则。
  *
  * 关键点（中文）
  * - 与旧 `.downcity/session/<sessionId>` 路径分开，避免不同 agent 在同一项目目录下互相污染。

package/src/sdk/{SessionPersistence.ts → session/Persistence.ts}

@@ -14,7 +14,7 @@ import type { AgentSessionConfigSnapshot } from "@/sdk/AgentSdkTypes.js";
 import {
   readSessionMetadata,
   writeSessionMetadata,
-} from "@/sdk/SessionMetadata.js";
+} from "@/sdk/session/Metadata.js";
 
 /**
  * SDK Session 元数据写入参数。

package/src/sdk/{SessionServicePort.ts → session/ServicePort.ts}

@@ -6,7 +6,7 @@
  * - service 侧直接复用底层 `Executor` 协议，避免 SDK `run()` 包装层重复补写消息。
  */
 
-import type { SessionPort } from "@/runtime/AgentContextTypes.js";
+import type { SessionPort } from "@/core/AgentContextTypes.js";
 
 /**
  * 构造 SDK SessionPort 的参数。

package/src/sdk/session/index.ts

@@ -0,0 +1,34 @@
+/**
+ * SDK Session 辅助模块聚合入口。
+ *
+ * 关键点（中文）
+ * - 这里收口 `Session.ts` 依赖的路径、元数据、持久化与 service 端口适配能力。
+ * - 避免这些实现继续平铺在 `sdk/` 顶层，提升目录语义清晰度。
+ */
+
+export {
+  getSdkAgentDirPath,
+  getSdkAgentRpcEndpointPath,
+  getSdkAgentSessionArchiveDirPath,
+  getSdkAgentSessionDirPath,
+  getSdkAgentSessionMessagesDirPath,
+  getSdkAgentSessionMessagesPath,
+  getSdkAgentSessionMetaPath,
+  getSdkAgentSessionsRootDirPath,
+  getSdkAgentsRootDirPath,
+  getSdkDowncityDirPath,
+} from "./Paths.js";
+export {
+  inferModelLabel,
+  patchSessionModelLabel,
+  readSessionMetadata,
+  resolveSystemTimezone,
+  writeSessionMetadata,
+} from "./Metadata.js";
+export {
+  persistSdkAssistantResult,
+  touchSessionMetadata,
+} from "./Persistence.js";
+export {
+  createSessionServicePort,
+} from "./ServicePort.js";

package/src/server/http/Server.ts

@@ -12,20 +12,20 @@ import { cors } from "hono/cors";
 import { logger } from "hono/logger";
 import http from "node:http";
 import { logger as serverLogger } from "@/utils/logger/Logger.js";
-import { executeRouter } from "@/server/http/execute/execute.js";
+import { createExecuteRouter } from "@/server/http/execute/execute.js";
 import { healthRouter } from "@/server/http/health/health.js";
 import {
-  ensureServiceActionRoutesRegistered,
-  servicesRouter,
+  createServicesRouter,
 } from "@/server/http/services/services.js";
-import { pluginsRouter } from "@/server/http/plugins/plugins.js";
-import { staticRouter } from "@/server/http/static/static.js";
-import { controlRouter } from "@/server/http/control/ControlRouter.js";
+import { createPluginsRouter } from "@/server/http/plugins/plugins.js";
+import { createStaticRouter } from "@/server/http/static/static.js";
+import { createControlRouter } from "@/server/http/control/ControlRouter.js";
 import {
-  listBuiltinPluginRuntimeAuthPolicies,
   registerBuiltinPluginHttpRoutes,
 } from "@/plugin/core/HttpRoutes.js";
-import { getAgentContext } from "@/runtime/AgentRuntime.js";
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentCore } from "@/core/AgentCore.js";
 
 /**
  * Server 启动参数。
@@ -35,6 +35,12 @@ export interface ServerStartOptions {
   port: number;
   /** HTTP 服务监听主机。 */
   host: string;
+  /** 可选实例级 agent core。 */
+  core?: Pick<AgentCore, "getContext" | "getRuntime">;
+  /** 可选实例级 runtime 读取函数。 */
+  getAgentRuntime?: () => AgentRuntime;
+  /** 可选实例级 context 读取函数。 */
+  getAgentContext?: () => AgentContext;
 }
 
 /**
@@ -49,11 +55,41 @@ export interface ServerInstance {
   stop(): Promise<void>;
 }
 
+type AgentServerBindings = {
+  getAgentRuntime: () => AgentRuntime;
+  getAgentContext: () => AgentContext;
+};
+
+function resolveServerBindings(options: Pick<
+  ServerStartOptions,
+  "core" | "getAgentRuntime" | "getAgentContext"
+>): AgentServerBindings {
+  const core = options.core;
+  if (core) {
+    return {
+      getAgentRuntime: () => core.getRuntime(),
+      getAgentContext: () => core.getContext(),
+    };
+  }
+  if (options.getAgentRuntime && options.getAgentContext) {
+    return {
+      getAgentRuntime: options.getAgentRuntime,
+      getAgentContext: options.getAgentContext,
+    };
+  }
+  throw new Error(
+    "createServerApp/startServer requires either core or both getAgentRuntime/getAgentContext",
+  );
+}
+
 /**
  * 创建主 Hono 应用。
  */
-export function createServerApp(): Hono {
+export function createServerApp(
+  options: Pick<ServerStartOptions, "core" | "getAgentRuntime" | "getAgentContext">,
+): Hono {
   const app = new Hono();
+  const bindings = resolveServerBindings(options);
 
   app.use("*", logger());
   app.use(
@@ -65,19 +101,28 @@ export function createServerApp(): Hono {
     }),
   );
 
-  // 关键点（中文）：service action 路由在 runtime ready 后再注册，避免命令级 import 副作用。
-  ensureServiceActionRoutesRegistered();
-
   // 关键点（中文）：按路由域挂载，server 模块只保留装配职责。
-  app.route("/", staticRouter);
+  app.route("/", createStaticRouter({
+    getAgentRuntime: bindings.getAgentRuntime,
+  }));
   app.route("/", healthRouter);
+  const servicesRouter = createServicesRouter({
+    getAgentContext: bindings.getAgentContext,
+  });
   app.route("/", servicesRouter);
-  app.route("/", pluginsRouter);
-  app.route("/", executeRouter);
-  app.route("/", controlRouter);
+  app.route("/", createPluginsRouter({
+    getAgentContext: bindings.getAgentContext,
+  }));
+  app.route("/", createExecuteRouter({
+    getAgentRuntime: bindings.getAgentRuntime,
+  }));
+  app.route("/", createControlRouter({
+    getAgentRuntime: bindings.getAgentRuntime,
+    getAgentContext: bindings.getAgentContext,
+  }));
   registerBuiltinPluginHttpRoutes({
     app,
-    getContext: getAgentContext,
+    getContext: bindings.getAgentContext,
   });
 
   return app;
@@ -89,7 +134,7 @@ export function createServerApp(): Hono {
 export async function startServer(
   options: ServerStartOptions,
 ): Promise<ServerInstance> {
-  const app = createServerApp();
+  const app = createServerApp(options);
   const server = createNodeServer(app, options);
 
   await new Promise<void>((resolve) => {

package/src/server/http/control/AuthControlService.ts

@@ -7,7 +7,7 @@
  * - 这样调用方不需要知道 plugin action 名称，也不需要依赖 `plugin/builtins/auth/*` 目录。
  */
 
-import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
 import type { JsonObject } from "@/types/common/Json.js";
 import type { AuthControlPayload } from "@/server/http/control/types/AuthControl.js";
 import type {

package/src/server/http/control/ControlAuthorizationRoutes.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Hono } from "hono";
-import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
 import {
   readAuthControlPayload,
   setAuthControlUserRole,

package/src/server/http/control/ControlRouter.ts

@@ -13,19 +13,35 @@
  */
 
 import { Hono } from "hono";
-import {
-  getAgentRuntime,
-  getAgentContext,
-} from "@/runtime/AgentRuntime.js";
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
 import { registerControlApiRoutes } from "@/server/http/control/ControlApiRoutes.js";
 
 /**
- * 单 agent control API 专用路由。
+ * control router 参数。
  */
-export const controlRouter = new Hono();
+type ControlRouterOptions = {
+  /**
+   * 读取当前 agent runtime。
+   */
+  getAgentRuntime: () => AgentRuntime;
+  /**
+   * 读取当前 agent 执行上下文。
+   */
+  getAgentContext: () => AgentContext;
+};
 
-registerControlApiRoutes({
-  app: controlRouter,
-  getAgentRuntime: getAgentRuntime,
-  getAgentContext: getAgentContext,
-});
+/**
+ * 创建单 agent control API 专用路由。
+ */
+export function createControlRouter(
+  options: ControlRouterOptions,
+): Hono {
+  const router = new Hono();
+  registerControlApiRoutes({
+    app: router,
+    getAgentRuntime: options.getAgentRuntime,
+    getAgentContext: options.getAgentContext,
+  });
+  return router;
+}

package/src/server/http/control/ExecuteBySession.ts

@@ -6,8 +6,8 @@
  * - 非 chat session 保留原有直接执行语义。
  */
 
-import type { AgentRuntime } from "@/runtime/AgentRuntime.js";
-import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
 import type { JsonObject } from "@/types/common/Json.js";
 import type { ControlSessionExecuteAttachmentInput } from "@/server/http/control/types/ControlSessionExecute.js";
 import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";

package/src/server/http/control/OverviewRoutes.ts

@@ -54,7 +54,9 @@ export function registerControlOverviewRoutes(
           executionContext: params.getAgentContext(),
           limit: sessionLimit,
         });
-        const services = listServiceStates();
+        const services = listServiceStates({
+          context: params.getAgentContext(),
+        });
         const taskResult = await listTaskDefinitions({
           projectRoot: runtime.rootPath,
         });
@@ -99,7 +101,9 @@ export function registerControlOverviewRoutes(
     app.get(routePath, (c) => {
       return c.json({
         success: true,
-        services: listServiceStates(),
+        services: listServiceStates({
+          context: params.getAgentContext(),
+        }),
       });
     });
   }

package/src/server/http/control/SessionSummaryStore.ts

@@ -7,7 +7,7 @@
  */
 
 import fs from "fs-extra";
-import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
 import {
   getDowncitySessionMessagesPath,
   getDowncitySessionRootDirPath,

package/src/server/http/control/types/ControlRoutes.ts

@@ -7,8 +7,8 @@
  */
 
 import type { Hono } from "hono";
-import type { AgentRuntime } from "@/runtime/AgentRuntimeTypes.js";
-import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
 
 /**
  * Control 路由注册入参。