@hanzo/build 0.2.9 → 0.2.11

package/lib/api/provider.js

@@ -0,0 +1,58 @@
+/**
+ * The organization's connectors: a Slack workspace, the GitHub accounts the
+ * platform's GitHub App is installed on.
+ *
+ *   GET  /v1/provider/{id}              one connector and this org's connection to it
+ *   POST /v1/provider/{id}/connect      {} → {authorizeUrl}: the provider's own consent page (org admin)
+ *   POST /v1/provider/{id}/disconnect   forget the org's connection (org admin)
+ *   GET  /v1/provider/slack/channels    the connected workspace's channels, a page at a time
+ *
+ * Connecting leaves this page once, for the provider's consent screen, and only
+ * for that provider's own host.
+ */
+import { call, query, seg } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const obj = (v) => (v && typeof v === 'object' ? v : {});
+const arr = (v) => (Array.isArray(v) ? v : []);
+export function connector(raw, id = '') {
+    const p = obj(raw);
+    const c = obj(p.connection);
+    return {
+        id: str(p.id) || id,
+        name: str(p.name) || id,
+        available: p.available === true,
+        connected: p.connected === true,
+        account: str(c.account),
+        since: str(c.connectedAt),
+        note: str(p.note),
+    };
+}
+export async function read(t, id) {
+    return connector(await call(t, 'GET', `/v1/provider/${seg(id)}`), id);
+}
+/** Where each provider's consent lives. An authorize address anywhere else is refused. */
+const CONSENT = {
+    slack: /^https:\/\/slack\.com\//,
+    github: /^https:\/\/github\.com\//,
+};
+/** The provider's consent page for this org. */
+export async function authorize(t, id) {
+    const url = str(obj(await call(t, 'POST', `/v1/provider/${seg(id)}/connect`, {})).authorizeUrl);
+    const host = CONSENT[id];
+    if (!host || !host.test(url))
+        throw new Error(`The platform did not name a ${id} address to connect at`);
+    return url;
+}
+export async function disconnect(t, id) {
+    await call(t, 'POST', `/v1/provider/${seg(id)}/disconnect`, {});
+}
+export async function channels(t, cursor = '') {
+    const raw = obj(await call(t, 'GET', `/v1/provider/slack/channels${query({ cursor })}`));
+    return {
+        channels: arr(raw.channels)
+            .map(obj)
+            .map((c) => ({ id: str(c.id), name: str(c.name), private: c.is_private === true, member: c.is_member === true }))
+            .filter((c) => c.id),
+        next: str(raw.next_cursor),
+    };
+}

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

@@ -1,10 +1,13 @@
 /**
  * Runs, as the platform records them: one session per run.
  *
- *   GET  /v1/agent/sessions?kind=&project=&status=&limit=   newest first
- *   GET  /v1/agent/sessions/{id}                            + the 50 most recent events
- *   POST /v1/agent/sessions/{id}/message {message}           steer a running run
- *   POST /v1/agent/sessions/{id}/stop    {message}           end it, work kept
+ *   GET   /v1/agent/sessions?kind=&project=&status=&limit=&after=   newest first, {sessions, next}
+ *   GET   /v1/agent/sessions/{id}                            + the 50 most recent events
+ *   PATCH /v1/agent/sessions/{id}         {title}|{published} rename it; open its story to the public build route
+ *   POST  /v1/agent/sessions/{id}/message {message}           steer a running run
+ *   POST  /v1/agent/sessions/{id}/pause                       pause it; a sandbox run keeps its work on its branch
+ *   POST  /v1/agent/sessions/{id}/resume                      ask a paused run to go on
+ *   POST  /v1/agent/sessions/{id}/stop    {message}           end it, work kept
  *   GET  /v1/agent/sessions/stream?root={id}                 SSE: `session` and `event` frames,
  *                                                            each wrapped: {"session":{…}}, {"event":{…}}
  *
@@ -35,6 +38,12 @@ 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;
+    /** The org the run is in, which the public build route is addressed by. */
+    org: string;
+    /** Whether its story is open to the public build route. Only a run that names a project can be. */
+    published: boolean;
     events: number;
     createdAt: string;
     updatedAt: string;
@@ -54,16 +63,42 @@ 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;
+    /** running, paused, done or error: the four the platform filters on. */
     status?: string;
     limit?: number;
+    /** The `next` of the page before. */
+    after?: string;
+}
+export interface Page {
+    sessions: Session[];
+    /** The cursor for the page after this one, or '' on the last. */
+    next: string;
 }
+export declare function page(t: Target, q?: ListQuery): Promise<Page>;
 export declare function list(t: Target, q?: ListQuery): Promise<Session[]>;
 export declare function get(t: Target, id: string): Promise<Detail>;
 export declare function message(t: Target, id: string, text: string): Promise<void>;
 export declare function stop(t: Target, id: string, why?: string): Promise<void>;
+export declare function pause(t: Target, id: string): Promise<void>;
+export declare function resume(t: Target, id: string): Promise<void>;
+/** A new title, up to the platform's 512 characters. */
+export declare function rename(t: Target, id: string, title: string): Promise<Session>;
+/**
+ * Open the run's story to the public build route, or close it. The platform
+ * refuses to open one that names no project, because that route is keyed on
+ * the org and the project.
+ */
+export declare function publish(t: Target, id: string, on: boolean): Promise<Session>;
+/** Where anyone can read a published run's story: the public build route, by org and project. */
+export declare const story: (t: Target, org: string, project: string) => string;
 export interface Watch {
     session?: (s: Session) => void;
     event?: (e: Event) => void;

package/lib/api/sessions.js

@@ -1,10 +1,13 @@
 /**
  * Runs, as the platform records them: one session per run.
  *
- *   GET  /v1/agent/sessions?kind=&project=&status=&limit=   newest first
- *   GET  /v1/agent/sessions/{id}                            + the 50 most recent events
- *   POST /v1/agent/sessions/{id}/message {message}           steer a running run
- *   POST /v1/agent/sessions/{id}/stop    {message}           end it, work kept
+ *   GET   /v1/agent/sessions?kind=&project=&status=&limit=&after=   newest first, {sessions, next}
+ *   GET   /v1/agent/sessions/{id}                            + the 50 most recent events
+ *   PATCH /v1/agent/sessions/{id}         {title}|{published} rename it; open its story to the public build route
+ *   POST  /v1/agent/sessions/{id}/message {message}           steer a running run
+ *   POST  /v1/agent/sessions/{id}/pause                       pause it; a sandbox run keeps its work on its branch
+ *   POST  /v1/agent/sessions/{id}/resume                      ask a paused run to go on
+ *   POST  /v1/agent/sessions/{id}/stop    {message}           end it, work kept
  *   GET  /v1/agent/sessions/stream?root={id}                 SSE: `session` and `event` frames,
  *                                                            each wrapped: {"session":{…}}, {"event":{…}}
  *
@@ -34,6 +37,9 @@ export function session(raw) {
         environment: str(s.environment),
         mode: str(s.mode),
         pr: str(s.pr),
+        sandbox: str(s.sandbox),
+        org: str(s.org),
+        published: s.published === true,
         events: num(s.events),
         createdAt: str(s.createdAt),
         updatedAt: str(s.updatedAt),
@@ -52,9 +58,30 @@ export function event(raw) {
         createdAt: str(e.createdAt),
     };
 }
-export async function list(t, q = {}) {
+/**
+ * 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 page(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);
+    return {
+        sessions: (Array.isArray(raw.sessions) ? raw.sessions : []).map(session).filter((s) => s.id),
+        next: str(raw.next),
+    };
+}
+export async function list(t, q = {}) {
+    return (await page(t, q)).sessions;
 }
 export async function get(t, id) {
     const raw = obj(await call(t, 'GET', `/v1/agent/sessions/${seg(id)}`));
@@ -72,6 +99,31 @@ export async function message(t, id, text) {
 export async function stop(t, id, why = 'Stopped from the builder') {
     await call(t, 'POST', `/v1/agent/sessions/${seg(id)}/stop`, { message: why });
 }
+export async function pause(t, id) {
+    await call(t, 'POST', `/v1/agent/sessions/${seg(id)}/pause`, {});
+}
+export async function resume(t, id) {
+    await call(t, 'POST', `/v1/agent/sessions/${seg(id)}/resume`, {});
+}
+/** A new title, up to the platform's 512 characters. */
+export async function rename(t, id, title) {
+    const name = title.trim();
+    if (!name)
+        throw new Refusal(400, 'Give the run a name');
+    if (name.length > 512)
+        throw new Refusal(400, 'A run’s name is at most 512 characters');
+    return session(await call(t, 'PATCH', `/v1/agent/sessions/${seg(id)}`, { title: name }));
+}
+/**
+ * Open the run's story to the public build route, or close it. The platform
+ * refuses to open one that names no project, because that route is keyed on
+ * the org and the project.
+ */
+export async function publish(t, id, on) {
+    return session(await call(t, 'PATCH', `/v1/agent/sessions/${seg(id)}`, { published: on }));
+}
+/** Where anyone can read a published run's story: the public build route, by org and project. */
+export const story = (t, org, project) => org && project ? `${t.api}/v1/agent/builds/${seg(org)}/${seg(project)}` : '';
 /**
  * Follow one run's tree until `signal` aborts. Reconnects with a capped backoff;
  * a refusal (401/403) ends it, because retrying a no is not recovery.

package/lib/api/skills.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Skills: what an agent knows how to do, as a SKILL.md it reads.
+ *
+ *   GET    /v1/tool/skills?activated=true   {tools: [Tool]}  the org's skills that are on, brand and own
+ *   GET    /v1/tool/skills/authored         {skills: [skill]} the org's own, with their SKILL.md
+ *   POST   /v1/tool/skills                  {name, description, content} → 201 {skill}; the same name revises it
+ *   DELETE /v1/tool/skills/{id}             {deleted}
+ *   GET    /.well-known/agent-skills/index.json         the brand's catalogue, public
+ *   GET    /.well-known/agent-skills/{name}/SKILL.md     one of its documents, public
+ *
+ * A skill is on when its tool name, `skill_<name>`, is activated (tools.ts):
+ * that is how a catalogue skill is added to an org and how an org's own skill is
+ * switched off. The brand's skill wins a name an org's own skill also takes.
+ */
+import { type Target } from './call.ts';
+import { type Tool } from './tools.ts';
+/** An org's own skill. */
+export interface Skill {
+    /** Derived from the name, and what a delete addresses. */
+    id: string;
+    name: string;
+    description: string;
+    /** The SKILL.md body. */
+    content: string;
+    /** When it was last written, Unix seconds. */
+    created: number;
+    /** The repository it was read from, or '' for one written here. */
+    source: string;
+}
+/** One skill of the brand's catalogue. */
+export interface Entry {
+    name: string;
+    description: string;
+    /** The product it belongs to. */
+    product: string;
+}
+export interface Catalogue {
+    skills: Entry[];
+    products: {
+        name: string;
+        count: number;
+    }[];
+}
+/** A skill's name: one lowercase path segment, as the handler takes it. */
+export declare const NAME: RegExp;
+/** The most SKILL.md the handler keeps. */
+export declare const MAX: number;
+/** The tool name a skill is switched on by. */
+export declare const tool: (name: string) => string;
+/** The skill a tool name switches, or '' when it is not a skill's. */
+export declare const nameOf: (tool: string) => string;
+export declare function skill(raw: unknown): Skill;
+export declare function catalogue(raw: unknown): Catalogue;
+/** The org's skills that are on, brand and own. */
+export declare function active(t: Target): Promise<Tool[]>;
+export declare function authored(t: Target): Promise<Skill[]>;
+/** Why a skill cannot be written as it stands, or '' when it can. */
+export declare function refuse(s: {
+    name: string;
+    content: string;
+}): string;
+export declare function write(t: Target, s: {
+    name: string;
+    description: string;
+    content: string;
+}): Promise<Skill>;
+export declare function remove(t: Target, id: string): Promise<void>;
+export declare function brand(t: Target): Promise<Catalogue>;
+/** One catalogue skill's SKILL.md. */
+export declare function document(t: Target, name: string): Promise<string>;

package/lib/api/skills.js

@@ -0,0 +1,90 @@
+/**
+ * Skills: what an agent knows how to do, as a SKILL.md it reads.
+ *
+ *   GET    /v1/tool/skills?activated=true   {tools: [Tool]}  the org's skills that are on, brand and own
+ *   GET    /v1/tool/skills/authored         {skills: [skill]} the org's own, with their SKILL.md
+ *   POST   /v1/tool/skills                  {name, description, content} → 201 {skill}; the same name revises it
+ *   DELETE /v1/tool/skills/{id}             {deleted}
+ *   GET    /.well-known/agent-skills/index.json         the brand's catalogue, public
+ *   GET    /.well-known/agent-skills/{name}/SKILL.md     one of its documents, public
+ *
+ * A skill is on when its tool name, `skill_<name>`, is activated (tools.ts):
+ * that is how a catalogue skill is added to an org and how an org's own skill is
+ * switched off. The brand's skill wins a name an org's own skill also takes.
+ */
+import { call, reason, Refusal, seg } from './call.js';
+import { toolsOf } from './tools.js';
+/** A skill's name: one lowercase path segment, as the handler takes it. */
+export const NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/** The most SKILL.md the handler keeps. */
+export const MAX = 256 << 10;
+/** The tool name a skill is switched on by. */
+export const tool = (name) => `skill_${name}`;
+/** The skill a tool name switches, or '' when it is not a skill's. */
+export const nameOf = (tool) => (tool.startsWith('skill_') ? tool.slice('skill_'.length) : '');
+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 skill(raw) {
+    const o = obj(raw);
+    const name = str(o.name);
+    return { id: str(o.id) || name, name, description: str(o.description), content: str(o.content), created: num(o.createdAt), source: str(o.source) };
+}
+export function catalogue(raw) {
+    const o = obj(raw);
+    return {
+        skills: rows(o.skills)
+            .map((r) => {
+            const e = obj(r);
+            return { name: str(e.name), description: str(e.description), product: str(e.service) };
+        })
+            .filter((e) => e.name),
+        products: rows(o.products)
+            .map((r) => {
+            const p = obj(r);
+            return { name: str(p.name), count: num(p.skill_count) };
+        })
+            .filter((p) => p.name),
+    };
+}
+/** The org's skills that are on, brand and own. */
+export async function active(t) {
+    return toolsOf(await call(t, 'GET', '/v1/tool/skills?activated=true'));
+}
+export async function authored(t) {
+    return rows(obj(await call(t, 'GET', '/v1/tool/skills/authored')).skills).map(skill).filter((s) => s.name);
+}
+/** Why a skill cannot be written as it stands, or '' when it can. */
+export function refuse(s) {
+    if (!NAME.test(s.name))
+        return 'A name is one lowercase word: letters, digits, _ or -';
+    if (!s.content.trim())
+        return 'A skill needs its SKILL.md';
+    if (new TextEncoder().encode(s.content).length > MAX)
+        return 'A SKILL.md is at most 256 KB';
+    return '';
+}
+export async function write(t, s) {
+    const why = refuse(s);
+    if (why)
+        throw new Error(why);
+    return skill(obj(await call(t, 'POST', '/v1/tool/skills', { name: s.name, description: s.description, content: s.content })).skill);
+}
+export async function remove(t, id) {
+    await call(t, 'DELETE', `/v1/tool/skills/${seg(id)}`);
+}
+/** A public document of the brand's catalogue. It needs no bearer, so it sends none. */
+async function open(t, path) {
+    const res = await fetch(`${t.api}/.well-known/agent-skills/${path}`);
+    if (!res.ok)
+        throw new Refusal(res.status, (await reason(res)) || `The catalogue answered ${res.status}`);
+    return res;
+}
+export async function brand(t) {
+    return catalogue(await (await open(t, 'index.json')).json());
+}
+/** One catalogue skill's SKILL.md. */
+export async function document(t, name) {
+    return (await open(t, `${seg(name)}/SKILL.md`)).text();
+}

package/lib/api/tools.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The org's tool plane: every tool it can reach, and which of them are on.
+ *
+ *   GET /v1/tool?source=&activated=true   {tools: [{name, source, description, activated, dispatchable}]}
+ *   GET /v1/tool/activation               {enabled: [name]}
+ *   PUT /v1/tool/activation               {activate: [name], deactivate: [name]} → {enabled: [name]}
+ *
+ * A tool is on per org. On is what puts a skill's SKILL.md in an agent's prompt
+ * and what lets an MCP server's tool be called; a tool that is off is listed and
+ * refused at call time. Any member of the org may switch one — the handler asks
+ * for the org and nothing more.
+ */
+import { type Target } from './call.ts';
+export interface Tool {
+    /** The flat, fleet-wide name: `skill_<name>`, `<server id>_<tool>`, `agent_<name>`… */
+    name: string;
+    /** connector, function, zap-service, agent, skill or mcp. */
+    source: string;
+    description: string;
+    activated: boolean;
+}
+export declare const names: (v: unknown) => string[];
+export declare function tool(raw: unknown): Tool;
+/** The tools in one listing, whichever of the plane's two envelopes it came in. */
+export declare function toolsOf(raw: unknown): Tool[];
+/** Every tool the org reaches, narrowed to one source and to the ones that are on when asked. */
+export declare function tools(t: Target, q?: {
+    source?: string;
+    activated?: boolean;
+}): Promise<Tool[]>;
+/** The names that are on. */
+export declare function enabled(t: Target): Promise<string[]>;
+/** Switch names on and off; answers every name that is on afterwards. */
+export declare function toggle(t: Target, on: string[], off?: string[]): Promise<string[]>;

package/lib/api/tools.js

@@ -0,0 +1,37 @@
+/**
+ * The org's tool plane: every tool it can reach, and which of them are on.
+ *
+ *   GET /v1/tool?source=&activated=true   {tools: [{name, source, description, activated, dispatchable}]}
+ *   GET /v1/tool/activation               {enabled: [name]}
+ *   PUT /v1/tool/activation               {activate: [name], deactivate: [name]} → {enabled: [name]}
+ *
+ * A tool is on per org. On is what puts a skill's SKILL.md in an agent's prompt
+ * and what lets an MCP server's tool be called; a tool that is off is listed and
+ * refused at call time. Any member of the org may switch one — the handler asks
+ * for the org and nothing more.
+ */
+import { call, query } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const obj = (v) => (v && typeof v === 'object' ? v : {});
+export const names = (v) => (Array.isArray(v) ? v.filter((n) => typeof n === 'string' && n !== '') : []);
+export function tool(raw) {
+    const o = obj(raw);
+    return { name: str(o.name), source: str(o.source), description: str(o.description), activated: o.activated === true };
+}
+/** The tools in one listing, whichever of the plane's two envelopes it came in. */
+export function toolsOf(raw) {
+    const list = obj(raw).tools;
+    return (Array.isArray(list) ? list : []).map(tool).filter((x) => x.name);
+}
+/** Every tool the org reaches, narrowed to one source and to the ones that are on when asked. */
+export async function tools(t, q = {}) {
+    return toolsOf(await call(t, 'GET', `/v1/tool${query({ source: q.source, activated: q.activated ? 'true' : undefined })}`));
+}
+/** The names that are on. */
+export async function enabled(t) {
+    return names(obj(await call(t, 'GET', '/v1/tool/activation')).enabled);
+}
+/** Switch names on and off; answers every name that is on afterwards. */
+export async function toggle(t, on, off = []) {
+    return names(obj(await call(t, 'PUT', '/v1/tool/activation', { activate: on, deactivate: off })).enabled);
+}

package/lib/api/turn.d.ts

@@ -1,18 +1,3 @@
-/**
- * What a run's events SAY, as text a person reads.
- *
- * A curated projection, never a dump: an event carries the machinery a run
- * happened on — hosts, paths, whole file bodies — and printing it would put
- * someone's filesystem in front of anyone who can read the run. Each kind gets a
- * sentence built from the few fields that describe the outcome; the rest is
- * dropped by omission, because a projection cannot leak a field it never reads.
- *
- * Every string here is rendered as TEXT by the transcript. Nothing is HTML.
- *
- * The coding plane's vocabulary (apps/coding): `status` for a lifecycle move
- * (started, routed, done, error, stopped, paused), `tool-call` for a step,
- * `log` for a free line. A steering message a person sent is a `message`.
- */
 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;
@@ -38,7 +23,12 @@ export interface StepLine {
     name: string;
     done: boolean;
 }
-/** Tool calls, in the order they were first named. A later status for the same step wins. */
+/**
+ * Tool calls, in the order they were first named. A later status for the same
+ * step wins, and a run's steps follow one another, so a step another has
+ * followed is over. `exit` is not a step: it is how the sandbox says one command
+ * in it ended (apps/sandbox work.go).
+ */
 export declare function steps(events: Pick<Event, 'kind' | 'payload' | 'seq'>[]): StepLine[];
 export interface Outcome {
     /** The last lifecycle status the run narrated, or ''. */
@@ -71,3 +61,81 @@ export declare function pull(url: string, repo: string): {
     href: string;
     label: string;
 };
+/** How a card's work went. One still running once the run has ended was cut off. */
+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
+ *   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
+ *   step   a step of the run itself (lease, clone, install, push), or a tool the agent called
+ *   note   a lifecycle line: started, pushed, stopped
+ *   plan   a plan run's answer, which can be approved into a build
+ */
+export type Card = {
+    kind: 'said';
+    key: string;
+    who: 'person' | 'agent';
+    text: string;
+} | {
+    kind: 'shell';
+    key: string;
+    command: string;
+    output: string;
+    ran: Ran;
+} | {
+    kind: 'edit';
+    key: string;
+    files: string[];
+    patch: string;
+    ran: Ran;
+} | {
+    kind: 'read';
+    key: string;
+    file: string;
+    ran: Ran;
+} | {
+    kind: 'step';
+    key: string;
+    name: string;
+    detail: string;
+    output: string;
+    ran: Ran;
+} | {
+    kind: 'note';
+    key: string;
+    text: string;
+} | {
+    kind: 'plan';
+    key: string;
+    text: string;
+};
+/**
+ * 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.
+ */
+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 ''. */
+export declare function answer(events: Pick<Event, 'kind' | 'payload' | 'seq'>[]): string;
+export interface Settled {
+    /** The run has said how it ended, or that it paused: its work is where it will stay. */
+    settled: boolean;
+    /** That work is on the run's own branch, which a follow-up can start from. */
+    pushed: boolean;
+}
+/**
+ * Whether the run has kept its work yet, and whether that work is on its
+ * branch. A stop or a pause commits and pushes AFTER it is asked, and says so
+ * in its status (apps/coding coding.go interrupted): until then a follow-up
+ * would clone a branch the push has not reached.
+ */
+export declare function settled(events: Pick<Event, 'kind' | 'payload' | 'seq'>[]): Settled;