@hanzo/build 0.2.9 → 0.2.10

package/README.md

@@ -106,7 +106,29 @@ codebase or an issue from its own screen lands here with that choice already
 made.
 
 **A run.** The transcript as it streams, steering while it works, Stop, and
-the pull request once it pushes one.
+the pull request once it pushes one. Beside it:
+
+- Environment: the codebase's environment, and the run's facts.
+- Git: what it pushed, read from the forge — Diff, Review, Commits.
+- Desktop: its sandbox's screen, framed from the sandbox's own noVNC page. A
+  sandbox run asks for a desktop.
+- Terminal: a shell in the same working tree (a tmux session named for the run,
+  so it reattaches), and the agent's own log.
+- Files: the working tree live from the sandbox, or the run's branch; and
+  Artifacts, what it produced.
+- Subscriptions.
+
+The desktop and the shell are the sandbox's, so they close when the run stops.
+The setup bar says how long setup runs here have taken, once there are three.
+
+**An environment.** What a sandbox run does to its codebase's checkout before
+the agent starts: the install script, the start command, and the secrets it
+exports. New offers to set one up when the chosen codebase has none. Start the
+agent, and a run in mode `setup`, titled by the prompt's first line and working
+through its steps, explores, installs and checks the codebase. Its answer is kept
+as a proposal the Environment tab shows in its editors until an org admin saves
+it. Or an org admin skips and saves it empty, and writes the scripts beside the
+next run. Secret values are sealed in KMS and never shown again.
 
 **A project.** The v2 workspace in the same window: its runs as a
 conversation with suggestions and a Build/Plan composer on the left; Preview,
@@ -123,6 +145,10 @@ picker and open-in-tab; Share and Publish; the console dock under it.
 | `POST /v1/agent/sessions/{id}/message` · `/stop` | steer, stop |
 | `GET /v1/agent/targets` | the org's machines |
 | `GET /v1/auto/flows` · `POST /v1/auto/flows` · `POST /v1/auto/flows/{id}/enable` | automations |
+| `GET /v1/environment` · `GET`/`PUT`/`DELETE /v1/environment/{repo}` · `PUT`/`DELETE …/secrets/{name}` | a codebase's environment |
+| `GET /v1/agent/coding/{session}/changes` · `/tree` · `/blob` | what a run pushed, and its branch's files, from the forge |
+| `POST /v1/sandbox/{id}/screen/ticket` · `…/terminal/ticket` | the run's desktop and shell, framed with a single-use ticket |
+| `POST /v1/sandbox/read` | the run's working tree, live |
 | `GET /v1/provider/github/repos` · `POST /v1/provider/github/repos/import` | granted repositories, and bringing them onto the forge |
 | `GET /v1/git/repos` · `GET /v1/git/repos/{name}` | the codebase chip, and its branches |
 | `GET /v1/task/projects` · `GET /v1/task/board` · `GET /v1/task/projects/{key}/issues` | boards and issues, read from the forge |
@@ -146,6 +172,11 @@ src/
   landing.tsx   New
   forge.tsx     Codebase, Automations, Projects, Issues
   run.tsx       one run
+  desk.tsx      the pane beside a run
+  door.tsx      a run's desktop or shell, framed
+  git.tsx       what a run pushed
+  files.tsx     a run's files and artifacts
+  environment.tsx a codebase's environment
   project.tsx   a project's workspace
   shelf.tsx     Artifacts and Templates
   publish.tsx   Add to project / Publish

package/lib/api/changes.d.ts

@@ -0,0 +1,56 @@
+/**
+ * What a run changed, read from the forge it pushed to, as the person asking.
+ *
+ *   GET /v1/agent/coding/{session}/changes     commits base..head, each file's patch, the pull request
+ *   GET /v1/agent/coding/{session}/tree?path=  one directory at the run's branch (its base until it pushes)
+ *   GET /v1/agent/coding/{session}/blob?path=  one file there, in /v1/git's blob shape
+ *
+ * Before the run pushes, changes answers empty, not 404.
+ */
+import { type Target } from './call.ts';
+import { type Blob, type Entry } from './git.ts';
+export interface Commit {
+    sha: string;
+    /** The first line. */
+    message: string;
+    author: string;
+    date: string;
+}
+export interface Change {
+    path: string;
+    /** The old path of a rename, or ''. */
+    from: string;
+    status: 'added' | 'modified' | 'deleted' | 'renamed';
+    additions: number;
+    deletions: number;
+    /** The file's unified diff hunks, or '' for a binary file. */
+    patch: string;
+    truncated: boolean;
+}
+export interface Review {
+    author: string;
+    state: string;
+    body: string;
+    at: string;
+}
+export interface Pull {
+    number: number;
+    url: string;
+    title: string;
+    state: 'open' | 'closed' | 'merged';
+    /** Null when the forge has not worked it out. */
+    mergeable: boolean | null;
+    reviews: Review[];
+}
+export interface Changes {
+    repo: string;
+    base: string;
+    head: string;
+    commits: Commit[];
+    files: Change[];
+    pull: Pull | null;
+}
+export declare function changes(raw: unknown): Changes;
+export declare function read(t: Target, session: string): Promise<Changes>;
+export declare function tree(t: Target, session: string, path?: string): Promise<Entry[]>;
+export declare function blob(t: Target, session: string, path: string): Promise<Blob>;

package/lib/api/changes.js

@@ -0,0 +1,63 @@
+/**
+ * What a run changed, read from the forge it pushed to, as the person asking.
+ *
+ *   GET /v1/agent/coding/{session}/changes     commits base..head, each file's patch, the pull request
+ *   GET /v1/agent/coding/{session}/tree?path=  one directory at the run's branch (its base until it pushes)
+ *   GET /v1/agent/coding/{session}/blob?path=  one file there, in /v1/git's blob shape
+ *
+ * Before the run pushes, changes answers empty, not 404.
+ */
+import { call, query, seg } from './call.js';
+import { entries, file } from './git.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const obj = (v) => (v && typeof v === 'object' ? v : {});
+const arr = (v) => (Array.isArray(v) ? v : []);
+const STATUS = ['added', 'modified', 'deleted', 'renamed'];
+const PULL = ['open', 'closed', 'merged'];
+export function changes(raw) {
+    const o = obj(raw);
+    const p = o.pull ? obj(o.pull) : null;
+    return {
+        repo: str(o.repo),
+        base: str(o.base),
+        head: str(o.head),
+        commits: arr(o.commits)
+            .map(obj)
+            .map((c) => ({ sha: str(c.sha), message: str(c.message), author: str(c.author), date: str(c.date) }))
+            .filter((c) => c.sha),
+        files: arr(o.files)
+            .map(obj)
+            .map((f) => ({
+            path: str(f.path),
+            from: str(f.from),
+            status: STATUS.find((s) => s === f.status) ?? 'modified',
+            additions: num(f.additions),
+            deletions: num(f.deletions),
+            patch: str(f.patch),
+            truncated: f.truncated === true,
+        }))
+            .filter((f) => f.path),
+        pull: p && num(p.number)
+            ? {
+                number: num(p.number),
+                url: str(p.url),
+                title: str(p.title),
+                state: PULL.find((s) => s === p.state) ?? 'open',
+                mergeable: typeof p.mergeable === 'boolean' ? p.mergeable : null,
+                reviews: arr(p.reviews)
+                    .map(obj)
+                    .map((r) => ({ author: str(r.author), state: str(r.state), body: str(r.body), at: str(r.at) })),
+            }
+            : null,
+    };
+}
+export async function read(t, session) {
+    return changes(await call(t, 'GET', `/v1/agent/coding/${seg(session)}/changes`));
+}
+export async function tree(t, session, path = '') {
+    return entries(await call(t, 'GET', `/v1/agent/coding/${seg(session)}/tree${query({ path })}`));
+}
+export async function blob(t, session, path) {
+    return file(await call(t, 'GET', `/v1/agent/coding/${seg(session)}/blob${query({ path })}`), path);
+}

package/lib/api/coding.d.ts

@@ -18,9 +18,13 @@
  *
  * `model` and `effort` are taken by the dev harness the builder runs (and by
  * codex); the builder names no other harness, so they are always honoured.
+ *
+ * `setup` is a plan's shape put to one question: how this codebase is installed,
+ * started and checked. Its agent may install and run things in its sandbox, and
+ * its answer is kept as the codebase's proposed environment (environment.ts).
  */
 import { type Target } from './call.ts';
-export type Mode = 'build' | 'plan';
+export type Mode = 'build' | 'plan' | 'setup';
 /** Why this mode cannot run where it is sent, or '' when it can. */
 export declare const unhonoured: (mode: Mode | undefined, target?: string) => string;
 export interface Ask {
@@ -48,6 +52,10 @@ export interface Run {
     routed: boolean;
     target: string;
 }
-/** The request body: only what was asked, with no empty strings sent as values. */
-export declare function body(ask: Ask): Record<string, string>;
+/**
+ * The request body: only what was asked, with no empty strings sent as values.
+ * A run in the sandbox asks for one with a desktop, so its Desktop tab has a
+ * screen to show; a machine is whatever it is.
+ */
+export declare function body(ask: Ask): Record<string, string | boolean>;
 export declare function start(t: Target, ask: Ask): Promise<Run>;

package/lib/api/coding.js

@@ -18,13 +18,21 @@
  *
  * `model` and `effort` are taken by the dev harness the builder runs (and by
  * codex); the builder names no other harness, so they are always honoured.
+ *
+ * `setup` is a plan's shape put to one question: how this codebase is installed,
+ * started and checked. Its agent may install and run things in its sandbox, and
+ * its answer is kept as the codebase's proposed environment (environment.ts).
  */
 import { call, Refusal } from './call.js';
 /** Why this mode cannot run where it is sent, or '' when it can. */
-export const unhonoured = (mode, target) => mode === 'plan' && target?.trim()
-    ? 'A plan runs in the Hanzo sandbox: a machine clones and pushes with its own credential. Choose Default, or switch to Build.'
+export const unhonoured = (mode, target) => (mode === 'plan' || mode === 'setup') && target?.trim()
+    ? `A ${mode} runs in the Hanzo sandbox: a machine clones and pushes with its own credential. Choose Default, or switch to Build.`
     : '';
-/** The request body: only what was asked, with no empty strings sent as values. */
+/**
+ * The request body: only what was asked, with no empty strings sent as values.
+ * A run in the sandbox asks for one with a desktop, so its Desktop tab has a
+ * screen to show; a machine is whatever it is.
+ */
 export function body(ask) {
     const out = { prompt: ask.prompt.trim() };
     for (const k of ['repo', 'base', 'targetId', 'project', 'after', 'mode', 'model', 'effort']) {
@@ -32,6 +40,8 @@ export function body(ask) {
         if (v)
             out[k] = v;
     }
+    if (!out.targetId)
+        out.desktop = true;
     return out;
 }
 export async function start(t, ask) {

package/lib/api/environment.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A codebase's environment: what a run does to its checkout before the agent
+ * starts, and which secrets it exports.
+ *
+ *   GET    /v1/environment                      {data: [environment]}
+ *   GET    /v1/environment/{repo}               one; a codebase with none answers state "none"
+ *   PUT    /v1/environment/{repo}               save {install, start} (org admin)
+ *   DELETE /v1/environment/{repo}               forget it and its secrets (org admin)
+ *   PUT    /v1/environment/{repo}/secrets/{name}  set one value (org admin)
+ *   DELETE /v1/environment/{repo}/secrets/{name}  remove one (org admin)
+ *
+ * A setup run is a coding run in mode `setup` (coding.ts): its agent explores the
+ * checkout, installs and checks what it finds, and the platform keeps its answer
+ * here as `proposal` until someone saves it. Secrets are names only; their values
+ * are sealed in KMS and reach the run's environment, never this record.
+ */
+import { type Target } from './call.ts';
+export type State = 'none' | 'proposed' | 'ready';
+export interface Proposal {
+    install: string;
+    start: string;
+    /** Variables the agent found the codebase reads. Some may not be set yet. */
+    secrets: string[];
+    /** What the setup agent found and checked, in its own words. */
+    note: string;
+}
+export interface Environment {
+    repo: string;
+    install: string;
+    start: string;
+    /** The names set on this codebase. Values are never answered. */
+    secrets: string[];
+    state: State;
+    /** The setup run that produced the proposal, or ''. */
+    session: string;
+    proposal: Proposal | null;
+    updated: string;
+}
+export declare function environment(raw: unknown, repo?: string): Environment;
+export declare function environments(t: Target): Promise<Environment[]>;
+export declare function read(t: Target, repo: string): Promise<Environment>;
+export declare function save(t: Target, repo: string, scripts: {
+    install: string;
+    start: string;
+}): Promise<Environment>;
+export declare function forget(t: Target, repo: string): Promise<void>;
+/** An environment variable name the run can export, and not one of its own. */
+export declare const NAME: RegExp;
+/** Why a secret name cannot be set, or '' when it can. */
+export declare function refuse(name: string): string;
+export declare function setSecret(t: Target, repo: string, name: string, value: string): Promise<Environment>;
+export declare function removeSecret(t: Target, repo: string, name: string): Promise<Environment>;
+/**
+ * What a setup run is asked. The first line is the run's title, the steps are
+ * its checklist, and the platform puts its own instructions ahead of both.
+ */
+export declare const SETUP: string;

package/lib/api/environment.js

@@ -0,0 +1,85 @@
+/**
+ * A codebase's environment: what a run does to its checkout before the agent
+ * starts, and which secrets it exports.
+ *
+ *   GET    /v1/environment                      {data: [environment]}
+ *   GET    /v1/environment/{repo}               one; a codebase with none answers state "none"
+ *   PUT    /v1/environment/{repo}               save {install, start} (org admin)
+ *   DELETE /v1/environment/{repo}               forget it and its secrets (org admin)
+ *   PUT    /v1/environment/{repo}/secrets/{name}  set one value (org admin)
+ *   DELETE /v1/environment/{repo}/secrets/{name}  remove one (org admin)
+ *
+ * A setup run is a coding run in mode `setup` (coding.ts): its agent explores the
+ * checkout, installs and checks what it finds, and the platform keeps its answer
+ * here as `proposal` until someone saves it. Secrets are names only; their values
+ * are sealed in KMS and reach the run's environment, never this record.
+ */
+import { call, seg } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const obj = (v) => (v && typeof v === 'object' ? v : {});
+const names = (v) => (Array.isArray(v) ? v.filter((n) => typeof n === 'string' && n !== '') : []);
+const STATES = ['none', 'proposed', 'ready'];
+export function environment(raw, repo = '') {
+    const o = obj(raw);
+    const p = o.proposal ? obj(o.proposal) : null;
+    const state = str(o.state);
+    return {
+        repo: str(o.repo) || repo,
+        install: str(o.install),
+        start: str(o.start),
+        secrets: names(o.secrets),
+        state: STATES.includes(state) ? state : 'none',
+        session: str(o.session),
+        proposal: p ? { install: str(p.install), start: str(p.start), secrets: names(p.secrets), note: str(p.note) } : null,
+        updated: str(o.updatedAt),
+    };
+}
+export async function environments(t) {
+    const r = await call(t, 'GET', '/v1/environment');
+    return (Array.isArray(r?.data) ? r.data : []).map((e) => environment(e)).filter((e) => e.repo);
+}
+export async function read(t, repo) {
+    return environment(await call(t, 'GET', `/v1/environment/${seg(repo)}`), repo);
+}
+export async function save(t, repo, scripts) {
+    return environment(await call(t, 'PUT', `/v1/environment/${seg(repo)}`, scripts), repo);
+}
+export async function forget(t, repo) {
+    await call(t, 'DELETE', `/v1/environment/${seg(repo)}`);
+}
+/** An environment variable name the run can export, and not one of its own. */
+export const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const RESERVED = ['PATH', 'HOME', 'USER', 'SHELL', 'PWD', 'HOSTNAME', 'IFS', 'ENV', 'BASH_ENV'];
+/** Why a secret name cannot be set, or '' when it can. */
+export function refuse(name) {
+    if (!NAME.test(name))
+        return `${name || 'That'} is not an environment variable name`;
+    const up = name.toUpperCase();
+    if (up.startsWith('HANZO_') || RESERVED.includes(up))
+        return `${name} is reserved for the run itself`;
+    return '';
+}
+export async function setSecret(t, repo, name, value) {
+    const why = refuse(name);
+    if (why)
+        throw new Error(why);
+    if (!value)
+        throw new Error('A secret needs a value');
+    return environment(await call(t, 'PUT', `/v1/environment/${seg(repo)}/secrets/${seg(name)}`, { value }), repo);
+}
+export async function removeSecret(t, repo, name) {
+    return environment(await call(t, 'DELETE', `/v1/environment/${seg(repo)}/secrets/${seg(name)}`), repo);
+}
+/**
+ * What a setup run is asked. The first line is the run's title, the steps are
+ * its checklist, and the platform puts its own instructions ahead of both.
+ */
+export const SETUP = [
+    'Set up the environment',
+    '',
+    '1. Understand the codebase: how it installs, builds, starts and tests.',
+    '2. Write the install script and the start command.',
+    '3. Run both in this fresh checkout.',
+    '4. Check that the build and the tests pass, and that the app answers if it is one.',
+    '5. Answer with what you checked and the environment.',
+].join('\n');

package/lib/api/git.d.ts

@@ -5,8 +5,8 @@
  *   GET /v1/git/repos/{name}/blob?ref=&path=   one file; binary is base64,
  *                                              past 1 MiB it is truncated with no content
  *
- * A run pushes its branch to native git, so these read what a run wrote at the
- * branch it wrote it on.
+ * A run pushes its branch to the forge, not here, so a run's files are read
+ * through the run (changes.ts); these read a codebase as the platform holds it.
  */
 import { type Target } from './call.ts';
 export interface Entry {
@@ -24,4 +24,8 @@ export interface Blob {
     size: number;
 }
 export declare function tree(t: Target, repo: string, ref: string, path?: string): Promise<Entry[]>;
+/** A tree answer's entries. A run's branch on the forge answers in the same shape. */
+export declare function entries(raw: unknown): Entry[];
 export declare function blob(t: Target, repo: string, ref: string, path: string): Promise<Blob>;
+/** A blob answer. A run's branch on the forge answers in the same shape. */
+export declare function file(raw: unknown, path: string): Blob;

package/lib/api/git.js

@@ -5,14 +5,18 @@
  *   GET /v1/git/repos/{name}/blob?ref=&path=   one file; binary is base64,
  *                                              past 1 MiB it is truncated with no content
  *
- * A run pushes its branch to native git, so these read what a run wrote at the
- * branch it wrote it on.
+ * A run pushes its branch to the forge, not here, so a run's files are read
+ * through the run (changes.ts); these read a codebase as the platform holds it.
  */
 import { call, query, seg } from './call.js';
 const str = (v) => (typeof v === 'string' ? v : '');
 export async function tree(t, repo, ref, path = '') {
-    const raw = await call(t, 'GET', `/v1/git/repos/${seg(repo)}/tree${query({ ref, path })}`);
-    const rows = Array.isArray(raw?.entries) ? raw.entries : [];
+    return entries(await call(t, 'GET', `/v1/git/repos/${seg(repo)}/tree${query({ ref, path })}`));
+}
+/** A tree answer's entries. A run's branch on the forge answers in the same shape. */
+export function entries(raw) {
+    const o = (raw && typeof raw === 'object' ? raw : {});
+    const rows = Array.isArray(o.entries) ? o.entries : [];
     return rows
         .map((r) => {
         const o = (r && typeof r === 'object' ? r : {});
@@ -26,7 +30,11 @@ export async function tree(t, repo, ref, path = '') {
         .filter((e) => e.path);
 }
 export async function blob(t, repo, ref, path) {
-    const o = (await call(t, 'GET', `/v1/git/repos/${seg(repo)}/blob${query({ ref, path })}`)) ?? {};
+    return file(await call(t, 'GET', `/v1/git/repos/${seg(repo)}/blob${query({ ref, path })}`), path);
+}
+/** A blob answer. A run's branch on the forge answers in the same shape. */
+export function file(raw, path) {
+    const o = (raw && typeof raw === 'object' ? raw : {});
     const binary = o.binary === true;
     const truncated = o.truncated === true;
     return {

package/lib/api/sandbox.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A run's sandbox while the run holds it: a door into its screen or its shell,
+ * and its working tree as it is right now.
+ *
+ *   POST /v1/sandbox/{id}/{screen|terminal}/ticket  one ticket, spent when the page's socket opens (30 s)
+ *   POST /v1/sandbox/read {id, path}               a directory's names, or a file's bytes
+ *
+ * The door is cloud's own page — noVNC for the screen, xterm for the shell — so
+ * the builder frames it and never speaks the socket itself. The sandbox is gone
+ * when the run ends, and every call here then answers 404.
+ */
+import { type Target } from './call.ts';
+export type Door = 'screen' | 'terminal';
+/** A shell's tmux session name: the sandbox reattaches to it when the door opens again. */
+export declare const NAME: RegExp;
+/** Where to frame one door, with a fresh ticket in its address. */
+export declare function door(t: Target, sandbox: string, which: Door, session?: string): Promise<string>;
+export interface Node {
+    /** The resolved path inside the sandbox. */
+    path: string;
+    dir: boolean;
+    /** A directory's entries, bare names, sorted. */
+    names: string[];
+    /** A file's text, or '' when it is binary or past the view cap. */
+    text: string;
+    binary: boolean;
+    truncated: boolean;
+}
+/** One path in the sandbox, relative to its working directory. */
+export declare function read(t: Target, sandbox: string, path: string): Promise<Node>;

package/lib/api/sandbox.js

@@ -0,0 +1,49 @@
+/**
+ * A run's sandbox while the run holds it: a door into its screen or its shell,
+ * and its working tree as it is right now.
+ *
+ *   POST /v1/sandbox/{id}/{screen|terminal}/ticket  one ticket, spent when the page's socket opens (30 s)
+ *   POST /v1/sandbox/read {id, path}               a directory's names, or a file's bytes
+ *
+ * The door is cloud's own page — noVNC for the screen, xterm for the shell — so
+ * the builder frames it and never speaks the socket itself. The sandbox is gone
+ * when the run ends, and every call here then answers 404.
+ */
+import { call, Refusal, seg } from './call.js';
+/** A shell's tmux session name: the sandbox reattaches to it when the door opens again. */
+export const NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,63}$/;
+/** Where to frame one door, with a fresh ticket in its address. */
+export async function door(t, sandbox, which, session = '') {
+    const r = await call(t, 'POST', `/v1/sandbox/${seg(sandbox)}/${which}/ticket`);
+    const path = typeof r?.url === 'string' ? r.url : '';
+    if (!path.startsWith('/v1/'))
+        throw new Refusal(502, 'The sandbox answered with no address to open');
+    const arg = which === 'terminal' && NAME.test(session) ? `&arg=${session}` : '';
+    return `${t.api}${path}${arg}`;
+}
+/** What a file shows at most. */
+const CAP = 1 << 20;
+/** One path in the sandbox, relative to its working directory. */
+export async function read(t, sandbox, path) {
+    const o = (await call(t, 'POST', '/v1/sandbox/read', { id: sandbox, path })) ?? {};
+    const dir = o.dir === true;
+    const names = Array.isArray(o.entries) ? o.entries.filter((n) => typeof n === 'string').sort() : [];
+    const bytes = !dir && typeof o.data === 'string' ? decode(o.data) : new Uint8Array();
+    const binary = bytes.includes(0);
+    const truncated = bytes.length > CAP;
+    return {
+        path: typeof o.path === 'string' ? o.path : path,
+        dir,
+        names,
+        text: binary || truncated ? '' : new TextDecoder().decode(bytes),
+        binary,
+        truncated,
+    };
+}
+function decode(b64) {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}

package/lib/api/sessions.d.ts

@@ -35,6 +35,8 @@ export interface Session {
     mode: string;
     /** The pull request the run proposed, or ''. */
     pr: string;
+    /** The sandbox the run leased, once it has one. It is gone when the run ends. */
+    sandbox: string;
     events: number;
     createdAt: string;
     updatedAt: string;
@@ -54,6 +56,11 @@ export interface Detail extends Session {
 }
 export declare function session(raw: unknown): Session;
 export declare function event(raw: unknown): Event;
+/**
+ * How long runs in one mode took, in whole minutes: the median and the ninetieth
+ * percentile of the finished ones. Null under three, which is too few to say.
+ */
+export declare function took(runs: Session[], mode: string): [number, number] | null;
 export interface ListQuery {
     kind?: string;
     project?: string;

package/lib/api/sessions.js

@@ -34,6 +34,7 @@ export function session(raw) {
         environment: str(s.environment),
         mode: str(s.mode),
         pr: str(s.pr),
+        sandbox: str(s.sandbox),
         events: num(s.events),
         createdAt: str(s.createdAt),
         updatedAt: str(s.updatedAt),
@@ -52,6 +53,21 @@ export function event(raw) {
         createdAt: str(e.createdAt),
     };
 }
+/**
+ * How long runs in one mode took, in whole minutes: the median and the ninetieth
+ * percentile of the finished ones. Null under three, which is too few to say.
+ */
+export function took(runs, mode) {
+    const spans = runs
+        .filter((r) => r.mode === mode && r.status === 'done' && r.endedAt)
+        .map((r) => Date.parse(r.endedAt) - Date.parse(r.createdAt))
+        .filter((ms) => Number.isFinite(ms) && ms > 0)
+        .sort((a, b) => a - b);
+    if (spans.length < 3)
+        return null;
+    const at = (q) => Math.max(1, Math.round(spans[Math.min(spans.length - 1, Math.floor(q * spans.length))] / 60_000));
+    return [at(0.5), at(0.9)];
+}
 export async function list(t, q = {}) {
     const raw = obj(await call(t, 'GET', `/v1/agent/sessions${query({ ...q })}`));
     return (Array.isArray(raw.sessions) ? raw.sessions : []).map(session).filter((s) => s.id);

package/lib/api/turn.js

@@ -34,8 +34,11 @@ function status(b, mode) {
             // A plan's answer IS its final status: the run read and wrote nothing.
             // Whether the run planned is the RECORD's word — any member of the org
             // can append an event saying `mode: plan`, and its text is not an answer.
+            // A setup is a plan put to one question, and answers the same way.
             if (mode === 'plan')
                 return str(b.plan) || 'Planned — the run answered with no plan';
+            if (mode === 'setup')
+                return str(b.plan) || 'Set up — the run answered with no environment';
             if (b.changed === false)
                 return 'Done — nothing to change';
             const pr = str(b.pr);

package/lib/desk.d.ts

@@ -1,5 +1,5 @@
 import type { Event } from './api/sessions.ts';
-export declare function Desk({ id, repo, branch, base, environment, mode, pr, events, live, refused, retry, onRetry, onHide, }: {
+export declare function Desk({ id, repo, branch, base, environment, mode, pr, title, project, sandbox, events, live, refused, retry, onRetry, onHide, }: {
     id: string;
     repo: string;
     branch: string;
@@ -10,6 +10,10 @@ export declare function Desk({ id, repo, branch, base, environment, mode, pr, ev
         href: string;
         label: string;
     };
+    title: string;
+    project: string;
+    /** The sandbox the run holds, or '' before it leases one and on a machine. */
+    sandbox: string;
     events: Event[];
     live: boolean;
     refused: string;