@frockbot/plugin-shell 0.3.20 → 0.3.22

package/package.json

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

package/src/agent.test.ts

@@ -7,6 +7,7 @@ import {
   type ToolCall,
   type ToolExecutionContext,
   type TurnTypeV1,
+  TURN_DEADLINE_MS_V1,
 } from "@frockbot/kernel-contracts";
 import { SystemPromptRegistry } from "@frockbot/plugin-prompt";
 import { ToolRegistry } from "@frockbot/plugin-tools";
@@ -19,6 +20,7 @@ import {
   PARENT_HANDOFF_CAPABILITY_V1,
   SEND_MESSAGE_ALIAS_V1,
   SEND_TO_USER_TOOL_V1,
+  TIME_BUDGET_WARNING_MS_V1,
   USER_VOICE_CAPABILITY_V1,
   WAKE_PARENT_TOOL_V1,
 } from "./agent.ts";
@@ -575,6 +577,36 @@ describe("the acknowledgement reaches the user", () => {
     }
   });
 
+  test("the last two minutes of a Turn tell the model to send a status", async () => {
+    const mounted = await mount();
+    try {
+      const assemble = (remainingMs: number) =>
+        mounted.root.systemPrompt.assemble({
+          sessionId: "session-1",
+          provider: "provider-1",
+          model: "model-1",
+          turnType: "chat",
+          step: { current: 61, max: 64 },
+          deadline: {
+            at: TURN_DEADLINE_MS_V1,
+            now: TURN_DEADLINE_MS_V1 - remainingMs,
+          },
+        });
+      const boundary = await assemble(TIME_BUDGET_WARNING_MS_V1);
+      expect(boundary.text).not.toContain("<time_budget>");
+      const warning = await assemble(TIME_BUDGET_WARNING_MS_V1 - 1);
+      expect(warning.text).toContain("<time_budget>");
+      expect(warning.text).toContain("fewer than 2 minutes left");
+      expect(warning.text).toContain("Do not start new work");
+      expect(warning.text).toContain(SEND_TO_USER_TOOL_V1);
+      expect(warning.text.indexOf("<time_budget>")).toBeGreaterThan(
+        warning.text.indexOf("<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

@@ -234,6 +234,11 @@ export const STEP_BUDGET_PROMPT_SECTION_V1 = "step-budget";
 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;
+export const TIME_BUDGET_PROMPT_SECTION_V1 = "time-budget";
+/** Immediately after the step warning, so the time warning is read last. */
+export const TIME_BUDGET_PROMPT_ORDER_V1 = 91;
+/** The section appears only once strictly fewer than two minutes remain. */
+export const TIME_BUDGET_WARNING_MS_V1 = 2 * 60_000;
 
 /**
  * What the model is told when its reply is about to be stopped.
@@ -265,6 +270,23 @@ export function stepBudgetPromptTextV1(context: {
   ].join("\n");
 }
 
+/** Warns by wall-clock budget even when the model has used few steps. */
+export function timeBudgetPromptTextV1(context: {
+  deadline?: { at: number; now: number };
+}): string {
+  const deadline = context.deadline;
+  if (!deadline) return "";
+  const remaining = deadline.at - deadline.now;
+  if (!Number.isFinite(remaining) || remaining >= TIME_BUDGET_WARNING_MS_V1) {
+    return "";
+  }
+  return [
+    "<time_budget>",
+    `This Turn has fewer than 2 minutes left 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.`,
+    "</time_budget>",
+  ].join("\n");
+}
+
 export const CONVERSATION_PROMPT_TEXT_V1 = [
   "## Talking to the user",
   "",
@@ -469,6 +491,11 @@ export const shellAgentPlugin: Plugin.Function = (ctx) => {
       order: STEP_BUDGET_PROMPT_ORDER_V1,
       render: (context) => stepBudgetPromptTextV1(context),
     }),
+    ctx.systemPrompt.register({
+      id: TIME_BUDGET_PROMPT_SECTION_V1,
+      order: TIME_BUDGET_PROMPT_ORDER_V1,
+      render: (context) => timeBudgetPromptTextV1(context),
+    }),
     ctx.tools.register(
       createSendToUserTool(SEND_TO_USER_TOOL_V1, ctx.sessions),
       userVoice ? { admissionCeiling: userVoice } : undefined,

package/src/backend-applets.test.ts

@@ -8,6 +8,7 @@ import {
   resolveAppletCompositionV1,
   APPLET_DIRECTORY_REVISION_SEEN_KEY,
   type AppletInstanceBindingV1,
+  type AppletSourceSyncOutcomeV1,
   type AppletUserDirectoryV1,
 } from "./backend-applets.js";
 import {
@@ -344,6 +345,7 @@ describe("ctx.applets", () => {
     directory?: Partial<AppletUserDirectoryV1>;
     instance?: Partial<AppletInstanceBindingV1>;
     storage?: ReturnType<typeof memoryStorage>;
+    synced?: AppletSourceSyncOutcomeV1;
   }) {
     const storage = options.storage ?? memoryStorage();
     const recorded: unknown[] = [];
@@ -455,6 +457,9 @@ describe("ctx.applets", () => {
           stat: () =>
             Promise.resolve({ status: "not-found", reason: "" }) as never,
         },
+        ...(options.synced
+          ? { syncSourceRootNow: () => Promise.resolve(options.synced!) }
+          : {}),
         composition: {
           current: () => bootstrap(),
           lastKnownGood: () => bootstrap(),
@@ -488,6 +493,39 @@ describe("ctx.applets", () => {
     );
   });
 
+  // Production, 2026-09-04: a 470 KB `dist/ui.html` the Bot had just built was
+  // reported as `not-found: run \`applet build\` … first`, and the Bot ran the
+  // build again, three times. The build was fine; the sync could not carry the
+  // file. The publish says which of the two it was now.
+  test("publish says a built file did not reach the Workspace rather than blaming the build", async () => {
+    const { host: capability } = host({
+      files: {},
+      synced: {
+        status: "degraded",
+        detail:
+          '1 sync operation failed at "dist/ui.html": unavailable: the Computer could not answer.',
+      },
+    });
+    const outcome = await capability.publish({ appletId: APPLET }, scope);
+    expect(outcome.status).toBe("failed");
+    const reason = outcome.status === "failed" ? outcome.reason : "";
+    expect(reason).toBe(
+      '"dist/server.js" is on the Computer but did not reach the Workspace: 1 sync operation failed at "dist/ui.html": unavailable: the Computer could not answer.',
+    );
+    expect(reason).not.toMatch(/applet build/);
+  });
+
+  test("publish still blames the build when the pull of the source root was clean", async () => {
+    const { host: capability } = host({
+      files: {},
+      synced: { status: "ok", detail: "" },
+    });
+    const outcome = await capability.publish({ appletId: APPLET }, scope);
+    expect(outcome.status === "failed" && outcome.reason).toMatch(
+      /applet build/,
+    );
+  });
+
   test("publish refuses a manifest whose hashes do not match the bytes", async () => {
     const { host: capability } = host({
       files: {

package/src/backend-applets.ts

@@ -58,6 +58,20 @@ export const APPLET_PUBLISH_EFFECT_PREFIX = "applets:publish-effect:";
  */
 export const APPLET_DIRECTORY_REVISION_SEEN_KEY = "applets:directory-revision";
 
+/**
+ * How the pre-publish pull of the Applet's source root went.
+ *
+ * `ok` and `skipped` mean the store now holds what the Computer holds. Anything
+ * else means the two may differ, and a `dist/` file the publish cannot find is
+ * then far more likely to be one the sync could not carry than one `applet
+ * build` never wrote.
+ */
+export interface AppletSourceSyncOutcomeV1 {
+  status: "ok" | "degraded" | "unavailable" | "refused" | "skipped";
+  /** What the sync said went wrong, empty when it had nothing to say. */
+  detail: string;
+}
+
 /** The three files `applet build` writes, read from the durable root. */
 export const APPLET_DIST_FILES_V1 = [
   "dist/server.js",
@@ -293,8 +307,12 @@ export interface AppletCapabilityHostOptionsV1 {
    * store is read as it stands — correct but possibly stale — and the Bot is
    * told so in the failure when the files are missing, rather than the publish
    * silently using old bytes.
+   *
+   * What it answers is how that pull went. A build that is on the Computer but
+   * did not reach the store is a different failure from a build that was never
+   * run, and the publish can only say which when it is told.
    */
-  syncSourceRootNow?(appletId: string): Promise<void>;
+  syncSourceRootNow?(appletId: string): Promise<AppletSourceSyncOutcomeV1>;
   composition: Pick<CompositionStore, "current" | "lastKnownGood" | "propose">;
   now?(): Date;
 }
@@ -594,11 +612,20 @@ export function createAppletCapabilityHostV1(
     appletId: string,
     file: string,
     maximum: number,
+    synced?: AppletSourceSyncOutcomeV1,
   ): Promise<{ text: string } | { failure: string }> {
     const outcome = await options.workspace.read(
       appletDistPathV1(options.userId, appletId, file),
     );
     if (outcome.status !== "ok") {
+      // A pull that did not finish is the likelier explanation than an
+      // unbuilt Applet, and telling the Bot to build again would send it
+      // round a loop that cannot end.
+      if (synced && synced.status !== "ok" && synced.status !== "skipped") {
+        return {
+          failure: `"${file}" is on the Computer but did not reach the Workspace: ${synced.detail || "the sync could not carry it"}`,
+        };
+      }
       return {
         failure: `"${file}" is ${outcome.status}: run \`applet build\` in applets/${appletId} on the Computer first`,
       };
@@ -731,12 +758,13 @@ 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?.(input.appletId);
+      const synced = await options.syncSourceRootNow?.(input.appletId);
 
       const server = await readFile(
         input.appletId,
         "dist/server.js",
         APPLET_MAX_SERVER_BYTES_V1,
+        synced,
       );
       if ("failure" in server) {
         return settle(failed(input.appletId, "unbuilt", server.failure));
@@ -745,6 +773,7 @@ export function createAppletCapabilityHostV1(
         input.appletId,
         "dist/ui.html",
         APPLET_MAX_UI_BYTES_V1,
+        synced,
       );
       if ("failure" in ui) {
         return settle(failed(input.appletId, "unbuilt", ui.failure));
@@ -753,6 +782,7 @@ export function createAppletCapabilityHostV1(
         input.appletId,
         "dist/manifest.json",
         APPLET_MAX_MANIFEST_BYTES_V1,
+        synced,
       );
       if ("failure" in manifestFile) {
         return settle(failed(input.appletId, "unbuilt", manifestFile.failure));

package/src/backend.ts

@@ -2492,7 +2492,9 @@ export class ShellBotBackendContribution {
               sessions: typeof active.mounted.runtime.root.sessions;
             };
             const computerIdentity = { userId: identity.userId };
-            if (!root.computers?.assignment(computerIdentity)) return;
+            if (!root.computers?.assignment(computerIdentity)) {
+              return { status: "skipped", detail: "" } as const;
+            }
             const session = root.sessions.get(active.sessionId);
             const started = session?.events.findLast(
               (event) => event.type === "step/start",
@@ -2503,7 +2505,7 @@ export class ShellBotBackendContribution {
               { botId: identity.botId },
               { signal: active.signal },
             );
-            await syncWorkspaceRootNowV1({
+            const summary = await syncWorkspaceRootNowV1({
               computer,
               sessions: root.sessions,
               sessionId: active.sessionId,
@@ -2514,6 +2516,7 @@ export class ShellBotBackendContribution {
               ),
               signal: active.signal,
             });
+            return { status: summary.status, detail: summary.detail };
           }
         : undefined,
       composition: {