@frockbot/plugin-shell 0.3.5 → 0.3.6

package/frockbot.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 4,
   "id": "shell",
-  "displayName": "FrockBot Shell",
+  "displayName": "FrockBot",
   "version": "0.0.1",
   "compatibility": {
     "frockbot": ">=0.0.1"

package/package.json

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

package/src/backend-authoring.test.ts

@@ -18,6 +18,8 @@ import {
   authorshipUndoIntentKey,
   authorshipUndoOutcomeKey,
   AUTHORSHIP_FAILURE_PREFIX,
+  classifyAuthoringEffectV1,
+  type AuthoringEffectOutcomeV1,
   type AuthoredArtifactRecordV1,
   type AuthoredManifestRecordV1,
   type AuthoringFailureRecordV1,
@@ -234,9 +236,13 @@ describe("a Bot authoring a Package", () => {
     quota?: (request: unknown) => unknown;
     runId?: string;
     currentToolNames?: readonly string[];
+    bundleTimeoutMs?: number;
   }) {
     let ids = 0;
     return createPackageAuthoringHost({
+      ...(options.bundleTimeoutMs === undefined
+        ? {}
+        : { bundleTimeoutMs: options.bundleTimeoutMs }),
       storage,
       composition,
       bundler: options.bundler as never,
@@ -911,4 +917,70 @@ describe("a Bot authoring a Package", () => {
       }),
     );
   });
+
+  test("a bundler outage leaves the effect retryable, not poisoned", async () => {
+    // F11: the "could not be reached" refusal returned without writing any
+    // outcome, so `classifyAuthoringEffectV1` called that effectId `unknown`
+    // forever — "it will not be bundled again". Since the effectId is
+    // run + Package + source hash, retrying the identical source in the same
+    // run could never succeed.
+    const effectId = "author-0123456789abcdef";
+    const offline = {
+      calls: 0,
+      bundle() {
+        offline.calls += 1;
+        return Promise.reject(
+          new Error('Worker "frockbot-cloudflare-bundler" not found'),
+        );
+      },
+    };
+    const refusal = await host({ bundler: offline as never }).author(
+      requestFor(),
+    );
+    expect(refusal.status).toBe("refused");
+
+    const outcome = storage.values.get(
+      authorshipArtifactKey(effectId),
+    ) as AuthoringEffectOutcomeV1;
+    expect(outcome).toMatchObject({ status: "unreachable", effectId });
+    expect(
+      classifyAuthoringEffectV1({
+        intent: storage.values.get(authorshipIntentKey(effectId)) as never,
+        outcome,
+      }),
+    ).toEqual({ kind: "fresh" });
+
+    // And the identical source, in the same run, now goes through.
+    const recovered = await host({
+      bundler: countingBundler((id) => bundledResult(id)),
+    }).author(requestFor());
+    expect(recovered.status).toBe("authored");
+  });
+
+  test("a bundler that never answers is refused at the deadline", async () => {
+    // F10: `bundle()` was awaited with no deadline and no AbortSignal, and the
+    // bundler runs esbuild-wasm inline — a hang there hung this tool call and
+    // the Turn around it, indefinitely.
+    const hanging = {
+      calls: 0,
+      bundle() {
+        hanging.calls += 1;
+        return new Promise<never>(() => {});
+      },
+    };
+    const outcome = await host({
+      bundler: hanging as never,
+      bundleTimeoutMs: 10,
+    }).author(requestFor());
+
+    expect(outcome).toMatchObject({ status: "refused" });
+    if (outcome.status !== "refused") return;
+    expect(outcome.reason).toContain(
+      "the Package bundler could not be reached: the Package bundler did not answer within 10ms",
+    );
+    // Nothing ran, so the effect stays retryable rather than poisoned (F11).
+    expect(
+      storage.values.get(authorshipArtifactKey("author-0123456789abcdef")),
+    ).toMatchObject({ status: "unreachable" });
+  });
 });

package/src/backend-authoring.ts

@@ -143,12 +143,45 @@ export interface PackageAuthoringHostOptions {
   };
   now?(): Date;
   newId?(): string;
+  /** Overrides `PACKAGE_BUNDLE_TIMEOUT_MS_V1`; tests drive the deadline. */
+  bundleTimeoutMs?: number;
 }
 
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * How long the Package bundler has to answer. It runs esbuild-wasm inline, so
+ * a hang there is a hang of this tool call and of the Turn around it; the
+ * service binding itself imposes no deadline (finding F10). Generous, because
+ * a cold `createWorker` is slow, and far short of any Turn-level bound.
+ */
+const PACKAGE_BUNDLE_TIMEOUT_MS_V1 = 60_000;
+
+/**
+ * `work`, or a rejection at the deadline. The pending work is abandoned, not
+ * cancelled: the bundler is stateless and side-effect free (its caller owns
+ * every durable write), so a late answer changes nothing.
+ */
+async function withDeadline<T>(
+  work: Promise<T>,
+  milliseconds: number,
+  message: string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      work,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), milliseconds);
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
 /**
  * Builds the authoring seam one admitted Turn runs under. Constructed per
  * Turn because provenance names the run and turn that produced the artifact.
@@ -691,18 +724,40 @@ export function createPackageAuthoringHost(
       let bundled;
       try {
         // Never inside a storage transaction: bundler CPU is the bundler's.
+        // Bounded, because the bundler runs esbuild-wasm inline: one that
+        // hangs rather than rejects would hang this tool call and the Turn
+        // with it (F10). An expiry takes the same path as unreachability —
+        // nothing ran either way.
+        const deadline =
+          options.bundleTimeoutMs ?? PACKAGE_BUNDLE_TIMEOUT_MS_V1;
         bundled = decodePackageBundleResultV1(
-          await options.bundler.bundle(bundleRequest),
+          await withDeadline(
+            options.bundler.bundle(bundleRequest),
+            deadline,
+            `the Package bundler did not answer within ${deadline}ms`,
+          ),
         );
       } catch (error) {
-        return refused(
-          await recordFailure({
+        const failure = await recordFailure({
+          effectId,
+          packageId,
+          phase: "bundle",
+          reason: `the Package bundler could not be reached: ${errorMessage(error)}`,
+        });
+        // The bundler never answered, so nothing about this effect is
+        // uncertain. Recording that explicitly is what lets an identical
+        // retry in the same run proceed instead of classifying `unknown`
+        // forever (F11).
+        await options.storage.put({
+          [authorshipArtifactKey(effectId)]: {
+            schemaVersion: 1,
+            status: "unreachable",
             effectId,
-            packageId,
-            phase: "bundle",
-            reason: `the Package bundler could not be reached: ${errorMessage(error)}`,
-          }),
-        );
+            failureId: failure.failureId,
+            reason: failure.reason,
+          } satisfies AuthoringEffectOutcomeV1,
+        });
+        return refused(failure);
       }
       if (bundled.status === "failed") {
         const failure = await recordFailure({
@@ -744,15 +799,26 @@ export function createPackageAuthoringHost(
             );
           }));
       if (uiMismatch || (uiPages === undefined && returnedPages.length > 0)) {
-        return refused(
-          await recordFailure({
+        const failure = await recordFailure({
+          effectId,
+          packageId,
+          phase: "bundle",
+          reason:
+            "the Package bundler returned UI bytes that do not match the recorded manifest",
+        });
+        // The bundler did answer, and deterministically: the same source
+        // would mismatch again. That is a settled failure, not an unknown —
+        // it too used to leave the effect with no outcome at all (F11).
+        await options.storage.put({
+          [authorshipArtifactKey(effectId)]: {
+            schemaVersion: 1,
+            status: "failed",
             effectId,
-            packageId,
-            phase: "bundle",
-            reason:
-              "the Package bundler returned UI bytes that do not match the recorded manifest",
-          }),
-        );
+            failureId: failure.failureId,
+            reason: failure.reason,
+          } satisfies AuthoringEffectOutcomeV1,
+        });
+        return refused(failure);
       }
       // Content-addressed and immutable: writing the same hash twice is a
       // no-op, so the object write is safe to repeat and the record is not.

package/src/backend-configuration.test.ts

@@ -702,10 +702,12 @@ describe("generic per-Turn model resolution", () => {
           acceptedAt: "2026-09-02T00:01:00.000Z",
           text: "must fail",
         }),
-      ).rejects.toThrow("not installed and enabled");
+      ).rejects.toThrow("Turn this model's plugin back on in Plugins");
       expect(await bot.storage.get(`run:${runId}`)).toMatchObject({
         status: "failed",
-        failure: expect.stringContaining("not installed and enabled"),
+        failure: expect.stringContaining(
+          "Turn this model's plugin back on in Plugins",
+        ),
       });
     }
 
@@ -722,10 +724,10 @@ describe("generic per-Turn model resolution", () => {
           acceptedAt: "2026-09-02T00:02:00.000Z",
           text: "must fail",
         }),
-      ).rejects.toThrow("is revoked");
+      ).rejects.toThrow("needs reconnecting");
       expect(await bot.storage.get(`run:${runId}`)).toMatchObject({
         status: "failed",
-        failure: expect.stringContaining("is revoked"),
+        failure: expect.stringContaining("needs reconnecting"),
       });
     }
   });

package/src/backend-package-catalog.test.ts

@@ -147,7 +147,12 @@ async function bootstrap(): Promise<CompositionGenerationV1> {
 }
 
 async function fixture(
-  options: { connected?: boolean; uiAvailable?: boolean } = {},
+  options: {
+    connected?: boolean;
+    uiAvailable?: boolean;
+    /** A deployment with no published Catalog pins no generation. */
+    pinned?: boolean;
+  } = {},
 ) {
   const log: string[] = [];
   const records = new Map<string, unknown>();
@@ -220,8 +225,9 @@ async function fixture(
           },
         ]
       : [],
-    catalogGeneration: "catalog-1",
-    catalogIndexHash: "d".repeat(64),
+    ...(options.pinned === false
+      ? {}
+      : { catalogGeneration: "catalog-1", catalogIndexHash: "d".repeat(64) }),
   };
   const commands: UserConfigurationCommandV1[] = [];
   const userAuthority = {
@@ -306,6 +312,20 @@ describe("Bot Package Catalog host", () => {
     });
   });
 
+  test("explains an unpinned Catalog in words a person can act on", async () => {
+    const { host } = await fixture({ pinned: false });
+    // F4: an unpinned User used to be told "this User has no pinned Package
+    // Catalog generation", which the Bot then relayed verbatim.
+    for (const call of [
+      () => host.search({ query: "shipping" }),
+      () => host.inspect({ catalogId: "parcel-tracking" }),
+    ]) {
+      await expect(call()).rejects.toThrow(
+        "No Package Catalog is published for this deployment, so there is nothing to search or install",
+      );
+    }
+  });
+
   test("persists the iframe manifest before the User effect, appends a summary generation, and replays", async () => {
     const test = await fixture();
     const request = {

package/src/backend-package-catalog.ts

@@ -145,7 +145,13 @@ function requiredCatalogPin(user: UserSettingsViewV1): {
   indexHash: string;
 } {
   if (!user.catalogGeneration || !user.catalogIndexHash) {
-    throw new Error("this User has no pinned Package Catalog generation");
+    // A User is pinned on the first configuration read that finds a published
+    // Catalog, so an absent pin means the deployment has none to find. Say
+    // that, rather than an internal sentence about pinning the Bot then
+    // relays to the person who asked.
+    throw new Error(
+      "No Package Catalog is published for this deployment, so there is nothing to search or install",
+    );
   }
   return {
     generation: user.catalogGeneration,

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

@@ -626,7 +626,11 @@ describe("Bot recovery", () => {
     expect(await recoveredAgain.listNotifications()).toEqual(notifications);
   });
 
-  test("preserves an unresolved request for an explicit decision", async () => {
+  // ADR 0028. This used to park the run and hand the person a Resolve button.
+  // `provider-1` has no retrieval — none of the providers this deployment
+  // ships does — so there was never an answer to resolve it with, and the Bot
+  // stayed wedged behind it.
+  test("settles an unresolved request no provider can be asked about", async () => {
     const storage = new MemoryStorage();
     const settings = initializeBotSettingsV1("primary");
     const events = [
@@ -690,19 +694,14 @@ describe("Bot recovery", () => {
       env: {} as never,
     });
 
-    await expect(recovered.listRuns()).resolves.toEqual({
-      schemaVersion: 1,
-      runs: [
-        expect.objectContaining({
-          schemaVersion: 2,
-          runId: "run-lost-marker",
-          status: "reconciliation-required",
-          recovery: expect.objectContaining({ action: "resume" }),
-        }),
-      ],
-      page: { truncated: false },
-    });
-    expect(storage.values.get("active-run")).toBe("run-lost-marker");
+    await recovered.listRuns();
+
+    const settled = storage.values.get("run:run-lost-marker") as StoredRun;
+    expect(settled.status).toBe("failed");
+    expect(settled.failure).toContain("stopped partway");
+    // The Bot is released: nothing is holding the next Turn behind a decision
+    // nobody can make.
+    expect(storage.values.get("active-run")).toBeUndefined();
     expect(storage.alarmAt).toBeUndefined();
   });
 

package/src/backend.ts

@@ -446,6 +446,25 @@ import {
 } from "./unread.js";
 import { defineBotBackendContribution } from "@frockbot/kernel-contracts/contributions";
 
+/**
+ * The providers that can be asked what happened to a model request they never
+ * answered — that is, the ones whose Package registers an
+ * `LlmReconciliationCapability` (ADR 0028).
+ *
+ * It is a list rather than a lookup because recovery consults it inside the
+ * durable transaction that settles the run, where nothing may be mounted or
+ * awaited. The cost is that a provider Package which gains retrieval has to
+ * name itself here; the ADR carries that obligation, and the failure mode of
+ * forgetting is a Turn settled as failed rather than one wedged forever, which
+ * 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.
+ */
+const RECONCILING_PROVIDER_IDS_V1: ReadonlySet<string> = new Set([
+  "foundation",
+]);
+
 export const BOT_CONFIGURATION_KEY = "bot-configuration";
 const CONFIGURATION_RECEIPT_PREFIX = "configuration-receipt:";
 const STOP_RECEIPT_PREFIX = "stop-receipt:";
@@ -784,6 +803,8 @@ export class ShellBotBackendContribution {
         deferScheduledWork: (transaction) =>
           this.deferScheduledWork(transaction),
         settleScheduledWork: () => this.settleScheduledWork(),
+        providerReconciles: (providerId) =>
+          RECONCILING_PROVIDER_IDS_V1.has(providerId),
       },
     });
   }
@@ -4572,13 +4593,13 @@ export class ShellBotBackendContribution {
     if (!effectiveModel) {
       throw new Error(
         effective.binding?.failure ??
-          "No model is configured; enable a model Package or restore the platform model",
+          "No model is set up yet. Choose one in Models.",
       );
     }
     const binding: ResolvedModelBindingV1 = effective.binding ?? {
       model: structuredClone(effectiveModel),
       state: "unavailable",
-      failure: "The resolved model Connection is unavailable",
+      failure: "This Bot's model isn't available. Pick one in Models.",
     };
     if (
       binding.state === "unavailable" ||
@@ -4587,7 +4608,8 @@ export class ShellBotBackendContribution {
       !binding.packageId
     ) {
       throw new Error(
-        binding.failure ?? "The resolved model Connection is unavailable",
+        binding.failure ??
+          "This Bot's model isn't available. Pick one in Models.",
       );
     }
     if (
@@ -4600,7 +4622,9 @@ export class ShellBotBackendContribution {
         admittedRequest.modelBinding.connectionGeneration !==
           binding.connection.generation)
     ) {
-      throw new Error("Admitted model binding is unavailable");
+      throw new Error(
+        "This Bot's model changed mid-reply. Send your message again.",
+      );
     }
     const bindingPackageId = binding.packageId;
     agentPackages.push(

package/src/client/AppletCanvas.vue

@@ -147,7 +147,7 @@ function generationLabel(generationId: string): string {
     hour: "numeric",
     minute: "2-digit",
   });
-  return `Live since ${when} · ${hash.slice(0, 7)}`;
+  return `Live since ${when}`;
 }
 
 function selectTab(next: "app" | "code"): void {
@@ -199,10 +199,8 @@ async function clearFocus(): Promise<void> {
       /></span>
       <div class="applet-canvas-title">
         <strong>{{ applet?.displayName ?? "Applet" }}</strong>
-        <small v-if="viewer" :title="viewer.generationId">{{
-          generationLabel(viewer.generationId)
-        }}</small>
-        <small v-else>No published version yet</small>
+        <small v-if="viewer">{{ generationLabel(viewer.generationId) }}</small>
+        <small v-else>Not published yet</small>
       </div>
       <div
         v-if="canShowApp"