@hanzo/build 0.2.10 → 0.2.11

package/lib/api/pref.js

@@ -0,0 +1,68 @@
+/**
+ * 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 { call } from './call.js';
+const THEMES = ['system', 'light', 'dark'];
+const TEXTS = ['small', 'medium', 'large'];
+const MOTIONS = ['system', 'reduced'];
+const EFFORTS = ['low', 'medium', 'high'];
+const MODES = ['build', 'plan'];
+const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+const text = (v) => (typeof v === 'string' && v.trim() ? v : undefined);
+const one = (v, of) => (of.includes(v) ? v : undefined);
+/** Drop the keys that say nothing, so a read and a merge compare cleanly. */
+function defined(o) {
+    return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+}
+export function code(raw) {
+    const c = obj(raw);
+    const out = defined({
+        model: text(c.model),
+        effort: one(c.effort, EFFORTS),
+        mode: one(c.mode, MODES),
+        place: typeof c.place === 'string' ? c.place : undefined,
+    });
+    return Object.keys(out).length ? out : undefined;
+}
+/** The builder's keys from a whole preference document. */
+export function prefs(raw) {
+    const p = obj(raw);
+    return defined({
+        theme: one(p.theme, THEMES),
+        text: one(p.text, TEXTS),
+        motion: one(p.motion, MOTIONS),
+        language: text(p.language),
+        callName: text(p.callName),
+        work: text(p.work),
+        instructions: text(p.instructions),
+        code: code(p.code),
+    });
+}
+/** What a document reads as once `patch` is merged into it — the platform's own rule. */
+export function merge(base, patch) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === null)
+            delete out[k];
+        else if (v !== undefined)
+            out[k] = v;
+    }
+    return prefs(out);
+}
+export async function read(t) {
+    const r = await call(t, 'GET', '/v1/pref');
+    return prefs(r?.prefs);
+}
+export async function save(t, patch) {
+    const r = await call(t, 'PATCH', '/v1/pref', patch);
+    return prefs(r?.prefs);
+}

package/lib/api/profile.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The signed-in person's own profile on Hanzo IAM: the name they are shown by
+ * and their photo.
+ *
+ *   PUT  /v1/iam/account  {displayName} → {status, data: {owner, name, displayName, avatar, …}}
+ *   POST /v1/account/avatar  multipart `file` → {avatar}   the photo, also written to IAM
+ *
+ * Both act on the caller alone: neither request names a person. The email is a
+ * sign-in identifier and changes only through IAM's verification, never here.
+ */
+import { type Target } from './call.ts';
+export interface Profile {
+    displayName: string;
+    avatar: string;
+}
+/** Save the name the person is shown by. An empty name is refused here. */
+export declare function rename(t: Target, name: string): Promise<Profile>;
+/** The formats the platform keeps a photo in; it decides by the bytes, this only filters the picker. */
+export declare const PHOTO = "image/png,image/jpeg,image/gif,image/webp";
+/** Store a new photo and answer its address. */
+export declare function photo(t: Target, file: Blob): Promise<string>;

package/lib/api/profile.js

@@ -0,0 +1,40 @@
+/**
+ * The signed-in person's own profile on Hanzo IAM: the name they are shown by
+ * and their photo.
+ *
+ *   PUT  /v1/iam/account  {displayName} → {status, data: {owner, name, displayName, avatar, …}}
+ *   POST /v1/account/avatar  multipart `file` → {avatar}   the photo, also written to IAM
+ *
+ * Both act on the caller alone: neither request names a person. The email is a
+ * sign-in identifier and changes only through IAM's verification, never here.
+ */
+import { call, headers, reason, Refusal, unwrap } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const obj = (v) => (v && typeof v === 'object' ? v : {});
+/** Save the name the person is shown by. An empty name is refused here. */
+export async function rename(t, name) {
+    const displayName = name.trim();
+    if (!displayName)
+        throw new Error('A name cannot be empty');
+    const p = obj(unwrap(await call(t, 'PUT', '/v1/iam/account', { displayName })));
+    return { displayName: str(p.displayName), avatar: str(p.avatar) };
+}
+/** The formats the platform keeps a photo in; it decides by the bytes, this only filters the picker. */
+export const PHOTO = 'image/png,image/jpeg,image/gif,image/webp';
+const LIMIT = 8 << 20;
+/** Store a new photo and answer its address. */
+export async function photo(t, file) {
+    if (!file.size)
+        throw new Error('That file is empty');
+    if (file.size > LIMIT)
+        throw new Error('A photo is at most 8 MB');
+    const form = new FormData();
+    form.append('file', file);
+    const res = await fetch(`${t.api}/v1/account/avatar`, { method: 'POST', headers: headers(t), body: form, cache: 'no-store' });
+    if (!res.ok)
+        throw new Refusal(res.status, (await reason(res)) || `POST /v1/account/avatar answered ${res.status}`);
+    const url = str(obj(await res.json()).avatar);
+    if (!url.startsWith('https://'))
+        throw new Refusal(502, 'The photo was stored without an address this page can show');
+    return url;
+}

package/lib/api/projects.d.ts

@@ -1,10 +1,15 @@
 /**
  * The org's projects: what it has built, and where each one is served.
  *
- *   GET /v1/projects → Project[]
+ *   GET    /v1/projects         → Project[]
+ *   PATCH  /v1/projects/{slug}  rename it, or make it public or private
+ *   DELETE /v1/projects/{slug}  delete it and take its site down
  *
  * `slug` is the one key every surface shares — the address under /dev, the
- * site's name, the `project` a run is tagged with.
+ * site's name, the `project` a run is tagged with. A project belongs to the org,
+ * not to a person: the record names no author, so any member lists, changes and
+ * deletes it. Private is paid, and an unfunded org is refused rather than left
+ * public without being told.
  */
 import { type Target } from './call.ts';
 export interface Project {
@@ -17,12 +22,24 @@ export interface Project {
     status: string;
     /** The deployed address, or '' when nothing has shipped. */
     live: string;
+    /** `public` or `private`, or '' when the platform did not say. */
+    visibility: '' | Visibility;
+    /** Unix seconds; 0 when unknown. A deploy does not move `updated`. */
+    created: number;
     updated: number;
 }
+export type Visibility = 'public' | 'private';
 /** An address the preview may frame: https, or http on loopback when the builder is local too. */
 export declare function safe(url: string, local?: boolean): string;
 export declare function project(raw: unknown): Project;
 export declare function projects(t: Target): Promise<Project[]>;
+/** Change a project's name or who can see it; what is not sent is left as it is. */
+export declare function change(t: Target, slug: string, what: {
+    name?: string;
+    visibility?: Visibility;
+}): Promise<Project>;
+/** Delete a project. Its site stops answering and its slug is free again. */
+export declare function remove(t: Target, slug: string): Promise<void>;
 /** The repository name a project's clone URL names — the last path segment, without `.git`. */
 export declare function name(clone: string): string;
 /** A starter from the public catalog. */

package/lib/api/projects.js

@@ -1,13 +1,19 @@
 /**
  * The org's projects: what it has built, and where each one is served.
  *
- *   GET /v1/projects → Project[]
+ *   GET    /v1/projects         → Project[]
+ *   PATCH  /v1/projects/{slug}  rename it, or make it public or private
+ *   DELETE /v1/projects/{slug}  delete it and take its site down
  *
  * `slug` is the one key every surface shares — the address under /dev, the
- * site's name, the `project` a run is tagged with.
+ * site's name, the `project` a run is tagged with. A project belongs to the org,
+ * not to a person: the record names no author, so any member lists, changes and
+ * deletes it. Private is paid, and an unfunded org is refused rather than left
+ * public without being told.
  */
-import { call } from './call.js';
+import { call, seg } from './call.js';
 const str = (v) => (typeof v === 'string' ? v : '');
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
 const loopback = (host) => host === 'localhost' || host === '127.0.0.1';
 /** Whether this page itself is served from loopback — local work. */
 const here = () => typeof window !== 'undefined' && loopback(window.location.hostname);
@@ -37,7 +43,9 @@ export function project(raw) {
         branch: str(repo.branch),
         status: str(p.status),
         live: safe(str(p.liveUrl)),
-        updated: typeof p.updatedAt === 'number' ? p.updatedAt : 0,
+        visibility: p.visibility === 'public' || p.visibility === 'private' ? p.visibility : '',
+        created: num(p.createdAt),
+        updated: num(p.updatedAt),
     };
 }
 export async function projects(t) {
@@ -48,6 +56,23 @@ export async function projects(t) {
         .filter((p) => p.slug)
         .sort((a, b) => b.updated - a.updated);
 }
+/** Change a project's name or who can see it; what is not sent is left as it is. */
+export async function change(t, slug, what) {
+    const body = {};
+    if (what.name !== undefined) {
+        const n = what.name.trim();
+        if (!n)
+            throw new Error('A project needs a name');
+        body.name = n;
+    }
+    if (what.visibility !== undefined)
+        body.visibility = what.visibility;
+    return project(await call(t, 'PATCH', `/v1/projects/${seg(slug)}`, body));
+}
+/** Delete a project. Its site stops answering and its slug is free again. */
+export async function remove(t, slug) {
+    await call(t, 'DELETE', `/v1/projects/${seg(slug)}`);
+}
 /** The repository name a project's clone URL names — the last path segment, without `.git`. */
 export function name(clone) {
     const cut = clone.replace(/\.git$/, '').replace(/\/+$/, '');

package/lib/api/provider.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 { type Target } from './call.ts';
+export interface Connector {
+    id: string;
+    name: string;
+    /** Whether this deployment can connect it at all. */
+    available: boolean;
+    connected: boolean;
+    /** The connected account's own name: the Slack workspace, the GitHub login. */
+    account: string;
+    since: string;
+    /** Why it cannot be connected here, when it cannot. */
+    note: string;
+}
+export declare function connector(raw: unknown, id?: string): Connector;
+export declare function read(t: Target, id: string): Promise<Connector>;
+/** The provider's consent page for this org. */
+export declare function authorize(t: Target, id: string): Promise<string>;
+export declare function disconnect(t: Target, id: string): Promise<void>;
+export interface Channel {
+    id: string;
+    name: string;
+    private: boolean;
+    /** Whether Hanzo has joined it. */
+    member: boolean;
+}
+export interface Channels {
+    channels: Channel[];
+    next: string;
+}
+export declare function channels(t: Target, cursor?: string): Promise<Channels>;

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/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":{…}}
  *
@@ -37,6 +40,10 @@ export interface Session {
     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;
@@ -64,13 +71,34 @@ export declare function took(runs: Session[], mode: string): [number, number] |
 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":{…}}
  *
@@ -35,6 +38,8 @@ export function session(raw) {
         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),
@@ -68,9 +73,15 @@ export function took(runs, mode) {
     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 list(t, q = {}) {
+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)}`));
@@ -88,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();
+}