@frockbot/kernel-agent-loop 0.1.4 → 0.2.0

package/package.json

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

package/src/agent.ts

@@ -1,6 +1,8 @@
 import { type Context, Service } from "cordis";
 import type {
   ModelBindingSnapshot,
+  LoopAgentInputV1,
+  LoopAgentRuntimeV1,
   NormalizedModelRequest,
   Session,
   SkillRefV1,
@@ -38,7 +40,7 @@ export interface AgentOptions {
   modelBinding?: ModelBindingSnapshot;
 }
 
-export interface AgentInput {
+export interface AgentInput extends LoopAgentInputV1 {
   messageId: string;
   text: string;
   /**
@@ -61,7 +63,7 @@ export type PreStepDecision =
 
 export type RequestErrorAction = { kind: "retry" } | { kind: "fail" };
 
-export interface Agent {
+export interface Agent extends LoopAgentRuntimeV1 {
   readonly id: string;
   readonly botId: string;
   readonly session: Session;
@@ -87,22 +89,6 @@ declare module "cordis" {
   }
 
   interface Events {
-    "agent/created": (agent: Agent) => void;
-    "agent/disposed": (agent: Agent) => void;
-    "agent/status": (agent: Agent, status: AgentStatus) => void;
-    "agent/inbox/inserted": (agent: Agent, input: AgentInput) => void;
-    "agent/inbox/claimed": (
-      agent: Agent,
-      inputs: AgentInput[],
-      turn: number,
-    ) => void;
-    "agent/pre-step": (
-      agent: Agent,
-      inputs: AgentInput[],
-      turn: number,
-      step: number,
-      next: () => Promise<PreStepDecision>,
-    ) => Promise<PreStepDecision>;
     "agent/request": (
       agent: Agent,
       request: NormalizedModelRequest,
@@ -121,11 +107,6 @@ declare module "cordis" {
       outcome: "completed" | "not-started",
     ) => Promise<void>;
     "agent/turn-stopping": (agent: Agent, turn: number) => Promise<void>;
-    "agent/cancel-requested": (
-      agent: Agent,
-      reason: "user" | "shutdown",
-    ) => void;
-    "agent/error": (agent: Agent, error: unknown) => void;
   }
 }
 

package/src/index.test.ts

@@ -4,6 +4,7 @@ import {
   LlmEffectNotStartedError,
   type LlmReconciliationOutcome,
   type LlmProvider,
+  type NormalizedModelRequest,
   type LlmStreamEvent,
   type PersistSessionEvents,
   type SessionEvent,
@@ -150,6 +151,79 @@ afterEach(async () => {
 });
 
 describe("AgentLoop", () => {
+  test("records exactly the hook-shaped request received by the provider", async () => {
+    let received: NormalizedModelRequest | undefined;
+    const provider: LlmProvider = {
+      id: "hook-shaped-request",
+      async *stream(request) {
+        received = structuredClone(request);
+        yield { type: "finish", reason: "completed" };
+      },
+    };
+    const root = await mountRuntime(provider, {
+      name: "original_tool",
+      description: "The initially exposed tool.",
+      inputSchema: { type: "object" },
+      execute: () => Promise.resolve({ content: "ok", isError: false }),
+    });
+    root.on("system-prompt/assemble", async (_context, next) => {
+      const assembly = await next();
+      return {
+        text: `${assembly.text}\nHook-shaped system context.`,
+        sections: [
+          ...assembly.sections,
+          { id: "hook", text: "Hook-shaped system context." },
+        ],
+      };
+    });
+    root.on(
+      "agent/message-window",
+      async (_agent, messages, _turn, _step, _signal, next) => [
+        ...(await next()),
+        { role: "user" as const, content: `window:${messages.length}` },
+      ],
+    );
+    root.on(
+      "agent/tool-exposure",
+      async (_agent, _tools, _turn, _step, _signal, next) => {
+        await next();
+        return [
+          {
+            name: "hook_visible",
+            description: "Visible only in this shaped request.",
+            inputSchema: { type: "object" },
+          },
+        ];
+      },
+    );
+    const handle = await root.agents.create({
+      ...allowEffectOptions,
+      botId: "bot-hook-request",
+      sessionId: "hook-shaped-request",
+      provider: provider.id,
+      model: "model-1",
+    });
+
+    handle.agent.send("shape the request");
+    await handle.agent.whenIdle();
+
+    const recorded = handle.agent.session.events.find(
+      (event) => event.type === "model/request",
+    );
+    if (recorded?.type !== "model/request" || !received) {
+      throw new Error("model request was not recorded and received");
+    }
+    expect(recorded.request).toEqual(received);
+    expect(recorded.request.system).toContain("Hook-shaped system context.");
+    expect(recorded.request.messages.at(-1)).toEqual({
+      role: "user",
+      content: "window:1",
+    });
+    expect(recorded.request.tools.map((tool) => tool.name)).toEqual([
+      "hook_visible",
+    ]);
+  });
+
   test("fences a model after durable intent without invoking its provider", async () => {
     let streams = 0;
     const provider: LlmProvider = {

package/src/index.ts

@@ -13,6 +13,7 @@ import {
   decodeSkillRefsV1,
   LlmEffectNotStartedError,
   type LlmStreamEvent,
+  type LoopStepContinuationV1,
   type NormalizedModelRequest,
   type Session,
   type SessionEvent,
@@ -409,6 +410,12 @@ class LoopAgent implements Agent {
         signal.throwIfAborted();
         await this.#notifyModelOutcome(response.request.requestId, "completed");
         if (response.toolCalls.length === 0) {
+          const shouldStop = await this.#stepShouldStop(
+            openTurn,
+            latestStep,
+            { kind: "stop" },
+            signal,
+          );
           this.session.append({
             type: "step/end",
             turn: openTurn,
@@ -416,29 +423,44 @@ class LoopAgent implements Agent {
             outcome: "completed",
           });
           openStep = undefined;
-          turnOutcome = "completed";
-          return;
-        }
-        const endsTurn = await this.#executeTools(
-          toolCallOccurrences(openTurn, latestStep, response.toolCalls),
-          signal,
-        );
-        signal.throwIfAborted();
-        this.session.append({
-          type: "step/end",
-          turn: openTurn,
-          step: latestStep,
-          outcome: "completed",
-        });
-        openStep = undefined;
-        if (endsTurn) {
-          turnOutcome = "completed";
-          return;
+          if (shouldStop) {
+            turnOutcome = "completed";
+            return;
+          }
+        } else {
+          const endsTurn = await this.#executeTools(
+            toolCallOccurrences(openTurn, latestStep, response.toolCalls),
+            signal,
+          );
+          signal.throwIfAborted();
+          const shouldStop = await this.#stepShouldStop(
+            openTurn,
+            latestStep,
+            { kind: endsTurn ? "stop" : "continue" },
+            signal,
+          );
+          this.session.append({
+            type: "step/end",
+            turn: openTurn,
+            step: latestStep,
+            outcome: "completed",
+          });
+          openStep = undefined;
+          if (shouldStop) {
+            turnOutcome = "completed";
+            return;
+          }
         }
         nextStep = latestStep + 1;
       } else if (latestStepStatus === "open" && latestAssistant) {
         openStep = latestStep;
         if (latestAssistant.toolCalls.length === 0) {
+          const shouldStop = await this.#stepShouldStop(
+            openTurn,
+            latestStep,
+            { kind: "stop" },
+            signal,
+          );
           this.session.append({
             type: "step/end",
             turn: openTurn,
@@ -446,26 +468,35 @@ class LoopAgent implements Agent {
             outcome: "completed",
           });
           openStep = undefined;
-          turnOutcome = "completed";
-          return;
-        }
-        const occurrences = toolCallOccurrences(
-          openTurn,
-          latestStep,
-          latestAssistant.toolCalls,
-        );
-        const endsTurn = await this.#executeTools(occurrences, signal);
-        signal.throwIfAborted();
-        this.session.append({
-          type: "step/end",
-          turn: openTurn,
-          step: latestStep,
-          outcome: "completed",
-        });
-        openStep = undefined;
-        if (endsTurn) {
-          turnOutcome = "completed";
-          return;
+          if (shouldStop) {
+            turnOutcome = "completed";
+            return;
+          }
+        } else {
+          const occurrences = toolCallOccurrences(
+            openTurn,
+            latestStep,
+            latestAssistant.toolCalls,
+          );
+          const endsTurn = await this.#executeTools(occurrences, signal);
+          signal.throwIfAborted();
+          const shouldStop = await this.#stepShouldStop(
+            openTurn,
+            latestStep,
+            { kind: endsTurn ? "stop" : "continue" },
+            signal,
+          );
+          this.session.append({
+            type: "step/end",
+            turn: openTurn,
+            step: latestStep,
+            outcome: "completed",
+          });
+          openStep = undefined;
+          if (shouldStop) {
+            turnOutcome = "completed";
+            return;
+          }
         }
         nextStep = latestStep + 1;
       } else if (latestStepStatus === "ended") {
@@ -499,6 +530,12 @@ class LoopAgent implements Agent {
         signal.throwIfAborted();
         await this.#notifyModelOutcome(response.request.requestId, "completed");
         if (response.toolCalls.length === 0) {
+          const shouldStop = await this.#stepShouldStop(
+            openTurn,
+            step,
+            { kind: "stop" },
+            signal,
+          );
           this.session.append({
             type: "step/end",
             turn: openTurn,
@@ -506,24 +543,33 @@ class LoopAgent implements Agent {
             outcome: "completed",
           });
           openStep = undefined;
-          turnOutcome = "completed";
-          return;
-        }
-        const endsTurn = await this.#executeTools(
-          toolCallOccurrences(openTurn, step, response.toolCalls),
-          signal,
-        );
-        signal.throwIfAborted();
-        this.session.append({
-          type: "step/end",
-          turn: openTurn,
-          step,
-          outcome: "completed",
-        });
-        openStep = undefined;
-        if (endsTurn) {
-          turnOutcome = "completed";
-          return;
+          if (shouldStop) {
+            turnOutcome = "completed";
+            return;
+          }
+        } else {
+          const endsTurn = await this.#executeTools(
+            toolCallOccurrences(openTurn, step, response.toolCalls),
+            signal,
+          );
+          signal.throwIfAborted();
+          const shouldStop = await this.#stepShouldStop(
+            openTurn,
+            step,
+            { kind: endsTurn ? "stop" : "continue" },
+            signal,
+          );
+          this.session.append({
+            type: "step/end",
+            turn: openTurn,
+            step,
+            outcome: "completed",
+          });
+          openStep = undefined;
+          if (shouldStop) {
+            turnOutcome = "completed";
+            return;
+          }
         }
       }
       throw new Error(`agent exceeded ${this.#maxSteps} steps`);
@@ -640,6 +686,12 @@ class LoopAgent implements Agent {
         await this.#notifyModelOutcome(response.request.requestId, "completed");
 
         if (response.toolCalls.length === 0) {
+          const shouldStop = await this.#stepShouldStop(
+            turn,
+            step,
+            { kind: "stop" },
+            signal,
+          );
           this.session.append({
             type: "step/end",
             turn,
@@ -647,27 +699,35 @@ class LoopAgent implements Agent {
             outcome: "completed",
           });
           openStep = undefined;
-          turnOutcome = "completed";
-          return;
-        }
-
-        const endsTurn = await this.#executeTools(
-          toolCallOccurrences(turn, step, response.toolCalls),
-          signal,
-        );
-        signal.throwIfAborted();
-        this.session.append({
-          type: "step/end",
-          turn,
-          step,
-          outcome: "completed",
-        });
-        openStep = undefined;
-        // A tool result that ends the Turn closes it here: no further model
-        // request, and the log replays as a completed Turn with none.
-        if (endsTurn) {
-          turnOutcome = "completed";
-          return;
+          if (shouldStop) {
+            turnOutcome = "completed";
+            return;
+          }
+        } else {
+          const endsTurn = await this.#executeTools(
+            toolCallOccurrences(turn, step, response.toolCalls),
+            signal,
+          );
+          signal.throwIfAborted();
+          const shouldStop = await this.#stepShouldStop(
+            turn,
+            step,
+            { kind: endsTurn ? "stop" : "continue" },
+            signal,
+          );
+          this.session.append({
+            type: "step/end",
+            turn,
+            step,
+            outcome: "completed",
+          });
+          openStep = undefined;
+          // A tool result that ends the Turn closes it here unless declared
+          // termination policy replaces that default for this step.
+          if (shouldStop) {
+            turnOutcome = "completed";
+            return;
+          }
         }
         inputs = [];
       }
@@ -750,18 +810,38 @@ class LoopAgent implements Agent {
     });
 
     while (true) {
+      const proposedMessages = this.session.deriveMessages();
+      const messages = await this.#ctx.waterfall(
+        "agent/message-window",
+        this,
+        proposedMessages,
+        turn,
+        step,
+        signal,
+        () => Promise.resolve(proposedMessages),
+      );
+      const proposedTools = this.#ctx.tools.schemas({
+        turnType: this.#turnType,
+        ...(this.#subagentRole === undefined
+          ? {}
+          : { subagentRole: this.#subagentRole }),
+      });
+      const tools = await this.#ctx.waterfall(
+        "agent/tool-exposure",
+        this,
+        proposedTools,
+        turn,
+        step,
+        signal,
+        () => Promise.resolve(proposedTools),
+      );
       const proposed: NormalizedModelRequest = {
         requestId: crypto.randomUUID(),
         provider: this.#options.provider,
         model: this.#options.model,
         system: assembly.text,
-        messages: this.session.deriveMessages(),
-        tools: this.#ctx.tools.schemas({
-          turnType: this.#turnType,
-          ...(this.#subagentRole === undefined
-            ? {}
-            : { subagentRole: this.#subagentRole }),
-        }),
+        messages,
+        tools,
         ...(this.#options.modelBinding
           ? { modelBinding: structuredClone(this.#options.modelBinding) }
           : {}),
@@ -1115,6 +1195,24 @@ class LoopAgent implements Agent {
     return endsTurn;
   }
 
+  async #stepShouldStop(
+    turn: number,
+    step: number,
+    proposed: LoopStepContinuationV1,
+    signal: AbortSignal,
+  ): Promise<boolean> {
+    const decision = await this.#ctx.waterfall(
+      "agent/step-continuation",
+      this,
+      proposed,
+      turn,
+      step,
+      signal,
+      () => Promise.resolve(proposed),
+    );
+    return decision.kind === "stop";
+  }
+
   async #settleCancelledStep(turn: number, step: number): Promise<void> {
     const assistant = this.session.events.findLast(
       (event) =>