@squidcloud/client 1.0.497 → 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
@@ -1244,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.
@@ -1401,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

@@ -46,7 +46,7 @@ export declare const AI_CODE_INTERPRETER_PROVIDER_TYPES: readonly ["openai", "an
  * 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", "gpt-6-sol", "gpt-6-luna"];
+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
@@ -66,7 +66,7 @@ export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-fable-5", "cl
  * 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", "gpt-6-sol", "gpt-6-luna", "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"];
+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-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';
@@ -943,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
@@ -1271,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
@@ -1358,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.
@@ -1896,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.
@@ -1912,21 +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'`, `'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.
-     * Additive; absent for ordinary failures.
-     */
-    errorCode?: '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';
+     * 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.
@@ -1963,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
@@ -2013,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.
@@ -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.497";
+export declare const SQUIDCLOUD_CLIENT_PACKAGE_VERSION = "1.0.498";

package/package.json

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

package/dist/internal-common/src/ai/system-openai-compatible.d.ts

@@ -1,35 +0,0 @@
-/**
- * System-level OpenAI-compatible backends ("slots") for Squid's own internal AI calls.
- *
- * Generic plumbing for pointing an internal model at ANY OpenAI-compatible HTTP endpoint —
- * primarily Squid's own self-hosted models, but any OpenAI-compatible backend works. The
- * non-secret part of a slot (base URL, optional headers/extra body) is hardcoded here on purpose
- * (changing a backend is a reviewed code change); only the API key lives in Vault under
- * `SystemSecrets['openai-compatible'][slotName].apiKey`.
- *
- * NOT the customer-facing `openai_compatible` Integration (per-app, console-configured). Models
- * served through these slots are declared in `AI_CHAT_MODEL_REGISTRY` with
- * `providerType: 'openai-compatible'` + `openAiCompatibleSlot`, and resolve only with
- * `keyType: 'system'` (see `AiProviderFactory.getChatProviderForModel`) — never customer-reachable.
- *
- * No slots are defined yet (foundation only). To wire one up:
- *   1. add a slot below, e.g. `'my-model': { baseUrl: 'https://llm.internal.squid/v1' }`;
- *   2. seed its key in `SystemSecrets['openai-compatible']['my-model'].apiKey`;
- *   3. add a model entry in ai-model.registry.ts pointing `openAiCompatibleSlot: 'my-model'`.
- */
-/** Non-secret configuration of one system OpenAI-compatible backend. */
-export interface SystemOpenAiCompatibleSlotConfig {
-    /** Base URL of the OpenAI-compatible API, e.g. a self-hosted 'https://llm.internal.squid/v1'. */
-    baseUrl: string;
-    /** Extra HTTP headers sent with every request. */
-    headers?: Record<string, string>;
-    /** Extra JSON body fields merged into every request — reserved wire fields are dropped by the provider. */
-    extraBody?: Record<string, unknown>;
-}
-/** Name of a system OpenAI-compatible slot (a key of `SYSTEM_OPENAI_COMPATIBLE_SLOTS`). */
-export type SystemOpenAiCompatibleSlotName = string;
-/**
- * Registered system OpenAI-compatible slots, keyed by name. Empty by design — add a self-hosted
- * (or any other) OpenAI-compatible backend here; see the module doc above.
- */
-export declare const SYSTEM_OPENAI_COMPATIBLE_SLOTS: Record<SystemOpenAiCompatibleSlotName, SystemOpenAiCompatibleSlotConfig>;

package/dist/internal-common/src/metric-name.d.ts

@@ -1,14 +0,0 @@
-/**
- * Names of the Squid metrics.
- *
- * This list and its Kotlin counterpart (MetricName.kt) may diverge:
- * each side declares only the metrics that its own backend emits.
- * However, metrics emitted by both backends MUST use identical names on both sides —
- * otherwise dashboards and metric queries that mix data from both sources will break.
- *
- * See MetricName.kt for documentation on each value.
- */
-export declare const ALL_SQUID_METRIC_NAMES: readonly ["squid_functionExecution_count", "squid_functionExecution_time", "squid_aiChatbotContext_size", "squid_aiChatbotChatInputTokens_count", "squid_aiChatbotChatOutputTokens_count", "squid_aiChatbotChatReasoningTokens_count", "squid_aiChatbotChatCacheReadInputTokens_count", "squid_aiChatbotChatCacheWriteInputTokens_count", "squid_aiChatbotChatCostUsd_count", "squid_aiChatbotChatOutcome_count", "squid_aiSpendInputTokens_count", "squid_aiSpendOutputTokens_count", "squid_aiSpendReasoningTokens_count", "squid_aiSpendCacheReadTokens_count", "squid_aiSpendCacheWriteTokens_count", "squid_aiSpendPages_count", "squid_aiSpendImages_count", "squid_aiSpendAudioSeconds_count", "squid_aiSpendCharacters_count", "squid_aiSpendSearches_count", "squid_aiSpendCostUsd_count", "squid_aiImageGeneration_count", "squid_aiImageGeneration_time", "squid_aiRemoveBackground_count", "squid_aiRemoveBackground_time", "squid_aiAudioTranscribe_count", "squid_aiAudioTranscribe_time", "squid_aiAudioCreateSpeech_count", "squid_aiAudioCreateSpeech_time", "squid_aiVoiceCreateSession_count", "squid_aiVoiceCreateSession_time", "squid_aiVoiceAnswerOpenAiCall_count", "squid_aiVoiceAnswerOpenAiCall_time", "squid_aiVoiceStartOpenAiWebCall_count", "squid_aiVoiceStartOpenAiWebCall_time", "squid_aiOpenAiChatCompletions_count", "squid_aiOpenAiChatCompletions_time", "squid_aiIntegrationData_count", "squid_aiIntegrationData_time", "squid_aiIntegrationApi_count", "squid_aiIntegrationApi_time", "squid_apiControllerCall_count", "squid_apiControllerCall_time", "squid_aiContextUpsert_count", "squid_aiContextDelete_count", "squid_codeInitialization_count", "squid_codeInitialization_time", "squid_sourceCodeAnalysis_count", "squid_sourceCodeAnalysis_time", "squid_sourceCodeWorkspaceBytes_value", "squid_sourceCodeInputTokens_count", "squid_sourceCodeOutputTokens_count", "squid_deleteApiKey_count", "squid_deleteApiKey_time", "squid_deleteSecret_count", "squid_deleteSecret_time", "squid_discoverGraphQLConnectionSchema_count", "squid_discoverGraphQLConnectionSchema_time", "squid_discoverOpenApiSchema_count", "squid_discoverOpenApiSchema_time", "squid_discoverOpenApiSchemaFromFile_count", "squid_discoverOpenApiSchemaFromFile_time", "squid_executeBackendFunction_count", "squid_executeBackendFunction_time", "squid_apiControllerCall_count", "squid_apiControllerCall_time", "squid_getAiChatbotProfiles_count", "squid_getAiChatbotProfiles_time", "squid_getAllApiKeys_count", "squid_getAllApiKeys_time", "squid_getAllSecrets_count", "squid_getAllSecrets_time", "squid_getAppApiKey_count", "squid_getAppApiKey_time", "squid_getSecret_count", "squid_getSecret_time", "squid_graphql_count", "squid_graphql_time", "squid_graphqlQuery_count", "squid_graphqlQuery_time", "squid_integrationCount_value", "squid_mutate_count", "squid_mutate_time", "squid_metricQuery_count", "squid_metricQuery_time", "squid_metricReport_count", "squid_metricReport_time", "squid_nativeQuery_count", "squid_nativeQuery_time", "squid_openapi_count", "squid_openapi_time", "squid_produceTopicMessage_count", "squid_produceTopicMessage_time", "squid_query_count", "squid_query_time", "squid_queueMessageHandler_count", "squid_queueMessageHandler_time", "squid_registerQuery_count", "squid_registerQuery_time", "squid_rerankChunks_count", "squid_rerankChunks_time", "squid_schedulerJob_count", "squid_schedulerJob_time", "squid_eventHandler_count", "squid_eventHandler_time", "squid_schema_size", "squid_secrets_entries", "squid_storageDeleteFiles_count", "squid_storageDeleteFiles_time", "squid_storageGetDownloadUrl_count", "squid_storageGetDownloadUrl_time", "squid_storageGetFileMetadata_count", "squid_storageGetFileMetadata_time", "squid_storageListDirectoryContents_count", "squid_storageListDirectoryContents_time", "squid_storageUploadFile_count", "squid_storageUploadFile_time", "squid_subscribeToTopic_count", "squid_subscribeToTopic_time", "squid_tenantDependencyResolved_count", "squid_tenantBrowserSpawnAttempt_count", "squid_testGraphQLConnection_count", "squid_testGraphQLConnection_time", "squid_testAgentProtocolConnection_count", "squid_testAgentProtocolConnection_time", "squid_trigger_count", "squid_trigger_time", "squid_upsertApiKey_count", "squid_upsertApiKey_time", "squid_upsertSecret_count", "squid_upsertSecret_time", "squid_vectorChunks_count", "squid_vectorChunks_time", "squid_webhook_count", "squid_webhook_time", "squid_acquireLock_count", "squid_acquireLock_time", "squid_releaseLock_count", "squid_releaseLock_time"];
-export type MetricName = (typeof ALL_SQUID_METRIC_NAMES)[number];
-/** Common prefix for all Squid metrics. */
-export declare const SQUID_METRIC_NAME_PREFIX = "squid_";

package/dist/internal-common/src/public-types-backend/api-call.public-context.d.ts

@@ -1,30 +0,0 @@
-import { ApiOptions } from '../public-types/api-client.public-types';
-import { ApiEndpointId, HttpMethod } from '../public-types/api.public-types';
-import { IntegrationId } from '../public-types/communication.public-types';
-/** The headers of an API call. */
-export type ApiHeaders = Record<string, string | number | boolean>;
-/** The context of an API call. */
-export declare class ApiCallContext {
-    readonly integrationId: IntegrationId;
-    readonly endpointId: ApiEndpointId;
-    readonly url: string;
-    readonly method: HttpMethod;
-    readonly body: unknown;
-    readonly options: ApiOptions;
-}
-/**
- * Represents a request to call an API through a specified integration and endpoint.
- * Includes optional method override and additional request options.
- */
-export interface CallApiRequest<BodyType = any> {
-    /** The identifier of the integration through which the API is called. */
-    integrationId: IntegrationId;
-    /** Target API endpoint to invoke. */
-    endpointId: ApiEndpointId;
-    /** Optional request payload. */
-    body?: BodyType;
-    /** Optional HTTP method override. Default is POST. */
-    overrideMethod?: HttpMethod;
-    /** Additional request options. */
-    options: ApiOptions;
-}