@downcity/agent 1.1.287 → 1.1.310

package/scripts/action-schedule-store.test.mjs

@@ -0,0 +1,101 @@
+/**
+ * @file 验证 ActionScheduleStore 通过 Workspace FileSystem 持久化异步事件流。
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { ActionScheduleStore, Workspace } from "../bin/index.js";
+
+test("ActionScheduleStore persists through Workspace FileSystem", async (t) => {
+  const workspace_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-action-schedule-"),
+  );
+  t.after(async () => {
+    await fs.rm(workspace_path, { recursive: true, force: true });
+  });
+  const workspace = new Workspace({ path: workspace_path });
+  const store = new ActionScheduleStore(workspace.files);
+
+  const created = await store.create_job({
+    plugin_name: "demo",
+    action_name: "run",
+    payload: { value: 1 },
+    run_at_ms: Date.now() - 1,
+  });
+  assert.equal((await store.list_due_pending_jobs(Date.now())).length, 1);
+  assert.equal(await store.mark_job_running(created.id), true);
+  assert.equal((await store.get_job_by_id(created.id))?.status, "running");
+  assert.equal(await store.reset_running_jobs_to_pending(), 1);
+  assert.equal(await store.cancel_pending_job(created.id), true);
+  assert.equal((await store.get_job_by_id(created.id))?.status, "cancelled");
+
+  await workspace.dispose();
+});
+
+test("ActionScheduleStore serializes cross-instance pending claims", async (t) => {
+  const workspace_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-action-schedule-lock-"),
+  );
+  t.after(async () => {
+    await fs.rm(workspace_path, { recursive: true, force: true });
+  });
+  const first_workspace = new Workspace({ path: workspace_path });
+  const second_workspace = new Workspace({ path: workspace_path });
+  const first_store = new ActionScheduleStore(first_workspace.files);
+  const second_store = new ActionScheduleStore(second_workspace.files);
+  const created = await first_store.create_job({
+    plugin_name: "demo",
+    action_name: "run",
+    payload: null,
+    run_at_ms: Date.now(),
+  });
+
+  const claims = await Promise.all([
+    first_store.mark_job_running(created.id),
+    second_store.mark_job_running(created.id),
+  ]);
+  assert.deepEqual(claims.sort(), [false, true]);
+  assert.equal((await first_store.get_job_by_id(created.id))?.status, "running");
+
+  await Promise.all([
+    first_workspace.dispose(),
+    second_workspace.dispose(),
+  ]);
+});
+
+test("ActionScheduleStore only allows running jobs to enter terminal states", async (t) => {
+  const workspace_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-action-schedule-state-"),
+  );
+  t.after(async () => {
+    await fs.rm(workspace_path, { recursive: true, force: true });
+  });
+  const workspace = new Workspace({ path: workspace_path });
+  const store = new ActionScheduleStore(workspace.files);
+
+  const cancelled = await store.create_job({
+    plugin_name: "demo",
+    action_name: "cancelled",
+    payload: null,
+    run_at_ms: Date.now(),
+  });
+  assert.equal(await store.cancel_pending_job(cancelled.id), true);
+  assert.equal(await store.mark_job_succeeded(cancelled.id), false);
+  assert.equal((await store.get_job_by_id(cancelled.id))?.status, "cancelled");
+
+  const running = await store.create_job({
+    plugin_name: "demo",
+    action_name: "running",
+    payload: null,
+    run_at_ms: Date.now(),
+  });
+  assert.equal(await store.mark_job_running(running.id), true);
+  assert.equal(await store.mark_job_succeeded(running.id), true);
+  assert.equal(await store.mark_job_failed(running.id, "late failure"), false);
+  assert.equal((await store.get_job_by_id(running.id))?.status, "succeeded");
+
+  await workspace.dispose();
+});

package/scripts/agent-env-shell-sandbox.test.mjs

@@ -12,7 +12,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
-import { Agent } from "@downcity/agent";
+import { Agent, Workspace } from "@downcity/agent";
 import { Shell } from "@downcity/shell";
 import { create_platform_sandbox } from "./PlatformSandbox.mjs";
 
@@ -31,7 +31,7 @@ async function execute_shell(agent, cmd) {
   return String(result.output || "");
 }
 
-test("agent setEnv and patchEnv are visible in shell safe sandbox", async (t) => {
+test("workspace set_env and patch_env are visible in shell safe sandbox", async (t) => {
   const sandbox = await create_platform_sandbox();
   const preflight = await sandbox.preflight();
   if (!preflight.ok) {
@@ -43,14 +43,17 @@ test("agent setEnv and patchEnv are visible in shell safe sandbox", async (t) =>
   const previous_host_value = process.env.HOST_ONLY_ENV_REPRO;
   process.env.HOST_ONLY_ENV_REPRO = "host_secret";
 
-  const agent = new Agent({
-    id: "agent-env-shell-sandbox-test",
+  const workspace = new Workspace({
     path: root_path,
     shell: new Shell({ sandbox }),
   });
+  const agent = new Agent({
+    id: "agent-env-shell-sandbox-test",
+    workspace,
+  });
 
   try {
-    agent.setEnv({
+    workspace.set_env({
       DYNAMIC_ENV_REPRO: "initial_value",
       DC_DYNAMIC_REPRO: "dc_initial",
       REMOVED_ENV_REPRO: "remove_me",
@@ -65,20 +68,7 @@ test("agent setEnv and patchEnv are visible in shell safe sandbox", async (t) =>
     assert.match(first_output, /REMOVED=remove_me/);
     assert.match(first_output, /HOST_ONLY=\n/);
 
-    agent.getShell()?.configure({
-      env: {
-        DYNAMIC_ENV_REPRO: "configured_value",
-      },
-    });
-
-    const configured_output = await execute_shell(
-      agent,
-      'printf "CURRENT=%s\\nHOST_ONLY=%s\\n" "$DYNAMIC_ENV_REPRO" "$HOST_ONLY_ENV_REPRO"',
-    );
-    assert.match(configured_output, /CURRENT=configured_value/);
-    assert.match(configured_output, /HOST_ONLY=\n/);
-
-    agent.patchEnv({
+    workspace.patch_env({
       DYNAMIC_ENV_REPRO: "updated_value",
       ADDED_ENV_REPRO: "added_value",
       REMOVED_ENV_REPRO: null,

package/scripts/agent-env.test.mjs

@@ -8,15 +8,15 @@ import path from "node:path";
 import test from "node:test";
 import {
   Agent,
-  initializeAgentProject,
-  resolve_agent_env,
+  Workspace,
+  resolve_workspace_env,
 } from "../bin/index.js";
 
 function create_project_root() {
   return fs.mkdtempSync(path.join(os.tmpdir(), "downcity-agent-env-"));
 }
 
-test("项目 .env 覆盖宿主环境且不修改 process.env", () => {
+test("Workspace 显式 env 覆盖项目 .env 且不修改 process.env", () => {
   const project_root = create_project_root();
   const original_value = process.env.DOWNCITY_ENV_TEST;
   try {
@@ -24,11 +24,11 @@ test("项目 .env 覆盖宿主环境且不修改 process.env", () => {
       path.join(project_root, ".env"),
       "DOWNCITY_ENV_TEST=project\nPROJECT_ONLY=value\n",
     );
-    const env = resolve_agent_env(project_root, {
+    const env = resolve_workspace_env(project_root, {
       DOWNCITY_ENV_TEST: "host",
       HOST_ONLY: "value",
     });
-    assert.equal(env.DOWNCITY_ENV_TEST, "project");
+    assert.equal(env.DOWNCITY_ENV_TEST, "host");
     assert.equal(env.HOST_ONLY, "value");
     assert.equal(env.PROJECT_ONLY, "value");
     assert.equal(process.env.DOWNCITY_ENV_TEST, original_value);
@@ -44,44 +44,15 @@ test("Agent 运行时只使用显式 id，不读取完整项目 config", async (
       id: "legacy_id",
       version: "9.9.9",
     }));
-    const agent = new Agent({ id: "sdk_id", path: project_root });
+    const agent = new Agent({
+      id: "sdk_id",
+      workspace: new Workspace({ path: project_root }),
+    });
     assert.equal(agent.id, "sdk_id");
-    assert.equal(agent.getContext().agent_id, "sdk_id");
-    assert.equal(agent.getContext().rootPath, project_root);
+    assert.equal(agent.workspace.path, fs.realpathSync(project_root));
     await agent.ready();
     await agent.dispose();
   } finally {
     fs.rmSync(project_root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   }
 });
-
-test("项目初始化只创建 .env、Skills 和运行目录并返回真实结果", async () => {
-  const project_root = create_project_root();
-  try {
-    const first = await initializeAgentProject({
-      projectRoot: project_root,
-      id: "init_agent",
-      execution: { type: "api", modelId: "model_a" },
-    });
-    assert.equal(fs.existsSync(path.join(project_root, ".env")), true);
-    assert.equal(fs.existsSync(path.join(project_root, ".env.example")), false);
-    assert.equal(fs.existsSync(path.join(project_root, ".agents", "skills")), true);
-    assert.equal(first.createdFiles.includes(".env"), true);
-    assert.equal(first.createdFiles.includes(".agents/skills/"), true);
-    assert.equal(first.createdFiles.includes(".downcity/"), true);
-    const gitignore = fs.readFileSync(path.join(project_root, ".gitignore"), "utf8");
-    assert.match(gitignore, /^\.env$/m);
-    assert.match(gitignore, /^\.downcity$/m);
-
-    const second = await initializeAgentProject({
-      projectRoot: project_root,
-      id: "init_agent",
-      execution: { type: "api", modelId: "model_a" },
-    });
-    assert.equal(second.skippedFiles.includes(".env"), true);
-    assert.equal(second.skippedFiles.includes(".agents/skills/"), true);
-    assert.equal(second.skippedFiles.includes(".downcity/"), true);
-  } finally {
-    fs.rmSync(project_root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
-  }
-});

package/scripts/agent-ready.test.mjs

@@ -13,8 +13,8 @@ import path from "node:path";
 import fs from "node:fs/promises";
 
 import { MockLanguageModelV3 } from "ai/test";
-import { Agent } from "../bin/index.js";
-import { createPlugin } from "../bin/plugin/core/PluginActionFactory.js";
+import { Agent, Workspace } from "../bin/index.js";
+import { create_plugin } from "../bin/plugin/core/PluginActionFactory.js";
 
 function create_deferred() {
   let resolve;
@@ -93,7 +93,7 @@ test("session.prompt waits for agent runtime ready before model execution", asyn
   const lifecycle_ready = create_deferred();
   let model_stream_calls = 0;
 
-  const blocking_plugin = createPlugin({
+  const blocking_plugin = create_plugin({
     name: "blocking",
     title: "Blocking",
     description: "Blocks lifecycle start until the test releases it",
@@ -138,14 +138,14 @@ test("session.prompt waits for agent runtime ready before model execution", asyn
   });
   const agent = new Agent({
     id: "ready_agent",
-    path: agent_path,
+    workspace: new Workspace({ path: agent_path }),
     plugins: [blocking_plugin],
     model,
   });
 
   try {
     const session = await agent.sessions.create({
-      sessionId: "ready_session",
+      session_id: "ready_session",
     });
     const prompt_promise = session.prompt({
       query: "hello",
@@ -171,7 +171,7 @@ test("agent ready isolates plugin lifecycle start failures", async () => {
     path.join(os.tmpdir(), "downcity-agent-ready-isolation-"),
   );
   let healthy_started = false;
-  const failing_plugin = createPlugin({
+  const failing_plugin = create_plugin({
     name: "failing",
     lifecycle: {
       start: async () => {
@@ -179,7 +179,7 @@ test("agent ready isolates plugin lifecycle start failures", async () => {
       },
     },
   });
-  const healthy_plugin = createPlugin({
+  const healthy_plugin = create_plugin({
     name: "healthy",
     lifecycle: {
       start: async () => {
@@ -189,7 +189,7 @@ test("agent ready isolates plugin lifecycle start failures", async () => {
   });
   const agent = new Agent({
     id: "ready_isolation_agent",
-    path: agent_path,
+    workspace: new Workspace({ path: agent_path }),
     plugins: [failing_plugin, healthy_plugin],
   });
 
@@ -204,15 +204,15 @@ test("agent ready isolates plugin lifecycle start failures", async () => {
   }
 });
 
-test("AgentState installs plugin tools when an action plugin is registered", async () => {
+test("Agent registers PluginRegistry tools and removes them with the last action plugin", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-agent-state-plugin-tools-"),
   );
   const agent = new Agent({
     id: "state_plugin_tools_agent",
-    path: agent_path,
+    workspace: new Workspace({ path: agent_path }),
   });
-  const action_plugin = createPlugin({
+  const action_plugin = create_plugin({
     name: "dynamic_action",
     actions: {
       ping: {
@@ -230,6 +230,11 @@ test("AgentState installs plugin tools when an action plugin is registered", asy
 
     assert.notEqual(agent.tools.plugin_read, undefined);
     assert.notEqual(agent.tools.plugin_call, undefined);
+
+    await agent.plugins.unregister("dynamic_action");
+
+    assert.equal(agent.tools.plugin_read, undefined);
+    assert.equal(agent.tools.plugin_call, undefined);
   } finally {
     await agent.dispose();
   }

package/scripts/agent-session-maintenance.test.mjs

@@ -7,7 +7,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
-import { Agent } from "../bin/index.js";
+import { Agent, Workspace } from "../bin/index.js";
 
 function create_project_root() {
   return fs.mkdtempSync(path.join(os.tmpdir(), "downcity-session-maintenance-"));
@@ -24,27 +24,29 @@ function get_session_path(root_path, agent_id, session_id) {
   );
 }
 
-test("AgentContext sessions 负责清空消息和删除 Session 数据", async () => {
+test("Agent sessions 负责清空消息和删除 Session 数据", async () => {
   const root_path = create_project_root();
-  const agent = new Agent({ id: "agent_test", path: root_path });
+  const agent = new Agent({
+    id: "agent_test",
+    workspace: new Workspace({ path: root_path }),
+  });
   try {
     await agent.ready();
-    assert.equal(agent.getContext().sessions, agent.sessions);
     const session_id = "session_test";
-    await agent.sessions.create({ sessionId: session_id });
+    await agent.sessions.create({ session_id: session_id });
     const session_path = get_session_path(root_path, agent.id, session_id);
     const messages_path = path.join(session_path, "messages");
     fs.mkdirSync(messages_path, { recursive: true });
     fs.writeFileSync(path.join(messages_path, "active.jsonl"), "{}\n");
 
     assert.equal(
-      await agent.getContext().sessions.clear_messages(session_id),
+      await agent.sessions.clear_messages(session_id),
       true,
     );
     assert.equal(fs.existsSync(messages_path), false);
     assert.equal(fs.existsSync(session_path), true);
 
-    assert.equal(await agent.getContext().sessions.remove(session_id), true);
+    assert.equal(await agent.sessions.remove(session_id), true);
     assert.equal(fs.existsSync(session_path), false);
   } finally {
     await agent.dispose();

package/scripts/agent-store.test.mjs

@@ -0,0 +1,83 @@
+/**
+ * @file 验证 AgentStore / SessionStore 的领域边界与本地实现契约。
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { Agent, Workspace } from "../bin/index.js";
+
+async function create_test_roots(t) {
+  const parent_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-agent-store-"));
+  const workspace_path = path.join(parent_path, "workspace");
+  await fs.mkdir(workspace_path);
+  t.after(async () => await fs.rm(parent_path, { recursive: true, force: true }));
+  return { workspace_path };
+}
+
+test("Workspace provides AgentStore on the same file resource", async (t) => {
+  const { workspace_path } = await create_test_roots(t);
+  const workspace = new Workspace({ path: workspace_path });
+  const store = workspace.bind_agent("store-test");
+  const session_store = store.session("first");
+
+  assert.equal(store.session("first"), session_store);
+  assert.equal(await store.has_session("first"), false);
+
+  await session_store.messages.initialize();
+  await session_store.write_metadata({
+    v: 1,
+    session_id: "first",
+    agent_id: "store-test",
+    created_at: 1,
+    updated_at: 1,
+    title: "独立存储",
+  });
+  await session_store.write_instruction("");
+
+  assert.equal(await store.has_session("first"), true);
+  assert.equal((await session_store.read_metadata()).title, "独立存储");
+  assert.equal(await session_store.has_instruction(), true);
+  assert.equal(await session_store.read_instruction(), "");
+  const tool_result = await workspace.files.run_file_action({
+    action: "read",
+    input: {
+      file_path: ".downcity/agents/store-test/sessions/first/messages/meta.json",
+    },
+  });
+  assert.equal(tool_result.success, true);
+  assert.match(tool_result.success ? tool_result.content : "", /独立存储/);
+
+  assert.equal(await store.clear_session_messages("first"), true);
+  assert.equal((await store.session("first").read_metadata()).title, undefined);
+  assert.equal(await store.has_session("first"), true);
+  assert.equal(await store.remove_session("first"), true);
+  assert.equal(await store.has_session("first"), false);
+});
+
+test("LocalAgentStore archives and cleans sessions", async (t) => {
+  const { workspace_path } = await create_test_roots(t);
+  const store = new Workspace({ path: workspace_path }).bind_agent("archive-test");
+  await store.session("archived").messages.initialize();
+
+  const archived = await store.archive_session("archived");
+  assert.equal(archived.session_id, "archived");
+  assert.equal((await store.list_archived_sessions()).items[0]?.session_id, "archived");
+  assert.deepEqual((await store.clean_archive()).removed_session_ids, ["archived"]);
+  assert.equal((await store.list_archived_sessions()).items.length, 0);
+});
+
+test("Agent obtains its Store from Workspace", async (t) => {
+  const { workspace_path } = await create_test_roots(t);
+  const workspace = new Workspace({ path: workspace_path });
+  const agent = new Agent({
+    id: "dispose-test",
+    workspace,
+  });
+
+  assert.equal(agent.workspace, workspace);
+  assert.equal((await agent.sessions.create({ session_id: "first" })).id, "first");
+  await agent.dispose();
+});

package/scripts/city-model-tool-loop.test.mjs

@@ -16,8 +16,8 @@ import { MockLanguageModelV3 } from "ai/test";
 import { tool } from "ai";
 import { z } from "zod";
 
-import { Agent } from "../bin/index.js";
-import { createAction, createPlugin } from "../bin/plugin/core/PluginActionFactory.js";
+import { Agent, Workspace } from "../bin/index.js";
+import { create_action, create_plugin } from "../bin/plugin/core/PluginActionFactory.js";
 import { CITY_MODEL_KIND } from "@downcity/type";
 
 /** 构造 AI SDK V3 usage。 */
@@ -109,12 +109,14 @@ test("CityModel uses direct LanguageModel path and sends tool result back", asyn
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-agent-city-model-tool-loop-"),
   );
-  const skill_plugin = createPlugin({
+  const input_image_path = path.join(agent_path, "tool-input.png");
+  await fs.writeFile(input_image_path, Buffer.from("tool-input-image"));
+  const skill_plugin = create_plugin({
     name: "skill",
     title: "Skill",
     description: "Test skill plugin",
     actions: {
-      lookup: createAction({
+      lookup: create_action({
         description: "Lookup a skill",
         execute: async ({ input }) => ({
           success: true,
@@ -126,21 +128,37 @@ test("CityModel uses direct LanguageModel path and sends tool result back", asyn
   });
   const agent = new Agent({
     id: "tool_loop_agent",
-    path: agent_path,
+    workspace: new Workspace({ path: agent_path }),
     plugins: [skill_plugin],
     tools: {
       ping: tool({
         description: "ping tool",
         inputSchema: z.object({ value: z.string() }),
-        execute: async ({ value }, options) => {
+        execute: async ({ value }) => {
           tool_executed = true;
-          options.experimental_context.session_run_context.pendingAssistantFileParts.push({
-            type: "file",
-            mediaType: "image/png",
-            url: ".downcity/resources/tool-output.png",
-            filename: "tool-output.png",
-          });
-          return { echoed: value };
+          return {
+            output: { echoed: value },
+            messages: [
+              {
+                role: "assistant",
+                parts: [{
+                  type: "file",
+                  mediaType: "image/png",
+                  url: "/workspace/tool-output.png",
+                  filename: "tool-output.png",
+                }],
+              },
+              {
+                role: "user",
+                parts: [{
+                  type: "file",
+                  mediaType: "image/png",
+                  url: input_image_path,
+                  filename: "tool-input.png",
+                }],
+              },
+            ],
+          };
         },
       }),
     },
@@ -168,6 +186,16 @@ test("CityModel uses direct LanguageModel path and sends tool result back", asyn
     assert.match(serialized_second_prompt, /call_1/);
     assert.match(serialized_second_prompt, /echoed/);
     assert.match(serialized_second_prompt, /hello/);
+    const injected_file = model_requests[1].prompt
+      .filter((message) => message.role === "user")
+      .flatMap((message) => Array.isArray(message.content) ? message.content : [])
+      .find((part) => part.type === "file" && part.filename === "tool-input.png");
+    assert.ok(injected_file, JSON.stringify(model_requests[1].prompt.at(-1)));
+    assert.equal(injected_file.mediaType, "image/png");
+    assert.equal(
+      String(injected_file.data),
+      Buffer.from("tool-input-image").toString("base64"),
+    );
     const restored_tool_call = model_requests[1].prompt
       .flatMap((message) => Array.isArray(message.content) ? message.content : [])
       .find((part) => part.type === "tool-call" && part.toolCallId === "call_1");
@@ -175,23 +203,21 @@ test("CityModel uses direct LanguageModel path and sends tool result back", asyn
       openai: { itemId: "fc_1" },
     });
 
-    const result_file = result.assistantMessage.parts.find((part) => part.type === "file");
+    const session_messages = await session.messages({ include_internal: true });
+    const persisted_assistant = session_messages.items.find((message) => message.type === "assistant");
+    const result_file = persisted_assistant.parts.find((part) => part.type === "file");
     assert.deepEqual(result_file, {
+      part_id: result_file.part_id,
+      sequence: result_file.sequence,
       type: "file",
-      mediaType: "image/png",
-      url: ".downcity/resources/tool-output.png",
+      media_type: "image/png",
+      url: "/workspace/tool-output.png",
       filename: "tool-output.png",
     });
-    const session_messages = await session.messages({ include_internal: true });
-    const persisted_assistant = session_messages.items.find((message) => message.type === "assistant");
     const persisted_tool = persisted_assistant.parts.find((part) => part.type === "tool");
     assert.deepEqual(persisted_tool.call_provider_metadata, {
       openai: { itemId: "fc_1" },
     });
-    const persisted_file = persisted_assistant.parts.find((part) => part.type === "file");
-    assert.equal(persisted_file.media_type, "image/png");
-    assert.equal(persisted_file.url, ".downcity/resources/tool-output.png");
-    assert.equal(persisted_file.filename, "tool-output.png");
   } finally {
     await agent.dispose();
   }