@frockbot/kernel-agent-loop 0.3.11 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-agent-loop",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,13 +12,13 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-contracts": "0.3.11",
+    "@frockbot/kernel-contracts": "0.3.13",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {
-    "@frockbot/plugin-models": "0.3.11",
-    "@frockbot/plugin-prompt": "0.3.11",
-    "@frockbot/plugin-tools": "0.3.11",
+    "@frockbot/plugin-models": "0.3.13",
+    "@frockbot/plugin-prompt": "0.3.13",
+    "@frockbot/plugin-tools": "0.3.13",
     "@types/bun": "1.4.0",
     "@types/node": "26.2.0",
     "typescript": "^7.0.2"

package/src/agent.ts

@@ -107,6 +107,26 @@ declare module "cordis" {
       outcome: "completed" | "not-started",
     ) => Promise<void>;
     "agent/turn-stopping": (agent: Agent, turn: number) => Promise<void>;
+    /**
+     * A step where the model wrote something *and* called tools, raised the
+     * moment the assistant message is journaled and before any tool runs.
+     *
+     * The kernel has no opinion about what that text is for — a Package that
+     * gives the Bot a voice does. In the Shell, the only thing a person sees
+     * is a `send_to_user` call, so a model that writes "On it — building the
+     * countdown applet now." and then goes on to call three tools has said it
+     * to nobody: the client draws one bubble per send, and there was no send.
+     * The prompt asks for the call, and this is what catches the model that
+     * narrates its acknowledgement in text anyway.
+     *
+     * Serial, and before the tools, so the promoted line lands ahead of the
+     * first tool result rather than after the work it was announcing.
+     */
+    "agent/assistant-text": (
+      agent: Agent,
+      text: string,
+      position: { turn: number; step: number; requestId: string },
+    ) => Promise<void>;
   }
 }
 

package/src/index.test.ts

@@ -3057,4 +3057,79 @@ describe("AgentLoop", () => {
       ),
     ).toHaveLength(1);
   });
+
+  // A model that writes an acknowledgement and then calls tools has said
+  // something to the person, and the Package that owns the Bot's voice has to
+  // hear about it *before* the work it was announcing produces results.
+  test("raises assistant text ahead of the tools the same step called", async () => {
+    const provider: LlmProvider = {
+      id: "acknowledging-model",
+      async *stream() {
+        yield { type: "text-delta", text: "On it — building it now." };
+        yield {
+          type: "tool-call",
+          call: { id: "call-1", name: "build", input: {} },
+        };
+        yield { type: "finish", reason: "tool-calls" };
+      },
+    };
+    const order: string[] = [];
+    const root = await mountRuntime(provider, {
+      name: "build",
+      description: "Does the work the acknowledgement announced.",
+      inputSchema: { type: "object" },
+      execute: () => {
+        order.push("tool");
+        return Promise.resolve({ content: "built", isError: true });
+      },
+    });
+    const seen: string[] = [];
+    root.on("agent/assistant-text", async (_agent, text, position) => {
+      order.push("assistant-text");
+      seen.push(`${position.turn}:${position.step}:${text}`);
+    });
+    const handle = await root.agents.create({
+      ...allowEffectOptions,
+      botId: "bot-ack",
+      sessionId: "acknowledging-model",
+      provider: provider.id,
+      model: "model-1",
+    });
+
+    handle.agent.send("build me a countdown");
+    await handle.agent.whenIdle();
+
+    expect(seen[0]).toBe("1:1:On it — building it now.");
+    expect(order[0]).toBe("assistant-text");
+    expect(order).toContain("tool");
+  });
+
+  // A step with nothing to say, or one that says everything it has and stops,
+  // raises nothing: the first has no text, and the second's text is the reply.
+  test("raises nothing for a step with no text or no tools", async () => {
+    const provider: LlmProvider = {
+      id: "quiet-model",
+      async *stream() {
+        yield { type: "text-delta", text: "Here is your answer." };
+        yield { type: "finish", reason: "completed" };
+      },
+    };
+    const root = await mountRuntime(provider);
+    let raised = 0;
+    root.on("agent/assistant-text", async () => {
+      raised += 1;
+    });
+    const handle = await root.agents.create({
+      ...allowEffectOptions,
+      botId: "bot-quiet",
+      sessionId: "quiet-model",
+      provider: provider.id,
+      model: "model-1",
+    });
+
+    handle.agent.send("answer me");
+    await handle.agent.whenIdle();
+
+    expect(raised).toBe(0);
+  });
 });

package/src/index.ts

@@ -22,6 +22,7 @@ import {
   type ToolCallOccurrence,
   type ToolExecutionResult,
   type TurnTypeV1,
+  TURN_DEADLINE_MS_V1,
   toolCallOccurrences,
   turnEndReason,
   validateSettledToolOccurrenceJournal,
@@ -112,12 +113,12 @@ class StepLimitReachedError extends Error {
 /**
  * The longest a single Turn may run before the loop stops waiting for it.
  *
- * Nothing bounded a Turn's wall clock before this: one hung for seventeen
- * minutes with an animated avatar and nothing else, and would have hung until
- * the isolate died. Fifteen minutes is well past any Turn a person is watching
- * and well inside the point at which they have concluded the product is broken.
+ * Defined in the contracts, because the loop is not its only reader: anything
+ * deciding whether a run still marked `running` can still be running needs the
+ * same number. Re-exported here because this is where every caller looks for
+ * it.
  */
-export const TURN_DEADLINE_MS_V1 = 15 * 60 * 1000;
+export { TURN_DEADLINE_MS_V1 };
 
 /**
  * How many times one step will send its model request.
@@ -520,6 +521,7 @@ class LoopAgent implements Agent {
         await this.session.flush();
         signal.throwIfAborted();
         await this.#notifyModelOutcome(response.request.requestId, "completed");
+        await this.#announceAssistantText(response, openTurn, latestStep);
         if (response.toolCalls.length === 0) {
           const shouldStop = await this.#stepShouldStop(
             openTurn,
@@ -640,6 +642,7 @@ class LoopAgent implements Agent {
         await this.session.flush();
         signal.throwIfAborted();
         await this.#notifyModelOutcome(response.request.requestId, "completed");
+        await this.#announceAssistantText(response, openTurn, step);
         if (response.toolCalls.length === 0) {
           const shouldStop = await this.#stepShouldStop(
             openTurn,
@@ -820,6 +823,7 @@ class LoopAgent implements Agent {
         await this.session.flush();
         signal.throwIfAborted();
         await this.#notifyModelOutcome(response.request.requestId, "completed");
+        await this.#announceAssistantText(response, turn, step);
 
         if (response.toolCalls.length === 0) {
           const shouldStop = await this.#stepShouldStop(
@@ -1371,6 +1375,31 @@ class LoopAgent implements Agent {
     return endsTurn;
   }
 
+  /**
+   * Raises `agent/assistant-text` for a step that wrote something and then
+   * called tools, so a Package that owns the Bot's voice can do something with
+   * words the model addressed to the person.
+   *
+   * Only that shape. A step with no tool calls ends the Turn on its assistant
+   * message, which every surface already draws; a step with tools and no text
+   * has nothing to say. The narrow case is the one that went missing: text and
+   * tools together, where the text is an acknowledgement and the tools are the
+   * work it was announcing.
+   */
+  async #announceAssistantText(
+    response: ModelResponse,
+    turn: number,
+    step: number,
+  ): Promise<void> {
+    if (response.toolCalls.length === 0) return;
+    if (response.text.trim().length === 0) return;
+    await this.#ctx.serial("agent/assistant-text", this, response.text, {
+      turn,
+      step,
+      requestId: response.request.requestId,
+    });
+  }
+
   async #stepShouldStop(
     turn: number,
     step: number,