@skrr-ai/cli 0.1.92 → 0.1.93

package/dist/lib/open-target.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenTargetError = exports.OPEN_REF_KINDS = void 0;
+exports.resolveOpenTarget = resolveOpenTarget;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const agent_ref_1 = require("./agent-ref");
+const web_url_1 = require("./web-url");
+/**
+ * What `skrr open <target>` accepts, resolved to one absolute web URL.
+ *
+ *   - a skrr web URL (`https://skrr.ai/a/agent_abc`) — opened as given, after
+ *     checking it is first-party;
+ *   - a site path (`/spaces/sp_1/tasks`) — on the configured deployment;
+ *   - a typed reference (`space:sp_1`, `listing:agent_abc`) — through the
+ *     CLI's one route table, `web-url.ts`, so no route is spelled here;
+ *   - an agent reference `resolveAgentRef` understands that is not already a
+ *     web URL (`skrr://agent/<id>`, `agent_abc`) — opened at its public
+ *     listing, keeping any attribution it carried.
+ *
+ * A foreign host is refused rather than opened. `skrr open` is also run by
+ * coding agents, and a command that opens whatever URL it is handed would turn
+ * "open this skrr link" into "open any link" for anything that can put text in
+ * front of one. WHETHER a URL is first-party is data-provider's
+ * `inspectSkrrLink` (the shared link parser) over the CLI's host list, never a
+ * host comparison of our own.
+ */
+/** Kind words a typed reference may use, mapped to the route table's refs. */
+const REF_KINDS = {
+    space: (id) => ({ kind: 'space', spaceId: id }),
+    task: (id) => ({ kind: 'task', taskId: id }),
+    goal: (id) => ({ kind: 'goal', goalId: id }),
+    commitment: (id) => ({ kind: 'commitment', commitmentId: id }),
+    northstar: (id) => ({ kind: 'northstar', northstarId: id }),
+    // The owner's workspace for an agent you hold. To open a published agent's
+    // public page — the address you hand to someone else — use `listing:`.
+    agent: (id) => ({ kind: 'agent', agentId: id }),
+    listing: (id) => ({ kind: 'storeListing', agentId: id }),
+    conversation: (id) => ({ kind: 'conversation', conversationId: id }),
+    group: (id) => ({ kind: 'groupChat', groupChatId: id }),
+    machine: (id) => ({ kind: 'machine', machineId: id }),
+    harness: (id) => ({ kind: 'harness', harnessId: id }),
+    template: (id) => ({ kind: 'spaceTemplate', templateId: id }),
+};
+exports.OPEN_REF_KINDS = Object.freeze(Object.keys(REF_KINDS));
+class OpenTargetError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'OpenTargetError';
+    }
+}
+exports.OpenTargetError = OpenTargetError;
+/** An agent reference that is not a web URL: an app-scheme link, `@handle/…`, or an `agent_` id. */
+function looksLikeAgentRef(value) {
+    return (/^[a-z][a-z0-9+.-]*:\/\//i.test(value) ||
+        value.startsWith('@') ||
+        /^agent_[A-Za-z0-9_-]+$/.test(value));
+}
+async function resolveOpenTarget(input, baseURL) {
+    const value = String(input ?? '').trim();
+    if (!value) {
+        throw new OpenTargetError(`Name what to open: a ${data_provider_1.BRAND.displayName} URL, a /path, or <kind>:<id>.`, 'OPEN_TARGET_EMPTY');
+    }
+    if (/^https?:\/\//i.test(value)) {
+        let parsed;
+        try {
+            parsed = new URL(value);
+        }
+        catch {
+            throw new OpenTargetError(`"${value}" is not a valid URL.`, 'OPEN_TARGET_UNKNOWN');
+        }
+        if (!(0, data_provider_1.inspectSkrrLink)(value, { firstPartyHosts: (0, agent_ref_1.cliFirstPartyHosts)(baseURL) })) {
+            throw new OpenTargetError(`${parsed.host} is not a ${data_provider_1.BRAND.displayName} web address, so it was not opened.`, 'OPEN_TARGET_FOREIGN');
+        }
+        return { url: parsed.toString(), form: 'url' };
+    }
+    if (value.startsWith('/')) {
+        // `//host/...` is a protocol-relative URL to ANOTHER host, not a path.
+        if (value.startsWith('//')) {
+            throw new OpenTargetError(`"${value}" is not a site path.`, 'OPEN_TARGET_UNKNOWN');
+        }
+        return { url: new URL(value, `${(0, web_url_1.webOrigin)(baseURL)}/`).toString(), form: 'path' };
+    }
+    const ref = /^([a-z]+):(.+)$/i.exec(value);
+    const build = ref ? REF_KINDS[ref[1].toLowerCase()] : undefined;
+    if (ref && build) {
+        const url = (0, web_url_1.webUrl)(baseURL, build(ref[2].trim()));
+        if (url)
+            return { url, form: 'ref' };
+    }
+    if (looksLikeAgentRef(value)) {
+        try {
+            const agent = await (0, agent_ref_1.resolveAgentRef)(value, { baseURL });
+            return { url: (0, agent_ref_1.attributedListingUrl)(baseURL, agent), form: 'agent' };
+        }
+        catch (err) {
+            if (!(err instanceof agent_ref_1.AgentRefError))
+                throw err;
+            // A foreign scheme or an unresolvable vanity link says so in its own words.
+            if (err.code !== 'AGENT_REF_UNSUPPORTED') {
+                throw new OpenTargetError(err.message, err.code === 'AGENT_REF_FOREIGN' ? 'OPEN_TARGET_FOREIGN' : 'OPEN_TARGET_UNKNOWN');
+            }
+        }
+    }
+    throw new OpenTargetError(`"${value}" is not something \`skrr open\` understands. Pass a ${data_provider_1.BRAND.displayName} URL, a site path ` +
+        `(/spaces/<id>), or <kind>:<id> where kind is one of: ${exports.OPEN_REF_KINDS.join(', ')}.`, 'OPEN_TARGET_UNKNOWN');
+}

package/dist/lib/rate-limit-retry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Bounded retry on HTTP 429 (agent-surface audit E6).
+ *
+ * The API limits writes per USER (task create is 200/min), so N agents under one
+ * account share one bucket, and the server already says when to come back
+ * (`Retry-After`, `standardHeaders: true`). Until now both transports treated a
+ * 429 as terminal, so a burst of keyed creates failed on the first refusal.
+ *
+ * Retried only when replay is provably safe: a GET, or a write that carries an
+ * `X-Idempotency-Key` (every `request.ts` / adapter write does). A 429 means the
+ * request was refused before it ran, so the key is belt and braces.
+ *
+ * Bounded twice: at most `maxRetries` extra attempts and a per-wait ceiling, so
+ * a stuck limiter costs a script seconds, not minutes. `SKRR_RATE_LIMIT_RETRIES=0`
+ * turns it off.
+ */
+export declare const DEFAULT_MAX_RATE_LIMIT_RETRIES = 2;
+export declare const MAX_RATE_LIMIT_WAIT_MS = 10000;
+/** `Retry-After` is delta-seconds or an HTTP-date; both become milliseconds. */
+export declare function parseRetryAfterMs(value: string | null | undefined, now?: number): number | undefined;
+/**
+ * Wait before retry number `attempt` (0-based): the server's `Retry-After` when
+ * given, else exponential from 500 ms, plus 0-25% jitter so a fleet released
+ * together does not come back together. Clamped to the ceiling.
+ */
+export declare function rateLimitWaitMs(attempt: number, retryAfterMs: number | undefined, random?: () => number): number;
+export declare function maxRateLimitRetries(env?: NodeJS.ProcessEnv): number;
+export declare function isRateLimitRetrySafe(method: string, headers: Record<string, string> | undefined): boolean;
+export interface RateLimitRetryOptions {
+    method: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+    maxRetries?: number;
+}
+/**
+ * Run `attemptFetch` and, on a 429 for a replay-safe request, wait and run it
+ * again. Returns the last response, with `retryAfterMs` of the final 429 (so the
+ * caller can surface it) when retries ran out.
+ */
+export declare function fetchWithRateLimitRetry(attemptFetch: () => Promise<Response>, options: RateLimitRetryOptions): Promise<{
+    response: Response;
+    retryAfterMs?: number;
+}>;

package/dist/lib/rate-limit-retry.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Bounded retry on HTTP 429 (agent-surface audit E6).
+ *
+ * The API limits writes per USER (task create is 200/min), so N agents under one
+ * account share one bucket, and the server already says when to come back
+ * (`Retry-After`, `standardHeaders: true`). Until now both transports treated a
+ * 429 as terminal, so a burst of keyed creates failed on the first refusal.
+ *
+ * Retried only when replay is provably safe: a GET, or a write that carries an
+ * `X-Idempotency-Key` (every `request.ts` / adapter write does). A 429 means the
+ * request was refused before it ran, so the key is belt and braces.
+ *
+ * Bounded twice: at most `maxRetries` extra attempts and a per-wait ceiling, so
+ * a stuck limiter costs a script seconds, not minutes. `SKRR_RATE_LIMIT_RETRIES=0`
+ * turns it off.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RATE_LIMIT_WAIT_MS = exports.DEFAULT_MAX_RATE_LIMIT_RETRIES = void 0;
+exports.parseRetryAfterMs = parseRetryAfterMs;
+exports.rateLimitWaitMs = rateLimitWaitMs;
+exports.maxRateLimitRetries = maxRateLimitRetries;
+exports.isRateLimitRetrySafe = isRateLimitRetrySafe;
+exports.fetchWithRateLimitRetry = fetchWithRateLimitRetry;
+exports.DEFAULT_MAX_RATE_LIMIT_RETRIES = 2;
+exports.MAX_RATE_LIMIT_WAIT_MS = 10_000;
+const MIN_WAIT_MS = 250;
+/** `Retry-After` is delta-seconds or an HTTP-date; both become milliseconds. */
+function parseRetryAfterMs(value, now = Date.now()) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed))
+        return Math.round(Number(trimmed) * 1000);
+    const at = Date.parse(trimmed);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, at - now);
+}
+/**
+ * Wait before retry number `attempt` (0-based): the server's `Retry-After` when
+ * given, else exponential from 500 ms, plus 0-25% jitter so a fleet released
+ * together does not come back together. Clamped to the ceiling.
+ */
+function rateLimitWaitMs(attempt, retryAfterMs, random = Math.random) {
+    const base = retryAfterMs ?? 500 * 2 ** attempt;
+    const jittered = base * (1 + 0.25 * random());
+    return Math.min(exports.MAX_RATE_LIMIT_WAIT_MS, Math.max(MIN_WAIT_MS, Math.round(jittered)));
+}
+function maxRateLimitRetries(env = process.env) {
+    const raw = env.SKRR_RATE_LIMIT_RETRIES;
+    if (raw === undefined || raw === '')
+        return exports.DEFAULT_MAX_RATE_LIMIT_RETRIES;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? Math.min(n, 5) : exports.DEFAULT_MAX_RATE_LIMIT_RETRIES;
+}
+function hasKey(headers) {
+    return Object.keys(headers ?? {}).some((k) => k.toLowerCase() === 'x-idempotency-key');
+}
+function isRateLimitRetrySafe(method, headers) {
+    return method.toUpperCase() === 'GET' || hasKey(headers);
+}
+function retryAfterOf(response) {
+    return response.status === 429
+        ? parseRetryAfterMs(response.headers.get('retry-after'))
+        : undefined;
+}
+/**
+ * Run `attemptFetch` and, on a 429 for a replay-safe request, wait and run it
+ * again. Returns the last response, with `retryAfterMs` of the final 429 (so the
+ * caller can surface it) when retries ran out.
+ */
+async function fetchWithRateLimitRetry(attemptFetch, options) {
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const max = options.maxRetries ?? maxRateLimitRetries();
+    let response = await attemptFetch();
+    let retryAfterMs = retryAfterOf(response);
+    if (!isRateLimitRetrySafe(options.method, options.headers))
+        return { response, retryAfterMs };
+    for (let attempt = 0; attempt < max && response.status === 429; attempt++) {
+        if (options.signal?.aborted)
+            break;
+        await sleep(rateLimitWaitMs(attempt, retryAfterMs, options.random));
+        response = await attemptFetch();
+        retryAfterMs = retryAfterOf(response);
+    }
+    return { response, retryAfterMs };
+}

package/dist/lib/store-listing.d.ts

@@ -0,0 +1,45 @@
+import { type ReleaseCapabilityManifestView, type StoreAgentInstallFunnelSummary, type StoreAgentReleaseAdoptionSummary, type StoreAgentReleaseOutcomes } from '@skrr-ai/data-provider';
+/**
+ * Terminal wording for a Store listing (`skrr store show`) and its publisher
+ * readouts (`skrr store stats`). Pure functions, so the commands only fetch
+ * and print and every sentence here is pinned by a unit test.
+ *
+ * Two rules carried over from the web surfaces, because a terminal is not a
+ * licence to say less:
+ *
+ *   - The capability manifest is a DISCLOSURE. Nothing narrows a run to it
+ *     (see `client/src/components/Store/capabilityDisclosure.ts`), so no line
+ *     here says an agent is limited, restricted or "can only" do something.
+ *     `Unrestricted` is the one state word, and it names the BAD case.
+ *   - A k-anonymous readout below its floor has NO figures. It is printed as
+ *     "withheld" with the floor it missed, never as 0 — a zero is a claim that
+ *     nobody did the thing, and the server did not make that claim.
+ */
+/** A listing's price in token credits (1,000,000 = $1), as the Store states it. */
+export declare function formatListingPrice(price: number | null | undefined): string;
+/** `4.6 ★ (12 ratings)`, or `No ratings yet` — never `0.0` for an unrated listing. */
+export declare function formatListingRating(rating: number | null | undefined, count: number | null | undefined): string;
+/**
+ * What the listed release is configured to use, as `label: value` pairs.
+ *
+ * `unavailable` stays its own answer — "we could not tell" — and is never
+ * rendered as an empty manifest, which would read as "uses nothing".
+ */
+export declare function capabilityDisclosureRows(view: ReleaseCapabilityManifestView | null | undefined): Array<[string, string]>;
+/** One sentence that keeps the disclosure from being read as a sandbox. */
+export declare const CAPABILITY_DISCLOSURE_FOOTNOTE = "Recorded by the platform when the release was created. A disclosure of its configuration \u2014 not a limit on what a run may do.";
+/** Align `label: value` pairs under a section, indented two spaces. */
+export declare function labelledLines(rows: ReadonlyArray<readonly [string, string]>): string[];
+/** `withheld: fewer than 5 buyers in this window` — the floor, never a zero. */
+export declare function withheldLine(minimumCohort: number, unit: string): string;
+export declare function formatRate(value: number | null | undefined): string;
+export declare function funnelWindowLine(summary: StoreAgentInstallFunnelSummary): string;
+export declare function adoptionWindowLine(summary: StoreAgentReleaseAdoptionSummary): string;
+export declare function outcomesWindowLine(outcomes: StoreAgentReleaseOutcomes): string;
+/**
+ * Small cells that were withheld from an otherwise reported readout. Said
+ * once, with the floor, so a short table is not mistaken for a complete one.
+ */
+export declare function suppressedCellsLine(cells: Record<string, number>, minimumCohort: number, unit: string): string | null;
+/** An exclusion count; `null` is "some, from too few buyers to say how many". */
+export declare function exclusionValue(value: number | null | undefined): string;

package/dist/lib/store-listing.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPABILITY_DISCLOSURE_FOOTNOTE = void 0;
+exports.formatListingPrice = formatListingPrice;
+exports.formatListingRating = formatListingRating;
+exports.capabilityDisclosureRows = capabilityDisclosureRows;
+exports.labelledLines = labelledLines;
+exports.withheldLine = withheldLine;
+exports.formatRate = formatRate;
+exports.funnelWindowLine = funnelWindowLine;
+exports.adoptionWindowLine = adoptionWindowLine;
+exports.outcomesWindowLine = outcomesWindowLine;
+exports.suppressedCellsLine = suppressedCellsLine;
+exports.exclusionValue = exclusionValue;
+const data_provider_1 = require("@skrr-ai/data-provider");
+/**
+ * Terminal wording for a Store listing (`skrr store show`) and its publisher
+ * readouts (`skrr store stats`). Pure functions, so the commands only fetch
+ * and print and every sentence here is pinned by a unit test.
+ *
+ * Two rules carried over from the web surfaces, because a terminal is not a
+ * licence to say less:
+ *
+ *   - The capability manifest is a DISCLOSURE. Nothing narrows a run to it
+ *     (see `client/src/components/Store/capabilityDisclosure.ts`), so no line
+ *     here says an agent is limited, restricted or "can only" do something.
+ *     `Unrestricted` is the one state word, and it names the BAD case.
+ *   - A k-anonymous readout below its floor has NO figures. It is printed as
+ *     "withheld" with the floor it missed, never as 0 — a zero is a claim that
+ *     nobody did the thing, and the server did not make that claim.
+ */
+/** A listing's price in token credits (1,000,000 = $1), as the Store states it. */
+function formatListingPrice(price) {
+    return (0, data_provider_1.formatStoreAcquisitionPrice)(price);
+}
+/** `4.6 ★ (12 ratings)`, or `No ratings yet` — never `0.0` for an unrated listing. */
+function formatListingRating(rating, count) {
+    const ratings = Number(count) || 0;
+    if (ratings <= 0)
+        return 'No ratings yet';
+    return `${(Number(rating) || 0).toFixed(1)} / 5 (${ratings} rating${ratings === 1 ? '' : 's'})`;
+}
+const UNAVAILABLE_REASON = {
+    not_recorded: 'no capability record was stored for this release',
+    digest_mismatch: 'the stored record describes a different configuration, so it is not shown',
+    no_release: 'the listing has no approved public release',
+};
+const SHARED_DATA = {
+    none: 'None — you start from a blank agent',
+    bootstrap: "The publisher's bootstrap files are offered with the agent",
+    memory: "The publisher's shared memories are offered with the agent",
+    full: "The publisher's bootstrap files and shared memories are offered with the agent",
+};
+function listOrNone(items, none = 'None named') {
+    return items.length > 0 ? items.join(', ') : none;
+}
+/** A permission dimension: a wildcard entry means it is not narrowed at all. */
+function permissionValue(items) {
+    if (items.some(data_provider_1.isUnrestrictedCapabilityEntry)) {
+        const named = items.filter((entry) => !(0, data_provider_1.isUnrestrictedCapabilityEntry)(entry));
+        return named.length > 0 ? `Unrestricted (also names: ${named.join(', ')})` : 'Unrestricted';
+    }
+    return listOrNone(items);
+}
+/**
+ * What the listed release is configured to use, as `label: value` pairs.
+ *
+ * `unavailable` stays its own answer — "we could not tell" — and is never
+ * rendered as an empty manifest, which would read as "uses nothing".
+ */
+function capabilityDisclosureRows(view) {
+    if (!view) {
+        return [['Disclosure', 'Not available — this server did not send one']];
+    }
+    if (view.status !== 'available') {
+        return [['Disclosure', `Not available — ${UNAVAILABLE_REASON[view.reason] ?? view.reason}`]];
+    }
+    const m = view.manifest;
+    const rows = [];
+    rows.push([
+        'Platform capabilities',
+        m.platformCapabilities.mode === 'unrestricted'
+            ? 'Unrestricted — chosen per request'
+            : m.platformCapabilities.mode === 'not_loaded'
+                ? 'Not loaded by its tool policy'
+                : listOrNone(m.platformCapabilities.capabilities),
+    ]);
+    rows.push([
+        'Built-in tools',
+        m.builtinTools.mode === 'platform_default'
+            ? 'Platform default set (includes a shell and web access)'
+            : m.builtinTools.mode === 'none'
+                ? 'None'
+                : listOrNone(m.builtinTools.tools),
+    ]);
+    rows.push(['Tools', permissionValue(m.permissionManifest.tools)]);
+    rows.push(['Connectors', permissionValue(m.permissionManifest.connectors)]);
+    rows.push(['Network', permissionValue(m.permissionManifest.networkDomains)]);
+    rows.push(['Data', permissionValue(m.permissionManifest.dataScopes)]);
+    rows.push(['Secrets', permissionValue(m.permissionManifest.secretNames)]);
+    const delegation = m.delegation;
+    let delegationValue;
+    switch (delegation.mode) {
+        case 'none':
+            delegationValue = 'None';
+            break;
+        case 'all':
+            delegationValue = 'Unrestricted — any agent in its network';
+            break;
+        case 'not_loaded':
+            delegationValue = 'Not loaded by its tool policy';
+            break;
+        default:
+            delegationValue = listOrNone(delegation.agentIds);
+    }
+    if (delegation.includesPublicAgents && delegation.mode !== 'none') {
+        delegationValue += ' (includes public agents)';
+    }
+    rows.push(['Delegates to', delegationValue]);
+    const model = [m.model.provider, m.model.model].filter(Boolean).join(' / ');
+    rows.push(['Model', model || 'Not stated']);
+    const autonomy = [];
+    if (m.proactive.enabled) {
+        const watches = [...m.proactive.sources, ...m.proactive.watchers];
+        autonomy.push(watches.length > 0
+            ? `Acts on its own schedule after install (watches: ${watches.join(', ')})`
+            : 'Acts on its own schedule after install');
+    }
+    if (m.firstContact)
+        autonomy.push('Starts a conversation shortly after install');
+    rows.push(['Acts on its own', autonomy.length > 0 ? autonomy.join('; ') : 'No']);
+    rows.push(['Shared data', SHARED_DATA[m.sharedData] ?? m.sharedData]);
+    return rows;
+}
+/** One sentence that keeps the disclosure from being read as a sandbox. */
+exports.CAPABILITY_DISCLOSURE_FOOTNOTE = 'Recorded by the platform when the release was created. A disclosure of its configuration — not a limit on what a run may do.';
+/** Align `label: value` pairs under a section, indented two spaces. */
+function labelledLines(rows) {
+    const width = Math.max(0, ...rows.map(([label]) => label.length)) + 1;
+    return rows.map(([label, value]) => `  ${`${label}:`.padEnd(width + 1)}${value}`);
+}
+// ─── Publisher readouts (`skrr store stats`) ────────────────────────────────
+/** `withheld: fewer than 5 buyers in this window` — the floor, never a zero. */
+function withheldLine(minimumCohort, unit) {
+    return `withheld: fewer than ${minimumCohort} ${unit} in this window, so no figures are shown`;
+}
+function formatRate(value) {
+    if (value === null || value === undefined || !Number.isFinite(Number(value)))
+        return '-';
+    return `${Math.round(Number(value) * 100)}%`;
+}
+function day(value) {
+    return value ? String(value).slice(0, 10) : '?';
+}
+function funnelWindowLine(summary) {
+    return `${summary.days}-day window, ${day(summary.since)} to ${day(summary.until)} (UTC, complete days)`;
+}
+function adoptionWindowLine(summary) {
+    return `copies acquired before ${day(summary.until)} (UTC)`;
+}
+function outcomesWindowLine(outcomes) {
+    return `${outcomes.windowDays}-day window, ${day(outcomes.since)} to ${day(outcomes.until)} (UTC)`;
+}
+/**
+ * Small cells that were withheld from an otherwise reported readout. Said
+ * once, with the floor, so a short table is not mistaken for a complete one.
+ */
+function suppressedCellsLine(cells, minimumCohort, unit) {
+    const parts = Object.entries(cells)
+        .filter(([, count]) => Number(count) > 0)
+        .map(([name, count]) => `${count} ${humanize(name)}`);
+    if (parts.length === 0)
+        return null;
+    return `Withheld rows (fewer than ${minimumCohort} ${unit} each): ${parts.join(', ')}.`;
+}
+function humanize(key) {
+    return key.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+}
+/** An exclusion count; `null` is "some, from too few buyers to say how many". */
+function exclusionValue(value) {
+    if (value === null)
+        return 'some (too few buyers to count)';
+    if (value === undefined)
+        return '-';
+    return String(value);
+}

package/dist/lib/task-batch.d.ts

@@ -0,0 +1,67 @@
+import { type TaskBatchItemResult, type TaskBatchPatchItem } from '@skrr-ai/data-provider';
+export type ApiFailure = {
+    message: string;
+    status?: number;
+    code?: string;
+    retryable: boolean;
+};
+/** Normalize a thrown API error (or a per-item batch error) into one shape. */
+export declare function describeApiFailure(err: unknown): ApiFailure;
+/**
+ * A server that predates the batch routes answers 404 (no such POST route) or
+ * 405. A processed batch is ALWAYS a 200 (or 400/413/429 with a code), so a
+ * bare 404/405 on the batch call itself means "route missing", never "task
+ * not found".
+ */
+export declare function isBatchRouteMissing(err: unknown): boolean;
+export declare function chunkItems<T>(items: T[], size?: number): T[][];
+/**
+ * Same chunk, same key: a retry of an interrupted command replays the stored
+ * result instead of creating twice. The key is a fingerprint of the items, so a
+ * DIFFERENT chunk can never collide with it (the server answers 422 on a key
+ * reused with a different body).
+ */
+export declare function batchIdempotencyKey(kind: 'create' | 'patch', items: unknown[]): string;
+export type BatchCreateNode = {
+    key: string;
+    parentKey?: string;
+    payload: Record<string, unknown>;
+};
+export type BatchCreatedRow = {
+    key: string;
+    id: string;
+    identifier?: string;
+    /** `created` now, or `exists` when an earlier attempt already made it. */
+    status: 'created' | 'exists';
+    externalKey?: string;
+};
+export type BatchCreateFailure = {
+    key: string;
+    /** Not attempted because its parent was not created (or an earlier chunk failed). */
+    skipped: boolean;
+    error: ApiFailure;
+};
+export type BatchCreateOutcome = {
+    supported: false;
+} | {
+    supported: true;
+    rows: BatchCreatedRow[];
+    failures: BatchCreateFailure[];
+};
+/**
+ * Create `nodes` (parents before children) in chunks. `mapping` holds key -> id
+ * for nodes that already exist and is extended in place. Stops after the first
+ * chunk that reports a failure, as the serial path stopped at its first failure.
+ */
+export declare function createNodesViaBatch(nodes: BatchCreateNode[], mapping: Record<string, string>): Promise<BatchCreateOutcome>;
+export type BatchPatchOutcome = {
+    supported: false;
+} | {
+    supported: true;
+    results: TaskBatchItemResult[];
+};
+/**
+ * Apply `updates` in chunks; `results[i]` answers `updates[i]`. A chunk the
+ * server never processed is reported `skipped` for every row rather than lost.
+ */
+export declare function patchTasksViaBatch(updates: TaskBatchPatchItem[]): Promise<BatchPatchOutcome>;