@opengeni/react 0.11.0 → 0.13.0

package/src/hooks/use-sandbox-git.ts

@@ -1,4 +1,9 @@
-import type { GitFileDiff, SessionEvent } from "@opengeni/sdk";
+import type {
+  GitFileDiff,
+  SessionEvent,
+  WorkspaceCaptureManifest,
+  WorkspaceCaptureRepo,
+} from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
 
@@ -12,6 +17,12 @@ export type UseSandboxGitOptions = ClientOverride & {
   staged?: boolean | undefined;
   /** Hold off the initial fetch. Default true. */
   enabled?: boolean | undefined;
+  /** Lease liveness ("warm" | "draining" | "cold"). When NOT warm, the diff is
+   *  served from the capture (cold/offline) instead of a live `gitDiff` RPC. */
+  liveness?: string | undefined;
+  /** The latest turn-end capture (from `useWorkspaceCapture`). Supplies the cold
+   *  diff for this repo. A warm box always wins (live `gitDiff` unchanged). */
+  capture?: WorkspaceCaptureManifest | null | undefined;
 };
 
 export type UseSandboxGitResult = {
@@ -24,16 +35,100 @@ export type UseSandboxGitResult = {
   ahead: number;
   behind: number;
   refresh: () => Promise<void>;
+  /** Which source the diff is served from: the live box or the turn-end capture. */
+  source: "live" | "capture" | null;
+  /** When the served capture was taken (ISO), when `source === "capture"`. */
+  capturedAt: string | null;
   loading: boolean;
   error: Error | null;
 };
 
+/** Normalize a repo root for matching ("" and "." both mean the workspace root). */
+function normalizeRoot(root: string): string {
+  return root === "." ? "" : root;
+}
+
+/** Find the capture repo matching `repoPath` (default workspace root). */
+function repoForPath(
+  manifest: WorkspaceCaptureManifest,
+  repoPath: string,
+): WorkspaceCaptureRepo | null {
+  const want = normalizeRoot(repoPath);
+  const exact = manifest.repos.find((r) => normalizeRoot(r.root) === want);
+  if (exact) return exact;
+  // Root-scoped hook against a single-repo capture whose root isn't literally "":
+  // fall back to the sole repo so the common single-repo case just works.
+  if (want === "" && manifest.repos.length === 1) return manifest.repos[0] ?? null;
+  return null;
+}
+
+/** Full diff equality for identity preservation. Hunk count/count summaries are
+ *  not sufficient: an edit can replace text without changing either shape. */
+function sameFileDiff(a: GitFileDiff, b: GitFileDiff): boolean {
+  if (
+    a.path !== b.path ||
+    a.oldPath !== b.oldPath ||
+    a.status !== b.status ||
+    a.isBinary !== b.isBinary ||
+    a.isImage !== b.isImage ||
+    a.additions !== b.additions ||
+    a.deletions !== b.deletions ||
+    a.truncated !== b.truncated ||
+    a.hunks.length !== b.hunks.length
+  )
+    return false;
+
+  return a.hunks.every((hunk, hunkIndex) => {
+    const other = b.hunks[hunkIndex];
+    if (
+      !other ||
+      hunk.oldStart !== other.oldStart ||
+      hunk.oldLines !== other.oldLines ||
+      hunk.newStart !== other.newStart ||
+      hunk.newLines !== other.newLines ||
+      hunk.header !== other.header ||
+      hunk.lines.length !== other.lines.length
+    )
+      return false;
+    return hunk.lines.every((line, lineIndex) => {
+      const otherLine = other.lines[lineIndex];
+      return (
+        otherLine !== undefined &&
+        line.type === otherLine.type &&
+        line.oldNo === otherLine.oldNo &&
+        line.newNo === otherLine.newNo &&
+        line.text === otherLine.text
+      );
+    });
+  });
+}
+
+/** Merge a freshly-served diff over the current one, preserving the identity of
+ *  genuinely unchanged per-file entries so a cold→warm reconcile does NOT
+ *  remount unchanged file sections — no-flicker (§12-D1). */
+function mergeDiffs(current: GitFileDiff[], next: GitFileDiff[]): GitFileDiff[] {
+  if (current.length === 0) return next;
+  const byPath = new Map(current.map((d) => [d.path, d] as const));
+  let changed = current.length !== next.length;
+  const merged = next.map((file, index) => {
+    const existing = byPath.get(file.path);
+    if (existing && sameFileDiff(existing, file)) {
+      if (current[index] !== existing) changed = true;
+      return existing;
+    }
+    changed = true;
+    return file;
+  });
+  return changed ? merged : current;
+}
+
 /**
  * Project the Git service into the Pierre diff data contract: structured
  * `GitFileDiff[]` (per-file hunks with per-line old/new numbers, rename
- * detection, binary flag, add/del counts) plus branch + ahead/behind. The
- * `git diff` runs in-box (API-direct) and the hunks come back inline. Refreshes
- * on `git.changed`.
+ * detection, binary flag, add/del counts) plus branch + ahead/behind. When the
+ * box is warm the `git diff` runs in-box (API-direct); when it is cold/offline the
+ * diff is served from the turn-end capture instead (dossier §10.4). Refreshes on
+ * `git.changed`; reconciles live in place on the cold→warm transition.
  */
 export function useSandboxGit(
   sessionId: string | null | undefined,
@@ -43,50 +138,121 @@ export function useSandboxGit(
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const repoPath = options.repoPath ?? "";
   const staged = options.staged ?? false;
+  const capture = options.capture ?? null;
+  const isLive = options.liveness === "warm" || options.liveness === "draining";
 
   const [diff, setDiff] = useState<GitFileDiff[]>([]);
   const [branch, setBranch] = useState<string | null>(null);
   const [isRepo, setIsRepo] = useState(false);
   const [ahead, setAhead] = useState(0);
   const [behind, setBehind] = useState(0);
+  const [source, setSource] = useState<"live" | "capture" | null>(null);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
+  // Live requests and event cursors are identity-scoped. The refs deliberately
+  // survive renders, so they must be fenced/reset when that identity changes.
+  const refreshGenerationRef = useRef(0);
+  const lastChangeRef = useRef(0);
 
   const refresh = useCallback(async () => {
     if (!sessionId) return;
+    const generation = (refreshGenerationRef.current += 1);
     setLoading(true);
     setError(null);
     try {
       const status = await client.gitStatus(workspaceId, sessionId, { path: repoPath });
+      if (refreshGenerationRef.current !== generation) return;
       setIsRepo(status.isRepo);
       setBranch(status.head);
       setAhead(status.ahead);
       setBehind(status.behind);
       if (!status.isRepo) {
         setDiff([]);
+        setSource("live");
         return;
       }
       const result = await client.gitDiff(workspaceId, sessionId, { path: repoPath, staged });
-      setDiff(result.files);
+      if (refreshGenerationRef.current !== generation) return;
+      // Merge in place so the cold→warm swap keeps unchanged file sections mounted.
+      setDiff((prev) => mergeDiffs(prev, result.files));
+      setSource("live");
     } catch (cause) {
+      if (refreshGenerationRef.current !== generation) return;
       setError(cause instanceof Error ? cause : new Error(String(cause)));
     } finally {
-      setLoading(false);
+      if (refreshGenerationRef.current === generation) setLoading(false);
     }
   }, [client, workspaceId, sessionId, repoPath, staged]);
 
+  // Serve the diff from a capture (the cold/offline source). `staged` has no
+  // meaning here: the capture records the combined turn-end change surface vs HEAD.
+  const seedFromCapture = useCallback(
+    (manifest: WorkspaceCaptureManifest) => {
+      const repo = repoForPath(manifest, repoPath);
+      if (!repo) {
+        setIsRepo(false);
+        setBranch(null);
+        setAhead(0);
+        setBehind(0);
+        setDiff((prev) => (prev.length === 0 ? prev : []));
+        setSource("capture");
+        return;
+      }
+      setIsRepo(true);
+      setBranch(repo.head);
+      setAhead(repo.ahead);
+      setBehind(repo.behind);
+      setDiff((prev) => mergeDiffs(prev, repo.diff));
+      setSource("capture");
+      setError(null);
+    },
+    [repoPath],
+  );
+
+  // Source selection on mount / liveness / capture-revision change. Key on the
+  // capture REVISION (a primitive), not the manifest object, so a fresh object per
+  // render can't spin the effect; the latest manifest is read from a ref.
+  const captureRef = useRef<WorkspaceCaptureManifest | null>(capture);
+  captureRef.current = capture;
+  const captureRevision = capture?.revision ?? null;
+  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${repoPath}\u0000${staged}`;
+  const previousIdentityRef = useRef(identityKey);
   useEffect(() => {
-    if (!enabled) {
+    // A liveness/capture source change supersedes any older live request. Only a
+    // true data-identity change clears rendered state and the event high-water mark.
+    refreshGenerationRef.current += 1;
+    const identityChanged = previousIdentityRef.current !== identityKey;
+    previousIdentityRef.current = identityKey;
+    if (identityChanged || !enabled) {
+      lastChangeRef.current = 0;
       setDiff([]);
       setIsRepo(false);
       setBranch(null);
+      setAhead(0);
+      setBehind(0);
+      setSource(null);
+      setLoading(false);
+      setError(null);
+    }
+    if (!enabled) {
       return;
     }
-    void refresh();
-  }, [enabled, refresh]);
+    if (isLive) {
+      void refresh();
+    } else if (captureRevision !== null && captureRef.current) {
+      seedFromCapture(captureRef.current);
+    } else {
+      void refresh();
+    }
+    return () => {
+      refreshGenerationRef.current += 1;
+    };
+  }, [enabled, isLive, captureRevision, identityKey, refresh, seedFromCapture]);
 
+  // git.changed → re-fetch the LIVE diff. A git.changed only originates from a
+  // live box, so this both keeps warm sessions fresh and folds a cold box that
+  // just came up (unchanged from the pre-capture behavior).
   const events = options.events;
-  const lastChangeRef = useRef(0);
   useEffect(() => {
     if (!enabled || !events) return;
     let latest = lastChangeRef.current;
@@ -101,5 +267,16 @@ export function useSandboxGit(
     }
   }, [enabled, events, refresh]);
 
-  return { diff, branch, isRepo, ahead, behind, refresh, loading, error };
+  return {
+    diff,
+    branch,
+    isRepo,
+    ahead,
+    behind,
+    refresh,
+    source,
+    capturedAt: source === "capture" ? (capture?.capturedAt ?? null) : null,
+    loading,
+    error,
+  };
 }

package/src/hooks/use-sandbox-terminal.ts

@@ -108,7 +108,9 @@ export function useSandboxTerminal(
       .then((res) => {
         if (cancelled) {
           // Raced past unmount — close the orphan we just opened.
-          void client.terminalPtyClose(workspaceId, sessionId, { ptyId: res.ptyId }).catch(() => {});
+          void client
+            .terminalPtyClose(workspaceId, sessionId, { ptyId: res.ptyId })
+            .catch(() => {});
           return;
         }
         openedId = res.ptyId;
@@ -194,19 +196,21 @@ export function useSandboxTerminal(
   const write = useMemo(() => {
     if (!activePtyId || !canWrite || !sessionId) return null;
     return (data: string) => {
-      void client.terminalPtyWrite(workspaceId, sessionId, { ptyId: activePtyId, data }).catch((cause) => {
-        // The PTY exec-session was lost on the live box (409/404 — the box rolled
-        // over since the open). Self-heal: drop the stale id and re-open a fresh
-        // PTY against the current box rather than silently swallowing keystrokes.
-        if (
-          cause instanceof OpenGeniApiError &&
-          (cause.status === 409 || cause.status === 404) &&
-          activePtyId === openedPtyId
-        ) {
-          setOpenedPtyId(null);
-          setReopenNonce((n) => n + 1);
-        }
-      });
+      void client
+        .terminalPtyWrite(workspaceId, sessionId, { ptyId: activePtyId, data })
+        .catch((cause) => {
+          // The PTY exec-session was lost on the live box (409/404 — the box rolled
+          // over since the open). Self-heal: drop the stale id and re-open a fresh
+          // PTY against the current box rather than silently swallowing keystrokes.
+          if (
+            cause instanceof OpenGeniApiError &&
+            (cause.status === 409 || cause.status === 404) &&
+            activePtyId === openedPtyId
+          ) {
+            setOpenedPtyId(null);
+            setReopenNonce((n) => n + 1);
+          }
+        });
     };
   }, [client, workspaceId, sessionId, activePtyId, canWrite, openedPtyId]);
 

package/src/hooks/use-scheduled-tasks.ts

@@ -24,6 +24,14 @@ export function useScheduledTasks(options: UseScheduledTasksOptions = {}): UseSc
     async () => await client.listScheduledTasks(workspaceId, limit !== undefined ? { limit } : {}),
     [client, workspaceId, limit],
   );
-  const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled: options.enabled });
-  return { tasks: state.data ?? [], loading: state.loading, error: state.error, refresh: state.refresh };
+  const state = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  return {
+    tasks: state.data ?? [],
+    loading: state.loading,
+    error: state.error,
+    refresh: state.refresh,
+  };
 }

package/src/hooks/use-session-capabilities.ts

@@ -8,7 +8,21 @@ import {
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
 
-export type SessionCapabilitiesState = "idle" | "negotiating" | "ready" | "cold" | "error";
+// "on-demand" is the boxless-benign resting state: the lease is cold and NOTHING
+// asked to warm a box (no viewer/consent action, no files-tab warm). Under lazy
+// provisioning a chat-only turn never creates a box, so this is the correct calm
+// terminal state — NOT an error. It is distinct from "cold", which now means "a
+// warm-up is genuinely in flight" (a viewer attach was requested) and therefore
+// still polls with a patience deadline. A box appears on demand when the agent
+// first runs a sandbox tool; the workbench observes `sandbox.provision` and
+// renegotiates to pick up the freshly-warm box.
+export type SessionCapabilitiesState =
+  | "idle"
+  | "negotiating"
+  | "ready"
+  | "cold"
+  | "on-demand"
+  | "error";
 
 export type UseSessionCapabilitiesOptions = ClientOverride & {
   /**
@@ -35,15 +49,18 @@ export type UseSessionCapabilitiesOptions = ClientOverride & {
    */
   attachTerminal?: boolean | undefined;
   /**
-   * Whether to acquire a viewer holder purely to KEEP THE BOX WARM while the
-   * structured Files surface is open. Shares the SAME viewer attach as the
-   * desktop/terminal (one warm box, one holder) and — like the terminal — needs
-   * NO un-redacted acknowledgment: listing/reading/writing files is the ordinary
-   * Channel-A control plane, not the pixel plane. Default false: the Files tab
-   * negotiates read-only and each op pays the cold-box resume (~5s). When true,
-   * the holder warms the box once and heartbeats it, so subsequent fs ops are
-   * ~100ms instead of re-resuming the box on every list/write. It folds NO live
-   * URL (files ride the stateless HTTP plane) — it only refcounts liveness.
+   * Whether to acquire a viewer holder to warm the box for a FILE WRITE — the
+   * wake-on-edit INTENT (a first keystroke in the editor), NOT passive browsing.
+   * Shares the SAME viewer attach as the desktop/terminal (one warm box, one
+   * holder) and — like the terminal — needs NO un-redacted acknowledgment:
+   * reading/writing files is the ordinary Channel-A control plane, not the pixel
+   * plane. It folds NO live URL (files ride the stateless HTTP plane) — it only
+   * refcounts liveness. Unlike desktop/terminal it warms even a COLD box: an edit
+   * legitimately cold-creates (that IS the wake), so the write lands ~100ms warm
+   * instead of paying the ~5s cold resume. Default false. IMPORTANT: merely
+   * opening/reading the Files tab must NOT set this — browsing capture-served
+   * trees/diffs needs no box, and warming one on a cold glance burns box-hours to
+   * serve reads the capture already answers for free.
    */
   attachFiles?: boolean | undefined;
   /** Hold off negotiating (e.g. the workbench panel is collapsed). Default true. */
@@ -103,7 +120,9 @@ function desktopAttachable(cell: SessionCapabilities["DesktopStream"]): boolean
 function terminalAttachable(cell: SessionCapabilities["Terminal"]): boolean {
   if (cell.transport === null) {
     // No terminal at all unless the only blocker is a transient cold state.
-    return cell.reason === "lease_cold" || cell.reason === "not_provisioned" || cell.reason === null;
+    return (
+      cell.reason === "lease_cold" || cell.reason === "not_provisioned" || cell.reason === null
+    );
   }
   // Already pty-ws (warm) is fine to (re)attach; sse-events is the cold state the
   // attach upgrades. Either way it's attachable.
@@ -147,7 +166,9 @@ export function useSessionCapabilities(
   const [capabilities, setCapabilities] = useState<SessionCapabilities | null>(null);
   const [state, setState] = useState<SessionCapabilitiesState>("idle");
   const [error, setError] = useState<Error | null>(null);
-  const [acknowledgmentRequired, setAcknowledgmentRequired] = useState<"unredacted" | "shared" | null>(null);
+  const [acknowledgmentRequired, setAcknowledgmentRequired] = useState<
+    "unredacted" | "shared" | null
+  >(null);
   const [viewerCapReached, setViewerCapReached] = useState(false);
   const [viewerId, setViewerId] = useState<string | null>(null);
   // Bumped to force a fresh negotiation cycle.
@@ -191,7 +212,8 @@ export function useSessionCapabilities(
 
     const startHeartbeat = (caps: SessionCapabilities) => {
       if (!localViewerId || heartbeatTimer !== null) return;
-      const intervalMs = caps.viewerHeartbeatIntervalMs > 0 ? caps.viewerHeartbeatIntervalMs : 30_000;
+      const intervalMs =
+        caps.viewerHeartbeatIntervalMs > 0 ? caps.viewerHeartbeatIntervalMs : 30_000;
       heartbeatTimer = setInterval(() => {
         if (cancelled || !localViewerId) return;
         void client
@@ -205,7 +227,10 @@ export function useSessionCapabilities(
           })
           .catch((cause) => {
             if (cancelled) return;
-            if (cause instanceof OpenGeniApiError && (cause.status === 409 || cause.status === 410)) {
+            if (
+              cause instanceof OpenGeniApiError &&
+              (cause.status === 409 || cause.status === 410)
+            ) {
               renegotiate();
             }
           });
@@ -267,9 +292,14 @@ export function useSessionCapabilities(
         // mint the URLs. Only a genuinely-unsupported reason suppresses the attach.
         const wantDesktopAttach = attachDesktop && desktopAttachable(caps.DesktopStream);
         const wantTerminalAttach = attachTerminal && terminalAttachable(caps.Terminal);
-        // The Files surface warms the box for fast Channel-A ops. It folds no live
-        // URL (files are stateless HTTP) — the attach is purely a liveness refcount,
-        // so it's wanted whenever the FileSystem capability is advertised at all.
+        // The Files attach warms the box for a file WRITE (wake-on-edit intent). It
+        // folds no live URL (files are stateless HTTP) — the attach is purely a
+        // liveness refcount. Unlike the previous "keep the box warm while the Files
+        // tab is on screen" wiring, this fires on genuine EDIT intent only, so it
+        // legitimately cold-CREATES: an edit is the wake, and the caller (the dock)
+        // never sets it for passive browsing. Gate solely on the FileSystem cap
+        // being advertised; liveness (cold included) does not suppress it — POST
+        // /viewers warms a cold box exactly as it does for a desktop/terminal engage.
         const wantFilesAttach = attachFiles && caps.FileSystem.available;
         if (wantDesktopAttach || wantTerminalAttach || wantFilesAttach) {
           try {
@@ -277,7 +307,9 @@ export function useSessionCapabilities(
             // un-redacted pixel plane (which carries the consent gate); a
             // terminal-only attach (`desktop:false`) warms the box + mints the
             // pty-ws terminal cell WITHOUT tripping the desktop consent 409.
-            const holder = await client.attachViewer(workspaceId, sessionId, { desktop: wantDesktopAttach });
+            const holder = await client.attachViewer(workspaceId, sessionId, {
+              desktop: wantDesktopAttach,
+            });
             if (cancelled) return;
             localViewerId = holder.viewerId;
             viewerIdRef.current = holder.viewerId;
@@ -348,12 +380,26 @@ export function useSessionCapabilities(
           }
         }
 
+        // Whether ANYTHING asked to warm a box this negotiation. Only then is a
+        // cold lease "warming in flight" — worth polling, and worth surfacing a
+        // stall as an error. With no warm-up requested a cold lease is the benign
+        // boxless resting state (below), never an error.
+        const warmUpRequested = wantDesktopAttach || wantTerminalAttach || wantFilesAttach;
         if (caps.liveness === "warm" || caps.liveness === "draining" || localViewerId) {
           setState("ready");
           startHeartbeat(caps);
-        } else {
+        } else if (warmUpRequested) {
+          // A warm-up is genuinely in flight (a viewer attach was requested) but the
+          // box isn't warm yet — poll until it warms, with the patience deadline so a
+          // real stall surfaces as an error.
           setState("cold");
           pollUntilWarm();
+        } else {
+          // Boxless and nobody asked for a box: rest in the benign on-demand state.
+          // NO poll, NO deadline, NO false "sandbox offline". The box is created on
+          // demand when the agent first runs a sandbox tool; the workbench watches
+          // for `sandbox.provision` and renegotiates to pick the warm box back up.
+          setState("on-demand");
         }
       } catch (cause) {
         if (cancelled) return;
@@ -378,7 +424,18 @@ export function useSessionCapabilities(
       }
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [client, workspaceId, sessionId, enabled, attachDesktop, attachTerminal, attachFiles, warmingPollMs, warmingDeadlineMs, nonce]);
+  }, [
+    client,
+    workspaceId,
+    sessionId,
+    enabled,
+    attachDesktop,
+    attachTerminal,
+    attachFiles,
+    warmingPollMs,
+    warmingDeadlineMs,
+    nonce,
+  ]);
 
   // ── Fold stream.url.rotated from the live event log (no round trip) ──────────
   const events = options.events;

package/src/hooks/use-session-control.ts

@@ -6,9 +6,9 @@ import { useMutationRunner } from "./internal";
 export type UseSessionControlOptions = ClientOverride;
 
 export type UseSessionControlResult = {
-  /** Interrupt the running turn (the explicit alternative to queueing). */
-  interrupt: (reason?: string) => Promise<SessionEvent | null>;
-  interrupting: boolean;
+  pause: (reason?: string) => Promise<SessionEvent | null>;
+  resume: (reason?: string) => Promise<SessionEvent | null>;
+  controlling: boolean;
   /** Approve a pending `requires_action` approval. */
   approve: (approvalId: string, message?: string) => Promise<SessionEvent | null>;
   /** Reject a pending `requires_action` approval. */
@@ -20,7 +20,7 @@ export type UseSessionControlResult = {
 };
 
 /**
- * Session control events: interrupt and approval decisions. Pair with
+ * Session pause/resume and approval decisions. Pair with
  * `useSessionEvents` (for `session.requiresAction` payloads carrying the
  * `approvalId`) to render an approval bar.
  */
@@ -29,33 +29,60 @@ export function useSessionControl(
   options: UseSessionControlOptions = {},
 ): UseSessionControlResult {
   const { client, workspaceId } = useOpenGeni(options);
-  const interruptMutation = useMutationRunner();
-  const approvalMutation = useMutationRunner();
+  const {
+    run: runControl,
+    mutating: controlling,
+    mutationError: controlError,
+    clearMutationError: clearControlError,
+  } = useMutationRunner();
+  const {
+    run: runApproval,
+    mutating: responding,
+    mutationError: approvalError,
+    clearMutationError: clearApprovalError,
+  } = useMutationRunner();
 
-  const interrupt = useCallback(
+  const pause = useCallback(
     async (reason?: string): Promise<SessionEvent | null> => {
       if (!sessionId) {
         return null;
       }
-      return await interruptMutation.run(() =>
-        client.interrupt(workspaceId, sessionId, reason !== undefined ? { reason } : {}));
+      return await runControl(() =>
+        client.pauseSession(workspaceId, sessionId, reason !== undefined ? { reason } : {}),
+      );
     },
-    [client, workspaceId, sessionId, interruptMutation.run],
+    [client, workspaceId, sessionId, runControl],
+  );
+
+  const resume = useCallback(
+    async (reason?: string): Promise<SessionEvent | null> => {
+      if (!sessionId) return null;
+      const result = await runControl(() =>
+        client.resumeSession(workspaceId, sessionId, reason !== undefined ? { reason } : {}),
+      );
+      return result?.event ?? null;
+    },
+    [client, workspaceId, sessionId, runControl],
   );
 
   const decide = useCallback(
-    async (approvalId: string, decision: "approve" | "reject", message?: string): Promise<SessionEvent | null> => {
+    async (
+      approvalId: string,
+      decision: "approve" | "reject",
+      message?: string,
+    ): Promise<SessionEvent | null> => {
       if (!sessionId) {
         return null;
       }
-      return await approvalMutation.run(() =>
+      return await runApproval(() =>
         client.sendApprovalDecision(workspaceId, sessionId, {
           approvalId,
           decision,
           ...(message !== undefined ? { message } : {}),
-        }));
+        }),
+      );
     },
-    [client, workspaceId, sessionId, approvalMutation.run],
+    [client, workspaceId, sessionId, runApproval],
   );
 
   const approve = useCallback(
@@ -67,18 +94,19 @@ export function useSessionControl(
     [decide],
   );
 
-  const error = approvalMutation.mutationError ?? interruptMutation.mutationError;
+  const error = approvalError ?? controlError;
   const clearError = useCallback(() => {
-    interruptMutation.clearMutationError();
-    approvalMutation.clearMutationError();
-  }, [interruptMutation.clearMutationError, approvalMutation.clearMutationError]);
+    clearControlError();
+    clearApprovalError();
+  }, [clearControlError, clearApprovalError]);
 
   return {
-    interrupt,
-    interrupting: interruptMutation.mutating,
+    pause,
+    resume,
+    controlling,
     approve,
     reject,
-    responding: approvalMutation.mutating,
+    responding,
     error,
     clearError,
   };