@hanzo/rooms 0.1.0

package/dist/lib/account.js

@@ -0,0 +1,229 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useState, useEffect, useMemo } from 'react';
+import { useIam, useIamIdentity, useIamToken, useOrganizations } from '@hanzo/iam/react';
+import { iam } from './api.js';
+const AccountContext = createContext(undefined);
+function mapUser(u) {
+    return {
+        id: u.id ?? u.name,
+        name: u.displayName || u.name,
+        email: u.email ?? '',
+        avatar: u.avatar,
+        phone: u.phone,
+        bio: u.bio,
+        location: u.location,
+        // IAM calls it `homepage`; this app calls it a website. One name each side,
+        // translated at the seam rather than in every screen.
+        website: u.homepage,
+        joinedDate: u.createdTime,
+    };
+}
+/** An organization as the signed `orgs` claim names it: a name and a display name (@hanzo/iam `useOrganizations`). */
+function mapOrg(o, role) {
+    return {
+        id: o.name,
+        name: o.displayName || o.name,
+        role: role ?? 'member',
+        members: [],
+    };
+}
+// ── The write ──────────────────────────────────────────────────────────────
+//
+// IAM owns the person. There is no second store to keep a name or a picture in,
+// so a profile edit is a write to IAM and this page has succeeded when that has.
+//
+// `PUT /v1/iam/account` IS THE DOOR, and it is the only one a person has. The
+// request names no target — the subject is whoever holds the token — so no
+// shape of it reaches somebody else's record, and that property is exactly why
+// a regular person may send it. The typed CRUD write beside it binds a WHOLE
+// user from the body, which is an act only an administrator may perform (a
+// full-row write is how a reader would carry `isAdmin` on their own row), so
+// reaching for that one made changing a picture a privilege: the read
+// succeeded, the write was refused, and the picture stayed on screen over a row
+// that had not changed.
+//
+// A PATCH, NOT A ROW. Every field is optional: one omitted keeps the value it
+// had and one sent empty clears it. So the panel that saves a picture cannot
+// blank a biography it never drew, and two screens saving at once do not undo
+// each other — which is also why there is nothing to read first.
+//
+// FOUR FIELDS, because four is what IAM lets a person write about themselves.
+// An email address and a phone number are LOGIN IDENTIFIERS and second-factor
+// destinations: moving where a code is delivered is a credential act, safe only
+// once the new address has proved it can receive one. That is the verification
+// flow's job, not a profile save's, so they are not here and this app does not
+// draw a control that pretends otherwise.
+/** IAM's self-scoped account door, at the host's IAM. */
+const account = () => `${iam()}/v1/iam/account`;
+// ── The read ───────────────────────────────────────────────────────────────
+//
+// THE SAME DOOR, and that is the point: the row this page edits is the row it
+// draws. `PUT /v1/iam/account` names no target and neither does the GET — the
+// subject is whoever holds the token — so a person reads their own record and
+// nobody else's, which is why a regular person may ask.
+//
+// It reads the ROW because a token does not carry one. `IamProvider` sets its
+// `user` to the OIDC userinfo response, which answers who you are (sub, name,
+// email, picture) and nothing about the record: no avatar under that name, no
+// bio, no homepage, no phone, no joined date, and no id. Read as a row it is
+// a person with no picture and empty fields — the profile page drew "Add a
+// picture" over an account that had one.
+/** IAM's answer, whether it wraps the row or is the row. */
+function row(said) {
+    if (!said || typeof said !== 'object')
+        return null;
+    const body = said;
+    if (body.status === 'error')
+        return null;
+    const it = (body.data ?? said);
+    return it && typeof it === 'object' ? it : null;
+}
+async function fetchAccount(token) {
+    // The bearer is the whole proof, so the request carries no cookie — the same
+    // reason the write does not.
+    const res = await fetch(account(), { headers: { Authorization: `Bearer ${token}` } });
+    if (!res.ok)
+        return null;
+    return row(await res.json().catch(() => null));
+}
+/** IAM's names for what this app calls a profile. */
+function fields(patch) {
+    const body = {};
+    if (patch.name !== undefined)
+        body.displayName = patch.name;
+    if (patch.bio !== undefined)
+        body.bio = patch.bio;
+    // IAM calls it `homepage`; this app calls it a website. One name each side,
+    // translated at the seam rather than in every screen.
+    if (patch.website !== undefined)
+        body.homepage = patch.website;
+    if (patch.avatar !== undefined)
+        body.avatar = patch.avatar;
+    return body;
+}
+/** What IAM said went wrong. A refused image names its own limit, and that
+ *  sentence is the useful half of the answer. */
+function reason(said, status) {
+    return said?.msg || `Could not save (${status}).`;
+}
+async function store(token, patch) {
+    const body = fields(patch);
+    // Nothing IAM stores changed, so there is nothing to ask it.
+    if (Object.keys(body).length === 0)
+        return;
+    // THE BEARER IS THE WHOLE PROOF, so the request carries no cookie. IAM opens
+    // this path to a browser on the strength of a token in a header — asking for
+    // credentials as well means the browser demands an
+    // `Access-Control-Allow-Credentials` on the answer, and where the origin does
+    // not get one the save fails as a network error with no status and no
+    // sentence to show the reader.
+    const res = await fetch(account(), {
+        method: 'PUT',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const said = await res.json().catch(() => null);
+    if (!res.ok || said?.status === 'error')
+        throw new Error(reason(said, res.status));
+}
+export const AccountProvider = ({ children }) => {
+    const { user: iamUser, isLoading: authLoading } = useIam();
+    const { token } = useIamToken();
+    const { organizations: iamOrgs, roles, currentOrgId, switchOrg, isLoading: orgsLoading } = useOrganizations();
+    const identity = useIamIdentity();
+    // Held against the token it was read with. A row is about ONE person, so a
+    // token change must not leave the previous account's picture on screen while
+    // the next one is in flight — reading it back through the token is what makes
+    // that impossible rather than merely brief.
+    const [held, setHeld] = useState(null);
+    const account = held && token && held.of === token ? held.row : null;
+    const [userOverrides, setUserOverrides] = useState({});
+    const [orgOverrides, setOrgOverrides] = useState({});
+    useEffect(() => {
+        setUserOverrides({});
+        setOrgOverrides({});
+    }, [iamUser?.id, iamUser?.name]);
+    useEffect(() => {
+        if (!token)
+            return;
+        let live = true;
+        fetchAccount(token)
+            .then((row) => {
+            if (live)
+                setHeld({ of: token, row });
+        })
+            // A record that will not load leaves the token's identity on screen,
+            // which is what this page had before it asked for the row at all.
+            .catch(() => { });
+        return () => {
+            live = false;
+        };
+    }, [token]);
+    const user = useMemo(() => {
+        if (!iamUser && !identity)
+            return null;
+        // The row where IAM answered with one; otherwise the identity the token
+        // already carries, resolved by the one resolver that knows every key IAM
+        // spells a name and a picture under.
+        const base = account
+            ? mapUser(account)
+            : {
+                id: iamUser?.id ?? identity?.name ?? '',
+                name: identity?.name ?? '',
+                email: identity?.email ?? '',
+                avatar: identity?.avatarUrl ?? undefined,
+            };
+        return { ...base, ...userOverrides };
+    }, [account, iamUser, identity, userOverrides]);
+    const organizations = useMemo(() => iamOrgs.map((o) => {
+        const base = mapOrg(o, roles[o.name]);
+        return { ...base, ...orgOverrides[base.id] };
+    }), [iamOrgs, roles, orgOverrides]);
+    const currentOrganization = useMemo(() => organizations.find((o) => o.id === currentOrgId) ?? organizations[0] ?? null, [organizations, currentOrgId]);
+    const setUser = (next) => setUserOverrides(next);
+    // The override lands FIRST so the picture the reader just picked is on screen
+    // while the request is in flight, and is rolled back where the write is
+    // refused — a preview that survives a failure is the page lying about what it
+    // has.
+    const updateUserProfile = async (userData) => {
+        const before = userOverrides;
+        setUserOverrides((prev) => ({ ...prev, ...userData }));
+        if (!iamUser || !token) {
+            setUserOverrides(before);
+            throw new Error('Sign in to change your profile.');
+        }
+        try {
+            await store(token, userData);
+        }
+        catch (e) {
+            setUserOverrides(before);
+            throw e;
+        }
+    };
+    const updateOrganization = (orgData) => {
+        if (!currentOrganization)
+            return;
+        setOrgOverrides((prev) => ({
+            ...prev,
+            [currentOrganization.id]: { ...prev[currentOrganization.id], ...orgData },
+        }));
+    };
+    return (_jsx(AccountContext.Provider, { value: {
+            user,
+            setUser,
+            organizations,
+            currentOrganization,
+            isLoading: authLoading || orgsLoading,
+            switchOrganization: switchOrg,
+            updateUserProfile,
+            updateOrganization,
+        }, children: children }));
+};
+export const useAccount = () => {
+    const context = useContext(AccountContext);
+    if (context === undefined) {
+        throw new Error('useAccount must be used within an AccountProvider');
+    }
+    return context;
+};

package/dist/lib/ai.d.ts

@@ -0,0 +1,46 @@
+import { type AiClient } from '@hanzo/ai';
+/**
+ * The tenant a signed-out turn is recorded against: the publishable key IAM
+ * mints, the same one this page beacons analytics with. It names an org and no
+ * person, so it is safe in a bundle by construction, and a free turn attributes
+ * to the org that published the page rather than to nobody.
+ *
+ * It is a KEY, not a token, and the distinction decides which route is called.
+ * `laneFor` in the SDK asks whether a bearer is present: with one it sends the
+ * metered `/v1/chat/completions`, without one it sends `/v1/chat/public` — the
+ * credential-less lane, which reads neither the model nor the org off the
+ * request, so a signed-out visitor cannot name a paid model or another tenant
+ * even by trying. Passing this as `token` would therefore select the metered
+ * route and be refused; it is passed as `publishableKey` (SDK >= 0.6.13).
+ */
+/** The gateway's own free pool: enso-free when logged out. */
+export declare const FREE = "enso-free";
+/** Enso routes a signed-in turn: enso-auto when logged in. */
+export declare const ENSO = "enso-auto";
+/**
+ * The model that will actually ANSWER, given what the gateway serves.
+ */
+export declare function served(models: {
+    id: string;
+}[], prefer: string): string;
+/**
+ * The gateway's address in the shape `createAiClient` takes it.
+ *
+ * The address itself is `api()` — one derivation, in `lib/hanzo/api.ts`, which
+ * every plain `fetch` in the app also reads. This working correctly here and
+ * nowhere else is what left eight other modules pointed at production while the
+ * dev proxy sat unused beside them.
+ */
+export declare const base: () => {
+    baseUrl?: string;
+};
+export interface Ai {
+    client: AiClient | null;
+    model: string;
+    /** Answering free, so the turn is data-shared and owes the notice. */
+    free: boolean;
+    /** Mounted client-side. The static export always prerenders the signed-out
+     *  page, so nothing interactive may render until this is true. */
+    ready: boolean;
+}
+export declare function useAi(): Ai;

package/dist/lib/ai.js

@@ -0,0 +1,140 @@
+'use client';
+// Who answers a chat turn on this site, and on whose account.
+//
+// Signed in — the visitor's own IAM token. Enso routes the turn and it meters to
+// their account like every other turn they run.
+//
+// Signed out — the FREE POOL, anonymously. There is no account to bill and none
+// is needed: a free turn spends no balance, and what it costs instead is stated
+// in the consent block the composer asks before the first send. A widget key, if
+// one is configured, rides along so the turn attributes to the org that minted
+// it; without one the turn is simply anonymous. Either way the client EXISTS,
+// because a chat you cannot send is not a chat.
+//
+// This used to answer `client: null` with no key, which is what put "Sign in to
+// send" under the composer — a wall in front of a lane that is free by design.
+//
+// So `client` is NEVER null now, and the type keeps saying `AiClient | null`
+// because a caller that still branches on it stays correct. Nothing in this
+// file returns null any more; if you are reading the type looking for the
+// signed-out case, it is not there.
+import { useEffect, useMemo, useState } from 'react';
+import { useHydrated } from './hydrated.js';
+import { api } from './api.js';
+import { useIam } from '@hanzo/iam/react';
+import { ORG, bearer, hasSession, org } from './session.js';
+import { createAiClient } from '@hanzo/ai';
+import { observed } from './served.js';
+import { where } from '../where.js';
+/**
+ * The tenant a signed-out turn is recorded against: the publishable key IAM
+ * mints, the same one this page beacons analytics with. It names an org and no
+ * person, so it is safe in a bundle by construction, and a free turn attributes
+ * to the org that published the page rather than to nobody.
+ *
+ * It is a KEY, not a token, and the distinction decides which route is called.
+ * `laneFor` in the SDK asks whether a bearer is present: with one it sends the
+ * metered `/v1/chat/completions`, without one it sends `/v1/chat/public` — the
+ * credential-less lane, which reads neither the model nor the org off the
+ * request, so a signed-out visitor cannot name a paid model or another tenant
+ * even by trying. Passing this as `token` would therefore select the metered
+ * route and be refused; it is passed as `publishableKey` (SDK >= 0.6.13).
+ */
+/** The gateway's own free pool: enso-free when logged out. */
+export const FREE = 'enso-free';
+/** Enso routes a signed-in turn: enso-auto when logged in. */
+export const ENSO = 'enso-auto';
+/**
+ * The model that will actually ANSWER, given what the gateway serves.
+ */
+export function served(models, prefer) {
+    const cleanPrefer = prefer === 'openrouter/auto' || prefer?.includes('openrouter') ? 'enso-auto' : prefer;
+    if (models.length === 0)
+        return cleanPrefer || 'enso-auto';
+    if (cleanPrefer && models.some((m) => m.id === cleanPrefer))
+        return cleanPrefer;
+    if (cleanPrefer === 'enso-free' || cleanPrefer === 'free' || cleanPrefer.includes('free')) {
+        const free = models.find((m) => m.id === 'enso-free' || m.id === 'zen-free' || (m.id.includes('free') && !m.id.includes('openrouter')));
+        if (free)
+            return free.id;
+        return 'enso-free';
+    }
+    // House routers: Enso or Zen
+    const houseAuto = models.find((m) => m.id === 'enso-auto' || m.id === 'zen-auto' || m.id === 'enso' || m.id === 'zen');
+    if (houseAuto)
+        return houseAuto.id;
+    const houseModel = models.find((m) => (m.id.startsWith('enso') || m.id.startsWith('zen')) && !m.id.includes('openrouter'));
+    if (houseModel)
+        return houseModel.id;
+    const clean = models.find((m) => !m.id.includes('openrouter'));
+    if (clean)
+        return clean.id;
+    return 'enso-auto';
+}
+/**
+ * The gateway's address in the shape `createAiClient` takes it.
+ *
+ * The address itself is `api()` — one derivation, in `lib/hanzo/api.ts`, which
+ * every plain `fetch` in the app also reads. This working correctly here and
+ * nowhere else is what left eight other modules pointed at production while the
+ * dev proxy sat unused beside them.
+ */
+export const base = () => ({ baseUrl: api() });
+export function useAi() {
+    const { sdk, isAuthenticated } = useIam();
+    // The organization every call is scoped to: the SDK's selection, sent only
+    // when the token says the reader belongs to it (`org()`), and followed through
+    // the one event a change fires — so the client is rebuilt and every hook on
+    // it reads the new organization's rooms, agents and threads.
+    const [scoped, setScoped] = useState(() => org());
+    useEffect(() => {
+        const on = () => setScoped(org());
+        window.addEventListener(ORG, on);
+        window.addEventListener('storage', on);
+        return () => {
+            window.removeEventListener(ORG, on);
+            window.removeEventListener('storage', on);
+        };
+    }, []);
+    const ready = useHydrated();
+    const signedIn = isAuthenticated || hasSession();
+    const account = Boolean(signedIn && sdk);
+    const client = useMemo(() => {
+        // TWO STATES, ONE ISSUER. Signed in is the visitor's own IAM session; signed
+        // out is the org's IAM-minted publishable key. There is no third credential
+        // and no locally-invented one — a token this app made up is a token the
+        // gateway has no reason to accept, and it reaches the metered lane rather
+        // than the free one, which is the opposite of what a signed-out reader needs.
+        if (account && sdk) {
+            return createAiClient({
+                fetch: observed((input, init) => fetch(input, init)),
+                headers: scoped ? { 'X-Org-Id': scoped } : {},
+                auth: {
+                    ...sdk,
+                    getValidAccessToken: async () => {
+                        const t = (await sdk.getValidAccessToken?.()) || bearer();
+                        if (!t)
+                            return null;
+                        try {
+                            const part = t.split('.')[1];
+                            if (part) {
+                                const payload = JSON.parse(atob(part.replace(/-/g, '+').replace(/_/g, '/')));
+                                const auds = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+                                if (auds.includes('hanzo-ai') && !auds.includes('hanzo-app')) {
+                                    // Production gateway does not yet whitelist aud="hanzo-ai"; fallback
+                                    // to anonymous key rather than failing with "jwt: audience not allowed".
+                                    return null;
+                                }
+                            }
+                        }
+                        catch { }
+                        return t;
+                    },
+                },
+                ...base(),
+            });
+        }
+        return createAiClient({ fetch: observed((input, init) => fetch(input, init)), publishableKey: where().key ?? '', ...base() });
+    }, [account, sdk, scoped]);
+    return { client, model: account ? ENSO : FREE, free: !account, ready };
+}

package/dist/lib/api.d.ts

@@ -0,0 +1,43 @@
+/**
+ * WHERE THE PLATFORM IS, DERIVED ONCE.
+ *
+ * `hooks/useAi.ts` worked this out correctly for the SDK client and nothing
+ * else could reach it: seven other modules wrote their own
+ * `process.env.NEXT_PUBLIC_HANZO_API_URL || 'https://api.hanzo.ai'` — reach.ts,
+ * team.ts, coding.ts, referrals.ts, useTiers.ts, Settings.tsx, Directory.tsx,
+ * Beluga.tsx — and every one of them got the local case wrong in the same way.
+ *
+ * THE LOCAL CASE IS THE WHOLE POINT. api.hanzo.ai admits an origin by allowlist
+ * and by an https, portless DNS proof; localhost satisfies neither, so a
+ * credentialed read to an ABSOLUTE address fails its preflight and the room
+ * draws as though the org owned nothing. `next.config.mjs` proxies `/v1` for
+ * exactly this, but a caller with an absolute default never reaches a rewrite.
+ * Same-origin on the dev server is what makes the proxy do its job.
+ *
+ * A FUNCTION, NOT A CONSTANT. Those eight were module-scope `const`s, evaluated
+ * while the static export prerenders — where there is no `window` — so the
+ * production address was frozen into the bundle before a browser could say
+ * where it was. Called at request time it answers for the page that is open.
+ */
+/** The gateway's origin, with no trailing slash: callers write `${api()}/v1/…`. */
+export declare function api(): string;
+/**
+ * Identity, likewise once. IAM issues the bearer every call above carries and
+ * is not reached through the API host, so it is a second address rather than a
+ * path on the first. It is NOT proxied and does not need to be — hanzo.id
+ * admits localhost on authorize, token and userinfo.
+ *
+ * `NEXT_PUBLIC_HANZO_IAM_URL` is the name — the one `.env.example` documents
+ * and `AccountContext` already reads. `team.ts` read `NEXT_PUBLIC_HANZO_ID_URL`
+ * instead, a name nothing sets, so pointing this app at another IAM would have
+ * moved the account panel and left the invitation links behind on hanzo.id.
+ * Two spellings of one setting are indistinguishable from a working one until
+ * the day it is changed.
+ */
+export declare function iam(): string;
+/**
+ * The IAM application hanzo.ai signs people in through, and the one an invited
+ * member joins through: the gateway admits it and IAM holds hanzo.ai's callbacks
+ * on it. It is platform-owned, so its full id is `admin/<CLIENT>`.
+ */
+export declare const CLIENT = "hanzo-app";

package/dist/lib/api.js

@@ -0,0 +1,62 @@
+/**
+ * WHERE THE PLATFORM IS, DERIVED ONCE.
+ *
+ * `hooks/useAi.ts` worked this out correctly for the SDK client and nothing
+ * else could reach it: seven other modules wrote their own
+ * `process.env.NEXT_PUBLIC_HANZO_API_URL || 'https://api.hanzo.ai'` — reach.ts,
+ * team.ts, coding.ts, referrals.ts, useTiers.ts, Settings.tsx, Directory.tsx,
+ * Beluga.tsx — and every one of them got the local case wrong in the same way.
+ *
+ * THE LOCAL CASE IS THE WHOLE POINT. api.hanzo.ai admits an origin by allowlist
+ * and by an https, portless DNS proof; localhost satisfies neither, so a
+ * credentialed read to an ABSOLUTE address fails its preflight and the room
+ * draws as though the org owned nothing. `next.config.mjs` proxies `/v1` for
+ * exactly this, but a caller with an absolute default never reaches a rewrite.
+ * Same-origin on the dev server is what makes the proxy do its job.
+ *
+ * A FUNCTION, NOT A CONSTANT. Those eight were module-scope `const`s, evaluated
+ * while the static export prerenders — where there is no `window` — so the
+ * production address was frozen into the bundle before a browser could say
+ * where it was. Called at request time it answers for the page that is open.
+ */
+import { guest, team } from './host.js';
+import { where } from '../where.js';
+/** The gateway's origin, with no trailing slash: callers write `${api()}/v1/…`. */
+export function api() {
+    const set = where().api;
+    if (set)
+        return set.replace(/\/+$/, '');
+    if (typeof window !== 'undefined') {
+        const host = window.location.hostname;
+        // The shipped site is served from an origin the gateway already admits, so
+        // there the absolute address stands and no proxy is involved. hanzo.team,
+        // hanzo.bot and the Sites plane's `<slug>.hanzo.app` aliases serve this same
+        // export and are admitted the same way; none of them has a /v1 of its own.
+        if (host === 'hanzo.ai' || host.endsWith('.hanzo.ai') || team(host) || host === 'hanzo.bot' || guest(host))
+            return 'https://api.hanzo.ai';
+        return window.location.origin;
+    }
+    return 'https://api.hanzo.ai';
+}
+/**
+ * Identity, likewise once. IAM issues the bearer every call above carries and
+ * is not reached through the API host, so it is a second address rather than a
+ * path on the first. It is NOT proxied and does not need to be — hanzo.id
+ * admits localhost on authorize, token and userinfo.
+ *
+ * `NEXT_PUBLIC_HANZO_IAM_URL` is the name — the one `.env.example` documents
+ * and `AccountContext` already reads. `team.ts` read `NEXT_PUBLIC_HANZO_ID_URL`
+ * instead, a name nothing sets, so pointing this app at another IAM would have
+ * moved the account panel and left the invitation links behind on hanzo.id.
+ * Two spellings of one setting are indistinguishable from a working one until
+ * the day it is changed.
+ */
+export function iam() {
+    return (where().iam || 'https://hanzo.id').replace(/\/+$/, '');
+}
+/**
+ * The IAM application hanzo.ai signs people in through, and the one an invited
+ * member joins through: the gateway admits it and IAM holds hanzo.ai's callbacks
+ * on it. It is platform-owned, so its full id is `admin/<CLIENT>`.
+ */
+export const CLIENT = 'hanzo-app';

package/dist/lib/bare.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A scroller that does not draw its scrollbar, as a gui prop: a row of chips or
+ * tabs scrolls sideways under a finger or a trackpad, and a bar under it would
+ * be chrome around nothing. gui applies `scrollbarWidth` on the web and its
+ * types do not list it, so it is spread rather than written.
+ */
+export declare const bare: {
+    readonly scrollbarWidth: 'none';
+};

package/dist/lib/bare.js

@@ -0,0 +1,7 @@
+/**
+ * A scroller that does not draw its scrollbar, as a gui prop: a row of chips or
+ * tabs scrolls sideways under a finger or a trackpad, and a bar under it would
+ * be chrome around nothing. gui applies `scrollbarWidth` on the web and its
+ * types do not list it, so it is spread rather than written.
+ */
+export const bare = { scrollbarWidth: 'none' };

package/dist/lib/coding.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Starting a coding run, and choosing WHERE it runs.
+ *
+ * The contract, read off the served document rather than assumed:
+ *  - start   POST /v1/agents/coding   → 202 {sessionId, repo, branch, routed, targetId}
+ *  - targets GET  /v1/agents/targets  → {targets: [...]}
+ *
+ * WHERE A RUN RUNS IS ONE FIELD. Omit `targetId` and the run goes to the cloud's
+ * own sandbox; name one and it is routed to a machine the org has claimed. The
+ * answer comes back rather than being assumed: `routed` says whether it reached
+ * a machine, and `targetId` says which. A caller that asked for a machine and
+ * reads `routed: false` was given a sandbox instead, and should say so rather
+ * than draw a screen that claims otherwise.
+ *
+ * That is the whole of the web-vs-desktop question. A browser has no machine to
+ * offer, so it sends no target and gets a sandbox. A surface running ON a
+ * claimed machine sends that machine's id. Neither needs a second endpoint, and
+ * nothing here sniffs the user agent to decide — the caller says what it has.
+ *
+ * A refusal states its reason: 401 is the credential and 403 is permission, and
+ * neither is "try again", so neither says it.
+ *
+ * AND IT REACHES THE READER, which for a while it did not. On localhost this
+ * caught every refusal it had just raised and answered with a fabricated
+ * accepted run — `sessionId: 'ses_' + Math.random()` — plus two invented
+ * targets, and `token()` minted `hz_local_dev_token` for a reader who was not
+ * signed in. So the one machine the acceptance gate is run on was the one where
+ * a platform that was down, unauthenticated or 500ing still opened a run, wrote
+ * `?run=` and mounted live Pause/Resume/Stop over nothing. Measured: the same
+ * prompt twice returned two different ids, which a served id cannot do.
+ *
+ * `Start.tsx` already renders `e.message` beside the composer. Point
+ * NEXT_PUBLIC_HANZO_API_URL at a platform that answers; do not synthesise one.
+ */
+/** What a coding run answers with. 202 — accepted, not finished. */
+export interface CodingRun {
+    /** The session every surface hangs this run's activity off. */
+    sessionId: string;
+    repo: string;
+    /** The branch the run works on; the server picks one when `base` is empty. */
+    branch: string;
+    /** Whether it reached a claimed machine. False means the sandbox took it. */
+    routed: boolean;
+    /** Which machine, when one took it. Empty for a sandbox run. */
+    targetId: string;
+}
+/** A machine the org has claimed, as `/v1/agents/targets` lists it. */
+export interface Target {
+    /** `tgt_` + 32 hex. What a run names to route here. */
+    id: string;
+    /** The name a person gave it ("workshop"). */
+    label: string;
+    /** laptop | cloud | … — a closed set the server owns. */
+    kind: string;
+    /** EFFECTIVE liveness: online | offline | draining. */
+    status: string;
+    /** Human summary — "8 vCPU / 32G", "1× GB10". */
+    capacity?: string;
+    host?: string;
+    /** How many of the org's sessions map here, and how many are running now. */
+    sessions?: number;
+    running?: number;
+}
+export interface StartCoding {
+    /** The task, in the words you would use with a colleague. */
+    prompt: string;
+    /** Model to route the coding agent through. */
+    model?: string;
+    /** `owner/name` in the caller's own org. */
+    repo?: string;
+    /** dev | claude | codex | python — which harness runs the prompt. */
+    tool?: string;
+    /** The branch to start from. Empty takes the repository's default. */
+    base?: string;
+    /**
+     * Route to a claimed machine. OMITTED IS THE SANDBOX, and that is the default
+     * on the web deliberately: a browser has no machine to offer.
+     */
+    targetId?: string;
+    /** Ask for a run with a screen — an image carrying an X server. */
+    desktop?: boolean;
+}
+export declare class CodingRefusal extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Starts one autonomous coding run and answers the session it opened.
+ *
+ * 202, not 200: the run is ACCEPTED here and finishes later, so what comes back
+ * is where to watch it — `sessionId` is the row the working view already
+ * renders — and never its output.
+ */
+export declare function startCoding(params: StartCoding): Promise<CodingRun>;
+export declare const startRun: typeof startCoding;
+/**
+ * The machines this org has claimed.
+ *
+ * An empty list is an ANSWER — this org has claimed none, so every run goes to
+ * a sandbox — and is not an error. A refusal still throws, because "we could
+ * not ask" and "there are none" must not render the same.
+ */
+export declare function listTargets(): Promise<Target[]>;
+/** A machine can take a run only while it is online. */
+export declare const dispatchable: (t: Target) => boolean;