@hanzo/rooms 0.1.0

package/dist/lib/coding.js

@@ -0,0 +1,87 @@
+import { bearer as held, scope } from './session.js';
+import { api } from './api.js';
+export class CodingRefusal extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function token() {
+    return held();
+}
+async function call(path, init) {
+    const tok = token();
+    const headers = new Headers(init?.headers);
+    if (!headers.has('Content-Type')) {
+        headers.set('Content-Type', 'application/json');
+    }
+    if (tok && !headers.has('Authorization')) {
+        for (const [k, v] of Object.entries(scope()))
+            if (!headers.has(k))
+                headers.set(k, v);
+    }
+    const res = await fetch(`${api()}${path}`, {
+        ...init,
+        // A run is a fact about right now, and a cached refusal survives the fix —
+        // it reads as the system still being broken long after it is not.
+        cache: 'no-store',
+        headers,
+    });
+    if (res.status === 401 && tok)
+        throw new CodingRefusal(401, 'Your session expired — sign in again');
+    if (res.status === 401 && !tok)
+        throw new CodingRefusal(401, 'Sign in or use Free AI to start a run');
+    if (res.status === 403)
+        throw new CodingRefusal(403, 'Your role cannot start runs in this organization');
+    if (!res.ok) {
+        let detail = '';
+        try {
+            const body = (await res.json());
+            detail = body?.error?.message || body?.msg || '';
+        }
+        catch {
+            // A refusal with no JSON body is still a refusal; the status carries it.
+        }
+        throw new CodingRefusal(res.status, detail || `Could not start the run (${res.status})`);
+    }
+    return res.json();
+}
+/**
+ * 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 async function startCoding(params) {
+    const body = await call('/v1/agents/coding', { method: 'POST', body: JSON.stringify(params) });
+    const r = (body ?? {});
+    if (!r.sessionId) {
+        // Accepted with no session is not a run anybody can watch. Say so rather
+        // than hand back a half-value the caller will render as success.
+        throw new CodingRefusal(502, 'The run was accepted but named no session');
+    }
+    return {
+        sessionId: r.sessionId,
+        repo: r.repo ?? '',
+        branch: r.branch ?? '',
+        routed: r.routed ?? false,
+        targetId: r.targetId ?? '',
+    };
+}
+export const startRun = 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 async function listTargets() {
+    const body = await call('/v1/agents/targets', { method: 'GET' });
+    const t = body?.targets;
+    return Array.isArray(t) ? t : [];
+}
+/** A machine can take a run only while it is online. */
+export const dispatchable = (t) => t.status === 'online';

package/dist/lib/destination.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Where a sign-in comes back to, decided in ONE place.
+ *
+ * Signing in is a round trip through another origin: the browser leaves for
+ * hanzo.id's /authorize and returns to /auth/callback, and nothing about that
+ * return says which page the person was reading when they started. So the page
+ * is written down on the way out and read back on the way in. One writer (the
+ * header's Sign in), one reader (the callback), read-once.
+ *
+ * sessionStorage, because the note must NOT outlive the trip it belongs to. The
+ * session itself is localStorage — signing in is meant to survive the tab — but
+ * a destination is not a session: it answers "which page did this one sign-in
+ * start from", and a page remembered from yesterday's tab is not an answer to
+ * that. It survives the redirect because a redirect keeps the tab, which is the
+ * whole lifetime it needs.
+ *
+ * Every access is guarded because storage THROWS rather than returning null in
+ * a browser that refuses it (Safari private mode, a locked-down profile). A
+ * person who cannot be sent back to their page must still be signed in, so a
+ * refusal degrades to the default and never to an exception.
+ */
+/** The default on the apex: the app, which is `/` for anyone signed in
+ *  (app/page.tsx). It answers the case where there is no page to go back to (a
+ *  typed /login, a /signup funnel, a stranger who cleared their storage
+ *  mid-flight). */
+export declare const DEFAULT_DESTINATION = "/";
+/** Where a sign-in with no page to go back to lands on `hostname`: the app on
+ *  the apex, and the rooms' Home everywhere else. */
+export declare function landing(hostname: string): string;
+/** Write down where we are, immediately before leaving for the issuer.
+ *
+ *  It reads `window.location` itself rather than taking a path, because a
+ *  caller that can name the page is a caller that can name the wrong one —
+ *  there is exactly one moment this is correct to call and it is this one. */
+export declare function rememberDestination(): void;
+/** Where a person signs in: this site's own page. */
+export declare const LOGIN = "/login";
+/** Where a new one signs up: this site's own page, which the host names. */
+export declare const signUp: () => string;
+export declare function recognize(): void;
+/**
+ * The page a signed-out reader is sent to when nothing says which: /login for
+ * a browser that has signed in here, /signup for a stranger, who has no
+ * password to type. Both ask hanzo.id first and link to each other.
+ */
+export declare function door(): string;
+/**
+ * Send this reader to sign in, and back to this page after.
+ *
+ * Every signed-out door into the app is this one call: `/` at a place in the
+ * app, /dev, a room. The page is written down, and the browser goes to `to`,
+ * which asks IAM for an existing session before it draws a form
+ * (components/auth/panel.tsx `Gate`). On a `guest` host the same address is asked for on hanzo.ai instead. With no `to`
+ * the page is `door()`'s; a control that says "Sign in" names LOGIN.
+ */
+export declare function enter(to?: string): void;
+/**
+ * The `?next=` a sign-in page was opened with, when it is an address on this
+ * site (`safe`): where the sign-in goes on to. Anything else is undefined.
+ */
+export declare function onward(search: string): string | undefined;
+/**
+ * On a `guest` host, send this sign-in to `address` on hanzo.ai and report that
+ * it left; anywhere else, do nothing and report false so the caller signs in
+ * here. A guest host cannot finish a sign-in (no client lists its callback), so
+ * starting one there only reaches IAM's refusal.
+ */
+export declare function handoff(address: string): boolean;
+/**
+ * Write down `address` as where this sign-in goes, in place of the page it
+ * started from: for a page that knows the reader's next stop rather than being
+ * it — /signup with a paid plan chosen goes on to /pay. Held to the same rule
+ * as everything read back: a path on this origin, or nothing is written.
+ */
+export declare function aim(address: string): void;
+/** The plan picker. */
+export declare const PICKER = "/onboarding";
+/**
+ * Where a completed sign-in goes first: the plan picker, which sends the reader
+ * on to `to` (components/onboarding/flow.tsx). A shared chat opens straight
+ * away. The picker is reached this way only, so it is shown once per sign-in.
+ */
+export declare function picker(to: string): string;
+/** Free was chosen: the sign-in this starts goes straight to the app. */
+export declare function chooseFree(): void;
+/** Read-once: whether Free was chosen before this sign-in. */
+export declare function choseFree(): boolean;
+/** Read-once: where this sign-in was headed, or this host's landing. */
+export declare function takeDestination(): string;
+/**
+ * A same-origin path, or `fallback`.
+ *
+ * `startsWith('/')` alone is not that test, and the gap is an open redirect:
+ * `//evil.example` and `/\evil.example` both begin with a slash and both
+ * navigate OFF this origin — the browser reads them as protocol-relative
+ * authorities, not paths. A single leading slash NOT followed by a second
+ * slash or a backslash is what makes a path a path.
+ *
+ * Exported so the rule can be exercised without a DOM: it is the one piece of
+ * this module that is a decision rather than a storage call.
+ */
+export declare function safe(stored: string | null | undefined, fallback?: string): string;

package/dist/lib/destination.js

@@ -0,0 +1,260 @@
+/**
+ * Where a sign-in comes back to, decided in ONE place.
+ *
+ * Signing in is a round trip through another origin: the browser leaves for
+ * hanzo.id's /authorize and returns to /auth/callback, and nothing about that
+ * return says which page the person was reading when they started. So the page
+ * is written down on the way out and read back on the way in. One writer (the
+ * header's Sign in), one reader (the callback), read-once.
+ *
+ * sessionStorage, because the note must NOT outlive the trip it belongs to. The
+ * session itself is localStorage — signing in is meant to survive the tab — but
+ * a destination is not a session: it answers "which page did this one sign-in
+ * start from", and a page remembered from yesterday's tab is not an answer to
+ * that. It survives the redirect because a redirect keeps the tab, which is the
+ * whole lifetime it needs.
+ *
+ * Every access is guarded because storage THROWS rather than returning null in
+ * a browser that refuses it (Safari private mode, a locked-down profile). A
+ * person who cannot be sent back to their page must still be signed in, so a
+ * refusal degrades to the default and never to an exception.
+ */
+import { apex, guest, SIGNIN } from "./host.js";
+import { SHARED } from "./share.js";
+import { where } from "../where.js";
+/** The default on the apex: the app, which is `/` for anyone signed in
+ *  (app/page.tsx). It answers the case where there is no page to go back to (a
+ *  typed /login, a /signup funnel, a stranger who cleared their storage
+ *  mid-flight). */
+export const DEFAULT_DESTINATION = "/";
+/** Where a sign-in with no page to go back to lands on `hostname`: the app on
+ *  the apex, and the rooms' Home everywhere else. */
+export function landing(hostname) {
+    return apex(hostname) ? DEFAULT_DESTINATION : where().home;
+}
+/** The storage key.
+ *
+ *  No brand in it — a key is a name, and the product it belongs to is not part
+ *  of what it names. But not the bare word `destination` either: sessionStorage
+ *  is scoped to the ORIGIN (per tab, but every page in it), and this origin also serves the chat SPA under
+ *  /chat/, so a one-word key is a name two unrelated programs could both reach
+ *  for. The qualifier says which flow owns it, which is the thing that makes it
+ *  unambiguous. */
+const KEY = "signin.destination";
+/**
+ * The addresses a sign-in must never return to, because each of them RESTARTS
+ * the thing that just finished.
+ *
+ * /login calls `login()` from an effect on mount, so returning there sends the
+ * browser straight back to /authorize — a loop that ends only when the person
+ * gives up. /signup does the same with a signup hint. /auth/callback would
+ * re-run `handleCallback()` against an authorization code that is single-use
+ * and a verifier that was consumed by the exchange it is repeating, so it fails
+ * and bounces to /login, which then loops as above.
+ *
+ * They are excluded here rather than at the point of writing because this is
+ * the boundary that has to hold: the value has crossed storage and a foreign
+ * origin between the two, and a rule enforced only on the way out is a rule
+ * enforced nowhere.
+ */
+const RESTARTS_THE_FLOW = new Set(["/login", "/signup", "/auth/callback"]);
+/** Write down where we are, immediately before leaving for the issuer.
+ *
+ *  It reads `window.location` itself rather than taking a path, because a
+ *  caller that can name the page is a caller that can name the wrong one —
+ *  there is exactly one moment this is correct to call and it is this one. */
+export function rememberDestination() {
+    try {
+        const { pathname, search, hash } = window.location;
+        window.sessionStorage.setItem(KEY, pathname + search + hash);
+    }
+    catch {
+        /* no store — the callback then uses the default; never throw on the way to
+           a login, or the control does nothing at all instead of signing anyone in */
+    }
+}
+/** Where a person signs in: this site's own page. */
+export const LOGIN = "/login";
+/** Where a new one signs up: this site's own page, which the host names. */
+export const signUp = () => where().signUp;
+/**
+ * Whether this browser has held a session on this site. It is marked where the
+ * site resolves a signed-in user (app/providers.tsx `Identity`) and outlives
+ * sign-out, which clears the SDK's keys and not this one.
+ */
+const KNOWN = "hz_known";
+export function recognize() {
+    try {
+        window.localStorage.setItem(KNOWN, "1");
+    }
+    catch {
+        /* no store — this browser reads as a stranger's and is offered sign-up */
+    }
+}
+/**
+ * The page a signed-out reader is sent to when nothing says which: /login for
+ * a browser that has signed in here, /signup for a stranger, who has no
+ * password to type. Both ask hanzo.id first and link to each other.
+ */
+export function door() {
+    try {
+        return window.localStorage.getItem(KNOWN) === "1" ? LOGIN : signUp();
+    }
+    catch {
+        return signUp();
+    }
+}
+/**
+ * Send this reader to sign in, and back to this page after.
+ *
+ * Every signed-out door into the app is this one call: `/` at a place in the
+ * app, /dev, a room. The page is written down, and the browser goes to `to`,
+ * which asks IAM for an existing session before it draws a form
+ * (components/auth/panel.tsx `Gate`). On a `guest` host the same address is asked for on hanzo.ai instead. With no `to`
+ * the page is `door()`'s; a control that says "Sign in" names LOGIN.
+ */
+export function enter(to = door()) {
+    const { pathname, search, hash } = window.location;
+    const here = `${pathname}${search}${hash}`;
+    if (handoff(here))
+        return;
+    rememberDestination();
+    // Written in the address too, so the place (a room, a prompt in `?q=`)
+    // survives what sessionStorage does not: a new tab, a pasted link.
+    const back = safe(here, "");
+    window.location.assign(back && back !== "/" ? `${to}?next=${encodeURIComponent(back)}` : to);
+}
+/**
+ * The `?next=` a sign-in page was opened with, when it is an address on this
+ * site (`safe`): where the sign-in goes on to. Anything else is undefined.
+ */
+export function onward(search) {
+    const next = new URLSearchParams(search).get("next");
+    return next && safe(next, "") === next ? next : undefined;
+}
+/**
+ * On a `guest` host, send this sign-in to `address` on hanzo.ai and report that
+ * it left; anywhere else, do nothing and report false so the caller signs in
+ * here. A guest host cannot finish a sign-in (no client lists its callback), so
+ * starting one there only reaches IAM's refusal.
+ */
+export function handoff(address) {
+    if (typeof window === "undefined" || !guest(window.location.hostname))
+        return false;
+    window.location.assign(SIGNIN + address);
+    return true;
+}
+/**
+ * Write down `address` as where this sign-in goes, in place of the page it
+ * started from: for a page that knows the reader's next stop rather than being
+ * it — /signup with a paid plan chosen goes on to /pay. Held to the same rule
+ * as everything read back: a path on this origin, or nothing is written.
+ */
+export function aim(address) {
+    if (safe(address, "") !== address)
+        return;
+    try {
+        window.sessionStorage.setItem(KEY, address);
+    }
+    catch {
+        /* no store: the callback uses the default */
+    }
+}
+/** The plan picker. */
+export const PICKER = "/onboarding";
+/**
+ * Where a completed sign-in goes first: the plan picker, which sends the reader
+ * on to `to` (components/onboarding/flow.tsx). A shared chat opens straight
+ * away. The picker is reached this way only, so it is shown once per sign-in.
+ */
+export function picker(to) {
+    const path = to.split(/[?#]/)[0].replace(/\/+$/, "") || "/";
+    return path === SHARED || path === PICKER ? to : `${PICKER}?next=${encodeURIComponent(to)}`;
+}
+/**
+ * FREE, CHOSEN BEFORE SIGNING IN, IS AN ANSWER. A paid plan chosen on a pricing
+ * card rides the sign-in as its destination (`/pay…?plan=`), and the picker opens
+ * its checkout. Free has no page to ride on, so the choice is written down here,
+ * in this tab, for the one sign-in it starts, and that sign-in skips the picker.
+ */
+const FREE = "signin.free";
+/** Free was chosen: the sign-in this starts goes straight to the app. */
+export function chooseFree() {
+    try {
+        window.sessionStorage.setItem(FREE, "1");
+    }
+    catch {
+        /* no store: the picker asks, and Free is one click there */
+    }
+}
+/** Read-once: whether Free was chosen before this sign-in. */
+export function choseFree() {
+    try {
+        const chosen = window.sessionStorage.getItem(FREE) === "1";
+        window.sessionStorage.removeItem(FREE);
+        return chosen;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read-once: where this sign-in was headed, or this host's landing. */
+export function takeDestination() {
+    return safe(take(), landing(window.location.hostname));
+}
+/** The storage half, alone, so the guard covers the read and nothing else — a
+ *  `try` wrapped around the decision too would turn a bug in the rule below
+ *  into a silent fallback instead of a failure anyone could see. */
+function take() {
+    try {
+        const stored = window.sessionStorage.getItem(KEY);
+        window.sessionStorage.removeItem(KEY);
+        return stored;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A same-origin path, or `fallback`.
+ *
+ * `startsWith('/')` alone is not that test, and the gap is an open redirect:
+ * `//evil.example` and `/\evil.example` both begin with a slash and both
+ * navigate OFF this origin — the browser reads them as protocol-relative
+ * authorities, not paths. A single leading slash NOT followed by a second
+ * slash or a backslash is what makes a path a path.
+ *
+ * Exported so the rule can be exercised without a DOM: it is the one piece of
+ * this module that is a decision rather than a storage call.
+ */
+export function safe(stored, fallback = DEFAULT_DESTINATION) {
+    if (!stored)
+        return fallback;
+    if (!stored.startsWith("/") ||
+        stored.startsWith("//") ||
+        stored.startsWith("/\\"))
+        return fallback;
+    // The browser's parser drops tabs and newlines and reads a backslash as a
+    // slash, so `/\t/evil.example` is `//evil.example` to it. An address is kept
+    // only when that same parser resolves it onto this origin.
+    let parsed;
+    try {
+        parsed = new URL(stored, HERE);
+    }
+    catch {
+        return fallback;
+    }
+    if (parsed.origin !== HERE)
+        return fallback;
+    // Compared without a trailing slash, because `/login` and `/login/` are the
+    // same page here and only one of them would be caught by a literal set. That
+    // is not hypothetical: this export answers both, and /auth/callback is itself
+    // inside the marketing layout, so it wears the header and its Sign in can be
+    // clicked — from the one address whose second visit is guaranteed to fail.
+    const path = parsed.pathname.replace(/\/+$/, "") || "/";
+    if (RESTARTS_THE_FLOW.has(path))
+        return fallback;
+    return stored;
+}
+/** An origin no address can name, to resolve a path against. */
+const HERE = "https://hanzo.invalid";

package/dist/lib/durable.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Hanzo Tasks — the durable execution engine — as the board reaches it.
+ *
+ * TWO SUBSYSTEMS, ONE SEAM, and the seam is the point. `/v1/todo` holds what
+ * should be done and who holds it; `/v1/tasks` runs work that survives a crash,
+ * event-sourced and replayable. They are not two spellings of one thing: a card
+ * is dragged between columns and a run is replayed, and neither verb makes sense
+ * on the other. So nothing here merges them — a card HANDS ITS WORK to the
+ * engine, and the engine answers about the run.
+ *
+ * THE JOIN IS THE NAME, and it is derived rather than stored. A card started
+ * from this board runs under `card-<board>-<number>`, so the workflow says which
+ * card it came from and the card can find its run — with no new column on either
+ * side, and nothing to fall out of step. The forge issue and the workflow are
+ * still two objects in two stores; the identifier is what makes them one fact.
+ */
+import type { AiClient } from '@hanzo/ai';
+/** The engine's default namespace. A deployment with more picks per org later. */
+export declare const NAMESPACE = "default";
+/** One durable run, as the engine reports it. */
+export interface Run {
+    workflowId: string;
+    runId?: string;
+    type?: string;
+    status?: string;
+    startTime?: string;
+    closeTime?: string;
+    historyLength?: number;
+    taskQueue?: string;
+}
+/** THE STATUSES the engine publishes, said the way a person would. */
+export declare function reads(status?: string): string;
+/** The workflow id a card's work runs under. Derived, never stored. */
+export declare const runName: (board: string, number: number) => string;
+/**
+ * THE QUEUE AND THE TYPE a card's work is handed to.
+ *
+ * `agents` because the worker that would execute it is an agent, and the engine
+ * matches work to workers by queue name — one queue per kind of worker is the
+ * whole of its routing. The engine ACCEPTS a start with nothing subscribed and
+ * leaves the run pending, which is the honest state: the work is recorded, and
+ * it moves when something is listening.
+ */
+export declare const AGENT_QUEUE = "agents";
+export declare const AGENT_WORKFLOW = "AgentWorkflow";
+/** Every run the engine holds, newest first as it answers. */
+export declare function runs(client: AiClient, signal?: AbortSignal): Promise<Run[]>;
+/** The run a card's work is doing, or null when it has never been started. */
+export declare function runOf(client: AiClient, board: string, number: number, signal?: AbortSignal): Promise<Run | null>;
+/**
+ * Hands a card's work to the engine.
+ *
+ * IT STARTS EVEN WITH NOTHING LISTENING — measured, not assumed: the engine
+ * accepts the start and leaves the run RUNNING with one history event until a
+ * worker polls the queue. That is the engine's own semantics and it is the
+ * useful one: the work is durably recorded the moment it is handed over, and it
+ * moves when something subscribes. A card therefore shows "running" for work
+ * nobody is doing yet, which is true and is exactly the state worth seeing.
+ *
+ * `requestId` is the card's own name, so pressing twice is one run.
+ */
+export declare function start(client: AiClient, board: string, number: number, work: {
+    title: string;
+    queue: string;
+    type: string;
+}, signal?: AbortSignal): Promise<Run>;

package/dist/lib/durable.js

@@ -0,0 +1,107 @@
+/**
+ * Hanzo Tasks — the durable execution engine — as the board reaches it.
+ *
+ * TWO SUBSYSTEMS, ONE SEAM, and the seam is the point. `/v1/todo` holds what
+ * should be done and who holds it; `/v1/tasks` runs work that survives a crash,
+ * event-sourced and replayable. They are not two spellings of one thing: a card
+ * is dragged between columns and a run is replayed, and neither verb makes sense
+ * on the other. So nothing here merges them — a card HANDS ITS WORK to the
+ * engine, and the engine answers about the run.
+ *
+ * THE JOIN IS THE NAME, and it is derived rather than stored. A card started
+ * from this board runs under `card-<board>-<number>`, so the workflow says which
+ * card it came from and the card can find its run — with no new column on either
+ * side, and nothing to fall out of step. The forge issue and the workflow are
+ * still two objects in two stores; the identifier is what makes them one fact.
+ */
+/** The engine's default namespace. A deployment with more picks per org later. */
+export const NAMESPACE = 'default';
+/** THE STATUSES the engine publishes, said the way a person would. */
+export function reads(status) {
+    if (!status)
+        return 'unknown';
+    return ({
+        WORKFLOW_EXECUTION_STATUS_RUNNING: 'running',
+        WORKFLOW_EXECUTION_STATUS_COMPLETED: 'done',
+        WORKFLOW_EXECUTION_STATUS_FAILED: 'failed',
+        WORKFLOW_EXECUTION_STATUS_CANCELED: 'canceled',
+        WORKFLOW_EXECUTION_STATUS_TERMINATED: 'stopped',
+        WORKFLOW_EXECUTION_STATUS_TIMED_OUT: 'timed out',
+    }[status] ?? status.replace(/^WORKFLOW_EXECUTION_STATUS_/, '').toLowerCase());
+}
+/** The workflow id a card's work runs under. Derived, never stored. */
+export const runName = (board, number) => `card-${board}-${number}`;
+/**
+ * THE QUEUE AND THE TYPE a card's work is handed to.
+ *
+ * `agents` because the worker that would execute it is an agent, and the engine
+ * matches work to workers by queue name — one queue per kind of worker is the
+ * whole of its routing. The engine ACCEPTS a start with nothing subscribed and
+ * leaves the run pending, which is the honest state: the work is recorded, and
+ * it moves when something is listening.
+ */
+export const AGENT_QUEUE = 'agents';
+export const AGENT_WORKFLOW = 'AgentWorkflow';
+/** Every run the engine holds, newest first as it answers. */
+export async function runs(client, signal) {
+    const out = await client.http.json({
+        path: `/v1/tasks/namespaces/${NAMESPACE}/workflows`,
+        signal,
+    });
+    const rows = Array.isArray(out?.executions) ? out.executions : [];
+    return rows.map(shape);
+}
+/** The run a card's work is doing, or null when it has never been started. */
+export async function runOf(client, board, number, signal) {
+    const name = runName(board, number);
+    const out = await client.http.json({
+        path: `/v1/tasks/namespaces/${NAMESPACE}/workflows/${encodeURIComponent(name)}/executions`,
+        signal,
+    });
+    const rows = Array.isArray(out?.executions) ? out.executions : [];
+    // The chain is every attempt under that name; the newest is the one running.
+    return rows.length ? shape(rows[rows.length - 1]) : null;
+}
+/**
+ * Hands a card's work to the engine.
+ *
+ * IT STARTS EVEN WITH NOTHING LISTENING — measured, not assumed: the engine
+ * accepts the start and leaves the run RUNNING with one history event until a
+ * worker polls the queue. That is the engine's own semantics and it is the
+ * useful one: the work is durably recorded the moment it is handed over, and it
+ * moves when something subscribes. A card therefore shows "running" for work
+ * nobody is doing yet, which is true and is exactly the state worth seeing.
+ *
+ * `requestId` is the card's own name, so pressing twice is one run.
+ */
+export async function start(client, board, number, work, signal) {
+    const out = await client.http.json({
+        method: 'POST',
+        path: `/v1/tasks/namespaces/${NAMESPACE}/workflows`,
+        body: {
+            workflowId: runName(board, number),
+            workflowType: { name: work.type },
+            taskQueue: { name: work.queue },
+            input: [{ card: `${board}#${number}`, title: work.title }],
+            // The card is the request, so a double press is one run rather than two.
+            requestId: runName(board, number),
+        },
+        signal,
+    });
+    return shape(out);
+}
+/** The engine's row, flattened to what a card needs to draw. */
+function shape(row) {
+    const r = (row ?? {});
+    const ex = (r.execution ?? {});
+    return {
+        workflowId: String(ex.workflowId ?? r.workflowId ?? ''),
+        runId: ex.runId ?? r.runId,
+        type: r.type?.name ?? r.workflowType?.name,
+        status: r.status,
+        startTime: r.startTime,
+        closeTime: r.closeTime,
+        historyLength: r.historyLength,
+        taskQueue: typeof r.taskQueue === 'string' ? r.taskQueue : r.taskQueue?.name,
+    };
+}

package/dist/lib/first.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Activation: the first time this browser does what the product is for,
+ * counted once as `first_action` with that thing as its `action` — the one
+ * activation name every product shares (@hanzo/events), which GA4 hears as
+ * `first_message` for the only action this site counts, `chat_message`.
+ *
+ * The mark lives in localStorage, so it is once per browser: a person on a
+ * second device is counted there too, and a browser that stores nothing is
+ * never counted, which undercounts rather than inflating.
+ */
+export declare function first(action: string): void;

package/dist/lib/first.js

@@ -0,0 +1,23 @@
+import { track } from './tags.js';
+/**
+ * Activation: the first time this browser does what the product is for,
+ * counted once as `first_action` with that thing as its `action` — the one
+ * activation name every product shares (@hanzo/events), which GA4 hears as
+ * `first_message` for the only action this site counts, `chat_message`.
+ *
+ * The mark lives in localStorage, so it is once per browser: a person on a
+ * second device is counted there too, and a browser that stores nothing is
+ * never counted, which undercounts rather than inflating.
+ */
+export function first(action) {
+    const key = `hz_first.${action}`;
+    try {
+        if (window.localStorage.getItem(key))
+            return;
+        window.localStorage.setItem(key, '1');
+    }
+    catch {
+        return;
+    }
+    track('first_action', { action });
+}