@downcity/agent 1.1.338 → 1.1.400

package/city-test/session-model.test.mjs

@@ -0,0 +1,169 @@
+/**
+ * @file 验证 RemoteAgent 通过 RPC 控制 Session。
+ *
+ * 关键点（中文）
+ * - RemoteAgent 只传递 model_id，模型实例由 Agent Server 宿主解析。
+ * - compact 只验证 command 被远程 Session 接受，不应自行启动 turn。
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { Agent, RemoteAgent } from "../bin/index.js";
+import { create_workspace_entry } from "../bin/internal/index.js";
+import { Workspace } from "../../workspace/bin/index.js";
+import { AgentRPC } from "../bin/city/transport/rpc/AgentRPC.js";
+
+const network_tests_enabled = process.env.DOWNCITY_RUN_NETWORK_TESTS === "1";
+
+async function reserve_port() {
+  const server = net.createServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : 0;
+  await new Promise((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()));
+  });
+  return port;
+}
+
+async function send_rpc_request(port, request) {
+  return await new Promise((resolve, reject) => {
+    const socket = net.createConnection({ host: "127.0.0.1", port });
+    let buffered = "";
+    socket.setTimeout(2_000);
+    socket.once("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on("data", (chunk) => {
+      buffered += chunk.toString("utf8");
+      const newline_index = buffered.indexOf("\n");
+      if (newline_index < 0) return;
+      socket.destroy();
+      resolve(JSON.parse(buffered.slice(0, newline_index)));
+    });
+    socket.once("timeout", () => reject(new Error("RPC request timed out")));
+    socket.once("error", reject);
+  });
+}
+
+test("RPC resolves model_id through the host and queues compact", {
+  skip: !network_tests_enabled,
+}, async () => {
+  const project_root = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-server-session-model-"),
+  );
+  const model = {
+    modelId: "host-model",
+    provider: "test",
+  };
+  const agent = new Agent({
+    id: "rpc_model_agent",
+    model,
+  });
+  const entry = create_workspace_entry(agent, new Workspace({ id: "rpc_model_workspace", path: project_root, data_root_path: path.join(project_root, "data") }));
+  let resolved_model_id = "";
+  const rpc = new AgentRPC(entry, {
+    resolve_session_model: (model_id) => {
+      resolved_model_id = model_id;
+      return {
+        modelId: model_id,
+        provider: "test",
+      };
+    },
+  });
+  const port = await reserve_port();
+  const remote_agent = new RemoteAgent({
+    url: `rpc://127.0.0.1:${port}`,
+  });
+  try {
+    await rpc.listen({ host: "127.0.0.1", port });
+    const session = await remote_agent.sessions.create({
+      session_id: "rpc-model-session",
+    });
+    const initial_info = await session.get_info();
+    assert.equal("modelId" in initial_info, false);
+    assert.equal(initial_info.model_label, "host-model");
+    await session.set({ model_id: "selected-model" });
+    assert.equal(resolved_model_id, "selected-model");
+    assert.equal((await session.get_info()).model_label, "selected-model");
+    await session.compact();
+  } finally {
+    await remote_agent.close();
+    await rpc.close();
+    await agent.dispose();
+    await fs.rm(project_root, { recursive: true, force: true });
+  }
+});
+
+test("RPC rejects remote model switching when the host has no resolver", {
+  skip: !network_tests_enabled,
+}, async () => {
+  const project_root = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-server-model-resolver-required-"),
+  );
+  const agent = new Agent({
+    id: "rpc_model_resolver_required_agent",
+    model: { modelId: "host-model", provider: "test" },
+  });
+  const entry = create_workspace_entry(agent, new Workspace({ id: "resolver_workspace", path: project_root, data_root_path: path.join(project_root, "data") }));
+  const rpc = new AgentRPC(entry);
+  const port = await reserve_port();
+  const remote_agent = new RemoteAgent({ url: `rpc://127.0.0.1:${port}` });
+  try {
+    await rpc.listen({ host: "127.0.0.1", port });
+    const session = await remote_agent.sessions.create({ session_id: "resolver-required" });
+    await assert.rejects(
+      session.set({ model_id: "selected-model" }),
+      /model switching is not configured by the host/,
+    );
+  } finally {
+    await remote_agent.close();
+    await rpc.close();
+    await agent.dispose();
+    await fs.rm(project_root, { recursive: true, force: true });
+  }
+});
+
+test("internal RPC 让宿主重新加载 Workspace Env", {
+  skip: !network_tests_enabled,
+}, async () => {
+  const project_root = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-server-env-reload-"));
+  const workspace = new Workspace({
+    id: "env_workspace",
+    path: project_root, data_root_path: path.join(project_root, "data"),
+    env: { BEFORE: "value" },
+  });
+  const agent = new Agent({ id: "rpc_env_agent" });
+  const entry = create_workspace_entry(agent, workspace);
+  let reload_count = 0;
+  const rpc = new AgentRPC(entry, {
+    reload_workspace_env: () => {
+      reload_count += 1;
+      const env = { AFTER: "value" };
+      workspace.set_env(env);
+      return env;
+    },
+  });
+  const port = await reserve_port();
+  try {
+    await rpc.listen({ host: "127.0.0.1", port });
+    const frame = await send_rpc_request(port, {
+      id: "reload-env",
+      method: "internal.workspace.reload_env",
+    });
+    assert.equal(frame.success, true);
+    assert.equal(frame.data.reloaded, true);
+    assert.equal(frame.data.key_count, 1);
+    assert.equal(reload_count, 1);
+    assert.deepEqual(workspace.get_env(), { AFTER: "value" });
+  } finally {
+    await rpc.close();
+    await agent.dispose();
+    await fs.rm(project_root, { recursive: true, force: true });
+  }
+});

package/city-test/transport-lifecycle.test.mjs

@@ -0,0 +1,164 @@
+/**
+ * @file 验证 Agent HTTP/RPC transport 的协议错误与服务生命周期。
+ *
+ * 关键点（中文）
+ * - HTTP 路由应将输入错误、领域错误映射为稳定 JSON 响应。
+ * - transport 的 listen、binding 与 close 必须可重复调用且状态一致。
+ */
+
+import assert from "node:assert/strict"
+import net from "node:net"
+import test from "node:test"
+import { AgentHTTP } from "../bin/city/transport/http/AgentHTTP.js"
+import { AgentRPC } from "../bin/city/transport/rpc/AgentRPC.js"
+
+const network_tests_enabled = process.env.DOWNCITY_RUN_NETWORK_TESTS === "1"
+
+async function reserve_port() {
+  const server = net.createServer()
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(0, "127.0.0.1", resolve)
+  })
+  const address = server.address()
+  const port = typeof address === "object" && address ? address.port : 0
+  await new Promise((resolve, reject) => {
+    server.close((error) => error ? reject(error) : resolve())
+  })
+  return port
+}
+
+function create_transport_agent() {
+  return {
+    sessions: {
+      async list() {
+        throw new Error("session list failed")
+      },
+    },
+    plugins: {
+      async run_action({ plugin, action, payload }) {
+        if (action === "throw") throw new Error("plugin failed")
+        return { success: true, data: { plugin, action, payload } }
+      },
+    },
+  }
+}
+
+test("AgentHTTP exposes stable validation and domain error responses", async () => {
+  const http = new AgentHTTP(create_transport_agent())
+  const router = http.router()
+  assert.equal(http.router(), router)
+  assert.equal(http.server(), http.server())
+
+  const missing_plugin = await router.request("/api/plugins/action", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ action_name: "run" }),
+  })
+  assert.equal(missing_plugin.status, 400)
+  assert.deepEqual(await missing_plugin.json(), {
+    success: false,
+    error: "plugin_name is required",
+  })
+
+  const missing_action = await router.request("/api/plugins/action", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ plugin_name: "test" }),
+  })
+  assert.equal(missing_action.status, 400)
+  assert.equal((await missing_action.json()).error, "action_name is required")
+
+  const plugin_failure = await router.request("/api/plugins/action", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ plugin_name: "test", action_name: "throw" }),
+  })
+  assert.equal(plugin_failure.status, 500)
+  assert.equal((await plugin_failure.json()).error, "plugin failed")
+
+  const session_failure = await router.request("/api/sdk/sessions")
+  assert.equal(session_failure.status, 500)
+  assert.equal((await session_failure.json()).error, "session list failed")
+  assert.equal((await router.request("/unknown")).status, 404)
+})
+
+test("AgentHTTP listen, binding and close remain idempotent", {
+  skip: !network_tests_enabled,
+}, async () => {
+  const http = new AgentHTTP(create_transport_agent())
+  const handle = http.server()
+  assert.equal(handle.binding(), null)
+  await assert.rejects(handle.listen({ port: 0 }), /valid TCP port/iu)
+
+  const port = await reserve_port()
+  const [first_binding, second_binding] = await Promise.all([
+    handle.listen({ host: "127.0.0.1", port }),
+    handle.listen({ host: "127.0.0.1", port }),
+  ])
+  assert.deepEqual(second_binding, first_binding)
+  assert.deepEqual(handle.binding(), first_binding)
+  assert.equal((await fetch(`${first_binding.url}/unknown`)).status, 404)
+
+  await http.close()
+  await http.close()
+  assert.equal(handle.binding(), null)
+  assert.equal(http.server(), handle)
+})
+
+test("AgentHTTP close queued during listen releases the new server", {
+  skip: !network_tests_enabled,
+}, async () => {
+  const http = new AgentHTTP(create_transport_agent())
+  const handle = http.server()
+  const port = await reserve_port()
+  const listen_promise = handle.listen({ host: "127.0.0.1", port })
+  const close_promise = handle.close()
+  await Promise.all([listen_promise, close_promise])
+  assert.equal(handle.binding(), null)
+
+  const probe = net.createServer()
+  await new Promise((resolve, reject) => {
+    probe.once("error", reject)
+    probe.listen(port, "127.0.0.1", resolve)
+  })
+  await new Promise((resolve) => probe.close(resolve))
+})
+
+test("AgentRPC listen, binding and close remain idempotent", {
+  skip: !network_tests_enabled,
+}, async () => {
+  const rpc = new AgentRPC(create_transport_agent())
+  const port = await reserve_port()
+  assert.equal(rpc.binding(), null)
+  try {
+    const [first_binding, second_binding] = await Promise.all([
+      rpc.listen({ host: "127.0.0.1", port }),
+      rpc.listen({ host: "127.0.0.1", port }),
+    ])
+    assert.deepEqual(second_binding, first_binding)
+    assert.deepEqual(rpc.binding(), first_binding)
+  } finally {
+    await rpc.close()
+    await rpc.close()
+  }
+  assert.equal(rpc.binding(), null)
+})
+
+test("AgentRPC close queued during listen releases the new server", {
+  skip: !network_tests_enabled,
+}, async () => {
+  const rpc = new AgentRPC(create_transport_agent())
+  const port = await reserve_port()
+  const listen_promise = rpc.listen({ host: "127.0.0.1", port })
+  const close_promise = rpc.close()
+  await Promise.all([listen_promise, close_promise])
+  assert.equal(rpc.binding(), null)
+
+  const probe = net.createServer()
+  await new Promise((resolve, reject) => {
+    probe.once("error", reject)
+    probe.listen(port, "127.0.0.1", resolve)
+  })
+  await new Promise((resolve) => probe.close(resolve))
+})

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.338",
+  "version": "1.1.400",
   "type": "module",
-  "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
+  "description": "Downcity 单 Agent SDK 与执行运行时",
   "main": "./bin/index.js",
   "types": "./bin/index.d.ts",
   "exports": {
@@ -10,15 +10,36 @@
       "import": "./bin/index.js",
       "types": "./bin/index.d.ts"
     },
+    "./agent": {
+      "import": "./bin/agent/index.js",
+      "types": "./bin/agent/index.d.ts"
+    },
+    "./city": {
+      "import": "./bin/city/index.js",
+      "types": "./bin/city/index.d.ts"
+    },
     "./tools": {
       "import": "./bin/tools/index.js",
       "types": "./bin/tools/index.d.ts"
+    },
+    "./internal": {
+      "import": "./bin/internal/index.js",
+      "types": "./bin/internal/index.d.ts"
     }
   },
+  "scripts": {
+    "build": "node scripts/agent-compiler.mjs build",
+    "dev": "node scripts/agent-compiler.mjs dev",
+    "test": "pnpm build && pnpm --filter '@downcity/sandbox-*' build && pnpm -C ../plugins build && node --test scripts/*.test.mjs city-test/*.test.mjs",
+    "test:executor-runtime": "pnpm build && node --test scripts/session-prompt-runtime.test.mjs",
+    "typecheck": "node scripts/agent-compiler.mjs typecheck",
+    "prepack": "npm run build && node ../../scripts/rewrite-workspace-dependencies.mjs prepare ./package.json",
+    "postpack": "node ../../scripts/rewrite-workspace-dependencies.mjs restore ./package.json"
+  },
   "dependencies": {
-    "@downcity/shell": "^0.1.172",
-    "@downcity/type": "0.1.197",
-    "ai": "^6.0.193",
+    "@downcity/workspace": "^0.1.5",
+    "@downcity/type": "0.1.199",
+    "@downcity/federation": "^0.1.9",
     "commander": "^15.0.0",
     "dotenv": "^17.4.2",
     "execa": "^9.6.1",
@@ -32,10 +53,9 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@downcity/sandbox-linux": "^0.1.35",
-    "@downcity/sandbox-macos": "^0.1.35",
-    "@downcity/sandbox-windows-mxc": "^0.1.35",
-    "@ai-sdk/openai": "^3.0.67",
+    "@downcity/sandbox-linux": "^0.1.37",
+    "@downcity/sandbox-macos": "^0.1.37",
+    "@downcity/sandbox-windows-mxc": "^0.1.37",
     "@types/fs-extra": "^11.0.4",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.9.1",
@@ -43,12 +63,5 @@
     "@types/ws": "^8.18.1",
     "tsc-alias": "^1.8.17",
     "typescript": "^6.0.3"
-  },
-  "scripts": {
-    "build": "node scripts/agent-compiler.mjs build",
-    "dev": "node scripts/agent-compiler.mjs dev",
-    "test": "pnpm build && pnpm --filter '@downcity/sandbox-*' build && pnpm -C ../plugins build && node --test scripts/*.test.mjs",
-    "test:executor-runtime": "pnpm build && node --test scripts/session-prompt-runtime.test.mjs",
-    "typecheck": "node scripts/agent-compiler.mjs typecheck"
   }
-}
+}

package/scripts/ModelClientMock.mjs

@@ -0,0 +1,165 @@
+/**
+ * Agent 测试使用的可编程 Downcity ModelClient。
+ *
+ * 旧测试夹具可以继续用分块构造器表达场景，本模块只在测试进程内把这些分块
+ * 规范化为 ModelStreamEvent，不进入 SDK 产物或公开协议。
+ */
+
+export class MockModelClient {
+  constructor(options = {}) {
+    this.id = options.modelId || options.id || "mock-model";
+    this.stream_handler = options.stream || options.doStream;
+    this.generate_handler = options.generate || options.doGenerate;
+  }
+
+  async stream(call) {
+    if ((!call.tools || call.tools.length === 0) && this.generate_handler) {
+      const generated = await this.generate_handler(to_fixture_call(call));
+      return generate_result_stream(this.id, generated);
+    }
+    if (!this.stream_handler) {
+      return generate_result_stream(this.id, await this.generate_handler(to_fixture_call(call)));
+    }
+    const result = await this.stream_handler(to_fixture_call(call));
+    return normalize_fixture_stream(this.id, result.stream ?? result);
+  }
+}
+
+function to_fixture_call(call) {
+  return {
+    ...call,
+    prompt: call.messages.map((message) => ({
+      role: message.role,
+      content: message.content.map(to_fixture_content),
+    })),
+    tools: call.tools?.map((tool) => ({
+      type: "function",
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.input_schema,
+      providerOptions: undefined,
+    })),
+  };
+}
+
+function to_fixture_content(part) {
+  if (part.type === "tool_call") {
+    return { type: "tool-call", toolCallId: part.tool_call_id, toolName: part.tool_name, input: part.input };
+  }
+  if (part.type === "tool_result") {
+    return {
+      type: "tool-result", toolCallId: part.tool_call_id, toolName: part.tool_name,
+      output: part.content,
+    };
+  }
+  if (part.type !== "file") return part;
+  return {
+    type: "file",
+    mediaType: part.media_type,
+    data: part.source.type === "base64" ? part.source.data : part.source.url,
+    ...(part.filename ? { filename: part.filename } : {}),
+  };
+}
+
+function generate_result_stream(model_id, result = {}) {
+  const content = Array.isArray(result.content)
+    ? result.content
+    : [{ type: "text", text: String(result.text || "") }];
+  return new ReadableStream({ start(controller) {
+    controller.enqueue({ type: "model_start", request_id: `req_${crypto.randomUUID()}`, model_id });
+    for (const [index, part] of content.entries()) {
+      const content_id = `${part.type}_${String(index + 1)}`;
+      if (part.type === "text" && part.text) {
+        controller.enqueue({ type: "text_start", content_id });
+        controller.enqueue({ type: "text_delta", content_id, delta: part.text });
+        controller.enqueue({ type: "text_finish", content_id });
+      } else if (part.type === "tool_call") {
+        controller.enqueue({
+          type: "tool_call_start",
+          content_id,
+          tool_call_id: part.tool_call_id,
+          tool_name: part.tool_name,
+        });
+        controller.enqueue({ type: "tool_call_finish", content_id, input: part.input });
+      }
+    }
+    controller.enqueue({ type: "model_usage", usage: normalize_usage(result.usage) });
+    controller.enqueue({ type: "model_finish", finish_reason: normalize_finish_reason(result.finishReason) });
+    controller.close();
+  } });
+}
+
+function normalize_fixture_stream(model_id, stream) {
+  const reader = stream.getReader();
+  return new ReadableStream({
+    async start(controller) {
+      const tools = new Map();
+      let started = false;
+      let finished = false;
+      const ensure_started = () => {
+        if (started) return;
+        started = true;
+        controller.enqueue({ type: "model_start", request_id: `req_${crypto.randomUUID()}`, model_id });
+      };
+      try {
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done) break;
+          const part = chunk.value;
+          if (!part || typeof part !== "object") continue;
+          ensure_started();
+          if (part.type === "text-start") controller.enqueue({ type: "text_start", content_id: part.id });
+          else if (part.type === "text-delta") controller.enqueue({ type: "text_delta", content_id: part.id, delta: part.delta });
+          else if (part.type === "text-end") controller.enqueue({ type: "text_finish", content_id: part.id });
+          else if (part.type === "reasoning-start") controller.enqueue({ type: "reasoning_start", content_id: part.id });
+          else if (part.type === "reasoning-delta") controller.enqueue({ type: "reasoning_delta", content_id: part.id, delta: part.delta });
+          else if (part.type === "reasoning-end") controller.enqueue({ type: "reasoning_finish", content_id: part.id });
+          else if (part.type === "tool-input-start") {
+            tools.set(part.id, { name: part.toolName, input: "", started: true });
+            controller.enqueue({ type: "tool_call_start", content_id: part.id, tool_call_id: part.id, tool_name: part.toolName });
+          } else if (part.type === "tool-input-delta") {
+            const tool = tools.get(part.id) ?? { name: "", input: "", started: false };
+            tool.input += part.delta;
+            tools.set(part.id, tool);
+            controller.enqueue({ type: "tool_call_delta", content_id: part.id, input_delta: part.delta });
+          } else if (part.type === "tool-call") {
+            const id = part.toolCallId;
+            const tool = tools.get(id) ?? { name: part.toolName, input: "", started: false };
+            if (!tool.started) {
+              controller.enqueue({ type: "tool_call_start", content_id: id, tool_call_id: id, tool_name: part.toolName });
+            }
+            controller.enqueue({
+              type: "tool_call_finish", content_id: id,
+              input: typeof part.input === "string" ? JSON.parse(part.input || "{}") : part.input,
+            });
+          } else if (part.type === "finish") {
+            controller.enqueue({ type: "model_usage", usage: normalize_usage(part.usage) });
+            controller.enqueue({ type: "model_finish", finish_reason: normalize_finish_reason(part.finishReason) });
+            finished = true;
+          } else if (part.type === "error") {
+            controller.enqueue({ type: "model_error", error: { code: "provider_error", message: String(part.error || "Provider error"), retryable: false } });
+            finished = true;
+          }
+        }
+        ensure_started();
+        if (!finished) controller.enqueue({ type: "model_finish", finish_reason: "stop" });
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      }
+    },
+  });
+}
+
+function normalize_usage(usage = {}) {
+  const input_tokens = Number(usage.input_tokens ?? usage.inputTokens?.total ?? 0);
+  const output_tokens = Number(usage.output_tokens ?? usage.outputTokens?.total ?? 0);
+  return { input_tokens, output_tokens, total_tokens: input_tokens + output_tokens };
+}
+
+function normalize_finish_reason(value) {
+  const reason = typeof value === "string" ? value : value?.unified;
+  if (reason === "tool-calls" || reason === "tool_calls") return "tool_call";
+  if (["stop", "length", "content_filter", "cancelled", "error", "unknown"].includes(reason)) return reason;
+  return "stop";
+}