@trydreamstate/cli 1.3.2 → 1.3.3

package/dist/tableFileReader.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_IMPORT_FILE_BYTES = void 0;
+exports.stagingHeaderKeys = stagingHeaderKeys;
+exports.readLocalTableFile = readLocalTableFile;
+const promises_1 = require("node:fs/promises");
+const tableFilePreview_1 = require("./tableFilePreview");
+/** Largest file an import reads into memory. The server caps one upload at 200,000 rows. */
+exports.MAX_IMPORT_FILE_BYTES = 250_000_000;
+/**
+ * Duplicate CSV labels cannot be object keys twice, so they get private
+ * staging keys; the column definitions keep the labels. Same rule as
+ * csvStagingHeaderKeys in packages/types (the server's own parser), pinned by
+ * tableFileReader.test.ts against that function.
+ */
+function stagingHeaderKeys(headers) {
+    const counts = new Map();
+    for (const header of headers)
+        counts.set(header, (counts.get(header) ?? 0) + 1);
+    const reserved = new Set(headers);
+    const used = new Set();
+    return headers.map((header, index) => {
+        let key = counts.get(header) === 1 ? header : `__csv_column_${index + 1}`;
+        while (used.has(key) || (key !== header && reserved.has(key)))
+            key = `${key}_`;
+        used.add(key);
+        return key;
+    });
+}
+function tabularString(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return JSON.stringify(value);
+}
+function fromGrid(kind, grid) {
+    const [rawHeaders, ...dataRows] = grid;
+    const headers = (rawHeaders ?? []).map((value) => value.trim());
+    if (headers.length === 0 || headers.every((header) => header.length === 0))
+        throw new Error('File has no header row');
+    const stagingHeaders = stagingHeaderKeys(headers);
+    return {
+        file_kind: kind,
+        headers,
+        rows: dataRows
+            .filter((values) => values.some(Boolean))
+            .map((values, index) => ({
+            source_row_number: index + 2,
+            data: Object.fromEntries(stagingHeaders.map((header, column) => [header, values[column] ?? ''])),
+        })),
+    };
+}
+function fromObjects(kind, records) {
+    if (!records.every((row) => row && typeof row === 'object' && !Array.isArray(row))) {
+        throw new Error('JSON import must contain only object rows');
+    }
+    const headers = [...new Set(records.flatMap((row) => Object.keys(row)))];
+    return {
+        file_kind: kind,
+        headers,
+        rows: records.map((row, index) => ({
+            source_row_number: index + 1,
+            data: Object.fromEntries(headers.map((header) => [header, tabularString(row[header])])),
+        })),
+    };
+}
+/** Every row of a local CSV, JSON, JSONL or XLSX file, shaped for csv_upload_stage. */
+async function readLocalTableFile(filePath, format) {
+    const kind = (0, tableFilePreview_1.inferLocalTableFileKind)(filePath, format);
+    const bytes = await (0, promises_1.readFile)(filePath);
+    if (bytes.length > exports.MAX_IMPORT_FILE_BYTES)
+        throw new Error(`File is larger than ${exports.MAX_IMPORT_FILE_BYTES / 1_000_000}MB; split it before importing.`);
+    if (kind === 'xlsx')
+        return { file: fromGrid('xlsx', (0, tableFilePreview_1.readXlsxRows)(bytes, null).rows), bytes };
+    const text = bytes.toString('utf8').replace(/^/, '');
+    if (kind === 'json') {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            throw new Error(`JSON import could not parse the file: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (Array.isArray(parsed))
+            return { file: fromObjects('json', parsed), bytes };
+        if (parsed && typeof parsed === 'object')
+            return { file: fromObjects('json', [parsed]), bytes };
+        throw new Error('JSON import expects an object or an array of objects');
+    }
+    if (kind === 'jsonl') {
+        const records = text.split(/\r?\n/).filter((line) => line.trim()).map((line, index) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                throw new Error(`JSONL line ${index + 1} is not valid JSON`);
+            }
+        });
+        return { file: fromObjects('jsonl', records), bytes };
+    }
+    const parsed = (0, tableFilePreview_1.parseCsv)(text);
+    if (parsed.unterminatedQuote)
+        throw new Error('CSV contains an unterminated quoted field');
+    return { file: fromGrid('csv', parsed.rows), bytes };
+}

package/dist/tablesImport.d.ts

@@ -0,0 +1,57 @@
+import { type GatedRunContext } from './gatedRun';
+/**
+ * `dreamstate tables import`: the real import. The old command ran
+ * tables.table_sources.csv_import_prepare, which only returns the text of a
+ * CLI command, and printed it: nothing was ever uploaded. This follows the
+ * lifecycle the web app uses (apps/frontend/src/components/worksheet/
+ * CsvSourceUploadPanel.tsx), one capability per step, through the same door:
+ *
+ *   csv_upload_create  open an upload receipt from the header row
+ *   csv_upload_map     choose which header feeds which field, and the identity column
+ *   csv_upload_stage   send the rows in chunks of at most 5,000
+ *   csv_upload_attach  turn the upload into a live source.csv source
+ *   csv_upload_land_chunk  land staged rows as worksheet rows until done
+ *
+ * Wire shapes come from packages/types/src/tableApi.ts (csvUploadCreate ...
+ * csvUploadLandChunkOutput) and the server dispatch in tableCanonicalApiService.ts.
+ */
+export declare const STAGE_CHUNK_ROWS = 5000;
+/** One staged chunk stays under this size on the wire, whatever the row count. */
+export declare const STAGE_CHUNK_BYTES = 8000000;
+/** Matches DEFAULT_LAND_CHUNK in csvSourceUpload.ts and the web app. */
+export declare const LAND_CHUNK_ROWS = 250;
+/** csvSourceUpload.ts MAX_ROWS_PER_UPLOAD. Refused here before any request. */
+export declare const MAX_ROWS_PER_UPLOAD = 200000;
+export interface TablesImportOptions {
+    tableId: string;
+    file: string;
+    format?: 'csv' | 'json' | 'jsonl' | 'xlsx';
+    upsertKey?: string;
+    rowKind?: 'person' | 'company';
+    keepUnmappedColumns?: boolean;
+}
+export interface TablesImportResult {
+    table_id: string;
+    upload_id: string;
+    source_id: string;
+    file_name: string;
+    file_kind: string;
+    row_kind: 'person' | 'company';
+    rows_total: number;
+    rows_staged: number;
+    rows_landed: number;
+    rows_skipped: number;
+    mapping: Record<string, string>;
+    identity_column: string;
+    land_calls: number;
+}
+/**
+ * The outputs of a capability run, whichever envelope nesting the door used. A
+ * run that ended failed answers HTTP 200 with the failure in the run, so it is
+ * raised here as an error: an import must never read a failed step as success.
+ */
+export declare function capabilityOutputs(result: unknown): Record<string, unknown>;
+/** Header the rows are matched on across re-imports. An explicit --upsert-key wins; otherwise the strongest mapped field. */
+export declare function chooseIdentityColumn(headers: readonly string[], mapping: Readonly<Record<string, string>>, rowKind: 'person' | 'company'): string | null;
+export declare function importLocalTable(context: GatedRunContext, options: TablesImportOptions): Promise<TablesImportResult>;
+//# sourceMappingURL=tablesImport.d.ts.map

package/dist/tablesImport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tablesImport.d.ts","sourceRoot":"","sources":["../src/tablesImport.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlE;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AACtC,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAC3C,wEAAwE;AACxE,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,SAAU,CAAC;AAY3C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC/B,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoB1E;AAMD,6HAA6H;AAC7H,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACzC,OAAO,EAAE,QAAQ,GAAG,SAAS,GAC5B,MAAM,GAAG,IAAI,CAMf;AAkCD,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiJ1H"}

package/dist/tablesImport.js

@@ -0,0 +1,263 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ROWS_PER_UPLOAD = exports.LAND_CHUNK_ROWS = exports.STAGE_CHUNK_BYTES = exports.STAGE_CHUNK_ROWS = void 0;
+exports.capabilityOutputs = capabilityOutputs;
+exports.chooseIdentityColumn = chooseIdentityColumn;
+exports.importLocalTable = importLocalTable;
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const client_1 = require("./client");
+const errors_1 = require("./errors");
+const gatedRun_1 = require("./gatedRun");
+const idempotency_1 = require("./idempotency");
+const tableFileReader_1 = require("./tableFileReader");
+/**
+ * `dreamstate tables import`: the real import. The old command ran
+ * tables.table_sources.csv_import_prepare, which only returns the text of a
+ * CLI command, and printed it: nothing was ever uploaded. This follows the
+ * lifecycle the web app uses (apps/frontend/src/components/worksheet/
+ * CsvSourceUploadPanel.tsx), one capability per step, through the same door:
+ *
+ *   csv_upload_create  open an upload receipt from the header row
+ *   csv_upload_map     choose which header feeds which field, and the identity column
+ *   csv_upload_stage   send the rows in chunks of at most 5,000
+ *   csv_upload_attach  turn the upload into a live source.csv source
+ *   csv_upload_land_chunk  land staged rows as worksheet rows until done
+ *
+ * Wire shapes come from packages/types/src/tableApi.ts (csvUploadCreate ...
+ * csvUploadLandChunkOutput) and the server dispatch in tableCanonicalApiService.ts.
+ */
+exports.STAGE_CHUNK_ROWS = 5_000;
+/** One staged chunk stays under this size on the wire, whatever the row count. */
+exports.STAGE_CHUNK_BYTES = 8_000_000;
+/** Matches DEFAULT_LAND_CHUNK in csvSourceUpload.ts and the web app. */
+exports.LAND_CHUNK_ROWS = 250;
+/** csvSourceUpload.ts MAX_ROWS_PER_UPLOAD. Refused here before any request. */
+exports.MAX_ROWS_PER_UPLOAD = 200_000;
+const MAX_HEADERS = 200;
+/** The server's turn lives 10 minutes; stay well inside it. */
+const TURN_REUSE_WINDOW_MS = 8 * 60_000;
+/** A land loop that never reports done is a server fault, not a file this size. */
+const MAX_LAND_CALLS = 10_000;
+const IDENTITY_PREFERENCE = {
+    person: ['email', 'linkedin_url', 'external_id'],
+    company: ['domain', 'linkedin_url', 'external_id'],
+};
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+const FAILED_STATUSES = new Set(['failed', 'cancelled', 'canceled', 'timed_out', 'rejected']);
+/**
+ * The outputs of a capability run, whichever envelope nesting the door used. A
+ * run that ended failed answers HTTP 200 with the failure in the run, so it is
+ * raised here as an error: an import must never read a failed step as success.
+ */
+function capabilityOutputs(result) {
+    const data = record(record(result)?.data);
+    const run = record(data?.run);
+    if (run) {
+        const steps = Array.isArray(run.steps) ? run.steps : Array.isArray(run.completed) ? run.completed : [];
+        const stepError = steps.map((step) => record(record(step)?.user_error)).find(Boolean) ?? record(run.user_error);
+        if (typeof run.status === 'string' && FAILED_STATUSES.has(run.status)) {
+            throw new client_1.CliError(typeof stepError?.message === 'string' ? stepError.message : `The run ${run.status}.`, typeof stepError?.code === 'string' ? stepError.code : 'run_failed', 0, { details: stepError ? { user_error: stepError } : undefined, retryable: false });
+        }
+        const outputs = steps.map((step) => record(record(step)?.outputs)).find(Boolean);
+        if (outputs)
+            return outputs;
+        const direct = record(run.outputs);
+        if (direct)
+            return direct;
+    }
+    return record(data?.outputs) ?? data ?? {};
+}
+function importIdentity(parts) {
+    return (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 24);
+}
+/** Header the rows are matched on across re-imports. An explicit --upsert-key wins; otherwise the strongest mapped field. */
+function chooseIdentityColumn(headers, mapping, rowKind) {
+    for (const field of IDENTITY_PREFERENCE[rowKind]) {
+        const header = headers.find((candidate) => mapping[candidate] === field);
+        if (header)
+            return header;
+    }
+    return headers.find((header) => mapping[header]) ?? null;
+}
+function chunkRows(rows) {
+    const chunks = [];
+    let current = [];
+    let bytes = 0;
+    for (const row of rows) {
+        const size = JSON.stringify(row).length;
+        if (current.length && (current.length >= exports.STAGE_CHUNK_ROWS || bytes + size > exports.STAGE_CHUNK_BYTES)) {
+            chunks.push(current);
+            current = [];
+            bytes = 0;
+        }
+        current.push(row);
+        bytes += size;
+    }
+    if (current.length)
+        chunks.push(current);
+    return chunks;
+}
+function withStep(error, step, uploadId) {
+    if (!(error instanceof client_1.CliError))
+        return error;
+    const details = record(error.details) ?? {};
+    return new client_1.CliError(error.message, error.code, error.status, {
+        details: { ...details, import_step: step, ...(uploadId ? { upload_id: uploadId } : {}) },
+        ...(error.retryAfter === undefined ? {} : { retryAfter: error.retryAfter }),
+        ...(error.traceId === undefined ? {} : { traceId: error.traceId }),
+        ...(error.idempotencyKey === undefined ? {} : { idempotencyKey: error.idempotencyKey }),
+        ...(error.retryable === undefined ? {} : { retryable: error.retryable }),
+        ...(error.repair === undefined ? {} : { repair: error.repair }),
+        ...(error.meta === undefined ? {} : { meta: error.meta }),
+    });
+}
+async function importLocalTable(context, options) {
+    const rowKind = options.rowKind ?? 'person';
+    let parsed;
+    try {
+        parsed = await (0, tableFileReader_1.readLocalTableFile)(options.file, options.format);
+    }
+    catch (error) {
+        throw new errors_1.CliUsageError(error instanceof Error ? error.message : String(error));
+    }
+    const { file, bytes } = parsed;
+    if (file.rows.length === 0)
+        throw new errors_1.CliUsageError('The file has a header row but no data rows; nothing to import.');
+    if (file.rows.length > exports.MAX_ROWS_PER_UPLOAD) {
+        throw new errors_1.CliUsageError(`The file has ${file.rows.length} rows; one upload takes at most ${exports.MAX_ROWS_PER_UPLOAD}. Split it and import the parts.`);
+    }
+    if (file.headers.length > MAX_HEADERS)
+        throw new errors_1.CliUsageError(`The file has ${file.headers.length} columns; one upload takes at most ${MAX_HEADERS}.`);
+    const blank = file.headers.findIndex((header) => !header);
+    if (blank >= 0)
+        throw new errors_1.CliUsageError(`Column ${blank + 1} has no header name. Name every column before importing.`);
+    const fileName = (0, node_path_1.basename)(options.file);
+    const keepUnmappedColumns = options.keepUnmappedColumns !== false;
+    const importId = importIdentity({
+        table_id: options.tableId,
+        sha256: (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex'),
+        file_name: fileName,
+        row_kind: rowKind,
+        keep_unmapped_columns: keepUnmappedColumns,
+        upsert_key: options.upsertKey ?? null,
+    });
+    const key = (...parts) => (0, idempotency_1.deterministicIdempotencyKey)({
+        scope: 'tables.import',
+        workspace: context.workspace,
+        body: { import_id: importId, step: parts },
+    });
+    // Landing makes hundreds of calls to one capability. One tools get per
+    // capability mints the turn; later calls reuse it inside the server's window.
+    const turns = new Map();
+    const step = async (capabilityId, params, idempotencyKey, stepName, uploadId) => {
+        const run = async (reuse) => {
+            const turn = turns.get(capabilityId);
+            return (0, gatedRun_1.runGated)(context, {
+                capabilityId,
+                body: { params, mode: 'live' },
+                idempotencyKey,
+                waitTimeout: 120,
+                ...(reuse && turn && Date.now() - turn.at < TURN_REUSE_WINDOW_MS ? { turnToken: turn.token } : {}),
+            });
+        };
+        try {
+            let outcome;
+            try {
+                outcome = await run(true);
+            }
+            catch (error) {
+                if ((0, gatedRun_1.code)(error) !== 'tool_turn_expired' && (0, gatedRun_1.code)(error) !== 'capability_not_fetched')
+                    throw error;
+                turns.delete(capabilityId);
+                outcome = await run(false);
+            }
+            if (outcome.turnToken && !turns.has(capabilityId))
+                turns.set(capabilityId, { token: outcome.turnToken, at: Date.now() });
+            return capabilityOutputs(outcome.value);
+        }
+        catch (error) {
+            throw withStep(error, stepName, uploadId);
+        }
+    };
+    const progress = (message) => context.stderr.write(`${message}\n`);
+    progress(`Importing ${file.rows.length} rows from ${fileName} into ${options.tableId}.`);
+    const created = await step('tables.table_sources.csv_upload_create', {
+        table_id: options.tableId,
+        file_name: fileName,
+        headers: file.headers,
+        row_kind: rowKind,
+        keep_unmapped_columns: keepUnmappedColumns,
+    }, key('create'), 'create', null);
+    const uploadId = typeof created.upload_id === 'string' ? created.upload_id : null;
+    if (!uploadId)
+        throw new client_1.CliError('csv_upload_create returned no upload_id.', 'invalid_response', 0, { details: { import_step: 'create' } });
+    const mapping = { ...(record(created.suggested_mapping) ?? {}) };
+    if (options.upsertKey) {
+        if (!file.headers.includes(options.upsertKey)) {
+            throw new errors_1.CliUsageError(`--upsert-key "${options.upsertKey}" is not a column of ${fileName}. Columns: ${file.headers.join(', ')}.`);
+        }
+        if (!mapping[options.upsertKey]) {
+            if (Object.values(mapping).includes('external_id')) {
+                throw new errors_1.CliUsageError(`--upsert-key "${options.upsertKey}" is not mapped to a field and external_id is already used by another column. Rename the key column to a mappable name (email, linkedin_url, external_id).`);
+            }
+            mapping[options.upsertKey] = 'external_id';
+        }
+    }
+    const identityColumn = options.upsertKey ?? chooseIdentityColumn(file.headers, mapping, rowKind);
+    if (!identityColumn || Object.keys(mapping).length === 0) {
+        throw new errors_1.CliUsageError(`No column of ${fileName} could be matched to an identity field (email, linkedin_url, external_id${rowKind === 'company' ? ', domain' : ''}). The upload ${uploadId} was opened and stays unattached. Pass --upsert-key <column> to choose the identity column.`);
+    }
+    await step('tables.table_sources.csv_upload_map', {
+        upload_id: uploadId, mapping, identity_column: identityColumn,
+    }, key(uploadId, 'map'), 'map', uploadId);
+    const chunks = chunkRows(file.rows);
+    let staged = 0;
+    for (const [index, rows] of chunks.entries()) {
+        const result = await step('tables.table_sources.csv_upload_stage', { upload_id: uploadId, rows }, key(uploadId, 'stage', index), 'stage', uploadId);
+        staged += typeof result.staged === 'number' ? result.staged : rows.length;
+        progress(`Staged ${staged} of ${file.rows.length} rows.`);
+    }
+    const attached = await step('tables.table_sources.csv_upload_attach', {
+        table_id: options.tableId, upload_id: uploadId, source_label: fileName,
+    }, key(uploadId, 'attach'), 'attach', uploadId);
+    const sourceId = typeof attached.source_id === 'string' ? attached.source_id : null;
+    if (!sourceId)
+        throw new client_1.CliError('csv_upload_attach returned no source_id.', 'invalid_response', 0, { details: { import_step: 'attach', upload_id: uploadId } });
+    let landed = 0;
+    let skipped = 0;
+    let calls = 0;
+    for (;;) {
+        if (calls >= MAX_LAND_CALLS) {
+            throw new client_1.CliError(`Landing did not finish after ${MAX_LAND_CALLS} calls.`, 'run_failed', 0, { details: { import_step: 'land', upload_id: uploadId, source_id: sourceId } });
+        }
+        const chunk = await step('tables.table_sources.csv_upload_land_chunk', {
+            table_id: options.tableId, upload_id: uploadId, limit: exports.LAND_CHUNK_ROWS,
+        }, key(uploadId, 'land', calls), 'land', uploadId);
+        calls += 1;
+        landed += typeof chunk.landed === 'number' ? chunk.landed : 0;
+        skipped += typeof chunk.skipped === 'number' ? chunk.skipped : 0;
+        progress(`Landed ${landed} rows, ${typeof chunk.remaining === 'number' ? chunk.remaining : '?'} remaining.`);
+        if (chunk.done === true)
+            break;
+    }
+    if (skipped > 0)
+        progress(`${skipped} rows had no ${identityColumn} value and were skipped.`);
+    return {
+        table_id: options.tableId,
+        upload_id: uploadId,
+        source_id: sourceId,
+        file_name: fileName,
+        file_kind: file.file_kind,
+        row_kind: rowKind,
+        rows_total: file.rows.length,
+        rows_staged: staged,
+        rows_landed: landed,
+        rows_skipped: skipped,
+        mapping,
+        identity_column: identityColumn,
+        land_calls: calls,
+    };
+}

package/dist/turnCache.d.ts

@@ -1,8 +1,21 @@
 export declare const TURN_REUSE_MS: number;
+/** The quote a dry run returned, and the exact input it priced. */
+export type CachedQuote = {
+    quote_hash: string;
+    fingerprint: string;
+};
 type CacheWarning = (error: NodeJS.ErrnoException) => void;
 export declare function turnCachePath(credentialsPath: string): string;
 export declare function reusableTurnToken(path: string, baseUrl: string, apiKey: string, capabilityId: string, now?: number, onWarning?: CacheWarning): Promise<string | null>;
-export declare function rememberTurnToken(path: string, baseUrl: string, apiKey: string, capabilityId: string, token: string, now?: number, onWarning?: CacheWarning): Promise<void>;
+/**
+ * The cached turn together with the quote its dry run returned. The quote is
+ * handed back only when `fingerprint` matches the input it was minted for.
+ */
+export declare function reusableTurn(path: string, baseUrl: string, apiKey: string, capabilityId: string, fingerprint: string, now?: number, onWarning?: CacheWarning): Promise<{
+    token: string;
+    quote_hash: string | null;
+} | null>;
+export declare function rememberTurnToken(path: string, baseUrl: string, apiKey: string, capabilityId: string, token: string, now?: number, onWarning?: CacheWarning, quote?: CachedQuote): Promise<void>;
 export declare function forgetTurnToken(path: string, baseUrl: string, apiKey: string, capabilityId: string, onWarning?: CacheWarning): Promise<void>;
 export {};
 //# sourceMappingURL=turnCache.d.ts.map

package/dist/turnCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turnCache.d.ts","sourceRoot":"","sources":["../src/turnCache.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,aAAa,QAAa,CAAC;AAGxC,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,KAAK,IAAI,CAAC;AAE3D,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAE7D;AA2BD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,SAAa,EAAE,SAAS,CAAC,EAAE,YAAY,GAC9G,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAa,EAAE,SAAS,CAAC,EAAE,YAAY,GAC7H,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,YAAY,GAC5F,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"turnCache.d.ts","sourceRoot":"","sources":["../src/turnCache.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,aAAa,QAAa,CAAC;AAExC,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAGtE,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,KAAK,IAAI,CAAC;AAE3D,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAE7D;AA2BD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,SAAa,EAAE,SAAS,CAAC,EAAE,YAAY,GAC9G,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,SAAa,EAAE,SAAS,CAAC,EAAE,YAAY,GACnI,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAAC,CAO9D;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAa,EAAE,SAAS,CAAC,EAAE,YAAY,EAC9H,KAAK,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,YAAY,GAC5F,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/turnCache.js

@@ -3,17 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TURN_REUSE_MS = void 0;
 exports.turnCachePath = turnCachePath;
 exports.reusableTurnToken = reusableTurnToken;
+exports.reusableTurn = reusableTurn;
 exports.rememberTurnToken = rememberTurnToken;
 exports.forgetTurnToken = forgetTurnToken;
 const node_crypto_1 = require("node:crypto");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
-// A paid capability's first live call is refused with quote_required and the
-// server binds a quote to that call's tool_turn_token. Only a rerun carrying
-// the SAME token can spend. Each CLI invocation is a new process, so fetching
-// a fresh token per run made every paid capability unrunnable from the CLI
-// (2026-09-23: tables.table_sources.run refused four times in a row), while
-// the refusal itself told the user the CLI reuses the turn for 10 minutes.
+// A paid capability's live call needs the quote_hash of a dry_run of the same
+// input, and the quote is bound to the dry run's tool_turn_token: only a live
+// call carrying the SAME token and that quote_hash can spend. Each CLI
+// invocation is a new process, so fetching a fresh token per run made every paid
+// capability unrunnable from the CLI (2026-09-23: tables.table_sources.run
+// refused four times in a row). The cache therefore keeps the dry run's turn
+// token together with its quote_hash and a fingerprint of the exact input that
+// was priced, so a later `--live` of the same input can echo it and a changed
+// input never inherits a price it was not shown.
 // The server turn lives 10 minutes; reuse for 9 so a cached token never
 // expires mid-request.
 exports.TURN_REUSE_MS = 9 * 60_000;
@@ -49,13 +53,26 @@ async function reusableTurnToken(path, baseUrl, apiKey, capabilityId, now = Date
     const entry = (await load(path, onWarning))[entryKey(baseUrl, apiKey, capabilityId)];
     return entry && typeof entry.token === 'string' && now - entry.at < exports.TURN_REUSE_MS ? entry.token : null;
 }
-async function rememberTurnToken(path, baseUrl, apiKey, capabilityId, token, now = Date.now(), onWarning) {
+/**
+ * The cached turn together with the quote its dry run returned. The quote is
+ * handed back only when `fingerprint` matches the input it was minted for.
+ */
+async function reusableTurn(path, baseUrl, apiKey, capabilityId, fingerprint, now = Date.now(), onWarning) {
+    const entry = (await load(path, onWarning))[entryKey(baseUrl, apiKey, capabilityId)];
+    if (!entry || typeof entry.token !== 'string' || now - entry.at >= exports.TURN_REUSE_MS)
+        return null;
+    const quote = entry.quote && entry.quote.fingerprint === fingerprint && typeof entry.quote.quote_hash === 'string'
+        ? entry.quote.quote_hash
+        : null;
+    return { token: entry.token, quote_hash: quote };
+}
+async function rememberTurnToken(path, baseUrl, apiKey, capabilityId, token, now = Date.now(), onWarning, quote) {
     const entries = await load(path, onWarning);
     for (const [key, entry] of Object.entries(entries)) {
         if (!entry || now - entry.at >= exports.TURN_REUSE_MS)
             delete entries[key];
     }
-    entries[entryKey(baseUrl, apiKey, capabilityId)] = { token, at: now };
+    entries[entryKey(baseUrl, apiKey, capabilityId)] = { token, at: now, ...(quote ? { quote } : {}) };
     await persist(path, entries, onWarning);
 }
 async function forgetTurnToken(path, baseUrl, apiKey, capabilityId, onWarning) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trydreamstate/cli",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "Live command-line client for the Dreamstate v1 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,11 +20,12 @@
   ],
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc && node scripts/build-agent-plugin.mjs",
-    "test": "npm run build && jest --config jest.config.cjs --runInBand",
+    "test": "node scripts/build-agent-plugin.mjs --check && npm run build && jest --config jest.config.cjs --runInBand",
     "type-check": "tsc --noEmit",
     "pack:check": "npm pack --dry-run",
     "pack:smoke": "npm run build && node scripts/pack-smoke.mjs",
     "prepublishOnly": "npm run build && npm run type-check && npm test",
+    "verify:guidance": "node scripts/build-agent-plugin.mjs --check",
     "verify:test-collection": "jest --config jest.config.cjs --runInBand --testNamePattern='^(?!)'",
     "plugin:publish": "bash scripts/publish-plugin-repo.sh"
   },