@frockbot/plugin-shell 0.3.11 → 0.3.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "private": false,
   "type": "module",
   "exports": {
@@ -27,6 +27,7 @@
     "./client/FrockBotApp.vue": "./src/client/FrockBotApp.vue",
     "./client/notify": "./src/client/notify.ts",
     "./client/styles.css": "./src/client/styles.css",
+    "./focus": "./src/focus.ts",
     "./frockbot.json": "./frockbot.json",
     "./host": "./src/host.ts",
     "./manifest": "./src/manifest.ts",
@@ -48,46 +49,46 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/agent-runtime": "0.3.11",
-    "@frockbot/application-foundation": "0.3.11",
-    "@frockbot/catalog-core": "0.3.11",
-    "@frockbot/client-core": "0.3.11",
-    "@frockbot/client-ui": "0.3.11",
-    "@frockbot/computer-core": "0.3.11",
-    "@frockbot/computer-host-protocol": "0.3.11",
-    "@frockbot/configuration-core": "0.3.11",
-    "@frockbot/connection-core": "0.3.11",
-    "@frockbot/kernel-agent-loop": "0.3.11",
-    "@frockbot/kernel-composition": "0.3.11",
-    "@frockbot/kernel-contracts": "0.3.11",
-    "@frockbot/kernel-do": "0.3.11",
-    "@frockbot/machine-protocol": "0.3.11",
-    "@frockbot/plugin-applets": "0.3.11",
-    "@frockbot/plugin-authoring": "0.3.11",
-    "@frockbot/plugin-bot-template": "0.3.11",
-    "@frockbot/plugin-computer": "0.3.11",
-    "@frockbot/plugin-flock": "0.3.11",
-    "@frockbot/plugin-image": "0.3.11",
-    "@frockbot/plugin-machine-messages": "0.3.11",
-    "@frockbot/plugin-mcp": "0.3.11",
-    "@frockbot/plugin-memory": "0.3.11",
-    "@frockbot/plugin-package-catalog": "0.3.11",
-    "@frockbot/plugin-routines": "0.3.11",
-    "@frockbot/plugin-skills": "0.3.11",
-    "@frockbot/plugin-subagents": "0.3.11",
-    "@frockbot/plugin-user-machine": "0.3.11",
-    "@frockbot/protocol": "0.3.11",
+    "@frockbot/agent-runtime": "0.3.12",
+    "@frockbot/application-foundation": "0.3.12",
+    "@frockbot/catalog-core": "0.3.12",
+    "@frockbot/client-core": "0.3.12",
+    "@frockbot/client-ui": "0.3.12",
+    "@frockbot/computer-core": "0.3.12",
+    "@frockbot/computer-host-protocol": "0.3.12",
+    "@frockbot/configuration-core": "0.3.12",
+    "@frockbot/connection-core": "0.3.12",
+    "@frockbot/kernel-agent-loop": "0.3.12",
+    "@frockbot/kernel-composition": "0.3.12",
+    "@frockbot/kernel-contracts": "0.3.12",
+    "@frockbot/kernel-do": "0.3.12",
+    "@frockbot/machine-protocol": "0.3.12",
+    "@frockbot/plugin-applets": "0.3.12",
+    "@frockbot/plugin-authoring": "0.3.12",
+    "@frockbot/plugin-bot-template": "0.3.12",
+    "@frockbot/plugin-computer": "0.3.12",
+    "@frockbot/plugin-flock": "0.3.12",
+    "@frockbot/plugin-image": "0.3.12",
+    "@frockbot/plugin-machine-messages": "0.3.12",
+    "@frockbot/plugin-mcp": "0.3.12",
+    "@frockbot/plugin-memory": "0.3.12",
+    "@frockbot/plugin-package-catalog": "0.3.12",
+    "@frockbot/plugin-routines": "0.3.12",
+    "@frockbot/plugin-skills": "0.3.12",
+    "@frockbot/plugin-subagents": "0.3.12",
+    "@frockbot/plugin-user-machine": "0.3.12",
+    "@frockbot/protocol": "0.3.12",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "latest",
-    "@frockbot/plugin-prompt": "0.3.11",
-    "@frockbot/plugin-tools": "0.3.11",
+    "@frockbot/plugin-prompt": "0.3.12",
+    "@frockbot/plugin-tools": "0.3.12",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",
-    "typescript": "5.9.3",
+    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
     "vite": "8.2.2",
     "vue-tsc": "3.3.10"
   },

package/src/agent.ts

@@ -39,7 +39,15 @@ import {
 } from "@frockbot/kernel-contracts";
 // Merges the Agent loop's event declarations into the cordis Context type.
 import type {} from "@frockbot/kernel-agent-loop/agent";
-import { automationParentPointerV1, turnScopedMessagesV1 } from "./history.js";
+import {
+  automationParentPointerV1,
+  chatWindowV1,
+  CHAT_HISTORY_BUDGET_CHARS_V1,
+  turnScopedMessagesV1,
+  turnTypesByTurnV1,
+} from "./history.js";
+import { runCompactionV1 } from "./compaction.js";
+import { compactionWorkV1 } from "./compaction-scheduler.js";
 import type { Plugin } from "cordis";
 import manifest from "../frockbot.json" with { type: "json" };
 
@@ -85,6 +93,11 @@ function refusal(reason: string): ToolExecutionResult {
   return { content: reason, isError: true };
 }
 
+/** Adapts a cordis fiber to the plain disposer this Package's list holds. */
+function disposeFiber(fiber: { dispose(): unknown }): () => void {
+  return () => void fiber.dispose();
+}
+
 /**
  * The open step a Shell event belongs to. The session log is the
  * reconstruction surface, so a send without its turn and step would not
@@ -348,6 +361,57 @@ export const shellAgentPlugin: Plugin.Function = (ctx) => {
       createWakeParentTool(ctx.sessions),
       parentHandoff ? { admissionCeiling: parentHandoff } : undefined,
     ),
+    // ADR 0030. `ctx.inject` rather than a declared dependency: a host that
+    // mounts the Shell without a model still gets its tools and its transcript
+    // seam, and simply never compacts. The hook is evaluated after `turn/end`
+    // is on the log and flushed — but `agent/turn-stopping` is a hook the loop
+    // *awaits* inside its `finally`, so running the summariser here is exactly
+    // the latency ADR 0030 says a compaction never costs. It is handed to the
+    // detached scheduler instead and this returns at once: the Turn ends, the
+    // run settles, the response goes out, and the summariser carries on behind
+    // it. Nothing here may throw, and nothing here may wait.
+    disposeFiber(
+      ctx.inject(["llm"], (scoped) => {
+        scoped.on("agent/turn-stopping", async (agent, turn) => {
+          const session = agent.session;
+          const types = turnTypesByTurnV1(session.events);
+          if ((types.get(turn) ?? "chat") !== "chat") return;
+          compactionWorkV1(session.id).start(async (signal) => {
+            if (signal.aborted) return;
+            await runCompactionV1({
+              session,
+              window: chatWindowV1(session.events, session.deriveMessages()),
+              budget: CHAT_HISTORY_BUDGET_CHARS_V1,
+              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;
+                }
+                return text;
+              },
+            });
+          });
+        });
+      }),
+    ),
     // Applied after the rest of the chain, so this Package has the last word on
     // what history a request carries — the one rule the visible transcript
     // rests on.

package/src/backend-configuration.test.ts

@@ -150,7 +150,7 @@ function configuredUser(): UserSettingsViewV1 {
         connectionId: "flock-ai-ambient",
         packageId: "provider-flock-ai",
         connectionTypeId: "flock-ai-account",
-        displayName: "Flock AI",
+        displayName: "Frock AI",
         state: "ready",
         providerType: "flock-ai",
         generation: "foundation-generation-1",
@@ -160,7 +160,7 @@ function configuredUser(): UserSettingsViewV1 {
           state: "fresh",
           models: [
             {
-              providerModelId: "@flock/auto",
+              providerModelId: "@frock/auto",
               displayName: "Platform",
               capabilities: {
                 tools: true,
@@ -174,7 +174,7 @@ function configuredUser(): UserSettingsViewV1 {
         safeMetadata: {},
       },
     ],
-    platformModel: model("flock-ai-ambient", "@flock/auto"),
+    platformModel: model("flock-ai-ambient", "@frock/auto"),
   };
 }
 
@@ -194,7 +194,7 @@ function host(storage: MemoryStorage, readUser: () => UserSettingsViewV1) {
       },
       MEMORY_FILES: {},
       MEMORY_INDEX: {},
-      FLOCK_AI: {
+      FROCK_AI: {
         autoRoute: "flock-auto",
         runChatCompletion: () =>
           Promise.resolve(
@@ -527,7 +527,7 @@ describe("generic per-Turn model resolution", () => {
       connectionId: "flock-ai-ambient",
       packageId: "provider-flock-ai",
       provider: "flock-ai",
-      providerModelId: "@flock/auto",
+      providerModelId: "@frock/auto",
       connectionGeneration: "foundation-generation-1",
       catalogGeneration: "catalog-1",
     });
@@ -651,7 +651,7 @@ describe("generic per-Turn model resolution", () => {
       ),
     };
     expect(await contribution.resolveConfiguration(identity)).toMatchObject({
-      model: model("flock-ai-ambient", "@flock/auto"),
+      model: model("flock-ai-ambient", "@frock/auto"),
     });
     expect(await contribution.getSettings(identity)).toMatchObject({
       packageValues: {

package/src/backend-runner.ts

@@ -17,6 +17,10 @@ import {
   BotTurnRecoveryRequiredError,
 } from "@frockbot/kernel-do";
 import type { BotTurnCommand, BotTurnCompletion } from "./backend-contracts.js";
+import {
+  compactionInFlightV1,
+  whenCompactionSettledV1,
+} from "./compaction-scheduler.js";
 
 export {
   BotTurnExecutionError,
@@ -370,11 +374,24 @@ export async function executeBotTurn(
     await runtime.agent.agent.whenIdle();
     return settleBotTurn(runtime.agent, command, previousEvents);
   } catch (error) {
-    turnExecutionError(error, previousEvents, [
+    return turnExecutionError(error, previousEvents, [
       ...runtime.agent.agent.session.events,
     ]);
   } finally {
-    await composition.dispose();
+    // ADR 0030: a compaction outlives the Turn that triggered it, and it runs
+    // on this Composition's model binding — so the Composition outlives the
+    // Turn too, and only by as long as the compaction does. Awaiting the
+    // disposal here would put the summariser back in the latency path, which
+    // is the whole defect. The next admission aborts anything still running,
+    // so this can never stack up.
+    if (compactionInFlightV1(command.sessionId)) {
+      void whenCompactionSettledV1(command.sessionId).then(
+        () => composition.dispose(),
+        () => composition.dispose(),
+      );
+    } else {
+      await composition.dispose();
+    }
   }
 }
 

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(
@@ -1593,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,
@@ -4764,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,
@@ -5402,12 +5442,15 @@ export class ShellBotBackendContribution {
    * 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> {
-    if (runId === undefined) return false;
     try {
-      const run = await this.authority.readRun(runId);
-      return run?.status === "running";
+      return await this.authority.resolveRunWorking(runId);
     } catch {
       return false;
     }
@@ -5637,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) {
@@ -5706,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");
@@ -5739,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> {