@frockbot/plugin-shell 0.3.10 → 0.3.12

package/src/backend.ts

@@ -52,6 +52,8 @@ import {
   RUN_ADMISSION_FENCE_PREFIX,
   RUN_INDEX_PREFIX,
   RUN_PREFIX,
+  CONVERSATION_BUSY_MESSAGE_V1,
+  isConversationBusyV1,
   type BotIdentity,
   type BotDurableAuthorityOptions,
   type BotTurnExecutionInput,
@@ -389,6 +391,7 @@ import {
   projectPackageIframeCompositionV1,
 } from "./composition-views.js";
 import { executeBotTurn, executeDirectToolTurn } from "./backend-runner.js";
+import { yieldCompactionWorkV1 } from "./compaction-scheduler.js";
 import {
   shellTerminalRecordsV1,
   supersededTurnRecordsV1,
@@ -410,6 +413,7 @@ import {
   projectClientTurnV1,
   type ClientRunLookupV1,
   type ClientConversationListV1,
+  type ClientConversationOutcomeV1,
   type ClientRunListV1,
   type ClientRunStopReceiptV1,
   type ClientRunV1,
@@ -475,7 +479,7 @@ import { defineBotBackendContribution } from "@frockbot/kernel-contracts/contrib
  * is the direction this deployment wants to be wrong in.
  *
  * Today: the in-process foundation provider, and nothing else. Ollama Cloud
- * exposes no provider-bound retrieval (ADR 0010) and neither does Flock AI.
+ * exposes no provider-bound retrieval (ADR 0010) and neither does Frock AI.
  */
 const RECONCILING_PROVIDER_IDS_V1: ReadonlySet<string> = new Set([
   "foundation",
@@ -588,8 +592,8 @@ export interface BotStateEnv {
   MEMORY_INDEX: VectorizeIndex;
   /** The native AI binding consumed through the image Package adapter. */
   AI?: NativeAiBindingV1;
-  /** The Flock AI Gateway adapter constructed by the Cloudflare host. */
-  FLOCK_AI?: {
+  /** The Frock AI Gateway adapter constructed by the Cloudflare host. */
+  FROCK_AI?: {
     autoRoute: string;
     runChatCompletion(
       gatewayModel: string,
@@ -1135,14 +1139,43 @@ export class ShellBotBackendContribution {
     if (expired.length > 0) await transaction.delete(expired);
   }
 
-  /** The announcements the Session shows, oldest first. */
+  /**
+   * The announcements the Session shows, oldest first.
+   *
+   * Two sources, and deliberately so. A rename or a settled task has no live
+   * Session to be appended to, so it lives in this object's own bounded
+   * announcement log. A compaction (ADR 0030) is already a durable event on
+   * the conversation's session log — appending a second copy of it here would
+   * be two records of one fact — so it is read back from there instead.
+   */
   async listAnnouncements(): Promise<SessionEvent[]> {
     const stored = await this.ctx.storage.list<unknown>({
       prefix: BOT_ANNOUNCEMENT_PREFIX,
     });
-    return [...stored.entries()]
+    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)) ?? [];
+    for (const event of session) {
+      if (event.type === "conversation/compacted") announcements.push(event);
+    }
+    return announcements
+      .sort((left, right) => left.timestamp.localeCompare(right.timestamp))
+      .slice(-BOT_ANNOUNCEMENT_RETENTION);
+  }
+
+  /**
+   * The announcements as the transcript reads them, each already carrying the
+   * 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)) ?? [];
+    return projectClientAnnouncementsV1(
+      await this.listAnnouncements(),
+      session,
+    );
   }
 
   private async refreshRecoveryAlarm(
@@ -1158,6 +1191,9 @@ export class ShellBotBackendContribution {
   }
 
   async run(command: OwnedBotTurnCommand): Promise<ClientTurnV1> {
+    // Before the authority reads the session log, so a compaction detached
+    // from the previous Turn has already handed the log back (ADR 0030).
+    await yieldCompactionWorkV1(command.sessionId);
     // Before admission, so the pin this Turn takes already carries whatever the
     // User's Applet directory says now.
     await this.resolveAppletComposition(
@@ -1239,18 +1275,7 @@ export class ShellBotBackendContribution {
     return { schemaVersion: 1, skills: entries };
   }
 
-  /**
-   * The one durable manifest lookup used by mounts, commands, and UI views —
-   * as the **stored document**, byte-for-byte what `manifestHash` was taken
-   * over at authoring time.
-   *
-   * Decoding rebuilds the object (`decodeV5` always writes a `configuration`
-   * key, for one), so a decoded manifest does not canonicalize back to the
-   * recorded hash. Every mount re-verifies that hash
-   * (`botIsolatePackageDescriptorV1`), so the raw document is the only thing
-   * that can be handed to it; callers that want the typed shape decode it
-   * themselves through `readCompositionMemberManifest`.
-   */
+  /** The two places this Bot's manifests live; see `composition-manifest.ts`. */
   private compositionManifestSources(): CompositionManifestSourcesV1 {
     return {
       stored: (manifestHash) =>
@@ -1261,6 +1286,16 @@ export class ShellBotBackendContribution {
     };
   }
 
+  /**
+   * The manifest a **mount** is handed: the stored document, byte-for-byte
+   * what `manifestHash` was taken over at authoring time.
+   *
+   * Decoding rebuilds the object (`decodeV5` always writes a `configuration`
+   * key, for one), so a decoded manifest does not canonicalize back to the
+   * recorded hash. Every mount re-verifies that hash
+   * (`botIsolatePackageDescriptorV1`), so the raw document is the only thing
+   * that can be handed to it.
+   */
   private readCompositionMemberManifestDocument(
     member: CompositionMemberV1,
   ): Promise<unknown | undefined> {
@@ -1270,6 +1305,10 @@ export class ShellBotBackendContribution {
     );
   }
 
+  /**
+   * The same manifest as the typed shape, for the callers that are not mounts:
+   * commands and UI views, which read fields rather than re-hash the document.
+   */
   private readCompositionMemberManifest(
     member: CompositionMemberV1,
   ): Promise<FrockBotManifest | undefined> {
@@ -1590,6 +1629,10 @@ export class ShellBotBackendContribution {
   private async executeTurn(
     input: BotTurnExecutionInput<BotSettingsViewV1>,
   ): Promise<BotTurnCompletion> {
+    // ADR 0030: a compaction detached from the previous Turn yields to this
+    // one rather than holding it. Free when none is running, and an abort when
+    // one is, so this Turn is the only writer of the session log.
+    await yieldCompactionWorkV1(input.command.sessionId);
     const settings = input.configurationSnapshot;
     const turn = {
       runId: input.command.runId,
@@ -4761,11 +4804,11 @@ export class ShellBotBackendContribution {
             bindingPackageId,
             effectId,
           ),
-        ...(this.env.FLOCK_AI
+        ...(this.env.FROCK_AI
           ? {
-              flockAiAutoRoute: this.env.FLOCK_AI.autoRoute,
-              runFlockAiChatCompletion: (gatewayModel, body) =>
-                this.env.FLOCK_AI!.runChatCompletion(gatewayModel, body),
+              frockAiAutoRoute: this.env.FROCK_AI.autoRoute,
+              runFrockAiChatCompletion: (gatewayModel, body) =>
+                this.env.FROCK_AI!.runChatCompletion(gatewayModel, body),
             }
           : {}),
         fetch: this.outboundFetch,
@@ -5386,9 +5429,33 @@ export class ShellBotBackendContribution {
       index.map((entry) => entry.cursor),
       await this.sidebarPreview(storedPreview, index),
       failures,
+      await this.isWorking(index[0]?.runId),
     );
   }
 
+  /**
+   * Whether the Bot's newest admitted run is still going.
+   *
+   * The sidebar draws this as an activity ring, so somebody in another
+   * conversation can see a Bot working rather than reading a quiet row as a
+   * stalled one. It is the newest run only: a Bot admits one Turn at a time,
+   * so an older run that is somehow still marked running is a reconciliation
+   * problem and not something a ring should report. A read that fails is no
+   * ring — liveness is never worth failing a sidebar poll for.
+   *
+   * The record's `status` is not the test and never was. `resolveRunWorking`
+   * holds the rule — running, inside the Turn deadline, and a Turn the log has
+   * not already closed — and settles the record when it finds one that only
+   * claims to be running, which is why this read is also the repair.
+   */
+  private async isWorking(runId: string | undefined): Promise<boolean> {
+    try {
+      return await this.authority.resolveRunWorking(runId);
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * How many stored runs a read will open to recover a missing preview. The
    * newest settled chat Turn is almost always the first entry; the bound is
@@ -5613,6 +5680,16 @@ export class ShellBotBackendContribution {
       limit: CLIENT_RUN_PAGE_LIMIT + 1,
       ...(query.before ? { before: query.before } : {}),
     });
+    // The open chat draws its own activity ring from whichever run this page
+    // projects as `running`, so it owes the same liveness rule the sidebar row
+    // does — and from the same helper, or the two surfaces disagree about the
+    // same Bot. Only the newest run and the active marker are asked: a Turn
+    // further back cannot be the one anybody is waiting on, and a transcript
+    // read is not the place to walk a Bot's whole history looking for
+    // leftovers.
+    if (!query.before) {
+      await this.isWorking(activeRunId ?? candidates[0]?.runId);
+    }
 
     const selected = new Map<string, { cursor?: string; run: ClientRunV1 }>();
     if (activeRunId) {
@@ -5682,9 +5759,7 @@ export class ShellBotBackendContribution {
         : { truncated: false },
       // Announcements belong to the Session, not to a page of Turns, so only
       // the newest page carries them.
-      query.before
-        ? []
-        : projectClientAnnouncementsV1(await this.listAnnouncements()),
+      query.before ? [] : await this.projectAnnouncementPage(),
     );
     if (clientRunListWireBytes(page) > CLIENT_RUN_LIST_MAX_BYTES) {
       throw new Error("required run projections exceed the wire byte limit");
@@ -5715,10 +5790,26 @@ export class ShellBotBackendContribution {
    */
   async startConversation(
     identity: BotIdentity,
-  ): Promise<ClientConversationListV1> {
+  ): Promise<ClientConversationOutcomeV1> {
     await this.validateIdentity(identity);
-    await this.authority.startConversation(identity);
-    return this.listConversations();
+    try {
+      await this.authority.startConversation(identity);
+    } catch (error) {
+      // The one refusal this can give travels as data. Everything else is a
+      // genuine failure and still throws, so the boundary above answers 500.
+      if (isConversationBusyV1(error)) {
+        return {
+          status: "refused",
+          schemaVersion: 1,
+          reason:
+            error instanceof Error
+              ? error.message
+              : CONVERSATION_BUSY_MESSAGE_V1,
+        };
+      }
+      throw error;
+    }
+    return { status: "started", ...(await this.listConversations()) };
   }
 
   async lookupRun(input: unknown): Promise<ClientRunLookupV1> {