@hanzo/build 0.2.9 → 0.2.11

package/lib/api/connectors.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Connectors: the MCP servers an org adds, and the shelf it picks them from.
+ *
+ *   GET    /v1/tool/mcp/servers        {servers: [server]}
+ *   POST   /v1/tool/mcp/servers        {name, url} or {listing, name?}, with {authHeader, secret} → 201 server
+ *   DELETE /v1/tool/mcp/servers/{id}   204
+ *   GET    /v1/tool/catalog?q=&limit=&offset=   {catalog: [listing], total, limit, offset}
+ *   GET    /v1/tool/catalog/{id}       one listing in full
+ *
+ * A server's secret is sealed in KMS by the platform and never answered again;
+ * a record says only whether it has one. Its tools are GET /v1/tool?source=mcp
+ * (tools.ts), named `<server id>_<tool>`, and each is called only once it is on.
+ * A listing can be added here only when it serves streamable HTTP; one that
+ * ships only a package needs somewhere to run first. The fleet's own servers,
+ * on for every run, are mcp.ts.
+ */
+import { type Target } from './call.ts';
+export interface Server {
+    /** The server's id in the org, and the prefix of every tool it brings. */
+    id: string;
+    name: string;
+    url: string;
+    /** The header the sealed secret is sent in, or ''. */
+    header: string;
+    /** Whether a secret is sealed for it. */
+    secret: boolean;
+    /** The catalog listing it was added from, or '' for a URL typed in. */
+    listing: string;
+    created: number;
+}
+export interface Remote {
+    transport: string;
+    url: string;
+}
+export interface Package {
+    registry: string;
+    identifier: string;
+    runtime: string;
+    version: string;
+}
+export interface Listing {
+    id: string;
+    /** The publisher's reverse-DNS name, `com.stripe/mcp`. */
+    name: string;
+    title: string;
+    description: string;
+    vendor: string;
+    version: string;
+    logo: string;
+    featured: boolean;
+    official: boolean;
+    transports: string[];
+    remotes: Remote[];
+    packages: Package[];
+    repo: string;
+    site: string;
+}
+export interface Page {
+    listings: Listing[];
+    total: number;
+    offset: number;
+}
+export declare function server(raw: unknown): Server;
+export declare function listing(raw: unknown): Listing;
+/** What a listing is called on screen. */
+export declare const titleOf: (l: Listing) => string;
+/** Whether a listing can be added here and now: the platform dials its streamable-HTTP remote. */
+export declare const ready: (l: Listing) => boolean;
+/** A server's tools among the plane's, by the prefix its id gives them. */
+export declare const owns: (s: Server, toolName: string) => boolean;
+export declare function servers(t: Target): Promise<Server[]>;
+export interface Adding {
+    /** Required with a URL; a listing takes its own title when this is empty. */
+    name?: string;
+    url?: string;
+    listing?: string;
+    header?: string;
+    secret?: string;
+}
+/** Why a server cannot be added as it stands, or '' when it can. */
+export declare function refuse(a: Adding): string;
+export declare function add(t: Target, a: Adding): Promise<Server>;
+export declare function remove(t: Target, id: string): Promise<void>;
+/** A page of the shelf, featured first, then by name. */
+export declare function shelf(t: Target, q?: {
+    text?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<Page>;
+export declare function one(t: Target, id: string): Promise<Listing>;

package/lib/api/connectors.js

@@ -0,0 +1,109 @@
+/**
+ * Connectors: the MCP servers an org adds, and the shelf it picks them from.
+ *
+ *   GET    /v1/tool/mcp/servers        {servers: [server]}
+ *   POST   /v1/tool/mcp/servers        {name, url} or {listing, name?}, with {authHeader, secret} → 201 server
+ *   DELETE /v1/tool/mcp/servers/{id}   204
+ *   GET    /v1/tool/catalog?q=&limit=&offset=   {catalog: [listing], total, limit, offset}
+ *   GET    /v1/tool/catalog/{id}       one listing in full
+ *
+ * A server's secret is sealed in KMS by the platform and never answered again;
+ * a record says only whether it has one. Its tools are GET /v1/tool?source=mcp
+ * (tools.ts), named `<server id>_<tool>`, and each is called only once it is on.
+ * A listing can be added here only when it serves streamable HTTP; one that
+ * ships only a package needs somewhere to run first. The fleet's own servers,
+ * on for every run, are mcp.ts.
+ */
+import { call, query, seg } from './call.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 rows = (v) => (Array.isArray(v) ? v : []);
+export function server(raw) {
+    const o = obj(raw);
+    return {
+        id: str(o.id),
+        name: str(o.name),
+        url: str(o.url),
+        header: str(o.authHeader),
+        secret: o.hasSecret === true,
+        listing: str(o.listing),
+        created: num(o.createdAt),
+    };
+}
+export function listing(raw) {
+    const o = obj(raw);
+    return {
+        id: str(o.id),
+        name: str(o.name),
+        title: str(o.title),
+        description: str(o.description),
+        vendor: str(o.vendor),
+        version: str(o.version),
+        logo: str(o.logo),
+        featured: o.featured === true,
+        official: o.official === true,
+        transports: rows(o.transports).map(str).filter(Boolean),
+        remotes: rows(o.remotes)
+            .map((r) => ({ transport: str(obj(r).transport), url: str(obj(r).url) }))
+            .filter((r) => r.url),
+        packages: rows(o.packages)
+            .map((p) => {
+            const x = obj(p);
+            return { registry: str(x.registry), identifier: str(x.identifier), runtime: str(x.runtime), version: str(x.version) };
+        })
+            .filter((p) => p.identifier),
+        repo: str(o.repo),
+        site: str(o.site),
+    };
+}
+/** What a listing is called on screen. */
+export const titleOf = (l) => l.title || l.name;
+/** Whether a listing can be added here and now: the platform dials its streamable-HTTP remote. */
+export const ready = (l) => l.remotes.some((r) => r.transport === 'streamable-http');
+/** A server's tools among the plane's, by the prefix its id gives them. */
+export const owns = (s, toolName) => toolName.startsWith(`${s.id}_`);
+export async function servers(t) {
+    return rows(obj(await call(t, 'GET', '/v1/tool/mcp/servers')).servers).map(server).filter((s) => s.id);
+}
+/** Why a server cannot be added as it stands, or '' when it can. */
+export function refuse(a) {
+    if (!a.listing) {
+        if (!a.name?.trim())
+            return 'A connector needs a name';
+        if (!/^https?:\/\/[^\s/]+/.test(a.url?.trim() ?? ''))
+            return 'The URL is an http(s) address';
+    }
+    if (a.secret && !a.header?.trim())
+        return 'Name the header the secret is sent in';
+    return '';
+}
+export async function add(t, a) {
+    const why = refuse(a);
+    if (why)
+        throw new Error(why);
+    const body = {};
+    if (a.listing)
+        body.listing = a.listing;
+    else
+        body.url = a.url.trim();
+    if (a.name?.trim())
+        body.name = a.name.trim();
+    // The header names where the secret goes, so it rides with one or not at all.
+    if (a.secret) {
+        body.authHeader = a.header.trim();
+        body.secret = a.secret;
+    }
+    return server(await call(t, 'POST', '/v1/tool/mcp/servers', body));
+}
+export async function remove(t, id) {
+    await call(t, 'DELETE', `/v1/tool/mcp/servers/${seg(id)}`);
+}
+/** A page of the shelf, featured first, then by name. */
+export async function shelf(t, q = {}) {
+    const r = obj(await call(t, 'GET', `/v1/tool/catalog${query({ q: q.text?.trim(), limit: q.limit, offset: q.offset || undefined })}`));
+    return { listings: rows(r.catalog).map(listing).filter((l) => l.id), total: num(r.total), offset: num(r.offset) };
+}
+export async function one(t, id) {
+    return listing(await call(t, 'GET', `/v1/tool/catalog/${seg(id)}`));
+}

package/lib/api/consent.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The signed-in person's answers to Hanzo's data-sharing questions, as IAM
+ * records them for every Hanzo surface.
+ *
+ *   GET /v1/iam/consent → {status, data: {insights, training}}
+ *   PUT /v1/iam/consent   {insights?, training?}   only the answers sent change
+ *
+ * `training` has three states: unanswered (''), granted, refused. Only granted
+ * lets Hanzo train on this person's data; unanswered is read as no. `insights`
+ * is anonymous product usage, with no prompt or answer text, and is on until
+ * turned off. Every change is audited by IAM with the answer before and after.
+ */
+import { type Target } from './call.ts';
+export type Answer = '' | 'granted' | 'refused';
+export interface Consent {
+    insights: boolean;
+    training: Answer;
+}
+/** IAM's defaults for anything it did not say: insights on, training unanswered. */
+export declare function consentOf(raw: unknown): Consent;
+export declare function consent(t: Target): Promise<Consent>;
+export declare function setConsent(t: Target, change: Partial<Consent>): Promise<Consent>;

package/lib/api/consent.js

@@ -0,0 +1,28 @@
+/**
+ * The signed-in person's answers to Hanzo's data-sharing questions, as IAM
+ * records them for every Hanzo surface.
+ *
+ *   GET /v1/iam/consent → {status, data: {insights, training}}
+ *   PUT /v1/iam/consent   {insights?, training?}   only the answers sent change
+ *
+ * `training` has three states: unanswered (''), granted, refused. Only granted
+ * lets Hanzo train on this person's data; unanswered is read as no. `insights`
+ * is anonymous product usage, with no prompt or answer text, and is on until
+ * turned off. Every change is audited by IAM with the answer before and after.
+ */
+import { call, unwrap } from './call.js';
+const ANSWERS = ['', 'granted', 'refused'];
+/** IAM's defaults for anything it did not say: insights on, training unanswered. */
+export function consentOf(raw) {
+    const o = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        insights: typeof o.insights === 'boolean' ? o.insights : true,
+        training: ANSWERS.includes(o.training) ? o.training : '',
+    };
+}
+export async function consent(t) {
+    return consentOf(unwrap(await call(t, 'GET', '/v1/iam/consent')));
+}
+export async function setConsent(t, change) {
+    return consentOf(unwrap(await call(t, 'PUT', '/v1/iam/consent', change)));
+}

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/github.d.ts

@@ -6,6 +6,7 @@
  *   GET  /v1/provider/github/user              the person's own connection
  *   POST /v1/provider/github/user/connect      → {authorizeUrl}
  *   POST /v1/provider/github/user/disconnect
+ *   GET  /v1/provider/github/installations     the accounts this org has bound the App on
  *
  * Paged by an opaque `after` cursor; `next` is the cursor for the page after
  * this one, or empty on the last. Rows are read defensively: a field the
@@ -76,6 +77,18 @@ export declare function connection(t: Target): Promise<Connection>;
 /** Where to send the person to authorize the platform's GitHub App — github.com only. */
 export declare function connect(t: Target): Promise<string>;
 export declare function disconnect(t: Target): Promise<void>;
+/** A GitHub account the platform's App is installed on, as this org sees it. */
+export interface Installation {
+    login: string;
+    /** `Organization` or `User`. */
+    type: string;
+    /** `all` or `selected` repositories. */
+    grant: string;
+    /** This org has bound it, and GitHub still has the App installed there. */
+    connected: boolean;
+}
+/** The accounts this org has bound the App on. An org admin adds one through `/v1/provider/github/connect`. */
+export declare function installations(t: Target): Promise<Installation[]>;
 /** One repository the GitHub connection grants this organization. */
 export interface Grant {
     owner: string;

package/lib/api/github.js

@@ -6,6 +6,7 @@
  *   GET  /v1/provider/github/user              the person's own connection
  *   POST /v1/provider/github/user/connect      → {authorizeUrl}
  *   POST /v1/provider/github/user/disconnect
+ *   GET  /v1/provider/github/installations     the accounts this org has bound the App on
  *
  * Paged by an opaque `after` cursor; `next` is the cursor for the page after
  * this one, or empty on the last. Rows are read defensively: a field the
@@ -71,6 +72,14 @@ export async function connect(t) {
 export async function disconnect(t) {
     await call(t, 'POST', '/v1/provider/github/user/disconnect');
 }
+/** The accounts this org has bound the App on. An org admin adds one through `/v1/provider/github/connect`. */
+export async function installations(t) {
+    const raw = obj(await call(t, 'GET', '/v1/provider/github/installations'));
+    return (Array.isArray(raw.installations) ? raw.installations : [])
+        .map(obj)
+        .map((i) => ({ login: str(i.login), type: str(i.type), grant: str(i.grant), connected: i.connected === true }))
+        .filter((i) => i.login);
+}
 export function grant(raw) {
     const r = obj(raw);
     const name = str(r.name);

package/lib/api/harness.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The agent's own output, read as cards.
+ *
+ * A sandbox run's agent is `dev exec`, and everything it prints reaches the
+ * run's session as `log` chunks (apps/sandbox work.go). It prints each item of
+ * its turn under a header line (hanzo dev, exec/src/event_processor_with_human_output.rs):
+ *
+ *   exec / <command> in <dir>            a command started
+ *    succeeded in 12ms: / <output>       …how it ended, then what it printed
+ *   codex / <text>                        the agent said something
+ *   apply patch / patch: completed / <paths>, then the turn's diff
+ *   mcp: server/tool (completed)          a tool call
+ *   web search: <query>
+ *     ✓ step / → step / • step            its plan
+ *   tokens used / <n>                     the end; the final message follows once more, bare
+ *
+ * The chunks are cut by a clock, not by line, so a line is read only once it
+ * is whole. Lines no header owns — reasoning, or the tail of output from before
+ * the recorded events begin — are prose. Everything here becomes TEXT on the
+ * screen; nothing is markup.
+ */
+import type { Card } from './turn.ts';
+/**
+ * A shell command's words, as `sh` splits them: quotes grouped, `'"'"'`
+ * joined, a backslash escaping the next character outside single quotes.
+ */
+export declare function words(line: string): string[];
+/** The command a harness ran, out of the `bash -lc '…'` it wraps each one in. */
+export declare function unwrap(command: string): string;
+/**
+ * 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 declare function reads(command: string): string;
+/** A path to show: a relative one as it is, an absolute one by its name — never the sandbox's layout. */
+export declare const shown: (path: string) => string;
+/** A unified diff's sections, by the path each changes, from its first hunk on. */
+export declare function sections(diff: string): Map<string, string>;
+/** A reader that appends the cards it finds to `out`, keyed by `mint`. */
+export declare function harness(out: Card[], mint: () => string): {
+    feed(chunk: string): void;
+    /** The last line even without its newline, and what only the whole output can decide. */
+    end(): void;
+};