@ycodium-ai/agent-fake 0.2.3230 → 0.2.3232

package/README.md

@@ -4,7 +4,7 @@ A minimal executor plugin. It starts no CLI and replays a fixed event script:
 
 - `startSession` emits `session.started`
 - `sendTurn` emits `turn.started`, one `content.delta`, then `turn.completed` (the host binds the turn by `turn.started`)
-- `config.script` picks the script: `plain` (default), `approval-tool` (two approvals before the reply), `async-question` (on a thread's first turn, the reply plus one non-blocking `user-input.requested` with `responseMode: "message"`), `stream` (a Markdown answer in `config.streamChunks` deltas, default 200, one every `config.streamIntervalMs`, default 30; the UI probe `interaction-table.ts` measures streaming with it), `mcp-send` (real calls through the built-in MCP server the host handed to `startSession`, the same path a real agent takes: a turn whose input is a JSON object is passed as the arguments of one `send_message` call, and a JSON array of `{ "tool": "…", "arguments": { … } }` is called step by step, for example `ycodium_plugin_define`, then `ycodium_plugin_run`, then a tool the mounted plugin contributes; the reply has one line per call with its result or error, and any other input gets the plain reply; see [Playbook mode](#playbook-mode) for per-thread scripts that ignore turn input), `visualize` (emits one in-progress builtin tool row, holds for `config.previewHoldMs` milliseconds so the input preview can paint, then one real `visualize_visualize` call on that same server; the tool row’s result is the MCP confirmation text, and the reply is “The figure is in the card above.”), or `lane` (the UI probe `lane1-journey.ts` script: the user message's `lane:stream|plain|approve|question|attach|hold` picks the turn; `hold` accepts a second `sendTurn` with the in-flight turn id as a steer and folds that text into the reply; `config.holdMs` is how long `hold` waits, default 15000)
+- `config.script` picks the script: `plain` (default), `approval-tool` (two approvals before the reply), `async-question` (on a thread's first turn, the reply plus one non-blocking `user-input.requested` with `responseMode: "message"`), `stream` (a Markdown answer in `config.streamChunks` deltas, default 200, one every `config.streamIntervalMs`, default 30; the UI probe `interaction-table.ts` measures streaming with it), `replay` (recorded events; see [Event replay](#event-replay)), `mcp-send` (real calls through the built-in MCP server the host handed to `startSession`, the same path a real agent takes: a turn whose input is a JSON object is passed as the arguments of one `send_message` call, and a JSON array of `{ "tool": "…", "arguments": { … } }` is called step by step, for example `ycodium_plugin_define`, then `ycodium_plugin_run`, then a tool the mounted plugin contributes; the reply has one line per call with its result or error, and any other input gets the plain reply; see [Playbook mode](#playbook-mode) for per-thread scripts that ignore turn input), `visualize` (emits one in-progress builtin tool row, holds for `config.previewHoldMs` milliseconds so the input preview can paint, then one real `visualize_visualize` call on that same server; the tool row’s result is the MCP confirmation text, and the reply is “The figure is in the card above.”), or `lane` (the UI probe `lane1-journey.ts` script: the user message's `lane:stream|plain|approve|question|attach|hold` picks the turn; `hold` accepts a second `sendTurn` with the in-flight turn id as a steer and folds that text into the reply; `config.holdMs` is how long `hold` waits, default 15000)
 - `interruptTurn` (or an aborted `AbortSignal`) ends the in-flight turn as `interrupted`
 - `readThread` returns the bookkeeping the instance recorded
 - `probe` reports two models, `fake` (default) and `fake-large`
@@ -23,6 +23,37 @@ This package is **not** in the default bundle and **not** a first-party add-grid
 
 Develop with `vp run --filter @ycodium-ai/agent-fake typecheck`, `build`, and `test`.
 
+## Event replay
+
+Set `config.script: "replay"` to replay recorded `ExecutorEvent` output through the fake's
+event emitter. `config.replayEventsPath` must be an absolute path on the executor's machine
+to a JSON array or an adapter golden object with an `events` array. The file is read on each
+turn; an unreadable file, invalid event envelope or malformed JSON fails that turn with a
+`replay:` error. The plugin does not bundle recordings or depend on another executor plugin.
+
+```json
+{
+  "script": "replay",
+  "replayEventsPath": "/absolute/path/to/recorded-events.json",
+  "replayStepMs": 50,
+  "replayTaskHoldMs": 4000
+}
+```
+
+`replayStepMs` sets the interval between retained events (default 30 ms).
+`replayTaskHoldMs` adds a hold after every `task.started` (default 3000 ms), so observers can
+read the working state before completion. Both are non-negative integers; zero disables
+that delay. These settings are outside the settings form. Timing is configured, not recorded.
+
+Replay keeps items, content, tasks, plans and other turn-local events. Lifecycle events
+(`isExecutorLifecycleEvent` in the plugin API: session, thread and turn lifecycle, plus
+`runtime.error`, which the host turns into a session error) are owned by the fake and never
+replayed, so a recording cannot fail the turn behind the fake's back. See the allowlist in
+[`replayScript.ts`](src/replayScript.ts). Events get the current thread and turn IDs and fresh
+event metadata. Item, request and task IDs are fresh per replay, with tool/task links kept
+consistent. Adapter golden `⟨undefined⟩` fields are omitted. Assistant text is also recorded
+by `readThread`. Interrupting a replay cancels its delays and ends the turn as `interrupted`.
+
 ## Playbook mode
 
 Replay recorded conversations or drive multi-thread acceptance tests with

package/dist/index.js

@@ -2,6 +2,16 @@
 import { definePlugin } from "@ycodium-ai/plugin-api";
 
 // src/card.ts
+var FAKE_SCRIPTS = [
+  "plain",
+  "approval-tool",
+  "async-question",
+  "stream",
+  "replay",
+  "mcp-send",
+  "visualize",
+  "lane"
+];
 var FAKE_DRIVER_KIND = "fake";
 var FAKE_ASSISTANT_TEXT = "fake turn complete";
 var FAKE_CARD = {
@@ -45,18 +55,13 @@ var FAKE_CARD = {
     properties: {
       script: {
         type: "string",
-        enum: [
-          "plain",
-          "approval-tool",
-          "async-question",
-          "stream",
-          "mcp-send",
-          "visualize",
-          "lane"
-        ]
+        enum: [...FAKE_SCRIPTS]
       },
       streamChunks: { type: "integer", minimum: 1 },
       streamIntervalMs: { type: "integer", minimum: 0 },
+      replayEventsPath: { type: "string" },
+      replayStepMs: { type: "integer", minimum: 0 },
+      replayTaskHoldMs: { type: "integer", minimum: 0 },
       // 仅探针与测试故意违约：stop 收完后台轮但不发 session.exited，事件流仍打开；默认关闭，不进设置表单。
       stopWithoutExit: { type: "boolean" },
       // lane 的 hold 最多等插话多久；不进设置表单。
@@ -125,6 +130,131 @@ var EventBus = class {
   }
 };
 
+// src/approvalToolScript.ts
+function createApprovalToolScript({
+  emit,
+  nextId,
+  pendingDecisions,
+  yieldTick: yieldTick2
+}) {
+  const runApprovalToolScript = async (threadId, turnId, signal) => {
+    const isAborted = () => signal?.aborted === true;
+    const fakeReply = "\u597D";
+    emit(
+      "content.delta",
+      threadId,
+      {
+        streamKind: "reasoning_text",
+        delta: "\u5148\u60F3\u6E05\u695A\u6B65\u9AA4\uFF1A\u7B2C\u4E00\u6B65 ls \u5F53\u524D\u76EE\u5F55\uFF1B\u7B2C\u4E8C\u6B65\u8BFB README.md \u7684\u7B2C\u4E00\u884C\uFF1B\u6700\u540E\u53EA\u56DE\u4E00\u4E2A\u5B57\u3002"
+      },
+      { turnId }
+    );
+    await yieldTick2();
+    if (isAborted()) return null;
+    const approve = async (request) => {
+      emit(
+        "item.started",
+        threadId,
+        {
+          itemType: request.itemType,
+          status: "inProgress",
+          title: request.title,
+          data: request.args
+        },
+        { turnId, itemId: request.itemId }
+      );
+      emit(
+        "request.opened",
+        threadId,
+        {
+          requestType: request.requestType,
+          toolName: request.toolName,
+          detail: request.detail,
+          args: request.args
+        },
+        { turnId, requestId: request.requestId }
+      );
+      const decision = await new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+          if (settled) return;
+          settled = true;
+          signal?.removeEventListener("abort", onAbort);
+          pendingDecisions.delete(request.requestId);
+          resolve(value);
+        };
+        const onAbort = () => settle("cancel");
+        signal?.addEventListener("abort", onAbort);
+        if (isAborted()) {
+          settle("cancel");
+          return;
+        }
+        pendingDecisions.set(request.requestId, settle);
+      });
+      emit(
+        "request.resolved",
+        threadId,
+        {
+          requestType: request.requestType,
+          decision: decision === "allow" ? "accept" : decision === "deny" ? "decline" : "cancel"
+        },
+        { turnId, requestId: request.requestId }
+      );
+      if (decision === "allow") {
+        emit(
+          "content.delta",
+          threadId,
+          { streamKind: "command_output", delta: request.output },
+          { turnId, itemId: request.itemId }
+        );
+      }
+      emit(
+        "item.completed",
+        threadId,
+        {
+          itemType: request.itemType,
+          status: decision === "allow" ? "completed" : "declined",
+          title: request.title,
+          data: { ...request.args, ...decision === "allow" ? { output: request.output } : {} }
+        },
+        { turnId, itemId: request.itemId }
+      );
+      return decision;
+    };
+    const first = await approve({
+      itemId: nextId("item"),
+      requestId: nextId("req"),
+      requestType: "exec_command_approval",
+      toolName: "shell",
+      detail: "ls",
+      args: { command: "ls" },
+      itemType: "command_execution",
+      title: "ls",
+      output: "README.md\n"
+    });
+    if (first === "cancel") return null;
+    if (first === "allow") {
+      const second = await approve({
+        itemId: nextId("item"),
+        requestId: nextId("req"),
+        requestType: "file_read_approval",
+        toolName: "Read",
+        detail: "README.md",
+        args: { file_path: "README.md" },
+        itemType: "dynamic_tool_call",
+        title: "Read README.md",
+        output: "# hands-probe-workspace\n"
+      });
+      if (second === "cancel") return null;
+    }
+    if (isAborted()) return null;
+    emit("content.delta", threadId, { streamKind: "assistant_text", delta: fakeReply }, { turnId });
+    await yieldTick2();
+    return isAborted() ? null : fakeReply;
+  };
+  return runApprovalToolScript;
+}
+
 // src/fakeSessionLifecycle.ts
 var parseStopWithoutExit = (input) => {
   const envelope = input;
@@ -1239,6 +1369,112 @@ async function runVisualizeTurn(input) {
   return resultText.length > 0 ? REPLY : "visualize failed: empty tool result";
 }
 
+// src/replayScript.ts
+import * as NodeFSP2 from "node:fs/promises";
+import * as NodePath2 from "node:path";
+import { isExecutorLifecycleEvent } from "@ycodium-ai/plugin-api/executor";
+var IN_TURN_TYPES = /* @__PURE__ */ new Set([
+  "item.started",
+  "item.updated",
+  "item.completed",
+  "content.delta",
+  "task.started",
+  "task.progress",
+  "task.updated",
+  "task.completed",
+  "turn.plan.updated",
+  "turn.proposed.delta",
+  "turn.proposed.completed",
+  "turn.diff.updated",
+  "request.opened",
+  "request.resolved",
+  "user-input.requested",
+  "user-input.resolved",
+  "hook.started",
+  "hook.progress",
+  "hook.completed",
+  "tool.progress",
+  "tool.summary",
+  "tool.denied",
+  "model.rerouted",
+  "files.persisted",
+  "assistant.attachment.produced",
+  "assistant.artifact.produced",
+  "runtime.warning"
+]);
+var IDENTITY_FIELDS = [
+  ["taskId", "task"],
+  ["agentId", "task"],
+  ["parentAgentId", "task"],
+  ["toolUseId", "item"],
+  ["parentToolUseId", "item"]
+];
+var isRecord3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function parseEvents(text) {
+  const parsed = JSON.parse(
+    text,
+    (_key, value) => value === "\u27E8undefined\u27E9" ? void 0 : value
+  );
+  const events = isRecord3(parsed) ? parsed.events : parsed;
+  if (!Array.isArray(events))
+    throw new Error("expected ExecutorEvent[] or { events: ExecutorEvent[] }");
+  return events.map((event, index) => {
+    if (!isRecord3(event) || !["type", "eventId", "provider", "threadId", "createdAt"].every(
+      (key) => typeof event[key] === "string"
+    ) || !isRecord3(event.payload) || !["turnId", "itemId", "requestId"].every(
+      (key) => event[key] === void 0 || typeof event[key] === "string"
+    ))
+      throw new Error(`invalid ExecutorEvent at index ${index}`);
+    return event;
+  }).filter((event) => !isExecutorLifecycleEvent(event) && IN_TURN_TYPES.has(event.type));
+}
+async function runReplayTurn(input) {
+  const config = input.config?.config;
+  const path = config?.replayEventsPath;
+  const duration = (key, fallback) => {
+    const value = config?.[key] ?? fallback;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+      throw new Error(`replay: ${key} must be a non-negative integer`);
+    return value;
+  };
+  const stepMs = duration("replayStepMs", 30);
+  const taskHoldMs = duration("replayTaskHoldMs", 3e3);
+  if (typeof path !== "string" || !NodePath2.isAbsolute(path))
+    throw new Error("replay: replayEventsPath must be an absolute path");
+  let events;
+  try {
+    events = parseEvents(await NodeFSP2.readFile(path, "utf8"));
+  } catch (error) {
+    throw new Error(`replay: ${path}: ${error instanceof Error ? error.message : String(error)}`, {
+      cause: error
+    });
+  }
+  const ids = /* @__PURE__ */ new Map();
+  const remap = (kind, id) => {
+    const key = `${kind}:${id}`;
+    if (!ids.has(key)) ids.set(key, input.nextId(kind));
+    return ids.get(key);
+  };
+  let text = "";
+  for (const [index, event] of events.entries()) {
+    if (index > 0) await hold(stepMs, input.signal);
+    if (input.signal.aborted) return null;
+    const payload = { ...event.payload };
+    for (const [key, kind] of IDENTITY_FIELDS) {
+      if (typeof payload[key] === "string") payload[key] = remap(kind, payload[key]);
+    }
+    input.emit(event.type, input.threadId, payload, {
+      turnId: input.turnId,
+      ...event.itemId === void 0 ? {} : { itemId: remap("item", event.itemId) },
+      ...event.requestId === void 0 ? {} : { requestId: remap("request", event.requestId) }
+    });
+    if (event.type === "content.delta" && payload.streamKind === "assistant_text" && typeof payload.delta === "string")
+      text += payload.delta;
+    if (event.type === "task.started") await hold(taskHoldMs, input.signal);
+  }
+  return input.signal.aborted ? null : text;
+}
+
 // src/fakeInstance.ts
 var yieldTick = () => Promise.resolve();
 var FAKE_ASYNC_QUESTIONS = [
@@ -1265,7 +1501,7 @@ var FAKE_ASYNC_QUESTIONS = [
 function parseScript(input) {
   const envelope = input;
   const script = envelope?.config?.script;
-  return script === "approval-tool" || script === "async-question" || script === "stream" || script === "mcp-send" || script === "visualize" || script === "lane" ? script : "plain";
+  return FAKE_SCRIPTS.find((name) => name === script) ?? "plain";
 }
 var parseReplyText = (input) => {
   const envelope = input;
@@ -1370,121 +1606,12 @@ var createFakeInstance = (config, host) => {
     if (server === null) return "mcp-send: no MCP server was handed to this session";
     return runMcpCalls({ fetch: host.fetch, server, calls, signal });
   };
-  const runApprovalToolScript = async (threadId, turnId, signal) => {
-    const isAborted = () => signal?.aborted === true;
-    const fakeReply = "\u597D";
-    emit(
-      "content.delta",
-      threadId,
-      {
-        streamKind: "reasoning_text",
-        delta: "\u5148\u60F3\u6E05\u695A\u6B65\u9AA4\uFF1A\u7B2C\u4E00\u6B65 ls \u5F53\u524D\u76EE\u5F55\uFF1B\u7B2C\u4E8C\u6B65\u8BFB README.md \u7684\u7B2C\u4E00\u884C\uFF1B\u6700\u540E\u53EA\u56DE\u4E00\u4E2A\u5B57\u3002"
-      },
-      { turnId }
-    );
-    await yieldTick();
-    if (isAborted()) return null;
-    const approve = async (request) => {
-      emit(
-        "item.started",
-        threadId,
-        {
-          itemType: request.itemType,
-          status: "inProgress",
-          title: request.title,
-          data: request.args
-        },
-        { turnId, itemId: request.itemId }
-      );
-      emit(
-        "request.opened",
-        threadId,
-        {
-          requestType: request.requestType,
-          toolName: request.toolName,
-          detail: request.detail,
-          args: request.args
-        },
-        { turnId, requestId: request.requestId }
-      );
-      const decision = await new Promise((resolve) => {
-        let settled = false;
-        const settle = (value) => {
-          if (settled) return;
-          settled = true;
-          signal?.removeEventListener("abort", onAbort);
-          pendingDecisions.delete(request.requestId);
-          resolve(value);
-        };
-        const onAbort = () => settle("cancel");
-        signal?.addEventListener("abort", onAbort);
-        if (isAborted()) {
-          settle("cancel");
-          return;
-        }
-        pendingDecisions.set(request.requestId, settle);
-      });
-      emit(
-        "request.resolved",
-        threadId,
-        {
-          requestType: request.requestType,
-          decision: decision === "allow" ? "accept" : decision === "deny" ? "decline" : "cancel"
-        },
-        { turnId, requestId: request.requestId }
-      );
-      if (decision === "allow") {
-        emit(
-          "content.delta",
-          threadId,
-          { streamKind: "command_output", delta: request.output },
-          { turnId, itemId: request.itemId }
-        );
-      }
-      emit(
-        "item.completed",
-        threadId,
-        {
-          itemType: request.itemType,
-          status: decision === "allow" ? "completed" : "declined",
-          title: request.title,
-          data: { ...request.args, ...decision === "allow" ? { output: request.output } : {} }
-        },
-        { turnId, itemId: request.itemId }
-      );
-      return decision;
-    };
-    const first = await approve({
-      itemId: nextId("item"),
-      requestId: nextId("req"),
-      requestType: "exec_command_approval",
-      toolName: "shell",
-      detail: "ls",
-      args: { command: "ls" },
-      itemType: "command_execution",
-      title: "ls",
-      output: "README.md\n"
-    });
-    if (first === "cancel") return null;
-    if (first === "allow") {
-      const second = await approve({
-        itemId: nextId("item"),
-        requestId: nextId("req"),
-        requestType: "file_read_approval",
-        toolName: "Read",
-        detail: "README.md",
-        args: { file_path: "README.md" },
-        itemType: "dynamic_tool_call",
-        title: "Read README.md",
-        output: "# hands-probe-workspace\n"
-      });
-      if (second === "cancel") return null;
-    }
-    if (isAborted()) return null;
-    emit("content.delta", threadId, { streamKind: "assistant_text", delta: fakeReply }, { turnId });
-    await yieldTick();
-    return isAborted() ? null : fakeReply;
-  };
+  const runApprovalToolScript = createApprovalToolScript({
+    emit,
+    nextId,
+    pendingDecisions,
+    yieldTick
+  });
   const runScriptedTurn = async (booked, threadId, turnId, signal, input) => {
     const aborted = () => signal.aborted;
     await yieldTick();
@@ -1572,6 +1699,16 @@ var createFakeInstance = (config, host) => {
       ]);
       return;
     }
+    if (script === "replay") {
+      const text = await runReplayTurn({ config, threadId, turnId, signal, emit, nextId });
+      finishTurn(
+        booked,
+        turnId,
+        aborted() || text === null ? "interrupted" : "completed",
+        text === null || text === "" ? [] : [{ kind: "assistant", text }]
+      );
+      return;
+    }
     if (script === "lane") {
       const text = await runLaneTurn({
         threadId,
@@ -1693,7 +1830,7 @@ var createFakeInstance = (config, host) => {
         signal?.removeEventListener("abort", abortTurn);
         if (inflight.get(input.threadId)?.turnId === turnId) inflight.delete(input.threadId);
       };
-      const background = script === "approval-tool" || script === "stream" || script === "mcp-send" || script === "visualize" || script === "lane";
+      const background = script === "approval-tool" || script === "stream" || script === "replay" || script === "mcp-send" || script === "visualize" || script === "lane";
       if (background) signal?.removeEventListener("abort", abortTurn);
       booked.turnWork = runFakeTurn(
         run,
@@ -1751,7 +1888,7 @@ var executors = [
 ];
 var index_default = definePlugin({
   id: "agent-fake",
-  apiVersion: 23,
+  apiVersion: 24,
   executors,
   activate(ctx) {
     ctx.log.info("fake executor ready");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ycodium-ai/agent-fake",
-  "version": "0.2.3230",
+  "version": "0.2.3232",
   "description": "Minimal fake executor for plugin authors and host orchestration tests.",
   "keywords": [
     "ycodium",
@@ -21,7 +21,7 @@
     "@types/node": "24.12.4",
     "esbuild": "0.28.1",
     "vite-plus": "0.2.2",
-    "@ycodium-ai/plugin-api": "0.2.3230",
+    "@ycodium-ai/plugin-api": "0.2.3232",
     "ycodium-executor-testing": "0.0.0"
   },
   "ycodium": {