@frockbot/plugin-shell 0.3.15 → 0.3.17

package/frockbot.json

@@ -55,7 +55,7 @@
         "kind": "tool",
         "connectionTypes": [],
         "admission": {
-          "turnTypes": ["chat"]
+          "turnTypes": ["chat", "agent"]
         }
       },
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "private": false,
   "type": "module",
   "exports": {
@@ -51,42 +51,42 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/agent-runtime": "0.3.15",
-    "@frockbot/application-foundation": "0.3.15",
-    "@frockbot/catalog-core": "0.3.15",
-    "@frockbot/client-core": "0.3.15",
-    "@frockbot/client-ui": "0.3.15",
-    "@frockbot/computer-core": "0.3.15",
-    "@frockbot/computer-host-protocol": "0.3.15",
-    "@frockbot/configuration-core": "0.3.15",
-    "@frockbot/connection-core": "0.3.15",
-    "@frockbot/kernel-agent-loop": "0.3.15",
-    "@frockbot/kernel-composition": "0.3.15",
-    "@frockbot/kernel-contracts": "0.3.15",
-    "@frockbot/kernel-do": "0.3.15",
-    "@frockbot/machine-protocol": "0.3.15",
-    "@frockbot/plugin-applets": "0.3.15",
-    "@frockbot/plugin-authoring": "0.3.15",
-    "@frockbot/plugin-bot-template": "0.3.15",
-    "@frockbot/plugin-computer": "0.3.15",
-    "@frockbot/plugin-flock": "0.3.15",
-    "@frockbot/plugin-image": "0.3.15",
-    "@frockbot/plugin-machine-messages": "0.3.15",
-    "@frockbot/plugin-mcp": "0.3.15",
-    "@frockbot/plugin-memory": "0.3.15",
-    "@frockbot/plugin-package-catalog": "0.3.15",
-    "@frockbot/plugin-routines": "0.3.15",
-    "@frockbot/plugin-skills": "0.3.15",
-    "@frockbot/plugin-subagents": "0.3.15",
-    "@frockbot/plugin-user-machine": "0.3.15",
-    "@frockbot/protocol": "0.3.15",
+    "@frockbot/agent-runtime": "0.3.17",
+    "@frockbot/application-foundation": "0.3.17",
+    "@frockbot/catalog-core": "0.3.17",
+    "@frockbot/client-core": "0.3.17",
+    "@frockbot/client-ui": "0.3.17",
+    "@frockbot/computer-core": "0.3.17",
+    "@frockbot/computer-host-protocol": "0.3.17",
+    "@frockbot/configuration-core": "0.3.17",
+    "@frockbot/connection-core": "0.3.17",
+    "@frockbot/kernel-agent-loop": "0.3.17",
+    "@frockbot/kernel-composition": "0.3.17",
+    "@frockbot/kernel-contracts": "0.3.17",
+    "@frockbot/kernel-do": "0.3.17",
+    "@frockbot/machine-protocol": "0.3.17",
+    "@frockbot/plugin-applets": "0.3.17",
+    "@frockbot/plugin-authoring": "0.3.17",
+    "@frockbot/plugin-bot-template": "0.3.17",
+    "@frockbot/plugin-computer": "0.3.17",
+    "@frockbot/plugin-flock": "0.3.17",
+    "@frockbot/plugin-image": "0.3.17",
+    "@frockbot/plugin-machine-messages": "0.3.17",
+    "@frockbot/plugin-mcp": "0.3.17",
+    "@frockbot/plugin-memory": "0.3.17",
+    "@frockbot/plugin-package-catalog": "0.3.17",
+    "@frockbot/plugin-routines": "0.3.17",
+    "@frockbot/plugin-skills": "0.3.17",
+    "@frockbot/plugin-subagents": "0.3.17",
+    "@frockbot/plugin-user-machine": "0.3.17",
+    "@frockbot/protocol": "0.3.17",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "latest",
-    "@frockbot/plugin-prompt": "0.3.15",
-    "@frockbot/plugin-tools": "0.3.15",
+    "@frockbot/plugin-prompt": "0.3.17",
+    "@frockbot/plugin-tools": "0.3.17",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/agent.test.ts

@@ -74,7 +74,7 @@ async function invoke(
 }
 
 describe("the Shell's tool admission", () => {
-  test("offers the send tool and its alias on chat turns only", async () => {
+  test("offers the send tool on chat and agent Turns", async () => {
     const mounted = await mount();
     try {
       const chat = mounted.root.tools
@@ -86,10 +86,16 @@ describe("the Shell's tool admission", () => {
       const subagent = mounted.root.tools
         .schemas({ turnType: "subagent" })
         .map((tool) => tool.name);
+      const agent = mounted.root.tools
+        .schemas({ turnType: "agent" })
+        .map((tool) => tool.name);
 
       expect(chat).toContain(SEND_TO_USER_TOOL_V1);
       expect(chat).toContain(SEND_MESSAGE_ALIAS_V1);
       expect(chat).not.toContain(WAKE_PARENT_TOOL_V1);
+      expect(agent).toContain(SEND_TO_USER_TOOL_V1);
+      expect(agent).toContain(SEND_MESSAGE_ALIAS_V1);
+      expect(agent).not.toContain(WAKE_PARENT_TOOL_V1);
       expect(automation).toEqual([
         WAKE_PARENT_TOOL_V1,
         "get_dynamic_tools",
@@ -179,7 +185,10 @@ describe("the Shell's tool admission", () => {
   });
 
   test("bounds each tool by the turn types its manifest Capability declares", () => {
-    expect(shellAdmissionCeilingV1(USER_VOICE_CAPABILITY_V1)).toEqual(["chat"]);
+    expect(shellAdmissionCeilingV1(USER_VOICE_CAPABILITY_V1)).toEqual([
+      "chat",
+      "agent",
+    ]);
     expect(shellAdmissionCeilingV1(PARENT_HANDOFF_CAPABILITY_V1)).toEqual([
       "automation",
       "subagent",
@@ -492,6 +501,80 @@ describe("the acknowledgement reaches the user", () => {
     }
   });
 
+  test("a step that is about to call send_to_user is not promoted", async () => {
+    const mounted = await mount();
+    try {
+      // Bob on production, 2026-09-04: the model wrote the acknowledgement as
+      // plain text and passed the same line to `send_to_user` in one step, and
+      // the person saw two identical bubbles.
+      await mounted.root.serial(
+        "agent/assistant-text",
+        { session: mounted.session } as never,
+        "On it — building your to-do applet now.",
+        {
+          turn: 3,
+          step: 1,
+          requestId: "request-1",
+          toolNames: [SEND_TO_USER_TOOL_V1, "applet_create"],
+        },
+      );
+      await mounted.root.serial(
+        "agent/assistant-text",
+        { session: mounted.session } as never,
+        "Sending it another way.",
+        {
+          turn: 3,
+          step: 2,
+          requestId: "request-2",
+          toolNames: [SEND_MESSAGE_ALIAS_V1],
+        },
+      );
+
+      const sends = mounted.session.events.filter(
+        (event) => event.type === "send/to-user",
+      );
+      expect(sends).toHaveLength(0);
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("the last steps of a reply tell the model to send a status", async () => {
+    const mounted = await mount();
+    try {
+      const assemble = (current: number) =>
+        mounted.root.systemPrompt.assemble({
+          sessionId: "session-1",
+          provider: "provider-1",
+          model: "model-1",
+          turnType: "chat",
+          step: { current, max: 64 },
+        });
+      const early = await assemble(10);
+      expect(early.text).not.toContain("<step_budget>");
+      const warning = await assemble(61);
+      expect(warning.text).toContain("<step_budget>");
+      expect(warning.text).toContain("3 steps left after this one");
+      expect(warning.text).toContain(SEND_TO_USER_TOOL_V1);
+      const last = await assemble(64);
+      expect(last.text).toContain("This is the last step of this reply");
+      // The budget section sits after the conversation contract, where the
+      // model reads it last.
+      expect(last.text.indexOf("<step_budget>")).toBeGreaterThan(
+        last.text.indexOf("send_to_user"),
+      );
+      const outside = await mounted.root.systemPrompt.assemble({
+        sessionId: "session-1",
+        provider: "provider-1",
+        model: "model-1",
+        turnType: "chat",
+      });
+      expect(outside.text).not.toContain("<step_budget>");
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
   test("a step that already spoke is left alone, and a replay adds nothing", async () => {
     const mounted = await mount();
     try {

package/src/agent.ts

@@ -46,7 +46,12 @@ import {
   turnScopedMessagesV1,
   turnTypesByTurnV1,
 } from "./history.js";
-import { runCompactionV1 } from "./compaction.js";
+import {
+  COMPACTION_RESPONSE_SCHEMA_V1,
+  type CompactionSummaryPayloadV1,
+  renderCompactionSummaryV1,
+  runCompactionV1,
+} from "./compaction.js";
 import { compactionWorkV1 } from "./compaction-scheduler.js";
 import type { Plugin } from "cordis";
 import manifest from "../frockbot.json" with { type: "json" };
@@ -155,11 +160,25 @@ export function promotedSendOccurrenceIdV1(requestId: string): string {
 export async function promoteAssistantTextToSendV1(
   session: Session,
   text: string,
-  position: { turn: number; step: number; requestId: string },
+  position: {
+    turn: number;
+    step: number;
+    requestId: string;
+    toolNames?: readonly string[];
+  },
 ): Promise<void> {
   const trimmed = text.trim();
   if (trimmed.length === 0 || trimmed.length > PROMOTED_ASSISTANT_TEXT_LIMIT_V1)
     return;
+  // A step that narrates "On it — building it now." AND calls `send_to_user`
+  // with the same line is about to speak for itself; promoting the narration
+  // too is how the person saw the bubble twice. The send has not run yet when
+  // this hook fires (it runs before the tools, on purpose), so the pending
+  // call names are the only evidence.
+  const aboutToSend = (position.toolNames ?? []).some(
+    (name) => name === SEND_TO_USER_TOOL_V1 || name === SEND_MESSAGE_ALIAS_V1,
+  );
+  if (aboutToSend) return;
   const occurrenceId = promotedSendOccurrenceIdV1(position.requestId);
   const spokeThisStep = session.events.some(
     (event) =>
@@ -210,6 +229,42 @@ export const CONVERSATION_PROMPT_SECTION_V1 = "conversation";
 /** Ordered after identity (0), before anything a Package contributes. */
 export const CONVERSATION_PROMPT_ORDER_V1 = 1;
 
+export const STEP_BUDGET_PROMPT_SECTION_V1 = "step-budget";
+/** Late in the prompt, where the model reads it last and heeds it most. */
+export const STEP_BUDGET_PROMPT_ORDER_V1 = 90;
+/** The section appears when this many steps or fewer remain after this one. */
+export const STEP_BUDGET_WARNING_STEPS_V1 = 3;
+
+/**
+ * What the model is told when its reply is about to be stopped.
+ *
+ * A Turn that reaches the loop's step ceiling ends `interrupted`, and a model
+ * that was mid-work says nothing: the person sees a notice and no status. Bob
+ * (2026-09-04) spent twenty steps retrying a failing publish and the thread
+ * went quiet. So the last few steps carry a countdown and one instruction —
+ * stop starting work, send a status — and the final step allows nothing else.
+ */
+export function stepBudgetPromptTextV1(context: {
+  step?: { current: number; max: number };
+}): string {
+  const step = context.step;
+  if (!step) return "";
+  const remaining = step.max - step.current;
+  if (remaining > STEP_BUDGET_WARNING_STEPS_V1 || remaining < 0) return "";
+  if (remaining === 0) {
+    return [
+      "<step_budget>",
+      `This is the last step of this reply; after it the reply is stopped automatically. Do nothing except call \`${SEND_TO_USER_TOOL_V1}\` once with a short status for the person: what is finished, what is not, and what they can do next.`,
+      "</step_budget>",
+    ].join("\n");
+  }
+  return [
+    "<step_budget>",
+    `This reply has ${remaining} ${remaining === 1 ? "step" : "steps"} left after this one before it is stopped automatically. Do not start new work. Call \`${SEND_TO_USER_TOOL_V1}\` now with a short status for the person: what is finished, what is not, and what they can do next.`,
+    "</step_budget>",
+  ].join("\n");
+}
+
 export const CONVERSATION_PROMPT_TEXT_V1 = [
   "## Talking to the user",
   "",
@@ -271,7 +326,7 @@ function createSendToUserTool(
       string,
       unknown
     >,
-    admission: { turnTypes: ["chat"] },
+    admission: { turnTypes: ["chat", "agent"] },
     validate: (input: unknown) =>
       typeof input === "object" && input !== null && !Array.isArray(input),
     execute: async (
@@ -407,6 +462,13 @@ export const shellAgentPlugin: Plugin.Function = (ctx) => {
       order: CONVERSATION_PROMPT_ORDER_V1,
       render: () => CONVERSATION_PROMPT_TEXT_V1,
     }),
+    // Empty for most of a Turn; a countdown and one instruction at the end of
+    // its step budget. See `stepBudgetPromptTextV1`.
+    ctx.systemPrompt.register({
+      id: STEP_BUDGET_PROMPT_SECTION_V1,
+      order: STEP_BUDGET_PROMPT_ORDER_V1,
+      render: (context) => stepBudgetPromptTextV1(context),
+    }),
     ctx.tools.register(
       createSendToUserTool(SEND_TO_USER_TOOL_V1, ctx.sessions),
       userVoice ? { admissionCeiling: userVoice } : undefined,
@@ -449,27 +511,32 @@ export const shellAgentPlugin: Plugin.Function = (ctx) => {
               currentTurn: turn,
               newEffectId: () => `compaction-${crypto.randomUUID()}`,
               summarise: async (request) => {
-                let text = "";
                 // Two deadlines, one call: the compaction's own, and the abort
                 // a newly admitted Turn raises when it takes the log back.
                 const cancelled = AbortSignal.any([request.signal, signal]);
-                for await (const event of scoped.llm.stream(
-                  {
-                    requestId: `compaction-${crypto.randomUUID()}`,
-                    provider: request.provider,
-                    model: request.model,
-                    system: request.system,
-                    messages: request.messages,
-                    tools: [],
-                    ...(request.modelBinding
-                      ? { modelBinding: request.modelBinding }
-                      : {}),
-                  },
-                  cancelled,
-                )) {
-                  if (event.type === "text-delta") text += event.text;
+                const result =
+                  await scoped.llm.structured<CompactionSummaryPayloadV1>(
+                    {
+                      requestId: `compaction-${crypto.randomUUID()}`,
+                      provider: request.provider,
+                      model: request.model,
+                      system: request.system,
+                      messages: request.messages,
+                      tools: [],
+                      ...(request.modelBinding
+                        ? { modelBinding: request.modelBinding }
+                        : {}),
+                    },
+                    {
+                      name: "conversation_compaction",
+                      schema: COMPACTION_RESPONSE_SCHEMA_V1,
+                    },
+                    cancelled,
+                  );
+                if (result.status === "failed") {
+                  throw new Error(result.failure.message);
                 }
-                return text;
+                return renderCompactionSummaryV1(result.value);
               },
             });
           });

package/src/backend-applets.ts

@@ -294,7 +294,7 @@ export interface AppletCapabilityHostOptionsV1 {
    * told so in the failure when the files are missing, rather than the publish
    * silently using old bytes.
    */
-  syncSourceRootNow?(): Promise<void>;
+  syncSourceRootNow?(appletId: string): Promise<void>;
   composition: Pick<CompositionStore, "current" | "lastKnownGood" | "propose">;
   now?(): Date;
 }
@@ -731,7 +731,7 @@ export function createAppletCapabilityHostV1(
 
       // Force a pull of the source root so the publish sees what the Bot just
       // built, not the last synced copy. See the seam note on the option.
-      await options.syncSourceRootNow?.();
+      await options.syncSourceRootNow?.(input.appletId);
 
       const server = await readFile(
         input.appletId,

package/src/backend-completion.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { type SessionEvent } from "@frockbot/kernel-contracts";
 import { initializeBotSettingsV1 } from "@frockbot/configuration-core";
+import { SessionEventLog } from "@frockbot/kernel-do";
 import {
   botTurnCommandFingerprintV1,
   type BotTurnCompletion,
@@ -81,11 +82,15 @@ class MemoryRunStorage implements RunTerminalStorage {
     return Promise.resolve(this.values.get(key) as T | undefined);
   }
 
-  put(entries: Record<string, unknown>): Promise<void> {
-    this.putBatches.push(structuredClone(entries));
-    if (this.putFailure) return Promise.reject(this.putFailure);
-    for (const [key, value] of Object.entries(entries)) {
+  put(key: string | Record<string, unknown>, value?: unknown): Promise<void> {
+    if (typeof key === "string") {
       this.values.set(key, structuredClone(value));
+      return Promise.resolve();
+    }
+    this.putBatches.push(structuredClone(key));
+    if (this.putFailure) return Promise.reject(this.putFailure);
+    for (const [entry, item] of Object.entries(key)) {
+      this.values.set(entry, structuredClone(item));
     }
     return Promise.resolve();
   }
@@ -93,6 +98,16 @@ class MemoryRunStorage implements RunTerminalStorage {
   delete(key: string): Promise<boolean> {
     return Promise.resolve(this.values.delete(key));
   }
+
+  list<T>(options: { prefix: string }): Promise<Map<string, T>> {
+    return Promise.resolve(
+      new Map(
+        [...this.values.entries()].filter(([key]) =>
+          key.startsWith(options.prefix),
+        ) as Array<[string, T]>,
+      ),
+    );
+  }
 }
 
 describe("Bot run terminal persistence", () => {
@@ -284,6 +299,8 @@ describe("Bot run terminal persistence", () => {
       failure: "provider-bound retrieval unavailable",
     });
     expect(storage.values.get(keys.activeRun)).toBe("run-1");
-    expect(storage.values.get(keys.latestEvents)).toEqual([request]);
+    expect(await new SessionEventLog(storage).read("user:primary")).toEqual([
+      request,
+    ]);
   });
 });

package/src/backend-composition.ts

@@ -112,6 +112,11 @@ export interface ShellCompositionMountOptions {
   agentPackages?: readonly FoundationAgentPackage[];
   modelSelection?: RuntimeModelSelection;
   systemPromptSection?: string;
+  /** Called after the loop has flushed `turn/end`; errors are non-fatal. */
+  onTurnStopping?(input: {
+    turn: number;
+    events: readonly SessionEvent[];
+  }): Promise<void>;
   /**
    * Durably linearizes each provider or tool effect against Stop immediately
    * before it is used. The Bot Durable Object owns the transaction; the mounted
@@ -180,6 +185,20 @@ export function createShellCompositionHost(
         ...(options.turnType ? { turnType: options.turnType } : {}),
         ...(options.subagentRole ? { subagentRole: options.subagentRole } : {}),
       });
+      const disposeTurnStopping = options.onTurnStopping
+        ? runtime.root.on("agent/turn-stopping", async (agent, turn) => {
+            try {
+              await options.onTurnStopping!({
+                turn,
+                events: structuredClone(agent.session.events),
+              });
+            } catch {
+              // Accounting is a durable projection. Its own outbox exposes a
+              // gap; it can never turn a completed model response into a
+              // failed conversation Turn.
+            }
+          })
+        : undefined;
 
       const isolateMembers = generation.members.filter(
         (member) => member.artifact !== undefined,
@@ -290,6 +309,7 @@ export function createShellCompositionHost(
       }
 
       const dispose = async () => {
+        disposeTurnStopping?.();
         for (const unregister of unregisterApplets.toReversed()) unregister();
         for (const contribution of active.toReversed()) {
           await contribution.dispose();

package/src/backend-configuration.test.ts

@@ -6,6 +6,7 @@ import type {
   UserSettingsViewV1,
 } from "@frockbot/configuration-core";
 import type { PackageSettingDefinition } from "@frockbot/kernel-composition";
+import { SessionEventLog } from "@frockbot/kernel-do";
 import { createShellBotBackendContribution } from "./backend.js";
 import { createIsolateCapabilityHost } from "./backend-isolate.js";
 import { notificationIdV1 } from "./notification-id.js";
@@ -549,11 +550,12 @@ describe("generic per-Turn model resolution", () => {
     });
 
     expect(result.text).toBe("Cordis runtime: hello");
-    const durableEvents = storage.values.get("latest-events") as
-      Array<{ seq: number }> | undefined;
-    expect(durableEvents?.length).toBeGreaterThan(0);
-    expect(durableEvents?.map((event) => event.seq)).toEqual(
-      durableEvents?.map((_, index) => index),
+    const durableEvents = await new SessionEventLog(storage).read(
+      "user-1:primary",
+    );
+    expect(durableEvents.length).toBeGreaterThan(0);
+    expect(durableEvents.map((event) => event.seq)).toEqual(
+      durableEvents.map((_, index) => index),
     );
     const settings = await contribution.getSettings(identity);
     expect(settings).toMatchObject({ revision: 0, packageValues: {} });

package/src/backend-debug.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { initializeBotSettingsV1 } from "@frockbot/configuration-core";
+import { SessionEventLog, storedRunRecordV2 } from "@frockbot/kernel-do";
 import { createShellBotBackendContribution } from "./backend.js";
 import type { StoredRun } from "./backend-contracts.js";
 
@@ -154,6 +155,54 @@ describe("Bot debug snapshot", () => {
     expect(snapshot.activeRunId).toBeUndefined();
   });
 
+  test("reads bounded projections instead of hydrating full model prompts", async () => {
+    const storage = new MemoryStorage();
+    const event = {
+      type: "model/request",
+      turn: 1,
+      step: 1,
+      request: {
+        requestId: "request-large",
+        provider: "fake",
+        model: "large-context",
+        system: "s".repeat(80_000),
+        messages: [{ role: "user", content: "last question" }],
+        tools: [],
+      },
+      seq: 0,
+      timestamp: "2026-08-28T00:00:01.000Z",
+    } as StoredRun["events"][number];
+    const run = storedRun({ events: [event] });
+    await new SessionEventLog(storage).rewrite(run.sessionId, [event]);
+    await storage.put({
+      identity: IDENTITY,
+      [`run:${run.runId}`]: storedRunRecordV2(run),
+      [`run-index:${run.acceptedAt}:${run.runId}`]: run.runId,
+    });
+
+    const snapshot = await contributionOver(storage).debugSnapshot(IDENTITY, {
+      schemaVersion: 1,
+      runId: run.runId,
+    });
+
+    expect(snapshot.runs[0]?.eventCount).toBe(1);
+    expect(snapshot.runs[0]?.events?.[0]).toMatchObject({
+      type: "model/request",
+      cut: { marker: "content-cut", originalBytes: expect.any(Number) },
+      request: {
+        requestId: "request-large",
+        messageCount: 1,
+        toolCount: 0,
+        sha256: expect.stringMatching(/^[0-9a-f]{64}$/),
+        truncated: true,
+      },
+    });
+    expect(JSON.stringify(snapshot)).not.toContain("s".repeat(10_000));
+    expect(
+      new TextEncoder().encode(JSON.stringify(snapshot)).byteLength,
+    ).toBeLessThan(20_000);
+  });
+
   test("includes an active run older than the page it would otherwise fall off", async () => {
     const storage = new MemoryStorage();
     const stale = storedRun({