@saadnvd1/agent-os 0.3.610 → 0.3.612

package/app/api/sessions/[id]/simulator/run/route.ts

@@ -20,6 +20,7 @@ export async function POST(
         stderr: "",
         code: 0,
         screenshot: null,
+        read: null,
       });
     if (
       !Array.isArray(body.args) ||

package/components/Pane/MobileTabBar.tsx

@@ -17,69 +17,26 @@ import {
   ChevronDown,
   ChevronLeft,
   ChevronRight,
+  Ellipsis,
   Circle,
-  FolderOpen,
-  GitBranch,
   Menu,
   Plus,
   Search,
+  Star,
   Share2,
-  Terminal as TerminalIcon,
   TextSearch,
-  Users,
-  ScrollText,
-  Package,
 } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { useAwayQuery } from "@/data/away";
 import { awayUntil } from "@/components/Away/time";
 import type { Session, Project } from "@/lib/db";
-import type { LucideIcon } from "lucide-react";
 import { HostBadge } from "@/components/Hosts/HostBadge";
+import { bookmarksUiActions } from "@/stores/bookmarksUi";
 import { shareUiActions } from "@/stores/shareUi";
 import { MoveMenuItems } from "@/components/Tasks/MoveMenuItems";
 import { ChatBookmarksButton } from "@/components/Bookmarks/ChatBookmarksButton";
 import type { ViewMode } from "@/contexts/PaneContext";
-
-interface ViewModeButtonProps {
-  mode: ViewMode;
-  currentMode: ViewMode;
-  icon: LucideIcon;
-  label?: string;
-  onClick: (mode: ViewMode) => void;
-  badge?: React.ReactNode;
-}
-
-function ViewModeButton({
-  mode,
-  currentMode,
-  icon: Icon,
-  label,
-  onClick,
-  badge,
-}: ViewModeButtonProps) {
-  return (
-    <button
-      type="button"
-      aria-label={label}
-      aria-pressed={currentMode === mode}
-      onClick={(e) => {
-        e.stopPropagation();
-        onClick(mode);
-      }}
-      className={cn(
-        "rounded p-1.5 transition-colors",
-        badge && "flex items-center gap-0.5",
-        currentMode === mode
-          ? "bg-secondary text-foreground"
-          : "text-muted-foreground"
-      )}
-    >
-      <Icon className="h-4 w-4" />
-      {badge}
-    </button>
-  );
-}
+import { MobileViewPicker } from "./MobileViewPicker";
 
 interface MobileTabBarProps {
   session: Session | null | undefined;
@@ -205,7 +162,7 @@ export function MobileTabBar({
           onClick={handlePrev}
           onTouchEnd={(e) => e.stopPropagation()}
           disabled={!hasPrev || isNavigating}
-          className="hover:bg-accent flex h-8 w-8 shrink-0 items-center justify-center rounded-md disabled:pointer-events-none disabled:opacity-50"
+          className="hover:bg-accent flex h-8 w-8 shrink-0 items-center justify-center rounded-md disabled:pointer-events-none disabled:opacity-50 max-[429px]:hidden"
         >
           <ChevronLeft className="h-4 w-4" />
         </button>
@@ -304,7 +261,7 @@ export function MobileTabBar({
           onClick={handleNext}
           onTouchEnd={(e) => e.stopPropagation()}
           disabled={!hasNext || isNavigating}
-          className="hover:bg-accent flex h-8 w-8 shrink-0 items-center justify-center rounded-md disabled:pointer-events-none disabled:opacity-50"
+          className="hover:bg-accent flex h-8 w-8 shrink-0 items-center justify-center rounded-md disabled:pointer-events-none disabled:opacity-50 max-[429px]:hidden"
         >
           <ChevronRight className="h-4 w-4" />
         </button>
@@ -313,7 +270,7 @@ export function MobileTabBar({
       {bookmarksSessionId && (
         <ChatBookmarksButton
           sessionId={bookmarksSessionId}
-          className="-my-1.5 h-11 min-w-11"
+          className="-my-1.5 h-11 min-w-11 max-[429px]:hidden"
         />
       )}
       {onFind && (
@@ -325,7 +282,7 @@ export function MobileTabBar({
             e.stopPropagation();
             onFind();
           }}
-          className="-my-1.5 h-11 w-11 shrink-0"
+          className="-my-1.5 h-11 w-11 shrink-0 max-[429px]:hidden"
         >
           <TextSearch className="h-4 w-4" />
         </Button>
@@ -338,11 +295,49 @@ export function MobileTabBar({
           e.stopPropagation();
           paletteActions.open();
         }}
-        // A 44px target in a 32px bar row.
-        className="-my-1.5 h-11 w-11 shrink-0"
+        // 44px targets in a 32px bar row, via -my-1.5.
+        className="-my-1.5 h-11 w-11 shrink-0 max-[429px]:hidden"
       >
         <Search className="h-4 w-4" />
       </Button>
+      {/* Below 430px Find, Palette and Bookmarks fold into one menu. */}
+      <DropdownMenu modal={false}>
+        <DropdownMenuTrigger asChild>
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            aria-label="More"
+            onClick={(e) => e.stopPropagation()}
+            className="-my-1.5 hidden h-11 w-11 shrink-0 max-[429px]:flex"
+          >
+            <Ellipsis className="h-4 w-4" />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="min-w-48">
+          {onFind && (
+            <DropdownMenuItem className="h-11 gap-2" onSelect={onFind}>
+              <TextSearch className="h-4 w-4" />
+              Find in conversation
+            </DropdownMenuItem>
+          )}
+          <DropdownMenuItem
+            className="h-11 gap-2"
+            onSelect={() => paletteActions.open()}
+          >
+            <Search className="h-4 w-4" />
+            Command palette
+          </DropdownMenuItem>
+          {bookmarksSessionId && (
+            <DropdownMenuItem
+              className="h-11 gap-2"
+              onSelect={() => bookmarksUiActions.openChat(bookmarksSessionId)}
+            >
+              <Star className="h-4 w-4" />
+              Bookmarks
+            </DropdownMenuItem>
+          )}
+        </DropdownMenuContent>
+      </DropdownMenu>
       <Button
         variant="ghost"
         size="icon-sm"
@@ -358,60 +353,15 @@ export function MobileTabBar({
       <SessionPrStage sessionId={session?.id} />
       <ViewSwitch session={session} />
 
-      {/* View mode toggle */}
       {session?.working_directory && (
-        <div className="bg-accent/50 flex shrink-0 items-center rounded-md p-0.5">
-          <ViewModeButton
-            mode="terminal"
-            currentMode={viewMode}
-            icon={TerminalIcon}
-            onClick={onViewModeChange}
-          />
-          {isLocalSession && (
-            <ViewModeButton
-              mode="files"
-              currentMode={viewMode}
-              icon={FolderOpen}
-              onClick={onViewModeChange}
-            />
-          )}
-          {isLocalSession && (
-            <ViewModeButton
-              mode="git"
-              currentMode={viewMode}
-              icon={GitBranch}
-              onClick={onViewModeChange}
-            />
-          )}
-          <ViewModeButton
-            mode="artifacts"
-            currentMode={viewMode}
-            icon={Package}
-            label="Artifacts"
-            onClick={onViewModeChange}
-          />
-          {hasLog && (
-            <ViewModeButton
-              mode="log"
-              currentMode={viewMode}
-              icon={ScrollText}
-              onClick={onViewModeChange}
-            />
-          )}
-          {isConductor && (
-            <ViewModeButton
-              mode="workers"
-              currentMode={viewMode}
-              icon={Users}
-              onClick={onViewModeChange}
-              badge={
-                <span className="bg-primary/20 text-primary rounded px-1 text-[10px]">
-                  {workerCount}
-                </span>
-              }
-            />
-          )}
-        </div>
+        <MobileViewPicker
+          viewMode={viewMode}
+          onViewModeChange={onViewModeChange}
+          isLocalSession={isLocalSession}
+          hasLog={hasLog}
+          isConductor={isConductor}
+          workerCount={workerCount}
+        />
       )}
     </div>
   );

package/components/Pane/MobileViewPicker.test.ts

@@ -0,0 +1,92 @@
+import "@/components/Chat/composer/test-dom";
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import { MobileViewPicker, mobileViews } from "./MobileViewPicker";
+
+// Radix dispatches CustomEvents; the node global is not jsdom's.
+Object.defineProperty(globalThis, "CustomEvent", {
+  value: (window as unknown as { CustomEvent: unknown }).CustomEvent,
+  configurable: true,
+});
+
+const all = {
+  isLocalSession: true,
+  hasLog: true,
+  isConductor: true,
+  workerCount: 3,
+};
+
+describe("mobileViews", () => {
+  it("lists every view, Artifacts included", () => {
+    expect(mobileViews(all).map((v) => v.label)).toEqual([
+      "Chat",
+      "Files",
+      "Git",
+      "Artifacts",
+      "Log",
+      "Workers",
+    ]);
+    expect(mobileViews(all).at(-1)?.count).toBe(3);
+  });
+
+  it("hides views that do not apply", () => {
+    expect(
+      mobileViews({
+        isLocalSession: false,
+        isConductor: false,
+        workerCount: 0,
+      }).map((v) => v.label)
+    ).toEqual(["Chat", "Artifacts"]);
+  });
+});
+
+describe("MobileViewPicker", () => {
+  async function open(viewMode: "terminal" | "artifacts", onChange = vi.fn()) {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+    const root = createRoot(el);
+    await act(async () => {
+      root.render(
+        createElement(MobileViewPicker, {
+          ...all,
+          viewMode,
+          onViewModeChange: onChange,
+        })
+      );
+    });
+    const trigger = el.querySelector("button") as HTMLButtonElement;
+    await act(async () => {
+      trigger.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "Enter", bubbles: true })
+      );
+    });
+    return { trigger, onChange };
+  }
+
+  it("shows the current view and lists all views in the menu", async () => {
+    const { trigger } = await open("artifacts");
+    expect(trigger.textContent).toContain("Artifacts");
+    const items = [...document.querySelectorAll('[role="menuitem"]')];
+    expect(items.map((i) => i.textContent)).toEqual([
+      "Chat",
+      "Files",
+      "Git",
+      "Artifacts",
+      "Log",
+      "Workers3",
+    ]);
+    expect(items[3].getAttribute("aria-current")).toBe("true");
+  });
+
+  it("selecting an item calls the view-change handler", async () => {
+    const { onChange } = await open("terminal");
+    const log = [...document.querySelectorAll('[role="menuitem"]')].find((i) =>
+      i.textContent?.startsWith("Log")
+    ) as HTMLElement;
+    await act(async () => {
+      log.click();
+    });
+    expect(onChange).toHaveBeenCalledWith("log");
+  });
+});

package/components/Pane/MobileViewPicker.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import {
+  Check,
+  ChevronDown,
+  FolderOpen,
+  GitBranch,
+  Package,
+  ScrollText,
+  Terminal as TerminalIcon,
+  Users,
+  type LucideIcon,
+} from "lucide-react";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import type { ViewMode } from "@/contexts/PaneContext";
+
+export interface MobileView {
+  mode: ViewMode;
+  label: string;
+  icon: LucideIcon;
+  count?: number;
+}
+
+export interface MobileViewAvailability {
+  isLocalSession: boolean;
+  hasLog?: boolean;
+  isConductor: boolean;
+  workerCount: number;
+}
+
+// The one list of views on a phone; the picker renders it.
+export function mobileViews({
+  isLocalSession,
+  hasLog,
+  isConductor,
+  workerCount,
+}: MobileViewAvailability): MobileView[] {
+  const views: (MobileView | false)[] = [
+    { mode: "terminal", label: "Chat", icon: TerminalIcon },
+    isLocalSession && { mode: "files", label: "Files", icon: FolderOpen },
+    isLocalSession && { mode: "git", label: "Git", icon: GitBranch },
+    { mode: "artifacts", label: "Artifacts", icon: Package },
+    !!hasLog && { mode: "log", label: "Log", icon: ScrollText },
+    isConductor && {
+      mode: "workers",
+      label: "Workers",
+      icon: Users,
+      count: workerCount,
+    },
+  ];
+  return views.filter((v): v is MobileView => !!v);
+}
+
+export function MobileViewPicker({
+  viewMode,
+  onViewModeChange,
+  ...availability
+}: MobileViewAvailability & {
+  viewMode: ViewMode;
+  onViewModeChange: (mode: ViewMode) => void;
+}) {
+  const views = mobileViews(availability);
+  const current = views.find((v) => v.mode === viewMode) ?? views[0];
+  const CurrentIcon = current.icon;
+
+  return (
+    <DropdownMenu modal={false}>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          aria-label={`View: ${current.label}`}
+          onClick={(e) => e.stopPropagation()}
+          className="bg-accent/50 relative flex h-8 shrink-0 items-center gap-1 rounded-md px-2 text-xs after:absolute after:inset-x-0 after:-inset-y-1.5 after:content-['']"
+        >
+          <CurrentIcon className="h-4 w-4" />
+          <span className="max-[359px]:hidden">{current.label}</span>
+          <ChevronDown className="text-muted-foreground h-3 w-3" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="min-w-40">
+        {views.map(({ mode, label, icon: Icon, count }) => (
+          <DropdownMenuItem
+            key={mode}
+            aria-current={mode === current.mode}
+            onSelect={() => onViewModeChange(mode)}
+            className="h-11 gap-2"
+          >
+            <Icon className="h-4 w-4" />
+            <span className="flex-1">{label}</span>
+            {count !== undefined && (
+              <span className="bg-primary/20 text-primary rounded px-1 text-[10px]">
+                {count}
+              </span>
+            )}
+            {mode === current.mode && <Check className="h-4 w-4" />}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/lib/project-config/brief.ts

@@ -50,6 +50,10 @@ export function runningBrief(
     lines.push(
       `- \`${browse.map}\` maps every page to its URL: navigate by URL, don't explore.`
     );
+  if (browse)
+    lines.push(
+      "- Check state with the browser's text snapshot, not screenshots. Screenshot only the final changed screen, and just the changed element (its uid) rather than the full page where the tool allows; every image stays in your context."
+    );
   const sim = simulatorBrief(config.simulator);
   if (sim) lines.push(sim);
   for (const note of notesOf(config.notes))

package/lib/simulator/brief.ts

@@ -12,7 +12,8 @@ export function simulatorBrief(
     return "- The iOS simulator tools are not available on this machine; skip simulator checks and say so in the PR.";
   return [
     "- iOS simulator (optional; it never gates a PR or a build, and a failure is reported, not a blocker): `aos sim open` makes your own simulator and installs this worktree's build (run it with run_in_background, a cold build takes minutes; `aos sim status` shows where it is).",
-    '  Then `aos sim snapshot -i` (accessibility tree with @refs), `aos sim click @e3`, `aos sim fill @e5 "text"`, `aos sim screenshot` (prints a PNG path; read it), `aos sim logs --last 2m`. Refs are only valid from the latest snapshot.',
+    '  Drive and check state with `aos sim snapshot -i` (accessibility tree with @refs, text, cheap), `aos sim click @e3`, `aos sim fill @e5 "text"`, `aos sim logs --last 2m`. Refs are only valid from the latest snapshot.',
+    "  Every image you read stays in your context for every later turn, so screenshot only the final changed screens, and prefer `aos sim screenshot --region @e3` (one element from the latest snapshot) for a single row or banner. It prints two paths: read the `read:` one (reduced to 800px); attach the `full-size` file to the PR.",
     "  Screenshots are written outside the worktree: don't put them in commits or the PR body unless they belong there. `aos sim close` when you're done; it is closed for you when the task ends.",
   ].join("\n");
 }

package/lib/simulator/index.ts

@@ -24,6 +24,13 @@ import {
   simulatorDir,
   type CallResult,
 } from "./agent-device";
+import {
+  RegionError,
+  cropToFrame,
+  frameOf,
+  reducedCopy,
+  takeRegion,
+} from "./screenshot";
 import {
   allLeases,
   bootedCount,
@@ -320,7 +327,7 @@ async function wake(sessionId: string, lease: Lease): Promise<void> {
 export async function runSimulator(
   sessionId: string,
   args: string[]
-): Promise<CallResult & { screenshot: string | null }> {
+): Promise<CallResult & { screenshot: string | null; read: string | null }> {
   const { config, cwd } = declared(sessionId);
   let lease = getLease(sessionId);
   if (!lease || lease.state === "failed")
@@ -333,23 +340,58 @@ export async function runSimulator(
     await wake(sessionId, lease);
     lease = getLease(sessionId)!;
   }
+  let region: string | null = null;
+  if (args[0] === "screenshot") {
+    try {
+      ({ args, region } = takeRegion(args));
+    } catch (error) {
+      throw new SimulatorError((error as Error).message, 400);
+    }
+  }
+  const target = { udid: lease.udid!, sessionId, app: config.app, cwd };
   let argv: string[];
   try {
-    argv = buildArgs(args, {
-      udid: lease.udid!,
-      sessionId,
-      app: config.app,
-      cwd,
-    });
+    argv = buildArgs(args, target);
   } catch (error) {
     throw new SimulatorError((error as Error).message, 400);
   }
   const shot = screenshotPath(argv);
   if (shot) fs.mkdirSync(path.dirname(shot), { recursive: true });
   touchLease(sessionId);
+  // The element's frame comes from a fresh snapshot, before the shot, so a
+  // bad ref fails without writing anything.
+  let located: ReturnType<typeof frameOf> | null = null;
+  if (region) {
+    const snap = await callTool(
+      buildArgs(["snapshot", "-i", "--json"], target)
+    );
+    try {
+      if (snap.code) throw new RegionError(snap.stderr || "snapshot failed");
+      located = frameOf(snap.stdout, region);
+    } catch (error) {
+      if (error instanceof RegionError)
+        throw new SimulatorError(error.message, 400);
+      throw error;
+    }
+  }
   const result = await callTool(argv);
+  const taken = shot && fs.existsSync(shot) ? shot : null;
+  let note = "";
+  if (taken && located) {
+    try {
+      await cropToFrame(taken, located.frame, located.screen);
+    } catch (error) {
+      note = `region crop failed (${(error as Error).message}); kept the full screen\n`;
+    }
+  }
+  const read = taken ? await reducedCopy(taken) : null;
   touchLease(sessionId);
-  return { ...result, screenshot: shot && fs.existsSync(shot) ? shot : null };
+  return {
+    ...result,
+    stderr: result.stderr + note,
+    screenshot: taken,
+    read,
+  };
 }
 
 export async function simulatorLogs(sessionId: string, last: string) {

package/lib/simulator/screenshot.ts

@@ -0,0 +1,180 @@
+/**
+ * Cheaper screenshots for the agent: every image it reads costs tokens on
+ * every later turn, so it reads a copy capped at READ_SIZE px (or just one
+ * element of the screen) while the full-size file stays for the PR.
+ */
+
+import { execFile } from "child_process";
+import fs from "fs";
+import path from "path";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+
+export const READ_SIZE = 800;
+// Points of context kept around a cropped element.
+export const REGION_MARGIN = 8;
+
+export type Sips = (args: string[]) => Promise<string>;
+
+const realSips: Sips = async (args) =>
+  (await execFileAsync("sips", args, { timeout: 30_000 })).stdout;
+let sips: Sips = realSips;
+export const setSips = (fn: Sips | null) => {
+  sips = fn ?? realSips;
+};
+
+export interface Frame {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+export interface Crop {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export class RegionError extends Error {}
+
+// Where the agent reads from: a copy under shots/read, so the shots strip and
+// the PR files stay the full-size ones.
+export const readCopyPath = (full: string) =>
+  path.join(path.dirname(full), "read", path.basename(full));
+
+async function pixelSize(file: string) {
+  const out = await sips(["-g", "pixelWidth", "-g", "pixelHeight", file]);
+  const w = Number(/pixelWidth:\s*(\d+)/.exec(out)?.[1]);
+  const h = Number(/pixelHeight:\s*(\d+)/.exec(out)?.[1]);
+  if (!w || !h) throw new Error("cannot read image size");
+  return { width: w, height: h };
+}
+
+// The reduced copy, or the full file when resizing fails.
+export async function reducedCopy(full: string): Promise<string> {
+  const out = readCopyPath(full);
+  try {
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    await sips(["-Z", String(READ_SIZE), full, "--out", out]);
+    return fs.existsSync(out) ? out : full;
+  } catch {
+    return full;
+  }
+}
+
+// An element's frame (points) to a pixel rectangle of the image, with a
+// margin, clamped to the image. `screen` is the size of the frame's space.
+export function cropRect(
+  frame: Frame,
+  screen: { width: number; height: number },
+  image: { width: number; height: number },
+  margin = REGION_MARGIN
+): Crop {
+  const sx = image.width / screen.width;
+  const sy = image.height / screen.height;
+  const x0 = Math.max(0, Math.floor((frame.x - margin) * sx));
+  const y0 = Math.max(0, Math.floor((frame.y - margin) * sy));
+  const x1 = Math.min(
+    image.width,
+    Math.ceil((frame.x + frame.width + margin) * sx)
+  );
+  const y1 = Math.min(
+    image.height,
+    Math.ceil((frame.y + frame.height + margin) * sy)
+  );
+  if (x1 <= x0 || y1 <= y0)
+    throw new RegionError("that element is off the screen");
+  return { x: x0, y: y0, width: x1 - x0, height: y1 - y0 };
+}
+
+type Node = { ref?: unknown; rect?: Frame };
+
+// Every node with a ref and a rect, wherever the JSON nests them.
+function nodesOf(value: unknown, out: Node[] = []): Node[] {
+  if (Array.isArray(value)) value.forEach((v) => nodesOf(v, out));
+  else if (value && typeof value === "object") {
+    const n = value as Node;
+    if (typeof n.ref === "string" && n.rect) out.push(n);
+    for (const v of Object.values(value)) nodesOf(v, out);
+  }
+  return out;
+}
+
+const isFrame = (r: unknown): r is Frame =>
+  !!r &&
+  ["x", "y", "width", "height"].every(
+    (k) => typeof (r as Record<string, unknown>)[k] === "number"
+  );
+
+// The frame of `ref` in a `snapshot -i --json` output, and the screen size
+// (the widest, tallest frame: the app's window).
+export function frameOf(
+  json: string,
+  ref: string
+): { frame: Frame; screen: { width: number; height: number } } {
+  let nodes: Node[];
+  try {
+    nodes = nodesOf(JSON.parse(json)).filter((n) => isFrame(n.rect));
+  } catch {
+    throw new RegionError(
+      "could not read the snapshot; run `aos sim snapshot -i`"
+    );
+  }
+  const want = ref.replace(/^@/, "");
+  const hit = nodes.find((n) => String(n.ref).replace(/^@/, "") === want);
+  if (!hit)
+    throw new RegionError(
+      `unknown or stale ref @${want}: run \`aos sim snapshot -i\` and use a ref from it`
+    );
+  const screen = nodes.reduce(
+    (s, n) => ({
+      width: Math.max(s.width, n.rect!.x + n.rect!.width),
+      height: Math.max(s.height, n.rect!.y + n.rect!.height),
+    }),
+    { width: 0, height: 0 }
+  );
+  return { frame: hit.rect!, screen };
+}
+
+// Crops `file` in place to the rectangle.
+export async function cropInPlace(file: string, c: Crop): Promise<void> {
+  await sips([
+    "--cropToHeightWidth",
+    String(c.height),
+    String(c.width),
+    "--cropOffset",
+    String(c.y),
+    String(c.x),
+    file,
+  ]);
+}
+
+export async function cropToFrame(
+  file: string,
+  frame: Frame,
+  screen: { width: number; height: number }
+): Promise<void> {
+  await cropInPlace(file, cropRect(frame, screen, await pixelSize(file)));
+}
+
+// `--region <ref>` / `--region=<ref>` out of a screenshot's args.
+export function takeRegion(args: string[]): {
+  args: string[];
+  region: string | null;
+} {
+  const rest: string[] = [];
+  let region: string | null = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--region") {
+      region = args[++i] ?? "";
+      if (!region) throw new RegionError("--region needs a ref, like @e3");
+    } else if (a.startsWith("--region=")) region = a.slice(9);
+    else rest.push(a);
+  }
+  if (region !== null && !/^@?e?\d+$/.test(region) && !/^@\S+$/.test(region))
+    throw new RegionError("--region takes a ref from `aos sim snapshot -i`");
+  return { args: rest, region };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.610",
+  "version": "0.3.612",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"