@skrr-ai/cli 0.1.92 → 0.1.94

package/dist/lib/list-output.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listOutputFlags = exports.COMPACT_FIELDS = void 0;
+exports.parseFields = parseFields;
+exports.projectRow = projectRow;
+exports.toListEnvelope = toListEnvelope;
+exports.shapeListResponse = shapeListResponse;
+exports.limitNote = limitNote;
+exports.warningLines = warningLines;
+exports.renderListOutput = renderListOutput;
+/**
+ * Shared output shaping for `skrr` LIST commands (agent-surface audit
+ * OSK-14039 / OSK-14040: P3, P4, E1, E11).
+ *
+ * A list command's `--json` used to print whatever the server sent: 4.4 KB per
+ * task, 38% of it `activityLog`, with no way to ask for less, and an envelope
+ * that differed per command. This module is the one place that decides:
+ *
+ *   - the ENVELOPE: `{object:'list', data, has_more, next_cursor, ...}`, the same
+ *     for every list command (`data` is always the row array, so a consumer that
+ *     read `.data` keeps working);
+ *   - the PROJECTION: `--fields a,b,c` (explicit, wins) or `--compact` (a
+ *     documented per-resource navigation set), applied to `data` rows only;
+ *   - `--ndjson`: one JSON row per line on stdout, metadata on stderr;
+ *   - NOTES: `limit_applied` / `warnings[]`, so "the server clamped your limit" and
+ *     "your filter matched nothing because it is not a state id" are visible in
+ *     JSON the way they already are in text.
+ *
+ * Pure functions, no oclif: the commands own I/O, this owns the shape.
+ */
+const core_1 = require("@oclif/core");
+/**
+ * The navigation projection per resource: enough to identify a row, decide
+ * whether it matters and fetch it with `show`. Allowlists, not drop-lists, so a
+ * field the server adds tomorrow does not silently re-inflate every compact row.
+ * Documented in docs/cli/SKRR_TASKS.md (List output for agents).
+ */
+exports.COMPACT_FIELDS = {
+    task: [
+        'id',
+        'identifier',
+        'ref',
+        'title',
+        'status',
+        'statusType',
+        'priority',
+        'estimate',
+        'assigneeAgentIds',
+        'assigneeUserIds',
+        'parentId',
+        'spaceId',
+        'projectId',
+        'goalId',
+        'dueDate',
+        'scheduledFor',
+        'labelIds',
+        'tags',
+        'externalKey',
+        'version',
+        'executionMode',
+        'nextAction',
+        'createdAt',
+        'updatedAt',
+        'url',
+    ],
+    space: [
+        'id',
+        'identifier',
+        'title',
+        'status',
+        'parentSpaceId',
+        'leadAgentId',
+        'labelIds',
+        'archivedAt',
+        'createdAt',
+        'updatedAt',
+        'url',
+    ],
+    project: [
+        'id',
+        'identifier',
+        'title',
+        'spaceId',
+        'externalKey',
+        'taskCounts',
+        'archivedAt',
+        'createdAt',
+        'updatedAt',
+        'url',
+    ],
+};
+/** The three flags every projecting list command declares. */
+exports.listOutputFlags = {
+    fields: core_1.Flags.string({
+        description: 'JSON only: comma-separated fields to keep on each row (dotted paths allowed, e.g. id,title,assignee.name). Wins over --compact.',
+    }),
+    compact: core_1.Flags.boolean({
+        description: 'JSON only: keep the navigation fields of each row (id, ref, title, status, owners, dates, url) and drop activity logs, lifecycle and other bulk. See docs/cli/SKRR_TASKS.md (List output for agents).',
+    }),
+    ndjson: core_1.Flags.boolean({
+        description: 'One JSON object per line on stdout (rows only; paging and warnings go to stderr as one {"_meta":...} line). Implies --json.',
+    }),
+};
+/** `--fields a, b ,c` -> ['a','b','c']; empty/blank -> undefined. */
+function parseFields(raw) {
+    if (!raw)
+        return undefined;
+    const fields = raw
+        .split(',')
+        .map((f) => f.trim())
+        .filter(Boolean);
+    return fields.length > 0 ? Array.from(new Set(fields)) : undefined;
+}
+function pick(row, path) {
+    let current = row;
+    for (const segment of path.split('.')) {
+        if (current === null || typeof current !== 'object' || !(segment in current)) {
+            return { found: false, value: undefined };
+        }
+        current = current[segment];
+    }
+    return { found: true, value: current };
+}
+function assign(target, path, value) {
+    const segments = path.split('.');
+    let cursor = target;
+    for (const segment of segments.slice(0, -1)) {
+        const next = cursor[segment];
+        if (next === null || typeof next !== 'object' || Array.isArray(next))
+            cursor[segment] = {};
+        cursor = cursor[segment];
+    }
+    cursor[segments[segments.length - 1]] = value;
+}
+function projectRow(row, fields) {
+    const out = {};
+    for (const field of fields) {
+        const { found, value } = pick(row, field);
+        if (found)
+            assign(out, field, value);
+    }
+    return out;
+}
+/**
+ * Normalize any list response to the shared envelope. `data` is where rows live
+ * for every list command; `projects` (an older serialization) is folded into it.
+ * A response that is not list-shaped is returned untouched (never invent rows).
+ */
+function toListEnvelope(response) {
+    if (Array.isArray(response)) {
+        return {
+            object: 'list',
+            data: response,
+            has_more: false,
+            next_cursor: null,
+        };
+    }
+    if (!response || typeof response !== 'object')
+        return undefined;
+    const r = response;
+    const rows = Array.isArray(r.data) ? r.data : Array.isArray(r.projects) ? r.projects : undefined;
+    if (!rows)
+        return undefined;
+    const { projects: _legacy, ...rest } = r;
+    void _legacy;
+    return {
+        ...rest,
+        object: 'list',
+        data: rows,
+        has_more: typeof r.has_more === 'boolean' ? r.has_more : Boolean(r.next_cursor),
+        next_cursor: typeof r.next_cursor === 'string' ? r.next_cursor : null,
+    };
+}
+/** Pure: envelope + projection + notes. Returns the response untouched if not a list. */
+function shapeListResponse(response, options) {
+    const envelope = toListEnvelope(response);
+    if (!envelope)
+        return response;
+    const warnings = [...(options.warnings ?? [])];
+    const fields = parseFields(options.fields);
+    let data = envelope.data;
+    if (fields) {
+        data = data.map((row) => projectRow(row, fields));
+        if (envelope.data.length > 0) {
+            for (const field of fields) {
+                if (!envelope.data.some((row) => pick(row, field).found)) {
+                    warnings.push({
+                        code: 'UNKNOWN_FIELD',
+                        value: field,
+                        hint: `No row carried "${field}". Run without --fields to see the available keys.`,
+                    });
+                }
+            }
+        }
+    }
+    else if (options.compact) {
+        const keep = exports.COMPACT_FIELDS[options.resource];
+        data = data.map((row) => {
+            const kept = projectRow(row, keep);
+            // A row that carries none of the navigation fields is an unknown shape;
+            // dropping it to `{}` would hide it rather than compact it.
+            return Object.keys(kept).length > 0 ? kept : row;
+        });
+    }
+    const limit = limitNote(options.requestedLimit, envelope.data.length, envelope.has_more);
+    if (limit.warning)
+        warnings.push(limit.warning);
+    return {
+        ...envelope,
+        data,
+        ...(limit.applied !== undefined ? { limit_applied: limit.applied } : {}),
+        ...(options.filterApplied ? { filter_applied: options.filterApplied } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
+}
+/**
+ * E11: the server silently clamps `--limit` (cap) and coerces `0` to its default.
+ * Echo what was applied. `applied` is only reported when we can prove it: a full
+ * page that still has more rows means the cap is exactly the row count.
+ */
+function limitNote(requested, rowCount, hasMore) {
+    if (requested === undefined)
+        return {};
+    if (requested <= 0) {
+        return {
+            applied: hasMore ? rowCount : undefined,
+            warning: {
+                code: 'LIMIT_COERCED',
+                value: requested,
+                hint: '--limit must be >= 1; the server applied its default page size instead. Pass an explicit positive --limit.',
+            },
+        };
+    }
+    if (hasMore && rowCount > 0 && rowCount < requested) {
+        return {
+            applied: rowCount,
+            warning: {
+                code: 'LIMIT_CLAMPED',
+                value: requested,
+                hint: `The server returned ${rowCount} rows, its per-page cap, not the ${requested} requested. Follow next_cursor for the rest.`,
+            },
+        };
+    }
+    return {};
+}
+/** The text-mode twin of a warning: one `Note:` line a person can act on. */
+function warningLines(warnings) {
+    return (warnings ?? []).map((w) => `Note: ${w.hint}`);
+}
+/**
+ * Render a shaped list for `--json` (pretty envelope) or `--ndjson` (rows one per
+ * line, `_meta` on stderr). Pure; the caller writes the lines.
+ */
+function renderListOutput(shaped, ndjson) {
+    if (!ndjson)
+        return { stdout: [JSON.stringify(shaped, null, 2)], stderr: [] };
+    const envelope = shaped;
+    if (!envelope || !Array.isArray(envelope.data)) {
+        return { stdout: [JSON.stringify(shaped)], stderr: [] };
+    }
+    const { data, ...meta } = envelope;
+    return {
+        stdout: data.map((row) => JSON.stringify(row)),
+        stderr: [JSON.stringify({ _meta: meta })],
+    };
+}

package/dist/lib/machine-daemon-log.d.ts

@@ -0,0 +1,36 @@
+import { COMPUTER_DAEMON_LOG_LEVELS, COMPUTER_DAEMON_LOG_LIMITS, type ComputerDaemonLogResult } from '@skrr-ai/data-provider';
+import { type ComputerFileFailure } from './computer-files';
+/**
+ * machine-daemon-log.ts — request client for `GET /api/machines/:machineId/daemon-log`
+ * (`computer_daemon_log_v1`): the tail of what a machine's daemon logged about
+ * itself, so an owner can see why it reconnected, re-registered or failed
+ * without reading syslog (which a Dedicated Runtime guest's tenant uid cannot).
+ *
+ * The daemon serves an in-memory ring of its OWN logger's lines, redacted
+ * before they were kept; a `watch` grantee reads it too. Vocabulary, limits
+ * and the result shape are owned by `@skrr-ai/data-provider`.
+ *
+ * ## Inline path literal
+ *
+ * `domain-api-parity` resolves a command to an endpoint by reading this
+ * string; a helper that assembled the URL would read as unreachable.
+ */
+export { COMPUTER_DAEMON_LOG_LEVELS, COMPUTER_DAEMON_LOG_LIMITS };
+export type { ComputerDaemonLogResult };
+export interface MachineDaemonLogQuery {
+    lines?: number;
+    sinceMs?: number;
+    level?: (typeof COMPUTER_DAEMON_LOG_LEVELS)[number];
+}
+export declare function getMachineDaemonLog(machineId: string, query?: MachineDaemonLogQuery): Promise<ComputerDaemonLogResult>;
+/** `--since 90s|30m|2h|1d` as milliseconds, bounded by what the daemon will look back. */
+export declare function parseDaemonLogSince(value: string): number;
+/**
+ * A failed read as the sentence the command prints. `capability_missing` is the
+ * zero state: this machine's daemon predates the log, and the fix is the image.
+ * `consent_missing` is a personal machine that has not run `skrr computer allow`.
+ */
+export declare function describeDaemonLogFailure(err: unknown, ctx: {
+    bin: string;
+    leaseId: string;
+}): ComputerFileFailure | null;

package/dist/lib/machine-daemon-log.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPUTER_DAEMON_LOG_LIMITS = exports.COMPUTER_DAEMON_LOG_LEVELS = void 0;
+exports.getMachineDaemonLog = getMachineDaemonLog;
+exports.parseDaemonLogSince = parseDaemonLogSince;
+exports.describeDaemonLogFailure = describeDaemonLogFailure;
+const data_provider_1 = require("@skrr-ai/data-provider");
+Object.defineProperty(exports, "COMPUTER_DAEMON_LOG_LEVELS", { enumerable: true, get: function () { return data_provider_1.COMPUTER_DAEMON_LOG_LEVELS; } });
+Object.defineProperty(exports, "COMPUTER_DAEMON_LOG_LIMITS", { enumerable: true, get: function () { return data_provider_1.COMPUTER_DAEMON_LOG_LIMITS; } });
+const api_fetch_1 = require("./api-fetch");
+const computer_files_1 = require("./computer-files");
+async function getMachineDaemonLog(machineId, query = {}) {
+    const params = new URLSearchParams();
+    if (query.lines !== undefined)
+        params.set('lines', String(query.lines));
+    if (query.sinceMs !== undefined)
+        params.set('sinceMs', String(query.sinceMs));
+    if (query.level)
+        params.set('level', query.level);
+    const qs = params.toString();
+    const suffix = qs ? `?${qs}` : '';
+    return (0, api_fetch_1.apiFetch)(`/api/machines/${encodeURIComponent(machineId)}/daemon-log` + suffix);
+}
+const SINCE_UNIT_MS = {
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+/** `--since 90s|30m|2h|1d` as milliseconds, bounded by what the daemon will look back. */
+function parseDaemonLogSince(value) {
+    const match = value.trim().match(/^(\d+)([smhd])$/i);
+    if (!match) {
+        throw new Error(`Invalid --since value: ${value}. Use an age such as 90s, 30m, 2h or 1d.`);
+    }
+    const ms = Number(match[1]) * SINCE_UNIT_MS[match[2].toLowerCase()];
+    if (ms < 1 || ms > data_provider_1.COMPUTER_DAEMON_LOG_LIMITS.maxSinceMs) {
+        throw new Error(`--since must be between 1s and ${data_provider_1.COMPUTER_DAEMON_LOG_LIMITS.maxSinceMs / 3_600_000}h; the daemon keeps a short, recent log.`);
+    }
+    return ms;
+}
+/**
+ * A failed read as the sentence the command prints. `capability_missing` is the
+ * zero state: this machine's daemon predates the log, and the fix is the image.
+ * `consent_missing` is a personal machine that has not run `skrr computer allow`.
+ */
+function describeDaemonLogFailure(err, ctx) {
+    const refusal = (0, computer_files_1.computerFileRefusalInfo)(err);
+    if (refusal?.code === 'capability_missing') {
+        return {
+            message: `This machine's daemon predates daemon logs, so it has none to show. ` +
+                `\`${ctx.bin} machines dedicated update-image ${ctx.leaseId}\` moves the machine onto the current image, which keeps one.`,
+            code: 'capability_missing',
+            status: refusal.status,
+            retryable: false,
+            details: refusal.body,
+        };
+    }
+    if (refusal?.code === 'consent_missing') {
+        return {
+            message: `${refusal.message} The person who uses the machine sets this on it: \`${ctx.bin} computer allow\`.`,
+            code: 'consent_missing',
+            status: refusal.status,
+            retryable: false,
+            details: refusal.body,
+        };
+    }
+    if (refusal?.code === 'unauthorized') {
+        return {
+            message: `${refusal.message} Reading a machine's daemon log needs at least the watch tier — see \`${ctx.bin} machines shares ${ctx.leaseId}\`.`,
+            code: 'unauthorized',
+            status: refusal.status,
+            retryable: false,
+            details: refusal.body,
+        };
+    }
+    return (0, computer_files_1.describeComputerFileFailure)(err, ctx);
+}

package/dist/lib/node-adapter.js

@@ -18,6 +18,7 @@ const delegated_cli_1 = require("./delegated-cli");
 const workspace_header_1 = require("./workspace-header");
 const non_json_response_1 = require("./non-json-response");
 require("./auth-core-init");
+const rate_limit_retry_1 = require("./rate-limit-retry");
 // ---------------------------------------------------------------------
 // Per-process credential override — set by BaseCommand.init().
 // Pulled out of the closure so test harnesses or long-lived callers
@@ -146,6 +147,8 @@ function createNodeAdapter(opts = {}) {
         }
         return u.toString();
     }
+    /** The last 429's `Retry-After`, read off the response of the most recent attempt. */
+    let lastRetryAfterMs;
     async function rawRequest(method, url, body, options, isFormData) {
         const headers = buildHeaders(options?.headers);
         let finalBody;
@@ -163,7 +166,10 @@ function createNodeAdapter(opts = {}) {
         // OSK-12020 — a DPoP-bound hand-off token needs a fresh proof per request
         // (and per retry: proofs are single-use). No-op for every other token.
         Object.assign(headers, await (0, dpop_auth_1.dpopHeadersFor)(currentCredential().token, method, finalUrl));
-        return fetch(finalUrl, { method, headers, body: finalBody });
+        // E6: bounded retry on 429 for a GET or an idempotency-keyed write.
+        const { response, retryAfterMs } = await (0, rate_limit_retry_1.fetchWithRateLimitRetry)(() => fetch(finalUrl, { method, headers, body: finalBody }), { method, headers });
+        lastRetryAfterMs = retryAfterMs;
+        return response;
     }
     /**
      * Inner refresh: delegates to `refresh.ts`, the shared CLI refresh
@@ -359,6 +365,9 @@ function createNodeAdapter(opts = {}) {
             // "which of these requests was mine" is otherwise unanswerable, and a
             // 409 that belonged to another session was nearly filed as a CLI bug.
             err.requestId = res.headers.get('x-request-id') || undefined;
+            if (res.status === 429 && lastRetryAfterMs !== undefined) {
+                err.retryAfterMs = lastRetryAfterMs;
+            }
             throw err;
         }
         if (options?.responseType === 'arraybuffer') {

package/dist/lib/northstars.js

@@ -148,7 +148,7 @@ function renderNorthstar(status, log) {
             id: commitment.id,
             title: String(commitment.title ?? ''),
             status: String(commitment.status ?? ''),
-            health: String(commitment.state?.health ?? 'unknown'),
+            health: String(commitment.assessment?.label ?? 'Outcome unknown'),
             tier: String(commitment.priority?.tier ?? '—'),
         })), [
             { key: 'id', header: 'COMMITMENT' },

package/dist/lib/open-target.d.ts

@@ -0,0 +1,12 @@
+export declare const OPEN_REF_KINDS: readonly string[];
+export type OpenTargetErrorCode = 'OPEN_TARGET_EMPTY' | 'OPEN_TARGET_FOREIGN' | 'OPEN_TARGET_UNKNOWN';
+export declare class OpenTargetError extends Error {
+    readonly code: OpenTargetErrorCode;
+    constructor(message: string, code: OpenTargetErrorCode);
+}
+export type ResolvedOpenTarget = {
+    url: string;
+    /** Which spelling was given — echoed by `--json` so a script can tell. */
+    form: 'url' | 'path' | 'ref' | 'agent';
+};
+export declare function resolveOpenTarget(input: string, baseURL: string): Promise<ResolvedOpenTarget>;

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;
+}>;