@trydreamstate/cli 1.3.3 → 1.3.5

package/dist/gatedRun.js

@@ -1,14 +1,13 @@
 "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.refusalFromRunResult = refusalFromRunResult;
 exports.readCapability = readCapability;
 const node_crypto_1 = require("node:crypto");
 const client_1 = require("./client");
@@ -17,6 +16,9 @@ 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
@@ -32,43 +34,12 @@ function code(error) {
         ? error.code
         : undefined;
 }
-function toolTurnToken(value) {
+function optionalToolTurnToken(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);
+    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) {
@@ -138,7 +109,6 @@ function cliSurfaceRefusal(capabilityId, fetched) {
         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.
@@ -164,7 +134,7 @@ function quoteFromResult(value, depth = 0) {
         return null;
     }
     const entry = value;
-    if (typeof entry.quote_hash === 'string' && QUOTE_HASH_PATTERN.test(entry.quote_hash)) {
+    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,
@@ -178,11 +148,103 @@ function quoteFromResult(value, depth = 0) {
     }
     return null;
 }
-function quoteSummary(capabilityId, body, quote) {
+function quotePriced(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.`;
+    return `Dry run of ${capabilityId} priced: ${rows}, ${credits}.`;
+}
+/** A known price of 0 spends nothing. An unknown price or a positive price is sent only after the caller passes the approval flag. */
+function spendNeedsApproval(maximum, approved) {
+    if (approved)
+        return false;
+    if (maximum === 0)
+        return false;
+    return true;
+}
+const CREDENTIALS_REQUIRED_SENTENCE = 'A connected credential is required before this run can continue.';
+function readinessRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function blockerSentence(blocker) {
+    if (typeof blocker === 'string' && blocker.trim())
+        return blocker.trim();
+    const record = readinessRecord(blocker);
+    const message = record?.message;
+    return typeof message === 'string' && message.trim() ? message.trim() : null;
+}
+function blockerCodeOf(blocker) {
+    const record = readinessRecord(blocker);
+    const code = record?.code;
+    return typeof code === 'string' && /^[a-z][a-z0-9_]*$/.test(code) ? code : null;
+}
+/**
+ * HTTP 200 can still be a refusal: smoke and dry_run succeed without spending
+ * and attach run_blockers or readiness.blockers. Only those top-level buckets
+ * count. A row skip_reason is not a refusal of the command.
+ */
+function readinessRefusal(value) {
+    const root = readinessRecord(value);
+    const data = readinessRecord(root?.data) ?? root;
+    if (!data)
+        return null;
+    const run = readinessRecord(data.run);
+    const outputs = readinessRecord(run?.outputs);
+    const buckets = [];
+    const states = [];
+    const take = (readiness) => {
+        if (!readiness)
+            return;
+        if (Array.isArray(readiness.blockers))
+            buckets.push(...readiness.blockers);
+        if (typeof readiness.state === 'string')
+            states.push(readiness.state);
+    };
+    // Dry runs put readiness on run.outputs. Durable and polled runs put the
+    // same object on run.steps[].outputs. A blocked rehearsal is an array of
+    // { status:'blocked', blocked_by, next_action }, not { blockers, state }.
+    const absorbSurface = (surface) => {
+        if (!surface)
+            return;
+        if (Array.isArray(surface.run_blockers))
+            buckets.push(...surface.run_blockers);
+        absorbReadiness(surface.readiness);
+    };
+    const absorbReadiness = (readiness) => {
+        if (Array.isArray(readiness)) {
+            for (const entry of readiness) {
+                const row = readinessRecord(entry);
+                if (!row || row.status !== 'blocked')
+                    continue;
+                const blockedBy = Array.isArray(row.blocked_by)
+                    ? row.blocked_by.filter((item) => typeof item === 'string' && /^[a-z][a-z0-9_]*$/.test(item))
+                    : [];
+                const nextAction = typeof row.next_action === 'string' && row.next_action.trim() ? row.next_action.trim() : null;
+                const message = typeof row.message === 'string' && row.message.trim() ? row.message.trim() : null;
+                buckets.push({
+                    ...(blockedBy[0] ? { code: blockedBy[0] } : {}),
+                    message: nextAction ?? message ?? 'This run is blocked until the workspace is ready.',
+                });
+            }
+            return;
+        }
+        take(readinessRecord(readiness));
+    };
+    absorbSurface(outputs);
+    if (Array.isArray(run?.steps)) {
+        for (const step of run.steps)
+            absorbSurface(readinessRecord(readinessRecord(step)?.outputs));
+    }
+    absorbReadiness(run?.readiness);
+    absorbReadiness(data.readiness);
+    const codes = buckets.map(blockerCodeOf).filter((code) => Boolean(code));
+    const sentences = buckets.map(blockerSentence).filter((sentence) => Boolean(sentence));
+    const credentials = codes.includes('credentials_required') || states.includes('credentials_required');
+    if (!credentials && codes.length === 0 && sentences.length === 0)
+        return null;
+    const sentence = sentences[0] ?? (credentials ? CREDENTIALS_REQUIRED_SENTENCE : 'This run is blocked until the workspace is ready.');
+    const code = credentials ? 'credentials_required' : codes[0] ?? 'not_ready';
+    return new client_1.CliError(sentence, code, 409, { retryable: false });
 }
 /** Adds the idempotency key to the printed meta, so a user can see which key to re-run with. */
 function withIdempotencyMeta(value, key) {
@@ -230,28 +292,38 @@ async function runGated(context, 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';
-    const inlineRead = !input.turnToken && !pending && !input.idempotencyKey && omitsToolTurnForInlineTableRead(capabilityId);
-    if (!input.turnToken && !pending && !inlineRead)
+    // --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;
-    let turnToken = input.turnToken ?? pending ?? (inlineRead ? undefined : toolTurnToken(fetched));
+    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'
+    const explicitQuote = typeof body.quote_hash === 'string';
+    let quoteHash = explicitQuote
         ? body.quote_hash
         : live ? cached?.quote_hash ?? undefined : undefined;
-    const explicitKey = parameterIdempotencyKey(body) ?? input.idempotencyKey;
-    let recoveredInlineRead = false;
+    // null means the price was not stated (or the flag named a hash with no ceiling).
+    let quotedMaximum = !explicitQuote && cached?.quote_hash ? cached.maximum_credits : undefined;
     let ranDryRun = false;
     let sentKey = null;
+    const approvalRequired = () => new client_1.CliError('This run spends credits. Rerun the same command with --approved.', 'approval_required', 409, { retryable: false, repair: { kind: 'ask_user', hint: 'Rerun the same command with --approved.' } });
     const requestBody = () => ({
         ...body,
         ...(turnToken ? { tool_turn_token: turnToken } : {}),
@@ -284,16 +356,27 @@ async function runGated(context, input) {
     let result;
     try {
         try {
+            if (live && quoteHash) {
+                const maximum = explicitQuote ? null : quotedMaximum ?? null;
+                if (spendNeedsApproval(maximum, body.approved === true)) {
+                    stderr.write(`${quotePriced(capabilityId, body, { quote_hash: quoteHash, maximum_credits: maximum })}\n`);
+                    throw approvalRequired();
+                }
+                if (body.approved === true || maximum === 0) {
+                    stderr.write(`${quotePriced(capabilityId, body, { quote_hash: quoteHash, maximum_credits: maximum })}\nRunning live on that quote.\n`);
+                }
+            }
             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;
+            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);
-                turnToken = toolTurnToken(fetched);
+                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) {
@@ -318,8 +401,12 @@ async function runGated(context, input) {
                 }
                 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 });
+                quotedMaximum = quote.maximum_credits;
+                stderr.write(`${quotePriced(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, maximum_credits: quote.maximum_credits });
+                if (spendNeedsApproval(quote.maximum_credits, body.approved === true))
+                    throw approvalRequired();
+                stderr.write('Running live on that quote.\n');
                 result = await run();
             }
             else {
@@ -334,7 +421,7 @@ async function runGated(context, input) {
             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);
+            await (0, turnCache_1.rememberTurnToken)(context.turnsPath, context.baseUrl, context.turnKey, capabilityId, turnToken, Date.now(), warnTurnCache, quoteHash ? { quote_hash: quoteHash, fingerprint, ...(quotedMaximum !== undefined ? { maximum_credits: quotedMaximum } : {}) } : 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.
@@ -346,23 +433,33 @@ async function runGated(context, input) {
     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);
+            await (0, turnCache_1.rememberTurnToken)(context.turnsPath, context.baseUrl, context.turnKey, capabilityId, turnToken, Date.now(), warnTurnCache, quote ? { quote_hash: quote.quote_hash, fingerprint, maximum_credits: quote.maximum_credits } : 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)) {
+    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 timeout still owns the quote and the idempotency key. Forgetting the
+    // turn here made the rerun hash a body with no quote_hash and start a second run.
+    if (!input.turnToken && body.mode !== 'dry_run' && (pending || ranDryRun) && !timedOut) {
+        await (0, turnCache_1.forgetTurnToken)(context.turnsPath, context.baseUrl, context.turnKey, capabilityId, warnTurnCache);
+    }
     // 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);
+    const blocked = readinessRefusal(result);
+    if (blocked)
+        throw blocked;
     return { value: withIdempotencyMeta(result, explicitKey ? null : sentKey), timedOut, idempotencyKey: sentKey, turnToken: turnToken ?? null };
 }
+/** Blocker refusal for a run envelope that did not go through runGated (runs wait). */
+function refusalFromRunResult(value) {
+    return readinessRefusal(value);
+}
 /** 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 });