@hanzo/build 0.2.9 → 0.2.11

package/lib/api/harness.js

@@ -0,0 +1,348 @@
+/** Colour codes a terminal would have drawn; a sandbox is not a terminal, but a harness may still print them. */
+const ANSI = /\u001b\[[0-9;?]*[A-Za-z]/g;
+/**
+ * A shell command's words, as `sh` splits them: quotes grouped, `'"'"'`
+ * joined, a backslash escaping the next character outside single quotes.
+ */
+export function words(line) {
+    const out = [];
+    let cur = '';
+    let open = false;
+    let q = '';
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (q === "'") {
+            if (c === "'")
+                q = '';
+            else
+                cur += c;
+            continue;
+        }
+        if (q === '"') {
+            if (c === '"')
+                q = '';
+            else if (c === '\\' && i + 1 < line.length)
+                cur += line[++i];
+            else
+                cur += c;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            q = c;
+            open = true;
+        }
+        else if (c === '\\' && i + 1 < line.length) {
+            cur += line[++i];
+            open = true;
+        }
+        else if (/\s/.test(c)) {
+            if (open)
+                out.push(cur);
+            cur = '';
+            open = false;
+        }
+        else {
+            cur += c;
+            open = true;
+        }
+    }
+    if (open)
+        out.push(cur);
+    return out;
+}
+/** The command a harness ran, out of the `bash -lc '…'` it wraps each one in. */
+export function unwrap(command) {
+    const w = words(command);
+    if (w.length === 3 && /(^|\/)(ba|z)?sh$/.test(w[0]) && (w[1] === '-lc' || w[1] === '-c'))
+        return w[2];
+    return command;
+}
+/**
+ * The file a command only reads, or ''. `cat f`, `nl -ba f`, `sed -n '1,80p' f`,
+ * `head -n 40 f`, `tail f` — one file, and nothing piped, chained or redirected.
+ */
+export function reads(command) {
+    const inner = unwrap(command);
+    if (/[|;&<>`$]/.test(inner))
+        return '';
+    const [cmd, ...args] = words(inner);
+    const one = (xs) => {
+        const files = xs.filter((a) => !a.startsWith('-'));
+        return files.length === 1 ? files[0] : '';
+    };
+    switch (cmd) {
+        case 'cat':
+        case 'nl':
+            return one(args);
+        case 'sed':
+            return args.length === 3 && args[0] === '-n' && /^\d+(,\d+)?p$/.test(args[1]) ? args[2] : '';
+        case 'head':
+        case 'tail':
+            return one(args[0] === '-n' ? args.slice(2) : args);
+    }
+    return '';
+}
+/** A path to show: a relative one as it is, an absolute one by its name — never the sandbox's layout. */
+export const shown = (path) => {
+    if (!path.startsWith('/'))
+        return path;
+    const cut = path.replace(/\/+$/, '');
+    return cut.slice(cut.lastIndexOf('/') + 1);
+};
+/** A unified diff's sections, by the path each changes, from its first hunk on. */
+export function sections(diff) {
+    const out = new Map();
+    let at = '';
+    let lines = [];
+    const close = () => {
+        if (at)
+            out.set(at, lines.join('\n'));
+    };
+    for (const line of diff.split('\n')) {
+        const m = /^diff --git a\/(.+) b\/(.+)$/.exec(line);
+        if (m) {
+            close();
+            at = m[2];
+            lines = [];
+        }
+        else if (at && (lines.length || line.startsWith('@@')))
+            lines.push(line);
+    }
+    close();
+    return out;
+}
+const HEAD = /^(exec|codex|thinking|user|apply patch|tokens used|turn interrupted|context compacted)$/;
+const LEAD = /^(patch|mcp|web search|warning|ERROR|deprecated|model rerouted|hook): /;
+const RESULT = /^\s*(succeeded|exited (-?\d+)|declined|in progress)( in [\d.]+m?s)?:$/;
+/** A reader that appends the cards it finds to `out`, keyed by `mint`. */
+export function harness(out, mint) {
+    let rest = '';
+    let mode = 'prose';
+    // The banner is a rule, the settings, and a rule.
+    let rules = 0;
+    let card = null;
+    let final = [];
+    const open = [];
+    const edits = [];
+    let edit = null;
+    let diff = null;
+    const said = (text) => {
+        const c = { kind: 'said', key: mint(), who: 'agent', text };
+        out.push(c);
+        return c;
+    };
+    const patch = () => {
+        const c = { kind: 'edit', key: mint(), files: [], patch: '', ran: 'running' };
+        out.push(c);
+        edit = { card: c, paths: [] };
+        edits.push(edit);
+        return edit;
+    };
+    // The diff printed after a patch is the turn's so far; the edit keeps the latest.
+    const settle = () => {
+        if (diff && edit)
+            edit.card.patch = diff.join('\n');
+        diff = null;
+    };
+    const step = (name, detail, ran) => {
+        const c = { kind: 'step', key: mint(), name, detail, output: '', ran };
+        out.push(c);
+        return c;
+    };
+    const line = (raw) => {
+        const l = raw.replace(ANSI, '').replace(/\r$/, '');
+        if (mode === 'config') {
+            if (l === '--------' && ++rules === 2)
+                mode = 'prose';
+            return;
+        }
+        if (mode === 'command') {
+            const cut = l.lastIndexOf(' in ');
+            const command = cut > 0 ? l.slice(0, cut) : l;
+            const file = reads(command);
+            const c = file
+                ? { kind: 'read', key: mint(), file: shown(file), ran: 'running' }
+                : { kind: 'shell', key: mint(), command: unwrap(command), output: '', ran: 'running' };
+            out.push(c);
+            open.push(c);
+            card = null;
+            mode = 'prose';
+            return;
+        }
+        if (mode === 'tokens') {
+            mode = 'final';
+            return;
+        }
+        if (mode === 'diff' && !HEAD.test(l) && !LEAD.test(l)) {
+            diff.push(l);
+            return;
+        }
+        const result = RESULT.exec(l);
+        if (result && open.length) {
+            settle();
+            const c = open.pop();
+            c.ran = result[1] === 'succeeded' ? 'done' : result[1] === 'declined' ? 'cancelled' : result[1] === 'in progress' ? 'running' : 'error';
+            card = c;
+            mode = 'output';
+            return;
+        }
+        if (HEAD.test(l)) {
+            settle();
+            card = null;
+            switch (l) {
+                case 'exec':
+                    mode = 'command';
+                    return;
+                case 'codex':
+                case 'thinking':
+                    card = said('');
+                    mode = 'agent';
+                    return;
+                case 'user':
+                    mode = 'user';
+                    return;
+                case 'apply patch':
+                    patch();
+                    mode = 'prose';
+                    return;
+                case 'tokens used':
+                    mode = 'tokens';
+                    return;
+                default:
+                    out.push({ kind: 'note', key: mint(), text: l === 'turn interrupted' ? 'The agent was interrupted' : 'The agent compacted its context' });
+                    mode = 'prose';
+                    return;
+            }
+        }
+        if (/^Hanzo Dev v\S+$/.test(l)) {
+            settle();
+            mode = 'config';
+            rules = 0;
+            return;
+        }
+        const patched = /^patch: (completed|failed|declined|in_progress)$/.exec(l);
+        if (patched) {
+            settle();
+            const e = edit && edit.card.ran === 'running' ? edit : patch();
+            e.card.ran = patched[1] === 'completed' ? 'done' : patched[1] === 'in_progress' ? 'running' : 'error';
+            card = null;
+            mode = 'patch';
+            return;
+        }
+        if (mode === 'patch' && l.startsWith('diff --git ')) {
+            diff = [l];
+            mode = 'diff';
+            return;
+        }
+        const mcp = /^mcp: (\S+) (started|\((completed|failed|in_progress)\))$/.exec(l);
+        if (mcp) {
+            settle();
+            const ran = mcp[3] === 'completed' ? 'done' : mcp[3] === 'failed' ? 'error' : 'running';
+            const started = [...out].reverse().find((c) => c.kind === 'step' && c.name === mcp[1] && c.ran === 'running');
+            if (started && started.kind === 'step' && mcp[2] !== 'started')
+                started.ran = ran;
+            else
+                step(mcp[1], 'tool', ran);
+            card = null;
+            mode = 'prose';
+            return;
+        }
+        const web = /^web search: (.*)$/.exec(l);
+        if (web) {
+            settle();
+            const prior = out[out.length - 1];
+            // Printed when the search starts and again when it lands: one card.
+            if (!(prior && prior.kind === 'step' && prior.name === 'Web search' && prior.detail === web[1]))
+                step('Web search', web[1], 'done');
+            card = null;
+            mode = 'prose';
+            return;
+        }
+        const warn = /^(warning|ERROR|deprecated|model rerouted): ?(.*)$/.exec(l);
+        if (warn) {
+            settle();
+            out.push({ kind: 'note', key: mint(), text: warn[1] === 'ERROR' ? warn[2] : `${warn[1]}: ${warn[2]}` });
+            card = null;
+            mode = 'prose';
+            return;
+        }
+        if (l.startsWith('hook: '))
+            return;
+        const todo = /^ {2}(✓|→|•) (.*)$/.exec(l);
+        if (todo && mode !== 'output' && mode !== 'agent') {
+            const row = `${todo[1] === '✓' ? '✓' : todo[1] === '→' ? '●' : '○'} ${todo[2]}`;
+            if (card && card.kind === 'step' && card.name === 'Plan')
+                card.output += `\n${row}`;
+            else {
+                card = step('Plan', '', 'done');
+                if (card.kind === 'step')
+                    card.output = row;
+            }
+            mode = 'prose';
+            return;
+        }
+        switch (mode) {
+            case 'user':
+                return;
+            case 'patch':
+                if (l.trim() && edit)
+                    edit.paths.push(l.trim());
+                return;
+            case 'final':
+                final.push(l);
+                return;
+            case 'output':
+                if (card && card.kind === 'shell')
+                    card.output += card.output ? `\n${l}` : l;
+                return;
+        }
+        // Prose: what the agent said under its header, or lines no header owns.
+        if (card && card.kind === 'said') {
+            card.text += card.text ? `\n${l}` : l;
+            return;
+        }
+        if (!l.trim())
+            return;
+        card = said(l);
+        mode = 'agent';
+    };
+    return {
+        feed(chunk) {
+            const text = rest + chunk;
+            const lines = text.split('\n');
+            rest = lines.pop() ?? '';
+            for (const l of lines)
+                line(l);
+        },
+        /** The last line even without its newline, and what only the whole output can decide. */
+        end() {
+            if (rest)
+                line(rest);
+            rest = '';
+            settle();
+            // The final message is printed twice: under its header, and bare at the end.
+            const tail = final.join('\n').trim();
+            const spoken = out.filter((c) => c.kind === 'said' && c.who === 'agent').map((c) => c.text.trim());
+            if (tail && !spoken.includes(tail))
+                said(tail);
+            final = [];
+            // A patch names the sandbox's paths; the diff names them as the repository
+            // does, and is the whole turn's, so an edit keeps the sections of its own files.
+            for (const e of edits) {
+                const parts = sections(e.card.patch);
+                const known = [...parts.keys()];
+                e.card.files = e.paths.map((p) => known.find((k) => p === k || p.endsWith(`/${k}`)) ?? shown(p));
+                if (!e.card.files.length)
+                    e.card.files = known;
+                const mine = e.card.files.filter((f) => parts.has(f));
+                e.card.patch = mine.length === 1 ? parts.get(mine[0]) : mine.map((f) => `${f}\n${parts.get(f)}`).join('\n');
+            }
+            edits.length = 0;
+            for (let i = out.length - 1; i >= 0; i--) {
+                const c = out[i];
+                if (c.kind === 'said' && !c.text.trim())
+                    out.splice(i, 1);
+            }
+        },
+    };
+}

package/lib/api/keys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A person's own API keys: one secret key (sk-, it belongs on a server) and one
+ * publishable key (pk-, safe in a page's source), at most one of each.
+ *
+ *   GET    /v1/account/keys             {keys: [{type, prefix, key?, limit?, createdAt}]}
+ *   POST   /v1/account/keys             {type, limit?} → {key, type, limit}, answered once
+ *   DELETE /v1/account/keys?type=…      revoke that one
+ *
+ * Creating is rotating: a new key of a type ends the one before it. A secret key
+ * is answered once and by its prefix after; a publishable key is public by
+ * construction and always comes back whole. A limit only narrows what a key may
+ * reach — `model:zen5`, `project:acme`, `product:commerce`, `model:*`.
+ */
+import { type Target } from './call.ts';
+export declare const KINDS: readonly ['secret', 'publishable'];
+export type Kind = (typeof KINDS)[number];
+export interface Key {
+    type: Kind;
+    /** The recognizable head, never enough to use the key. */
+    prefix: string;
+    /** The whole key: a publishable key's only. */
+    key: string;
+    /** `kind:name` entries; none reaches whatever its holder does. */
+    limit: string[];
+    /** When it last changed, as IAM records it. */
+    created: string;
+}
+export interface Minted {
+    type: Kind;
+    /** The key itself. A secret one is never readable again. */
+    key: string;
+    limit: string[];
+}
+export declare function keys(t: Target): Promise<Key[]>;
+/** A `kind:name` limit: a lowercase kind, a colon, and a name or `*`. */
+export declare const LIMIT: RegExp;
+/** The limits a person typed, split on commas and spaces; throws on the first that is not one. */
+export declare function limits(raw: string): string[];
+/** Create a key of this type, ending the one before it. The answer is the only time a secret key is shown. */
+export declare function mint(t: Target, type: Kind, limit?: string[]): Promise<Minted>;
+export declare function revoke(t: Target, type: Kind): Promise<void>;

package/lib/api/keys.js

@@ -0,0 +1,55 @@
+/**
+ * A person's own API keys: one secret key (sk-, it belongs on a server) and one
+ * publishable key (pk-, safe in a page's source), at most one of each.
+ *
+ *   GET    /v1/account/keys             {keys: [{type, prefix, key?, limit?, createdAt}]}
+ *   POST   /v1/account/keys             {type, limit?} → {key, type, limit}, answered once
+ *   DELETE /v1/account/keys?type=…      revoke that one
+ *
+ * Creating is rotating: a new key of a type ends the one before it. A secret key
+ * is answered once and by its prefix after; a publishable key is public by
+ * construction and always comes back whole. A limit only narrows what a key may
+ * reach — `model:zen5`, `project:acme`, `product:commerce`, `model:*`.
+ */
+import { call, query } from './call.js';
+export const KINDS = ['secret', 'publishable'];
+const str = (v) => (typeof v === 'string' ? v : '');
+const list = (v) => (Array.isArray(v) ? v.filter((s) => typeof s === 'string' && s !== '') : []);
+const kind = (v) => (KINDS.includes(v) ? v : null);
+export async function keys(t) {
+    const r = await call(t, 'GET', '/v1/account/keys');
+    const rows = Array.isArray(r?.keys) ? r.keys : [];
+    const out = [];
+    for (const raw of rows) {
+        const o = (raw && typeof raw === 'object' ? raw : {});
+        const type = kind(o.type);
+        if (!type)
+            continue;
+        out.push({ type, prefix: str(o.prefix), key: str(o.key), limit: list(o.limit), created: str(o.createdAt) });
+    }
+    return out;
+}
+/** A `kind:name` limit: a lowercase kind, a colon, and a name or `*`. */
+export const LIMIT = /^[a-z][a-z0-9-]*:[^\s,:]+$/;
+/** The limits a person typed, split on commas and spaces; throws on the first that is not one. */
+export function limits(raw) {
+    const out = raw
+        .split(/[\s,]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const bad = out.find((s) => !LIMIT.test(s));
+    if (bad)
+        throw new Error(`${bad} is not a limit — write it as kind:name, like model:zen5`);
+    return out;
+}
+/** Create a key of this type, ending the one before it. The answer is the only time a secret key is shown. */
+export async function mint(t, type, limit = []) {
+    const r = await call(t, 'POST', '/v1/account/keys', limit.length ? { type, limit } : { type });
+    const key = str(r?.key) || str(r?.accessKey);
+    if (!key)
+        throw new Error('The platform answered no key');
+    return { type: kind(r?.type) ?? type, key, limit: list(r?.limit) };
+}
+export async function revoke(t, type) {
+    await call(t, 'DELETE', `/v1/account/keys${query({ type })}`);
+}

package/lib/api/machines.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The org's machines: its own computers a run can be sent to, beside the sandbox.
+ *
+ *   GET    /v1/agent/targets            {targets: [...]}, newest first
+ *   POST   /v1/agent/targets            register one by hand {label, kind, host}
+ *   PATCH  /v1/agent/targets/{id}       rename it, drain it, bring it back
+ *   DELETE /v1/agent/targets/{id}       deregister it
+ *   POST   /v1/agent/targets/{id}/key   mint or rotate its claim key, answered once
+ *
+ * A machine belongs to the member who registered it. Only that member or an org
+ * admin changes, removes or keys it, and the platform answers anyone else the
+ * same 404 an unknown id gets — the record names no owner — so a 404 here is
+ * said as that rule. `hanzo link`, run on the machine, registers it under its
+ * hostname and keeps it online while it runs.
+ */
+import { type Target } from './call.ts';
+export declare const KINDS: readonly ['laptop', 'gpu', 'cloud', 'cluster', 'machine'];
+export type Kind = (typeof KINDS)[number];
+export interface Machine {
+    /** `tgt_…` */
+    id: string;
+    label: string;
+    /** laptop | gpu | cloud | cluster | machine */
+    kind: string;
+    /** online | offline | draining, as the platform judges it from the last heartbeat. */
+    status: string;
+    /** "10 vCPU / 122G / 1× GB10", when the machine reported one. */
+    capacity: string;
+    /** The hostname its runs report, or '' for one addressed by id only. */
+    host: string;
+    /** The org's runs mapped to it, and how many of those are running now. */
+    sessions: number;
+    running: number;
+    /** When it last beat, RFC 3339, or '' when it never has. */
+    seen: string;
+}
+export declare function machine(raw: unknown): Machine;
+export declare function machines(t: Target): Promise<Machine[]>;
+/** Register a machine by hand. `hanzo link` on a machine with this hostname takes the row over. */
+export declare function add(t: Target, what: {
+    label: string;
+    kind: Kind;
+    host?: string;
+}): Promise<Machine>;
+/** Rename a machine, or drain it (`draining`) and bring it back (`online`). */
+export declare function change(t: Target, id: string, what: {
+    label?: string;
+    status?: 'online' | 'draining';
+}): Promise<Machine>;
+export declare function remove(t: Target, id: string): Promise<void>;
+/**
+ * Mint the machine's claim key, answered this once: only its hash is kept, and
+ * minting again ends the key before it. A runner on the machine sends it as
+ * `X-Target-Key` when it claims the runs sent there.
+ */
+export declare function key(t: Target, id: string): Promise<string>;

package/lib/api/machines.js

@@ -0,0 +1,84 @@
+/**
+ * The org's machines: its own computers a run can be sent to, beside the sandbox.
+ *
+ *   GET    /v1/agent/targets            {targets: [...]}, newest first
+ *   POST   /v1/agent/targets            register one by hand {label, kind, host}
+ *   PATCH  /v1/agent/targets/{id}       rename it, drain it, bring it back
+ *   DELETE /v1/agent/targets/{id}       deregister it
+ *   POST   /v1/agent/targets/{id}/key   mint or rotate its claim key, answered once
+ *
+ * A machine belongs to the member who registered it. Only that member or an org
+ * admin changes, removes or keys it, and the platform answers anyone else the
+ * same 404 an unknown id gets — the record names no owner — so a 404 here is
+ * said as that rule. `hanzo link`, run on the machine, registers it under its
+ * hostname and keeps it online while it runs.
+ */
+import { call, Refusal, seg } from './call.js';
+export const KINDS = ['laptop', 'gpu', 'cloud', 'cluster', 'machine'];
+const str = (v) => (typeof v === 'string' ? v : '');
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+export function machine(raw) {
+    const o = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        id: str(o.id),
+        label: str(o.label) || str(o.host) || str(o.id),
+        kind: str(o.kind),
+        status: str(o.status),
+        capacity: str(o.capacity),
+        host: str(o.host),
+        sessions: num(o.sessions),
+        running: num(o.running),
+        seen: str(o.metricsAt),
+    };
+}
+export async function machines(t) {
+    const raw = (await call(t, 'GET', '/v1/agent/targets')) ?? {};
+    return (Array.isArray(raw.targets) ? raw.targets : []).map(machine).filter((m) => m.id);
+}
+/** The platform's 404 for a machine that is someone else's, said as the rule it is. */
+async function owned(p) {
+    try {
+        return await p;
+    }
+    catch (e) {
+        if (e instanceof Refusal && e.status === 404)
+            throw new Refusal(404, 'This machine is gone, or not yours to change: only the member who linked it, or an org admin, can.');
+        throw e;
+    }
+}
+/** Register a machine by hand. `hanzo link` on a machine with this hostname takes the row over. */
+export async function add(t, what) {
+    const label = what.label.trim();
+    if (!label)
+        throw new Error('A machine needs a name');
+    const host = (what.host ?? '').trim();
+    return machine(await call(t, 'POST', '/v1/agent/targets', { label, kind: what.kind, ...(host ? { host } : {}) }));
+}
+/** Rename a machine, or drain it (`draining`) and bring it back (`online`). */
+export async function change(t, id, what) {
+    const body = {};
+    if (what.label !== undefined) {
+        const label = what.label.trim();
+        if (!label)
+            throw new Error('A machine needs a name');
+        body.label = label;
+    }
+    if (what.status !== undefined)
+        body.status = what.status;
+    return machine(await owned(call(t, 'PATCH', `/v1/agent/targets/${seg(id)}`, body)));
+}
+export async function remove(t, id) {
+    await owned(call(t, 'DELETE', `/v1/agent/targets/${seg(id)}`));
+}
+/**
+ * Mint the machine's claim key, answered this once: only its hash is kept, and
+ * minting again ends the key before it. A runner on the machine sends it as
+ * `X-Target-Key` when it claims the runs sent there.
+ */
+export async function key(t, id) {
+    const r = await owned(call(t, 'POST', `/v1/agent/targets/${seg(id)}/key`));
+    const k = str(r?.claimKey);
+    if (!k)
+        throw new Error('The platform answered no key');
+    return k;
+}

package/lib/api/members.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Who is in the organization, and who has been asked to join it, as Hanzo IAM
+ * holds them.
+ *
+ *   GET    /v1/iam/memberships?org=              the roster: {status, data: [membership], data2: count}
+ *   GET    /v1/iam/invitations?owner=            {invitations, total} (org admin)
+ *   POST   /v1/iam/invitations                   issue one (org admin)
+ *   DELETE /v1/iam/invitations/{owner}/{name}    withdraw one (org admin)
+ *
+ * IAM decides the scope from the credential: a member reads the roster of an org
+ * they belong to, and only an admin of the org reads or writes its invitations.
+ * An invitation is a code IAM redeems when someone signs up with it; IAM sends
+ * no email of its own.
+ */
+import { type Target } from './call.ts';
+export type Role = 'owner' | 'admin' | 'member';
+export interface Member {
+    /** `<homeOrg>/<username>`, IAM's id for the person. */
+    user: string;
+    /** The username alone. */
+    name: string;
+    role: Role;
+    since: string;
+}
+export declare function member(raw: unknown): Member;
+/** The org's people, owners first. Grants to a team or narrowed to one project are not the org's roster. */
+export declare function roster(t: Target, org: string): Promise<Member[]>;
+export interface Invitation {
+    owner: string;
+    name: string;
+    email: string;
+    /** What the invitee enters when they sign up. */
+    code: string;
+    /** How many may join with it, and how many have. */
+    seats: number;
+    used: number;
+    /** `Active` is redeemable; anything else is not. */
+    state: string;
+    created: string;
+}
+export declare function invitation(raw: unknown): Invitation;
+export declare function invitations(t: Target, org: string): Promise<Invitation[]>;
+/** An address that can receive an invitation. */
+export declare const EMAIL: RegExp;
+/** Invite one address into the org: one seat, redeemable now, pinned to that address. */
+export declare function invite(t: Target, org: string, email: string): Promise<Invitation>;
+export declare function revoke(t: Target, i: Pick<Invitation, 'owner' | 'name'>): Promise<void>;