@frockbot/plugin-computer 0.3.11 → 0.3.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-computer",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "private": false,
   "type": "module",
   "exports": {
@@ -29,25 +29,25 @@
   },
   "dependencies": {
     "@cordisjs/client": "0.8.2",
-    "@frockbot/client-core": "0.3.11",
-    "@frockbot/client-ui": "0.3.11",
-    "@frockbot/computer-core": "0.3.11",
-    "@frockbot/computer-host-runtime": "0.3.11",
-    "@frockbot/kernel-agent-loop": "0.3.11",
-    "@frockbot/kernel-contracts": "0.3.11",
-    "@frockbot/plugin-prompt": "0.3.11",
-    "@frockbot/plugin-shell": "0.3.11",
-    "@frockbot/plugin-tools": "0.3.11",
+    "@frockbot/client-core": "0.3.12",
+    "@frockbot/client-ui": "0.3.12",
+    "@frockbot/computer-core": "0.3.12",
+    "@frockbot/computer-host-runtime": "0.3.12",
+    "@frockbot/kernel-agent-loop": "0.3.12",
+    "@frockbot/kernel-contracts": "0.3.12",
+    "@frockbot/plugin-prompt": "0.3.12",
+    "@frockbot/plugin-shell": "0.3.12",
+    "@frockbot/plugin-tools": "0.3.12",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
-    "@frockbot/plugin-models": "0.3.11",
-    "@frockbot/plugin-testkit": "0.3.11",
+    "@frockbot/plugin-models": "0.3.12",
+    "@frockbot/plugin-testkit": "0.3.12",
     "@types/bun": "1.4.0",
     "@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

@@ -73,6 +73,7 @@ import {
   COMPUTER_SCREENSHOTS_ROOT_ID,
 } from "./roots.js";
 import {
+  createComputerCaptureCadenceV1,
   fileComputerScreenshotV1,
   type ComputerProjectionFileInvalidationV1,
   type ComputerProjectionFileKindV1,
@@ -142,6 +143,11 @@ export interface ComputerAgentPluginConfig {
   };
   /** Drops resident projection caches after this Turn's Workspace sync. */
   projectionFiles?: ComputerProjectionFileInvalidationV1;
+  /**
+   * The shortest gap between two mid-Turn progress captures. Tests set it;
+   * production takes `COMPUTER_PROGRESS_CAPTURE_INTERVAL_MS`.
+   */
+  progressCaptureIntervalMs?: number;
 }
 
 export const HUMAN_CONTROL_PROMPT_LINE =
@@ -564,6 +570,13 @@ export function createComputerAgentPlugin(
     // Agent loop knows it; a tool context does not, so it is caught where the
     // loop already announces it.
     let currentTurn = 1;
+    // One cadence per mounted plugin, which is one per Turn: a Turn's first
+    // Computer action always gets its capture, and the rest are debounced.
+    const progressCadence = createComputerCaptureCadenceV1(
+      config.progressCaptureIntervalMs === undefined
+        ? undefined
+        : { intervalMs: config.progressCaptureIntervalMs },
+    );
     const projectionWrites = new Set<ComputerProjectionFileKindV1>();
     const noteProjectionWrite = (kind: ComputerProjectionFileKindV1): void => {
       projectionWrites.add(kind);
@@ -676,6 +689,7 @@ export function createComputerAgentPlugin(
                 },
                 { signal: context.signal, effectId: context.effectId },
               );
+              await fileProgressCapture(computer, context.botId, context);
               return {
                 content: [text(result.stdout), text(result.stderr)]
                   .filter(Boolean)
@@ -1008,6 +1022,60 @@ export function createComputerAgentPlugin(
 
     let captureSequence = 0;
 
+    /**
+     * Files one capture of the desktop the Bot has just acted on, and tells
+     * the browser to read again.
+     *
+     * "Live while working" has two halves, and this is the one that works
+     * without a viewer session: the card that cannot open a stream still
+     * shows a picture of what the Bot did a second ago rather than what it
+     * did at the end of the last Turn. Debounced, best effort, and never the
+     * reason a tool call fails — the Bot's answer is the tool's result, and a
+     * photograph of the screen is a courtesy to the person watching.
+     */
+    const fileProgressCapture = async (
+      computer: ComputerHandle,
+      botId: string,
+      context: ToolExecutionContext,
+    ): Promise<void> => {
+      if (!writer || !computer.workspace || !computer.screenshot) return;
+      if (!progressCadence.admit(Date.now())) return;
+      const botKey = computerBotPathKeyV1(botId);
+      captureSequence += 1;
+      try {
+        await fileComputerScreenshotV1({
+          computer,
+          workspace: computer.workspace,
+          path: {
+            root: {
+              kind: "package-declared",
+              userId,
+              packageId: "computer",
+              rootId: COMPUTER_SCREENSHOTS_ROOT_ID,
+            },
+            path: `${botKey}/${writer.turnId}-${captureSequence}.png`,
+          },
+          writer: {
+            kind: "bot",
+            botId,
+            sessionId: writer.sessionId,
+            turnId: writer.turnId,
+            runId: writer.runId,
+          },
+          botKey,
+          effectId: `${context.effectId}:progress-screenshot`,
+        });
+      } catch {
+        // A desktop that refused a capture — human control, a Sprite that
+        // paused, a Computer with no screen — changes nothing the Bot did.
+        return;
+      }
+      noteProjectionWrite("screenshots");
+      // Flushed now rather than at Turn end: a capture nobody is told about
+      // is the delay this exists to remove.
+      invalidateProjectionWrites(botId);
+    };
+
     /**
      * Captures the Bot's own desktop into the Package-declared `screenshots`
      * root.
@@ -1096,6 +1164,11 @@ export function createComputerAgentPlugin(
                 effectId: context.effectId,
               });
               noteProjectionWrite("screenshots");
+              // The Bot just looked at its own screen; so should the person
+              // watching the card. Recording the admission keeps the very
+              // next Computer action from filing a near-identical capture.
+              progressCadence.admit(Date.now());
+              invalidateProjectionWrites(context.botId);
               const dimensions = pngDimensionsV1(filed.captured.bytes);
               const attachment: ToolAttachmentV1 = {
                 kind: "image",
@@ -1436,6 +1509,7 @@ export function createComputerAgentPlugin(
                 signal: context.signal,
                 effectId: context.effectId,
               });
+              await fileProgressCapture(computer, context.botId, context);
               return {
                 content: result.accessibilitySnapshot,
                 isError: false,
@@ -1463,7 +1537,12 @@ export function createComputerAgentPlugin(
       // A Turn's first step is where the Turn's sync state begins; a Turn that
       // never touches the Computer never syncs and never wakes one.
       ctx.on("agent/pre-step", async (agent, _inputs, turn, _step, next) => {
-        if (turn !== currentTurn) projectionWrites.clear();
+        if (turn !== currentTurn) {
+          projectionWrites.clear();
+          // Every Turn's first Computer action is worth a capture, however
+          // soon after the previous Turn's last one it happens.
+          progressCadence.reset();
+        }
         currentTurn = turn;
         turnSync.beginTurn(turn);
         if (controlPrompt?.loadedTurn() !== turn) {

package/src/capture-cadence.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import {
+  COMPUTER_PROGRESS_CAPTURE_INTERVAL_MS,
+  createComputerCaptureCadenceV1,
+} from "./capture.js";
+
+describe("the mid-Turn capture cadence", () => {
+  test("captures the first Computer action of a Turn immediately", () => {
+    const cadence = createComputerCaptureCadenceV1();
+    expect(cadence.admit(1_000)).toBe(true);
+  });
+
+  test("files at most one capture per interval however busy the Turn", () => {
+    const cadence = createComputerCaptureCadenceV1({ intervalMs: 2_000 });
+    expect(cadence.admit(0)).toBe(true);
+    // Twenty browser actions inside two seconds cost one screenshot.
+    for (let at = 1; at < 2_000; at += 100) {
+      expect(cadence.admit(at)).toBe(false);
+    }
+    expect(cadence.admit(2_000)).toBe(true);
+    expect(cadence.admit(2_001)).toBe(false);
+    expect(cadence.admit(4_000)).toBe(true);
+  });
+
+  test("a new Turn starts capturing again after a reset", () => {
+    const cadence = createComputerCaptureCadenceV1({ intervalMs: 2_000 });
+    expect(cadence.admit(0)).toBe(true);
+    expect(cadence.admit(10)).toBe(false);
+    cadence.reset();
+    expect(cadence.admit(20)).toBe(true);
+  });
+
+  test("a clock that jumps backwards does not stop captures", () => {
+    const cadence = createComputerCaptureCadenceV1({ intervalMs: 2_000 });
+    expect(cadence.admit(10_000)).toBe(true);
+    expect(cadence.admit(1_000)).toBe(true);
+  });
+
+  test("defaults to roughly two seconds", () => {
+    expect(COMPUTER_PROGRESS_CAPTURE_INTERVAL_MS).toBe(2_000);
+    const cadence = createComputerCaptureCadenceV1();
+    expect(cadence.admit(0)).toBe(true);
+    expect(cadence.admit(COMPUTER_PROGRESS_CAPTURE_INTERVAL_MS - 1)).toBe(
+      false,
+    );
+    expect(cadence.admit(COMPUTER_PROGRESS_CAPTURE_INTERVAL_MS)).toBe(true);
+  });
+});

package/src/capture.ts

@@ -14,6 +14,56 @@ import { COMPUTER_SCREENSHOT_RETENTION } from "./roots.js";
 
 export type ComputerProjectionFileKindV1 = "screenshots" | "doctor";
 
+/**
+ * The shortest gap between two progress captures of the same desktop.
+ *
+ * A Turn can run a dozen Computer actions a second, and each capture crosses
+ * a service binding to the Sprite and writes durable bytes. Two seconds is
+ * fast enough that the card looks like it is following the Bot and slow
+ * enough that a busy Turn does not spend itself photographing a screen.
+ */
+export const COMPUTER_PROGRESS_CAPTURE_INTERVAL_MS = 2_000;
+
+/**
+ * Decides whether the next Computer action gets a fresh capture filed for it.
+ *
+ * Turn-end captures do not ask: the last frame of a Turn is the one the card
+ * will show for as long as the Bot is idle, so it is always filed. Everything
+ * inside the Turn is progress, and progress is debounced.
+ */
+export interface ComputerCaptureCadenceV1 {
+  /** True at most once per interval; records the admission when it grants. */
+  admit(now: number): boolean;
+  /** Forgets the last admission, so the next call grants immediately. */
+  reset(): void;
+}
+
+export function createComputerCaptureCadenceV1(options?: {
+  intervalMs?: number;
+}): ComputerCaptureCadenceV1 {
+  const intervalMs =
+    options?.intervalMs ?? COMPUTER_PROGRESS_CAPTURE_INTERVAL_MS;
+  let lastAdmittedAt: number | undefined;
+  return {
+    admit(now: number): boolean {
+      // A clock that went backwards is not a licence to stop capturing; the
+      // gap is measured forwards only.
+      if (
+        lastAdmittedAt !== undefined &&
+        now >= lastAdmittedAt &&
+        now - lastAdmittedAt < intervalMs
+      ) {
+        return false;
+      }
+      lastAdmittedAt = now;
+      return true;
+    },
+    reset(): void {
+      lastAdmittedAt = undefined;
+    },
+  };
+}
+
 /** Invalidates files projected by one resident Bot Durable Object. */
 export interface ComputerProjectionFileInvalidationV1 {
   invalidate(botId: string, kind: ComputerProjectionFileKindV1): void;

package/src/client/ComputerCard.vue

@@ -1,7 +1,15 @@
 <script setup lang="ts">
 import { useRpc } from "@cordisjs/client";
 import { UiIcon } from "@frockbot/client-ui";
-import { computed, inject, ref } from "vue";
+import {
+  computed,
+  inject,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  watch,
+  watchEffect,
+} from "vue";
 import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
 import { computerKey, type ComputerState } from "../shared.ts";
 import { COMPUTER_COLD_PROVISION_EXPECTATION } from "../protocol.ts";
@@ -10,6 +18,12 @@ import {
   computerProgressFrame,
   computerProgressRunKind,
 } from "./progress.ts";
+import {
+  COMPUTER_SCREEN_STATUS_TICK_MS,
+  computerScreenModeV1,
+  computerScreenStatusLabelV1,
+} from "./live-preview.ts";
+import { viewerUrlForControlV1 } from "./viewer.ts";
 
 const computer = inject(computerKey) ?? useRpc<ComputerState>();
 const state = computed(() => computer.value);
@@ -89,6 +103,92 @@ const progressAriaLabel = computed(
   () => `${openingHeading.value}: ${progressPhaseLabel.value}`,
 );
 
+// ---------------------------------------------------------------------------
+// Live while working.
+//
+// The card draws the Bot's own screen region as it changes, in the same
+// view-only frame the full-screen viewer uses and on the same minted session
+// — no second token, no takeover lease, and no input reaching the desktop.
+// Rendering still wakes nothing: with no session minted the card stays on the
+// stored capture, which the Bot now files after every Computer action.
+// ---------------------------------------------------------------------------
+const screen = ref<HTMLElement>();
+const onScreen = ref(true);
+const documentVisible = ref(
+  typeof document === "undefined" || document.visibilityState === "visible",
+);
+const now = ref(Date.now());
+let statusTicker: ReturnType<typeof setInterval> | undefined;
+let observer: IntersectionObserver | undefined;
+/** When the Bot's last Turn stopped; the grace window is measured from it. */
+const turnEndedAt = ref<number | undefined>(undefined);
+const turnRunning = computed(() => Boolean(shell?.value.runningRunId));
+const screenMode = computed(() =>
+  computerScreenModeV1({
+    ...(state.value.viewerUrl ? { viewerUrl: state.value.viewerUrl } : {}),
+    phase: state.value.phase,
+    expanded: state.value.expanded,
+    turnRunning: turnRunning.value,
+    onScreen: onScreen.value,
+    documentVisible: documentVisible.value,
+    ...(turnEndedAt.value === undefined
+      ? {}
+      : { sinceTurnEndedMs: now.value - turnEndedAt.value }),
+  }),
+);
+const streaming = computed(() => screenMode.value === "stream");
+// The one client-visible input fence, set the same way the overlay sets it.
+// The card never asks for control, so this URL is always the view-only one.
+const previewSrc = computed(() =>
+  streaming.value && state.value.viewerUrl
+    ? viewerUrlForControlV1(state.value.viewerUrl, false)
+    : undefined,
+);
+const screenStatus = computed(() =>
+  computerScreenStatusLabelV1({
+    mode: screenMode.value,
+    ...(screenshot.value ? { capturedAt: screenshot.value.capturedAt } : {}),
+    now: now.value,
+  }),
+);
+
+watch(turnRunning, (running, previous) => {
+  if (previous && !running) turnEndedAt.value = Date.now();
+  if (running) turnEndedAt.value = undefined;
+});
+// Holding is what keeps the minted session alive while the card watches it;
+// releasing is what stops an idle Bot from paying for a stream nobody reads.
+watchEffect(() => {
+  state.value.holdLivePreview?.(streaming.value);
+});
+
+function readVisibility(): void {
+  documentVisible.value =
+    typeof document === "undefined" || document.visibilityState === "visible";
+}
+
+onMounted(() => {
+  document.addEventListener("visibilitychange", readVisibility);
+  statusTicker = setInterval(() => {
+    now.value = Date.now();
+  }, COMPUTER_SCREEN_STATUS_TICK_MS);
+  if (typeof IntersectionObserver === "undefined" || !screen.value) return;
+  observer = new IntersectionObserver(
+    (entries) => {
+      const entry = entries.at(-1);
+      if (entry) onScreen.value = entry.isIntersecting;
+    },
+    { threshold: 0.05 },
+  );
+  observer.observe(screen.value);
+});
+onBeforeUnmount(() => {
+  document.removeEventListener("visibilitychange", readVisibility);
+  if (statusTicker !== undefined) clearInterval(statusTicker);
+  observer?.disconnect();
+  state.value.holdLivePreview?.(false);
+});
+
 async function open(): Promise<void> {
   if (busy.value) return;
   busy.value = true;
@@ -105,14 +205,26 @@ async function open(): Promise<void> {
 <template>
   <section v-if="hasBot" class="computer-card">
     <button
+      ref="screen"
       type="button"
       class="computer-screen computer-screen-thumbnail"
+      :class="{ 'is-live': streaming }"
       :disabled="busy || unconfigured"
       aria-label="Open computer in full window"
       @click="open"
     >
+      <iframe
+        v-if="previewSrc && !opening"
+        class="computer-screen-preview"
+        :src="previewSrc"
+        title="Computer, live"
+        tabindex="-1"
+        aria-hidden="true"
+        sandbox="allow-same-origin allow-scripts"
+        referrerpolicy="no-referrer"
+      />
       <img
-        v-if="screenshot && !opening"
+        v-else-if="screenshot && !opening"
         :key="screenshot.contentHash"
         :src="screenshot.url"
         alt=""
@@ -157,5 +269,14 @@ async function open(): Promise<void> {
         </template>
       </span>
     </button>
+    <p
+      v-if="screenStatus"
+      class="computer-screen-status"
+      :class="{ 'is-live': streaming }"
+      aria-live="polite"
+    >
+      <span class="computer-screen-status-dot" aria-hidden="true" />
+      {{ screenStatus }}
+    </p>
   </section>
 </template>

package/src/client/application.test.ts

@@ -345,6 +345,34 @@ describe("hosted Computer provider", () => {
     mounted.dispose();
   });
 
+  test("a held card preview keeps the same session alive, and a hidden tab drops it", async () => {
+    const mounted = mountHostedProvider();
+    await flush();
+    await mounted.state.connect();
+    await flush();
+    // A minted session that nobody is watching is not renewed.
+    expect(mounted.runtime.count(VIEWER_REFRESH_INTERVAL_MS)).toBe(0);
+
+    mounted.state.holdLivePreview?.(true);
+    expect(mounted.runtime.count(VIEWER_REFRESH_INTERVAL_MS)).toBe(1);
+    mounted.runtime.tick(VIEWER_REFRESH_INTERVAL_MS);
+    await flush();
+    expect(postedTypes(mounted.calls)).toEqual(["connect", "refreshViewer"]);
+    // The card never expands and never asks for control to watch a Bot work.
+    expect(mounted.state.expanded).toBe(false);
+    expect(mounted.state.takingControl).toBe(false);
+
+    mounted.runtime.setVisible(false);
+    expect(mounted.runtime.count(VIEWER_REFRESH_INTERVAL_MS)).toBe(0);
+    mounted.runtime.setVisible(true);
+    await flush();
+    expect(mounted.runtime.count(VIEWER_REFRESH_INTERVAL_MS)).toBe(1);
+
+    mounted.state.holdLivePreview?.(false);
+    expect(mounted.runtime.count(VIEWER_REFRESH_INTERVAL_MS)).toBe(0);
+    mounted.dispose();
+  });
+
   test("an updating card click rejoins the update and lands on ready when it finishes", async () => {
     const mounted = mountHostedProvider();
     await flush();

package/src/client/application.ts

@@ -95,11 +95,19 @@ export function createComputerClientPlugin(
     let controlRequest: Promise<void> | undefined;
     /** Set by a release the backend refused; no heartbeat renews after it. */
     let controlAbandoned = false;
+    /**
+     * Whether a view-only card preview is watching the desktop right now.
+     *
+     * It is the card's declaration, not a second session: the heartbeat it
+     * keeps alive renews the same minted viewer the overlay would use.
+     */
+    let livePreviewHeld = false;
 
     const state = ref<ComputerState>({
       ...machine,
       connect: () => connect("connect-requested"),
       openViewer: () => openViewer(),
+      holdLivePreview: (held: boolean) => holdLivePreview(held),
       closeViewer: () => closeViewer(),
       takeControl: () => takeControl(),
       releaseControl: () => releaseControl(),
@@ -148,7 +156,11 @@ export function createComputerClientPlugin(
     }
 
     function syncViewerHeartbeat(): void {
-      if (!machine.expanded || !machine.viewerUrl) {
+      // A hidden tab watches nothing, so it renews nothing: the slot lapses
+      // and the Sprite stops paying for a stream no one is looking at.
+      const watching =
+        machine.expanded || (livePreviewHeld && runtime.isVisible());
+      if (!watching || !machine.viewerUrl) {
         stopViewerHeartbeat();
         return;
       }
@@ -333,6 +345,12 @@ export function createComputerClientPlugin(
       await connect("connect-requested");
     }
 
+    function holdLivePreview(held: boolean): void {
+      if (livePreviewHeld === held) return;
+      livePreviewHeld = held;
+      syncViewerHeartbeat();
+    }
+
     async function closeViewer(): Promise<void> {
       if (!machine.expanded) return;
       // A host with no Computer never had a viewer session to close.
@@ -431,6 +449,9 @@ export function createComputerClientPlugin(
         stopViewerHeartbeat();
         stopUpdateRejoin();
         controlAbandoned = false;
+        // The card remounts its preview against the newly selected Bot; a
+        // hold carried across would renew the previous Bot's session.
+        livePreviewHeld = false;
         machine = initialComputerMachineState();
         Object.assign(state.value, machine);
         watchStateChannel(selectedBotId);
@@ -443,6 +464,7 @@ export function createComputerClientPlugin(
     );
     const stopVisibility = runtime.onVisibilityChange(() => {
       syncProjectionPoll();
+      syncViewerHeartbeat();
       syncUpdateRejoin();
       const selectedBotId = shell.value.activeBotId;
       if (!selectedBotId || !runtime.isVisible()) return;

package/src/client/live-preview.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import {
+  COMPUTER_LIVE_PREVIEW_GRACE_MS,
+  computerScreenModeV1,
+  computerScreenStatusLabelV1,
+  computerSnapshotAgeLabelV1,
+  type ComputerScreenModeInputV1,
+} from "./live-preview.js";
+
+const cardSource = readFileSync(
+  new URL("./ComputerCard.vue", import.meta.url),
+  "utf8",
+);
+
+const watching: ComputerScreenModeInputV1 = {
+  viewerUrl: "https://sprite.invalid/vnc.html#view_only=1&path=websockify",
+  phase: "ready",
+  expanded: false,
+  turnRunning: true,
+  onScreen: true,
+  documentVisible: true,
+};
+
+describe("the card's live-vs-snapshot choice", () => {
+  test("streams the desktop while the Bot's Turn is running", () => {
+    expect(computerScreenModeV1(watching)).toBe("stream");
+  });
+
+  test("stays on the stored capture when no session has been minted", () => {
+    expect(computerScreenModeV1({ ...watching, viewerUrl: undefined })).toBe(
+      "snapshot",
+    );
+  });
+
+  test("a hidden tab holds no stream", () => {
+    expect(computerScreenModeV1({ ...watching, documentVisible: false })).toBe(
+      "snapshot",
+    );
+  });
+
+  test("a card scrolled off screen holds no stream", () => {
+    expect(computerScreenModeV1({ ...watching, onScreen: false })).toBe(
+      "snapshot",
+    );
+  });
+
+  test("the open full-screen viewer keeps the session warm off screen", () => {
+    expect(
+      computerScreenModeV1({
+        ...watching,
+        onScreen: false,
+        turnRunning: false,
+        expanded: true,
+      }),
+    ).toBe("stream");
+  });
+
+  test("an idle Bot with no Turn ever run shows the snapshot", () => {
+    expect(computerScreenModeV1({ ...watching, turnRunning: false })).toBe(
+      "snapshot",
+    );
+  });
+
+  test("a settled Turn keeps streaming through the grace window only", () => {
+    const settled = { ...watching, turnRunning: false };
+    expect(computerScreenModeV1({ ...settled, sinceTurnEndedMs: 1_000 })).toBe(
+      "stream",
+    );
+    expect(
+      computerScreenModeV1({
+        ...settled,
+        sinceTurnEndedMs: COMPUTER_LIVE_PREVIEW_GRACE_MS,
+      }),
+    ).toBe("snapshot");
+    expect(
+      computerScreenModeV1({
+        ...settled,
+        sinceTurnEndedMs: 1_000,
+        graceMs: 500,
+      }),
+    ).toBe("snapshot");
+  });
+
+  test("a host mid-operation draws its progress, not a frame", () => {
+    for (const phase of [
+      "provisioning",
+      "updating",
+      "disconnected",
+      "error",
+      "idle",
+      "unconfigured",
+    ] as const) {
+      expect(computerScreenModeV1({ ...watching, phase })).toBe("snapshot");
+    }
+    expect(computerScreenModeV1({ ...watching, phase: "human-control" })).toBe(
+      "stream",
+    );
+  });
+});
+
+describe("the status line under the screen", () => {
+  test("says Live while the stream is up", () => {
+    expect(computerScreenStatusLabelV1({ mode: "stream", now: 1_000 })).toBe(
+      "Live",
+    );
+  });
+
+  test("ages the snapshot in the User's units", () => {
+    const now = Date.parse("2026-09-04T00:01:00.000Z");
+    expect(
+      computerScreenStatusLabelV1({
+        mode: "snapshot",
+        capturedAt: "2026-09-04T00:00:48.000Z",
+        now,
+      }),
+    ).toBe("Snapshot · 12s ago");
+    expect(computerSnapshotAgeLabelV1(90_000)).toBe("1m ago");
+    expect(computerSnapshotAgeLabelV1(3 * 3_600_000)).toBe("3h ago");
+    expect(computerSnapshotAgeLabelV1(50 * 3_600_000)).toBe("2d ago");
+    expect(computerSnapshotAgeLabelV1(-5_000)).toBe("0s ago");
+  });
+
+  test("says nothing at all when there is no capture to age", () => {
+    expect(
+      computerScreenStatusLabelV1({ mode: "snapshot", now: 1_000 }),
+    ).toBeUndefined();
+    expect(
+      computerScreenStatusLabelV1({
+        mode: "snapshot",
+        capturedAt: "not a date",
+        now: 1_000,
+      }),
+    ).toBeUndefined();
+  });
+
+  test("uses no architecture words", () => {
+    for (const word of ["VNC", "noVNC", "iframe", "websocket", "session"]) {
+      expect(
+        computerScreenStatusLabelV1({
+          mode: "snapshot",
+          capturedAt: "2026-09-04T00:00:00.000Z",
+          now: Date.parse("2026-09-04T00:00:05.000Z"),
+        }),
+      ).not.toContain(word);
+    }
+  });
+});
+
+describe("the card's live frame", () => {
+  test("is view-only and takes no input", () => {
+    // The card never asks for control: the second argument is the input fence
+    // and it is hard-coded false, so the framed viewer is minted view-only.
+    expect(cardSource).toContain(
+      "viewerUrlForControlV1(state.value.viewerUrl, false)",
+    );
+    expect(cardSource).not.toContain("allow-pointer-lock");
+    expect(cardSource).toContain('tabindex="-1"');
+    expect(cardSource).toContain('aria-hidden="true"');
+  });
+
+  test("keeps click-to-take-control on the button behind it", () => {
+    expect(cardSource).toContain('aria-label="Open computer in full window"');
+    expect(cardSource).toContain('@click="open"');
+  });
+
+  test("releases the held session when the card leaves the screen", () => {
+    expect(cardSource).toContain("holdLivePreview?.(streaming.value)");
+    expect(cardSource).toContain("holdLivePreview?.(false)");
+    expect(cardSource).toContain("visibilitychange");
+    expect(cardSource).toContain("IntersectionObserver");
+  });
+});

package/src/client/live-preview.ts

@@ -0,0 +1,98 @@
+import type { ComputerPhase } from "../protocol.js";
+
+/**
+ * How long the card keeps streaming after the Bot's Turn settles.
+ *
+ * A Turn that ends is usually followed by another within seconds — a tool
+ * result the model answers, or a User reply. Dropping the VNC connection the
+ * instant a Turn stops would make the next one reconnect from black, which is
+ * the stall this feature exists to remove. The grace window is what stops an
+ * idle Bot from holding a connection all afternoon.
+ */
+export const COMPUTER_LIVE_PREVIEW_GRACE_MS = 15_000;
+
+/** How often the card re-reads its own status line while it is on screen. */
+export const COMPUTER_SCREEN_STATUS_TICK_MS = 1_000;
+
+/**
+ * The phases in which a minted viewer session addresses a desktop that is
+ * actually there. Provisioning and updating are hosts mid-operation, and the
+ * card draws their progress rather than a frame that cannot connect.
+ */
+const STREAMABLE_PHASES: readonly ComputerPhase[] = [
+  "ready",
+  "taking-control",
+  "human-control",
+];
+
+export type ComputerScreenModeV1 = "stream" | "snapshot";
+
+export interface ComputerScreenModeInputV1 {
+  /** The minted view-only viewer URL, absent until a session exists. */
+  viewerUrl?: string;
+  phase: ComputerPhase;
+  /** The full-screen viewer is open over the shell. */
+  expanded: boolean;
+  /** A Turn is executing for the selected Bot right now. */
+  turnRunning: boolean;
+  /** The card is mounted and inside the viewport. */
+  onScreen: boolean;
+  /** `document.visibilityState === "visible"`. */
+  documentVisible: boolean;
+  /**
+   * Milliseconds since the Bot's last Turn stopped running. Undefined where
+   * no Turn has run in this session, which is not a reason to stream.
+   */
+  sinceTurnEndedMs?: number;
+  graceMs?: number;
+}
+
+/**
+ * Whether the card draws the Bot's desktop live or the last stored capture.
+ *
+ * The rule is one sentence: stream a desktop that exists, to a card someone
+ * is actually looking at, while the Bot is working or has just stopped. Every
+ * other answer is the snapshot, which costs nothing to hold.
+ */
+export function computerScreenModeV1(
+  input: ComputerScreenModeInputV1,
+): ComputerScreenModeV1 {
+  if (!input.viewerUrl) return "snapshot";
+  if (!input.documentVisible) return "snapshot";
+  if (!input.onScreen && !input.expanded) return "snapshot";
+  if (!STREAMABLE_PHASES.includes(input.phase)) return "snapshot";
+  if (input.expanded || input.turnRunning) return "stream";
+  const grace = input.graceMs ?? COMPUTER_LIVE_PREVIEW_GRACE_MS;
+  const since = input.sinceTurnEndedMs;
+  return since !== undefined && since < grace ? "stream" : "snapshot";
+}
+
+/** A whole-unit age, coarse enough that it does not redraw every frame. */
+export function computerSnapshotAgeLabelV1(ageMs: number): string {
+  const seconds = Math.max(0, Math.floor(ageMs / 1_000));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+/**
+ * The one line under the screen, in the User's words.
+ *
+ * "Live" and "Snapshot · 12s ago" are the whole vocabulary: the User asked
+ * whether they are watching the Bot or a photograph of it, and no answer that
+ * names a transport or a session answers that question.
+ */
+export function computerScreenStatusLabelV1(input: {
+  mode: ComputerScreenModeV1;
+  capturedAt?: string;
+  now: number;
+}): string | undefined {
+  if (input.mode === "stream") return "Live";
+  if (!input.capturedAt) return undefined;
+  const capturedAt = Date.parse(input.capturedAt);
+  if (!Number.isFinite(capturedAt)) return undefined;
+  return `Snapshot · ${computerSnapshotAgeLabelV1(input.now - capturedAt)}`;
+}

package/src/client/styles.css

@@ -97,6 +97,63 @@ button.computer-screen {
   pointer-events: auto;
 }
 
+/*
+ * The card's live frame. It is inert by inheritance: `.computer-screen iframe`
+ * already takes no pointer events, so a click lands on the button behind it and
+ * opens the full-screen viewer exactly as a click on the stored capture did.
+ */
+.computer-screen-preview {
+  display: block;
+}
+
+.computer-screen-thumbnail.is-live {
+  border-color: var(--frock-computer-accent);
+}
+
+.computer-screen-status {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+  margin: 6px 0 0;
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-xs);
+  line-height: 1.4;
+}
+
+.computer-screen-status-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: currentColor;
+  opacity: 0.5;
+}
+
+.computer-screen-status.is-live {
+  color: var(--frock-computer-accent-text);
+}
+
+.computer-screen-status.is-live .computer-screen-status-dot {
+  background: var(--frock-computer-accent);
+  opacity: 1;
+  animation: computer-live-pulse 2s ease-in-out infinite;
+}
+
+@keyframes computer-live-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.35;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .computer-screen-status.is-live .computer-screen-status-dot {
+    animation: none;
+  }
+}
+
 .human-control .computer-screen {
   border-color: var(--frock-computer-accent);
   box-shadow: 0 0 0 1px var(--frock-computer-focus);

package/src/screenshot.test.ts

@@ -294,7 +294,9 @@ describe("computer_screenshot", () => {
 
     await harness.root.serial("agent/turn-stopping", agent as never, 1);
 
-    expect(workspace.writes).toHaveLength(1);
+    // One capture for the action the Bot just took, so the card can show it
+    // working, and one final frame at Turn end.
+    expect(workspace.writes).toHaveLength(2);
     expect(workspace.writes[0]?.writer).toEqual({
       kind: "bot",
       botId: "bot-1",
@@ -302,7 +304,41 @@ describe("computer_screenshot", () => {
       turnId: "run-9",
       runId: "run-9",
     });
-    expect(invalidations).toEqual(["bot-1:screenshots"]);
+    // The mid-Turn capture is announced as soon as it is filed; waiting for
+    // Turn end is the delay the live card exists to remove.
+    expect(invalidations).toEqual(["bot-1:screenshots", "bot-1:screenshots"]);
+    await harness.dispose();
+  });
+
+  test("a busy Turn files at most one progress capture per interval", async () => {
+    const workspace = new FakeWorkspace();
+    const harness = await mount(
+      providerWith(workspace, () =>
+        Promise.resolve({
+          bytes: png(1280, 720),
+          mediaType: "image/png" as const,
+          display: ":100",
+          capturedAt: "2026-09-03T00:00:10.000Z",
+        }),
+      ),
+      true,
+    );
+    const session = harness.root.sessions.create("session-1");
+    const agent = { botId: "bot-1", session };
+    await harness.root.waterfall(
+      "agent/pre-step",
+      agent as never,
+      [],
+      1,
+      1,
+      () => Promise.resolve({ kind: "enter" as const, inputs: [] }),
+    );
+    for (let call = 0; call < 5; call += 1) {
+      await executeTool(harness, "computer_exec", { command: "pwd" });
+    }
+
+    // Five shell commands inside the debounce window, one photograph.
+    expect(workspace.writes).toHaveLength(1);
     await harness.dispose();
   });
 
@@ -332,7 +368,9 @@ describe("computer_screenshot", () => {
     await expect(
       harness.root.serial("agent/turn-stopping", agent as never, 1),
     ).resolves.toBeUndefined();
-    expect(captures).toBe(1);
+    // Both the progress capture and the final frame are refused, and neither
+    // refusal reaches the Bot's answer or the Turn's outcome.
+    expect(captures).toBe(2);
     expect(workspace.writes).toHaveLength(0);
     await harness.dispose();
   });

package/src/shared.ts

@@ -45,6 +45,17 @@ export interface ComputerState {
   connect(): Promise<void>;
   /** Explicit User open. An idle Computer may wake; rendering never does. */
   openViewer(): Promise<void>;
+  /**
+   * Declares that a view-only card preview is on screen.
+   *
+   * Held, the one minted viewer session is kept alive by the same heartbeat
+   * the full-screen viewer uses, so a card watching a working Bot does not
+   * lose the desktop to session expiry. Releasing it lets the session lapse,
+   * which is what stops an idle Bot from holding a VNC connection. It mints
+   * nothing and wakes nothing: a Computer with no session stays on the
+   * stored capture (P1).
+   */
+  holdLivePreview?(held: boolean): void;
   /** Closes the viewer, releasing human control before it disappears. */
   closeViewer(): Promise<void>;
   takeControl(): Promise<void>;

package/tsconfig.json

@@ -5,9 +5,8 @@
     "moduleResolution": "Bundler",
     "allowImportingTsExtensions": true,
     "resolveJsonModule": true,
-    "baseUrl": ".",
     "paths": {
-      "@cordisjs/client": ["src/client/cordis-client-shim.d.ts"]
+      "@cordisjs/client": ["./src/client/cordis-client-shim.d.ts"]
     },
     "strict": true,
     "noEmit": true,