@downcity/agent 1.1.43 → 1.1.62

package/src/rpc/Server.ts

@@ -0,0 +1,302 @@
+/**
+ * Agent 本机 RPC Server。
+ *
+ * 职责说明（中文）
+ * - 为本机 `RemoteAgent(rpc://...)` 提供最小 SDK 会话访问面。
+ * - 当前只承载 Session actor 所需方法，不混入控制台 HTTP 语义。
+ * - 协议使用逐行 JSON（NDJSON），便于调试与事件流推送。
+ */
+
+import net from "node:net";
+import type {
+  AgentListSessionsInput,
+  AgentSessionCollection,
+} from "@/types/agent/AgentTypes.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+
+type RpcSessionRequest =
+  | {
+      id: string;
+      method: "sdk.sessions.list";
+      params?: AgentListSessionsInput;
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.create";
+      params?: {
+        sessionId?: string;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.get";
+      params: {
+        sessionId: string;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.prompt";
+      params: {
+        sessionId: string;
+        input: AgentSessionPromptInput;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.history";
+      params: {
+        sessionId: string;
+        input?: {
+          limit?: number;
+          cursor?: string;
+          order?: "asc" | "desc";
+          view?: "message" | "timeline";
+        };
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.system";
+      params: {
+        sessionId: string;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.fork";
+      params: {
+        sessionId: string;
+        messageId?: string;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.subscribe";
+      params: {
+        sessionId: string;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.unsubscribe";
+      params: {
+        subscriptionId: string;
+      };
+    };
+
+type RpcSuccessFrame = {
+  id: string;
+  success: true;
+  data?: unknown;
+};
+
+type RpcErrorFrame = {
+  id: string;
+  success: false;
+  error: string;
+};
+
+type RpcEventFrame = {
+  type: "event";
+  subscriptionId: string;
+  event: AgentSessionEvent;
+};
+
+type SocketSubscription = {
+  sessionId: string;
+  unsubscribe: () => void;
+};
+
+/**
+ * RPC Server 启动参数。
+ */
+export interface RpcServerStartOptions {
+  /** RPC 服务监听端口。 */
+  port: number;
+  /** RPC 服务监听主机。 */
+  host: string;
+  /** Session 集合访问口。 */
+  sessionCollection: AgentSessionCollection;
+}
+
+/**
+ * RPC Server 运行实例。
+ */
+export interface RpcServerInstance {
+  /** 当前监听 host。 */
+  host: string;
+  /** 当前监听 port。 */
+  port: number;
+  /** 当前访问 URL。 */
+  url: string;
+  /** 原生 net server。 */
+  server: net.Server;
+  /** 停止当前服务。 */
+  stop(): Promise<void>;
+}
+
+/**
+ * 启动 Agent 本机 RPC 服务。
+ */
+export async function startRpcServer(
+  options: RpcServerStartOptions,
+): Promise<RpcServerInstance> {
+  const server = net.createServer((socket) => {
+    const subscriptions = new Map<string, SocketSubscription>();
+    let buffered = "";
+
+    const cleanupSubscriptions = (): void => {
+      for (const subscription of subscriptions.values()) {
+        subscription.unsubscribe();
+      }
+      subscriptions.clear();
+    };
+
+    const writeFrame = (frame: RpcSuccessFrame | RpcErrorFrame | RpcEventFrame): void => {
+      socket.write(`${JSON.stringify(frame)}\n`);
+    };
+
+    const writeSuccess = (id: string, data?: unknown): void => {
+      writeFrame({
+        id,
+        success: true,
+        ...(data === undefined ? {} : { data }),
+      });
+    };
+
+    const writeError = (id: string, error: unknown): void => {
+      writeFrame({
+        id,
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    };
+
+    const handleRequest = async (request: RpcSessionRequest): Promise<void> => {
+      try {
+        switch (request.method) {
+          case "sdk.sessions.list": {
+            const page = await options.sessionCollection.listSessions(request.params);
+            writeSuccess(request.id, { page });
+            return;
+          }
+          case "sdk.sessions.create": {
+            const session = await options.sessionCollection.createSession(request.params);
+            writeSuccess(request.id, { session: await session.getInfo() });
+            return;
+          }
+          case "sdk.sessions.get": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            writeSuccess(request.id, { session: await session.getInfo() });
+            return;
+          }
+          case "sdk.sessions.prompt": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            const turn = await session.prompt(request.params.input);
+            writeSuccess(request.id, { turn: { id: turn.id } });
+            return;
+          }
+          case "sdk.sessions.history": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            const history = await session.history(request.params.input);
+            writeSuccess(request.id, { history });
+            return;
+          }
+          case "sdk.sessions.system": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            writeSuccess(request.id, { system: await session.system() });
+            return;
+          }
+          case "sdk.sessions.fork": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            const forked = await session.fork(request.params.messageId);
+            writeSuccess(request.id, { session: await forked.getInfo() });
+            return;
+          }
+          case "sdk.sessions.subscribe": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            const subscriptionId = `${request.params.sessionId}:${Date.now()}:${Math.random().toString(36).slice(2, 10)}`;
+            const unsubscribe = session.subscribe((event) => {
+              writeFrame({
+                type: "event",
+                subscriptionId,
+                event,
+              });
+            });
+            subscriptions.set(subscriptionId, {
+              sessionId: request.params.sessionId,
+              unsubscribe,
+            });
+            writeSuccess(request.id, { subscriptionId });
+            return;
+          }
+          case "sdk.sessions.unsubscribe": {
+            const subscription = subscriptions.get(request.params.subscriptionId);
+            if (subscription) {
+              subscription.unsubscribe();
+              subscriptions.delete(request.params.subscriptionId);
+            }
+            writeSuccess(request.id, { unsubscribed: true });
+            return;
+          }
+        }
+      } catch (error) {
+        writeError(request.id, error);
+      }
+    };
+
+    socket.on("data", (chunk) => {
+      buffered += chunk.toString("utf8");
+      let newlineIndex = buffered.indexOf("\n");
+      while (newlineIndex >= 0) {
+        const line = buffered.slice(0, newlineIndex).trim();
+        buffered = buffered.slice(newlineIndex + 1);
+        if (line) {
+          try {
+            const parsed = JSON.parse(line) as RpcSessionRequest;
+            void handleRequest(parsed);
+          } catch (error) {
+            writeFrame({
+              id: "parse",
+              success: false,
+              error: error instanceof Error ? error.message : String(error),
+            });
+          }
+        }
+        newlineIndex = buffered.indexOf("\n");
+      }
+    });
+
+    socket.on("error", () => {
+      cleanupSubscriptions();
+    });
+    socket.on("close", () => {
+      cleanupSubscriptions();
+    });
+    socket.on("end", () => {
+      cleanupSubscriptions();
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, options.host, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+
+  return {
+    host: options.host,
+    port: options.port,
+    url: `rpc://${options.host}:${options.port}`,
+    server,
+    async stop(): Promise<void> {
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      });
+    },
+  };
+}

package/src/runtime/host/daemon/Api.ts

@@ -39,7 +39,7 @@ export type DaemonJsonApiCallParams = {
    * 单次调用超时（毫秒）。
    *
    * 说明（中文）
-   * - 仅本地 IPC transport 当前会消费该参数。
+   * - HTTP daemon client 可消费该参数。
    * - 用于 `session execute`、`plugin command` 这类可能持续几十秒的请求，
    *   避免被默认短超时误判成“Agent server 未启动”。
    */

package/src/runtime/host/daemon/Client.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 业务模块统一通过 daemon API 与运行时通信。
- * - 地址解析优先级：CLI 参数 > 环境变量 > daemon meta > 默认值。
+ * - HTTP gateway 与本机 RPC 的地址解析分开，避免端口语义混淆。
  */
 
 import fs from "fs-extra";
@@ -62,29 +62,27 @@ function pickArgValue(args: string[], key: string): string | undefined {
   return next || undefined;
 }
 
-/**
- * 解析 daemon endpoint。
- *
- * 优先级（中文）
- * 1) 显式入参 `host/port`
- * 2) 环境变量 `DC_SERVER_*` / `DC_CTX_SERVER_*`
- * 3) daemon meta args（`downcity.daemon.json`）
- * 4) 默认 `127.0.0.1:5314`
- */
-function resolveDaemonEndpoint(params: {
+type ResolveDaemonEndpointParams = {
   projectRoot: string;
   host?: string;
   port?: number;
+};
+
+function resolveDaemonEndpointFromSources(params: {
+  projectRoot: string;
+  explicit_host?: string;
+  explicit_port?: number;
+  env_host_name: string;
+  env_port_name: string;
+  arg_port_name: string;
+  default_host: string;
+  default_port: number;
 }): DaemonEndpoint {
-  const explicitHost = normalizeHost(params.host);
-  const explicitPort = parsePortLike(params.port);
+  const explicitHost = normalizeHost(params.explicit_host);
+  const explicitPort = parsePortLike(params.explicit_port);
 
-  const envHost =
-    normalizeHost(process.env.DC_SERVER_HOST) ||
-    normalizeHost(process.env.DC_CTX_SERVER_HOST);
-  const envPort =
-    parsePortLike(process.env.DC_SERVER_PORT) ||
-    parsePortLike(process.env.DC_CTX_SERVER_PORT);
+  const envHost = normalizeHost(process.env[params.env_host_name]);
+  const envPort = parsePortLike(process.env[params.env_port_name]);
 
   let daemonArgHost: string | undefined;
   let daemonArgPort: number | undefined;
@@ -96,14 +94,14 @@ function resolveDaemonEndpoint(params: {
         ? raw.args.map((item) => String(item))
         : [];
       daemonArgHost = normalizeHost(pickArgValue(args, "--host"));
-      daemonArgPort = parsePortLike(pickArgValue(args, "--port"));
+      daemonArgPort = parsePortLike(pickArgValue(args, params.arg_port_name));
     }
   } catch {
     // ignore daemon meta errors, fallback to other sources
   }
 
-  const host = explicitHost || envHost || daemonArgHost || "127.0.0.1";
-  const port = explicitPort || envPort || daemonArgPort || 5314;
+  const host = explicitHost || envHost || daemonArgHost || params.default_host;
+  const port = explicitPort || envPort || daemonArgPort || params.default_port;
 
   return {
     host,
@@ -112,6 +110,30 @@ function resolveDaemonEndpoint(params: {
   };
 }
 
+/**
+ * 解析 daemon endpoint。
+ *
+ * 优先级（中文）
+ * 1) 显式入参 `host/port`
+ * 2) 环境变量 `DC_CITY_HOST/DC_CITY_PORT`
+ * 3) daemon meta args（`downcity.daemon.json`）
+ * 4) 默认 `127.0.0.1:5314`
+ */
+function resolveDaemonEndpoint(
+  params: ResolveDaemonEndpointParams,
+): DaemonEndpoint {
+  return resolveDaemonEndpointFromSources({
+    projectRoot: params.projectRoot,
+    explicit_host: params.host,
+    explicit_port: params.port,
+    env_host_name: "DC_CITY_HOST",
+    env_port_name: "DC_CITY_PORT",
+    arg_port_name: "--port",
+    default_host: "127.0.0.1",
+    default_port: 5314,
+  });
+}
+
 /**
  * 调用 daemon JSON API。
  *

package/src/runtime/host/daemon/Paths.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 这里只保留 agent 侧访问 daemon meta 所需的项目级路径。
- * - daemon 进程启停、pid 清理、registry 同步属于 `@downcity/city`，不放在 agent 包内。
+ * - daemon 进程启停、pid 清理、registry 同步属于 `downcity`，不放在 agent 包内。
  */
 
 import path from "node:path";

package/src/runtime/host/daemon/ProjectSetup.ts

@@ -30,14 +30,14 @@ function ensureContextFiles(projectRoot: string): void {
   // Check if initialized（启动入口一次性确认工程根目录与关键文件）
   if (!fs.existsSync(getProfileMdPath(projectRoot))) {
     console.error(
-      '❌ Project not initialized. Please run "city agent create" first',
+      '❌ Project not initialized. Please run "town agent create" first',
     );
     process.exit(1);
   }
 
   if (!fs.existsSync(getDowncityJsonPath(projectRoot))) {
     console.error(
-      '❌ downcity.json does not exist. Please run "city agent create" first',
+      '❌ downcity.json does not exist. Please run "town agent create" first',
     );
     process.exit(1);
   }

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

@@ -82,7 +82,7 @@ export function registerControlOverviewRoutes(
           cityVersion: DC_VERSION,
           now: new Date().toISOString(),
           agent: {
-            name: runtime.config.name,
+            id: runtime.config.id,
             status: "running",
           },
           sessions: {

package/src/session/Session.ts

@@ -30,7 +30,6 @@ import {
   SessionSystemBuilder,
 } from "@/session/SessionSystemBuilder.js";
 import {
-  inferModelLabel,
   buildSessionHistoryPage,
   buildSessionInfo,
   patchSessionModelLabel,
@@ -62,6 +61,11 @@ import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
 import { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
 import { SessionPromptRuntime } from "@/session/runtime/SessionPromptRuntime.js";
+import {
+  inferAgentModelLabel,
+  normalizeAgentModel,
+} from "@/model/CityModelAdapter.js";
+import { ensureSessionTitle } from "@/session/SessionTitle.js";
 
 type SessionOptions = {
   /**
@@ -257,8 +261,8 @@ export class Session implements AgentSession {
       this.createdAt = createdAt;
       this.timezone = timezone;
       this.sessionConfig = {
-        ...(metadata.sdkConfig?.modelLabel
-          ? { modelLabel: metadata.sdkConfig.modelLabel }
+        ...(metadata.modelLabel
+          ? { modelLabel: metadata.modelLabel }
           : {}),
       };
       return this;
@@ -280,8 +284,8 @@ export class Session implements AgentSession {
    */
   async set(input: AgentSessionSetInput): Promise<void> {
     if (input.model) {
-      this.sessionConfig.model = input.model;
-      this.sessionConfig.modelLabel = inferModelLabel(input.model);
+      this.sessionConfig.model = normalizeAgentModel(input.model);
+      this.sessionConfig.modelLabel = inferAgentModelLabel(input.model);
       this.executor.clearExecutor();
     }
     await patchSessionModelLabel({
@@ -333,6 +337,7 @@ export class Session implements AgentSession {
     await this.executor.appendUserMessage({
       text: String(input.text || "").trim(),
     });
+    await this.ensureTitleFromHistory({ generate: true });
     await this.touchMetadata();
   }
 
@@ -363,11 +368,19 @@ export class Session implements AgentSession {
       }),
       this.historyStore.list(),
     ]);
+    const metadataWithTitle = metadata.title
+      ? metadata
+      : await ensureSessionTitle({
+          projectRoot: this.projectRoot,
+          agentId: this.agentId,
+          sessionId: this.id,
+          messages,
+        });
     return buildSessionInfo({
       projectRoot: this.projectRoot,
       agentId: this.agentId,
       sessionId: this.id,
-      metadata,
+      metadata: metadataWithTitle,
       messages,
       executing: this.isExecuting(),
     });
@@ -477,6 +490,7 @@ export class Session implements AgentSession {
     for (const message of forkMessages) {
       await forked.historyStore.append(message);
     }
+    await forked.ensureTitleFromHistory({ generate: true });
     await forked.touchMetadata();
     return forked;
   }
@@ -503,6 +517,8 @@ export class Session implements AgentSession {
       },
       appendUserMessage: async (messageParams) => {
         await this.executor.appendUserMessage(messageParams);
+        await this.ensureTitleFromHistory({ generate: true });
+        await this.touchMetadata();
       },
       appendAssistantMessage: async (messageParams) => {
         await this.executor.appendAssistantMessage(messageParams);
@@ -558,6 +574,23 @@ export class Session implements AgentSession {
     });
   }
 
+  private async ensureTitleFromHistory(input?: {
+    /**
+     * 是否允许调用模型生成标题。
+     */
+    generate?: boolean;
+  }): Promise<void> {
+    const messages = await this.historyStore.list();
+    await ensureSessionTitle({
+      projectRoot: this.projectRoot,
+      agentId: this.agentId,
+      sessionId: this.id,
+      messages,
+      ...(input?.generate ? { model: this.sessionConfig.model } : {}),
+      generate: input?.generate === true,
+    });
+  }
+
   private async persistAssistantResult(
     assistantMessage: SessionMessageV1,
   ): Promise<void> {
@@ -583,6 +616,7 @@ export class Session implements AgentSession {
     await this.executor.appendUserMessage({
       message,
     });
+    await this.ensureTitleFromHistory({ generate: true });
     await this.touchMetadata();
     return message;
   }