@ycodium-ai/agent-fake 0.2.3265 → 0.2.3306

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), `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)
+- `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, and a steer whose target turn has ended is refused with `code: "provider-rejected"`; a playbook instance accepts steers too (see [Playbook mode](#playbook-mode)); `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`
@@ -61,6 +61,14 @@ Replay recorded conversations or drive multi-thread acceptance tests with
 machine. Use an absolute path. This option is outside the settings form and applies only to
 `mcp-send`. Each turn runs the next batch, ignoring its input, including host wake-ups and follow-ups.
 
+A playbook instance accepts a steer, as a real provider does: a second `sendTurn` carrying the
+running turn's id returns that turn, and when the current batch finishes the next batch runs inside
+the same turn, one steer at a time in arrival order (each still subject to `expectInput`). A steer
+the playbook has no batch for is logged as `playbook has no step for a steered input` and noted in
+the reply. A steer whose target turn has already ended, or is not the running turn, is refused with
+an error carrying `code: "provider-rejected"`, so the host puts the message back in the queue. A plain
+`mcp-send` instance without a playbook still refuses a second turn while one is running.
+
 This example assigns one script by thread ID and another by title:
 
 ```json

package/dist/index.js

@@ -805,9 +805,6 @@ async function runMcpCalls(input) {
   return lines.join("\n");
 }
 
-// src/playbook.ts
-import * as NodeFSP from "node:fs/promises";
-
 // src/hold.ts
 function hold(ms, signal) {
   if (ms === 0 || signal.aborted) return Promise.resolve();
@@ -823,6 +820,9 @@ function hold(ms, signal) {
   });
 }
 
+// src/playbook.ts
+import * as NodeFSP from "node:fs/promises";
+
 // src/playbookMcp.ts
 function redactMcpUrls(value, servers) {
   if (typeof value === "string") {
@@ -895,6 +895,13 @@ function parseStep(value) {
   if (!isRecord2(value)) return null;
   if (Object.hasOwn(value, "expectInput"))
     return onlyKeys(value, ["expectInput"]) && isName(value.expectInput) ? { expectInput: value.expectInput } : null;
+  if (Object.hasOwn(value, "awaitSteer")) {
+    const wait = value.awaitSteer;
+    if (!onlyKeys(value, ["awaitSteer"]) || !isRecord2(wait) || !onlyKeys(wait, ["timeoutMs"]))
+      return null;
+    const timeoutMs = parseTimeout(wait.timeoutMs);
+    return timeoutMs === null ? null : { awaitSteer: { timeoutMs } };
+  }
   if (Object.hasOwn(value, "wait")) {
     const wait = value.wait;
     if (!onlyKeys(value, ["wait"]) || !isRecord2(wait) || !isName(wait.tool)) return null;
@@ -962,7 +969,8 @@ function parsePlaybook(text) {
         const steps = [];
         for (const entry of batch) {
           const step = parseStep(entry);
-          if (step === null || "expectInput" in step && steps.length > 0)
+          const last = steps.at(-1);
+          if (step === null || "expectInput" in step && steps.length > 0 || last !== void 0 && "awaitSteer" in last)
             return { ok: false, reason: `threads[${index}].turns[${turn}] has an invalid step` };
           steps.push(step);
         }
@@ -1255,7 +1263,11 @@ function createPlaybookRunner(input) {
       for (const step of batch) {
         if (turn.signal.aborted) break;
         if ("expectInput" in step) continue;
-        if ("wait" in step) {
+        if ("awaitSteer" in step) {
+          const ready = await turn.awaitSteer?.(step.awaitSteer.timeoutMs, turn.signal) ?? false;
+          if (turn.signal.aborted) break;
+          lines.push(`mcp-send awaitSteer${ready ? ": ready" : " failed: timeout"}`);
+        } else if ("wait" in step) {
           const missing = opened.missing(step.wait.server);
           if (step.wait.server !== void 0 && missing !== void 0) {
             lines.push(`mcp-send ${step.wait.tool} failed: ${missing}`);
@@ -1540,6 +1552,19 @@ var createFakeInstance = (config, host) => {
   const previewHoldMs = parsePreviewHoldMs(config);
   const laneOptions = laneTurnOptions(config, streamOptions);
   const steeredInputs = /* @__PURE__ */ new Map();
+  const steerWaiters = /* @__PURE__ */ new Map();
+  const awaitSteer = (threadId, timeoutMs, signal) => {
+    if ((steeredInputs.get(threadId)?.length ?? 0) > 0) return Promise.resolve(true);
+    const waiters = steerWaiters.get(threadId) ?? /* @__PURE__ */ new Set();
+    steerWaiters.set(threadId, waiters);
+    const arrived = new AbortController();
+    const wake = () => arrived.abort();
+    waiters.add(wake);
+    return hold(timeoutMs, AbortSignal.any([signal, arrived.signal])).then(() => {
+      waiters.delete(wake);
+      return arrived.signal.aborted;
+    });
+  };
   const pendingDecisions = /* @__PURE__ */ new Map();
   let seq = 0;
   let streamRound = 0;
@@ -1639,7 +1664,8 @@ var createFakeInstance = (config, host) => {
       fetch: host.fetch,
       mcpServers: booked.mcpServers,
       emit,
-      nextItemId: () => nextId("item")
+      nextItemId: () => nextId("item"),
+      awaitSteer: (timeoutMs, waitSignal) => awaitSteer(threadId, timeoutMs, waitSignal)
     });
     const failure = playbookText === null ? parseFailInput(input) : void 0;
     if (failure !== void 0) {
@@ -1689,9 +1715,29 @@ var createFakeInstance = (config, host) => {
       return;
     }
     if (script === "mcp-send") {
-      const text = playbookText ?? await runMcpSendScript(booked, input, signal);
+      let text = playbookText ?? await runMcpSendScript(booked, input, signal);
       emit("content.delta", threadId, { streamKind: "assistant_text", delta: text }, { turnId });
-      await yieldTick();
+      for (; ; ) {
+        await yieldTick();
+        const steered = steeredInputs.get(threadId)?.shift();
+        if (steered === void 0 || aborted()) break;
+        const more = await playbook?.runTurn({
+          threadId,
+          turnId,
+          signal,
+          input: steered,
+          fetch: host.fetch,
+          mcpServers: booked.mcpServers,
+          emit,
+          nextItemId: () => nextId("item")
+        });
+        if (more == null)
+          host.log.warn("playbook has no step for a steered input", { threadId, turnId });
+        const delta = `
+${more ?? "playbook: steered input not handled"}`;
+        text += delta;
+        emit("content.delta", threadId, { streamKind: "assistant_text", delta }, { turnId });
+      }
       finishTurn(booked, turnId, aborted() ? "interrupted" : "completed", [
         { kind: "assistant", text }
       ]);
@@ -1814,15 +1860,24 @@ var createFakeInstance = (config, host) => {
       const booked = requireThread(input.threadId);
       if (booked.closing !== void 0) throw new Error("session closing");
       const running = inflight.get(input.threadId);
+      const steerable = script === "lane" || playbook !== void 0;
       const steered = acceptLaneSteer({
         running,
-        enabled: script === "lane",
+        enabled: steerable,
         expectedTurnId: input.expectedTurnId,
         text: input.input,
         threadId: input.threadId,
         steered: steeredInputs
       });
-      if (steered !== null) return steered;
+      if (steered !== null) {
+        if ((steeredInputs.get(input.threadId)?.length ?? 0) > 0)
+          for (const wake of steerWaiters.get(input.threadId) ?? []) wake();
+        return steered;
+      }
+      if (steerable && input.expectedTurnId !== void 0)
+        throw Object.assign(new Error("The target turn has ended. The message was not sent."), {
+          code: "provider-rejected"
+        });
       if (running !== void 0) throw new Error("turn already in flight");
       const turnId = input.expectedTurnId ?? nextId("turn");
       const turnAbort = new AbortController();
@@ -1901,7 +1956,7 @@ var executors = [
 ];
 var index_default = definePlugin({
   id: "agent-fake",
-  apiVersion: 31,
+  apiVersion: 34,
   executors,
   activate(ctx) {
     ctx.log.info("fake executor ready");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ycodium-ai/agent-fake",
-  "version": "0.2.3265",
+  "version": "0.2.3306",
   "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.3265",
+    "@ycodium-ai/plugin-api": "0.2.3306",
     "ycodium-executor-testing": "0.0.0"
   },
   "ycodium": {