@hanzo/build 0.2.80 → 0.2.82

package/README.md

@@ -100,6 +100,19 @@ nothing behind a More; `useSessions(host)` is the runs — the org's coding runs
 kept live by the org's feed — for a host that draws the rows itself. `administers(token, org)` reads the org-admin bit off a
 hanzo.id token for `Host.admin`. One left column, never two.
 
+## Words
+
+Every word the builder authors is said through @hanzo/i18n, a required peer
+(`>=0.4.0`): the host's `I18nProvider` is the one asked, and without one the
+builder reads in English, unchanged. A component asks `useI18n()`; copy held as
+data is `phrase()` where it is written and drawn through `t`; a helper outside a
+render (`nav()`, `own()`, `tabs()`, `library()`, turn.ts, the plan sentences)
+takes the caller's `t` last and falls back to `say.ts`'s `english`. Names, model
+ids, what a person typed, what the platform said and figures are drawn as given;
+prompts sent to a model stay in English. `src/e2e/language*.spec.ts` and
+`translated.spec.ts` hold the composer, Projects, Skills and the Library in
+French and right to left in Arabic.
+
 ## The model, the composer, the panel
 
 One of each, shared with Chat (@hanzo/rooms imports them):

package/lib/activity.d.ts

@@ -1,8 +1,4 @@
-/**
- * Activity's words: what a run's state is called and drawn as, how long it
- * took, what it cost, and the one line under its title. Pure, so the screen and
- * its tests read the same sentences.
- */
+import type { Say } from '@hanzo/i18n/react';
 import type { SessionStatus } from '@hanzo/ui/chat';
 import type { Job, State } from './api/auto.ts';
 /** A job's state as the rail's dot draws it, and in words. */
@@ -12,8 +8,8 @@ export declare const SAID: Record<State, string>;
 export declare function lasted(started: string, finished: string | null, now?: number): string;
 /** Cents as dollars. */
 export declare const dollars: (cents: number) => string;
-/** One line about a job: when it started, how long, what it cost, what it made. */
-export declare function about(j: Job, now?: number): string;
+/** One line about a job: when it started, how long, what it cost, what it made. Its words in the language of `t`. */
+export declare function about(j: Job, now?: number, t?: Say): string;
 /** The jobs, newest first, with `j` in its place. */
 export declare function merged(list: Job[], j: Job): Job[];
 /** A task's name from what it does: its first line, short. */

package/lib/activity.js

@@ -1,8 +1,21 @@
+/**
+ * Activity's words: what a run's state is called and drawn as, how long it
+ * took, what it cost, and the one line under its title. Pure, so the screen and
+ * its tests read the same sentences.
+ */
+import { phrase } from '@hanzo/i18n';
 import { ago } from './ago.js';
 import { SOURCE } from './api/library.js';
+import { english } from './say.js';
 /** A job's state as the rail's dot draws it, and in words. */
 export const DOTS = { scheduled: 'idle', running: 'running', succeeded: 'done', failed: 'error', cancelled: 'stopped' };
-export const SAID = { scheduled: 'Scheduled', running: 'Running', succeeded: 'Succeeded', failed: 'Failed', cancelled: 'Cancelled' };
+export const SAID = {
+    scheduled: phrase('Scheduled'),
+    running: phrase('Running'),
+    succeeded: phrase('Succeeded'),
+    failed: phrase('Failed'),
+    cancelled: phrase('Cancelled'),
+};
 /** How long a run took, or has taken so far. */
 export function lasted(started, finished, now = Date.now()) {
     const a = Date.parse(started);
@@ -20,10 +33,10 @@ export function lasted(started, finished, now = Date.now()) {
 }
 /** Cents as dollars. */
 export const dollars = (cents) => `$${(cents / 100).toFixed(2)}`;
-/** One line about a job: when it started, how long, what it cost, what it made. */
-export function about(j, now = Date.now()) {
-    const made = j.outputs.length ? `${j.outputs.length} ${j.outputs.length === 1 ? 'output' : 'outputs'}` : '';
-    return [SOURCE[j.product], j.started ? ago(j.started) : '', lasted(j.started, j.finished, now), j.cost !== null ? dollars(j.cost) : '', made].filter(Boolean).join(' · ');
+/** One line about a job: when it started, how long, what it cost, what it made. Its words in the language of `t`. */
+export function about(j, now = Date.now(), t = english) {
+    const made = j.outputs.length ? (j.outputs.length === 1 ? t('{n} output', { n: 1 }) : t('{n} outputs', { n: j.outputs.length })) : '';
+    return [SOURCE[j.product] ? t(SOURCE[j.product]) : '', j.started ? ago(j.started) : '', lasted(j.started, j.finished, now), j.cost !== null ? dollars(j.cost) : '', made].filter(Boolean).join(' · ');
 }
 /** The jobs, newest first, with `j` in its place. */
 export function merged(list, j) {

package/lib/api/agents.d.ts

@@ -1,22 +1,3 @@
-/**
- * Agents: the org's own — a model, instructions, the tools it may call, a
- * budget and a face — and the templates one is made from.
- *
- *   GET    /v1/agent                 {agents: [agent]}, without instructions
- *   POST   /v1/agent                 create → 201 agent
- *   GET    /v1/agent/{ref}           one, with its instructions
- *   PATCH  /v1/agent/{ref}           the fields sent change, the rest stay → agent
- *   DELETE /v1/agent/{ref}           removes it and every run recorded against it → 204
- *   GET    /v1/agent/chat/presets    {presets: [{id, title, systemPrompt, serverExecuted}]}
- *
- * A ref is the agent's id or its name. A budget is required: the most it may
- * spend in a period and in one run, in micro-USD, and the period — day, week or
- * month. Tools are names from the tool plane; none grants none, and `*` is
- * whatever the fleet's MCP server serves when it runs. An omitted model is the
- * deployment's default. A preset whose tool calls run on the platform
- * (`serverExecuted`) makes a working agent; the others hand their calls back to
- * the client that asked, so they are not offered here.
- */
 import { type Target } from './call.ts';
 export type Period = 'day' | 'week' | 'month';
 export declare const PERIODS: readonly Period[];
@@ -69,7 +50,7 @@ export declare function agent(raw: unknown): Agent;
 /** A draft of an agent as it stands, to edit. */
 export declare function draft(a: Agent): Draft;
 export declare const EMPTY: Draft;
-/** Why a draft cannot be saved as it stands, or '' when it can. */
+/** Why a draft cannot be saved as it stands, or '' when it can: English, marked (`phrase`), so a screen says it through `t`. */
 export declare function refuse(d: Draft): string;
 export declare function agents(t: Target): Promise<Agent[]>;
 export declare function one(t: Target, ref: string): Promise<Agent>;

package/lib/api/agents.js

@@ -17,6 +17,7 @@
  * (`serverExecuted`) makes a working agent; the others hand their calls back to
  * the client that asked, so they are not offered here.
  */
+import { phrase } from '@hanzo/i18n';
 import { call, seg } from './call.js';
 export const PERIODS = ['day', 'week', 'month'];
 /** An agent's name, as the handler takes it. */
@@ -66,20 +67,27 @@ export function draft(a) {
     };
 }
 export const EMPTY = { name: '', description: '', model: '', instructions: '', tools: [], cap: '', task: '', period: 'month', avatar: '' };
-/** Why a draft cannot be saved as it stands, or '' when it can. */
+/** What a budget left unset says, and one run that outspends its period, by the period: whole sentences, so a language says the period its own way. */
+const UNSET = { day: phrase('Set what it may spend each day'), week: phrase('Set what it may spend each week'), month: phrase('Set what it may spend each month') };
+const OVER = {
+    day: phrase('One run cannot spend more than the whole day'),
+    week: phrase('One run cannot spend more than the whole week'),
+    month: phrase('One run cannot spend more than the whole month'),
+};
+/** Why a draft cannot be saved as it stands, or '' when it can: English, marked (`phrase`), so a screen says it through `t`. */
 export function refuse(d) {
     if (!NAME.test(d.name))
-        return 'A name is letters, digits, . _ or -, starting with a letter or digit';
+        return phrase('A name is letters, digits, . _ or -, starting with a letter or digit');
     if (new TextEncoder().encode(d.instructions).length > MAX)
-        return 'Instructions are at most 32 KB';
+        return phrase('Instructions are at most 32 KB');
     const cap = micros(d.cap);
     const task = micros(d.task);
     if (!(cap > 0))
-        return 'Set what it may spend each ' + d.period;
+        return UNSET[d.period];
     if (!(task > 0))
-        return 'Set what one run may spend';
+        return phrase('Set what one run may spend');
     if (task > cap)
-        return 'One run cannot spend more than the whole ' + d.period;
+        return OVER[d.period];
     return '';
 }
 export async function agents(t) {
@@ -142,7 +150,7 @@ export async function use(t, c, base) {
 export function person(name, about, writing, avatar = '') {
     const who = name.trim();
     const lines = [`You are ${who}.`, about.trim(), writing.trim() && `Writing by ${who}:\n\n${writing.trim()}`];
-    return { name: who, title: who, description: about.trim(), category: 'Person', model: '', instructions: lines.filter(Boolean).join('\n\n'), avatar };
+    return { name: who, title: who, description: about.trim(), category: phrase('Person'), model: '', instructions: lines.filter(Boolean).join('\n\n'), avatar };
 }
 export async function create(t, d) {
     const why = refuse(d);
@@ -204,5 +212,5 @@ export async function presets(t) {
 }
 /** A preset as a template. */
 export function fromPreset(p) {
-    return { name: p.id, title: p.title || p.id, description: p.title, category: 'Preset', model: '', instructions: p.prompt };
+    return { name: p.id, title: p.title || p.id, description: p.title, category: phrase('Preset'), model: '', instructions: p.prompt };
 }

package/lib/api/auto.d.ts

@@ -1,24 +1,4 @@
-/**
- * Automations: a task that runs itself, on a schedule or when asked.
- *
- *   GET    /v1/auto/automations            {data: [automation]}
- *   POST   /v1/auto/automations            create one: name and instructions
- *   GET    /v1/auto/automations/{id}       one
- *   PATCH  /v1/auto/automations/{id}       change it, or switch it on or off
- *   DELETE /v1/auto/automations/{id}       delete it, its schedule and its runs
- *   POST   /v1/auto/automations/{id}/run   {run: {id, status}}  one run, now
- *   GET    /v1/auto/automations/{id}/runs  {data: [run]}        newest first
- *   POST   /v1/auto/automations/{id}/runs/{run}/review  {post}  post a held post, or discard it
- *   GET    /v1/auto/templates              {data: [starter]}    to start a new one from
- *   POST   /v1/auto/cron                   {schedule, says, next}  a schedule from a person's words
- *   GET    /v1/auto/jobs                   {data: [job]}        what runs without you, across products
- *   GET    /v1/auto/jobs/{id}              one job
- *   GET    /v1/auto/events                 text/event-stream: `job` and `automation`, the reader's own
- *
- * Each run is one Dev run in this organization, started as the person who last
- * saved what it does. A draft is a flow named and not yet told what to do: it
- * runs once its instructions are saved.
- */
+import type { Say } from '@hanzo/i18n/react';
 import { type Target } from './call.ts';
 import { type Source } from './library.ts';
 export type { Source };
@@ -107,8 +87,8 @@ export declare function start(t: Target, id: string): Promise<{
 export declare function runs(t: Target, id: string): Promise<Run[]>;
 /** Post a held post to the automation's accounts, or discard it. */
 export declare function review(t: Target, id: string, runId: string, post: boolean): Promise<Run>;
-/** A schedule the way a person says it. */
-export declare function words(s: Schedule): string;
+/** A schedule the way a person says it, in the words of the `t` handed (English without one). */
+export declare function words(s: Schedule, t?: Say): string;
 /** A ready-made automation to start a new one from. Its schedule names no zone: the page fills in the person's. */
 export interface Starter {
     key: string;

package/lib/api/auto.js

@@ -19,6 +19,8 @@
  * saved what it does. A draft is a flow named and not yet told what to do: it
  * runs once its instructions are saved.
  */
+import { phrase } from '@hanzo/i18n';
+import { english } from '../say.js';
 import { call, headers, query, reason, Refusal, seg } from './call.js';
 import { inApp } from './library.js';
 import { read as stream } from './sse.js';
@@ -78,13 +80,13 @@ export async function automations(t) {
 export async function automation(t, id) {
     const a = read(await call(t, 'GET', `/v1/auto/automations/${seg(id)}`));
     if (!a)
-        throw new Error('The automation came back without an id');
+        throw new Error(phrase('The automation came back without an id'));
     return a;
 }
 export async function create(t, d) {
     const a = read(await call(t, 'POST', '/v1/auto/automations', d));
     if (!a)
-        throw new Error('The automation was created and came back without an id');
+        throw new Error(phrase('The automation was created and came back without an id'));
     return a;
 }
 /** What changed between two drafts, field by field: what a save sends. */
@@ -100,7 +102,7 @@ export function changes(was, now) {
 export async function save(t, id, change) {
     const a = read(await call(t, 'PATCH', `/v1/auto/automations/${seg(id)}`, change));
     if (!a)
-        throw new Error('The automation was saved and came back without an id');
+        throw new Error(phrase('The automation was saved and came back without an id'));
     return a;
 }
 export async function remove(t, id) {
@@ -130,40 +132,55 @@ function run(o) {
 export async function review(t, id, runId, post) {
     return run(obj(await call(t, 'POST', `/v1/auto/automations/${seg(id)}/runs/${seg(runId)}/review`, { post })));
 }
-const DAYS = { mon: 'Mondays', tue: 'Tuesdays', wed: 'Wednesdays', thu: 'Thursdays', fri: 'Fridays', sat: 'Saturdays', sun: 'Sundays' };
-/** A once schedule's local date and time, as a person reads it. */
+/** A weekly schedule's sentence by its day: one sentence each, so a language says the day its own way. */
+const DAYS = {
+    mon: phrase('Mondays at {time} · {zone}'),
+    tue: phrase('Tuesdays at {time} · {zone}'),
+    wed: phrase('Wednesdays at {time} · {zone}'),
+    thu: phrase('Thursdays at {time} · {zone}'),
+    fri: phrase('Fridays at {time} · {zone}'),
+    sat: phrase('Saturdays at {time} · {zone}'),
+    sun: phrase('Sundays at {time} · {zone}'),
+};
+/** A once schedule's local date, as a person reads it, and its time. */
 function once(at) {
     const m = at.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/);
     if (!m)
-        return at;
+        return null;
     const d = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5]));
-    return `${d.toLocaleDateString(undefined, { weekday: 'short', month: 'short', day: 'numeric' })} at ${m[4]}:${m[5]}`;
+    return { date: d.toLocaleDateString(undefined, { weekday: 'short', month: 'short', day: 'numeric' }), time: `${m[4]}:${m[5]}` };
 }
-/** A schedule the way a person says it. */
-export function words(s) {
-    const zone = ` · ${s.tz || 'UTC'}`;
+/** A schedule the way a person says it, in the words of the `t` handed (English without one). */
+export function words(s, t = english) {
+    const zone = s.tz || 'UTC';
     switch (s.kind) {
         case 'manual':
-            return 'When you run it';
-        case 'once':
-            return s.at ? `Once, ${once(s.at)}${zone}` : 'Once, now';
+            return t('When you run it');
+        case 'once': {
+            if (!s.at)
+                return t('Once, now');
+            const when = once(s.at);
+            return when ? t('Once, {date} at {time} · {zone}', { ...when, zone }) : t('Once, {at} · {zone}', { at: s.at, zone });
+        }
         case 'hourly':
-            return `Every hour at :${(s.at ?? '00:00').slice(3) || '00'}`;
+            return t('Every hour at :{minute}', { minute: (s.at ?? '00:00').slice(3) || '00' });
         case 'daily':
-            return `Every day at ${s.at}${zone}`;
+            return t('Every day at {time} · {zone}', { time: s.at ?? '', zone });
         case 'weekdays':
-            return `Weekdays at ${s.at}${zone}`;
-        case 'weekly':
-            return `${DAYS[s.day ?? ''] ?? s.day} at ${s.at}${zone}`;
+            return t('Weekdays at {time} · {zone}', { time: s.at ?? '', zone });
+        case 'weekly': {
+            const day = DAYS[s.day ?? ''];
+            return day ? t(day, { time: s.at ?? '', zone }) : t('{day} at {time} · {zone}', { day: s.day ?? '', time: s.at ?? '', zone });
+        }
         case 'cron': {
             // The two a person says most, in their words; any other expression as written.
             const minutes = (s.cron ?? '').match(/^\*\/(\d+) \* \* \* \*$/);
             if (minutes)
-                return `Every ${minutes[1]} minutes${zone}`;
+                return t('Every {n} minutes · {zone}', { n: minutes[1], zone });
             const hours = (s.cron ?? '').match(/^0 \*\/(\d+) \* \* \*$/);
             if (hours)
-                return `Every ${hours[1]} hours${zone}`;
-            return `Cron ${s.cron}${zone}`;
+                return t('Every {n} hours · {zone}', { n: hours[1], zone });
+            return t('Cron {cron} · {zone}', { cron: s.cron ?? '', zone });
         }
     }
 }
@@ -241,7 +258,7 @@ export async function jobs(t, f = {}) {
 export async function one(t, id) {
     const j = job(await call(t, 'GET', `/v1/auto/jobs/${seg(id)}`));
     if (!j)
-        throw new Error('The job came back without an id');
+        throw new Error(phrase('The job came back without an id'));
     return j;
 }
 /** One frame of /v1/auto/events, or null for one this page does not read. */

package/lib/api/billing.d.ts

@@ -1,38 +1,3 @@
-/**
- * The organization's money: its plan, the cards it pays with, its invoices, its
- * balance and credits, what it has spent this month, and the caps on that spend.
- *
- *   GET    /v1/billing/plans                     the catalog the serving brand sells (public)
- *   GET    /v1/billing/subscriptions             {count, subscriptions}
- *   POST   /v1/billing/subscribe/card            buy a plan with a saved card; one paid plan at a time (409)
- *   POST   /v1/billing/subscriptions/{id}/cancel     at the end of the paid period
- *   POST   /v1/billing/subscriptions/{id}/reactivate
- *   GET    /v1/billing/methods                   saved cards, newest first
- *   POST   /v1/billing/methods                   save a card from the processor's single-use token
- *   DELETE /v1/billing/methods/{id}
- *   GET    /v1/billing/settings                  the processor a browser tokenizes a card against
- *   GET    /v1/billing/invoices                  {count, cursor, invoices}
- *   GET    /v1/billing/invoices/{id}/pdf         the invoice as a PDF
- *   GET    /v1/billing/balance                   prepaid balance, whole cents
- *   GET    /v1/billing/credit-balance            granted credit, per currency
- *   GET    /v1/billing/credits                   {grants}: every grant, spent and lapsed included
- *   GET    /v1/billing/tier                      the rung served and its tier class
- *   GET    /v1/billing/recharge                  the auto-reload rule
- *   PUT    /v1/billing/recharge                  arm it (a card on file) or disarm it
- *   POST   /v1/billing/topup                     charge a saved card into the balance
- *   GET    /v1/billing/usage/rollup              the plan's month: included spend and request windows
- *   GET    /v1/usage/summary?range=month         this month's spend, by category
- *   GET    /v1/allowance                         the Free plan's allowance, and the pool it is served from
- *   GET    /v1/billing/alerts                    spend caps (bare array)
- *   POST   /v1/billing/alerts                    open a cap (org admin)
- *   PATCH  /v1/billing/alerts/{id}               change one (org admin)
- *   DELETE /v1/billing/alerts/{id}               lift one (org admin)
- *
- * Every figure is whole cents. The wallet, the caps and the cards are the
- * caller's own, resolved by the platform from the credential; nothing here names
- * an org or a subject. No card number passes through this file: a card is saved
- * from the token the processor's own form returns.
- */
 import { type Target } from './call.ts';
 /** `$1,234.56` from whole cents; whole dollars drop the cents. */
 export declare function money(cents: number, currency?: string): string;

package/lib/api/billing.js

@@ -33,6 +33,7 @@
  * an org or a subject. No card number passes through this file: a card is saved
  * from the token the processor's own form returns.
  */
+import { phrase } from '@hanzo/i18n';
 import { call, headers, reason, Refusal, seg } from './call.js';
 const str = (v) => (typeof v === 'string' ? v : '');
 const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
@@ -115,7 +116,7 @@ export async function subscriptions(t) {
 /** Buy a plan. No amount is sent: the catalog prices it, and the platform charges that. */
 export async function subscribe(t, p) {
     if (!p.method)
-        throw new Error('Add a card before choosing a paid plan');
+        throw new Error(phrase('Add a card before choosing a paid plan'));
     const raw = obj(await call(t, 'POST', '/v1/billing/subscribe/card', { planId: p.plan, paymentMethodId: p.method, interval: p.interval }));
     return { subscription: str(raw.subscriptionId), charged: num(raw.amountCents) };
 }
@@ -183,7 +184,7 @@ export function chosen(list) {
 /** Save a card from the single-use token the processor's form returned, optionally with billing info. */
 export async function save(t, token, billingAddress) {
     if (!token)
-        throw new Error('The card form returned no token');
+        throw new Error(phrase('The card form returned no token'));
     const body = { type: 'card', providerRef: token };
     if (billingAddress && Object.values(billingAddress).some(Boolean)) {
         body.billingAddress = billingAddress;
@@ -299,9 +300,9 @@ export async function arm(t, rule) {
 /** Charge a saved card and add the amount to the balance; answers the balance after. */
 export async function topup(t, amount, card) {
     if (!Number.isInteger(amount) || amount <= 0)
-        throw new Error('Enter an amount to add');
+        throw new Error(phrase('Enter an amount to add'));
     if (!card)
-        throw new Error('Add a card before buying more');
+        throw new Error(phrase('Add a card before buying more'));
     const r = obj(await call(t, 'POST', '/v1/billing/topup', { amountCents: amount, paymentMethodId: card }));
     return num(r.balanceCents);
 }
@@ -371,7 +372,7 @@ export function monthly(list) {
 /** Set the org's monthly cap: change the one there is, or open one that refuses spend past it. */
 export async function limit(t, list, threshold) {
     if (!Number.isInteger(threshold) || threshold <= 0)
-        throw new Error('Enter a monthly limit');
+        throw new Error(phrase('Enter a monthly limit'));
     const was = monthly(list);
     if (was)
         return cap(await call(t, 'PATCH', `/v1/billing/alerts/${seg(was.id)}`, { threshold }));

package/lib/api/call.d.ts

@@ -1,11 +1,4 @@
-/**
- * One request path to the platform.
- *
- * Every typed op below goes through `call`, so the bearer, the org scope, the
- * no-store cache rule and the reading of a refusal are decided once. The
- * platform answers a refusal as RFC 9457 problem details; older handlers still
- * answer `{error:{message}}` or `{msg}`, and all three read the same way here.
- */
+import type { Say } from '@hanzo/i18n/react';
 /** Where the platform is and who is asking. The host supplies it. */
 export interface Target {
     /** The platform origin, no trailing slash: calls are `${api}/v1/…`. */
@@ -20,6 +13,21 @@ export declare class Refusal extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/**
+ * A sentence this client wrote with something of the moment in it (a file's
+ * name, an address), thrown where no `t` is at hand: its message is the
+ * English, filled, and a screen says it from its source and values.
+ */
+export declare class Sentence extends Error {
+    readonly source: string;
+    readonly values: Readonly<Record<string, string | number>>;
+    constructor(source: string, values?: Readonly<Record<string, string | number>>);
+}
+/**
+ * An error's own sentence, as the screen that caught it says it: one this
+ * client wrote, in the reader's language; the platform's, which is no key, as given.
+ */
+export declare function told(e: unknown, t?: Say): string;
 export type Query = Record<string, string | number | boolean | null | undefined>;
 /** `?a=1&b=2` from the defined, non-empty entries of `q`, or ''. */
 export declare function query(q?: Query): string;

package/lib/api/call.js

@@ -5,7 +5,15 @@
  * no-store cache rule and the reading of a refusal are decided once. The
  * platform answers a refusal as RFC 9457 problem details; older handlers still
  * answer `{error:{message}}` or `{msg}`, and all three read the same way here.
+ *
+ * A sentence this client writes is English, marked (`phrase`) for the
+ * translator: a module is not a component and asks no `t`, so a screen says
+ * what a module threw through its own (`told`), and a module that builds text
+ * takes the screen's `t` as its last argument, English (../say.ts `english`)
+ * when none is handed.
  */
+import { phrase, translate } from '@hanzo/i18n';
+import { english } from '../say.js';
 /** A refusal: the status, and the platform's own sentence for it. */
 export class Refusal extends Error {
     status;
@@ -15,6 +23,29 @@ export class Refusal extends Error {
         this.name = 'Refusal';
     }
 }
+/**
+ * A sentence this client wrote with something of the moment in it (a file's
+ * name, an address), thrown where no `t` is at hand: its message is the
+ * English, filled, and a screen says it from its source and values.
+ */
+export class Sentence extends Error {
+    source;
+    values;
+    constructor(source, values = {}) {
+        super(translate({}, source, values));
+        this.source = source;
+        this.values = values;
+    }
+}
+/**
+ * An error's own sentence, as the screen that caught it says it: one this
+ * client wrote, in the reader's language; the platform's, which is no key, as given.
+ */
+export function told(e, t = english) {
+    if (e instanceof Sentence)
+        return t(e.source, e.values);
+    return t(e instanceof Error ? e.message : String(e));
+}
 /** `?a=1&b=2` from the defined, non-empty entries of `q`, or ''. */
 export function query(q = {}) {
     const s = new URLSearchParams();
@@ -81,6 +112,6 @@ export async function call(t, method, path, body, init) {
 export function unwrap(raw) {
     const r = (raw && typeof raw === 'object' ? raw : {});
     if (r.status === 'error')
-        throw new Refusal(400, typeof r.msg === 'string' && r.msg ? r.msg : 'The platform refused that');
+        throw new Refusal(400, typeof r.msg === 'string' && r.msg ? r.msg : phrase('The platform refused that'));
     return r.data;
 }

package/lib/api/capabilities.d.ts

@@ -1,14 +1,3 @@
-/**
- * What the agent may use: every tool the org can reach, and which of them are
- * switched on.
- *
- *   GET /v1/tool → {tools: [{name, source, description, dispatchable, activated}]}
- *   PUT /v1/tool/activation  {activate: [], deactivate: []} → {enabled: []}
- *
- * Activation is per org (and project): a tool that is off is listed but
- * refused when an agent calls it. At most 256 names go in one request, so a
- * larger change is sent in turns.
- */
 import { type Target } from './call.ts';
 /** Where a tool comes from, in the order the platform ranks them. */
 export declare const SOURCES: readonly ['connector', 'function', 'zap-service', 'agent', 'skill', 'mcp'];

package/lib/api/capabilities.js

@@ -9,6 +9,7 @@
  * refused when an agent calls it. At most 256 names go in one request, so a
  * larger change is sent in turns.
  */
+import { phrase } from '@hanzo/i18n';
 import { call } from './call.js';
 /** Where a tool comes from, in the order the platform ranks them. */
 export const SOURCES = ['connector', 'function', 'zap-service', 'agent', 'skill', 'mcp'];
@@ -29,7 +30,7 @@ export async function tools(t) {
 /** Switch every tool in `names` on (or off), and answer the org's activated set. */
 export async function activate(t, names, on) {
     if (!names.length)
-        throw new Error('There is nothing to switch');
+        throw new Error(phrase('There is nothing to switch'));
     let enabled = [];
     for (let i = 0; i < names.length; i += BATCH) {
         const part = names.slice(i, i + BATCH);

package/lib/api/codebases.d.ts

@@ -1,13 +1,3 @@
-/**
- * Codebases on the forge, the org's own git.
- *
- *   GET /v1/git/repos          {data: [repo]}   most recently updated first
- *   GET /v1/git/repos/{name}   one repo, with its branch names
- *
- * A coding run addresses a repository by its name. The org is the tenant on
- * the request, so the name is the whole address — `owner/name` is a path the
- * engine refuses.
- */
 import { type Target } from './call.ts';
 export interface Codebase {
     org: string;

package/lib/api/codebases.js

@@ -8,6 +8,7 @@
  * the request, so the name is the whole address — `owner/name` is a path the
  * engine refuses.
  */
+import { phrase } from '@hanzo/i18n';
 import { call, seg } from './call.js';
 const str = (v) => (typeof v === 'string' ? v : '');
 const obj = (v) => v && typeof v === 'object' ? v : {};
@@ -69,11 +70,11 @@ const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 export async function create(t, name, description = '') {
     const handle = name.trim().replace(/\.git$/, '');
     if (!NAME.test(handle))
-        throw new Error('A repository name starts with a letter or number, and may contain letters, numbers, dots, underscores and hyphens.');
+        throw new Error(phrase('A repository name starts with a letter or number, and may contain letters, numbers, dots, underscores and hyphens.'));
     const raw = await call(t, 'POST', '/v1/git/repos', { name: handle, description: description.trim() });
     const row = codebase(raw, t.org ?? '');
     if (!row)
-        throw new Error('The forge created a repository and did not name it');
+        throw new Error(phrase('The forge created a repository and did not name it'));
     return row;
 }
 export async function codebases(t, q = '') {

package/lib/api/coding.d.ts

@@ -1,37 +1,8 @@
-/**
- * Starting a coding run, and what it left.
- *
- *   POST /v1/agent/coding → 202 {sessionId, repo, branch, routed, targetId}
- *   GET  /v1/agent/coding/{session}/artifacts          {session, saved, artifacts}
- *   GET  /v1/agent/coding/{session}/artifacts/{name}   one stored artifact's bytes
- *
- * 202 is ADMITTED, not finished: the answer is the session the run narrates
- * itself in, and the session stream is how it is watched.
- *
- * Where it runs is one field. No `targetId` is the platform's sandbox; a target
- * id routes it to one of the org's machines, and `routed` says whether it got
- * there.
- *
- * `mode` is what the run may do: `build` edits, commits and pushes its branch;
- * `plan` reads the repository with a credential that can only read and answers
- * with a plan, as its final status. A plan runs in the platform's sandbox only —
- * a claimed machine clones and pushes with its own credential — so a plan
- * routed to one is refused, here before sending as on the platform.
- *
- * `model` and `effort` are taken by the dev harness the builder runs (and by
- * codex); the builder names no other harness, so they are always honoured.
- *
- * `setup` is a plan's shape put to one question: how this codebase is installed,
- * started and checked. Its agent may install and run things in its sandbox, and
- * its answer is kept as the codebase's proposed environment (environment.ts).
- *
- * A sandbox run keeps its sandbox after it ends, so `after` continues the earlier
- * run in that same sandbox and working tree, resumed if it parked.
- */
+import type { Say } from '@hanzo/i18n/react';
 import { type Target } from './call.ts';
 export type Mode = 'build' | 'plan' | 'setup';
-/** Why this mode cannot run where it is sent, or '' when it can. */
-export declare const unhonoured: (mode: Mode | undefined, target?: string) => string;
+/** Why this mode cannot run where it is sent, in the words of the `t` handed (English without one), or '' when it can. */
+export declare const unhonoured: (mode: Mode | undefined, target?: string, t?: Say) => string;
 export interface Ask {
     /** The task, in the words you would use with a colleague. */
     prompt: string;