@downcity/agent 1.1.189 → 1.1.196

package/bin/types/sdk/AgentSessionOperation.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Agent Session operation 类型定义。
+ *
+ * 关键点（中文）
+ * - operation 描述 session 内部正在发生的辅助操作，不代表 assistant 正文。
+ * - operation 可以同时作为订阅事件发布，也可以作为 UIMessage 持久化到 JSONL。
+ * - operation message 只用于前端时间线与调试，不应进入 LLM 输入。
+ */
+import type { JsonValue } from "../../types/common/Json.js";
+/**
+ * Session operation 当前状态。
+ */
+export type AgentSessionOperationStatus = "started" | "progress" | "finished" | "skipped" | "failed";
+/**
+ * Session operation 名称。
+ *
+ * 说明（中文）
+ * - 内置名称用于 SDK 与前端约定常见辅助操作。
+ * - 字符串扩展允许 plugin 或宿主运行时声明自己的 operation。
+ */
+export type AgentSessionOperationName = "compacting" | "model-switching" | "history-forking" | (string & {});
+/**
+ * Session operation 记录。
+ */
+export interface AgentSessionOperationRecord {
+    /**
+     * 同一个 operation 生命周期内稳定复用的 ID。
+     */
+    operationId: string;
+    /**
+     * 当前 operation 名称。
+     */
+    name: AgentSessionOperationName;
+    /**
+     * 当前 operation 状态。
+     */
+    status: AgentSessionOperationStatus;
+    /**
+     * 当前 operation 关联的 turn 标识。
+     *
+     * 说明（中文）
+     * - turn 内触发的 operation 应写入该字段。
+     * - session 级 operation 可以省略。
+     */
+    turnId?: string;
+    /**
+     * 面向用户展示的短文本。
+     */
+    label?: string;
+    /**
+     * 机器可读原因。
+     *
+     * 示例（中文）
+     * - `under_budget`：未达到压缩阈值。
+     * - `summary_fallback`：摘要生成失败后使用降级摘要。
+     */
+    reason?: string;
+    /**
+     * 当前 operation 进度，范围 0 到 1。
+     *
+     * 说明（中文）
+     * - 无法估算进度时省略。
+     */
+    progress?: number;
+    /**
+     * operation 完成后产生的轻量结果。
+     */
+    result?: JsonValue;
+    /**
+     * operation 失败时的错误文本。
+     */
+    error?: string;
+    /**
+     * 是否建议前端展示。
+     *
+     * 说明（中文）
+     * - 默认视为 `true`。
+     * - 调试或审计类辅助事件可显式写入 `false`。
+     */
+    visible?: boolean;
+}
+/**
+ * Session operation 订阅事件。
+ */
+export interface AgentSessionOperationEvent extends AgentSessionOperationRecord {
+    /**
+     * 当前事件类型。
+     */
+    type: "operation";
+    /**
+     * 当前 session 唯一标识。
+     */
+    sessionId: string;
+}
+/**
+ * Session operation 发布回调。
+ */
+export type AgentSessionOperationCallback = (operation: AgentSessionOperationEvent) => Promise<void>;
+//# sourceMappingURL=AgentSessionOperation.d.ts.map

package/bin/types/sdk/AgentSessionOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionOperation.d.ts","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionOperation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,2BAA2B,GACnC,SAAS,GACT,UAAU,GACV,UAAU,GACV,SAAS,GACT,QAAQ,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GACjC,YAAY,GACZ,iBAAiB,GACjB,iBAAiB,GACjB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,IAAI,EAAE,yBAAyB,CAAC;IAEhC;;OAEG;IACH,MAAM,EAAE,2BAA2B,CAAC;IAEpC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA2B,SAAQ,2BAA2B;IAC7E;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC;IAElB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAC1C,SAAS,EAAE,0BAA0B,KAClC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/bin/types/sdk/AgentSessionOperation.js

@@ -0,0 +1,10 @@
+/**
+ * Agent Session operation 类型定义。
+ *
+ * 关键点（中文）
+ * - operation 描述 session 内部正在发生的辅助操作，不代表 assistant 正文。
+ * - operation 可以同时作为订阅事件发布，也可以作为 UIMessage 持久化到 JSONL。
+ * - operation message 只用于前端时间线与调试，不应进入 LLM 输入。
+ */
+export {};
+//# sourceMappingURL=AgentSessionOperation.js.map

package/bin/types/sdk/AgentSessionOperation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionOperation.js","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionOperation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.189",
+  "version": "1.1.196",
   "type": "module",
   "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
   "main": "./bin/index.js",
@@ -17,8 +17,8 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "^2.0.48",
-    "@downcity/shell": "^0.1.61",
-    "@downcity/type": "0.1.94",
+    "@downcity/shell": "^0.1.66",
+    "@downcity/type": "0.1.99",
     "ai": "^6.0.193",
     "commander": "^15.0.0",
     "dotenv": "^17.4.2",

package/scripts/agent-ready.test.mjs

@@ -0,0 +1,168 @@
+/**
+ * @file 验证 session.prompt 会等待当前 Agent 后台能力 ready。
+ *
+ * 关键点（中文）
+ * - 这里走编译后的公开 SDK，覆盖宿主真实入口。
+ * - plugin lifecycle 未完成前，session.prompt 不应进入模型执行。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+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";
+
+function create_deferred() {
+  let resolve;
+  const promise = new Promise((inner_resolve) => {
+    resolve = inner_resolve;
+  });
+  return {
+    promise,
+    resolve,
+  };
+}
+
+async function is_settled(promise) {
+  const marker = {};
+  const result = await Promise.race([
+    promise.then(
+      () => true,
+      () => true,
+    ),
+    new Promise((resolve) => setTimeout(() => resolve(marker), 0)),
+  ]);
+  return result !== marker;
+}
+
+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("session.prompt waits for agent background ready before model execution", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-ready-"),
+  );
+  const lifecycle_ready = create_deferred();
+  let model_stream_calls = 0;
+
+  const blocking_plugin = createPlugin({
+    name: "blocking",
+    title: "Blocking",
+    description: "Blocks lifecycle start until the test releases it",
+    lifecycle: {
+      start: async () => {
+        await lifecycle_ready.promise;
+      },
+    },
+  });
+  const model = new MockLanguageModelV3({
+    modelId: "agent-ready-model",
+    doStream: async () => {
+      model_stream_calls += 1;
+      return create_stream_text_result("ready");
+    },
+    doGenerate: async () => ({
+      content: [
+        {
+          type: "text",
+          text: "Ready title",
+        },
+      ],
+      finishReason: {
+        unified: "stop",
+        raw: "stop",
+      },
+      usage: {
+        inputTokens: {
+          total: 0,
+          noCache: 0,
+          cacheRead: 0,
+          cacheWrite: 0,
+        },
+        outputTokens: {
+          total: 0,
+          text: 0,
+          reasoning: 0,
+        },
+      },
+      warnings: [],
+    }),
+  });
+  const agent = new Agent({
+    id: "ready_agent",
+    path: agent_path,
+    plugins: [blocking_plugin],
+    model,
+  });
+
+  try {
+    const session = await agent.session_collection().create_session({
+      sessionId: "ready_session",
+    });
+    const prompt_promise = session.prompt({
+      query: "hello",
+    });
+
+    assert.equal(await is_settled(prompt_promise), false);
+    assert.equal(model_stream_calls, 0);
+
+    lifecycle_ready.resolve();
+    const turn = await prompt_promise;
+    const result = await turn.finished;
+
+    assert.equal(result.success, true);
+    assert.equal(model_stream_calls, 1);
+  } finally {
+    lifecycle_ready.resolve();
+    await agent.dispose();
+  }
+});
+

package/scripts/plugin-tool-bridge.test.mjs

@@ -15,8 +15,8 @@ import fs from "node:fs/promises";
 import {
   invokePluginCallTool,
   invokePluginReadTool,
-  setPluginToolRuntime,
 } from "../bin/executor/tools/plugin/PluginToolBridge.js";
+import { createPluginTools } from "../bin/executor/tools/plugin/PluginToolDefinition.js";
 import { withSessionRunScope } from "../bin/executor/SessionRunScope.js";
 import { createAction, createPlugin } from "../bin/plugin/core/PluginActionFactory.js";
 import { createAgentPluginRegistry } from "../bin/agent/local/AgentPluginFactory.js";
@@ -38,7 +38,7 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
   );
   const bytes = Buffer.from("png-bytes-for-plugin-tool", "utf8");
 
-  setPluginToolRuntime({
+  const plugins = {
     list: () => [],
     read: () => ({ plugins: [] }),
     availability: async () => ({ enabled: true, available: true, reasons: [] }),
@@ -64,14 +64,17 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
     resolve: async () => {
       throw new Error("not implemented");
     },
-  });
+  };
 
   const run_context = create_run_context(project_root);
   const result = await withSessionRunScope({ runContext: run_context }, () =>
     invokePluginCallTool({
-      plugin: "image",
-      action: "image_result",
-      payload: { job_id: "img_1" },
+      plugins,
+      input: {
+        plugin: "image",
+        action: "image_result",
+        payload: { job_id: "img_1" },
+      },
     }),
   );
 
@@ -93,7 +96,7 @@ test("invokePluginCallTool returns absolute paths for materialized file parts",
 });
 
 test("invokePluginReadTool returns plugin action metadata", async () => {
-  setPluginToolRuntime({
+  const plugins = {
     list: () => [],
     read: () => ({
       name: "image",
@@ -130,11 +133,14 @@ test("invokePluginReadTool returns plugin action metadata", async () => {
     resolve: async () => {
       throw new Error("not implemented");
     },
-  });
+  };
 
   const result = await invokePluginReadTool({
-    plugin: "image",
-    action: "image_create",
+    plugins,
+    input: {
+      plugin: "image",
+      action: "image_create",
+    },
   });
 
   assert.equal(result.success, true);
@@ -174,6 +180,7 @@ test("PluginRegistry validates action payload with metadata schema", async () =>
   });
   const registry = createAgentPluginRegistry({
     plugins: [plugin],
+    plugin_instances: new Map(),
     get_context: () => ({ rootPath: process.cwd() }),
   });
 
@@ -197,3 +204,100 @@ test("PluginRegistry validates action payload with metadata schema", async () =>
   assert.equal(valid.success, true);
   assert.equal(valid.data.text, "hello");
 });
+
+test("createPluginTools binds plugin_call to the current registry", async () => {
+  function create_owner_registry(owner) {
+    const plugin = createPlugin({
+      name: "skill",
+      title: `Skill ${owner}`,
+      description: "Owner scoped skill plugin",
+      actions: {
+        lookup: createAction({
+          description: "Return registry owner",
+          execute: async () => ({
+            success: true,
+            data: { owner },
+            message: owner,
+          }),
+        }),
+      },
+    });
+    return createAgentPluginRegistry({
+      plugins: [plugin],
+      plugin_instances: new Map(),
+      get_context: () => ({ rootPath: process.cwd() }),
+    });
+  }
+
+  const registry_a = create_owner_registry("agent_a");
+  const registry_b = create_owner_registry("agent_b");
+  const tools_a = createPluginTools({ plugins: registry_a });
+  const tools_b = createPluginTools({ plugins: registry_b });
+
+  const result_a = await tools_a.plugin_call.execute({
+    plugin: "skill",
+    action: "lookup",
+    payload: { name: "anything" },
+  });
+  const result_b = await tools_b.plugin_call.execute({
+    plugin: "skill",
+    action: "lookup",
+    payload: { name: "anything" },
+  });
+
+  assert.equal(result_a.success, true);
+  assert.equal(result_a.data.value.owner, "agent_a");
+  assert.equal(result_b.success, true);
+  assert.equal(result_b.data.value.owner, "agent_b");
+});
+
+test("PluginRegistry keeps plugin ready after action business failure", async () => {
+  let call_count = 0;
+  const plugin = createPlugin({
+    name: "skill",
+    title: "Skill",
+    description: "Retryable skill plugin",
+    actions: {
+      lookup: createAction({
+        description: "Fail once then succeed",
+        execute: async () => {
+          call_count += 1;
+          if (call_count === 1) {
+            return {
+              success: false,
+              error: "Skill not found: missing",
+              message: "Skill not found: missing",
+            };
+          }
+          return {
+            success: true,
+            data: { loaded: true },
+            message: "loaded",
+          };
+        },
+      }),
+    },
+  });
+  const registry = createAgentPluginRegistry({
+    plugins: [plugin],
+    plugin_instances: new Map(),
+    get_context: () => ({ rootPath: process.cwd() }),
+  });
+
+  const failed = await registry.runAction({
+    plugin: "skill",
+    action: "lookup",
+    payload: { name: "missing" },
+  });
+  assert.equal(failed.success, false);
+  assert.equal(registry.status("skill").state, "ready");
+
+  const retry = await registry.runAction({
+    plugin: "skill",
+    action: "lookup",
+    payload: { name: "exists" },
+  });
+  assert.equal(retry.success, true);
+  assert.equal(retry.data.loaded, true);
+  assert.equal(registry.status("skill").state, "ready");
+});

package/scripts/session-operation-message.test.mjs

@@ -0,0 +1,182 @@
+/**
+ * @file 验证 operation message 的持久化、模型输入过滤与 timeline 投影。
+ *
+ * 关键点（中文）
+ * - operation message 会作为 UIMessage 写入 JSONL。
+ * - history composer 组装 LLM 输入时必须过滤 operation message。
+ * - timeline view 可以把 operation message 投影成前端可识别的 operation 事件。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+import { JsonlSessionHistoryStore } from "../bin/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
+import { JsonlSessionHistoryComposer } from "../bin/executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
+import { toSessionTimelineEvents } from "../bin/session/browse/Browse.js";
+import { Agent } from "../bin/index.js";
+
+test("operation message is persisted but filtered from LLM history", async () => {
+  const root_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-operation-message-"),
+  );
+  const session_id = "operation_session";
+  const store = new JsonlSessionHistoryStore({
+    rootPath: root_path,
+    agentId: "operation_agent",
+    sessionId: session_id,
+  });
+  const composer = new JsonlSessionHistoryComposer({ store });
+
+  await store.append(
+    store.userText({
+      text: "hello",
+      metadata: { sessionId: session_id },
+      id: "u:1",
+    }),
+  );
+  await store.append(
+    store.operation({
+      operation: {
+        operationId: "op-1",
+        name: "compacting",
+        status: "started",
+        label: "Compacting session history",
+        turnId: "turn-1",
+      },
+      metadata: { sessionId: session_id },
+      id: "op:1",
+    }),
+  );
+  await store.append(
+    store.assistantText({
+      text: "world",
+      metadata: { sessionId: session_id },
+      id: "a:1",
+    }),
+  );
+
+  const persisted_messages = await store.list();
+  assert.equal(persisted_messages.length, 3);
+  assert.equal(persisted_messages[1].metadata.kind, "operation");
+  assert.equal(persisted_messages[1].metadata.operation.operationId, "op-1");
+
+  const model_messages = await composer.prepare({
+    query: "",
+    tools: {},
+    system: [],
+    model: {},
+    retryCount: 0,
+  });
+  assert.deepEqual(
+    model_messages.map((message) => message.id),
+    ["u:1", "a:1"],
+  );
+
+  const timeline_events = toSessionTimelineEvents(persisted_messages[1]);
+  assert.equal(timeline_events.length, 1);
+  assert.equal(timeline_events[0].role, "operation");
+  assert.equal(timeline_events[0].operationId, "op-1");
+  assert.equal(timeline_events[0].operationName, "compacting");
+  assert.equal(timeline_events[0].operationStatus, "started");
+  assert.equal(timeline_events[0].text, "Compacting session history");
+});
+
+test("session.set persists and publishes model-switching operations", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-model-switching-"),
+  );
+  const agent = new Agent({
+    id: "model_switching_agent",
+    path: agent_path,
+  });
+  try {
+    const session = await agent.session_collection().create_session({
+      sessionId: "model_switching_session",
+    });
+    const events = [];
+    const unsubscribe = session.subscribe((event) => {
+      if (event.type === "operation") events.push(event);
+    });
+
+    await session.set({
+      model: {
+        modelId: "test-model",
+        provider: "test",
+      },
+    });
+    unsubscribe();
+
+    assert.deepEqual(
+      events.map((event) => `${event.name}:${event.status}`),
+      ["model-switching:started", "model-switching:finished"],
+    );
+
+    const history = await session.history({ view: "timeline" });
+    const operation_events = history.items.filter(
+      (item) => item.role === "operation",
+    );
+    assert.deepEqual(
+      operation_events.map((event) => `${event.operationName}:${event.operationStatus}`),
+      ["model-switching:started", "model-switching:finished"],
+    );
+  } finally {
+    await agent.dispose();
+  }
+});
+
+test("session.fork persists and publishes history-forking operations on source session", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-history-forking-"),
+  );
+  const agent = new Agent({
+    id: "history_forking_agent",
+    path: agent_path,
+  });
+  try {
+    const session = await agent.session_collection().create_session({
+      sessionId: "history_forking_session",
+    });
+    await session.set({
+      model: {
+        modelId: "fork-test-model",
+        provider: "test",
+      },
+    });
+    await session.appendUserMessage({ text: "source message" });
+
+    const events = [];
+    const unsubscribe = session.subscribe((event) => {
+      if (event.type === "operation" && event.name === "history-forking") {
+        events.push(event);
+      }
+    });
+    const forked = await session.fork();
+    unsubscribe();
+
+    assert.deepEqual(
+      events.map((event) => `${event.name}:${event.status}`),
+      ["history-forking:started", "history-forking:finished"],
+    );
+    assert.notEqual(forked.id, session.id);
+
+    const source_history = await session.history({ view: "timeline" });
+    const source_fork_operations = source_history.items.filter(
+      (item) => item.operationName === "history-forking",
+    );
+    assert.deepEqual(
+      source_fork_operations.map((event) => event.operationStatus),
+      ["started", "finished"],
+    );
+
+    const forked_history = await forked.history({ view: "timeline" });
+    const forked_model_operations = forked_history.items.filter(
+      (item) => item.operationName === "model-switching",
+    );
+    assert.equal(forked_model_operations.length, 2);
+  } finally {
+    await agent.dispose();
+  }
+});

package/src/agent/local/Agent.ts

@@ -90,14 +90,14 @@ export class Agent {
     this.instruction = assembly.instruction;
     this.shell = assembly.shell;
 
-    this.sessionManager = this.create_session_manager(assembly);
-    session_manager_ref = this.sessionManager;
     // 关键点（中文）：构造完成即触发后台能力启动；调用方可 `await agent.ready()` 等待。
     this.backgroundService = new AgentBackgroundService({
       logger: this.logger,
       agent_context: this.agentContext,
       get_shell: () => this.shell,
     });
+    this.sessionManager = this.create_session_manager(assembly);
+    session_manager_ref = this.sessionManager;
   }
 
   /**
@@ -269,6 +269,9 @@ export class Agent {
       get_agent_context: () => this.agentContext ?? assembly.agent_context,
       get_instruction: () => this.instruction,
       plugin_instances: assembly.plugin_instances,
+      ensure_agent_ready: async () => {
+        await this.backgroundService.ready();
+      },
       default_model: this.defaultModel,
       SessionClass: this.SessionClass,
     });