@frockbot/plugin-shell 0.3.15 → 0.3.17

package/src/backend-flock.ts

@@ -1,17 +1,17 @@
 // The Bot Durable Object's half of the Bot self-management seam.
 //
-// The Flock Package offers a Bot two tools over its own identity and its
-// User's flock. This module decides, for one admitted Turn, what provenance
-// those writes record and which authorities they may reach. It implements
-// neither: the profile write is the Bot Durable Object's own configuration
-// command, and the create is the User Durable Object's `bot/create` — the
-// same two paths the hosted client drives.
+// The Flock Package offers a Bot self-management and direct messaging over its
+// own identity and its User's flock. This module decides, for one admitted
+// Turn, what provenance those effects record and which authorities they may
+// reach. The profile write is the Bot Durable Object's own configuration
+// command, create is the User Durable Object's `bot/create`, and messaging
+// admits an agent Turn through the target Bot's Durable Object.
 //
 // AUTHORITY. "Self-modification never widens authority." The host handed to
-// the Package exposes exactly four calls, all of them things the User's own
-// surfaces already do, and the `botId` on every one of them is fixed here
-// rather than taken from the model's arguments. A Bot cannot address another
-// Bot's settings through this seam because the seam never accepts a target.
+// the Package exposes only narrow authority calls. The `botId` on every
+// mutation is fixed here rather than taken from the model's arguments. A Bot
+// cannot address another Bot's settings through this seam; a message target is
+// instead resolved from the same User's Flock directory before admission.
 //
 // HIBERNATION. Nothing here reaches the Computer registry, a Computer
 // provider, or a Sprite: identity is Durable Object state, so self-management
@@ -26,7 +26,9 @@ import type {
   CreateBotCommandV1,
   FlockReceiptV1,
   FlockSelfRuntimeHostV1,
+  BotMessageOutcomeV1,
 } from "@frockbot/plugin-flock/agent";
+import type { AgentTurnSlotReceiptV1 } from "@frockbot/plugin-flock/quota";
 
 /** The Bot and User whose identity a Turn may change. */
 export interface BotSelfManagementIdentity {
@@ -39,6 +41,9 @@ export interface BotSelfManagementTurn {
   runId: string;
   turnId: string;
   sessionId: string;
+  /** This Turn's pinned profile name, stable across effect recovery. */
+  fromBotName: string;
+  inboundAgent?: FlockSelfRuntimeHostV1["inboundAgent"];
 }
 
 /**
@@ -57,6 +62,51 @@ export interface BotSelfManagementAuthorities {
     userId: string,
     command: CreateBotCommandV1,
   ): Promise<FlockReceiptV1>;
+  reserveAgentTurn(request: {
+    schemaVersion: 1;
+    userId: string;
+    requesterId: string;
+    runId: string;
+    reservedAt: string;
+  }): Promise<AgentTurnSlotReceiptV1>;
+  releaseAgentTurn(request: {
+    schemaVersion: 1;
+    userId: string;
+    requesterId: string;
+    runId: string;
+  }): Promise<void>;
+  runAgent(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: {
+      runId: string;
+      sessionId: string;
+      acceptedAt: string;
+      text: string;
+      source: {
+        kind: "bot";
+        fromBotId: string;
+        fromBotName: string;
+        messageId: string;
+      };
+    };
+  }): Promise<{ text: string }>;
+}
+
+async function agentRunIdV1(
+  identity: BotSelfManagementIdentity,
+  targetBotId: string,
+  effectId: string,
+): Promise<string> {
+  const bytes = new TextEncoder().encode(
+    `${identity.userId}\u0000${identity.botId}\u0000${targetBotId}\u0000${effectId}`,
+  );
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  const hex = [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+  return `agent-${hex.slice(0, 32)}`;
 }
 
 /**
@@ -92,5 +142,64 @@ export function createBotSelfManagementHost(
     },
     listBots: () => authorities.listBots(identity.userId),
     createBot: (command) => authorities.createBot(identity.userId, command),
+    ...(turn.inboundAgent ? { inboundAgent: turn.inboundAgent } : {}),
+    messageBot: async (request): Promise<BotMessageOutcomeV1> => {
+      if (request.targetBotId === identity.botId) {
+        throw new Error("a Bot cannot message itself");
+      }
+      const directory = await authorities.listBots(identity.userId);
+      const target = directory.bots.find(
+        (bot) => bot.botId === request.targetBotId,
+      );
+      if (!target)
+        throw new Error("the target Bot is not in this User's flock");
+      const runId = await agentRunIdV1(
+        identity,
+        request.targetBotId,
+        request.effectId,
+      );
+      const reservation = await authorities.reserveAgentTurn({
+        schemaVersion: 1,
+        userId: identity.userId,
+        requesterId: identity.botId,
+        runId,
+        reservedAt: new Date().toISOString(),
+      });
+      if (reservation.status === "refused") {
+        throw new Error(reservation.reason);
+      }
+      try {
+        const turnResult = await authorities.runAgent({
+          schemaVersion: 1,
+          userId: identity.userId,
+          botId: request.targetBotId,
+          command: {
+            runId,
+            sessionId: `${identity.userId}:${request.targetBotId}`,
+            acceptedAt: new Date().toISOString(),
+            text: request.message,
+            source: {
+              kind: "bot",
+              fromBotId: identity.botId,
+              fromBotName: turn.fromBotName,
+              messageId: runId,
+            },
+          },
+        });
+        return {
+          targetBotId: request.targetBotId,
+          targetBotName: target.initialName,
+          runId,
+          text: turnResult.text,
+        };
+      } finally {
+        await authorities.releaseAgentTurn({
+          schemaVersion: 1,
+          userId: identity.userId,
+          requesterId: identity.botId,
+          runId,
+        });
+      }
+    },
   };
 }

package/src/backend-recovery-integration.test.ts

@@ -9,6 +9,7 @@ import {
   type UserSettingsViewV1,
 } from "@frockbot/configuration-core";
 import { compileFoundationApplication } from "@frockbot/application-foundation/runtime";
+import { SessionEventLog } from "@frockbot/kernel-do";
 import { createShellBotBackendContribution } from "./backend.js";
 import {
   botTurnCommandFingerprintV1,
@@ -291,10 +292,23 @@ describe("Bot recovery", () => {
       },
     ]);
     expect(settledEffects).toHaveLength(2);
+    const eventLog = new SessionEventLog(storage);
     for (const runId of ["ollama-run-1", "ollama-run-2"]) {
-      const run = await storage.get<StoredRun>(`run:${runId}`);
+      const run = await storage.get<
+        Omit<StoredRun, "events"> & {
+          eventRange: { startSeq: number; endSeq: number };
+        }
+      >(`run:${runId}`);
+      expect(run).not.toHaveProperty("events");
+      const events = run
+        ? await eventLog.readRange(
+            "user-1:primary",
+            run.eventRange.startSeq,
+            run.eventRange.endSeq,
+          )
+        : [];
       expect(
-        run?.events.find((event) => event.type === "model/request"),
+        events.find((event) => event.type === "model/request"),
       ).toMatchObject({
         request: {
           provider: "ollama-cloud",
@@ -594,7 +608,7 @@ describe("Bot recovery", () => {
       schemaVersion: 1,
       runs: [
         expect.objectContaining({
-          schemaVersion: 2,
+          schemaVersion: 3,
           runId: "run-1",
           status: "completed",
           outcome: { type: "completed", text: "Durable reply" },

package/src/backend-runner.ts

@@ -91,6 +91,7 @@ function settleBotTurn(
       events.some(
         (event) =>
           (event.type === "assistant/message" ||
+            event.type === "model/response-failed" ||
             event.type === "model/effect-not-started") &&
           event.requestId === latestRequest.request.requestId,
       );

package/src/backend.ts

@@ -9,6 +9,7 @@ import {
   decodeIsolateWorkspaceListRequestV1,
   decodeIsolateWorkspacePathV1,
   decodeIsolateWorkspaceWriteRequestV1,
+  decodeSendToUserPayloadV1,
   decodeWorkspacePathV1,
   decodeWorkspaceRootV1,
   decodeSessionEvent,
@@ -46,12 +47,13 @@ import {
   ACTIVE_RUN_KEY,
   BotDurableAuthority,
   IDENTITY_KEY,
-  LATEST_EVENTS_KEY,
   NOTIFICATION_PREFIX,
   RECOVERY_ALARM_DELAY_MS,
   RUN_ADMISSION_FENCE_PREFIX,
   RUN_INDEX_PREFIX,
   RUN_PREFIX,
+  SessionEventLog,
+  storedRunRecordV2,
   CONVERSATION_BUSY_MESSAGE_V1,
   isConversationBusyV1,
   type BotIdentity,
@@ -133,6 +135,7 @@ import {
 import {
   createAppletCapabilityHostV1,
   createAppletInstanceBindingV1,
+  APPLET_DIST_FILES_V1,
   appletRpcSnapshotV1 as rpcJsonSnapshotV1,
   resolveAppletCompositionV1,
   type AppletCapabilityHostV1,
@@ -252,6 +255,7 @@ import {
   decodeSubagentSlotReceiptV1,
   type SubagentSlotBinding,
 } from "@frockbot/plugin-subagents/quota";
+import { decodeAgentTurnSlotReceiptV1 } from "@frockbot/plugin-flock/quota";
 import {
   subagentModelCatalogV1,
   type SubagentModelOptionV1,
@@ -405,6 +409,7 @@ import {
   decodeClientRunLookupQueryV1,
   decodeClientRunListQueryV1,
   decodeClientRunStopCommandV1,
+  decodeClientTurnV1,
   isVisibleRunV1,
   projectClientRunLookupV1,
   projectClientRunV1,
@@ -666,6 +671,16 @@ export interface ShellBotBackendHost {
   scheduledWorkInFlight?(): boolean;
   deferScheduledWork?(transaction: DurableObjectTransaction): Promise<void>;
   settleScheduledWork?(): Promise<void>;
+  /**
+   * A derived accounting projection after `turn/end` is durable. The host
+   * queues it before delivery, so failure never changes the Turn's outcome.
+   */
+  recordSettledUsage?(input: {
+    botId: string;
+    runId: string;
+    turn: number;
+    events: readonly SessionEvent[];
+  }): Promise<void>;
 }
 
 /** The narrow storage seam the Bot's announcement log is written through. */
@@ -768,6 +783,7 @@ export class ShellBotBackendContribution {
   private readonly hostScheduledWorkInFlight?: ShellBotBackendHost["scheduledWorkInFlight"];
   private readonly hostDeferScheduledWork?: ShellBotBackendHost["deferScheduledWork"];
   private readonly hostSettleScheduledWork?: ShellBotBackendHost["settleScheduledWork"];
+  private readonly recordSettledUsage?: ShellBotBackendHost["recordSettledUsage"];
 
   constructor(host: ShellBotBackendHost) {
     this.ctx = host.state;
@@ -783,6 +799,7 @@ export class ShellBotBackendContribution {
     this.hostScheduledWorkInFlight = host.scheduledWorkInFlight;
     this.hostDeferScheduledWork = host.deferScheduledWork;
     this.hostSettleScheduledWork = host.settleScheduledWork;
+    this.recordSettledUsage = host.recordSettledUsage;
     const routines = createBotRoutines(
       host.state.storage,
       createBotRoutineHookMinter(
@@ -1156,8 +1173,10 @@ export class ShellBotBackendContribution {
     const announcements = [...stored.entries()]
       .sort(([left], [right]) => left.localeCompare(right))
       .map(([, value]) => decodeSessionEvent(value));
-    const session =
-      (await this.ctx.storage.get<SessionEvent[]>(LATEST_EVENTS_KEY)) ?? [];
+    const sessionId = await this.authority.readConversationSessionId();
+    const session = sessionId
+      ? await this.authority.readSessionEvents(sessionId)
+      : [];
     for (const event of session) {
       if (event.type === "conversation/compacted") announcements.push(event);
     }
@@ -1171,8 +1190,10 @@ export class ShellBotBackendContribution {
    * timestamp of the place it belongs rather than the moment it was written.
    */
   private async projectAnnouncementPage() {
-    const session =
-      (await this.ctx.storage.get<SessionEvent[]>(LATEST_EVENTS_KEY)) ?? [];
+    const sessionId = await this.authority.readConversationSessionId();
+    const session = sessionId
+      ? await this.authority.readSessionEvents(sessionId)
+      : [];
     return projectClientAnnouncementsV1(
       await this.listAnnouncements(),
       session,
@@ -1640,6 +1661,9 @@ export class ShellBotBackendContribution {
       // One admitted Turn is one run; the Turn ordinal lives in the session log.
       turnId: input.command.runId,
       sessionId: input.command.sessionId,
+      // The admitted configuration snapshot is durable, so a recovered
+      // bot_message reuses the same sender display name in its target command.
+      fromBotName: settings.profile.name,
       // The pin this Turn was admitted under, and the type it was admitted as.
       // A subagent dispatched from here runs on this generation, and the model
       // catalog it is offered is narrowed by this turn type.
@@ -1655,6 +1679,17 @@ export class ShellBotBackendContribution {
       ...(input.command.origin?.kind === "subagent"
         ? { subagentTaskId: input.command.origin.taskId }
         : {}),
+      ...(input.command.origin?.kind === "bot"
+        ? {
+            inboundAgent: {
+              kind: "bot" as const,
+              fromBotId: input.command.origin.fromBotId,
+              fromBotName: input.command.origin.fromBotName,
+            },
+          }
+        : input.command.origin?.kind === "voice"
+          ? { inboundAgent: { kind: "voice" as const } }
+          : {}),
     };
     let mountedRoot: ShellMountedComposition["root"] | undefined;
     let mountedGeneration: CompositionGenerationV1 | undefined;
@@ -1724,6 +1759,16 @@ export class ShellBotBackendContribution {
               input.command.sessionId,
               effect,
             ),
+          ...(this.recordSettledUsage
+            ? {
+                onTurnStopping: (settled) =>
+                  this.recordSettledUsage!({
+                    botId: input.identity.botId,
+                    runId: input.command.runId,
+                    ...settled,
+                  }),
+              }
+            : {}),
           ...(isolate ? { isolate } : {}),
           ...(appletRouting ? { applets: appletRouting } : {}),
         }).mount(mounting, signal);
@@ -2409,7 +2454,7 @@ export class ShellBotBackendContribution {
       // User with no Computer assignment has no root to pull, and the Bot that
       // just built on its Computer has it open already.
       syncSourceRootNow: active
-        ? async () => {
+        ? async (appletId) => {
             const root = active.mounted.runtime.root as unknown as {
               computers?: ComputerRegistry;
               sessions: typeof active.mounted.runtime.root.sessions;
@@ -2432,6 +2477,9 @@ export class ShellBotBackendContribution {
               sessionId: active.sessionId,
               turn,
               root: appletsSourceRootV1(identity.userId),
+              requiredPaths: APPLET_DIST_FILES_V1.map(
+                (path) => `${appletId}/${path}`,
+              ),
               signal: active.signal,
             });
           }
@@ -3246,6 +3294,22 @@ export class ShellBotBackendContribution {
     };
   }
 
+  /** Narrow RPC for the User-wide agent-lane concurrency lease. */
+  private agentTurnSlots(identity: BotIdentity) {
+    const id = this.env.USER_CONFIGURATIONS.idFromName(identity.userId);
+    const rpc = this.env.USER_CONFIGURATIONS.get(id) as unknown as {
+      reserveAgentTurnSlot(input: unknown): Promise<unknown>;
+      releaseAgentTurnSlot(input: unknown): Promise<unknown>;
+    };
+    return {
+      reserve: async (request: unknown) =>
+        decodeAgentTurnSlotReceiptV1(await rpc.reserveAgentTurnSlot(request)),
+      release: async (request: unknown) => {
+        await rpc.releaseAgentTurnSlot(request);
+      },
+    };
+  }
+
   /**
    * The User-wide `desktop-gui` lease, held at the Computer host.
    *
@@ -4328,6 +4392,7 @@ export class ShellBotBackendContribution {
       runId: string;
       turnId: string;
       sessionId: string;
+      fromBotName: string;
       /**
        * The generation this Turn pinned, and the type it was admitted as. A
        * dispatched subagent runs on the generation its parent pinned, and the
@@ -4517,6 +4582,39 @@ export class ShellBotBackendContribution {
                   this.userConfiguration(identity).listBots(userId),
                 createBot: (userId, command) =>
                   this.userConfiguration(identity).createBot(userId, command),
+                reserveAgentTurn: (request) =>
+                  this.agentTurnSlots(identity).reserve(request),
+                releaseAgentTurn: (request) =>
+                  this.agentTurnSlots(identity).release(request),
+                runAgent: async (request) => {
+                  if (!this.env.BOT_STATES) {
+                    throw new Error("Bot-to-Bot messaging is unavailable");
+                  }
+                  const id = this.env.BOT_STATES.idFromName(
+                    `${request.userId}:${request.botId}`,
+                  );
+                  const rpc = this.env.BOT_STATES.get(id) as unknown as {
+                    runAgent(input: unknown): Promise<unknown>;
+                  };
+                  const completed = decodeClientTurnV1(
+                    structuredClone(await rpc.runAgent(request)),
+                  );
+                  let sentText: string | undefined;
+                  for (const event of completed.events) {
+                    if (event.type !== "send/to-user") continue;
+                    const payload = decodeSendToUserPayloadV1(
+                      event.payload,
+                      "agent send/to-user payload",
+                    );
+                    if (payload.type === "text") {
+                      sentText = payload.text;
+                      break;
+                    }
+                  }
+                  return {
+                    text: sentText ?? completed.text,
+                  };
+                },
               }),
             }
           : {}),
@@ -5951,10 +6049,13 @@ export class ShellBotBackendContribution {
     let budget = BOT_DEBUG_EVENT_BYTES_V1;
     const runs: BotDebugRunV1[] = [];
     for (const candidate of candidates) {
-      const stored = await this.authority.readStoredRun(candidate.runId);
-      if (!stored) continue;
+      const projected = await this.authority.readRunEventProjections(
+        candidate.runId,
+      );
+      if (!projected) continue;
+      const { run: stored } = projected;
       const bounded = includeEvents
-        ? boundDebugEventsV1(stored.events, budget)
+        ? boundDebugEventsV1(projected.events, budget)
         : undefined;
       if (bounded) budget = Math.max(0, budget - bounded.spent);
       runs.push({
@@ -5967,7 +6068,7 @@ export class ShellBotBackendContribution {
         commandFingerprint: stored.commandFingerprint,
         compositionGenerationId: stored.compositionGenerationId,
         previousEventCount: stored.previousEventCount,
-        eventCount: stored.events.length,
+        eventCount: projected.eventCount,
         ...(stored.responseText === undefined
           ? {}
           : { responseText: stored.responseText }),
@@ -6328,7 +6429,24 @@ export class ShellBotBackendContribution {
         transaction.get<BotIdentity>(IDENTITY_KEY),
         transaction.get<unknown>(`${RUN_PREFIX}${runId}`),
       ]);
-      const run = optionalStoredRun(candidate);
+      const storedRun = optionalStoredRun(candidate);
+      let run = storedRun;
+      if (storedRun?.eventRange) {
+        const events = await new SessionEventLog(transaction).readRange(
+          storedRun.sessionId,
+          storedRun.eventRange.startSeq,
+          storedRun.eventRange.endSeq,
+        );
+        if (
+          events.length !==
+          storedRun.eventRange.endSeq - storedRun.eventRange.startSeq
+        ) {
+          throw new Error(
+            `run "${storedRun.runId}" has an incomplete event range`,
+          );
+        }
+        run = requireStoredRunV1({ ...storedRun, events });
+      }
       if (
         activeRunId !== runId ||
         !run ||
@@ -6388,7 +6506,10 @@ export class ShellBotBackendContribution {
           { kind: effect.kind, effectId: effect.effectId, outcome },
         ],
       } satisfies StoredRun);
-      await transaction.put(`${RUN_PREFIX}${runId}`, structuredClone(next));
+      await transaction.put(
+        `${RUN_PREFIX}${runId}`,
+        structuredClone(storedRunRecordV2(next)),
+      );
       return outcome === "admitted";
     });
   }

package/src/client/FrockBotApp.vue

@@ -1490,7 +1490,12 @@ function handleComposerKeydown(event: KeyboardEvent): void {
                 </div>
               </div>
             </template>
-            <div v-else class="message-bubble">{{ message.text }}</div>
+            <div v-else class="message-user-column">
+              <div class="message-bubble">{{ message.text }}</div>
+              <span v-if="message.via" class="message-via">
+                via {{ message.via.name }}
+              </span>
+            </div>
           </article>
           <!--
             The working row: the Bot's own avatar on its own line at the end of

package/src/client/index.test.ts

@@ -95,6 +95,40 @@ afterEach(() => {
   }
 });
 
+test("a degraded Computer sync is a notice beneath the Turn once", () => {
+  const state: Pick<
+    FrockBotWebData,
+    "messages" | "activeRunId" | "runningRunId" | "activeRun"
+  > = { messages: [] };
+
+  projectDurableRuns(
+    state,
+    [],
+    [
+      {
+        runId: "run-sync",
+        input: "build the applet",
+        status: "completed",
+        responseText: "The Applet is ready.",
+        events: [
+          {
+            type: "computer/sync",
+            status: "degraded",
+            message: "Excluded 1 reproducible Workspace item from sync.",
+          },
+        ],
+      },
+    ],
+  );
+
+  expect(state.messages).toHaveLength(2);
+  expect(state.messages[1]).toMatchObject({
+    role: "assistant",
+    text: "The Applet is ready.",
+    notice: "Excluded 1 reproducible Workspace item from sync.",
+  });
+});
+
 describe("application manifest protocol", () => {
   const emptyManifest = {
     schemaVersion: 1,
@@ -1451,6 +1485,33 @@ describe("active durable Turn projection", () => {
     expect(state.messages[1]).toMatchObject({ text: "", status: "streaming" });
   });
 
+  test("keeps the source marker on an agent-origin user bubble", () => {
+    const state: Pick<
+      FrockBotWebData,
+      "messages" | "activeRunId" | "activeRun"
+    > = { messages: [] };
+    projectDurableRuns(
+      state,
+      [],
+      [
+        {
+          runId: "run-agent",
+          input: "What changed?",
+          events: [],
+          status: "completed",
+          responseText: "The answer",
+          via: { kind: "bot", name: "Researcher", botId: "researcher" },
+        },
+      ],
+    );
+
+    expect(state.messages[0]).toMatchObject({
+      role: "user",
+      text: "What changed?",
+      via: { kind: "bot", name: "Researcher" },
+    });
+  });
+
   test("projects dispatched subagents as chips, and skips one it cannot draw", () => {
     const state: Pick<
       FrockBotWebData,