@downcity/agent 1.1.287 → 1.1.310

package/scripts/search-tools.test.mjs

@@ -0,0 +1,188 @@
+/**
+ * @file 验证 Workspace 可装配的 grep / find 项目搜索工具。
+ *
+ * 关键点（中文）
+ * - grep 覆盖字面量、正则、大小写、结果截断与项目路径边界。
+ * - find 覆盖 glob、.gitignore、dotfile、符号链接与非法模式。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { Workspace } from "@downcity/agent";
+
+const rg_available = spawnSync("rg", ["--version"], { stdio: "ignore" }).status === 0;
+
+async function create_fixture(t) {
+  const root_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-search-tools-"));
+  const outside_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-search-outside-"));
+  t.after(async () => {
+    await fs.rm(root_path, { recursive: true, force: true });
+    await fs.rm(outside_path, { recursive: true, force: true });
+  });
+  return {
+    root_path,
+    outside_path,
+    tools: new Workspace({ path: root_path }).tools,
+  };
+}
+
+async function execute_tool(tools, name, input, abort_signal) {
+  const execute = tools[name]?.execute;
+  assert.equal(typeof execute, "function", `${name} tool must be executable`);
+  const result = await execute(input, {
+    toolCallId: `test-${name}`,
+    messages: [],
+    abortSignal: abort_signal || new AbortController().signal,
+  });
+  assert.deepEqual(result.messages, []);
+  return result.output;
+}
+
+test("grep returns structured literal matches and respects .gitignore", { skip: !rg_available }, async (t) => {
+  const fixture = await create_fixture(t);
+  await fs.mkdir(path.join(fixture.root_path, "src"), { recursive: true });
+  await fs.mkdir(path.join(fixture.root_path, "ignored"), { recursive: true });
+  await fs.writeFile(path.join(fixture.root_path, ".gitignore"), "ignored/\n", "utf8");
+  await fs.writeFile(path.join(fixture.root_path, "src", "main.ts"), "é Beta value\n", "utf8");
+  await fs.writeFile(path.join(fixture.root_path, "ignored", "secret.ts"), "Beta hidden\n", "utf8");
+
+  const result = await execute_tool(fixture.tools, "grep", {
+    query: "beta",
+    glob: ["*.ts"],
+  });
+  assert.equal(result.success, true);
+  assert.equal(result.match_count, 1);
+  assert.deepEqual(result.matches[0], {
+    file_path: "src/main.ts",
+    line_number: 1,
+    column: 4,
+    text: "é Beta value",
+    match_text: "Beta",
+    line_truncated: false,
+  });
+  assert.equal(result.truncated, false);
+});
+
+test("grep supports case-sensitive regex and bounded results", { skip: !rg_available }, async (t) => {
+  const fixture = await create_fixture(t);
+  await fs.writeFile(
+    path.join(fixture.root_path, "values.txt"),
+    "Item 1\nitem 2\nItem 3\nItem 4\n",
+    "utf8",
+  );
+  const result = await execute_tool(fixture.tools, "grep", {
+    query: "Item [0-9]",
+    literal: false,
+    case_sensitive: true,
+    max_results: 2,
+  });
+  assert.equal(result.success, true);
+  assert.equal(result.match_count, 2);
+  assert.deepEqual(result.matches.map((item) => item.line_number), [1, 3]);
+  assert.equal(result.truncated, true);
+
+  const invalid = await execute_tool(fixture.tools, "grep", {
+    query: "(",
+    literal: false,
+  });
+  assert.equal(invalid.success, false);
+  assert.equal(invalid.error_code, "invalid_pattern");
+});
+
+test("grep rejects paths outside the project root", { skip: !rg_available }, async (t) => {
+  const fixture = await create_fixture(t);
+  const result = await execute_tool(fixture.tools, "grep", {
+    query: "outside",
+    path: fixture.outside_path,
+  });
+  assert.equal(result.success, false);
+  assert.equal(result.error_code, "sandbox_denied");
+});
+
+test("find uses glob while respecting ignore rules and dotfiles", async (t) => {
+  const fixture = await create_fixture(t);
+  await fs.mkdir(path.join(fixture.root_path, "src", "nested"), { recursive: true });
+  await fs.mkdir(path.join(fixture.root_path, "ignored"), { recursive: true });
+  await fs.writeFile(path.join(fixture.root_path, ".gitignore"), "ignored/\n", "utf8");
+  await fs.writeFile(path.join(fixture.root_path, ".config.ts"), "dot\n", "utf8");
+  await fs.writeFile(path.join(fixture.root_path, "src", "main.ts"), "main\n", "utf8");
+  await fs.writeFile(path.join(fixture.root_path, "src", "nested", "value.ts"), "value\n", "utf8");
+  await fs.writeFile(path.join(fixture.root_path, "ignored", "secret.ts"), "secret\n", "utf8");
+
+  const result = await execute_tool(fixture.tools, "find", {
+    pattern: "**/*.ts",
+  });
+  assert.equal(result.success, true);
+  assert.deepEqual(result.files, [".config.ts", "src/main.ts", "src/nested/value.ts"]);
+  assert.equal(result.match_count, 3);
+  assert.equal(result.truncated, false);
+});
+
+test("find scopes patterns to path and stops at max_results", async (t) => {
+  const fixture = await create_fixture(t);
+  await fs.writeFile(
+    path.join(fixture.root_path, ".gitignore"),
+    "src/ignored.ts\n",
+    "utf8",
+  );
+  await fs.mkdir(path.join(fixture.root_path, "src"), { recursive: true });
+  await Promise.all([
+    fs.writeFile(path.join(fixture.root_path, "src", "a.ts"), "a\n"),
+    fs.writeFile(path.join(fixture.root_path, "src", "b.ts"), "b\n"),
+    fs.writeFile(path.join(fixture.root_path, "src", "ignored.ts"), "ignored\n"),
+    fs.writeFile(path.join(fixture.root_path, "src", "c.js"), "c\n"),
+  ]);
+  const result = await execute_tool(fixture.tools, "find", {
+    pattern: "*.ts",
+    path: "src",
+    max_results: 1,
+  });
+  assert.equal(result.success, true);
+  assert.equal(result.match_count, 1);
+  assert.equal(result.files[0].startsWith("src/"), true);
+  assert.equal(result.truncated, true);
+
+  const ignored = await execute_tool(fixture.tools, "find", {
+    pattern: "ignored.ts",
+    path: "src",
+  });
+  assert.equal(ignored.success, true);
+  assert.deepEqual(ignored.files, []);
+});
+
+test("find rejects parent glob segments and does not follow symlinks", async (t) => {
+  const fixture = await create_fixture(t);
+  await fs.writeFile(path.join(fixture.outside_path, "outside.ts"), "outside\n", "utf8");
+  await fs.symlink(fixture.outside_path, path.join(fixture.root_path, "outside-link"));
+
+  const invalid = await execute_tool(fixture.tools, "find", {
+    pattern: "../**/*.ts",
+  });
+  assert.equal(invalid.success, false);
+  assert.equal(invalid.error_code, "invalid_pattern");
+
+  const result = await execute_tool(fixture.tools, "find", {
+    pattern: "**/*.ts",
+  });
+  assert.equal(result.success, true);
+  assert.deepEqual(result.files, []);
+});
+
+test("search tools expose aborted results", async (t) => {
+  const fixture = await create_fixture(t);
+  const controller = new AbortController();
+  controller.abort();
+  const result = await execute_tool(
+    fixture.tools,
+    "find",
+    { pattern: "**/*" },
+    controller.signal,
+  );
+  assert.equal(result.success, false);
+  assert.equal(result.error_code, "aborted");
+});

package/scripts/session-ask-question.test.mjs

@@ -0,0 +1,216 @@
+/**
+ * @file 验证模型通过 ask_question Tool 在同一个 Session Turn 内等待并恢复执行。
+ *
+ * 关键点（中文）
+ * - LLM 只返回标准 Tool Call，不依赖 Provider 私有的提问协议。
+ * - Session 原子持久化 Question Interaction 与 waiting-user Tool 状态。
+ * - 用户回答作为 Tool Result 返回模型，后续 Step 在同一个 Turn 中继续。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { MockLanguageModelV3 } from "ai/test";
+import { Agent, Workspace } from "@downcity/agent";
+import { AskQuestionsTool } from "@downcity/agent/tools";
+
+/** 构造 AI SDK V3 usage。 */
+function create_usage() {
+  return {
+    inputTokens: { total: 0, noCache: 0, cacheRead: 0, cacheWrite: 0 },
+    outputTokens: { total: 0, text: 0, reasoning: 0 },
+  };
+}
+
+/** 构造 ask_question Tool Call 模型流。 */
+function create_question_stream() {
+  const input = {
+    title: "选择部署区域",
+    questions: [
+      {
+        question_id: "region",
+        prompt: "需要部署到哪个区域？",
+        response_type: "single_select",
+        options: [
+          { value: "cn", label: "中国" },
+          { value: "us", label: "美国" },
+        ],
+      },
+    ],
+  };
+  return {
+    stream: new ReadableStream({
+      start(controller) {
+        controller.enqueue({ type: "stream-start", warnings: [] });
+        controller.enqueue({
+          type: "tool-input-start",
+          id: "call_ask_question",
+          toolName: "ask_question",
+        });
+        controller.enqueue({
+          type: "tool-input-delta",
+          id: "call_ask_question",
+          delta: JSON.stringify(input),
+        });
+        controller.enqueue({ type: "tool-input-end", id: "call_ask_question" });
+        controller.enqueue({
+          type: "tool-call",
+          toolCallId: "call_ask_question",
+          toolName: "ask_question",
+          input: JSON.stringify(input),
+        });
+        controller.enqueue({
+          type: "finish",
+          finishReason: { unified: "tool-calls", raw: "tool-calls" },
+          usage: create_usage(),
+        });
+        controller.close();
+      },
+    }),
+  };
+}
+
+/** 构造收到回答后的最终文本流。 */
+function create_final_text_stream() {
+  return {
+    stream: new ReadableStream({
+      start(controller) {
+        controller.enqueue({ type: "stream-start", warnings: [] });
+        controller.enqueue({ type: "text-start", id: "text_1" });
+        controller.enqueue({
+          type: "text-delta",
+          id: "text_1",
+          delta: "将部署到中国区域。",
+        });
+        controller.enqueue({ type: "text-end", id: "text_1" });
+        controller.enqueue({
+          type: "finish",
+          finishReason: { unified: "stop", raw: "stop" },
+          usage: create_usage(),
+        });
+        controller.close();
+      },
+    }),
+  };
+}
+
+test("Agent 默认不注册 ask_question", async () => {
+  const project_root = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-without-ask-question-"),
+  );
+  const agent = new Agent({
+    id: "agent_without_ask_question",
+    workspace: new Workspace({ path: project_root }),
+  });
+
+  try {
+    assert.equal("ask_question" in agent.tools, false);
+  } finally {
+    await agent.dispose();
+    await fs.rm(project_root, { recursive: true, force: true });
+  }
+});
+
+test("显式注入的 ask_question 等待回答并继续同一个 Turn", async () => {
+  const project_root = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-session-ask-question-"),
+  );
+  let stream_count = 0;
+  const model = new MockLanguageModelV3({
+    modelId: "session-ask-question-model",
+    doStream: async (options) => {
+      if (!Array.isArray(options.tools) || options.tools.length === 0) {
+        return create_final_text_stream();
+      }
+      stream_count += 1;
+      return stream_count === 1
+        ? create_question_stream()
+        : create_final_text_stream();
+    },
+    doGenerate: async () => ({
+      content: [{ type: "text", text: "Ask question test" }],
+      finishReason: { unified: "stop", raw: "stop" },
+      usage: create_usage(),
+      warnings: [],
+    }),
+  });
+  const agent = new Agent({
+    id: "session_ask_question_agent",
+    workspace: new Workspace({ path: project_root }),
+    model,
+    tools: {
+      ask_question: AskQuestionsTool,
+    },
+  });
+
+  try {
+    assert.ok(agent.tools.ask_question);
+    const session = await agent.sessions.create({
+      session_id: "session_ask_question",
+    });
+    let pending_interaction;
+    let response_result;
+    const unsubscribe = session.subscribe((mutation) => {
+      if (
+        mutation.variant !== "part" ||
+        mutation.type !== "interaction" ||
+        mutation.part.status !== "pending" ||
+        mutation.part.request.kind !== "question"
+      ) return;
+      pending_interaction = mutation.part;
+      response_result = session.respond({
+        interaction_id: mutation.part.interaction_id,
+        response: {
+          kind: "question",
+          answers: [{ question_id: "region", value: "cn" }],
+        },
+      });
+    });
+
+    const turn = await session.prompt({ query: "帮我选择部署方案" });
+    const result = await turn.finished;
+    unsubscribe();
+
+    assert.equal(result.success, true, result.error);
+    assert.equal(result.text, "将部署到中国区域。");
+    assert.equal(stream_count, 2);
+    const messages = await session.messages();
+    assert.ok(pending_interaction, JSON.stringify(messages.items, null, 2));
+    assert.equal(pending_interaction.request.turn_id, turn.id);
+    assert.deepEqual(await response_result, {
+      status: "resolved",
+      interaction_id: pending_interaction.interaction_id,
+      response: {
+        kind: "question",
+        answers: [{ question_id: "region", value: "cn" }],
+      },
+    });
+
+    const assistant_parts = messages.items.flatMap((message) =>
+      message.type === "assistant" ? message.parts : []
+    );
+    const tool_part = assistant_parts.find(
+      (part) => part.type === "tool" && part.tool_call_id === "call_ask_question",
+    );
+    const interaction_part = assistant_parts.find(
+      (part) => part.type === "interaction" &&
+        part.interaction_id === pending_interaction.interaction_id,
+    );
+    assert.equal(tool_part?.state, "completed");
+    assert.deepEqual(tool_part?.output, {
+      status: "resolved",
+      answers: [{ question_id: "region", value: "cn" }],
+    });
+    assert.equal(interaction_part?.status, "resolved");
+    assert.equal(interaction_part?.request.source.type, "tool");
+    assert.equal(
+      interaction_part?.request.source.tool_call_id,
+      "call_ask_question",
+    );
+  } finally {
+    await agent.dispose();
+    await fs.rm(project_root, { recursive: true, force: true });
+  }
+});

package/scripts/session-compact-handle.test.mjs

@@ -0,0 +1,117 @@
+/**
+ * @file 验证 session.compact() 的队列顺序与 Handle 完成语义。
+ *
+ * 关键点（中文）
+ * - `compact()` 只返回已入队 Handle，不在空闲期主动创建 Turn。
+ * - 后续 Prompt 必须等待排在它前面的 Compact Command 真正完成后才启动。
+ * - `result` 与 `finished` 使用同一个稳定领域结果。
+ */
+
+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 { MockLanguageModelV3 } from "ai/test";
+
+import {
+  Agent,
+  DefaultSessionComposer,
+  Session,
+  Workspace,
+} from "../bin/index.js";
+
+function create_deferred() {
+  let resolve;
+  const promise = new Promise((inner_resolve) => {
+    resolve = inner_resolve;
+  });
+  return { promise, resolve };
+}
+
+function create_stream_text_result(text) {
+  return {
+    stream: new ReadableStream({
+      start(controller) {
+        controller.enqueue({ type: "stream-start", warnings: [] });
+        controller.enqueue({ type: "text-start", id: "text_1" });
+        controller.enqueue({ type: "text-delta", id: "text_1", delta: text });
+        controller.enqueue({ type: "text-end", id: "text_1" });
+        controller.enqueue({
+          type: "finish",
+          finishReason: { unified: "stop", raw: "stop" },
+          usage: {
+            inputTokens: { total: 0, noCache: 0, cacheRead: 0, cacheWrite: 0 },
+            outputTokens: { total: 0, text: 0, reasoning: 0 },
+          },
+        });
+        controller.close();
+      },
+    }),
+  };
+}
+
+test("compact Handle 在队列命令完成后兑现并阻塞后续 Prompt", async () => {
+  const compact_started = create_deferred();
+  const release_compact = create_deferred();
+
+  class CompactComposer extends DefaultSessionComposer {
+    async compact() {
+      compact_started.resolve();
+      await release_compact.promise;
+      return null;
+    }
+  }
+
+  class CompactSession extends Session {
+    constructor(options) {
+      super({ ...options, composer: new CompactComposer() });
+    }
+  }
+
+  const project_root = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-session-compact-handle-"),
+  );
+  const agent = new Agent({
+    id: "compact_handle_agent",
+    workspace: new Workspace({ path: project_root }),
+    model: new MockLanguageModelV3({
+      modelId: "compact-handle-model",
+      doStream: async () => create_stream_text_result("done"),
+    }),
+    session_class: CompactSession,
+  });
+
+  try {
+    const session = await agent.sessions.create({
+      session_id: "compact_handle_session",
+    });
+    const compact_handle = await session.compact();
+    assert.equal(compact_handle.result, null);
+
+    let prompt_returned = false;
+    const prompt_promise = session.prompt({ query: "continue" }).then((handle) => {
+      prompt_returned = true;
+      return handle;
+    });
+    await compact_started.promise;
+    assert.equal(prompt_returned, false);
+    assert.equal(compact_handle.result, null);
+
+    release_compact.resolve();
+    const turn_handle = await prompt_promise;
+    const compact_result = await compact_handle.finished;
+    assert.deepEqual(compact_result, {
+      compact_id: compact_handle.id,
+      success: true,
+      compacted: false,
+      reason: "nothing_to_compact",
+    });
+    assert.deepEqual(compact_handle.result, compact_result);
+    assert.equal((await turn_handle.finished).success, true);
+  } finally {
+    release_compact.resolve();
+    await agent.dispose();
+    await fs.rm(project_root, { recursive: true, force: true });
+  }
+});

package/scripts/session-composer.test.mjs

@@ -12,6 +12,7 @@ import {
   Agent,
   DefaultSessionComposer,
   Session,
+  Workspace,
 } from "../bin/index.js";
 
 function create_input(model) {
@@ -120,13 +121,13 @@ test("Session system 快照与 Custom Composer 的实际模型输入一致", asy
   );
   const agent = new Agent({
     id: "custom_composer_agent",
-    path: project_root,
+    workspace: new Workspace({ path: project_root }),
     model: new MockLanguageModelV3({ modelId: "custom-composer-model" }),
-    Session: CustomSession,
+    session_class: CustomSession,
   });
   try {
     const session = await agent.sessions.create({
-      sessionId: "custom_composer_session",
+      session_id: "custom_composer_session",
     });
     const snapshot = await session.system();
     assert.equal(snapshot.blocks.at(-1).content, "Custom snapshot behavior");
@@ -153,8 +154,9 @@ test("Composer compact 只返回计划，不修改 Message 快照", async () =>
   const input = create_input(model);
   const before = structuredClone(input.history);
   const plan = await new DefaultSessionComposer().compact({
-    ...input,
-    force: true,
+    session: input.session,
+    model: input.state.model,
+    history: input.history,
   });
 
   assert.equal(plan.through_sequence, 1);