@hanzo/build 0.2.10 → 0.2.12

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>;

package/lib/api/members.js

@@ -0,0 +1,88 @@
+/**
+ * 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 { 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 arr = (v) => (Array.isArray(v) ? v : []);
+const ROLES = ['owner', 'admin', 'member'];
+export function member(raw) {
+    const m = obj(raw);
+    const user = str(m.user);
+    const role = str(m.role);
+    return {
+        user,
+        name: user.includes('/') ? user.slice(user.indexOf('/') + 1) : user,
+        role: ROLES.includes(role) ? role : 'member',
+        since: str(m.createdTime),
+    };
+}
+/** The org's people, owners first. Grants to a team or narrowed to one project are not the org's roster. */
+export async function roster(t, org) {
+    const raw = obj(await call(t, 'GET', `/v1/iam/memberships${query({ org })}`));
+    if (raw.status === 'error')
+        throw new Error(str(raw.msg) || 'IAM refused the roster');
+    const rank = (r) => ROLES.indexOf(r);
+    return arr(raw.data)
+        .map(obj)
+        .filter((m) => str(m.user) && !str(m.workspace) && !str(m.project))
+        .map(member)
+        .sort((a, b) => rank(a.role) - rank(b.role) || a.name.localeCompare(b.name));
+}
+export function invitation(raw) {
+    const i = obj(raw);
+    return {
+        owner: str(i.owner),
+        name: str(i.name),
+        email: str(i.email),
+        code: str(i.code),
+        seats: num(i.quota),
+        used: num(i.usedCount),
+        state: str(i.state),
+        created: str(i.createdTime) || str(i.createdAt),
+    };
+}
+export async function invitations(t, org) {
+    const raw = obj(await call(t, 'GET', `/v1/iam/invitations${query({ owner: org })}`));
+    return arr(raw.invitations).map(invitation).filter((i) => i.name);
+}
+/** An address that can receive an invitation. */
+export const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/** Random hex, from the browser's own generator. */
+function hex(bytes) {
+    const b = new Uint8Array(bytes);
+    crypto.getRandomValues(b);
+    return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+}
+/** Invite one address into the org: one seat, redeemable now, pinned to that address. */
+export async function invite(t, org, email) {
+    const address = email.trim().toLowerCase();
+    if (!EMAIL.test(address))
+        throw new Error(`${email.trim() || 'That'} is not an email address`);
+    const local = address.slice(0, address.indexOf('@')).replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24);
+    return invitation(await call(t, 'POST', '/v1/iam/invitations', {
+        owner: org,
+        name: `invite-${local || 'member'}-${hex(3)}`,
+        displayName: address,
+        email: address,
+        code: hex(8),
+        quota: 1,
+        usedCount: 0,
+        state: 'Active',
+    }));
+}
+export async function revoke(t, i) {
+    await call(t, 'DELETE', `/v1/iam/invitations/${seg(i.owner)}/${seg(i.name)}`);
+}

package/lib/api/memory.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What Hanzo remembers about the signed-in person, in the org they act in.
+ *
+ *   GET  /v1/ai/memory/list?limit=  {status, data: [memory]}, newest first
+ *   POST /v1/ai/memory/remember     {content} → {status, data: memory}
+ *   POST /v1/ai/memory/delete       {id: "<owner>/<name>"}
+ *
+ * The platform keys every memory on the validated caller and org, never on the
+ * request, so these read and change the caller's own and nobody else's. A
+ * refusal arrives in the envelope, usually under a 200.
+ */
+import { type Target } from './call.ts';
+export interface Memory {
+    /** `<owner>/<name>`, what a delete names. */
+    id: string;
+    content: string;
+    /** user, fact, … as the platform files it. */
+    kind: string;
+    /** When it was last written, as the platform wrote it. */
+    updated: string;
+}
+export declare function memoryOf(raw: unknown): Memory | null;
+export declare function memories(t: Target, limit?: number): Promise<Memory[]>;
+export declare function remember(t: Target, content: string): Promise<Memory | null>;
+export declare function forget(t: Target, id: string): Promise<void>;

package/lib/api/memory.js

@@ -0,0 +1,34 @@
+/**
+ * What Hanzo remembers about the signed-in person, in the org they act in.
+ *
+ *   GET  /v1/ai/memory/list?limit=  {status, data: [memory]}, newest first
+ *   POST /v1/ai/memory/remember     {content} → {status, data: memory}
+ *   POST /v1/ai/memory/delete       {id: "<owner>/<name>"}
+ *
+ * The platform keys every memory on the validated caller and org, never on the
+ * request, so these read and change the caller's own and nobody else's. A
+ * refusal arrives in the envelope, usually under a 200.
+ */
+import { call, query, unwrap } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+export function memoryOf(raw) {
+    const o = (raw && typeof raw === 'object' ? raw : {});
+    const owner = str(o.owner);
+    const name = str(o.name);
+    if (!owner || !name)
+        return null;
+    return { id: `${owner}/${name}`, content: str(o.content), kind: str(o.kind), updated: str(o.updatedTime) || str(o.createdTime) };
+}
+export async function memories(t, limit = 100) {
+    const rows = unwrap(await call(t, 'GET', `/v1/ai/memory/list${query({ limit })}`));
+    return (Array.isArray(rows) ? rows : []).map(memoryOf).filter((m) => m !== null);
+}
+export async function remember(t, content) {
+    const said = content.trim();
+    if (!said)
+        throw new Error('Say what Hanzo should remember');
+    return memoryOf(unwrap(await call(t, 'POST', '/v1/ai/memory/remember', { content: said })));
+}
+export async function forget(t, id) {
+    unwrap(await call(t, 'POST', '/v1/ai/memory/delete', { id }));
+}

package/lib/api/places.d.ts

@@ -1,13 +1,13 @@
 /**
  * Where a run can run: the platform's sandbox, or one of the org's machines.
  *
- *   GET /v1/agent/targets → {targets: [...]}, newest first
+ *   GET /v1/agent/targets → {targets: [...]}, newest first (machines.ts)
  *
  * The sandbox is not a row the platform lists — it is what a run gets when it
  * names no target — so it is the first place here and carries no id. A machine
  * can take a run only while it is online.
  */
-import { type Target } from './call.ts';
+import type { Target } from './call.ts';
 export interface Place {
     /** `tgt_…`, or '' for the sandbox. */
     id: string;

package/lib/api/places.js

@@ -1,31 +1,8 @@
-/**
- * Where a run can run: the platform's sandbox, or one of the org's machines.
- *
- *   GET /v1/agent/targets → {targets: [...]}, newest first
- *
- * The sandbox is not a row the platform lists — it is what a run gets when it
- * names no target — so it is the first place here and carries no id. A machine
- * can take a run only while it is online.
- */
-import { call } from './call.js';
+import { machines } from './machines.js';
 export const SANDBOX = { id: '', label: 'Hanzo sandbox', kind: 'sandbox', status: 'online', capacity: '' };
-const str = (v) => (typeof v === 'string' ? v : '');
 export async function places(t) {
-    const raw = (await call(t, 'GET', '/v1/agent/targets')) ?? {};
-    const rows = Array.isArray(raw.targets) ? raw.targets : [];
-    const machines = rows
-        .map((r) => {
-        const o = (r && typeof r === 'object' ? r : {});
-        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),
-        };
-    })
-        .filter((p) => p.id);
-    return [SANDBOX, ...machines];
+    const list = await machines(t);
+    return [SANDBOX, ...list.map(({ id, label, kind, status, capacity }) => ({ id, label, kind, status, capacity }))];
 }
 /** Whether a run sent here now would be taken. */
 export const ready = (p) => p.status === 'online';

package/lib/api/plugins.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Plugins: TypeScript connectors an org builds, and what this deployment mounts.
+ *
+ *   GET    /v1/tool/plugins/authored        {plugins: [plugin]}, newest first, each with its source
+ *   POST   /v1/tool/plugins/build           {name, provider?, source | spec} → 201 {bytes, generated, plugin}
+ *   DELETE /v1/tool/plugins/authored/{id}   {deleted}
+ *   GET    /v1/tool/plugins                 {plugins: [{name, enabled, prefixes}]}
+ *
+ * Building is the gate: the platform bundles the source and compiles it in the
+ * runtime that will run it, and keeps it only if both succeed — a failure is a
+ * 422 whose reason is the bundler's. A spec (an OpenAPI document or prose) has a
+ * model write the source, which comes back to be read. A plugin never carries a
+ * credential: it names the connectors provider whose credential it reads when it
+ * runs. The mounted list is the deployment's own subsystems, read-only.
+ */
+import { type Target } from './call.ts';
+export interface Plugin {
+    /** What a delete addresses. */
+    id: string;
+    name: string;
+    /** The connectors provider whose credential it reads, or ''. */
+    provider: string;
+    /** The TypeScript as written or generated. */
+    source: string;
+    /** When it was last built, Unix seconds. */
+    built: number;
+}
+export interface Mount {
+    name: string;
+    enabled: boolean;
+    prefixes: string[];
+}
+export interface Built {
+    plugin: Plugin;
+    /** The size of the bundle the runtime executes. */
+    bytes: number;
+    /** Whether a model wrote the source from a spec. */
+    generated: boolean;
+}
+/** A plugin's name: one lowercase path segment, the id it runs by. */
+export declare const NAME: RegExp;
+export declare function plugin(raw: unknown): Plugin;
+export declare function authored(t: Target): Promise<Plugin[]>;
+export declare function mounted(t: Target): Promise<Mount[]>;
+export interface Build {
+    name: string;
+    provider: string;
+    /** Exactly one of the two carries text. */
+    source: string;
+    spec: string;
+}
+/** Why a plugin cannot be built as it stands, or '' when it can. */
+export declare function refuse(b: Build): string;
+export declare function build(t: Target, b: Build): Promise<Built>;
+export declare function remove(t: Target, id: string): Promise<void>;

package/lib/api/plugins.js

@@ -0,0 +1,62 @@
+/**
+ * Plugins: TypeScript connectors an org builds, and what this deployment mounts.
+ *
+ *   GET    /v1/tool/plugins/authored        {plugins: [plugin]}, newest first, each with its source
+ *   POST   /v1/tool/plugins/build           {name, provider?, source | spec} → 201 {bytes, generated, plugin}
+ *   DELETE /v1/tool/plugins/authored/{id}   {deleted}
+ *   GET    /v1/tool/plugins                 {plugins: [{name, enabled, prefixes}]}
+ *
+ * Building is the gate: the platform bundles the source and compiles it in the
+ * runtime that will run it, and keeps it only if both succeed — a failure is a
+ * 422 whose reason is the bundler's. A spec (an OpenAPI document or prose) has a
+ * model write the source, which comes back to be read. A plugin never carries a
+ * credential: it names the connectors provider whose credential it reads when it
+ * runs. The mounted list is the deployment's own subsystems, read-only.
+ */
+import { call, seg } from './call.js';
+/** A plugin's name: one lowercase path segment, the id it runs by. */
+export const NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+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 plugin(raw) {
+    const o = obj(raw);
+    return { id: str(o.id), name: str(o.name), provider: str(o.provider), source: str(o.source), built: num(o.createdAt) };
+}
+export async function authored(t) {
+    return rows(obj(await call(t, 'GET', '/v1/tool/plugins/authored')).plugins).map(plugin).filter((p) => p.id);
+}
+export async function mounted(t) {
+    return rows(obj(await call(t, 'GET', '/v1/tool/plugins')).plugins)
+        .map((r) => {
+        const o = obj(r);
+        return { name: str(o.name), enabled: o.enabled === true, prefixes: rows(o.prefixes).map(str).filter(Boolean) };
+    })
+        .filter((m) => m.name);
+}
+/** Why a plugin cannot be built as it stands, or '' when it can. */
+export function refuse(b) {
+    if (!NAME.test(b.name))
+        return 'A name is one lowercase word: letters, digits, _ or -';
+    if (!b.source.trim() === !b.spec.trim())
+        return 'Give the TypeScript or the API it calls, one of the two';
+    return '';
+}
+export async function build(t, b) {
+    const why = refuse(b);
+    if (why)
+        throw new Error(why);
+    const body = { name: b.name };
+    if (b.provider.trim())
+        body.provider = b.provider.trim();
+    if (b.source.trim())
+        body.source = b.source;
+    else
+        body.spec = b.spec;
+    const r = obj(await call(t, 'POST', '/v1/tool/plugins/build', body));
+    return { plugin: plugin(r.plugin), bytes: num(r.bytes), generated: r.generated === true };
+}
+export async function remove(t, id) {
+    await call(t, 'DELETE', `/v1/tool/plugins/authored/${seg(id)}`);
+}

package/lib/api/pref.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The signed-in person's own settings, as the platform keeps them for every
+ * Hanzo surface.
+ *
+ *   GET   /v1/pref → {prefs: {…}, updatedAt}   an empty document for someone who saved nothing
+ *   PATCH /v1/pref   {key: value | null}        a shallow merge; null deletes the key
+ *
+ * The document is one object shared by every surface, keyed per person and per
+ * org. This reads only the keys the builder owns and writes only those, so a
+ * key another surface saved is left as it was. A value this version does not
+ * recognise reads as unset rather than as a choice.
+ */
+import { type Target } from './call.ts';
+export type Theme = 'system' | 'light' | 'dark';
+export type Text = 'small' | 'medium' | 'large';
+export type Motion = 'system' | 'reduced';
+/** Where and how a new run starts when New has no choice of its own kept. */
+export interface Code {
+    model?: string;
+    effort?: 'low' | 'medium' | 'high';
+    mode?: 'build' | 'plan';
+    /** A machine's id, or '' for the sandbox. */
+    place?: string;
+}
+export interface Prefs {
+    theme?: Theme;
+    text?: Text;
+    motion?: Motion;
+    /** The dictation language, as voice.ts names it. */
+    language?: string;
+    /** What Hanzo calls the person. */
+    callName?: string;
+    /** What best describes their work. */
+    work?: string;
+    /** What every coding run is told about how they like to work. */
+    instructions?: string;
+    code?: Code;
+}
+/** A change: a key set to a value, or to null to delete it. */
+export type Patch = {
+    [K in keyof Prefs]?: Prefs[K] | null;
+};
+export declare function code(raw: unknown): Code | undefined;
+/** The builder's keys from a whole preference document. */
+export declare function prefs(raw: unknown): Prefs;
+/** What a document reads as once `patch` is merged into it — the platform's own rule. */
+export declare function merge(base: Prefs, patch: Patch): Prefs;
+export declare function read(t: Target): Promise<Prefs>;
+export declare function save(t: Target, patch: Patch): Promise<Prefs>;