@hanzo/build 0.2.30 → 0.2.31

package/lib/api/turn.js

@@ -1,27 +1,5 @@
-/**
- * What a run's events SAY, as text a person reads.
- *
- * A curated projection, never a dump: an event carries the machinery a run
- * happened on — hosts, paths, whole file bodies — and printing it would put
- * someone's filesystem in front of anyone who can read the run. Each kind gets a
- * sentence built from the few fields that describe the outcome; the rest is
- * dropped by omission, because a projection cannot leak a field it never reads.
- *
- * Every string here is rendered as TEXT by the transcript. Nothing is HTML.
- *
- * The coding plane's vocabulary (apps/coding): `status` for a lifecycle move
- * (started, routed, done, error, stopped, paused), `tool-call` for a step,
- * `log` for a free line. A person's steering is a `control` {command, message}.
- * A run on a project with a site ends `done` with `live` when it published what
- * it pushed, or `unpublished` saying why it did not.
- *
- * `cards` is the transcript as it is drawn: the run's steps, and the agent's own
- * output read by what each part is (harness.ts). The output a card shows is what
- * the run's Terminal log already prints; a command's working directory, which is
- * the sandbox's layout, is dropped.
- */
-import { harness } from './harness.js';
 const str = (v) => (typeof v === 'string' ? v : '');
+const obj = (v) => (v && typeof v === 'object' ? v : {});
 /** The payload as an object. A live frame may carry it as a JSON string. */
 export function decode(payload) {
     if (payload && typeof payload === 'object')
@@ -253,31 +231,76 @@ export function pull(url, repo) {
         return { href: '', label: '' };
     return { href: url, label: `#${m[3]}` };
 }
-/** The platform's own words for the step that starts the agent (apps/coding sandboxrunner.go). */
-const TASK = 'running the task';
 /** What the run's own steps are called on a card. */
 const NAMES = {
     lease: 'Sandbox',
+    workspace: 'Workspace',
     clone: 'Clone',
+    branch: 'Branch',
     secrets: 'Secrets',
     install: 'Install',
     start: 'Start',
+    skills: 'Skills',
+    artifacts: 'Save artifacts',
     push: 'Push',
-    keep: 'Keep the work',
+    kept: 'Keep the sandbox',
 };
-/** Steps another card already says: `leased` finishes the lease, `done` is the final status, `ended` is housekeeping. */
-const QUIET = new Set(['leased', 'done', 'ended']);
+/** Steps another card already says: `leased` finishes the lease, `done` is the final status, `ended` and `exit` are housekeeping. */
+const QUIET = new Set(['leased', 'done', 'ended', 'exit']);
 const ranOf = (status) => (status === 'ok' || status === 'done' ? 'done' : status === 'error' ? 'error' : 'running');
+/** How an agent's item went: in progress, finished, or failed or declined. */
+function itemRan(item) {
+    switch (str(item.status)) {
+        case 'in_progress':
+            return 'running';
+        case 'failed':
+            return 'error';
+        case 'declined':
+            return 'cancelled';
+    }
+    return typeof item.exit_code === 'number' && item.exit_code !== 0 ? 'error' : 'done';
+}
+/** A path in the workspace, without the sandbox's working directory above it. */
+const rel = (path) => path.replace(/^\/work\//, '');
+/**
+ * One item of the agent's narration as a card, or null when it says nothing a
+ * person reads. `key` is the card's, kept as the item is updated.
+ */
+function item(it, key) {
+    switch (str(it.type)) {
+        case 'agent_message':
+            return str(it.text) ? { kind: 'said', key, who: 'agent', text: str(it.text) } : null;
+        case 'reasoning':
+            return str(it.text) ? { kind: 'think', key, text: str(it.text) } : null;
+        case 'command_execution':
+            return { kind: 'shell', key, command: str(it.command), output: str(it.aggregated_output), ran: itemRan(it) };
+        case 'file_change': {
+            const changes = Array.isArray(it.changes) ? it.changes : [];
+            return { kind: 'edit', key, files: changes.map((c) => rel(str(obj(c).path))).filter(Boolean), ran: itemRan(it) };
+        }
+        case 'mcp_tool_call':
+            return { kind: 'step', key, name: str(it.tool) || 'Tool', detail: str(it.server), output: '', ran: itemRan(it) };
+        case 'web_search':
+            return { kind: 'step', key, name: 'Search', detail: str(it.query), output: '', ran: 'done' };
+        case 'todo_list': {
+            const items = Array.isArray(it.items) ? it.items : [];
+            return { kind: 'todo', key, items: items.map((x) => ({ text: str(obj(x).text), done: obj(x).completed === true })).filter((x) => x.text) };
+        }
+    }
+    return null;
+}
 /**
  * A run's events, as the cards its transcript draws. `mode` is the run's, from
  * its record: a plan's final status is its plan, and nothing else draws a plan.
  *
- * The run's own steps arrive as `tool-call` {step, message, status}; each
- * command in the sandbox narrates its output as `log` {message} chunks and ends
- * with `tool-call` {step: "exit"}. The output after the step that starts the
- * agent is the agent's, read by its harness's grammar (harness.ts); after any
- * other step it is that step's. Once the agent has exited, the commands the run
- * runs before it pushes commit its work.
+ * The run's own steps arrive as `tool-call` {step, message, status}. The agent
+ * narrates itself as `event` lines: an item is started, updated and completed
+ * under one id, and its card is drawn once and kept current. Ids count from zero
+ * in each agent process, so an id is the agent's within the thread it started. A
+ * turn that fails is one plain line with the detail folded beneath it, drawn once
+ * however many times it is said; an `error` on its own is the agent retrying and
+ * is drawn only if the turn then fails. The final status carries the agent's
+ * answer, drawn once. `log` is never drawn here.
  */
 export function cards(events, mode = '') {
     const out = [];
@@ -285,48 +308,56 @@ export function cards(events, mode = '') {
     let n = 0;
     const mint = () => `${seq}.${n++}`;
     let phase = null;
-    let agent = null;
-    // The agent has run and exited: output with no step of its own is the run's.
-    let exited = false;
-    const settle = () => {
-        agent?.end();
-        agent = null;
-        phase = null;
-    };
+    const items = new Map();
+    let thread = 0;
+    let said = '';
     const answers = new Set();
-    // What the person said in an event of its own. The harness prints their ask
-    // too (harness.ts); an event saying the same words is the one drawn. Words
-    // that steered the run are not its ask.
-    const told = new Set();
     const steered = new Set();
     const person = (text) => {
         const c = { kind: 'said', key: mint(), who: 'person', text };
         out.push(c);
-        told.add(c);
         return c;
     };
+    const failures = new Set();
+    const failed = (message) => {
+        if (failures.has(message))
+            return;
+        failures.add(message);
+        out.push({ kind: 'note', key: mint(), text: plain(message) });
+        if (message)
+            out.push({ kind: 'step', key: mint(), name: 'Error', detail: '', output: message, ran: 'error' });
+    };
     for (const e of [...events].sort((a, b) => a.seq - b.seq)) {
         seq = e.seq;
         n = 0;
         const body = decode(e.payload);
         const b = body && typeof body === 'object' ? body : null;
         switch (e.kind) {
-            case 'log': {
-                const text = typeof body === 'string' ? body : str(b?.message) || str(b?.text);
-                if (!text)
+            case 'event': {
+                if (!b)
                     break;
-                if (agent)
-                    agent.feed(text);
-                else if (phase)
-                    phase.output += text;
-                else if (exited) {
-                    phase = { kind: 'step', key: mint(), name: 'Commit', detail: 'committing the work', output: text, ran: 'running' };
-                    out.push(phase);
-                }
-                else {
-                    agent = harness(out, mint);
-                    agent.feed(text);
+                const type = str(b.type);
+                if (type === 'thread.started')
+                    thread++;
+                if (type === 'error')
+                    said = str(b.message);
+                if (type === 'turn.failed')
+                    failed(str(obj(b.error).message) || said);
+                if (type !== 'item.started' && type !== 'item.updated' && type !== 'item.completed')
+                    break;
+                const it = obj(b.item);
+                const id = str(it.id) && `${thread}:${str(it.id)}`;
+                const at = id ? items.get(id) : undefined;
+                const card = item(it, at === undefined ? mint() : out[at].key);
+                if (!card)
+                    break;
+                if (at === undefined) {
+                    if (id)
+                        items.set(id, out.length);
+                    out.push(card);
                 }
+                else
+                    out[at] = card;
                 break;
             }
             case 'tool-call': {
@@ -336,20 +367,10 @@ export function cards(events, mode = '') {
                 const message = str(b.message);
                 if (step === 'exit') {
                     // One command in the sandbox ended: `exit 0`, `exit 1`, or `ended: …`.
-                    if (agent) {
-                        settle();
-                        exited = true;
-                    }
-                    else if (phase && phase.ran === 'running')
+                    if (phase && phase.ran === 'running')
                         phase.ran = message === 'exit 0' ? 'done' : 'error';
                     break;
                 }
-                if (message === TASK) {
-                    settle();
-                    exited = false;
-                    agent = harness(out, mint);
-                    break;
-                }
                 if (step === 'leased') {
                     const lease = out.find((c) => c.kind === 'step' && c.name === NAMES.lease);
                     if (lease)
@@ -364,26 +385,33 @@ export function cards(events, mode = '') {
                         phase.detail = message;
                     break;
                 }
-                settle();
                 phase = { kind: 'step', key: mint(), name, detail: message, output: '', ran: ranOf(str(b.status)) };
                 out.push(phase);
                 break;
             }
             case 'status': {
-                settle();
+                phase = null;
                 if (!b)
                     break;
-                const text = str(b.plan);
-                if (str(b.status) === 'done' && (mode === 'plan' || mode === 'setup') && text) {
+                const done = str(b.status) === 'done';
+                const text = str(b.plan) || str(b.answer);
+                if (done && (mode === 'plan' || mode === 'setup') && text) {
                     answers.add(text.trim());
                     out.push(mode === 'plan' ? { kind: 'plan', key: mint(), text } : { kind: 'said', key: mint(), who: 'agent', text });
                     break;
                 }
+                const answer = str(b.answer).trim();
+                if (answer) {
+                    answers.add(answer);
+                    out.push({ kind: 'said', key: mint(), who: 'agent', text: answer });
+                }
+                if (str(b.status) === 'error') {
+                    failed(str(b.error));
+                    break;
+                }
                 const line = status(b, mode);
                 if (line)
                     out.push({ kind: 'note', key: mint(), text: line });
-                if (str(b.status) === 'error' && str(b.error))
-                    out.push({ kind: 'step', key: mint(), name: 'Error', detail: '', output: str(b.error), ran: 'error' });
                 break;
             }
             case 'control': {
@@ -413,24 +441,21 @@ export function cards(events, mode = '') {
             }
         }
     }
-    settle();
-    // The answer the final status carries is also the agent's last message: draw it once, as the answer.
-    let kept = false;
+    // The answer a status carries is also the agent's last message: each is drawn once, as the answer.
+    const kept = new Set();
     for (let i = out.length - 1; i >= 0; i--) {
         const c = out[i];
         if (!((c.kind === 'said' && c.who === 'agent') || c.kind === 'plan') || !answers.has(c.text.trim()))
             continue;
-        if (kept)
+        if (kept.has(c.text.trim()))
             out.splice(i, 1);
-        kept = true;
+        kept.add(c.text.trim());
     }
-    const heard = new Set([...told].map((c) => c.text.trim()));
-    const drawn = out.filter((c) => !(c.kind === 'said' && c.who === 'person' && !told.has(c) && heard.has(c.text.trim())));
     // The ask opens the conversation, ahead of the steps that set the run up.
-    const ask = drawn.findIndex((c) => c.kind === 'said' && c.who === 'person' && !steered.has(c));
+    const ask = out.findIndex((c) => c.kind === 'said' && c.who === 'person' && !steered.has(c));
     if (ask > 0)
-        drawn.unshift(...drawn.splice(ask, 1));
-    return drawn;
+        out.unshift(...out.splice(ask, 1));
+    return out;
 }
 /** The plan a plan run answered with, from its final status, or ''. */
 export function answer(events) {

package/lib/desk.d.ts

@@ -13,7 +13,7 @@ export declare function Desk({ id, repo, branch, base, environment, mode, pr, ti
     };
     title: string;
     project: string;
-    /** The sandbox the run holds, or '' before it leases one and on a machine. */
+    /** The sandbox the run leased, or '' before it leases one and on a machine. */
     sandbox: string;
     /** Where the run's work is published, or '' before it is. */
     site: string;

package/lib/desk.js

@@ -1,22 +1,32 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
- * The pane beside a run's transcript, as tabs: the Browser showing where the run
- * is published, its sandbox's Desktop and Terminal, what it produced, its files,
- * what it pushed, and its codebase's environment.
+ * The pane beside a run's transcript, as tabs: the Browser showing what the run's
+ * sandbox serves (or where the run is published), its sandbox's Desktop and
+ * Terminal, what it produced, its files, what it pushed, and its codebase's
+ * environment.
+ *
+ * The sandbox outlives the run: kept when the run ends, parked while nobody
+ * watches, retired a day after it parks. The bar under the tabs says which and
+ * suspends or resumes it; a tab that needs it running resumes it (sandbox.ts).
  */
 import { SizableText, XStack, YStack } from '@hanzo/gui';
 import { ExternalLink, Info, MoreHorizontal, PanelRightClose, RefreshCcw } from '@hanzogui/lucide-icons-2';
 import { Button, DropdownMenu } from '@hanzo/ui';
 import { PreviewFrame } from '@hanzo/ui/agents';
-import { useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { park, ports as listening, preview, sandbox as look, wake } from './api/sandbox.js';
 import { failure, shell } from './api/turn.js';
 import { Door } from './door.js';
 import { Environment } from './environment.js';
 import { Artifacts, Files } from './files.js';
 import { Git } from './git.js';
-import { Out } from './out.js';
+import { useTarget } from './host.js';
+import { away, Out } from './out.js';
 /** The tabs that are a surface of their own, drawn edge to edge. */
 const BLEED = ['browser', 'desktop', 'terminal'];
+/** How often the sandbox's state, and what it serves, is read while the pane is open. */
+const EVERY = 10_000;
+const PORTS = 5_000;
 export function Desk({ id, repo, branch, base, environment, mode, pr, title, project, sandbox, site, published, events, live, menu, refused, retry, onRetry, onHide, }) {
     // Until a tab is picked it follows the run: a setup run's work IS the
     // environment, a published run opens on its site, any other on its terminal.
@@ -26,15 +36,177 @@ export function Desk({ id, repo, branch, base, environment, mode, pr, title, pro
     const lines = shell(events);
     const failed = failure(events);
     const bleed = BLEED.includes(tab);
-    return (_jsxs(YStack, { role: "complementary", "aria-label": "Run details", flex: 1, minW: 0, minH: 0, borderLeftWidth: 1, borderColor: "$borderColor", display: "none", $md: { display: 'flex' }, children: [_jsxs(XStack, { px: "$2", pt: "$2", gap: "$1", borderBottomWidth: 1, borderColor: "$borderColor", items: "center", children: [_jsxs(XStack, { flex: 1, minW: 0, gap: "$1", overflow: "scroll", children: [_jsx(TabButton, { id: "browser", tab: tab, onPick: setTab, children: "Browser" }), _jsx(TabButton, { id: "desktop", tab: tab, onPick: setTab, children: "Desktop" }), _jsx(TabButton, { id: "terminal", tab: tab, onPick: setTab, children: "Terminal" }), _jsx(TabButton, { id: "artifacts", tab: tab, onPick: setTab, children: "Artifacts" }), _jsx(TabButton, { id: "files", tab: tab, onPick: setTab, children: "Files" }), _jsx(TabButton, { id: "git", tab: tab, onPick: setTab, children: "Git" }), _jsx(TabButton, { id: "environment", tab: tab, onPick: setTab, children: "Environment" })] }), _jsx(XStack, { render: "button", "aria-label": "Hide the side pane", px: "$2", py: "$1", rounded: "$2", hoverStyle: { bg: '$hover' }, onPress: onHide, children: _jsx(PanelRightClose, { size: 16 }) }), _jsx(DropdownMenu, { trigger: _jsx(XStack, { render: "button", "aria-label": "Run actions", px: "$2", py: "$1", rounded: "$2", hoverStyle: { bg: '$hover' }, children: _jsx(MoreHorizontal, { size: 16 }) }), items: [...menu, { key: 'details', label: 'Details', icon: _jsx(Info, { size: 16 }), onSelect: () => setTab('environment') }] })] }), _jsxs(YStack, { flex: 1, minH: 0, overflow: bleed ? 'hidden' : 'scroll', px: bleed ? 0 : '$3', py: bleed ? 0 : '$3', children: [tab === 'environment' ? (_jsxs(YStack, { gap: "$2", children: [_jsx(Environment, { repo: name, busy: live && mode === 'setup' }), _jsx(SizableText, { size: "$2", color: "$ink", pt: "$4", children: "This run" }), _jsx(Fact, { label: "Run", value: id }), _jsx(Fact, { label: "Repository", value: name || '—' }), _jsx(Fact, { label: "Branch", value: branch || '—' }), _jsx(Fact, { label: "Base", value: base || '—' }), _jsx(Fact, { label: "Runs on", value: environment || 'sandbox' }), _jsx(Fact, { label: "Mode", value: mode || 'build' })] })) : null, tab === 'browser' ? _jsx(Browser, { site: site, live: live }, published) : null, tab === 'git' ? _jsx(Git, { session: id, title: title, live: live }) : null, tab === 'desktop' ? _jsx(Door, { which: "screen", sandbox: sandbox, live: live, session: id }) : null, tab === 'terminal' ? (_jsx(Terminal, { id: id, sandbox: sandbox, lines: lines, live: live, failed: failed, refused: refused, retry: retry, onRetry: onRetry })) : null, tab === 'artifacts' ? (_jsx(Artifacts, { repo: repo, branch: branch, mode: mode, project: project, site: site, pr: pr, onEnvironment: () => setTab('environment') })) : null, tab === 'files' ? _jsx(Files, { session: id, repo: repo, branch: branch, sandbox: sandbox, live: live }) : null] })] }));
+    const box = useBox(sandbox);
+    // Nothing is said of the sandbox until it has been read.
+    const held = box.value?.state ?? '';
+    return (_jsxs(YStack, { role: "complementary", "aria-label": "Run details", flex: 1, minW: 0, minH: 0, borderLeftWidth: 1, borderColor: "$borderColor", display: "none", $md: { display: 'flex' }, children: [_jsxs(XStack, { px: "$2", pt: "$2", gap: "$1", borderBottomWidth: 1, borderColor: "$borderColor", items: "center", children: [_jsxs(XStack, { flex: 1, minW: 0, gap: "$1", overflow: "scroll", children: [_jsx(TabButton, { id: "browser", tab: tab, onPick: setTab, children: "Browser" }), _jsx(TabButton, { id: "desktop", tab: tab, onPick: setTab, children: "Desktop" }), _jsx(TabButton, { id: "terminal", tab: tab, onPick: setTab, children: "Terminal" }), _jsx(TabButton, { id: "artifacts", tab: tab, onPick: setTab, children: "Artifacts" }), _jsx(TabButton, { id: "files", tab: tab, onPick: setTab, children: "Files" }), _jsx(TabButton, { id: "git", tab: tab, onPick: setTab, children: "Git" }), _jsx(TabButton, { id: "environment", tab: tab, onPick: setTab, children: "Environment" })] }), _jsx(XStack, { render: "button", "aria-label": "Hide the side pane", px: "$2", py: "$1", rounded: "$2", hoverStyle: { bg: '$hover' }, onPress: onHide, children: _jsx(PanelRightClose, { size: 16 }) }), _jsx(DropdownMenu, { trigger: _jsx(XStack, { render: "button", "aria-label": "Run actions", px: "$2", py: "$1", rounded: "$2", hoverStyle: { bg: '$hover' }, children: _jsx(MoreHorizontal, { size: 16 }) }), items: [...menu, { key: 'details', label: 'Details', icon: _jsx(Info, { size: 16 }), onSelect: () => setTab('environment') }] })] }), sandbox ? _jsx(Held, { box: box, live: live }) : null, _jsxs(YStack, { flex: 1, minH: 0, overflow: bleed ? 'hidden' : 'scroll', px: bleed ? 0 : '$3', py: bleed ? 0 : '$3', children: [tab === 'environment' ? (_jsxs(YStack, { gap: "$2", children: [_jsx(Environment, { repo: name, busy: live && mode === 'setup' }), _jsx(SizableText, { size: "$2", color: "$ink", pt: "$4", children: "This run" }), _jsx(Fact, { label: "Run", value: id }), _jsx(Fact, { label: "Repository", value: name || '—' }), _jsx(Fact, { label: "Branch", value: branch || '—' }), _jsx(Fact, { label: "Base", value: base || '—' }), _jsx(Fact, { label: "Runs on", value: environment || 'sandbox' }), _jsx(Fact, { label: "Sandbox", value: sandbox || '—' }), _jsx(Fact, { label: "Mode", value: mode || 'build' })] })) : null, tab === 'browser' ? _jsx(Browser, { sandbox: sandbox, held: held, site: site, live: live }, published) : null, tab === 'git' ? _jsx(Git, { session: id, title: title, live: live }) : null, tab === 'desktop' ? _jsx(Door, { which: "screen", sandbox: sandbox, held: held, session: id }) : null, tab === 'terminal' ? (_jsx(Terminal, { id: id, sandbox: sandbox, held: held, lines: lines, live: live, failed: failed, refused: refused, retry: retry, onRetry: onRetry })) : null, tab === 'artifacts' ? (_jsx(Artifacts, { session: id, sandbox: sandbox, repo: repo, branch: branch, mode: mode, project: project, site: site, pr: pr, onEnvironment: () => setTab('environment') })) : null, tab === 'files' ? _jsx(Files, { session: id, repo: repo, branch: branch, sandbox: sandbox, live: held === 'running' }) : null] })] }));
 }
 /**
- * The Browser tab: the page where the run published its work, framed, with its
- * address, a reload and the page in a tab of its own.
+ * The run's sandbox as it stands, and what moves it. It is read while the pane is
+ * open and the page is in view, and no more once it has ended or failed.
  */
-function Browser({ site, live }) {
+function useBox(id) {
+    const t = useTarget();
+    const [value, setValue] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const [note, setNote] = useState('');
+    useEffect(() => {
+        setValue(null);
+        if (!id)
+            return;
+        let gone = false;
+        let every;
+        const read = () => {
+            if (document.hidden)
+                return;
+            look(t, id).then((b) => {
+                if (gone)
+                    return;
+                setValue(b);
+                if (b.state === 'gone' || b.state === 'error')
+                    clearInterval(every);
+            }, (e) => !gone && setNote(e.message));
+        };
+        read();
+        every = setInterval(read, EVERY);
+        return () => {
+            gone = true;
+            clearInterval(every);
+        };
+    }, [t, id]);
+    const act = useCallback((how) => {
+        setBusy(true);
+        setNote('');
+        (how === 'park' ? park(t, id) : wake(t, id)).then(setValue, (e) => setNote(e.message)).finally(() => setBusy(false));
+    }, [t, id]);
+    return { value, busy, note, act };
+}
+/** When a parked sandbox is retired, as a person reads it. */
+const until = (ms) => new Date(ms).toLocaleString(undefined, { weekday: 'short', hour: 'numeric', minute: '2-digit' });
+/**
+ * The sandbox's line under the tabs: where it is, and the one thing to do to it.
+ * A sandbox a run is working in is not suspended from here.
+ */
+function Held({ box, live }) {
+    const b = box.value;
+    const state = b?.state ?? 'pending';
+    const says = state === 'running'
+        ? 'Sandbox running'
+        : state === 'parked'
+            ? b?.ends
+                ? `Sandbox suspended · its files are kept until ${until(b.ends)}`
+                : 'Sandbox suspended · its files are kept'
+            : state === 'pending'
+                ? 'Sandbox starting…'
+                : state === 'gone'
+                    ? 'Sandbox ended'
+                    : `Sandbox unavailable${b?.error ? ` · ${b.error}` : ''}`;
+    return (_jsxs(XStack, { px: "$3", py: "$1.5", gap: "$2", items: "center", borderBottomWidth: 1, borderColor: "$borderColor", "aria-label": "Sandbox", children: [_jsx(YStack, { width: 7, height: 7, rounded: 99, bg: state === 'running' ? '$green10' : state === 'parked' ? '$soft' : '$borderColor' }), _jsx(SizableText, { flex: 1, minW: 0, size: "$1", color: "$soft", numberOfLines: 1, children: box.note || says }), state === 'running' && !live ? (_jsx(Button, { size: "sm", variant: "ghost", disabled: box.busy, onPress: () => box.act('park'), children: "Suspend" })) : state === 'parked' ? (_jsx(Button, { size: "sm", variant: "outline", disabled: box.busy, onPress: () => box.act('wake'), children: box.busy ? 'Resuming…' : 'Resume' })) : null] }));
+}
+/** What a preview page says of itself, when it cannot serve. */
+const PREVIEW = 'hanzo-preview';
+/** How often a preview is opened again on its own before Retry is the person's to press. */
+const REMINTS = 2;
+const REMINT = 30_000;
+/** What a preview page's status means to the person looking at it, when it is not reopened. */
+const SAYS = {
+    401: () => 'This browser keeps the preview’s cookie out of a frame. Open it in a new tab.',
+    502: (port) => `Nothing answered on port ${port}. Start the server, then Retry.`,
+};
+/**
+ * The Browser tab: what the run's sandbox serves, one port at a time, framed at
+ * its own origin; or, with nothing serving, where the run is published. Only a
+ * running sandbox is shown: a suspended one is resumed from the bar, never by
+ * looking. A preview that lost its sandbox (409) is opened again, at most twice
+ * in a while; any other status is said, and Retry is the person's.
+ */
+function Browser({ sandbox, held, site, live }) {
+    const t = useTarget();
+    const [open, setOpen] = useState([]);
+    const [port, setPort] = useState(0);
+    const [src, setSrc] = useState('');
+    const [why, setWhy] = useState('');
+    const [attempt, setAttempt] = useState(0);
+    const reopened = useRef([]);
+    const frame = useRef(null);
+    const running = Boolean(sandbox) && held === 'running';
+    // What listens, read again while the sandbox runs: a dev server appears once it listens.
+    useEffect(() => {
+        if (!running) {
+            setOpen([]);
+            setPort(0);
+            return;
+        }
+        let gone = false;
+        const read = () => listening(t, sandbox).then((ps) => {
+            if (gone)
+                return;
+            setOpen(ps);
+            setPort((p) => (ps.some((x) => x.port === p) ? p : (ps[0]?.port ?? 0)));
+        }, () => undefined);
+        void read();
+        const every = setInterval(read, PORTS);
+        return () => {
+            gone = true;
+            clearInterval(every);
+        };
+    }, [t, sandbox, running]);
+    // One address per port and attempt: its ticket is spent when the page opens it.
+    useEffect(() => {
+        setSrc('');
+        setWhy('');
+        if (!port || !sandbox)
+            return;
+        let gone = false;
+        preview(t, sandbox, port).then((u) => !gone && setSrc(u), (e) => !gone && setWhy(e.message));
+        return () => {
+            gone = true;
+        };
+    }, [t, sandbox, port, attempt]);
+    // A preview that can no longer serve says so; one whose sandbox stopped is opened again, a little.
+    useEffect(() => {
+        if (!src)
+            return;
+        const origin = new URL(src).origin;
+        const hear = (e) => {
+            if (e.origin !== origin || e.source !== frame.current?.contentWindow)
+                return;
+            const m = e.data;
+            if (m?.source !== PREVIEW || typeof m.status !== 'number')
+                return;
+            const now = Date.now();
+            reopened.current = reopened.current.filter((at) => now - at < REMINT);
+            if (m.status === 409 && reopened.current.length < REMINTS) {
+                reopened.current.push(now);
+                setAttempt((a) => a + 1);
+                return;
+            }
+            const say = SAYS[m.status];
+            if (say || m.status === 409)
+                setWhy(say ? say(port) : 'The sandbox stopped serving. Retry to open it again.');
+        };
+        window.addEventListener('message', hear);
+        return () => window.removeEventListener('message', hear);
+    }, [src, port]);
+    const tab = () => away(preview(t, sandbox, port)).catch((e) => setWhy(e.message));
+    if (!running)
+        return _jsx(Site, { site: site, live: live, held: held });
+    if (!port)
+        return _jsx(Site, { site: site, live: live, held: held });
+    const host = open.find((p) => p.port === port)?.host ?? '';
+    return (_jsxs(YStack, { flex: 1, minH: 0, children: [_jsxs(XStack, { px: "$2", py: "$1.5", gap: "$1.5", items: "center", borderBottomWidth: 1, borderColor: "$borderColor", children: [_jsx(XStack, { render: "button", "aria-label": "Reload the page", onPress: () => setAttempt((a) => a + 1), p: "$1.5", rounded: "$2", hoverStyle: { bg: '$hover' }, children: _jsx(RefreshCcw, { size: 14 }) }), open.length > 1 ? (_jsx(XStack, { gap: "$1", children: open.map((p) => (_jsx(XStack, { render: "button", "aria-label": `Port ${p.port}`, onPress: () => setPort(p.port), px: "$2", py: "$1", rounded: "$2", bg: p.port === port ? '$hover' : 'transparent', children: _jsx(SizableText, { size: "$1", color: p.port === port ? '$ink' : '$soft', children: String(p.port) }) }, p.port))) })) : null, _jsx(SizableText, { flex: 1, minW: 0, size: "$1", color: "$soft", numberOfLines: 1, style: mono, children: host || `port ${port}` }), _jsx(XStack, { render: "button", "aria-label": "Open in a new tab", onPress: () => void tab(), p: "$1.5", rounded: "$2", hoverStyle: { bg: '$hover' }, children: _jsx(ExternalLink, { size: 14 }) })] }), why ? (_jsxs(YStack, { flex: 1, items: "center", justify: "center", gap: "$2", p: "$6", children: [_jsx(SizableText, { size: "$2", color: "$soft", style: { textAlign: 'center' }, children: why }), _jsxs(XStack, { gap: "$2", children: [_jsx(Button, { size: "sm", variant: "outline", onPress: () => setAttempt((a) => a + 1), children: "Retry" }), _jsx(Button, { size: "sm", variant: "outline", onPress: () => void tab(), children: "Open in a new tab" })] })] })) : src ? (_jsx("iframe", { ref: frame, src: src, title: `What the run serves on port ${port}`, sandbox: "allow-scripts allow-same-origin allow-forms allow-popups", style: { border: 0, width: '100%', height: '100%', display: 'block', background: '#fff' } })) : (_jsx(YStack, { flex: 1, items: "center", justify: "center", children: _jsx(SizableText, { size: "$2", color: "$soft", children: `Opening port ${port}…` }) }))] }));
+}
+/**
+ * Where the run published its work, framed, with its address, a reload and the
+ * page in a tab of its own; or what keeps its sandbox from serving.
+ */
+function Site({ site, live, held }) {
     const frame = useRef(null);
-    return (_jsxs(YStack, { flex: 1, minH: 0, children: [_jsxs(XStack, { px: "$2", py: "$1.5", gap: "$1.5", items: "center", borderBottomWidth: 1, borderColor: "$borderColor", children: [_jsx(XStack, { render: "button", "aria-label": "Reload the page", onPress: () => frame.current?.reload(), p: "$1.5", rounded: "$2", hoverStyle: { bg: '$hover' }, children: _jsx(RefreshCcw, { size: 14 }) }), _jsx(SizableText, { flex: 1, minW: 0, size: "$1", color: "$soft", numberOfLines: 1, style: mono, children: site || 'Not published yet' }), site ? (_jsx(Out, { href: site, label: "Open in a new tab", children: _jsx(XStack, { p: "$1.5", rounded: "$2", hoverStyle: { bg: '$hover' }, children: _jsx(ExternalLink, { size: 14 }) }) })) : null] }), _jsx(PreviewFrame, { ref: frame, src: site, title: "Where this run is published", device: "desktop", empty: _jsxs(YStack, { items: "center", gap: "$2", p: "$6", children: [_jsx(SizableText, { size: "$3", color: "$ink", children: live ? 'Not published yet' : 'Nothing was published' }), _jsx(SizableText, { size: "$2", color: "$soft", style: { textAlign: 'center' }, children: live ? 'The page appears here once the run publishes its site.' : 'This run published no site. Its work is on its branch.' })] }) })] }));
+    return (_jsxs(YStack, { flex: 1, minH: 0, children: [_jsxs(XStack, { px: "$2", py: "$1.5", gap: "$1.5", items: "center", borderBottomWidth: 1, borderColor: "$borderColor", children: [_jsx(XStack, { render: "button", "aria-label": "Reload the page", onPress: () => frame.current?.reload(), p: "$1.5", rounded: "$2", hoverStyle: { bg: '$hover' }, children: _jsx(RefreshCcw, { size: 14 }) }), _jsx(SizableText, { flex: 1, minW: 0, size: "$1", color: "$soft", numberOfLines: 1, style: mono, children: site || 'Nothing is serving yet' }), site ? (_jsx(Out, { href: site, label: "Open in a new tab", children: _jsx(XStack, { p: "$1.5", rounded: "$2", hoverStyle: { bg: '$hover' }, children: _jsx(ExternalLink, { size: 14 }) }) })) : null] }), _jsx(PreviewFrame, { ref: frame, src: site, title: "Where this run is published", device: "desktop", empty: _jsxs(YStack, { items: "center", gap: "$2", p: "$6", children: [_jsx(SizableText, { size: "$3", color: "$ink", children: "Nothing is serving yet" }), _jsx(SizableText, { size: "$2", color: "$soft", style: { textAlign: 'center' }, children: held === 'parked'
+                                ? 'The run’s sandbox is suspended. Resume it to see what it serves.'
+                                : live
+                                    ? 'When the run starts a server in its sandbox, the page opens here.'
+                                    : 'Nothing listens in this run’s sandbox, and it published no site. Its work is on its branch.' })] }) })] }));
 }
 function TabButton({ id, tab, onPick, children }) {
     const on = tab === id;
@@ -46,16 +218,15 @@ function Fact({ label, value }) {
 const mono = { fontFamily: 'var(--f-mono, ui-monospace, monospace)', whiteSpace: 'pre' };
 /**
  * The Terminal tab: a shell in the run's sandbox, in the same working tree as the
- * agent, while the run holds one; and the commands the agent itself ran, which
- * outlive the sandbox. The shell is a tmux session named for the run, so a
- * reopened tab reattaches to it.
+ * agent, while the sandbox is kept; and the agent's log, which outlives it. The
+ * shell is a tmux session named for the run, so a reopened tab reattaches to it.
  */
-function Terminal({ id, sandbox, lines, live, failed, refused, retry, onRetry, }) {
-    const reachable = live && Boolean(sandbox);
+function Terminal({ id, sandbox, held, lines, live, failed, refused, retry, onRetry, }) {
+    const reachable = Boolean(sandbox) && held === 'running';
     // The shell while there is one, unless the log was asked for.
     const [log, setLog] = useState(false);
     const showShell = reachable && !log;
-    return (_jsxs(YStack, { flex: 1, minH: 0, bg: "$background", children: [_jsxs(XStack, { px: "$2", py: "$1.5", gap: "$1", borderBottomWidth: 1, borderColor: "$borderColor", items: "center", children: [reachable ? (_jsx(XStack, { render: "button", "aria-label": "Shell", onPress: () => setLog(false), px: "$2", py: "$1", rounded: "$2", bg: showShell ? '$hover' : 'transparent', children: _jsx(SizableText, { size: "$1", color: showShell ? '$ink' : '$soft', children: "Shell" }) })) : null, _jsx(XStack, { render: "button", "aria-label": "Agent log", onPress: () => setLog(true), px: "$2", py: "$1", rounded: "$2", bg: showShell ? 'transparent' : '$hover', children: _jsx(SizableText, { size: "$1", color: showShell ? '$soft' : '$ink', children: "Agent log" }) })] }), showShell ? _jsx(Door, { which: "terminal", sandbox: sandbox, live: live, session: `run-${id.replace(/^sess_/, '').slice(0, 12)}` }) : _jsx(Log, { lines: lines, live: live, failed: failed, refused: refused, retry: retry, onRetry: onRetry })] }));
+    return (_jsxs(YStack, { flex: 1, minH: 0, bg: "$background", children: [_jsxs(XStack, { px: "$2", py: "$1.5", gap: "$1", borderBottomWidth: 1, borderColor: "$borderColor", items: "center", children: [reachable ? (_jsx(XStack, { render: "button", "aria-label": "Shell", onPress: () => setLog(false), px: "$2", py: "$1", rounded: "$2", bg: showShell ? '$hover' : 'transparent', children: _jsx(SizableText, { size: "$1", color: showShell ? '$ink' : '$soft', children: "Shell" }) })) : null, _jsx(XStack, { render: "button", "aria-label": "Agent log", onPress: () => setLog(true), px: "$2", py: "$1", rounded: "$2", bg: showShell ? 'transparent' : '$hover', children: _jsx(SizableText, { size: "$1", color: showShell ? '$soft' : '$ink', children: "Agent log" }) })] }), showShell ? _jsx(Door, { which: "terminal", sandbox: sandbox, held: held, session: `run-${id.replace(/^sess_/, '').slice(0, 12)}` }) : _jsx(Log, { lines: lines, live: live, failed: failed, refused: refused, retry: retry, onRetry: onRetry })] }));
 }
 function Log({ lines, live, failed, refused, retry, onRetry, }) {
     const prompt = 'workspace';

package/lib/door.d.ts

@@ -1,7 +1,11 @@
-import { type Door as Which } from './api/sandbox.ts';
-export declare function Door({ which, sandbox, live, session }: {
+import { type Door as Which, type State as Held } from './api/sandbox.ts';
+/**
+ * `held` is where the run's sandbox is in its life, '' until it has been read. Only
+ * a running sandbox has an open door.
+ */
+export declare function Door({ which, sandbox, held, session }: {
     which: Which;
     sandbox: string;
-    live: boolean;
+    held: Held | '';
     session: string;
 }): import("react").JSX.Element;

package/lib/door.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * One door into a run's sandbox — its screen or its shell — framed from cloud's
- * own page with a fresh ticket in its address.
+ * own page with a fresh ticket in its address, while the sandbox runs. A
+ * suspended sandbox is resumed from the pane's bar, never by looking at it.
  *
  * The page says when its socket is up. A page that says it failed, or silence
  * past the deadline, is a failed connection, and Retry mints a new ticket: a
@@ -17,14 +18,18 @@ import { useTarget } from './host.js';
 const SOURCE = { screen: 'hanzo-screen', terminal: 'hanzo-term' };
 const WHAT = { screen: 'desktop', terminal: 'terminal' };
 const DEADLINE = 20_000;
-export function Door({ which, sandbox, live, session }) {
+/**
+ * `held` is where the run's sandbox is in its life, '' until it has been read. Only
+ * a running sandbox has an open door.
+ */
+export function Door({ which, sandbox, held, session }) {
     const t = useTarget();
     const frame = useRef(null);
     const [src, setSrc] = useState('');
     const [state, setState] = useState('opening');
     const [why, setWhy] = useState('');
     const [attempt, setAttempt] = useState(0);
-    const up = live && Boolean(sandbox);
+    const up = Boolean(sandbox) && held === 'running';
     useEffect(() => {
         if (!up)
             return;
@@ -73,12 +78,18 @@ export function Door({ which, sandbox, live, session }) {
             clearTimeout(late);
         };
     }, [src, which]);
-    if (!live) {
-        return _jsx(Shut, { title: "Not running", body: `This run’s ${WHAT[which]} closed when the run stopped.` });
-    }
-    if (!sandbox) {
+    if (!sandbox || held === '' || held === 'pending') {
         return _jsx(Shut, { title: "Starting", body: `The ${WHAT[which]} opens once the run’s sandbox is up.` });
     }
+    if (held === 'parked') {
+        return _jsx(Shut, { title: "Suspended", body: `This run’s sandbox is suspended with its files kept. Resume it from the bar above to open its ${WHAT[which]}.` });
+    }
+    if (held === 'gone') {
+        return _jsx(Shut, { title: "Ended", body: "This run\u2019s sandbox has ended. Its work is on its branch and in its artifacts." });
+    }
+    if (held === 'error') {
+        return _jsx(Shut, { title: "Unavailable", body: `This run’s sandbox could not start, so it has no ${WHAT[which]}.` });
+    }
     if (state === 'failed') {
         return (_jsx(Shut, { title: "Failed to connect", body: why || `Unable to reach the ${WHAT[which]}. The run may have stopped.`, children: _jsx(Button, { size: "sm", variant: "outline", onPress: () => setAttempt((a) => a + 1), children: "Retry" }) }));
     }