@hanzo/build 0.2.29 → 0.2.31

package/lib/api/coding.d.ts

@@ -1,7 +1,9 @@
 /**
- * Starting a coding run.
+ * Starting a coding run, and what it left.
  *
- *   POST /v1/agent/coding → 202 {sessionId, repo, branch, project, routed, targetId}
+ *   POST /v1/agent/coding → 202 {sessionId, repo, branch, routed, targetId}
+ *   GET  /v1/agent/coding/{session}/artifacts          {session, saved, artifacts}
+ *   GET  /v1/agent/coding/{session}/artifacts/{name}   one stored artifact's bytes
  *
  * 202 is ADMITTED, not finished: the answer is the session the run narrates
  * itself in, and the session stream is how it is watched.
@@ -22,6 +24,9 @@
  * `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).
+ *
+ * A sandbox run keeps its sandbox after it ends, so `after` continues the earlier
+ * run in that same sandbox and working tree, resumed if it parked.
  */
 import { type Target } from './call.ts';
 export type Mode = 'build' | 'plan' | 'setup';
@@ -52,7 +57,6 @@ export interface Run {
     session: string;
     repo: string;
     branch: string;
-    project: string;
     routed: boolean;
     target: string;
 }
@@ -78,7 +82,11 @@ export interface Earlier {
     /** Its work is on its own branch (turn.ts `settled`). */
     pushed: boolean;
 }
-/** The earlier run's ask, without the codebase its title leads with (`universe: add the widget`). */
+/**
+ * The earlier run's ask, without the codebase its title leads with (`universe:
+ * add the widget`), or the `new project:` the platform titles a run that made its
+ * codebase with (apps/coding start.go).
+ */
 export declare function headline(title: string, repo: string): string;
 /**
  * A new run continuing an earlier one in its mode: what the person said, and
@@ -89,3 +97,31 @@ export declare function headline(title: string, repo: string): string;
 export declare function followUp(e: Earlier, said: string): Ask;
 /** A build of what a plan run answered: its ask as the title, and the plan to carry out. */
 export declare function approve(e: Earlier, plan: string): Ask;
+/**
+ * The same ask again, where the earlier run worked and in its mode: what a failed
+ * run's Try again starts. `ask` is the person's words as the run recorded them;
+ * with none recorded, its title's.
+ */
+export declare function retry(e: Earlier, ask: string): Ask;
+/** What a run left: a changed file, the whole change as a patch, or a link. */
+export type Kind = 'file' | 'patch' | 'preview' | 'pull' | 'deploy';
+export interface Artifact {
+    /** A changed file's path in the workspace, `changes.patch`, or a link's name. */
+    name: string;
+    kind: Kind;
+    /** A stored artifact's length in bytes; 0 for a link. */
+    size: number;
+    /** Where a link points: a preview's host, a pull request, a deployment. */
+    url: string;
+    /** A preview's port in the run's sandbox. */
+    port: number;
+}
+export interface Left {
+    /** When the artifacts were saved, or '' while the run has saved none. */
+    saved: string;
+    artifacts: Artifact[];
+}
+/** What a run left, kept after its sandbox is gone. */
+export declare function artifacts(t: Target, session: string): Promise<Left>;
+/** One stored artifact's bytes. */
+export declare function artifact(t: Target, session: string, name: string): Promise<Blob>;

package/lib/api/coding.js

@@ -1,7 +1,9 @@
 /**
- * Starting a coding run.
+ * Starting a coding run, and what it left.
  *
- *   POST /v1/agent/coding → 202 {sessionId, repo, branch, project, routed, targetId}
+ *   POST /v1/agent/coding → 202 {sessionId, repo, branch, routed, targetId}
+ *   GET  /v1/agent/coding/{session}/artifacts          {session, saved, artifacts}
+ *   GET  /v1/agent/coding/{session}/artifacts/{name}   one stored artifact's bytes
  *
  * 202 is ADMITTED, not finished: the answer is the session the run narrates
  * itself in, and the session stream is how it is watched.
@@ -22,8 +24,11 @@
  * `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).
+ *
+ * A sandbox run keeps its sandbox after it ends, so `after` continues the earlier
+ * run in that same sandbox and working tree, resumed if it parked.
  */
-import { call, Refusal } from './call.js';
+import { call, headers, reason, Refusal, seg } from './call.js';
 /** Why this mode cannot run where it is sent, or '' when it can. */
 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 Cloud, or switch to Build.`
@@ -58,23 +63,29 @@ export async function start(t, ask) {
         session: s('sessionId'),
         repo: s('repo'),
         branch: s('branch'),
-        project: s('project'),
         routed: r?.routed === true,
         target: s('targetId'),
     };
 }
-/** The earlier run's ask, without the codebase its title leads with (`universe: add the widget`). */
+/**
+ * The earlier run's ask, without the codebase its title leads with (`universe:
+ * add the widget`), or the `new project:` the platform titles a run that made its
+ * codebase with (apps/coding start.go).
+ */
 export function headline(title, repo) {
     const name = repo.split('/').filter(Boolean).pop() ?? '';
     const t = title.trim();
-    return name && t.startsWith(`${name}: `) ? t.slice(name.length + 2).trim() : t;
+    for (const lead of [name, 'new project'])
+        if (lead && t.startsWith(`${lead}: `))
+            return t.slice(lead.length + 2).trim();
+    return t;
 }
 /**
- * The same codebase, place and project as the earlier run, starting from its
- * branch when it pushed one. `after` IS that branch as the base (BaseOf,
- * apps/coding coding.go), so it is named only then: a plan, a setup, or a build
- * that changed nothing pushed no branch to clone, and its follow-up starts where
- * it did.
+ * The same codebase, place and project as the earlier run. In the sandbox it goes
+ * on in the earlier run's own sandbox and working tree (`after`), whatever that
+ * run pushed. A machine keeps no sandbox: there `after` is the branch the earlier
+ * run pushed, named only when it pushed one, and otherwise the follow-up starts
+ * where it did.
  */
 function from(e) {
     const place = e.environment && e.environment !== 'sandbox' ? e.environment : undefined;
@@ -82,7 +93,7 @@ function from(e) {
         repo: e.repo || undefined,
         project: e.project || undefined,
         targetId: place,
-        ...(e.pushed ? { after: e.id } : { base: e.base || undefined }),
+        ...(!place || e.pushed ? { after: e.id } : { base: e.base || undefined }),
     };
 }
 const modeOf = (m) => (m === 'plan' || m === 'setup' ? m : 'build');
@@ -112,3 +123,39 @@ export function approve(e, plan) {
     const ask = `Carry out this plan:\n\n${plan.trim()}`;
     return { ...from(e), prompt: head ? `${head}\n\n${ask}` : ask, mode: 'build' };
 }
+/**
+ * The same ask again, where the earlier run worked and in its mode: what a failed
+ * run's Try again starts. `ask` is the person's words as the run recorded them;
+ * with none recorded, its title's.
+ */
+export function retry(e, ask) {
+    return { ...from(e), prompt: ask.trim() || headline(e.title, e.repo), mode: modeOf(e.mode) };
+}
+const KINDS = ['file', 'patch', 'preview', 'pull', 'deploy'];
+/** What a run left, kept after its sandbox is gone. */
+export async function artifacts(t, session) {
+    const r = (await call(t, 'GET', `/v1/agent/coding/${seg(session)}/artifacts`)) ?? {};
+    const list = Array.isArray(r.artifacts) ? r.artifacts : [];
+    return {
+        saved: typeof r.saved === 'string' ? r.saved : '',
+        artifacts: list.flatMap((raw) => {
+            const a = raw && typeof raw === 'object' ? raw : {};
+            const kind = KINDS.find((k) => k === a.kind);
+            const name = typeof a.name === 'string' ? a.name : '';
+            if (!kind || !name)
+                return [];
+            return [{ name, kind, size: typeof a.size === 'number' ? a.size : 0, url: typeof a.url === 'string' ? a.url : '', port: typeof a.port === 'number' ? a.port : 0 }];
+        }),
+    };
+}
+/** One stored artifact's bytes. */
+export async function artifact(t, session, name) {
+    const parts = name.split('/');
+    if (parts.some((p) => p === '' || p === '.' || p === '..'))
+        throw new Refusal(400, 'That artifact has no name to fetch it by');
+    const res = await fetch(`${t.api}/v1/agent/coding/${seg(session)}/artifacts/${parts.map(seg).join('/')}`, { headers: headers(t), cache: 'no-store' });
+    if (!res.ok)
+        throw new Refusal(res.status, (await reason(res)) || `The artifact answered ${res.status}`);
+    // Bytes, whatever type the store named: a page is saved, never opened here.
+    return new Blob([await res.arrayBuffer()], { type: 'application/octet-stream' });
+}

package/lib/api/sandbox.d.ts

@@ -1,20 +1,53 @@
 /**
- * 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.
+ * A run's sandbox. It outlives the run: kept after the run ends, parked (its pod
+ * stopped, its disk and working tree kept) while nobody watches, and retired a
+ * day after it parks; a free plan's sandbox is not parked, and ends within the
+ * hour. Resume gives a parked one a pod again under the same id and tree.
  *
- *   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
+ *   GET  /v1/sandbox/{id}                              its status and when its lease ends
+ *   POST /v1/sandbox/{id}/pause                        park it: stop the pod, keep the disk
+ *   POST /v1/sandbox/{id}/resume                       a pod again, same id and /work
+ *   POST /v1/sandbox/{id}/{screen|terminal}/ticket     one ticket, spent when the page's socket opens (30 s)
+ *   GET  /v1/sandbox/{id}/ports                        what listens in it, each with its preview host
+ *   POST /v1/sandbox/{id}/preview {port}               an address that opens that port in a browser
+ *   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.
+ * A door or a preview asked of a sandbox that stopped as it was asked is 409: it
+ * is resumed, and asked again once.
  */
 import { type Target } from './call.ts';
 export type Door = 'screen' | 'terminal';
+/** Where a sandbox is in its life. */
+export type State = 'pending' | 'running' | 'parked' | 'error' | 'gone';
+export interface Box {
+    id: string;
+    state: State;
+    /** When its lease ends, or a parked sandbox is retired; 0 when unknown. Unix ms. */
+    ends: number;
+    /** Why it could not come up, with state `error`. */
+    error: string;
+}
+/** The sandbox as it stands. One the caller no longer holds is gone. */
+export declare function sandbox(t: Target, id: string): Promise<Box>;
+/** Park it: its pod stops, its disk and working tree stay. */
+export declare function park(t: Target, id: string): Promise<Box>;
+/** Give it a pod again, under the same id and tree. */
+export declare function wake(t: Target, id: string): Promise<Box>;
 /** 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 declare function door(t: Target, id: string, which: Door, session?: string): Promise<string>;
+export interface Port {
+    port: number;
+    host: string;
+}
+/** What listens in the sandbox, ascending. */
+export declare function ports(t: Target, id: string): Promise<Port[]>;
+/**
+ * An address that opens one port in a browser: its own origin, with a single-use
+ * ticket that sets the preview's cookie and lands on its root.
+ */
+export declare function preview(t: Target, id: string, port: number): Promise<string>;
 export interface Node {
     /** The resolved path inside the sandbox. */
     path: string;

package/lib/api/sandbox.js

@@ -1,26 +1,115 @@
 /**
- * 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.
+ * A run's sandbox. It outlives the run: kept after the run ends, parked (its pod
+ * stopped, its disk and working tree kept) while nobody watches, and retired a
+ * day after it parks; a free plan's sandbox is not parked, and ends within the
+ * hour. Resume gives a parked one a pod again under the same id and tree.
  *
- *   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
+ *   GET  /v1/sandbox/{id}                              its status and when its lease ends
+ *   POST /v1/sandbox/{id}/pause                        park it: stop the pod, keep the disk
+ *   POST /v1/sandbox/{id}/resume                       a pod again, same id and /work
+ *   POST /v1/sandbox/{id}/{screen|terminal}/ticket     one ticket, spent when the page's socket opens (30 s)
+ *   GET  /v1/sandbox/{id}/ports                        what listens in it, each with its preview host
+ *   POST /v1/sandbox/{id}/preview {port}               an address that opens that port in a browser
+ *   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.
+ * A door or a preview asked of a sandbox that stopped as it was asked is 409: it
+ * is resumed, and asked again once.
  */
 import { call, Refusal, seg } from './call.js';
+const STATES = ['pending', 'running', 'parked', 'error'];
+function box(raw, id) {
+    const o = raw && typeof raw === 'object' ? raw : {};
+    // A parked sandbox is also said to be paused; a status this does not know is not one to open.
+    const state = STATES.find((s) => s === (o.status === 'paused' ? 'parked' : o.status)) ?? 'error';
+    const ends = typeof o.expiresAt === 'number' && o.expiresAt > 0 ? o.expiresAt * 1000 : 0;
+    return { id, state, ends, error: typeof o.error === 'string' ? o.error : '' };
+}
+/** The sandbox as it stands. One the caller no longer holds is gone. */
+export async function sandbox(t, id) {
+    try {
+        return box(await call(t, 'GET', `/v1/sandbox/${seg(id)}`), id);
+    }
+    catch (e) {
+        if (e instanceof Refusal && e.status === 404)
+            return { id, state: 'gone', ends: 0, error: '' };
+        throw e;
+    }
+}
+/** Park it: its pod stops, its disk and working tree stay. */
+export async function park(t, id) {
+    return box(await call(t, 'POST', `/v1/sandbox/${seg(id)}/pause`), id);
+}
+/** Give it a pod again, under the same id and tree. */
+export async function wake(t, id) {
+    return box(await call(t, 'POST', `/v1/sandbox/${seg(id)}/resume`), id);
+}
+/** How long a resumed sandbox is waited on to run. */
+const UP = 90_000;
+/** Resume it and wait until it runs. */
+async function up(t, id) {
+    let b = await wake(t, id);
+    const until = Date.now() + UP;
+    while (b.state === 'pending' && Date.now() < until) {
+        await new Promise((r) => setTimeout(r, 1500));
+        b = await sandbox(t, id);
+    }
+    if (b.state !== 'running')
+        throw new Refusal(503, b.error || 'The sandbox did not start again. Try again.');
+}
+/** Asks what needs a running sandbox; a parked one is resumed first. */
+async function running(t, id, ask) {
+    try {
+        return await ask();
+    }
+    catch (e) {
+        if (!(e instanceof Refusal) || e.status !== 409)
+            throw e;
+        await up(t, id);
+        return ask();
+    }
+}
 /** 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`);
+export async function door(t, id, which, session = '') {
+    const r = await running(t, id, () => call(t, 'POST', `/v1/sandbox/${seg(id)}/${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 listens in the sandbox, ascending. */
+export async function ports(t, id) {
+    const r = await call(t, 'GET', `/v1/sandbox/${seg(id)}/ports`);
+    const list = Array.isArray(r?.ports) ? r.ports : [];
+    return list
+        .map((p) => (p && typeof p === 'object' ? p : {}))
+        .filter((p) => typeof p.port === 'number' && p.port > 0 && p.port < 65536)
+        .map((p) => ({
+        port: p.port,
+        host: typeof p.host === 'string' ? p.host : '',
+    }));
+}
+/**
+ * An address that opens one port in a browser: its own origin, with a single-use
+ * ticket that sets the preview's cookie and lands on its root.
+ */
+export async function preview(t, id, port) {
+    const r = await running(t, id, () => call(t, 'POST', `/v1/sandbox/${seg(id)}/preview`, {
+        port,
+    }));
+    let url;
+    try {
+        url = new URL(typeof r?.url === 'string' ? r.url : '');
+    }
+    catch {
+        throw new Refusal(502, 'The sandbox answered with no address to open');
+    }
+    if (url.protocol !== 'https:')
+        throw new Refusal(502, 'The sandbox answered with no address to open');
+    return url.href;
+}
 /** What a file shows at most. */
 const CAP = 1 << 20;
 /** One path in the sandbox, relative to its working directory. */

package/lib/api/turn.d.ts

@@ -1,3 +1,26 @@
+/**
+ * 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 of the
+ * run itself, `event` for one line of the agent's own structured narration (the
+ * harness's JSON stream: its messages, reasoning, commands, edits, tool calls and
+ * plan), and `log` for raw output, which only the Terminal's log shows. 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
+ * items, never its log.
+ */
 import type { Event } from './sessions.ts';
 /** The payload as an object. A live frame may carry it as a JSON string. */
 export declare function decode(payload: unknown): Record<string, unknown> | string | null;
@@ -56,6 +79,8 @@ export interface Outcome {
  * the branch and the pull request are read from the run's record (`pull`).
  */
 export declare function outcome(events: Pick<Event, 'kind' | 'payload' | 'seq'>[]): Outcome;
+/** Why the run failed, as its last status says it, or '' when that status is not a failure. */
+export declare function failure(events: Pick<Event, 'kind' | 'payload' | 'seq'>[]): string;
 /** The turns, ordered and deduped: a recorded read and the live feed overlap. */
 export declare function merge<T extends Pick<Event, 'id' | 'seq'>>(...lists: T[][]): T[];
 /** The actor, short enough to label a block: `hanzo/2d4d67ab`, not the whole subject. */
@@ -78,10 +103,11 @@ export type Ran = 'running' | 'done' | 'error' | 'cancelled';
  * One piece of the transcript, drawn by what it is.
  *
  *   said   prose: the agent's messages (markdown), or a person's steering words
+ *   think  the agent's reasoning, folded until opened
  *   shell  a command the agent ran, and what it printed
- *   edit   files the agent changed, with the diff when the harness printed one
- *   read   a file the agent read, drawn as a chip
+ *   edit   files the agent changed; the diff is the run's Git tab
  *   step   a step of the run itself (lease, clone, install, push), or a tool the agent called
+ *   todo   the agent's plan, as a checklist it ticks
  *   note   a lifecycle line: started, pushed, stopped
  *   plan   a plan run's answer, which can be approved into a build
  */
@@ -90,6 +116,10 @@ export type Card = {
     key: string;
     who: 'person' | 'agent';
     text: string;
+} | {
+    kind: 'think';
+    key: string;
+    text: string;
 } | {
     kind: 'shell';
     key: string;
@@ -100,12 +130,6 @@ export type Card = {
     kind: 'edit';
     key: string;
     files: string[];
-    patch: string;
-    ran: Ran;
-} | {
-    kind: 'read';
-    key: string;
-    file: string;
     ran: Ran;
 } | {
     kind: 'step';
@@ -114,6 +138,13 @@ export type Card = {
     detail: string;
     output: string;
     ran: Ran;
+} | {
+    kind: 'todo';
+    key: string;
+    items: {
+        text: string;
+        done: boolean;
+    }[];
 } | {
     kind: 'note';
     key: string;
@@ -127,12 +158,14 @@ export type Card = {
  * 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 declare function cards(events: Pick<Event, 'kind' | 'payload' | 'seq'>[], mode?: string): Card[];
 /** The plan a plan run answered with, from its final status, or ''. */