@squidcloud/client 1.0.496 → 1.0.498

package/dist/internal-common/src/public-types/ai-agent.public-types.d.ts

@@ -1,5 +1,5 @@
 import { JSONSchema } from 'json-schema-typed';
-import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, CanonicalReasoningEffort, EmbeddingModelIdSpec, GeminiChatModelName, GrokChatModelName, ModelIdSpec, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat, OpenAiImageModelName } from './ai-common.public-types';
+import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, CanonicalReasoningEffort, EmbeddingModelIdSpec, GeminiChatModelName, GrokChatModelName, ModelIdSpec, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat, OpenAiImageModelName, VendorAiChatModelName } from './ai-common.public-types';
 import { AiContextMetadata, AiContextMetadataFilter, AiKnowledgeBaseContextType, AiRagType } from './ai-knowledge-base.public-types';
 import { AiFunctionId, AiFunctionIdWithContext, UserAiChatModelName } from './backend.public-types';
 import { AiAgentId, AiContextId, AiKnowledgeBaseId, AppId, IntegrationId } from './communication.public-types';
@@ -420,6 +420,39 @@ export interface IntegrationModelSpec {
  * @category AI
  */
 export type AiChatModelSelection = AiChatModelName | IntegrationModelSpec;
+/**
+ * Lets a routing model pick which of several vendor models answers an `ask` request. The routing model
+ * sees the question, the agent's instructions and a card per candidate (price, tier, reasoning,
+ * context window) and names the one that should answer; that model then serves the request.
+ * @category AI
+ */
+export interface AiModelRoutingOptions {
+    /** The vendor models the routing model chooses from; at least two, no duplicates. */
+    models: VendorAiChatModelName[];
+    /** The vendor model that makes the choice. */
+    routingModel: VendorAiChatModelName;
+}
+/**
+ * The model of an `ask` request: a concrete model, or a set of models a routing model chooses from.
+ * @category AI
+ */
+export type AiAskModelSelection = AiChatModelSelection | AiModelRoutingOptions;
+/**
+ * How an `ask` request whose `model` was an {@link AiModelRoutingOptions} was routed.
+ * @category AI
+ */
+export interface AiModelRoutingResult {
+    /** The model the routing model chose and the request was sent to. A `backupModel` may still have served it. */
+    model: VendorAiChatModelName;
+    /** The model that made the choice. */
+    routingModel: VendorAiChatModelName;
+    /** Input tokens the routing call consumed. */
+    inputTokens: number;
+    /** Output tokens the routing call generated. */
+    outputTokens: number;
+    /** Best-effort USD cost of the routing call; undefined when the routing model is unpriced. */
+    costUsd?: number;
+}
 /**
  * A backup model together with the sampling settings to run it with. Use this form instead of a
  * bare {@link AiChatModelSelection} when the backup needs settings of its own; anything left unset
@@ -505,7 +538,11 @@ export interface BaseAiChatOptions {
     responseFormat?: AiAgentResponseFormat;
     /** Whether to response in a "smooth typing" way, beneficial when the chat result is displayed in a UI. Default to true. */
     smoothTyping?: boolean;
-    /** Global context passed to the agent and all AI functions of the agent. */
+    /**
+     * Global context passed to the agent and all AI functions of the agent. A request's value also reaches the AI
+     * functions of its connected agents, merged over each one's stored `agentContext`. Its keys are caller input and
+     * win over stored ones: only the root agent's `@secureAiAgent` rules can vet them, and none run for a public agent.
+     */
     agentContext?: Record<string, unknown>;
     /**
      * Functions to expose to the AI.
@@ -1079,7 +1116,7 @@ export interface UpsertContextStatusSuccess extends BaseUpsertContextStatus {
  * succeed on retry. Document faults carry `retryable: false` because the same bytes fail again.
  * @category AI
  */
-export type UpsertContextErrorCode = 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'EMBEDDING_FAILED' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'NO_EMBEDDABLE_CONTENT' | 'PROVIDER_ACCESS_DENIED' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'SOURCE_UNREACHABLE' | 'UNREADABLE_WORKBOOK' | 'UNSUPPORTED_FILE_TYPE';
+export type UpsertContextErrorCode = 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'EMBEDDING_FAILED' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'IMAGE_OVER_PROVIDER_LIMIT' | 'NO_EMBEDDABLE_CONTENT' | 'PROVIDER_ACCESS_DENIED' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'SOURCE_UNREACHABLE' | 'UNREADABLE_DOCUMENT' | 'UNREADABLE_WORKBOOK' | 'UNSUPPORTED_FILE_TYPE';
 /**
  * The existing context a `DUPLICATE_CONTENT` rejection points at — where the byte-identical original
  * already lives.
@@ -1240,7 +1277,7 @@ export type AiPiiEntityType = 'email' | 'phoneNumber' | 'creditCard' | 'ssn' | '
 /** Entity kinds screened when {@link AiPiiOptions.entities} is omitted. */
 export declare const DEFAULT_PII_ENTITY_TYPES: ReadonlyArray<AiPiiEntityType>;
 /** Model that screens prompts unless overridden. Small and fast: it runs on every prompt. */
-export declare const DEFAULT_PII_CLASSIFIER_MODEL = "gpt-5.6-luna";
+export declare const DEFAULT_PII_CLASSIFIER_MODEL = "gpt-6-luna";
 /**
  * Rejects a prompt before it reaches the agent's model when it carries PII, so the prompt is never
  * sent to the model provider, never answered, and never written to chat memory.
@@ -1397,6 +1434,8 @@ export interface AiAskResponse {
     responseString: string;
     /** Optional annotations (e.g., file references) in the response */
     annotations?: Record<string, AiAnnotation>;
+    /** Set when `model` was an {@link AiModelRoutingOptions}: which model answered and what routing cost. */
+    routing?: AiModelRoutingResult;
 }
 /**
  * API request to create speech from text

package/dist/internal-common/src/public-types/ai-common.public-types.d.ts

@@ -37,11 +37,16 @@ export type AiFileProviderType = (typeof AI_FILE_PROVIDER_TYPES)[number];
  * for them the ids are inert rather than wrong.
  */
 export declare function isFileCapableProviderType(type: AiProviderType): type is AiFileProviderType;
+/**
+ * The AI providers whose chat provider implements the code interpreter. Declared like
+ * {@link AI_FILE_PROVIDER_TYPES}, so a provider that gains the interpreter is added here and nowhere else.
+ */
+export declare const AI_CODE_INTERPRETER_PROVIDER_TYPES: readonly ["openai", "anthropic", "gemini"];
 /**
  * Public OpenAI chat model names (active models only).
  * @category AI
  */
-export declare const OPENAI_CHAT_MODEL_NAMES: readonly ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-6-astra"];
+export declare const OPENAI_CHAT_MODEL_NAMES: readonly ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-6-astra", "gpt-6-luna", "gpt-6.1-sol"];
 /**
  * Public Gemini chat model names (active models only).
  * @category AI
@@ -56,12 +61,12 @@ export declare const GROK_CHAT_MODEL_NAMES: readonly ["grok-4.6", "grok-4-1-fast
  * Public Anthropic chat model names (active models only).
  * @category AI
  */
-export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5-20251001", "claude-opus-5", "claude-sonnet-5"];
+export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5-20251001", "claude-opus-5-5", "claude-sonnet-5"];
 /**
  * The supported AI model names.
  * @category AI
  */
-export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-6-astra", "claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5-20251001", "claude-opus-5", "claude-sonnet-5", "gemini-3.1-pro", "gemini-3.8-flash", "gemini-3.5-flash-lite", "grok-4.6", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
+export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-6-astra", "gpt-6-luna", "gpt-6.1-sol", "claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5-20251001", "claude-opus-5-5", "claude-sonnet-5", "gemini-3.1-pro", "gemini-3.8-flash", "gemini-3.5-flash-lite", "grok-4.6", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
 /** Checks if the given model name is a global AI chat model name.  */
 export declare function isVendorAiChatModelName(modelName: unknown): modelName is VendorAiChatModelName;
 /**

package/dist/internal-common/src/public-types/ai-function.public-types.d.ts

@@ -1,8 +1,11 @@
+import { JSONSchema } from 'json-schema-typed';
 import { AiFileUrl } from './ai-agent.public-types';
 import { ServiceFunctionName } from './backend.public-types';
 import { IntegrationType } from './integration.public-types';
 /** Represents the possible data types for an AI function parameter. */
-export type AiFunctionParamType = 'string' | 'number' | 'boolean' | 'date' | 'files';
+export type AiFunctionParamType = 'string' | 'number' | 'boolean' | 'date' | 'files' | 'object';
+/** JSON Schema (draft 2020-12) describing the value of an `object` AI function parameter. */
+export type AiFunctionParamSchema = JSONSchema.Interface;
 /**
  * How sticky affinity routing must be for a function that keeps state outside the request.
  * - `pod`: the state is reachable by any worker of the pod (a file on disk, a child process).
@@ -23,6 +26,13 @@ export interface AiFunctionParam {
     required: boolean;
     /** List of possible values for the parameter, if applicable. */
     enum?: Array<Omit<AiFunctionParamType, 'date'>>;
+    /**
+     * The JSON Schema of the value; required when `type` is `'object'` and rejected otherwise. Its root must be
+     * `{ type: 'object' }`, and an object that lists `properties` accepts no other property unless it sets
+     * `additionalProperties`. Squid validates every call against it, so the function only receives a value that
+     * satisfies it.
+     */
+    schema?: AiFunctionParamSchema;
     /**
      * Marks this parameter as the affinity key of the function and states how sticky the routing must
      * be: every call carrying the same value is routed to the same tenant pod (and, for `worker`, the

package/dist/internal-common/src/public-types/ai-knowledge-base.public-types.d.ts

@@ -1,4 +1,4 @@
-import { AiChatModelSelection, AiReasoningEffort, ContextImageFailure, UpsertContextStatusError } from './ai-agent.public-types';
+import { AiChatModelSelection, AiReasoningEffort, ContextImageFailure, UpsertContextErrorCode, UpsertContextStatusError } from './ai-agent.public-types';
 import { AiEmbeddingsModelSelection, AiRerankProvider } from './ai-common.public-types';
 import { AiContextId, AiKnowledgeBaseId, AppId } from './communication.public-types';
 import { DocumentExtractionMethod } from './extraction.public-types';
@@ -228,12 +228,24 @@ export interface AiKnowledgeBaseGraphConfig {
      */
     autoBuildDebounceMs?: number;
     /**
-     * When true, the sweep does not start automatic structural builds for this KB: activity keeps arming
-     * the build, and the first quiet window after the flag is cleared runs it. Meant for an ingestion
-     * campaign whose builds an operator wants to schedule by hand; `rebuildGraph` stays available.
-     * Defaults to false.
+     * When true, the sweep starts no automatic build for this KB, entity resolution included: activity keeps
+     * arming the build, and the first quiet window after the flag is cleared runs it. `rebuildGraph` stays
+     * available. To hold only the structural build, use `structuralBuildSchedule`. Defaults to false.
      */
     autoBuildPaused?: boolean;
+    /**
+     * When the sweep may start an automatic structural build: `'debounced'` (one quiet window after activity),
+     * `'off'` (manual `rebuildGraph` only) or a 5-field cron expression. Entity resolution keeps running
+     * either way. Omitted ⇒ the server's default, `'debounced'` unless the deployment sets one.
+     */
+    structuralBuildSchedule?: string;
+    /** IANA time zone of a cron `structuralBuildSchedule`, e.g. `'America/Los_Angeles'`. Omitted ⇒ the server's default (UTC). */
+    structuralBuildTimeZone?: string;
+    /**
+     * How long after a cron slot its structural build may still start (milliseconds); past it, the build waits for
+     * the next slot. Must be a positive integer. Omitted ⇒ the server's default (3 hours).
+     */
+    structuralBuildCatchUpMs?: number;
     /** Concept-layer (facet taxonomy) configuration. Omitted ⇒ `facets: 'auto'`. */
     concepts?: AiKnowledgeBaseGraphConceptsConfig;
 }
@@ -931,9 +943,11 @@ export interface AiKnowledgeBaseGrepMatch {
  *   content was never searchable.
  * - `coverageUnknown` — the scan itself succeeded, but how much of the scope holds stored text could not
  *   be determined, so completeness cannot be asserted either way.
+ * - `patternTooBroad` — the pattern may occur in too many places to check them all within the time limit,
+ *   so only some were searched. Narrow with `metadataFilter` or use a longer, more distinctive pattern.
  * @category AI
  */
-export type GrepScanLimitation = 'timedOut' | 'noIndexedText' | 'filterMatchedNoContexts' | 'scopeTruncated' | 'partsCapReached' | 'partialCoverage' | 'truncatedContent' | 'coverageUnknown';
+export type GrepScanLimitation = 'timedOut' | 'noIndexedText' | 'filterMatchedNoContexts' | 'scopeTruncated' | 'partsCapReached' | 'partialCoverage' | 'truncatedContent' | 'coverageUnknown' | 'patternTooBroad';
 /**
  * Response structure for a literal scan over a knowledge base's raw extracted text.
  * @category AI
@@ -1259,6 +1273,21 @@ export interface GetKnowledgeBaseGraphStatusResponse {
     conceptScopeReady?: boolean;
     /** The incremental entity-resolution sweep's latest readings, present once a sweep has sampled the KB. */
     resolution?: KnowledgeBaseGraphResolutionStatus;
+    /** Scheduled structural build slots skipped because the build could not start in time, newest last. */
+    structuralBuildSkips?: Array<KnowledgeBaseGraphStructuralBuildSkip>;
+    /** A manual `rebuildGraph` request waiting for the running entity-resolution build to finish. */
+    queuedRebuild?: KnowledgeBaseGraphQueuedRebuild;
+}
+/**
+ * A manual graph rebuild requested while an entity-resolution build ran. It starts once that build ends,
+ * regardless of the structural build schedule.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphQueuedRebuild {
+    /** The requested rebuild mode; a `'full'` request absorbs a `'structural'` one queued with it. */
+    mode: KnowledgeBaseGraphRebuildMode;
+    /** When the latest request was queued (epoch millis). */
+    requestedAt: number;
 }
 /**
  * Readings the incremental entity-resolution sweep persists on a knowledge base: the dirty backlog it
@@ -1346,7 +1375,58 @@ export interface KnowledgeBaseGraphBuildUsage {
     usage: KnowledgeBaseGraphUsage;
     /** The split of {@link usage} across the stages the build ran. */
     stages: KnowledgeBaseGraphBuildStageUsage;
+    /** What the build's incremental entity-resolution stage has got through; absent until its first pass reports. */
+    resolutionProgress?: KnowledgeBaseGraphResolutionProgress;
+}
+/**
+ * Running progress of a build's incremental entity-resolution stage, written as each pass proposes,
+ * adjudicates and merges, and summed over the build's execution attempts. The build's `usage` is flushed
+ * at the same points, so it reads as the cost so far while the build runs.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphResolutionProgress {
+    /** Drain rounds completed. */
+    rounds: number;
+    /** Resolution passes completed. */
+    passes: number;
+    /** Dirty entities examined. */
+    examined: number;
+    /** Candidate pairs sent to adjudication. */
+    pairsProposed: number;
+    /** Candidate pairs adjudication confirmed as the same entity. */
+    pairsConfirmed: number;
+    /** Entities merged into a canonical entity. */
+    entitiesMerged: number;
+    /** Time spent proposing candidate pairs (millis). */
+    proposalMs: number;
+    /** Time spent adjudicating candidate pairs (millis). */
+    adjudicationMs: number;
+    /** Time spent merging confirmed pairs and refreshing the survivors (millis). */
+    mergeMs: number;
+    /** When the progress was last written (epoch millis). */
+    updatedAt: number;
+}
+/**
+ * A scheduled structural build slot whose catch-up window closed (or the next slot superseded it) without a
+ * structural build, because the automatic build could not start while the window was open.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphStructuralBuildSkip {
+    /** The cron slot that was skipped (epoch millis). */
+    slotAt: number;
+    /** When the slot's catch-up window closed (epoch millis). */
+    windowEndsAt: number;
+    /**
+     * Why the build could not start: an entity-resolution build was still running, another graph build held the KB,
+     * a manual rebuild was queued ahead of it, a bulk ingestion was writing to it, or `graphRag.autoBuildPaused` was set.
+     * The last reason seen in the window.
+     */
+    reason: KnowledgeBaseGraphStructuralBuildSkipReason;
+    /** When the skip was recorded (epoch millis). */
+    recordedAt: number;
 }
+/** Why an automatic structural build could not start inside its scheduled window. @category AI */
+export type KnowledgeBaseGraphStructuralBuildSkipReason = 'resolution-running' | 'build-in-progress' | 'queued-rebuild' | 'bulk-ingest' | 'paused';
 /**
  * A graph build's LLM usage split by pipeline stage. A stage the build entered but spent nothing on
  * reads zero; a stage it never ran (skipped by its plan, or by a resume) is absent.
@@ -1884,6 +1964,23 @@ export interface BulkIngestionJobStatusCounts {
     /** Logical requests submitted to the provider and awaiting results. */
     requestsSubmitted: number;
 }
+/**
+ * Machine-readable class of a bulk-ingestion file failure, for outcomes to treat differently from real
+ * failures. Terminal — reported with `retryable: false` — are `'CONTENT_TOO_LARGE'` (past the per-context
+ * ceiling), `'ENCRYPTED_DOCUMENT'`, `'IMAGE_OVER_PROVIDER_LIMIT'` (the OCR provider refuses an image in the
+ * document as too large, even with the pages that draw it redrawn smaller), `'NO_EMBEDDABLE_CONTENT'`,
+ * `'SOURCE_OVER_PROVIDER_LIMIT'` (the bytes exceed what the extraction provider accepts),
+ * `'UNREADABLE_DOCUMENT'` (a PDF or Office file whose bytes cannot be opened as one), `'UNREADABLE_WORKBOOK'`
+ * (a spreadsheet whose content the parser cannot read) and `'UNSUPPORTED_FILE_TYPE'`.
+ * `'DUPLICATE_CONTENT'` is a skip rather than a failure: the KB already holds this content.
+ * `'EXTRACTION_TIMED_OUT'` stays retryable — the deadline is contended, so a borderline document can
+ * cross it under load. So do `'SOURCE_UNREACHABLE'` (the provider could not fetch the source, which a
+ * fresh link can fix) and `'PROVIDER_ACCESS_DENIED'` (the provider refused the credential or its quota is
+ * spent, a fault of the environment). `'JOB_FULL'`: the job's request ceiling had no room left for this
+ * file, so re-submit it in a fresh job; a file that alone exceeds the ceiling fails this way in every job.
+ * @category AI
+ */
+export type BulkIngestionFileErrorCode = 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'IMAGE_OVER_PROVIDER_LIMIT' | 'JOB_FULL' | 'NO_EMBEDDABLE_CONTENT' | 'PROVIDER_ACCESS_DENIED' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'SOURCE_UNREACHABLE' | 'UNREADABLE_DOCUMENT' | 'UNREADABLE_WORKBOOK' | 'UNSUPPORTED_FILE_TYPE';
 /**
  * Per-file/per-context status within a bulk-ingestion job, so a caller can see which file finished,
  * which is still processing, and why a file failed.
@@ -1900,19 +1997,9 @@ export interface BulkIngestionFileStatus {
     errorMessage?: string;
     /**
      * Machine-readable class of a failed file, for outcomes to treat differently from real failures.
-     * Terminal — reported with `retryable: false` — are `'CONTENT_TOO_LARGE'` (past the per-context
-     * ceiling), `'ENCRYPTED_DOCUMENT'`, `'NO_EMBEDDABLE_CONTENT'`, `'SOURCE_OVER_PROVIDER_LIMIT'` (the
-     * bytes exceed what the extraction provider accepts), `'UNREADABLE_WORKBOOK'` (a spreadsheet whose
-     * content the parser cannot read) and `'UNSUPPORTED_FILE_TYPE'`.
-     * `'DUPLICATE_CONTENT'` is a skip rather than a failure: the KB already holds this content.
-     * `'EXTRACTION_TIMED_OUT'` stays retryable — the deadline is contended, so a borderline document can
-     * cross it under load. So do `'SOURCE_UNREACHABLE'` (the provider could not fetch the source, which a
-     * fresh link can fix) and `'PROVIDER_ACCESS_DENIED'` (the provider refused the credential or its quota is
-     * spent, a fault of the environment). `'JOB_FULL'`: the job's request ceiling had no room left for this
-     * file, so re-submit it in a fresh job; a file that alone exceeds the ceiling fails this way in every job.
-     * Additive; absent for ordinary failures.
-     */
-    errorCode?: 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'JOB_FULL' | 'NO_EMBEDDABLE_CONTENT' | 'PROVIDER_ACCESS_DENIED' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'SOURCE_UNREACHABLE' | 'UNREADABLE_WORKBOOK' | 'UNSUPPORTED_FILE_TYPE';
+     * Additive; absent for ordinary failures. See {@link BulkIngestionFileErrorCode}.
+     */
+    errorCode?: BulkIngestionFileErrorCode;
     /**
      * Present only on a failed file an extraction provider answered: a stable fingerprint of that answer
      * (provider, HTTP status and provider code), so a caller can tell the same failure repeating from a new one.
@@ -1949,6 +2036,91 @@ export interface BulkIngestionFileStatus {
  * @category AI
  */
 export type BulkIngestionGraphSkipReason = 'cap' | 'queue';
+/**
+ * The durable ingestion status of a single file/text context, tracked independently of any one
+ * bulk-ingestion job so it survives job purge. `'no_record'` means the knowledge base has never seen
+ * this path — never persisted, only synthesized when a status query finds nothing. `'in_progress'`
+ * covers every non-terminal bulk-ingestion stage (staged through embedding); the ledger only records
+ * terminal outcomes, so finer sub-stages are not distinguished. `'completed'` and `'failed'` are terminal.
+ * @category AI
+ */
+export type AiKnowledgeBaseFileStatus = 'no_record' | 'in_progress' | 'completed' | 'failed';
+/**
+ * The durable ingestion status of one file/text context at a path, returned by
+ * {@link AiKnowledgeBaseReference.getFileStatus} and as one entry of
+ * {@link AiKnowledgeBaseFolderStatusResponse.files}.
+ * @category AI
+ */
+export interface AiKnowledgeBaseFileStatusInfo {
+    /** The context id, absent only when `status` is `'no_record'`. */
+    contextId?: AiContextId;
+    /** The file's path: `folderPath/filename`, or just `filename` at the upload root. */
+    path: string;
+    /** The file's current durable status. */
+    status: AiKnowledgeBaseFileStatus;
+    /** Present only when `status` is `'failed'`: the terminal failure reason. */
+    errorMessage?: string;
+    /**
+     * Present only when `status` is `'failed'`: the machine-readable failure class, when known. A bulk
+     * lane failure reports {@link BulkIngestionFileErrorCode}; a synchronous `upsertContexts` failure
+     * reports {@link UpsertContextErrorCode} — the two lanes use distinct, mostly-overlapping codes.
+     */
+    errorCode?: BulkIngestionFileErrorCode | UpsertContextErrorCode;
+    /** When this status was last recorded; absent when `status` is `'no_record'`. */
+    updatedAt?: Date;
+}
+/**
+ * Request to look up the durable ingestion status of a single file/text context by path.
+ * @category AI
+ */
+export interface GetKnowledgeBaseFileStatusRequest {
+    /** The knowledge base to query. */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** The file's path: `folderPath/filename`, or just `filename` at the upload root. */
+    path: string;
+}
+/**
+ * Request to search and aggregate the durable ingestion status of every file/text context matching
+ * `folderPath`, read three ways and unioned: a folder subtree, a bare filename anywhere in the
+ * knowledge base, and — when it contains a `/` — an exact `folderPath/filename` path.
+ * @category AI
+ */
+export interface GetKnowledgeBaseFolderStatusRequest {
+    /** The knowledge base to query. */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /**
+     * The folder subtree, bare filename, or exact file path to search for. A subtree match uses the same
+     * segment-safe matching as `$underPath` metadata filters; a value containing `/` also matches that
+     * exact file, so pasting a path from an earlier result finds that one file, not a folder of the same name.
+     */
+    folderPath: string;
+    /**
+     * Maximum number of files to return in `files`, prioritizing failures (the ones needing attention)
+     * before filling remaining room with other statuses. `counts`/`totalFiles` always cover every file
+     * regardless of this cap. Defaults to 50.
+     */
+    fileLimit?: number;
+}
+/**
+ * Aggregate ingestion status for every file/text context matching a searched folder subtree, bare
+ * filename, or exact file path (see {@link GetKnowledgeBaseFolderStatusRequest.folderPath}), combining
+ * a name/path search with per-status counts and the failures that need attention.
+ * @category AI
+ */
+export interface AiKnowledgeBaseFolderStatusResponse {
+    /** The folder subtree, filename, or exact path that was searched. */
+    folderPath: string;
+    /** Count of matching files by terminal/in-progress status (excludes `no_record`), uncapped. */
+    counts: Record<Exclude<AiKnowledgeBaseFileStatus, 'no_record'>, number>;
+    /** Total files found, across all statuses in `counts`. */
+    totalFiles: number;
+    /** False when nothing matched — the folder-level `no_record` case. */
+    hasAnyRecords: boolean;
+    /** Files under the folder, capped at `fileLimit` and prioritizing failures. */
+    files: Array<AiKnowledgeBaseFileStatusInfo>;
+    /** True when `files` was capped and more files exist under the folder than are returned. */
+    truncated: boolean;
+}
 /**
  * Why a whole bulk-ingestion staging call was refused, on the `details` of its 400 response. The
  * refusal names the one context that caused it, so a caller recording per-file outcomes charges only
@@ -1999,6 +2171,8 @@ export interface BulkIngestionProviderBatchStatus {
     providerStatus?: string;
     /** When a poll first saw {@link providerStatus}. */
     providerStatusChangedAt?: Date;
+    /** Why the provider failed the batch as a whole, in its own words; absent on a batch it did not fail. */
+    providerError?: string;
     /** When the provider started running the batch; absent while it has not. */
     providerInProgressAt?: Date;
     /** Per-request progress at the newest poll; absent for a provider that does not report it. */

package/dist/internal-common/src/public-types/langgraph.public-types.d.ts

@@ -7,6 +7,16 @@ export interface InvokeLangGraphOptions {
     threadId?: string;
     /** Initial state for the run. */
     input?: Record<string, unknown>;
+    /** How long the run may take, in ms, before it stops and fails. At most, and by default, one hour. */
+    timeoutMs?: number;
+}
+/**
+ * Options for resuming an interrupted LangGraph thread.
+ * @category AI
+ */
+export interface ResumeLangGraphOptions {
+    /** How long the resumed run may take, in ms, before it stops and fails. At most, and by default, one hour. */
+    timeoutMs?: number;
 }
 /**
  * Successful result of a LangGraph invocation.

package/dist/typescript-client/src/agent/ai-agent-client-reference.d.ts

@@ -1,5 +1,5 @@
 import { Observable } from 'rxjs';
-import { AiAgent, AiAgentMcpServerConfig, AiChatMessage, AiChatModelSelection, AiConnectedAgentMetadata, AiConnectedIntegrationMetadata, AiConnectedKnowledgeBaseMetadata, AiPiiOptions, AiStatusMessage, AiTranscribeAndAskResponse, AllAiAgentChatOptions, BuildAgentOptions, GenerateAgentMcpDescriptionsResponse, GuardrailsOptions, ListAgentRevisionsResponse, UpsertAgentRequest } from '../../../internal-common/src/public-types/ai-agent.public-types';
+import { AiAgent, AiAgentMcpServerConfig, AiAskModelSelection, AiChatMessage, AiChatModelSelection, AiConnectedAgentMetadata, AiConnectedIntegrationMetadata, AiConnectedKnowledgeBaseMetadata, AiPiiOptions, AiStatusMessage, AiTranscribeAndAskResponse, AllAiAgentChatOptions, BuildAgentOptions, GenerateAgentMcpDescriptionsResponse, GuardrailsOptions, ListAgentRevisionsResponse, UpsertAgentRequest } from '../../../internal-common/src/public-types/ai-agent.public-types';
 import { JobId } from '../../../internal-common/src/public-types/job.public-types';
 import { Paths } from '../../../internal-common/src/public-types/typescript.public-types';
 import { AiAskOptions, AiAskOptionsWithVoice, AiChatOptionsWithoutVoice, AskResponse, AskWithVoiceResponse, TranscribeAndAskWithVoiceResponse, TranscribeAndChatResponse } from './ai-agent-client.types';
@@ -131,7 +131,7 @@ export declare class AiAgentReference {
      *   `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who
      *   knows it can look up the job’s status.
      */
-    ask<T extends AiChatModelSelection | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<string>;
+    ask<T extends AiAskModelSelection | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<string>;
     /**
      * Sends a prompt and returns the string response and file annotations.
      * @param prompt The text prompt to send to the agent.
@@ -140,7 +140,7 @@ export declare class AiAgentReference {
      *   `squid.jobs().getJob(jobId)` to track progress. Make sure each job ID is both unique and kept private—anyone who
      *   knows it can look up the job’s status.
      */
-    askWithAnnotations<T extends AiChatModelSelection | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<AskResponse>;
+    askWithAnnotations<T extends AiAskModelSelection | undefined = undefined>(prompt: string, options?: AiAskOptions<T>, jobId?: JobId): Promise<AskResponse>;
     /**
      * Sends a prompt and not wait for the result - the result can be tracked using the job ID
      * (`squid.jobs().awaitJob(jobId)` or `squid.jobs().getJob(jobId)).
@@ -151,7 +151,7 @@ export declare class AiAgentReference {
      to track progress. Make sure each job ID is both unique and kept private—anyone who knows it can look up the job’s status.
      * @param options Optional parameters for the AI ask request.
      */
-    askAsync<T extends AiChatModelSelection | undefined = undefined>(prompt: string, jobId: JobId, options?: AiAskOptions<T>): Promise<void>;
+    askAsync<T extends AiAskModelSelection | undefined = undefined>(prompt: string, jobId: JobId, options?: AiAskOptions<T>): Promise<void>;
     /**
      * Observes live status messages from the agent.
      * @param jobId The job ID to filter status updates for a specific job. If not provided, all status updates for the agent are observed.

package/dist/typescript-client/src/agent/ai-agent-client.types.d.ts

@@ -1,5 +1,5 @@
 import { Observable } from 'rxjs';
-import { AiAnnotation, AiChatModelSelection, AiChatOptions, AiChatRequestCredentials } from '../../../internal-common/src/public-types/ai-agent.public-types';
+import { AiAnnotation, AiAskModelSelection, AiChatModelSelection, AiChatOptions, AiChatRequestCredentials, AiModelRoutingResult } from '../../../internal-common/src/public-types/ai-agent.public-types';
 /**
  * Response format for transcribing audio and generating a chat response.
  * Contains the transcribed text and a stream of AI-generated responses.
@@ -33,6 +33,8 @@ export interface AskResponse {
     responseString: string;
     /** Optional annotations that provide additional context or metadata about the response. */
     annotations?: Record<string, AiAnnotation>;
+    /** Set when `model` was an {@link AiModelRoutingOptions}: which model answered and what the routing call cost. */
+    routing?: AiModelRoutingResult;
 }
 /**
  * Response format for AI-generated voice responses.
@@ -56,13 +58,19 @@ export type AiChatOptionsWithoutVoice<T extends AiChatModelSelection | undefined
  * Options for AI-generated responses that exclude voice-specific settings and smooth typing behavior.
  * @category AI
  */
-export type AiAskOptions<T extends AiChatModelSelection | undefined = undefined> = Omit<AiChatOptions<T>, 'voiceOptions' | 'smoothTyping'> & {
+export type AiAskOptions<T extends AiAskModelSelection | undefined = undefined> = Omit<AiChatOptions<ConcreteModelOf<T>>, 'voiceOptions' | 'smoothTyping' | 'model'> & {
     model?: T;
 } & AiChatRequestCredentials;
 /**
  * Options for AI-generated responses that include voice-specific settings but excludes smooth typing.
  * @category AI
  */
-export type AiAskOptionsWithVoice<T extends AiChatModelSelection | undefined = undefined> = Omit<AiChatOptions<T>, 'smoothTyping'> & {
+export type AiAskOptionsWithVoice<T extends AiAskModelSelection | undefined = undefined> = Omit<AiChatOptions<ConcreteModelOf<T>>, 'smoothTyping' | 'model'> & {
     model?: T;
 } & AiChatRequestCredentials;
+/**
+ * The concrete model an ask's model selection names, which picks the provider-specific option set;
+ * a routing choice names none, so it gets the provider-agnostic options.
+ * @category AI
+ */
+export type ConcreteModelOf<T extends AiAskModelSelection | undefined> = T extends AiChatModelSelection ? T : undefined;

package/dist/typescript-client/src/ai-knowledge-base/ai-knowledge-base-client-reference.d.ts

@@ -1,5 +1,5 @@
 import { Observable } from 'rxjs';
-import { AiEmbeddingsModelWithOptionalFields, AiKnowledgeBase, AiKnowledgeBaseChatOptions, AiKnowledgeBaseContext, AiKnowledgeBaseContextRequest, AiKnowledgeBaseContextWithReasoning, AiKnowledgeBaseDownloadContextResponse, AiKnowledgeBaseSearchContextsWithContextIdRequest, AiKnowledgeBaseSearchContextsWithPromptRequest, AiKnowledgeBaseSearchResponse, AiKnowledgeBaseSearchResultChunk, BulkIngestionContext, BulkIngestionCreateUploadUrlsResponse, BulkIngestionJobStatusResponse, BulkIngestionUpsertContextsOptions, BulkIngestionUpsertContextsResponse, ExploreKnowledgeBaseGraphRequest, ExploreKnowledgeBaseGraphResponse, GenerateMetadataFieldDescriptionsRequest, GenerateMetadataFieldDescriptionsResponse, GetKnowledgeBaseGraphStatusResponse, GrepKnowledgeBaseOptions, GrepKnowledgeBaseResponse, ListAiKnowledgeBaseContextsPageResponse, ListKnowledgeBaseContextsOptions, QueryKnowledgeBaseGraphRequest, QueryKnowledgeBaseGraphResponse, RebuildKnowledgeBaseGraphRequest, UpsertKnowledgeBaseContextResponse, UpsertKnowledgeBaseContextsResponse } from '../../../internal-common/src/public-types/ai-knowledge-base.public-types';
+import { AiEmbeddingsModelWithOptionalFields, AiKnowledgeBase, AiKnowledgeBaseChatOptions, AiKnowledgeBaseContext, AiKnowledgeBaseContextRequest, AiKnowledgeBaseContextWithReasoning, AiKnowledgeBaseDownloadContextResponse, AiKnowledgeBaseFileStatusInfo, AiKnowledgeBaseFolderStatusResponse, AiKnowledgeBaseSearchContextsWithContextIdRequest, AiKnowledgeBaseSearchContextsWithPromptRequest, AiKnowledgeBaseSearchResponse, AiKnowledgeBaseSearchResultChunk, BulkIngestionContext, BulkIngestionCreateUploadUrlsResponse, BulkIngestionJobStatusResponse, BulkIngestionUpsertContextsOptions, BulkIngestionUpsertContextsResponse, ExploreKnowledgeBaseGraphRequest, ExploreKnowledgeBaseGraphResponse, GenerateMetadataFieldDescriptionsRequest, GenerateMetadataFieldDescriptionsResponse, GetKnowledgeBaseGraphStatusResponse, GrepKnowledgeBaseOptions, GrepKnowledgeBaseResponse, ListAiKnowledgeBaseContextsPageResponse, ListKnowledgeBaseContextsOptions, QueryKnowledgeBaseGraphRequest, QueryKnowledgeBaseGraphResponse, RebuildKnowledgeBaseGraphRequest, UpsertKnowledgeBaseContextResponse, UpsertKnowledgeBaseContextsResponse } from '../../../internal-common/src/public-types/ai-knowledge-base.public-types';
 import { AiContextId } from '../../../internal-common/src/public-types/communication.public-types';
 /**
  * Parameters for creating or updating an AI agent.
@@ -81,9 +81,9 @@ export declare class AiKnowledgeBaseReference {
      */
     listContextIds(): Promise<Array<AiContextId>>;
     /**
-     * Retrieves a specific context by its ID. Pass `truncateTextAfter: 0` to omit the context's `text`
-     * field from the response when only its metadata (e.g. `contentHash`) is needed — the stored text
-     * can be multiple MB, and truncating it avoids sending that payload back in full.
+     * Retrieves a specific context by its ID. Pass `truncateTextAfter: 0` to return an empty `text`
+     * field when only its metadata (e.g. `contentHash`) is needed — the stored text can be multiple
+     * MB, and truncating it avoids sending that payload back in full.
      */
     getContext(contextId: string, options?: GetContextOptions): Promise<AiKnowledgeBaseContext | undefined>;
     /**
@@ -207,6 +207,20 @@ export declare class AiKnowledgeBaseReference {
      * recent rebuild job, and the graph's LLM token/cost usage (`ingestUsage`, `lastRebuildUsage`).
      */
     getGraphStatus(): Promise<GetKnowledgeBaseGraphStatusResponse>;
+    /**
+     * Looks up the durable ingestion status of one file by path (`folderPath/filename`, or just
+     * `filename` at the upload root): `'completed'`, `'failed'` (with `errorMessage`/`errorCode`),
+     * `'in_progress'`, or `'no_record'` when the knowledge base has no trace of that path.
+     */
+    getFileStatus(path: string): Promise<AiKnowledgeBaseFileStatusInfo>;
+    /**
+     * Searches and aggregates the durable ingestion status of every file matching `folderPath`, read
+     * three ways and unioned: a folder subtree (matched the same segment-safe way as `$underPath`
+     * metadata filters), a bare filename anywhere in the knowledge base, and — when it contains a `/` —
+     * an exact `folderPath/filename` path. Returns per-status counts plus the files themselves (failures
+     * prioritized, capped at `fileLimit`, default 50).
+     */
+    getFolderStatus(folderPath: string, fileLimit?: number): Promise<AiKnowledgeBaseFolderStatusResponse>;
     /**
      * Enqueues a graph rebuild/backfill. The default `'structural'` mode keeps the already-extracted
      * entity graph (extracting only contexts never graph-indexed) and rebuilds just the concept layer

package/dist/typescript-client/src/langgraph-client.d.ts

@@ -1,5 +1,5 @@
 import { JobId } from '../../internal-common/src/public-types/job.public-types';
-import { GetLangGraphStateSuccessResult, InvokeLangGraphOptions, InvokeLangGraphSuccessResult } from '../../internal-common/src/public-types/langgraph.public-types';
+import { GetLangGraphStateSuccessResult, InvokeLangGraphOptions, InvokeLangGraphSuccessResult, ResumeLangGraphOptions } from '../../internal-common/src/public-types/langgraph.public-types';
 /**
  * Reference to a specific LangGraph.
  * @category AI
@@ -13,9 +13,7 @@ export declare class LangGraphReference {
      *
      * For very long graphs where you don't want to hold a Promise, use `invokeAsync()` instead.
      *
-     * Note: graph execution caps at the tenant IPC timeout (currently 4 minutes).
-     *
-     * @param options Initial state and optional thread to run against.
+     * @param options Initial state, optional thread to run against and optional timeout of the run.
      */
     invoke(options?: InvokeLangGraphOptions): Promise<InvokeLangGraphSuccessResult>;
     /**
@@ -24,31 +22,27 @@ export declare class LangGraphReference {
      *
      * Use this for graphs that may run longer than is comfortable to hold a Promise for.
      *
-     * Note: the underlying graph execution still caps at the tenant IPC timeout (currently 4 minutes)
-     *
-     * @param options Initial state and optional thread to run against.
+     * @param options Initial state, optional thread to run against and optional timeout of the run.
      */
     invokeAsync(options?: InvokeLangGraphOptions): Promise<JobId>;
     /**
      * Resumes an interrupted LangGraph thread and waits for the result.
      * The thread must currently be in `interrupted` status.
      *
-     * Note: graph execution caps at the tenant IPC timeout (currently 4 minutes).
-     *
      * @param threadId The thread to resume.
      * @param resumePayload Value passed to the `interrupt()` call inside the graph.
+     * @param options Optional timeout of the resumed run.
      */
-    resume(threadId: string, resumePayload: unknown): Promise<InvokeLangGraphSuccessResult>;
+    resume(threadId: string, resumePayload: unknown, options?: ResumeLangGraphOptions): Promise<InvokeLangGraphSuccessResult>;
     /**
      * Resumes an interrupted LangGraph thread without waiting for the result.
      * Returns a jobId — pass it to `squid.job().awaitJob(jobId)` or `getJob(jobId)` to retrieve the result later.
      *
-     * Note: graph execution caps at the tenant IPC timeout (currently 4 minutes)
-     *
      * @param threadId The thread to resume.
      * @param resumePayload Value passed to the `interrupt()` call inside the graph.
+     * @param options Optional timeout of the resumed run.
      */
-    resumeAsync(threadId: string, resumePayload: unknown): Promise<JobId>;
+    resumeAsync(threadId: string, resumePayload: unknown, options?: ResumeLangGraphOptions): Promise<JobId>;
     /** Returns the current state of a LangGraph thread. */
     getState(threadId: string): Promise<GetLangGraphStateSuccessResult>;
     /**

package/dist/typescript-client/src/version.d.ts

@@ -2,4 +2,4 @@
  * The current version of the SquidCloud client package.
  * @category Platform
  */
-export declare const SQUIDCLOUD_CLIENT_PACKAGE_VERSION = "1.0.496";
+export declare const SQUIDCLOUD_CLIENT_PACKAGE_VERSION = "1.0.498";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/client",
-  "version": "1.0.496",
+  "version": "1.0.498",
   "description": "A typescript implementation of the Squid client",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",