@squidcloud/client 1.0.495 → 1.0.497

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

@@ -8,7 +8,7 @@
  *
  * 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_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 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/ai-agent.public-types.d.ts

@@ -505,7 +505,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.
@@ -950,6 +954,12 @@ export interface AiStatusMessage {
     /** Optional tags providing additional metadata about the status. */
     tags?: Record<string, any>;
 }
+/**
+ * `errorType` on a failed chat/ask job when the AI provider itself failed (a stall, timeout, or
+ * unrecognized 5xx) rather than Squid or the caller's request.
+ * @category AI
+ */
+export declare const AI_PROVIDER_ERROR_TYPE = "AI_PROVIDER_ERROR";
 /** List of all chat history (memory) sources. */
 export declare const AI_CHAT_MESSAGE_SOURCE: readonly ["user", "ai"];
 /** Source of the chat history entry: either an AI response or a user. */
@@ -1068,17 +1078,12 @@ export interface UpsertContextStatusSuccess extends BaseUpsertContextStatus {
     imageFailureCount?: number;
 }
 /**
- * Machine-readable code identifying a specific upsert failure reason.
- *
- * `DUPLICATE_CONTENT` means the request omitted a contextId and its content is
- * byte-identical to an existing context in the same knowledge base.
- *
- * `EMBEDDING_FAILED` means extraction succeeded but embedding the context's chunks did not; the
- * content was not written (an overwrite target keeps its previous content) and the request can be
- * safely retried as-is.
+ * Names an upsert failure; `DUPLICATE_CONTENT` identifies existing content when contextId is omitted.
+ * `EMBEDDING_FAILED`, `EXTRACTION_TIMED_OUT`, `PROVIDER_ACCESS_DENIED`, and `SOURCE_UNREACHABLE` may
+ * succeed on retry. Document faults carry `retryable: false` because the same bytes fail again.
  * @category AI
  */
-export type UpsertContextErrorCode = 'DUPLICATE_CONTENT' | 'EMBEDDING_FAILED';
+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.
@@ -1105,6 +1110,11 @@ export interface UpsertContextStatusError extends BaseUpsertContextStatus {
     errorMessage: string;
     /** Machine-readable code for the failure, when one applies. */
     errorCode?: UpsertContextErrorCode;
+    /**
+     * Present only when the same bytes fail the same way again, so a caller must not retry the request
+     * as-is. Absence means the failure may be transient.
+     */
+    retryable?: false;
     /**
      * The existing context this request duplicated, when `errorCode` is `DUPLICATE_CONTENT`. Lets a caller
      * point the user at where the original already lives (e.g. its folder) instead of only reporting the

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-sol", "gpt-6-luna"];
 /**
  * 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-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"];
 /** 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 { AgentContextRequest, AiChatModelSelection, AiReasoningEffort, ContextImageFailure, UpsertContextStatusError } from './ai-agent.public-types';
+import { AiChatModelSelection, AiReasoningEffort, ContextImageFailure, 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;
 }
@@ -265,6 +277,13 @@ export interface AiKnowledgeBaseGraphConceptsConfig {
  * @category AI
  */
 export declare const FOLDER_PATH_METADATA_FIELD_NAME = "folderPath";
+/**
+ * The canonical file-name metadata field: the source file's name, stamped by file ingestion (console
+ * upload, document connectors). Metadata extraction reads it, beside {@link FOLDER_PATH_METADATA_FIELD_NAME},
+ * as evidence about the document.
+ * @category AI
+ */
+export declare const FILE_NAME_METADATA_FIELD_NAME = "filename";
 /**
  * A path facet: a deterministic tree built by splitting a hierarchical path field on {@link separator}.
  * Interior nodes are the path prefixes; scoping a search to one node matches that folder and everything
@@ -498,9 +517,18 @@ export interface AiKnowledgeBaseContext {
      * content-level dedup on upsert. Absent on legacy contexts ingested before hashing was introduced.
      */
     contentHash?: string;
-    /** Original request configuration for how the context content was processed. */
-    requestConfig?: AgentContextRequest;
+    /**
+     * The options the context was ingested with, replayed when it is reupserted. Absent on contexts that
+     * carry none; their reupsert takes the defaults.
+     */
+    requestConfig?: AiKnowledgeBaseContextRequestConfig;
 }
+/**
+ * The ingestion request's options only. Everything else a reupsert needs lives on the context itself —
+ * its text or stored file, title, metadata and access scopes — where it can change after ingestion.
+ * @category AI
+ */
+export type AiKnowledgeBaseContextRequestConfig = Omit<AiKnowledgeBaseTextContextRequest, 'text' | 'title' | 'metadata' | 'scopes'> | Omit<AiKnowledgeBaseFileContextRequest, 'metadata' | 'scopes'>;
 /**
  * @category AI
  */
@@ -633,11 +661,10 @@ export interface AiKnowledgeBaseFileContextRequest extends BaseAiKnowledgeBaseCo
     /** The preferred method for extracting data from the document. */
     preferredExtractionMethod?: DocumentExtractionMethod;
     /**
-     * Whether Squid keeps or discards the original file.
-     *
-     * Keeping the original file allows reprocessing and the ability for the user to download it later.
-     *
-     * Defaults to false.
+     * Whether Squid discards the downloadable original once the file is extracted; the extracted text and
+     * images are stored either way. Defaults to false: the original is kept so the user can download it and
+     * Squid can reprocess it. Without it, `querySpreadsheetsWithAi` cannot open a workbook context and a
+     * reupsert of the context fails, on the sync and the bulk lane alike.
      */
     discardOriginalFile?: boolean;
 }
@@ -945,9 +972,9 @@ export interface GrepKnowledgeBaseResponse {
      */
     unscannedContextCount?: number;
     /**
-     * With `limitation: 'truncatedContent'`, the file names of documents known to have lost content at
-     * ingest. A bounded sample, not a complete list — present it as an example, and do not infer that
-     * documents missing from it are intact.
+     * Every in-scope document known to have lost content at ingest, by file name. Present whenever such a
+     * document is in scope, alongside whichever {@link limitation} the scan reported — a cut document is no
+     * less cut because the scan also stopped early. Absent when none is.
      */
     truncatedContentFileNames?: Array<string>;
 }
@@ -1710,7 +1737,8 @@ export interface QueryKnowledgeBaseGraphResponse {
     summaries?: Array<KnowledgeBaseGraphQueryGlobalSummary>;
 }
 /**
- * One context to stage through bulk ingestion.
+ * One context to stage through bulk ingestion. Unlike the sync request, `imageExtractionModel` is not
+ * accepted: a job bills one fixed vision model for every image it describes.
  * @category AI
  */
 export interface BulkIngestionContext {
@@ -1744,6 +1772,24 @@ export interface BulkIngestionContext {
      * same name, so a caller's choice survives whichever lane a deployment routes the upload through.
      */
     preferredExtractionMethod?: DocumentExtractionMethod;
+    /**
+     * The RAG type and chunk overlap this context is chunked and indexed with; mirrors the sync request's
+     * `options`, with the same defaults (the knowledge base's `ragType`, and the overlap that type implies).
+     * `chunkOverlap` must be a number below the 4,000-character chunk size.
+     */
+    options?: BaseAiKnowledgeBaseContextOptions;
+    /**
+     * Minimum width/height in pixels for an extracted image to be kept; mirrors the sync request's field of
+     * the same name. Smaller images are skipped, and an inline markdown/HTML image below it keeps its raw
+     * reference in the text.
+     */
+    imageMinSizePixels?: number;
+    /**
+     * Whether Squid discards a file context's downloadable original once it is extracted (the extracted
+     * text and images are stored either way); mirrors {@link AiKnowledgeBaseFileContextRequest.discardOriginalFile},
+     * with the same consequences. Ignored for a text context.
+     */
+    discardOriginalFile?: boolean;
     /**
      * Optional metadata associated with the context item; mirrors {@link BaseAiKnowledgeBaseContextRequest.metadata}.
      * Squid-reserved keys are stripped server-side, and values are validated/normalized against the target
@@ -1867,8 +1913,11 @@ export interface BulkIngestionFileStatus {
     /**
      * 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) and `'UNSUPPORTED_FILE_TYPE'`.
+     * 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
@@ -1877,7 +1926,7 @@ export interface BulkIngestionFileStatus {
      * 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' | 'UNSUPPORTED_FILE_TYPE';
+    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';
     /**
      * 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.
@@ -1895,7 +1944,25 @@ export interface BulkIngestionFileStatus {
     imageFailures?: Array<ContextImageFailure>;
     /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
     imageFailureCount?: number;
+    /**
+     * Set on a `completed` file that is stored and searchable but that the job withheld from graph indexing;
+     * the bulk counterpart of {@link UpsertKnowledgeBaseContextsResponse.graphIndexingSkippedContextIds}, and
+     * `graphIndexingSkipReason` says why. Records the job's own outcome: it is written when the job's graph
+     * run admits its files, which can be after the job completes (a poll of the job status sees it, the
+     * terminal push may not), and it stays set even if a later graph build indexes the file.
+     */
+    graphIndexingSkipped?: boolean;
+    /** Why graph indexing was withheld; present exactly when `graphIndexingSkipped` is. */
+    graphIndexingSkipReason?: BulkIngestionGraphSkipReason;
 }
+/**
+ * Why a bulk-ingested file was withheld from graph indexing. `'cap'`: the knowledge base is over its
+ * per-KB graph chunk cap (or the cap could not be checked and the job failed closed), so the file stays
+ * out until the cap allows it. `'queue'`: the graph-indexing queue was full when the file finalized; the
+ * file is left to the graph auto-build sweep, which indexes it under the same cap once the job goes quiet.
+ * @category AI
+ */
+export type BulkIngestionGraphSkipReason = 'cap' | 'queue';
 /**
  * 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

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

@@ -78,6 +78,10 @@ export interface AnswerOpenAiVoiceCallRequest {
     model?: string;
     /** Voice of the realtime model; defaults to the integration's default voice. */
     voice?: string;
+    /** Whether caller speech interrupts the realtime model. Omitted values keep OpenAI's default. */
+    allowInterruptions?: boolean;
+    /** How readily OpenAI detects caller speech. Omitted values keep OpenAI's default. */
+    interruptionSensitivity?: 'low' | 'normal' | 'high';
     /** Instructions of the realtime model. */
     instructions: string;
     /** Spoken as soon as the call is answered; without it the model waits for the caller to speak first. */
@@ -124,6 +128,10 @@ export interface StartOpenAiWebVoiceCallRequest {
     model?: string;
     /** Voice of the realtime model. */
     voice?: string;
+    /** Whether caller speech interrupts the model; defaults to the phone line, then OpenAI's default. */
+    allowInterruptions?: boolean;
+    /** How readily caller speech is detected; defaults to the phone line, then OpenAI's default. */
+    interruptionSensitivity?: 'low' | 'normal' | 'high';
     /** Language the call starts in, as an ISO code or BCP-47 tag. */
     language?: string;
     /** Whether the caller may switch language mid-call. */

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

@@ -14,7 +14,7 @@ export declare const AUTH_INTEGRATION_TYPES: readonly ["auth0", "jwt_rsa", "jwt_
  * `AiAgentMcpServerConfig.oauthIntegrationId`). Kept in sync with the providers supported by the
  * MCP OAuth validation in core.
  */
-export declare const MCP_OAUTH_INTEGRATION_TYPES: readonly ["auth0"];
+export declare const MCP_OAUTH_INTEGRATION_TYPES: readonly ["auth0", "azure-entra-id", "azure-entra-external-id"];
 /** Supported integration types for GraphQL-based services. */
 export declare const GRAPHQL_INTEGRATION_TYPES: readonly ["graphql"];
 /** Supported integration types for HTTP-based services. */

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

@@ -84,4 +84,18 @@ export interface AsyncJob<T = any> {
      * This is optional.
      */
     error?: string;
+    /**
+     * A machine-readable category for the error, if the job has failed. Lets a caller branch on the
+     * failure kind (e.g. `'AI_PROVIDER_ERROR'`) without parsing {@link error}.
+     */
+    errorType?: string;
+}
+/**
+ * An `Error` carrying a machine-readable {@link errorType}, thrown by `JobClient.awaitJob` when a
+ * failed job's {@link AsyncJob.errorType} is set. Lets a caller branch on the failure kind (e.g.
+ * `'AI_PROVIDER_ERROR'`) without parsing `message`.
+ */
+export interface JobError extends Error {
+    /** The category the failed job's error was tagged with, if any (e.g. `'AI_PROVIDER_ERROR'`). */
+    errorType?: string;
 }

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

@@ -205,6 +205,18 @@ export interface AiKnowledgeBaseContextSizeRequest {
     /** The ID of the AIKnowledgeBase */
     knowledgeBaseId: AiKnowledgeBaseId;
 }
+/**
+ * Request structure for the internal test-only route that arms an app's next bulk-ingestion fulltext blob
+ * operations to fail, so the staging and finalize fallbacks can be exercised without a storage outage.
+ */
+export interface AiKnowledgeBaseFailNextBulkFulltextBlobOpsRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** How many blob uploads land before the next one fails; omitted leaves uploads alone. */
+    uploadsBeforeFailure?: number;
+    /** How many blob reads land before the next one fails; omitted leaves reads alone. */
+    readsBeforeFailure?: number;
+}
 /**
  * Request structure for the internal test-only route that arms the next `count` grep scans of a
  * knowledge base to fail at their `maxTimeMS` deadline.
@@ -216,7 +228,52 @@ export interface AiKnowledgeBaseFailNextGrepScansRequest {
     knowledgeBaseId: AiKnowledgeBaseId;
     /** How many upcoming scans fail; a non-positive value disarms. */
     count: number;
+    /** Whether the next truncated-file-name lookup fails; false disarms, absent leaves it alone. */
+    failNextTruncatedNameLookup?: boolean;
 }
+/**
+ * Where an armed bulk finalize failure throws: past the destructive-write boundary but before the vector
+ * write (nothing written), or right after it (the vectors are replaced, the record is not).
+ */
+export type BulkFinalizeFailurePhase = 'beforeVectorWrite' | 'afterVectorWrite';
+/**
+ * Request structure for the internal test-only route that arms the next `count` bulk-ingestion finalizes
+ * of a knowledge base to throw at `phase`.
+ */
+export interface AiKnowledgeBaseFailNextBulkFinalizeWritesRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** How many upcoming finalizes fail; a non-positive value disarms. */
+    count: number;
+    /** Where in the finalize the armed failures throw. */
+    phase: BulkFinalizeFailurePhase;
+}
+/**
+ * Request structure for the internal test-only route that arms the next `count` finalize-time
+ * image-description reads of a bulk-ingested knowledge base to fail.
+ */
+export interface AiKnowledgeBaseFailNextImageDescriptionReadsRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** How many upcoming reads fail; zero disarms. */
+    count: number;
+}
+/**
+ * Request structure for the internal test-only route that answers every image with a description derived
+ * from its own bytes and no vision call, so the sync and bulk lanes describe a file identically.
+ */
+export interface AiKnowledgeBaseStubImageDescriptionsRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** Arms the stub when true, disarms it when false. */
+    enabled: boolean;
+}
+/** Leading text of a stubbed image description; the rest is the sha256 of the image bytes. */
+export declare const STUB_IMAGE_DESCRIPTION_PREFIX = "Stubbed image description sha256:";
 /**
  * Request structure for the internal test-only route that makes one knowledge base's graph be built by
  * the deterministic stub extractor instead of by the model.
@@ -457,6 +514,53 @@ export interface AiKnowledgeBaseBackfillFulltextStatus {
     storedPartCount?: number;
     errorMessage?: string;
 }
+/** Longest context batch one `repairBulkFulltext` call accepts; larger work-lists are split by the caller. */
+export declare const REPAIR_BULK_FULLTEXT_MAX_CONTEXTS_PER_CALL = 20;
+/**
+ * Request structure for rebuilding the stored raw text (`kb_fulltext`) of bulk-ingested contexts from the
+ * bulk-ingestion rows their job retained: the staged pages plus the descriptions its `imageDescription`
+ * requests already produced. No vision call, so a repaired context reads exactly as a freshly ingested
+ * one at no model cost.
+ */
+export interface AiKnowledgeBaseRepairBulkFulltextRequest {
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /**
+     * The ids of the contexts to repair, at most {@link REPAIR_BULK_FULLTEXT_MAX_CONTEXTS_PER_CALL} per
+     * call. Each context's stored text is fully replaced, so re-running a context is safe.
+     */
+    contextIds: Array<AiContextId>;
+    /**
+     * Rebuilds a context whose staged pages are gone by re-extracting its stored source file, which runs
+     * the regular document lane and can bill OCR. Off by default; such contexts are skipped without it.
+     */
+    reextractMissingPages?: boolean;
+    /**
+     * The extraction method of the {@link reextractMissingPages} fallback, defaulting to the server's
+     * regular one. Name the method the original ingest used: a file extracted with OCR yields no text for
+     * its scanned pages under a method that does not run it, replacing the context's text with less of it.
+     */
+    extractionMethod?: DocumentExtractionMethod;
+}
+/** Response structure for a `repairBulkFulltext` call: one status per requested context, in request order. */
+export interface AiKnowledgeBaseRepairBulkFulltextResponse {
+    statuses: Array<AiKnowledgeBaseRepairBulkFulltextStatus>;
+}
+/** Outcome of repairing the raw text of one bulk-ingested context. */
+export interface AiKnowledgeBaseRepairBulkFulltextStatus {
+    contextId: AiContextId;
+    /**
+     * `repairedFromReextraction` rebuilt the pages from the stored source file because the row's own were
+     * gone: a fresh extraction, so its text is best-effort rather than the original's. `raced` means another
+     * ingest took the context over during the repair, so re-run it.
+     */
+    status: 'repaired' | 'repairedFromReextraction' | 'raced' | 'error' | 'skipped';
+    /** Why the context was left untouched, when it was skipped. `noJob` cannot be repaired by re-running. */
+    skippedReason?: 'notBulkIngested' | 'noJob' | 'jobActive' | 'noFileRow' | 'notFinalized' | 'pagesBounded' | 'noDescriptionRows' | 'noPages' | 'reingested';
+    /** How many parts (pages/sheets/image descriptions) were stored, on success. */
+    storedPartCount?: number;
+    errorMessage?: string;
+}
 /**
  * Response structure for getting size of context
  * @category AI

package/dist/internal-common/src/types/observability.types.d.ts

@@ -131,6 +131,8 @@ export interface AgentAuditLogUpdateEvent {
 }
 /** Tag for metric events. Value: '0' - not an error, '1' - is an error. */
 export declare const O11Y_TAG_IS_ERROR = "isError";
+/** Tag naming the organization an application belongs to. */
+export declare const O11Y_TAG_ORG_ID = "organizationId";
 /** Tag for log events. Metrics have an explicit appId field. */
 export declare const O11Y_TAG_APP_ID = "appId";
 /** Tag for metric and log events. */
@@ -168,6 +170,23 @@ export declare const O11Y_TAG_AI_BILLING_TIER = "billingTier";
  * the same app.
  */
 export declare const O11Y_TAG_AI_TRAFFIC_KIND = "trafficKind";
+/**
+ * Which stage of a multi-stage lane spent the money, and which pass of its loop produced the call.
+ * Set by the query lanes, whose stages re-send the results gathered so far: without them one
+ * operation's bill cannot be attributed to the stage that carries the tokens. `iteration` is set
+ * only by a lane that loops.
+ */
+export declare const O11Y_TAG_AI_SPEND_STAGE = "stage";
+export declare const O11Y_TAG_AI_SPEND_ITERATION = "iteration";
+/** The stages one `query_api` run reports under {@link O11Y_TAG_AI_SPEND_STAGE}. */
+export type AiQueryApiSpendStage = 'endpoint_select' | 'body_create' | 'response_analyze' | 'explanation';
+/** The stages one `query_data` run reports under {@link O11Y_TAG_AI_SPEND_STAGE}. */
+export type AiQueryDataSpendStage = 'select_tables' | 'generate_query' | 'regenerate_queries' | 'clarification' | 'validate_queries' | 'interpreter_check' | 'interpreter_run' | 'results_analysis' | 'raw_result_purpose' | 'readonly_check' | 'spreadsheet_action';
+/**
+ * Every stage value the ledger accepts. Enumerated rather than left free-form because the report
+ * groups by it: a typo would open a second bucket silently instead of failing to compile.
+ */
+export type AiSpendStage = AiQueryApiSpendStage | AiQueryDataSpendStage;
 /**
  * Whether a billed page reached the document it was extracted for. Page-billed spend only: the
  * provider charges for a stale attempt too, so the pages are recorded either way and this separates

package/dist/internal-common/src/types/query.types.d.ts

@@ -1,4 +1,10 @@
 import { Condition, DocIdCondition, SimpleCondition } from '../public-types/query.public-types';
+/**
+ * Whether a LIKE pattern has a backslash before anything but `%`, `_` or another backslash, which is not
+ * a valid escape. Executors disagree on what it matches: PostgreSQL reads `\d` as `d`, while Mongo and
+ * the local matcher pass it to a regex as a digit.
+ */
+export declare function hasInvalidLikeEscape(pattern: string): boolean;
 /**
  * Generates the regex pattern, handling special characters as follows:
  *  - `_` is replaced with a `.`

package/dist/internal-common/src/utils/http.d.ts

@@ -1,24 +1,4 @@
 import { AppId } from '../public-types/communication.public-types';
 import { Stage } from '../types/stage';
-export declare const KOTLIN_CONTROLLERS: string[];
-/**
- * Returns true if the given path is served by Kotlin core in local dev (port 8001). All `/ws/*`
- * WebSocket paths are served by the TypeScript core (port 8000).
- */
-export declare function isKotlinPath(path: string): boolean;
 export declare function getEnvironmentPrefix(shard: string | undefined, region: string, cloudId: string, stage: Stage): string;
-export declare function getApplicationUrl(environmentPrefix: string, appId: string, path: string, appIdPlaceholder?: AppId, environmentPrefixPlaceholder?: string, forceKotlin?: boolean): string;
-/**
- * Returns the URL of [path] on the `core-query-kotlin` Service, addressed from inside the cluster.
- *
- * Naming the Service rather than building the public URL with {@link getApplicationUrl} keeps a
- * purely intra-cluster call off the external load balancer, which is what the Kotlin core's own
- * `getApplicationUrlInternal` already does for the hop in the other direction; and it makes the call
- * independent of where ingress sends [path], so moving that route cannot turn a forward into a
- * request back to this core.
- *
- * The Service is shared and not per-app, so the application is identified by the
- * `SquidHeaders.APP_ID` header rather than by the hostname. Local development has no cluster DNS and
- * keeps the per-app host on Kotlin's port.
- */
-export declare function getQueryKotlinServiceUrl(environmentPrefix: string, appId: AppId, path: string): string;
+export declare function getApplicationUrl(environmentPrefix: string, appId: string, path: string, appIdPlaceholder?: AppId, environmentPrefixPlaceholder?: string): string;

package/dist/internal-common/src/utils/object.d.ts

@@ -1,3 +1,5 @@
+/** Splits a field path into the segments `getInPath` walks: a dot or a bracket separates them. */
+export declare const SPLIT_REGEX_FOR_GET_IN_PATH: RegExp;
 /** Returns a value by the `path`. Works with array indexes, like a.b[0]. */
 export declare function getInPath(obj: unknown, path: string): any;
 export declare function isDateObject(value: unknown): value is Date;

package/dist/internal-common/src/utils/serialization.d.ts

@@ -1,6 +1,12 @@
 export declare function sortKeys(json: unknown): any;
 export declare function normalizeJsonAsString(json: unknown): string;
 export declare function serializeObj(obj: unknown): string;
+/**
+ * A `JSON.stringify` replacer writing a `Date` as `{ $date }`, the form {@link deserializeObj} reads back,
+ * for callers that keep every other value's own `toJSON`. The date is read off the holder, since a
+ * replacer is handed the `toJSON` text of a date; an invalid date keeps that text, `null`.
+ */
+export declare function writeDateAsBson(this: Record<string, unknown>, key: string, value: unknown): unknown;
 export declare function deserializeObj<T = any>(str: string): T;
 /**
  * Deserializes a multipart request payload when present.

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

@@ -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>;
     /**