@downcity/agent 1.1.13 → 1.1.14

package/src/sdk/Session.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
- * - 统一收口消息落盘、默认模型配置、run/stream/fork 等高层 API。
+ * - 统一收口消息落盘、session 级模型配置、run/stream/fork 等高层 API。
  * - 内部继续复用 `Executor` / `JsonlSessionHistoryComposer` / `Runner`。
  */
 
@@ -40,7 +40,7 @@ import {
   getSdkAgentSessionDirPath,
 } from "@/sdk/Paths.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,
@@ -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/SessionServicePort.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/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 路由注册入参。

package/src/server/http/execute/execute.ts

@@ -9,112 +9,128 @@
 
 import { Hono } from "hono";
 import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
-import { getAgentRuntime } from "@/runtime/AgentRuntime.js";
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
 import {
   pickLastSuccessfulChatSendText,
   resolveAssistantMessageForPersistence,
 } from "@/service/builtins/chat/runtime/UserVisibleText.js";
 
 /**
- * 执行入口路由。
+ * 执行入口路由参数。
  */
-export const executeRouter = new Hono();
+type ExecuteRouterOptions = {
+  /**
+   * 读取当前 agent runtime。
+   */
+  getAgentRuntime: () => AgentRuntime;
+};
 
-executeRouter.post("/api/execute", async (c) => {
-  let bodyText = "";
-  try {
-    bodyText = await c.req.text();
-  } catch {
-    return c.json(
-      { success: false, message: "Unable to read request body" },
-      400,
-    );
-  }
-
-  if (!bodyText) {
-    return c.json({ success: false, message: "Request body is empty" }, 400);
-  }
+/**
+ * 创建执行入口路由。
+ */
+export function createExecuteRouter(
+  options: ExecuteRouterOptions,
+): Hono {
+  const router = new Hono();
 
-  let body: {
-    instructions?: string;
-    chatId?: string;
-    userId?: string;
-    actorId?: string;
-    messageId?: string;
-  };
-  try {
-    body = JSON.parse(bodyText) as typeof body;
-  } catch {
-    return c.json(
-      {
-        success: false,
-        message: `JSON parse failed: ${bodyText.substring(0, 50)}...`,
-      },
-      400,
-    );
-  }
+  router.post("/api/execute", async (c) => {
+    let bodyText = "";
+    try {
+      bodyText = await c.req.text();
+    } catch {
+      return c.json(
+        { success: false, message: "Unable to read request body" },
+        400,
+      );
+    }
 
-  const instructions = body?.instructions;
-  const chatId =
-    typeof body?.chatId === "string" && body.chatId.trim()
-      ? body.chatId.trim()
-      : "default";
-  const actorId =
-    typeof body?.userId === "string" && body.userId.trim()
-      ? body.userId.trim()
-      : typeof body?.actorId === "string" && body.actorId.trim()
-        ? body.actorId.trim()
-        : "api";
+    if (!bodyText) {
+      return c.json({ success: false, message: "Request body is empty" }, 400);
+    }
 
-  if (!instructions) {
-    return c.json(
-      { success: false, message: "Missing instructions field" },
-      400,
-    );
-  }
+    let body: {
+      instructions?: string;
+      chatId?: string;
+      userId?: string;
+      actorId?: string;
+      messageId?: string;
+    };
+    try {
+      body = JSON.parse(bodyText) as typeof body;
+    } catch {
+      return c.json(
+        {
+          success: false,
+          message: `JSON parse failed: ${bodyText.substring(0, 50)}...`,
+        },
+        400,
+      );
+    }
 
-  try {
-    const sessionId = `api:chat:${chatId}`;
-    const agentState = getAgentRuntime();
-    const session = agentState.getSession(sessionId);
-    await session.appendUserMessage({
-      text: String(instructions),
-    });
+    const instructions = body?.instructions;
+    const chatId =
+      typeof body?.chatId === "string" && body.chatId.trim()
+        ? body.chatId.trim()
+        : "default";
+    const actorId =
+      typeof body?.userId === "string" && body.userId.trim()
+        ? body.userId.trim()
+        : typeof body?.actorId === "string" && body.actorId.trim()
+          ? body.actorId.trim()
+          : "api";
 
-    const result = await session.run({
-      query: String(instructions),
-    });
+    if (!instructions) {
+      return c.json(
+        { success: false, message: "Missing instructions field" },
+        400,
+      );
+    }
 
-    const userVisible = pickLastSuccessfulChatSendText(result.assistantMessage);
     try {
-      const messageForPersistence = resolveAssistantMessageForPersistence(
-        result.assistantMessage,
-      );
-      if (messageForPersistence) {
-        await session.appendAssistantMessage({
-          message: messageForPersistence,
-          fallbackText: userVisible,
-          extra: {
-            via: "api_execute",
-            note: "assistant_message_missing",
-            actorId,
-          },
-        });
-      }
-      const deferredInjectedMessages = drainDeferredPersistedUserMessages(
-        sessionId,
-      );
-      for (const message of deferredInjectedMessages) {
-        await session.appendUserMessage({
-          message,
-        });
+      const sessionId = `api:chat:${chatId}`;
+      const agentState = options.getAgentRuntime();
+      const session = agentState.getSession(sessionId);
+      await session.appendUserMessage({
+        text: String(instructions),
+      });
+
+      const result = await session.run({
+        query: String(instructions),
+      });
+
+      const userVisible = pickLastSuccessfulChatSendText(result.assistantMessage);
+      try {
+        const messageForPersistence = resolveAssistantMessageForPersistence(
+          result.assistantMessage,
+        );
+        if (messageForPersistence) {
+          await session.appendAssistantMessage({
+            message: messageForPersistence,
+            fallbackText: userVisible,
+            extra: {
+              via: "api_execute",
+              note: "assistant_message_missing",
+              actorId,
+            },
+          });
+        }
+        const deferredInjectedMessages = drainDeferredPersistedUserMessages(
+          sessionId,
+        );
+        for (const message of deferredInjectedMessages) {
+          await session.appendUserMessage({
+            message,
+          });
+        }
+      } catch {
+        // ignore
       }
-    } catch {
-      // ignore
+
+      return c.json(result);
+    } catch (error) {
+      return c.json({ success: false, message: String(error) }, 500);
     }
+  });
 
-    return c.json(result);
-  } catch (error) {
-    return c.json({ success: false, message: String(error) }, 500);
-  }
-});
+  return router;
+}

package/src/server/http/plugins/plugins.ts

@@ -8,60 +8,76 @@
  */
 
 import { Hono } from "hono";
-import { getAgentContext } from "@/runtime/AgentRuntime.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
 
 /**
- * Plugin 路由。
+ * Plugin 路由参数。
  */
-export const pluginsRouter = new Hono();
+type PluginsRouterOptions = {
+  /**
+   * 读取当前 agent 执行上下文。
+   */
+  getAgentContext: () => AgentContext;
+};
 
-pluginsRouter.get("/api/plugins/list", (c) => {
-  return c.json({
-    success: true,
-    plugins: getAgentContext().plugins.list(),
+/**
+ * 创建 plugin 路由。
+ */
+export function createPluginsRouter(
+  options: PluginsRouterOptions,
+): Hono {
+  const router = new Hono();
+
+  router.get("/api/plugins/list", (c) => {
+    return c.json({
+      success: true,
+      plugins: options.getAgentContext().plugins.list(),
+    });
   });
-});
 
-pluginsRouter.post("/api/plugins/availability", async (c) => {
-  const body = await c.req.json().catch(() => null);
-  const pluginName = String(body?.pluginName || "").trim();
+  router.post("/api/plugins/availability", async (c) => {
+    const body = await c.req.json().catch(() => null);
+    const pluginName = String(body?.pluginName || "").trim();
 
-  if (!pluginName) {
-    return c.json({ success: false, error: "pluginName is required" }, 400);
-  }
+    if (!pluginName) {
+      return c.json({ success: false, error: "pluginName is required" }, 400);
+    }
 
-  const availability =
-    await getAgentContext().plugins.availability(pluginName);
-  return c.json({
-    success: true,
-    pluginName,
-    availability,
+    const availability =
+      await options.getAgentContext().plugins.availability(pluginName);
+    return c.json({
+      success: true,
+      pluginName,
+      availability,
+    });
   });
-});
 
-pluginsRouter.post("/api/plugins/action", async (c) => {
-  const body = await c.req.json().catch(() => null);
-  const pluginName = String(body?.pluginName || "").trim();
-  const actionName = String(body?.actionName || "").trim();
+  router.post("/api/plugins/action", async (c) => {
+    const body = await c.req.json().catch(() => null);
+    const pluginName = String(body?.pluginName || "").trim();
+    const actionName = String(body?.actionName || "").trim();
 
-  if (!pluginName) {
-    return c.json({ success: false, error: "pluginName is required" }, 400);
-  }
-  if (!actionName) {
-    return c.json({ success: false, error: "actionName is required" }, 400);
-  }
+    if (!pluginName) {
+      return c.json({ success: false, error: "pluginName is required" }, 400);
+    }
+    if (!actionName) {
+      return c.json({ success: false, error: "actionName is required" }, 400);
+    }
 
-  const result = await getAgentContext().plugins.runAction({
-    plugin: pluginName,
-    action: actionName,
-    payload: body?.payload,
+    const result = await options.getAgentContext().plugins.runAction({
+      plugin: pluginName,
+      action: actionName,
+      payload: body?.payload,
+    });
+    return c.json(
+      {
+        ...result,
+        pluginName,
+        actionName,
+      },
+      result.success ? 200 : 400,
+    );
   });
-  return c.json(
-    {
-      ...result,
-      pluginName,
-      actionName,
-    },
-    result.success ? 200 : 400,
-  );
-});
+
+  return router;
+}