@trydreamstate/cli 1.3.2 → 1.3.4

package/dist/errors.js

@@ -0,0 +1,84 @@
+"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.isApprovalRepair = isApprovalRepair;
+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 repair.kind ask_user (a person must decide),
+ * 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_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_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.' },
+};
+function isApprovalRepair(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const repair = error.repair;
+    if (!repair || typeof repair !== 'object')
+        return false;
+    const kind = repair.kind;
+    return kind === 'ask_user';
+}
+/**
+ * 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,79 @@
+import { CliError, type DreamstateClient } from './client';
+import { type IdempotencyIdentity } from './idempotency';
+export declare function code(error: unknown): string | undefined;
+/** 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":"AACA,OAAO,EAAE,QAAQ,EAA0B,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEnF,OAAO,EAA4F,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAoBnJ,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIvD;AAUD,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAKjF;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,CAKrI;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAKzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAazF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAMrE;AAoCD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,KAAK,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzH;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qGAAqG;IACrG,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AASD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAsKvG;AAED,mGAAmG;AACnG,wBAAsB,cAAc,CAClC,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/gatedRun.js

@@ -0,0 +1,346 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.code = code;
+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");
+const capabilityPosture_1 = require("./capabilityPosture");
+const registryManifest_1 = require("./registryManifest");
+const runContract_1 = require("./runContract");
+/**
+ * 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 optionalToolTurnToken(value) {
+    const root = value && typeof value === 'object' ? value : {};
+    const data = root.data && typeof root.data === 'object' ? root.data : {};
+    return typeof data.tool_turn_token === 'string' && data.tool_turn_token.trim()
+        ? data.tool_turn_token
+        : undefined;
+}
+/** 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 });
+}
+/**
+ * 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' && runContract_1.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 explicitKey = parameterIdempotencyKey(body) ?? input.idempotencyKey;
+    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';
+    // --turn-token is the contract. Do not fetch tools get to invent one.
+    // A cached inline read also skips the fetch until registry_hash changes.
+    const cachedPosture = input.turnToken ? null : (0, registryManifest_1.lookupPosture)(capabilityId);
+    const inlineFromCache = !input.turnToken && !pending && !explicitKey && cachedPosture?.inlineRead === true;
+    if (!input.turnToken && !pending && !inlineFromCache)
+        await contract();
+    const posture = fetched ? (0, capabilityPosture_1.postureFromContract)(fetched) : cachedPosture;
+    if (fetched && posture)
+        (0, registryManifest_1.rememberPosture)(capabilityId, posture);
+    const refusal = fetched ? cliSurfaceRefusal(capabilityId, fetched) : null;
+    if (refusal)
+        throw refusal;
+    const inlineRead = !input.turnToken && !pending && !explicitKey && posture?.inlineRead === true;
+    let turnToken = input.turnToken ?? pending ?? (inlineRead ? undefined : optionalToolTurnToken(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;
+    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) {
+            if (!input.turnToken && code(error) === 'capability_not_fetched') {
+                // Capability posture can change between tools get and run. Refresh it
+                // once rather than maintaining a client-side list of token-free reads.
+                fetched = await client.getTool(capabilityId);
+                const refreshed = (0, capabilityPosture_1.postureFromContract)(fetched);
+                // The server just required a turn token, so this id is not an inline read.
+                (0, registryManifest_1.rememberPosture)(capabilityId, { ...refreshed, inlineRead: false });
+                turnToken = optionalToolTurnToken(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 && !posture?.returnsRunId) {
+        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;
+}