@squidcloud/cli 1.0.485 → 1.0.487

package/dist/index.js

@@ -32200,6 +32200,7 @@ exports.AI_PROVIDER_TYPES = [
     'voyage',
     'mistral',
     'textract',
+    'azure_document_intelligence',
     'vertex',
     'external', // This is a technicality, referring to user-defined providers.
 ];
@@ -32225,12 +32226,17 @@ exports.oL = ['gemini-3.1-pro', 'gemini-3.6-flash', 'gemini-3.5-flash-lite'];
  * Public Grok chat model names (active models only).
  * @category AI
  */
-exports.Kq = ['grok-4.3', 'grok-4-1-fast-reasoning', 'grok-4-1-fast-non-reasoning'];
+exports.Kq = ['grok-4.5', 'grok-4-1-fast-reasoning', 'grok-4-1-fast-non-reasoning'];
 /**
  * Public Anthropic chat model names (active models only).
  * @category AI
  */
-exports.xV = ['claude-haiku-4-5-20251001', 'claude-opus-5', 'claude-sonnet-5'];
+exports.xV = [
+    'claude-fable-5',
+    'claude-haiku-4-5-20251001',
+    'claude-opus-5',
+    'claude-sonnet-5',
+];
 /**
  * The supported AI model names.
  * @category AI
@@ -32737,7 +32743,7 @@ function getConsoleAppRegionByStage(stage) {
 var __webpack_unused_export__;
 
 __webpack_unused_export__ = ({ value: true });
-__webpack_unused_export__ = __webpack_unused_export__ = exports.MILLIS_PER_DAY = __webpack_unused_export__ = __webpack_unused_export__ = exports.MILLIS_PER_SECOND = exports.LW = exports.FN = exports.xz = exports.NG = exports.fA = void 0;
+__webpack_unused_export__ = __webpack_unused_export__ = exports.MILLIS_PER_DAY = __webpack_unused_export__ = exports.MILLIS_PER_MINUTE = exports.MILLIS_PER_SECOND = exports.LW = exports.FN = exports.xz = exports.NG = exports.fA = void 0;
 /** @internal */
 exports.fA = 60;
 /** @internal */
@@ -32751,7 +32757,7 @@ exports.LW = 30 * exports.xz;
 /** @internal */
 exports.MILLIS_PER_SECOND = 1000;
 /** @internal */
-__webpack_unused_export__ = exports.fA * exports.MILLIS_PER_SECOND;
+exports.MILLIS_PER_MINUTE = exports.fA * exports.MILLIS_PER_SECOND;
 /** @internal */
 __webpack_unused_export__ = exports.NG * exports.MILLIS_PER_SECOND;
 /** @internal */
@@ -33049,7 +33055,6 @@ exports.sQ = [
     'mutation',
     'native-query',
     'query',
-    'queue',
     // Note: every `/ws/*` WebSocket path is served by the TypeScript core (port 8000), never Kotlin.
 ];
 /**
@@ -34367,6 +34372,726 @@ async function initWebpack() {
 }
 
 
+/***/ },
+
+/***/ 2713
+(__unused_webpack_module, exports, __webpack_require__) {
+
+"use strict";
+
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.setupKbUploadCommand = setupKbUploadCommand;
+const assertic_1 = __webpack_require__(3205);
+const dotenv = __importStar(__webpack_require__(9650));
+const fs_1 = __webpack_require__(9896);
+const fs = __importStar(__webpack_require__(1943));
+const path = __importStar(__webpack_require__(6928));
+const stream_1 = __webpack_require__(2203);
+const communication_types_1 = __webpack_require__(3443);
+const time_units_1 = __webpack_require__(1929);
+const http_1 = __webpack_require__(866);
+const process_utils_1 = __webpack_require__(8251);
+/** CLI-side pacing default: files staged per bulk-ingestion job (not a server-enforced cap). */
+const DEFAULT_BATCH_SIZE = 200;
+/** Upper bound accepted for `--batchSize`; keeps a single job's blast radius reasonable. */
+const MAX_BATCH_SIZE = 1000;
+/**
+ * Byte budget for one batch's files on disk. Mirrors the server's `BULK_INGESTION_MAX_STAGED_BYTES`
+ * (256 MiB, ai-knowledge-base-management.service.ts) with headroom, since that ceiling applies to
+ * EXTRACTED content and extraction can produce more text than the source file holds. Deliberately a
+ * separate constant rather than an import: the CLI does not depend on core.
+ */
+const MAX_BATCH_BYTES = 192 * 1024 * 1024;
+/** Server-enforced cap on `bulk/createUploadUrls`'s `files` array (`BULK_INGESTION_MAX_UPLOAD_URLS_PER_CALL`). */
+const MAX_UPLOAD_URLS_PER_CALL = 500;
+/** Number of concurrent presigned-URL PUTs. */
+const PUT_CONCURRENCY = 8;
+/**
+ * Files whose upload URLs are minted together. Kept a small multiple of {@link PUT_CONCURRENCY} so a wave's
+ * URLs are always used well inside their 15-minute lifetime, while still amortizing the mint round-trip.
+ */
+const UPLOAD_WAVE_SIZE = 40;
+/**
+ * How long a SIGINT waits for an in-flight `upsertContexts` to yield its job id before cancelling without it.
+ * Bounded because that call has no request timeout of its own: an unbounded wait would leave the first Ctrl-C
+ * hanging behind a wedged server, and a job whose id never arrives is better left to the 7-day deadline than
+ * a CLI that will not quit.
+ */
+const SIGINT_STAGING_WAIT_MILLIS = 10 * time_units_1.MILLIS_PER_SECOND;
+/** Default per-job wait budget before falling back to "still running server-side" and moving on. */
+const DEFAULT_TIMEOUT_MINUTES = 120;
+/** Interval between `bulk/getJob` polls while waiting for a job to reach a terminal state. */
+const POLL_INTERVAL_MILLIS = 10 * time_units_1.MILLIS_PER_SECOND;
+/** Extensions ingested by default when `--extensions` is not provided. */
+const DEFAULT_EXTENSIONS = ['pdf', 'docx', 'txt', 'md', 'html', 'csv', 'xlsx', 'xls', 'xlsm', 'xlsb', 'pptx'];
+/** Job states that end a bulk-ingestion job's lifecycle (`BulkIngestionJobState` in core). */
+const TERMINAL_JOB_STATES = new Set(['completed', 'failed', 'cancelled']);
+const DEFAULT_MIME_TYPE = 'application/octet-stream';
+/** Placeholder status when a job's real status could never be retrieved before the timeout. */
+const UNKNOWN_JOB_STATUS = {
+    state: 'unknown',
+    counts: { files: 0, finalized: 0, failed: 0, requestsPending: 0, requestsSubmitted: 0 },
+    providerBatchIds: [],
+    files: [],
+};
+/**
+ * Fixed line width the progress line pads to, so a shorter update fully overwrites a longer one. 140 because
+ * at Pritzker scale a real line (`batch N/M job <uuid>: X/Y finalized, Z failed, state=...`) exceeds 100 chars.
+ */
+const PROGRESS_LINE_WIDTH = 140;
+/** Small extension → MIME map so the presigned PUT always carries an explicit Content-Type. */
+const EXTENSION_MIME_TYPES = {
+    pdf: 'application/pdf',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    doc: 'application/msword',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    ppt: 'application/vnd.ms-powerpoint',
+    txt: 'text/plain',
+    md: 'text/markdown',
+    html: 'text/html',
+    htm: 'text/html',
+    csv: 'text/csv',
+    tsv: 'text/tab-separated-values',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    xls: 'application/vnd.ms-excel',
+    xlsm: 'application/vnd.ms-excel.sheet.macroEnabled.12',
+    xlsb: 'application/vnd.ms-excel.sheet.binary.macroEnabled.12',
+    eml: 'message/rfc822',
+    msg: 'application/vnd.ms-outlook',
+    json: 'application/json',
+};
+/** Registers the `kb-upload` command: bulk-ingests a local directory tree into a knowledge base. */
+function setupKbUploadCommand(yargs) {
+    yargs.command('kb-upload', 'Bulk-ingests a local directory tree into a knowledge base via the direct-to-storage bulk-ingestion API', yargs => {
+        yargs.option('dir', {
+            type: 'string',
+            demandOption: true,
+            describe: 'The local directory to walk recursively for files to ingest',
+        });
+        yargs.option('knowledgeBase', {
+            type: 'string',
+            demandOption: true,
+            describe: 'The id of the knowledge base to ingest into',
+        });
+        yargs.option('appId', {
+            type: 'string',
+            describe: 'The application ID (Can be retrieved from the Squid Console). Falls back to SQUID_APP_ID',
+        });
+        yargs.option('apiKey', {
+            type: 'string',
+            describe: 'The application API key (Can be retrieved from the Squid Console). Falls back to SQUID_API_KEY',
+        });
+        yargs.option('internalApiKey', {
+            type: 'string',
+            describe: 'Internal API key for local/on-prem use instead of --apiKey. Falls back to SQUID_INTERNAL_API_KEY',
+        });
+        yargs.option('region', {
+            type: 'string',
+            describe: 'The Squid region the application lives in. Falls back to SQUID_REGION',
+        });
+        yargs.option('environmentId', {
+            type: 'string',
+            describe: "The environment to ingest into ('dev' or 'prod'). Falls back to SQUID_ENVIRONMENT_ID",
+        });
+        yargs.option('batchSize', {
+            type: 'number',
+            default: DEFAULT_BATCH_SIZE,
+            describe: `Files staged per bulk-ingestion job (max ${MAX_BATCH_SIZE})`,
+        });
+        yargs.option('extensions', {
+            type: 'string',
+            default: DEFAULT_EXTENSIONS.join(','),
+            describe: 'Comma-separated allow-list of file extensions to ingest',
+        });
+        yargs.option('dryRun', {
+            type: 'boolean',
+            default: false,
+            describe: 'List the files that would be uploaded and exit without contacting the server',
+        });
+        yargs.option('timeoutMinutes', {
+            type: 'number',
+            default: DEFAULT_TIMEOUT_MINUTES,
+            describe: 'Minutes to wait for each job to finish before moving on and reporting it as still running',
+        });
+    }, async (argv) => {
+        // Mirrors what `deploy`/`undeploy` do in main.ts: an initialized project keeps its appId, region,
+        // environment and developer id in a local `.env`, and nothing else loads it for this command — so
+        // without this every normal project fails on "Missing application ID" until the user exports the
+        // variables by hand.
+        dotenv.config({ path: path.resolve('./', '.env') });
+        await kbUpload(argv);
+    });
+}
+/** Drives the full walk → stage → wait → summarize flow and sets `process.exitCode` accordingly. */
+async function kbUpload(argv) {
+    const extensions = parseExtensions(argv.extensions);
+    const batchSize = validateBatchSize(argv.batchSize);
+    const files = await collectFiles(argv.dir, extensions);
+    if (argv.dryRun) {
+        await printDryRun(argv.dir, files, batchSize);
+        return;
+    }
+    if (files.length === 0) {
+        console.log(`No files with extensions [${Array.from(extensions).join(', ')}] found under ${argv.dir}`);
+        return;
+    }
+    const appId = getDataPlaneAppId(argv);
+    const region = getRegion(argv);
+    const { apiKey, internalApiKey } = getAuth(argv);
+    const timeoutMillis = argv.timeoutMinutes * time_units_1.MILLIS_PER_MINUTE;
+    const client = new BulkIngestionClient(region, appId, apiKey, internalApiKey);
+    const batches = await groupFilesIntoBatches(files, batchSize);
+    console.log(`Found ${files.length} file(s) under ${argv.dir}; staging in ${batches.length} batch(es) of up to ${batchSize}.`);
+    const activeJobIds = new Set();
+    // The job id of a batch whose `upsertContexts` call is CURRENTLY in flight. That call runs extraction
+    // inline server-side for a whole batch, so it is a long window in which a job exists on the server but has
+    // no id here yet — and a SIGINT landing in it would otherwise snapshot an empty `activeJobIds`, exit, and
+    // leave that job running and billing. The handler waits on this before cancelling.
+    let pendingStaging;
+    let interrupted = false;
+    const onSigint = () => {
+        if (interrupted) {
+            process.exit(130);
+        }
+        interrupted = true;
+        process.stdout.write('\n');
+        console.log('Received interrupt; cancelling in-flight bulk-ingestion job(s)... (press Ctrl-C again to exit immediately)');
+        // Resolve any in-flight staging FIRST so its job id can be cancelled too; a staging that itself fails
+        // created no job, so an undefined result simply adds nothing. Never rejects — a staging error is already
+        // reported by runBatch — so cancellation always runs.
+        //
+        // Raced against a deadline: `upsertContexts` runs extraction inline server-side for a whole batch and
+        // carries no request timeout, so waiting on it unconditionally would hang the FIRST Ctrl-C behind a slow
+        // or wedged server. On timeout we fall back to cancelling what we already know about, which is strictly
+        // better than not exiting.
+        const stagingOrTimeout = Promise.race([
+            // Belt and braces: the published promise is already non-rejecting (see onStagingStarted).
+            Promise.resolve(pendingStaging).catch(() => undefined),
+            new Promise(resolve => setTimeout(() => resolve(undefined), SIGINT_STAGING_WAIT_MILLIS)),
+        ]);
+        void stagingOrTimeout
+            .then(stagingJobId => cancelActiveJobs(client, stagingJobId ? new Set([...activeJobIds, stagingJobId]) : activeJobIds))
+            .finally(() => process.exit(130));
+    };
+    process.on('SIGINT', onSigint);
+    const results = [];
+    for (let batchIndex = 0; batchIndex < batches.length && !interrupted; batchIndex++) {
+        // runBatch handles the expected failure modes internally (upload failures, and a staging/job-creation
+        // failure that happens after uploads already succeeded) and always returns a BatchResult for those. This
+        // catch is a last resort for something genuinely unexpected happening before any of that is known (e.g.
+        // createUploadUrls itself throwing), so one batch's crash doesn't abort the whole run.
+        try {
+            const result = await runBatch(client, argv.knowledgeBase, batches[batchIndex], batchIndex, batches.length, timeoutMillis, activeJobIds, () => interrupted, staging => {
+                pendingStaging = staging;
+            });
+            results.push(result);
+            // Cleared once the batch is done: its job id is in `activeJobIds` now (or the job was never created),
+            // so a later SIGINT must not re-resolve this settled promise and issue a pointless cancel.
+            pendingStaging = undefined;
+        }
+        catch (error) {
+            const message = (0, assertic_1.getMessageFromError)(error);
+            console.error(`batch ${batchIndex + 1}/${batches.length}: unexpected error before staging: ${message}`);
+            results.push({
+                batchIndex,
+                batchCount: batches.length,
+                uploadFailures: [],
+                duplicates: [],
+                timedOut: false,
+                batchError: message,
+            });
+        }
+    }
+    process.off('SIGINT', onSigint);
+    printSummary(files.length, results);
+    process.exitCode = interrupted || results.some(hasBatchFailed) ? 1 : 0;
+}
+/** Stages one batch (upload + upsertContexts) and waits for its job to finish or time out. */
+async function runBatch(client, knowledgeBaseId, filePaths, batchIndex, batchCount, timeoutMillis, activeJobIds, isInterrupted, 
+/** Publishes this batch's in-flight `upsertContexts` promise so a SIGINT can cancel the job it creates. */
+onStagingStarted) {
+    const batchLabel = `batch ${batchIndex + 1}/${batchCount}`;
+    // Minted wave by wave, immediately before the PUTs that use them, rather than all at once up front. The
+    // server gives a presigned URL BULK_INGESTION_UPLOAD_URL_EXPIRATION_SECONDS (15 min) of life, and a large
+    // batch on a slow link uploads at only PUT_CONCURRENCY at a time — so URLs minted for the tail of the
+    // batch could expire before their turn arrived, and the single retry would reuse the same dead URL.
+    const uploadResults = [];
+    for (const wave of chunk(filePaths, UPLOAD_WAVE_SIZE)) {
+        // SIGINT is observed between waves, not only after the whole batch has uploaded.
+        if (isInterrupted())
+            break;
+        try {
+            const waveUrls = await createUploadUrlsForBatch(client, wave.map(filePath => path.basename(filePath)));
+            (0, assertic_1.assertTruthy)(waveUrls.length === wave.length, `${batchLabel}: createUploadUrls returned ${waveUrls.length} entries for ${wave.length} files`);
+            uploadResults.push(...(await runWithConcurrency(wave, PUT_CONCURRENCY, async (filePath, index) => uploadFile(filePath, waveUrls[index], waveUrls[index].stagedObjectKey))));
+        }
+        catch (error) {
+            // A mint failure on a LATER wave must not discard the earlier waves' successful uploads: those objects
+            // are already staged, and throwing here would leave them orphaned until the 24h expiry with no job
+            // referencing them. Record this wave's files as upload failures and stage whatever did land — the
+            // summary machinery below already reports per-file failures honestly.
+            const message = (0, assertic_1.getMessageFromError)(error);
+            console.warn(`${batchLabel}: failed to mint or upload a wave of ${wave.length} file(s): ${message}`);
+            uploadResults.push(...wave.map(filePath => ({ fileName: path.basename(filePath), error: message })));
+        }
+    }
+    const uploadFailures = uploadResults.filter(result => !isUploaded(result));
+    for (const failure of uploadFailures) {
+        console.warn(`${batchLabel}: failed to upload ${failure.fileName}: ${failure.error}`);
+    }
+    // BulkIngestionContext.metadata (ENG-2527 Phase-7) is available here for a future path-rule feature —
+    // e.g. tagging each staged file with its source folder/glob-derived metadata — but this command has no
+    // such flag yet, so no metadata is stamped today.
+    const stagedContexts = uploadResults
+        .filter(isUploaded)
+        .map(result => ({ type: 'file', stagedObjectKey: result.stagedObjectKey }));
+    if (stagedContexts.length === 0) {
+        console.warn(`${batchLabel}: every file failed to upload; no job was created.`);
+        return { batchIndex, batchCount, uploadFailures, duplicates: [], timedOut: false };
+    }
+    // Re-checked immediately before staging, not only between waves: the wave loop's `break` lands right here,
+    // so without this Ctrl-C would SKIP the remaining uploads and then promptly create a job anyway. Worse, its
+    // id reaches `activeJobIds` only after `cancelActiveJobs` has already snapshotted the set, so the job would
+    // survive the CLI and keep billing. Uploaded objects with no job simply expire on their own 24h clock.
+    if (isInterrupted()) {
+        console.warn(`${batchLabel}: interrupted before job creation; ${stagedContexts.length} uploaded object(s) remain ` +
+            `staged (auto-expire in 24h) and no job was created.`);
+        return {
+            batchIndex,
+            batchCount,
+            uploadFailures,
+            duplicates: [],
+            timedOut: false,
+            stagedCount: stagedContexts.length,
+        };
+    }
+    // The uploads above already succeeded, so a failure from here on is NOT an upload failure: the objects are
+    // already sitting in staging. Catch this call specifically so that outcome is reported honestly instead of
+    // being conflated with "no job created (all uploads failed)".
+    let jobId;
+    let duplicates;
+    try {
+        const staging = client.upsertContexts(knowledgeBaseId, stagedContexts);
+        // The published promise must never REJECT. It is a derived branch of `staging`, and the only rejection
+        // handler on it lives inside the SIGINT path — which usually never runs, so a staging failure would
+        // otherwise surface as an unhandled rejection and take the whole CLI down AFTER it had already reported
+        // the failure honestly. `undefined` is exactly what the handler treats as "no job to cancel".
+        onStagingStarted(staging.then(response => response.jobId).catch(() => undefined));
+        const response = await staging;
+        jobId = response.jobId;
+        // Named by the title the server rejected them under, which for this command is always the file name.
+        duplicates = (response.duplicates ?? []).map(duplicate => duplicate.name);
+    }
+    catch (error) {
+        const message = (0, assertic_1.getMessageFromError)(error);
+        console.error(`${batchLabel}: staged ${stagedContexts.length} upload(s) but job creation failed: ${message}; ` +
+            `${stagedContexts.length} uploaded object(s) remain staged (auto-expire in 24h).`);
+        return {
+            batchIndex,
+            batchCount,
+            uploadFailures,
+            duplicates: [],
+            timedOut: false,
+            stagingError: message,
+            stagedCount: stagedContexts.length,
+        };
+    }
+    if (duplicates.length > 0) {
+        console.log(`${batchLabel}: ${duplicates.length} file(s) skipped as content this knowledge base already holds.`);
+    }
+    activeJobIds.add(jobId);
+    const { finalStatus, timedOut } = await waitForJobCompletion(client, jobId, batchLabel, timeoutMillis, isInterrupted);
+    activeJobIds.delete(jobId);
+    return { batchIndex, batchCount, jobId, uploadFailures, duplicates, finalStatus, timedOut };
+}
+/** Mints presigned upload URLs for a batch, chunking requests to the server's per-call cap. */
+async function createUploadUrlsForBatch(client, fileNames) {
+    const uploads = [];
+    for (const group of chunk(fileNames, MAX_UPLOAD_URLS_PER_CALL)) {
+        const response = await client.createUploadUrls(group);
+        uploads.push(...response.uploads);
+    }
+    return uploads;
+}
+/**
+ * PUTs one file's bytes to its presigned URL, retrying once on a network error or non-2xx response.
+ * `upload.requiredHeaders` carries whatever the storage backend mandates beyond `Content-Type` (Azure Blob
+ * rejects a PUT without `x-ms-blob-type`), so it must be sent as given rather than assumed empty.
+ */
+async function uploadFile(filePath, upload, stagedObjectKey) {
+    const fileName = path.basename(filePath);
+    const mimeType = EXTENSION_MIME_TYPES[extensionOf(fileName)] || DEFAULT_MIME_TYPE;
+    // Sized once, up front: a presigned PUT needs an explicit Content-Length because a stream body is not
+    // measurable, and knowing it also lets the retry below reopen the file rather than hold it in memory.
+    const { size } = await fs.stat(filePath);
+    let lastError = 'Unknown upload error';
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            // Streamed from disk, NOT buffered: PUT_CONCURRENCY workers each reading a whole file into memory
+            // allocates their combined size, and the direct-upload contract admits files far larger than this
+            // process should ever hold. A fresh stream per attempt — a consumed one cannot be replayed.
+            const response = await fetch(upload.uploadUrl, {
+                method: 'PUT',
+                headers: {
+                    'Content-Type': mimeType,
+                    'Content-Length': String(size),
+                    ...(upload.requiredHeaders ?? {}),
+                },
+                body: stream_1.Readable.toWeb((0, fs_1.createReadStream)(filePath)),
+                // Node requires this for a streaming request body; without it fetch rejects the stream outright.
+                duplex: 'half',
+            });
+            if (response.ok) {
+                return { fileName, stagedObjectKey };
+            }
+            lastError = `HTTP ${response.status}: ${await response.text()}`;
+        }
+        catch (error) {
+            lastError = (0, assertic_1.getMessageFromError)(error);
+        }
+    }
+    return { fileName, error: lastError };
+}
+/**
+ * Polls `bulk/getJob` until the job reaches a terminal state or the timeout elapses. A run can wait up to
+ * `--timeoutMinutes` (default two hours), so a single transient poll error must not crash the whole CLI —
+ * it's logged and retried on the next tick instead.
+ */
+async function waitForJobCompletion(client, jobId, batchLabel, timeoutMillis, isInterrupted) {
+    const deadline = Date.now() + timeoutMillis;
+    let status;
+    let isFirstPoll = true;
+    while (!isInterrupted() && Date.now() < deadline && (!status || !TERMINAL_JOB_STATES.has(status.state))) {
+        if (!isFirstPoll) {
+            await sleep(POLL_INTERVAL_MILLIS);
+        }
+        isFirstPoll = false;
+        try {
+            status = await client.getJob(jobId);
+            printProgress(batchLabel, jobId, status);
+        }
+        catch (error) {
+            console.warn(`\n${batchLabel}: transient error polling job ${jobId}, retrying: ${(0, assertic_1.getMessageFromError)(error)}`);
+        }
+    }
+    process.stdout.write('\n');
+    if (!status) {
+        console.warn(`${batchLabel}: could not retrieve job ${jobId}'s status before the timeout.`);
+        return { finalStatus: UNKNOWN_JOB_STATUS, timedOut: true };
+    }
+    const timedOut = !TERMINAL_JOB_STATES.has(status.state) && !isInterrupted();
+    if (timedOut) {
+        console.warn(`${batchLabel}: job ${jobId} did not finish within the timeout; it may still be running server-side.`);
+    }
+    return { finalStatus: status, timedOut };
+}
+/** Best-effort cancellation of every job still active when the process is interrupted. */
+async function cancelActiveJobs(client, activeJobIds) {
+    await Promise.allSettled(Array.from(activeJobIds).map(async (jobId) => {
+        try {
+            await client.cancelJob(jobId);
+            console.log(`Cancelled job ${jobId}.`);
+        }
+        catch (error) {
+            console.warn(`Failed to cancel job ${jobId}: ${(0, assertic_1.getMessageFromError)(error)}`);
+        }
+    }));
+}
+function printProgress(batchLabel, jobId, status) {
+    const { counts, state } = status;
+    const line = `${batchLabel} job ${jobId}: ${counts.finalized}/${counts.files} finalized, ${counts.failed} failed, state=${state}`;
+    process.stdout.write(`\r${line}${' '.repeat(Math.max(0, PROGRESS_LINE_WIDTH - line.length))}`);
+}
+/** Narrows a `FileUploadResult` to one that uploaded successfully (has a `stagedObjectKey`, no `error`). */
+function isUploaded(result) {
+    return result.stagedObjectKey !== undefined;
+}
+async function printDryRun(dir, files, batchSize) {
+    const preview = files.slice(0, 20);
+    for (const filePath of preview) {
+        console.log(path.relative(dir, filePath));
+    }
+    if (files.length > preview.length) {
+        console.log(`... and ${files.length - preview.length} more`);
+    }
+    // Uses the real grouping rather than a count division: batches are bounded by bytes as well, so a
+    // division would under-report the batch count for exactly the large-corpus runs this flag is used to plan.
+    const batchCount = (await groupFilesIntoBatches(files, batchSize)).length;
+    console.log(`\n${files.length} file(s) would be uploaded in ${batchCount} batch(es) of up to ${batchSize} file(s) ` +
+        `and ${Math.floor(MAX_BATCH_BYTES / (1024 * 1024))} MiB. Dry run: no files were uploaded.`);
+}
+function printSummary(totalFiles, results) {
+    const totalFinalized = results.reduce((sum, result) => sum + (result.finalStatus?.counts.finalized ?? 0), 0);
+    const totalServerFailed = results.reduce((sum, result) => sum + (result.finalStatus?.counts.failed ?? 0), 0);
+    const totalUploadFailed = results.reduce((sum, result) => sum + result.uploadFailures.length, 0);
+    const totalDuplicates = results.reduce((sum, result) => sum + result.duplicates.length, 0);
+    const totalStagedButFailed = results.reduce((sum, result) => sum + (result.stagingError ? (result.stagedCount ?? 0) : 0), 0);
+    console.log('\n=== Bulk KB upload summary ===');
+    console.log(`Files scanned:          ${totalFiles}`);
+    console.log(`Finalized (server):     ${totalFinalized}`);
+    console.log(`Failed (server-side):   ${totalServerFailed}`);
+    console.log(`Failed to upload:       ${totalUploadFailed}`);
+    if (totalDuplicates > 0) {
+        // Between "scanned" and "finalized" so the two reconcile: a duplicate is neither finalized nor failed,
+        // and reading the summary without this line the difference looks like files that silently disappeared.
+        console.log(`Skipped as duplicate:   ${totalDuplicates}`);
+    }
+    if (totalStagedButFailed > 0) {
+        console.log(`Staged but job failed:  ${totalStagedButFailed} (uploaded objects remain; auto-expire in 24h)`);
+    }
+    for (const result of results) {
+        const label = `batch ${result.batchIndex + 1}/${result.batchCount}`;
+        if (result.stagingError) {
+            console.log(`  ${label}: staged ${result.stagedCount ?? 0} upload(s) but job creation failed: ${result.stagingError}; ` +
+                `uploaded object(s) remain (auto-expire in 24h)`);
+            continue;
+        }
+        if (result.batchError) {
+            console.log(`  ${label}: unexpected error before staging: ${result.batchError}`);
+            continue;
+        }
+        if (!result.jobId) {
+            console.log(`  ${label}: no job created (all uploads failed)`);
+            continue;
+        }
+        const state = result.timedOut
+            ? `${result.finalStatus?.state ?? 'unknown'} (timed out waiting)`
+            : result.finalStatus?.state;
+        console.log(`  ${label}: job ${result.jobId} — ${result.finalStatus?.counts.finalized ?? 0}/${result.finalStatus?.counts.files ?? 0} finalized, ${result.finalStatus?.counts.failed ?? 0} failed [${state}]`);
+        // Per-file failure reasons, straight from the job-status response (BulkIngestionFileStatus).
+        const failedFiles = result.finalStatus?.files.filter(file => file.status === 'failed') ?? [];
+        for (const failedFile of failedFiles) {
+            console.log(`    - ${failedFile.title}: ${failedFile.errorMessage ?? 'unknown error'}`);
+        }
+        // Named individually for the same reason failures are: "20 skipped" does not tell an operator whether
+        // the right 20 were skipped, and these files never reach the job, so nothing else will ever name them.
+        for (const duplicate of result.duplicates) {
+            console.log(`    - ${duplicate}: skipped, already in this knowledge base`);
+        }
+    }
+}
+function hasBatchFailed(result) {
+    if (result.uploadFailures.length > 0 || result.timedOut)
+        return true;
+    if (!result.finalStatus)
+        return true;
+    return result.finalStatus.state !== 'completed' || result.finalStatus.counts.failed > 0;
+}
+/** Recursively walks `dir`, skipping symlinks and dotfiles/dot-directories, filtered to `extensions`. */
+async function collectFiles(dir, extensions) {
+    const stat = await fs.stat(dir).catch(() => undefined);
+    if (!stat || !stat.isDirectory()) {
+        (0, process_utils_1.exitWithError)(`--dir must point to an existing directory: ${dir}`);
+    }
+    const files = [];
+    await walk(dir, files, extensions);
+    files.sort();
+    return files;
+}
+async function walk(dir, files, extensions) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') || entry.isSymbolicLink()) {
+            continue;
+        }
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walk(fullPath, files, extensions);
+        }
+        else if (entry.isFile() && extensions.has(extensionOf(entry.name))) {
+            files.push(fullPath);
+        }
+    }
+}
+function extensionOf(fileName) {
+    return path.extname(fileName).slice(1).toLowerCase();
+}
+function parseExtensions(raw) {
+    const extensions = raw
+        .split(',')
+        .map(extension => extension.trim().replace(/^\./, '').toLowerCase())
+        .filter(extension => extension.length > 0);
+    if (extensions.length === 0) {
+        (0, process_utils_1.exitWithError)('--extensions must list at least one extension');
+    }
+    return new Set(extensions);
+}
+function validateBatchSize(batchSize) {
+    if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > MAX_BATCH_SIZE) {
+        (0, process_utils_1.exitWithError)(`--batchSize must be an integer between 1 and ${MAX_BATCH_SIZE}`);
+    }
+    return batchSize;
+}
+/**
+ * The app id the DATA PLANE is addressed by: base id plus environment plus developer id, exactly as
+ * `deploy` (appIdWithEnvironmentId) and `sample` (appIdWithEnvironmentIdAndDevId) build it.
+ *
+ * The base id alone is not a synonym for it. `appIdWithEnvironmentId` renders `prod` as the bare id, so
+ * uploading with an unsuffixed id targets PRODUCTION; and omitting the developer id targets the shared
+ * dev environment instead of the developer's own sandbox — which the API key does not catch, because key
+ * lookup strips the developer id (`omitSquidDevId`), so both authenticate with the same key and the
+ * upload silently lands in the wrong place.
+ */
+function getDataPlaneAppId(argv) {
+    const appId = argv.appId || process.env['SQUID_APP_ID'];
+    if (!appId) {
+        (0, process_utils_1.exitWithError)('Missing application ID: pass --appId or set SQUID_APP_ID');
+    }
+    const environmentId = (argv.environmentId || process.env['SQUID_ENVIRONMENT_ID']);
+    const developerId = process.env['SQUID_DEVELOPER_ID'];
+    return (0, communication_types_1.appIdWithEnvironmentIdAndDevId)(appId, environmentId, developerId);
+}
+function getRegion(argv) {
+    const region = argv.region || process.env['SQUID_REGION'];
+    if (!region) {
+        (0, process_utils_1.exitWithError)('Missing Squid region: pass --region or set SQUID_REGION');
+    }
+    return region;
+}
+function getAuth(argv) {
+    const apiKey = argv.apiKey || process.env['SQUID_API_KEY'];
+    const internalApiKey = argv.internalApiKey || process.env['SQUID_INTERNAL_API_KEY'];
+    if (!apiKey && !internalApiKey) {
+        (0, process_utils_1.exitWithError)('Missing credentials: pass --apiKey (or SQUID_API_KEY) or --internalApiKey (or SQUID_INTERNAL_API_KEY)');
+    }
+    return { apiKey, internalApiKey };
+}
+function chunk(items, size) {
+    const chunks = [];
+    for (let i = 0; i < items.length; i += size) {
+        chunks.push(items.slice(i, i + size));
+    }
+    return chunks;
+}
+/**
+ * Groups files into batches bounded by BOTH count and total bytes.
+ *
+ * Count alone is not a bound on what the server will accept: it caps a job's staged CONTENT at
+ * BULK_INGESTION_MAX_STAGED_BYTES, so a default 200-file batch of individually legal 2 MiB documents adds
+ * up to roughly 400 MiB and the whole job is rejected with BULK_INGESTION_TOO_LARGE — every file in it,
+ * including the 199 that were fine.
+ *
+ * On-disk size is a proxy for extracted content, not an equality: plain text is about 1:1, while a PDF or
+ * a workbook can extract to more text than it occupies. {@link MAX_BATCH_BYTES} is set well under the
+ * server ceiling to absorb that, and a file bigger than the budget still gets its own batch — splitting a
+ * single document is not something this tool can do.
+ */
+async function groupFilesIntoBatches(files, batchSize) {
+    const batches = [];
+    let current = [];
+    let currentBytes = 0;
+    for (const filePath of files) {
+        // A file that cannot be stat'ed is counted as weightless rather than skipped: it still belongs in a
+        // batch, and the upload itself is what should report its failure.
+        const size = await fs
+            .stat(filePath)
+            .then(stat => stat.size)
+            .catch(() => 0);
+        if (current.length > 0 && (current.length >= batchSize || currentBytes + size > MAX_BATCH_BYTES)) {
+            batches.push(current);
+            current = [];
+            currentBytes = 0;
+        }
+        current.push(filePath);
+        currentBytes += size;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+/** Runs `worker` over `items` with at most `concurrency` in flight at once, preserving result order. */
+async function runWithConcurrency(items, concurrency, worker) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const runNext = async () => {
+        while (nextIndex < items.length) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            results[currentIndex] = await worker(items[currentIndex], currentIndex);
+        }
+    };
+    const workerCount = Math.min(concurrency, items.length);
+    await Promise.all(Array.from({ length: workerCount }, runNext));
+    return results;
+}
+function sleep(millis) {
+    return new Promise(resolve => setTimeout(resolve, millis));
+}
+/** Thin raw-fetch client for the Phase-5 bulk-ingestion HTTP surface (no SDK dependency — see report). */
+class BulkIngestionClient {
+    constructor(region, appId, apiKey, internalApiKey) {
+        this.region = region;
+        this.appId = appId;
+        this.apiKey = apiKey;
+        this.internalApiKey = internalApiKey;
+        this.lp = 'BulkIngestionClient';
+    }
+    async createUploadUrls(fileNames) {
+        return this.post('ai/knowledge-base/bulk/createUploadUrls', { files: fileNames.map(fileName => ({ fileName })) });
+    }
+    async upsertContexts(knowledgeBaseId, contexts) {
+        return this.post('ai/knowledge-base/bulk/upsertContexts', { knowledgeBaseId, contexts });
+    }
+    async getJob(jobId) {
+        return this.post('ai/knowledge-base/bulk/getJob', { jobId });
+    }
+    async cancelJob(jobId) {
+        await this.post('ai/knowledge-base/bulk/cancelJob', { jobId });
+    }
+    async post(urlPath, body) {
+        const lp = `${this.lp}.post:`;
+        const url = (0, http_1.getApplicationUrl)(this.region, this.appId, urlPath);
+        console.debug(`${lp} POST ${url}`);
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.apiKey) {
+            headers['Authorization'] = `ApiKey ${this.apiKey}`;
+        }
+        if (this.internalApiKey) {
+            headers['x-squid-secret'] = this.internalApiKey;
+        }
+        const response = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body) });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new Error(`${urlPath} failed: ${response.status} ${text}`);
+        }
+        return (text ? JSON.parse(text) : undefined);
+    }
+}
+
+
 /***/ },
 
 /***/ 4291
@@ -34422,6 +35147,7 @@ const build_1 = __webpack_require__(8584);
 const deploy_1 = __webpack_require__(8705);
 const init_env_1 = __webpack_require__(1838);
 const init_webpack_1 = __webpack_require__(1134);
+const kb_upload_1 = __webpack_require__(2713);
 const sample_1 = __webpack_require__(4328);
 const start_1 = __webpack_require__(496);
 const undeploy_1 = __webpack_require__(7097);
@@ -34449,6 +35175,7 @@ function run() {
     setupInitEnvCommand(yargs_1.default);
     setupInitSampleCommand(yargs_1.default);
     setupInitWebpackCommand(yargs_1.default);
+    (0, kb_upload_1.setupKbUploadCommand)(yargs_1.default);
     setupStartCommand(yargs_1.default);
     setupUndeployCommand(yargs_1.default);
     setupUpdateSkillsCommand(yargs_1.default);
@@ -40002,7 +40729,7 @@ module.exports = /*#__PURE__*/JSON.parse('{"name":"seek-bzip","version":"1.0.6",
 (module) {
 
 "use strict";
-module.exports = /*#__PURE__*/JSON.parse('{"name":"@squidcloud/cli","version":"1.0.485","description":"The Squid CLI","main":"dist/index.js","scripts":{"start":"node dist/index.js","start-ts":"ts-node -r tsconfig-paths/register src/index.ts","prebuild":"rimraf dist","build":"webpack --mode=production","build:dev":"webpack --mode=development","lint":"eslint","link":"npm run build && chmod 755 dist/index.js && npm link","watch":"webpack --watch","deploy":"npm run build && npm pack --silent | xargs -I {} mv {} package.tgz && npm install -g package.tgz && rm -rf package.tgz","publish:public":"npm run build && npm publish --access public"},"files":["dist/**/*"],"bin":{"squid":"dist/index.js"},"keywords":[],"author":"","license":"ISC","engines":{"node":">=18.0.0"},"dependencies":{"@squidcloud/local-backend":"^1.0.485","adm-zip":"^0.5.16","copy-webpack-plugin":"^14.0.0","decompress":"^4.2.1","logpipes":"^1.11.0","nodemon":"^3.1.9","terser-webpack-plugin":"^5.5.0","ts-loader":"^9.5.1","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","tsconfig-paths-webpack-plugin":"^4.1.0","webpack":"^5.106.2","zip-webpack-plugin":"^4.0.1"},"devDependencies":{"@types/adm-zip":"^0.5.7","@types/decompress":"^4.2.7","@types/node":"^20.19.9","terminal-link":"^3.0.0"}}');
+module.exports = /*#__PURE__*/JSON.parse('{"name":"@squidcloud/cli","version":"1.0.487","description":"The Squid CLI","main":"dist/index.js","scripts":{"start":"node dist/index.js","start-ts":"ts-node -r tsconfig-paths/register src/index.ts","prebuild":"rimraf dist","build":"webpack --mode=production","build:dev":"webpack --mode=development","lint":"eslint","link":"npm run build && chmod 755 dist/index.js && npm link","watch":"webpack --watch","deploy":"npm run build && npm pack --silent | xargs -I {} mv {} package.tgz && npm install -g package.tgz && rm -rf package.tgz","publish:public":"npm run build && npm publish --access public"},"files":["dist/**/*"],"bin":{"squid":"dist/index.js"},"keywords":[],"author":"","license":"ISC","engines":{"node":">=18.0.0"},"dependencies":{"@squidcloud/local-backend":"^1.0.487","adm-zip":"^0.5.16","copy-webpack-plugin":"^14.0.0","decompress":"^4.2.1","logpipes":"^1.11.0","nodemon":"^3.1.9","terser-webpack-plugin":"^5.5.0","ts-loader":"^9.5.1","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","tsconfig-paths-webpack-plugin":"^4.1.0","webpack":"^5.106.2","zip-webpack-plugin":"^4.0.1"},"devDependencies":{"@types/adm-zip":"^0.5.7","@types/decompress":"^4.2.7","terminal-link":"^3.0.0"}}');
 
 /***/ }
 

package/dist/resources/claude/skills/squid-development/SKILL.md

@@ -23,7 +23,7 @@ Squid is a backend-as-a-service platform that provides:
 
 - **[client.md](reference/client.md)** → client SDK, initialization, setup, auth, login, tokens, OAuth, appId, region, environmentId, apiKey, authProvider, getToken, setAuthProvider, Squid client, frontend, collection, executeFunction, executeFunctionWithHeaders, getWebhookUrl, externalAuth, saveAuthCode, getAccessToken, storage, uploadFile, downloadUrl, queues, produce, consume, distributed locks, acquireLock, withLock, web, aiSearch, getUrlContent, createShortUrl, jobs, getJob, awaitJob, observability, metrics, reportMetric, queryMetrics, notifications, publishNotification, observeNotifications
 - **[console.md](reference/console.md)** → Squid Console, web UI, organizations, applications, AI Studio, knowledge bases, integrations, monitoring, logs, API keys, secrets, testing, debugging, profile settings, management API keys
-- **[ai.md](reference/ai.md)** → AI agents, chat, ask, askWithAnnotations, askAsync, askWithVoiceResponse, transcribeAndChat, transcribeAndAsk, knowledge bases, RAG, embeddings, image generation, audio, transcription, text-to-speech, TTS, connectedAgents, connectedIntegrations, connectedKnowledgeBases, @aiFunction, @secureAiAgent, @secureAiQuery, memory, memoryOptions, voiceOptions, OpenAI, Anthropic, Gemini, Grok, DALL-E, Whisper, MCP, @mcpServer, @mcpTool, executeAiQuery, executeAiApiCall, extraction, createPdf, upsert agent, listAgents
+- **[ai.md](reference/ai.md)** → AI agents, chat, ask, askWithAnnotations, askAsync, askWithVoiceResponse, transcribeAndChat, transcribeAndAsk, knowledge bases, RAG, embeddings, image generation, audio, transcription, text-to-speech, TTS, connectedAgents, connectedIntegrations, connectedKnowledgeBases, @aiFunction, @secureAiAgent, @secureAiQuery, memory, memoryOptions, voiceOptions, OpenAI, Anthropic, Gemini, Grok, DALL-E, Whisper, MCP, @mcpServer, @mcpTool, executeAiQuery, executeAiApiCall, extraction, createPdf, upsert agent, listAgents, spreadsheet understanding, querySpreadsheetsWithAi, searchMode, keyword search, xlsx, csv
 - **[chat-widget.md](reference/chat-widget.md)** → AI chat widget, @squidcloud/react-chat-widget, squid-chat-widget, squid-chat-widget-with-fab-button, embeddable chat, custom API webhook, AI query mode, chain-of-thought, status updates, session management, agentContext, memoryOptions, squid-ai-custom-api-url, squid-ai-agent-chat-options, FAB button, theming, CSS variables, localization, RTL, menu items slots, suggested prompts, voice transcription, error formatting, authentication, squid-auth-provider, onChange events
 - **[databases.md](reference/databases.md)** → collections, documents, queries, subscriptions, snapshots, insert, update, delete, CRUD, real-time, dereference, pagination, transactions, query operators, eq, neq, gt, gte, lt, lte, like, in, nin, arrayIncludesSome, arrayIncludesAll, sortBy, limit, join queries, OR queries, @trigger, native queries, SQL, MongoDB, Elasticsearch, incrementInPath, decrementInPath, watch changes, doc(), projectFields, field projection, __docId__, __id
 - **[backend.md](reference/backend.md)** → SquidService, @executable, @webhook, @trigger, TriggerRequest, @scheduler, @limits, rate limiting, quotas, decorators, backend functions, WebhookRequest, CronExpression, cron, file handling, SquidFile, getUserAuth, isAuthenticated, assertIsAuthenticated, createWebhookResponse, this.squid, this.secrets, @clientConnectionStateHandler, @onQueueMessage, QueueMessageRequest, queue message handler, server-side queue consumer, CLI, squid init, squid start, squid deploy, squid build, project structure, multiple services, service architecture, squidInject, cross-service communication

package/dist/resources/claude/skills/squid-development/reference/ai.md

@@ -436,6 +436,19 @@ const searchResults = await kb.search({
   limit: 10
 });
 
+// Keyword (lexical, embedding-free) search — best for exact tokens: IDs, error codes, SKUs, file names.
+// searchMode: 'vector' | 'hybrid' | 'keyword' | 'graph'. Default: 'hybrid' ('graph' on GraphRAG-enabled
+// KBs; setting 'graph' on other KBs throws). Keyword mechanics differ by the KB's vectorDbType:
+// mongoAtlas = ranked BM25, term-optional (partial matches still rank); postgres = unranked boolean
+// filter where EVERY whitespace-separated term must appear as a literal substring — a multi-word
+// prompt returns zero chunks when any one term is absent, so pass few, specific tokens.
+// On postgres 'hybrid' degrades to dense-only (no lexical channel; hybridWeights is ignored off
+// Mongo), so exact-token retrieval there REQUIRES explicitly setting searchMode: 'keyword'.
+const keywordResults = await kb.search({
+  prompt: 'ERR_0000_4F2A',
+  searchMode: 'keyword'
+});
+
 // Get context
 const context = await kb.getContext('doc-123');
 
@@ -451,6 +464,14 @@ await kb.deleteContext('doc-123');
 await kb.deleteContexts(['doc-1', 'doc-2']);
 ```
 
+### Spreadsheet Understanding
+
+Spreadsheet files (`.csv`, `.tsv`, `.xlsx`, `.xlsm`, `.xls`, `.xlsb`) uploaded as file context take a dedicated ingestion lane: instead of chunking raw cell text, Squid extracts the workbook structure (sheets, headers, hidden sheets; charts and pivot tables where the format exposes them — absent for CSV/TSV and `.xls`, pivots also absent for `.xlsb`) and embeds a generated whole-workbook summary, so search results describe what a workbook contains.
+
+When a connected knowledge base holds spreadsheet contexts, the agent automatically gets a `querySpreadsheetsWithAi` tool that runs Python in a sandbox against the actual uploaded files — for exact values (counts, sums, lookups, filtering, sorting), joins/comparisons across several workbooks in one call, and structure/provenance questions (which sheets feed live calculations, formulas vs hardcoded cells; formula/dependency inspection is fullest for `.xlsx`/`.xlsm`, partial for `.xls`, values-only for `.xlsb`, absent for CSV/TSV). No configuration needed, but the lane and the tool depend on the retained original file: with `discardOriginalFile: true` the spreadsheet ingests as plain extracted text and gets no query tool.
+
+Spreadsheets attached to a chat via `fileUrls` similarly get a per-file Python query tool. Detection is by file extension from `fileName` (or the URL path when `fileName` is absent; query strings are stripped, so a signed URL ending in `.xlsx?sig=...` is detected) — set `fileName` only when the URL path itself lacks the extension, e.g. opaque download routes.
+
 ## AI Files
 
 Manage files stored with AI providers (OpenAI, etc.) for use with agents.

package/dist/resources/claude/skills/squid-development/reference/openai.md

@@ -20,7 +20,8 @@ import {
 
 ### Verbosity Control
 
-Controls response length. OpenAI plain text responses only (ignored for other providers).
+Controls response length. OpenAI only (ignored for other providers), and applies to every response
+format — `text`, `json_object` and `json_schema` alike.
 
 ```typescript
 const response = await agent.ask('Explain quantum computing', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/cli",
-  "version": "1.0.485",
+  "version": "1.0.487",
   "description": "The Squid CLI",
   "main": "dist/index.js",
   "scripts": {
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@squidcloud/local-backend": "^1.0.485",
+    "@squidcloud/local-backend": "^1.0.487",
     "adm-zip": "^0.5.16",
     "copy-webpack-plugin": "^14.0.0",
     "decompress": "^4.2.1",
@@ -45,7 +45,6 @@
   "devDependencies": {
     "@types/adm-zip": "^0.5.7",
     "@types/decompress": "^4.2.7",
-    "@types/node": "^20.19.9",
     "terminal-link": "^3.0.0"
   }
 }