@trydreamstate/cli 1.3.2 → 1.3.3

package/dist/errors.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLI_LOCAL_ERROR_REPAIRS = exports.CLI_LOCAL_ERROR_CODES = exports.CLI_EXIT = exports.CliUsageError = void 0;
+exports.isApprovalGateCode = isApprovalGateCode;
+exports.isLocalRefusalCode = isLocalRefusalCode;
+class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliUsageError';
+    }
+}
+exports.CliUsageError = CliUsageError;
+/**
+ * Process exit codes. The numbers are a published contract; change them only
+ * with a major version. `dreamstate --help` renders their stable meanings.
+ *
+ * Contract C5 (cross-surface): 0 ok, 1 generic, 2 usage, 3 auth, 4 not found,
+ * 5 conflict/validation, 6 rate limited, 7 approval/consent/spend gate required,
+ * 8 cli_update_required, 9 other refusal. Where this CLI had already published a
+ * different meaning it kept the published one and the mapping is documented:
+ *
+ * - 5 stays "server failure" (HTTP 5xx and unreadable responses). A 4xx
+ *   conflict or validation refusal exits 9, as published and pinned by
+ *   exitCodes.test.ts: a script must not read a caller mistake as a broken server.
+ * - 8 is cli_update_required. It was "request timeout" before; timeouts are 11
+ *   now, so a script can tell "update the CLI" from "try again later".
+ */
+exports.CLI_EXIT = {
+    SUCCESS: 0,
+    UNCLASSIFIED: 1,
+    USAGE: 2,
+    AUTH: 3,
+    NOT_FOUND: 4,
+    SERVER: 5,
+    RATE_LIMITED: 6,
+    APPROVAL: 7,
+    UPDATE_REQUIRED: 8,
+    REFUSED: 9,
+    TRANSPORT: 10,
+    TIMEOUT: 11,
+};
+/**
+ * Codes the CLI process raises itself, with no server answer behind them.
+ * The server never emits these. They are declared here, once, so the README
+ * table and the tests that keep every code in CLI source accounted for
+ * (errorCodes.test.ts) read one list. A code that is not in this table must be
+ * a member of the shared API_ERROR_CODES.
+ */
+exports.CLI_LOCAL_ERROR_CODES = {
+    network_error: 'The request never reached the server (DNS, connection refused, TLS). Nothing executed.',
+    request_timeout: 'The server did not answer in time. The effect may have happened. Read the target back first. If the effect is there, report it done. If not, repeat the identical call once with the first attempt\'s idempotency key, never a new one. If the read-back is inconclusive, or the repeat is refused pending acknowledgement, ask the person.',
+    invalid_response: 'The server answered with something that is not a Dreamstate envelope.',
+    invalid_tool_turn_token: 'tools get returned no tool_turn_token to run with.',
+    invalid_web_url: 'The API returned a web_url that is not a safe http(s) URL.',
+    web_url_unavailable: '--open was given but the response carries no web_url.',
+    plugin_install_failed: 'dreamstate install could not install the plugin for any agent.',
+    skills_authentication_required: 'skills install needs a stored login.',
+};
+/** Recovery metadata for failures raised by this CLI, rather than the API. */
+exports.CLI_LOCAL_ERROR_REPAIRS = {
+    network_error: { kind: 'wait', hint: 'Retry the unchanged request when network connectivity is available.' },
+    request_timeout: { kind: 'ask_user', hint: 'Read the target back first. If absent, repeat once with the same idempotency key; otherwise ask the person.' },
+    invalid_response: { kind: 'server_defect', hint: 'The API response was not a Dreamstate envelope; report the trace id if one was returned.' },
+    invalid_tool_turn_token: { kind: 'server_defect', hint: 'The API did not provide a runnable tool turn; retry after reporting the response trace id.' },
+    invalid_web_url: { kind: 'server_defect', hint: 'The API returned an invalid web URL; report the response trace id.' },
+    web_url_unavailable: { kind: 'not_possible', hint: 'This result has no web URL to open.' },
+    plugin_install_failed: { kind: 'ask_user', hint: 'Install a supported agent, then retry plugin installation.' },
+    skills_authentication_required: { kind: 'ask_user', hint: 'Sign in with dreamstate login, then retry.' },
+};
+/**
+ * Refusals that mean a person (or the caller's own spend decision) must supply
+ * something before the run can proceed: an approval, a consent, a quote or a
+ * spend ceiling. They exit 7, whatever HTTP status carried them, so a script
+ * can stop and ask instead of retrying.
+ */
+const GATE_CODES = new Set([
+    'approval_required',
+    'standing_approval_required',
+    'destructive_approval_required',
+    'owner_approval_required',
+    'knowledge_approval_required',
+    'content_approval_required',
+    'effect_unknown_approval_required',
+    'approval_cap_exceeded',
+    'approval_stale',
+    'agent_tool_policy_ask_before_changes',
+    'publish_confirmation_required',
+    'launch_authorization_required',
+    'publish_permission_required',
+    'delegation_grant_required',
+    'creator_consent_required',
+    'csv_replace_confirmation_required',
+    'quote_required',
+    'quote_mismatch',
+    'quote_stale',
+    'quote_already_used',
+    'spend_cap',
+    'spend_cap_required',
+    'spend_cap_too_low',
+    'cost_cap_exceeded',
+    'agent_paid_capability_requires_max_credits',
+    'max_rows_required',
+    'mode_required',
+    'sequence_send_cap_required',
+]);
+const GATE_CODE_PATTERN = /(?:approval|consent|confirmation|authorization)_required$|requires_approval$/;
+function isApprovalGateCode(code) {
+    return Boolean(code) && (GATE_CODES.has(code) || GATE_CODE_PATTERN.test(code));
+}
+/**
+ * Refusals the CLI decides locally, before running anything, that are not usage
+ * errors: the capability is not published for the CLI surface.
+ */
+const LOCAL_REFUSAL_CODES = new Set(['unsupported_capability']);
+function isLocalRefusalCode(code) {
+    return Boolean(code) && LOCAL_REFUSAL_CODES.has(code);
+}

package/dist/gatedRun.d.ts

@@ -0,0 +1,81 @@
+import { CliError, type DreamstateClient } from './client';
+import { type IdempotencyIdentity } from './idempotency';
+export declare function code(error: unknown): string | undefined;
+export declare function toolTurnToken(value: unknown): string;
+export declare function omitsToolTurnForInlineTableRead(capabilityId: string): boolean;
+/** The capability record inside a tools get response, or null when the shape is unknown. */
+export declare function capabilityRecord(fetched: unknown): Record<string, unknown> | null;
+/**
+ * Header value, or null when the request must not carry Idempotency-Key.
+ * Any key forces a read onto the durable run path (isInlineReadEligible).
+ * Send one only for an explicit key, or when the tools get contract says
+ * mutates or idempotency_required. Missing flags omit the key: a read whose
+ * contract does not set mutates must not be treated as a write.
+ *
+ * A write's key is scoped to an attempt (idempotency.ts). A pending interrupted
+ * attempt reuses its key; a terminal attempt gets a fresh key on a later command.
+ */
+export declare function capabilityIdempotencyKey(fetched: unknown, explicit: string | undefined, identity: IdempotencyIdentity): string | null;
+export declare function parameterIdempotencyKey(body: Record<string, unknown>): string | undefined;
+/**
+ * Whether the capability is published for the CLI surface. The tools get
+ * contract lists the CLI commands the catalog advertises (cli_commands); an
+ * empty list means the capability is not on this surface. This reads the
+ * field the contract carries today; when the shared surface-visibility
+ * function (contract C7) reaches the contract this is the one place to
+ * call it. A contract that says nothing about the CLI is allowed, because a
+ * missing field is not a refusal.
+ */
+export declare function cliSurfaceRefusal(capabilityId: string, fetched: unknown): CliError | null;
+/**
+ * What a quote prices: the params plus the ceiling. Keys that say how a call is
+ * made, not what it does, are left out, like the server's own plan digest.
+ */
+export declare function planFingerprint(body: Record<string, unknown>): string;
+export interface GatedRunContext {
+    client: DreamstateClient;
+    baseUrl: string;
+    /** apiKey plus workspace: a turn belongs to one workspace, so it is part of the cache identity. */
+    turnKey: string;
+    turnsPath: string;
+    /** Pending live-attempt keys, stored next to CLI credentials. */
+    idempotencyPath?: string;
+    workspace?: string;
+    stderr: NodeJS.WritableStream;
+    sleep: (milliseconds: number) => Promise<void>;
+}
+export interface GatedRunInput {
+    capabilityId: string;
+    /** Door body: params plus mode, approved, max_credits, quote_hash, approval_id ... */
+    body: Record<string, unknown>;
+    /** --turn-token: a token the caller already holds from tools get. */
+    turnToken?: string;
+    /** --idempotency-key: used as given. Without it a write gets a deterministic key. */
+    idempotencyKey?: string;
+    waitTimeout: number;
+    noWait?: boolean;
+    /**
+     * The params came from shell flags (pack verbs), so each string value is
+     * converted to the type the capability's live input schema declares.
+     */
+    coerceParams?: boolean;
+    /**
+     * Last edit of the params once the live capability contract is known. Used by
+     * pack verbs to bridge a capability that still declares a gating input inside
+     * its params (contract C6 keeps those at the door): the verb copies the door
+     * value into params only while the contract's input schema still lists it.
+     */
+    adjustParams?: (params: Record<string, unknown>, capability: Record<string, unknown> | null) => Record<string, unknown>;
+}
+export interface GatedRunOutcome {
+    value: unknown;
+    timedOut: boolean;
+    /** The Idempotency-Key the run was sent with, or null when none applied. */
+    idempotencyKey: string | null;
+    /** The tool_turn_token the run used, so a caller making many runs of one capability can reuse it. */
+    turnToken: string | null;
+}
+export declare function runGated(context: GatedRunContext, input: GatedRunInput): Promise<GatedRunOutcome>;
+/** A read the CLI needs before it can form a write, run through the same gate as any other run. */
+export declare function readCapability(context: GatedRunContext, capabilityId: string, params: Record<string, unknown>, waitTimeout: number): Promise<unknown>;
+//# sourceMappingURL=gatedRun.d.ts.map

package/dist/gatedRun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatedRun.d.ts","sourceRoot":"","sources":["../src/gatedRun.ts"],"names":[],"mappings":"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"}

package/dist/gatedRun.js

@@ -0,0 +1,370 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.code = code;
+exports.toolTurnToken = toolTurnToken;
+exports.omitsToolTurnForInlineTableRead = omitsToolTurnForInlineTableRead;
+exports.capabilityRecord = capabilityRecord;
+exports.capabilityIdempotencyKey = capabilityIdempotencyKey;
+exports.parameterIdempotencyKey = parameterIdempotencyKey;
+exports.cliSurfaceRefusal = cliSurfaceRefusal;
+exports.planFingerprint = planFingerprint;
+exports.runGated = runGated;
+exports.readCapability = readCapability;
+const node_crypto_1 = require("node:crypto");
+const client_1 = require("./client");
+const errors_1 = require("./errors");
+const idempotency_1 = require("./idempotency");
+const schemaCoercion_1 = require("./schemaCoercion");
+const runWait_1 = require("./runWait");
+const turnCache_1 = require("./turnCache");
+/**
+ * The one path every capability run takes: `tools run` and every pack verb
+ * (`sequences ...`, `workflows ...`) call runGated. Gating lives here and only
+ * here (contract C6): mode, max_credits, quote_hash, approved, approval_id and
+ * the idempotency key are door inputs, handled once, so a verb can never be a
+ * quieter way to run what `tools run` would stop.
+ */
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function code(error) {
+    return error && typeof error === 'object' && typeof error.code === 'string'
+        ? error.code
+        : undefined;
+}
+function toolTurnToken(value) {
+    const root = value && typeof value === 'object' ? value : {};
+    const data = root.data && typeof root.data === 'object' ? root.data : {};
+    if (typeof data.tool_turn_token === 'string' && data.tool_turn_token.trim())
+        return data.tool_turn_token;
+    throw new client_1.CliError('tools get did not return a tool_turn_token.', 'invalid_tool_turn_token', 0);
+}
+/**
+ * Free sync reads. The server runs these on the inline read path when
+ * the body has no tool_turn_token and the request has no Idempotency-Key
+ * (isInlineReadEligible). A tools get before the run is a second HTTP the
+ * read does not need. Measured 2026-10-04: tables.workbooks.get full live CLI
+ * 0.726s against whoami 0.455s, about 0.27s of tools get per harness read-back.
+ * knowledge.brain.context.get is the same class (catalog: credit_class free,
+ * async_policy.mode sync, mutates not set). Live 2026-10-05 a standalone
+ * tools get of that id was 0.400s including node startup, next to whoami
+ * 0.422s, so the same-process skip is one HTTP, not a second process.
+ * The set name is historical. Writes are not in this set: they stay fetch-first.
+ */
+const INLINE_READ_CAPABILITIES = new Set([
+    'tables.workbooks.get',
+    'tables.workbooks.overview',
+    'tables.workbooks.list',
+    'tables.columns.list',
+    'tables.columns.stats',
+    'tables.rows.query',
+    'tables.rows.get',
+    'tables.rows.count',
+    'knowledge.brain.context.get',
+    // Both are stored, free, synchronous inbox reads. Keeping either behind a
+    // tools_get turns one list or thread open into two HTTP requests, while the
+    // canonical inline-read gate already validates their read-only contract.
+    'unibox.inbox.unified_list',
+    'unibox.inbox.conversation_get',
+]);
+function omitsToolTurnForInlineTableRead(capabilityId) {
+    return INLINE_READ_CAPABILITIES.has(capabilityId);
+}
+/** The capability record inside a tools get response, or null when the shape is unknown. */
+function capabilityRecord(fetched) {
+    const root = record(fetched);
+    if (!root)
+        return null;
+    const data = record(root.data);
+    return record(data?.capability) ?? record(root.capability);
+}
+function readIdempotencyContract(fetched) {
+    if (!fetched || typeof fetched !== 'object' || Array.isArray(fetched))
+        return null;
+    const root = fetched;
+    const data = record(root.data);
+    const candidates = [data?.capability, root.capability, data, root];
+    for (const candidate of candidates) {
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
+            continue;
+        if ('mutates' in candidate || 'idempotency_required' in candidate) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Header value, or null when the request must not carry Idempotency-Key.
+ * Any key forces a read onto the durable run path (isInlineReadEligible).
+ * Send one only for an explicit key, or when the tools get contract says
+ * mutates or idempotency_required. Missing flags omit the key: a read whose
+ * contract does not set mutates must not be treated as a write.
+ *
+ * A write's key is scoped to an attempt (idempotency.ts). A pending interrupted
+ * attempt reuses its key; a terminal attempt gets a fresh key on a later command.
+ */
+function capabilityIdempotencyKey(fetched, explicit, identity) {
+    if (typeof explicit === 'string' && explicit.length > 0)
+        return explicit;
+    const contract = readIdempotencyContract(fetched);
+    if (contract?.mutates === true || contract?.idempotency_required === true)
+        return (0, idempotency_1.deterministicIdempotencyKey)(identity);
+    return null;
+}
+function parameterIdempotencyKey(body) {
+    const params = body.params;
+    if (!params || typeof params !== 'object' || Array.isArray(params))
+        return undefined;
+    const key = params.idempotency_key;
+    return typeof key === 'string' && key.length > 0 ? key : undefined;
+}
+/**
+ * Whether the capability is published for the CLI surface. The tools get
+ * contract lists the CLI commands the catalog advertises (cli_commands); an
+ * empty list means the capability is not on this surface. This reads the
+ * field the contract carries today; when the shared surface-visibility
+ * function (contract C7) reaches the contract this is the one place to
+ * call it. A contract that says nothing about the CLI is allowed, because a
+ * missing field is not a refusal.
+ */
+function cliSurfaceRefusal(capabilityId, fetched) {
+    const capability = capabilityRecord(fetched);
+    if (!capability)
+        return null;
+    const commands = capability.cli_commands;
+    const surfaces = record(capability.surfaces);
+    const absent = Array.isArray(commands) ? commands.length === 0 : surfaces?.cli === false;
+    if (!absent)
+        return null;
+    return new client_1.CliError(`${capabilityId} is not available on the CLI surface. Use the web app, MCP or the Architect for it.`, 'unsupported_capability', 0, { details: { capability_id: capabilityId, surface: 'cli' }, retryable: false });
+}
+const QUOTE_HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
+/**
+ * What a quote prices: the params plus the ceiling. Keys that say how a call is
+ * made, not what it does, are left out, like the server's own plan digest.
+ */
+function planFingerprint(body) {
+    const params = body.params && typeof body.params === 'object' && !Array.isArray(body.params)
+        ? { ...body.params }
+        : {};
+    for (const key of ['quote_hash', 'plan_digest', 'estimate_digest', 'approved', 'max_credits', 'mode', 'dry_run', 'idempotency_key', 'tool_turn_token'])
+        delete params[key];
+    return (0, node_crypto_1.createHash)('sha256').update((0, idempotency_1.stableJson)({ params, max_credits: body.max_credits ?? null })).digest('hex');
+}
+/** The quote a dry run returned, wherever the envelope nests its outputs. */
+function quoteFromResult(value, depth = 0) {
+    if (!value || typeof value !== 'object' || depth > 6)
+        return null;
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const found = quoteFromResult(entry, depth + 1);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    const entry = value;
+    if (typeof entry.quote_hash === 'string' && QUOTE_HASH_PATTERN.test(entry.quote_hash)) {
+        const estimate = entry.estimate && typeof entry.estimate === 'object' ? entry.estimate : null;
+        return {
+            quote_hash: entry.quote_hash,
+            maximum_credits: typeof estimate?.maximum_credits === 'number' ? estimate.maximum_credits : null,
+        };
+    }
+    for (const key of ['data', 'run', 'outputs', 'steps']) {
+        const found = quoteFromResult(entry[key], depth + 1);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function quoteSummary(capabilityId, body, quote) {
+    const params = body.params && typeof body.params === 'object' ? body.params : {};
+    const rows = typeof params.max_rows === 'number' ? `${params.max_rows} rows` : 'rows not stated';
+    const credits = quote.maximum_credits === null ? 'credits not stated' : `up to ${quote.maximum_credits} credits`;
+    return `Dry run of ${capabilityId} priced: ${rows}, ${credits}. Running live on that quote.`;
+}
+/** Adds the idempotency key to the printed meta, so a user can see which key to re-run with. */
+function withIdempotencyMeta(value, key) {
+    const envelope = record(value);
+    if (!envelope || !key)
+        return value;
+    return { ...envelope, meta: { ...(record(envelope.meta) ?? {}), idempotency_key: key } };
+}
+async function runGated(context, input) {
+    const { client, stderr } = context;
+    const { capabilityId } = input;
+    const idempotencyPath = context.idempotencyPath ?? `${context.turnsPath}.attempts`;
+    const body = { ...input.body };
+    let fetched = null;
+    const contract = async () => {
+        fetched ??= await client.getTool(capabilityId);
+        return fetched;
+    };
+    let warnedAboutTurnCache = false;
+    const warnTurnCache = () => {
+        if (warnedAboutTurnCache)
+            return;
+        warnedAboutTurnCache = true;
+        stderr.write('Warning: Dreamstate turn cache unavailable; continuing without turn reuse.\n');
+    };
+    // Flag-built params are converted before anything is fingerprinted, priced or sent.
+    if (input.coerceParams || input.adjustParams) {
+        const capability = capabilityRecord(await contract());
+        let params = record(body.params);
+        if (params && input.coerceParams) {
+            try {
+                (0, schemaCoercion_1.assertParamsMatchSchema)(params, capability?.input_json_schema);
+            }
+            catch (error) {
+                throw new errors_1.CliUsageError(error instanceof Error ? error.message : 'live schema validation failed');
+            }
+            params = (0, schemaCoercion_1.coerceParamsToSchema)(params, capability?.input_json_schema).params;
+        }
+        if (params && input.adjustParams)
+            params = input.adjustParams(params, capability);
+        if (params)
+            body.params = params;
+    }
+    // A paid live run needs the quote_hash of a dry run of the same input,
+    // and a quote is bound to the turn that asked for it. So a turn is reused
+    // only while a quote is pending, together with the quote its dry run
+    // returned, and forgotten once the paid run is admitted.
+    const fingerprint = planFingerprint(body);
+    const cached = input.turnToken
+        ? null
+        : await (0, turnCache_1.reusableTurn)(context.turnsPath, context.baseUrl, context.turnKey, capabilityId, fingerprint, Date.now(), warnTurnCache);
+    const pending = cached?.token ?? null;
+    const live = body.mode === 'live';
+    const inlineRead = !input.turnToken && !pending && !input.idempotencyKey && omitsToolTurnForInlineTableRead(capabilityId);
+    if (!input.turnToken && !pending && !inlineRead)
+        await contract();
+    const refusal = fetched ? cliSurfaceRefusal(capabilityId, fetched) : null;
+    if (refusal)
+        throw refusal;
+    let turnToken = input.turnToken ?? pending ?? (inlineRead ? undefined : toolTurnToken(fetched));
+    // Only a quote the caller named or a dry run of this exact input returned.
+    // The server's refusal also shows a price, but that one is information, not consent.
+    let quoteHash = typeof body.quote_hash === 'string'
+        ? body.quote_hash
+        : live ? cached?.quote_hash ?? undefined : undefined;
+    const explicitKey = parameterIdempotencyKey(body) ?? input.idempotencyKey;
+    let recoveredInlineRead = false;
+    let ranDryRun = false;
+    let sentKey = null;
+    const requestBody = () => ({
+        ...body,
+        ...(turnToken ? { tool_turn_token: turnToken } : {}),
+        ...(live && quoteHash ? { quote_hash: quoteHash } : {}),
+    });
+    // A write is replay-safe on live runs; a rehearsal has no effect to replay.
+    let attemptIdentity = null;
+    const keyFor = async (sent) => {
+        if (explicitKey)
+            return explicitKey;
+        if (sent.mode === 'dry_run' || sent.mode === 'smoke_test')
+            return null;
+        const identity = { scope: capabilityId, workspace: context.workspace, body: sent };
+        const known = capabilityIdempotencyKey(fetched, undefined, identity);
+        if (known) {
+            attemptIdentity = identity;
+            return (0, idempotency_1.pendingIdempotencyKey)(idempotencyPath, identity);
+        }
+        // A cached turn exists only because an earlier dry run of this input priced a
+        // paid write, so the live rerun is a write even though no contract was fetched.
+        return !fetched && !input.turnToken && live && pending
+            ? await (0, idempotency_1.pendingIdempotencyKey)(idempotencyPath, (attemptIdentity = { scope: capabilityId, workspace: context.workspace, body: sent }))
+            : null;
+    };
+    const run = async () => {
+        const sent = requestBody();
+        sentKey = await keyFor(sent);
+        return client.runCapability(capabilityId, sent, sentKey);
+    };
+    let result;
+    try {
+        try {
+            result = await run();
+        }
+        catch (error) {
+            // The inline skip is only valid while the server still treats this
+            // capability as a free sync read. capability_not_fetched means the
+            // fetch-first fence is on, so retry once on the old get-then-run path.
+            if (inlineRead && !recoveredInlineRead && code(error) === 'capability_not_fetched') {
+                recoveredInlineRead = true;
+                fetched = await client.getTool(capabilityId);
+                turnToken = toolTurnToken(fetched);
+                result = await run();
+            }
+            else if (live && code(error) === 'quote_required' && !quoteHash && turnToken) {
+                // A live paid run with no quote behind it. The refusal's own quote is
+                // only a price and is never replayed, so price the same input with a
+                // real dry run (free, never calls a paid provider), show the person
+                // its rows and cost, and run live on that quote. Above the size or
+                // dollar threshold the server still refuses until --approved.
+                const dry = await client.runCapability(capabilityId, {
+                    ...body,
+                    mode: 'dry_run',
+                    tool_turn_token: turnToken,
+                }, null);
+                const quote = quoteFromResult(dry);
+                if (!quote)
+                    throw error;
+                // The no-quote call was definitively refused before execution. Its
+                // pending attempt must not survive into the separately quoted call.
+                if (attemptIdentity) {
+                    await (0, idempotency_1.finishIdempotencyAttempt)(idempotencyPath, attemptIdentity);
+                    attemptIdentity = null;
+                }
+                ranDryRun = true;
+                quoteHash = quote.quote_hash;
+                stderr.write(`${quoteSummary(capabilityId, body, quote)}\n`);
+                await (0, turnCache_1.rememberTurnToken)(context.turnsPath, context.baseUrl, context.turnKey, capabilityId, turnToken, Date.now(), warnTurnCache, { quote_hash: quote.quote_hash, fingerprint });
+                result = await run();
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    catch (error) {
+        // Keep the turn and the quote across a refusal that a person can fix,
+        // so the rerun (with --approved, or a stated max_rows) reuses them.
+        if (!input.turnToken && turnToken && (code(error) === 'quote_required' || code(error) === 'approval_required')) {
+            if (code(error) === 'approval_required') {
+                stderr.write('This run needs a person\'s approval. Show them the rows and cost above; when they agree, rerun the same command with --approved.\n');
+            }
+            await (0, turnCache_1.rememberTurnToken)(context.turnsPath, context.baseUrl, context.turnKey, capabilityId, turnToken, Date.now(), warnTurnCache, quoteHash ? { quote_hash: quoteHash, fingerprint } : undefined);
+        }
+        // Only an unknown or transient result may resume an attempt. A server
+        // refusal with retryable:false is terminal and must receive a new key.
+        const transient = error instanceof client_1.CliError && (error.code === 'request_timeout' || error.code === 'network_error' || error.retryable === true || error.status >= 500);
+        if (attemptIdentity && !transient)
+            await (0, idempotency_1.finishIdempotencyAttempt)(idempotencyPath, attemptIdentity);
+        throw error;
+    }
+    if (!input.turnToken) {
+        if (body.mode === 'dry_run' && turnToken) {
+            const quote = quoteFromResult(result);
+            await (0, turnCache_1.rememberTurnToken)(context.turnsPath, context.baseUrl, context.turnKey, capabilityId, turnToken, Date.now(), warnTurnCache, quote ? { quote_hash: quote.quote_hash, fingerprint } : undefined);
+        }
+        else if (pending || ranDryRun)
+            await (0, turnCache_1.forgetTurnToken)(context.turnsPath, context.baseUrl, context.turnKey, capabilityId, warnTurnCache);
+    }
+    let timedOut = false;
+    if (!input.noWait && !(0, runWait_1.columnRunReturnsRunId)(capabilityId)) {
+        const waited = await (0, runWait_1.waitForRun)(client, result, input.waitTimeout, context.sleep);
+        result = waited.value;
+        timedOut = waited.timedOut;
+    }
+    // A run still active after waiting has unknown outcome; retain its key for
+    // the read-back/retry rule. A terminal response completes this attempt.
+    if (attemptIdentity && !timedOut)
+        await (0, idempotency_1.finishIdempotencyAttempt)(idempotencyPath, attemptIdentity);
+    return { value: withIdempotencyMeta(result, explicitKey ? null : sentKey), timedOut, idempotencyKey: sentKey, turnToken: turnToken ?? null };
+}
+/** A read the CLI needs before it can form a write, run through the same gate as any other run. */
+async function readCapability(context, capabilityId, params, waitTimeout) {
+    const outcome = await runGated(context, { capabilityId, body: { params }, waitTimeout });
+    return outcome.value;
+}

package/dist/idempotency.d.ts

@@ -0,0 +1,38 @@
+/** A key-sorted JSON string, so two spellings of one input fingerprint alike. */
+export declare function stableJson(value: unknown): string;
+export interface IdempotencyIdentity {
+    /** What the key is for: a capability id, or a control such as runs.cancel. */
+    scope: string;
+    /** Workspace the command acts in; the same body in another workspace is another command. */
+    workspace?: string | null;
+    /** The request body that will be sent (params, mode, max_credits, quote_hash, approved ...). */
+    body: unknown;
+}
+export declare function pendingIdempotencyPath(credentialsPath: string): string;
+/**
+ * Deterministic idempotency key for one logical command.
+ *
+ * A random key per invocation made a re-run after a timeout a brand new
+ * operation: the server could not replay the first attempt, so a write whose
+ * response was lost ran twice. The key is now a digest of the capability, the
+ * canonical request body and the workspace, so running the same command again
+ * presents the same key and the server replays. A key the caller names with
+ * --idempotency-key is used as given and never reaches this function.
+ *
+ * Because the whole body is hashed, a changed input, ceiling, mode, quote or
+ * approval flag is a different command with a different key. That is the same
+ * rule the server applies when it refuses a reused key with a different body
+ * (idempotency_key_reuse), so a deliberate change can never collide with an
+ * earlier attempt.
+ */
+export declare function idempotencyDigest(identity: IdempotencyIdentity): string;
+/**
+ * Request digest, not a durable command key. A terminal attempt removes its
+ * entry; only an interrupted or transient attempt is resumed with this key.
+ */
+export declare function deterministicIdempotencyKey(identity: IdempotencyIdentity): string;
+/** Gets a fresh attempt key, or resumes only a pending attempt for this digest. */
+export declare function pendingIdempotencyKey(path: string, identity: IdempotencyIdentity): Promise<string>;
+/** A success or definitive refusal finishes an attempt; a transient outcome keeps it resumable. */
+export declare function finishIdempotencyAttempt(path: string, identity: IdempotencyIdentity): Promise<void>;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAIA,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOjD;AASD,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gGAAgG;IAChG,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAavE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAEjF;AAqBD,mFAAmF;AACnF,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CASxG;AAED,mGAAmG;AACnG,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzG"}