@squidcloud/client 1.0.497 → 1.0.499

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

@@ -1,13 +1,4 @@
-/**
- * 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.
- */
+/** Names of the Squid metrics; dashboards and metric queries key on these exact strings. */
 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. */

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,54 @@ export interface IntegrationModelSpec {
  * @category AI
  */
 export type AiChatModelSelection = AiChatModelName | IntegrationModelSpec;
+/**
+ * Lets a routing model pick which of several vendor models answers an `ask` or `chat` 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` or `chat` request: a concrete model, or a set of models a routing model chooses from.
+ * @category AI
+ */
+export type AiAskModelSelection = AiChatModelSelection | AiModelRoutingOptions;
+/**
+ * What a `chat` job resolves to once its stream has ended; read it with `squid.jobs().awaitJob(jobId)`.
+ * @category AI
+ */
+export interface AiChatJobResult {
+    /** Set when `model` was an {@link AiModelRoutingOptions}: which model answered and what routing cost. */
+    routing?: AiModelRoutingResult;
+}
+/**
+ * Chat options as a request carries them: the model may also be a routing choice between several models.
+ * @category AI
+ */
+export type AiChatRequestOptions = Omit<AllAiAgentChatOptions, 'model'> & {
+    model?: AiAskModelSelection;
+};
+/**
+ * How a 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
@@ -750,7 +798,7 @@ export type AiVerbosityLevel = 'low' | 'medium' | 'high';
  * **Example:**
  * ```typescript
  * {
- *   model: 'claude-sonnet-5',
+ *   model: 'claude-sonnet-5-5',
  *   responseFormat: {
  *     type: 'json_schema',
  *     schema: {
@@ -1244,7 +1292,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 +1449,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
@@ -61,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-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-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", "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-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,24 @@ 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 when it was admitted — before any paid stage ran — 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 +1998,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 +2037,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 +2172,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,23 @@ 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;
+    /**
+     * Context of the run, which every node reads as LangGraph's `runtime.context`. It is not stored, so a resume
+     * passes its own.
+     */
+    context?: Record<string, unknown>;
+}
+/**
+ * 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;
+    /** Context of the resumed run, which every node reads as LangGraph's `runtime.context`. */
+    context?: Record<string, unknown>;
 }
 /**
  * Successful result of a LangGraph invocation.

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

@@ -1,4 +1,4 @@
-import { AgentContextRequest, AiAgent, AiAgentContext, AiAgentMcpServerConfig, AiAnnotation, AiAudioCreateSpeechOptions, AiChatMessage, AiChatOptions, AiGenerateImageOptions, AllAiAgentChatOptions, ApplicationAiSettings, BuildAgentOptions } from '../public-types/ai-agent.public-types';
+import { AgentContextRequest, AiAgent, AiAgentContext, AiAgentMcpServerConfig, AiAnnotation, AiAudioCreateSpeechOptions, AiChatMessage, AiChatOptions, AiChatRequestOptions, AiGenerateImageOptions, AiModelRoutingResult, ApplicationAiSettings, BuildAgentOptions } from '../public-types/ai-agent.public-types';
 import { AiProviderType, ModelIdSpec } from '../public-types/ai-common.public-types';
 import { AiContextMetadata, AiContextMetadataFilter } from '../public-types/ai-knowledge-base.public-types';
 import { AiAgentId, AiKnowledgeBaseId, AppId, ClientRequestId } from '../public-types/communication.public-types';
@@ -15,13 +15,13 @@ export interface AiChatRequest {
     agentId: AiAgentId;
     clientRequestId: ClientRequestId;
     prompt?: string;
-    options?: AllAiAgentChatOptions;
+    options?: AiChatRequestOptions;
     jobId: JobId;
 }
 export interface AiAskRequest {
     agentId: AiAgentId;
     prompt?: string;
-    options?: AllAiAgentChatOptions;
+    options?: AiChatRequestOptions;
     jobId: JobId;
 }
 export interface AiGenerateImageRequest {
@@ -65,6 +65,7 @@ export interface AiContextSizeResponse {
 export interface AiAskResponse {
     responseString: string;
     annotations?: Record<string, AiAnnotation>;
+    routing?: AiModelRoutingResult;
 }
 export interface AiAskWithVoiceResponse {
     responseString: string;

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

@@ -193,7 +193,7 @@ export interface AiKnowledgeBaseSearchResponse {
     /** Traversed subgraph for a `searchMode:'graph'` query with `includeGraphContext`; absent otherwise. */
     graphContext?: AiKnowledgeBaseGraphContext;
 }
-export type { ExploreKnowledgeBaseGraphRequest, ExploreKnowledgeBaseGraphResponse, GetKnowledgeBaseGraphStatusRequest, GetKnowledgeBaseGraphStatusResponse, KnowledgeBaseGraphBuildStageUsage, KnowledgeBaseGraphBuildUsage, KnowledgeBaseGraphEdge, KnowledgeBaseGraphFacetStatus, KnowledgeBaseGraphModelUsage, KnowledgeBaseGraphNode, KnowledgeBaseGraphQueryConcepts, KnowledgeBaseGraphQueryDoc, KnowledgeBaseGraphQueryGlobalSummary, KnowledgeBaseGraphQueryMatch, KnowledgeBaseGraphQueryOp, KnowledgeBaseGraphQueryPath, KnowledgeBaseGraphQuerySubtreeNode, KnowledgeBaseGraphRebuildMode, KnowledgeBaseGraphResolutionStatus, KnowledgeBaseGraphTopic, KnowledgeBaseGraphTopicEdge, KnowledgeBaseGraphUsage, QueryKnowledgeBaseGraphRequest, QueryKnowledgeBaseGraphResponse, RebuildKnowledgeBaseGraphRequest, } from '../public-types/ai-knowledge-base.public-types';
+export type { ExploreKnowledgeBaseGraphRequest, ExploreKnowledgeBaseGraphResponse, GetKnowledgeBaseGraphStatusRequest, GetKnowledgeBaseGraphStatusResponse, KnowledgeBaseGraphBuildStageUsage, KnowledgeBaseGraphBuildUsage, KnowledgeBaseGraphEdge, KnowledgeBaseGraphFacetStatus, KnowledgeBaseGraphModelUsage, KnowledgeBaseGraphNode, KnowledgeBaseGraphQueryConcepts, KnowledgeBaseGraphQueryDoc, KnowledgeBaseGraphQueryGlobalSummary, KnowledgeBaseGraphQueryMatch, KnowledgeBaseGraphQueryOp, KnowledgeBaseGraphQueryPath, KnowledgeBaseGraphQuerySubtreeNode, KnowledgeBaseGraphQueuedRebuild, KnowledgeBaseGraphRebuildMode, KnowledgeBaseGraphResolutionProgress, KnowledgeBaseGraphResolutionStatus, KnowledgeBaseGraphStructuralBuildSkip, KnowledgeBaseGraphStructuralBuildSkipReason, KnowledgeBaseGraphTopic, KnowledgeBaseGraphTopicEdge, KnowledgeBaseGraphUsage, QueryKnowledgeBaseGraphRequest, QueryKnowledgeBaseGraphResponse, RebuildKnowledgeBaseGraphRequest, } from '../public-types/ai-knowledge-base.public-types';
 /**
  * Request structure for getting the size of context
  * for an AiKnowledgeBase
@@ -231,6 +231,25 @@ export interface AiKnowledgeBaseFailNextGrepScansRequest {
     /** Whether the next truncated-file-name lookup fails; false disarms, absent leaves it alone. */
     failNextTruncatedNameLookup?: boolean;
 }
+/**
+ * Request structure for the internal test-only route that reports how many chunk-collection scope
+ * resolutions a Mongo-backed knowledge base's filtered searches ran, and arms the next ones to fail.
+ */
+export interface AiKnowledgeBaseChunkScopeResolutionsRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** How many upcoming chunk-collection resolutions fail at their `maxTimeMS` deadline; absent disarms. */
+    failNext?: number;
+    /** How many upcoming context-record lookups fail at their `maxTimeMS` deadline; absent disarms. */
+    failNextRecordLookups?: number;
+}
+/** Response structure for {@link AiKnowledgeBaseChunkScopeResolutionsRequest}. */
+export interface AiKnowledgeBaseChunkScopeResolutionsResponse {
+    /** How many chunk-collection scope resolutions ran since the previous request. */
+    count: number;
+}
 /**
  * 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).
@@ -346,6 +365,8 @@ export interface AiKnowledgeBaseSetGraphWriteGateRequest {
 export interface AiKnowledgeBaseSetGraphWriteGateResponse {
     /** True once a writer has parked on the gate. */
     entered: boolean;
+    /** How many writers have parked on the gate since it was armed. */
+    entrants: number;
 }
 /**
  * Request structure for the internal test-only route that runs one knowledge base's graph writes without the
@@ -610,9 +631,9 @@ export interface AiKnowledgeBaseChatRequest {
     prompt?: string;
     options?: AiKnowledgeBaseChatOptionsInternal;
 }
-/** Emitted to the console queue when a knowledge base or its contexts change. */
+/** Emitted to the console queue when a knowledge base, its contexts, or a file's ingestion status change. */
 export interface KbChangeEvent {
     appId: AppId;
     knowledgeBaseId: AiKnowledgeBaseId;
-    changeType: 'kb' | 'context';
+    changeType: 'kb' | 'context' | 'fileStatus';
 }

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

@@ -10,21 +10,8 @@ export declare const SquidHeaders: {
     readonly APP_ID: "x-squid-appid";
     /** Unique identifier of the end user or service client. */
     readonly CLIENT_ID: "x-squid-clientid";
-    /**
-     * Marks a request already forwarded between the cores, carrying a digest of the internal API key.
-     *
-     * The receiving core answers such a request itself instead of forwarding it back, and does not
-     * meter it — whichever core took the request from the outside already did. A value derived from a
-     * shared secret is what makes that safe: a caller could otherwise send the header and skip their
-     * own quota. A digest rather than the key itself, because the header reaches tenant code, where
-     * the key would be a privilege escalation; it authorizes nothing, {@link SECRET} is what internal
-     * auth reads.
-     */
-    readonly PROXY_HOP: "x-squid-proxy-hop";
     /** Version string of the Squid client library. */
     readonly CLIENT_VERSION: "x-squid-client-version";
-    /** Originating IP address of the request. */
-    readonly SOURCE_IP: "x-squid-source-ip";
     /**
      * Access tokens the caller supplies for the request's integrations, as a JSON object keyed by
      * integration ID. An integration type that runs with one takes it in place of its stored secret.

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

@@ -1,5 +1,6 @@
 import { MetricName } from '../metric-name';
 import { AppId } from '../public-types/communication.public-types';
+import { JobId } from '../public-types/job.public-types';
 export interface ObservableNameMetrics {
     count: MetricName;
     time: MetricName;
@@ -129,6 +130,58 @@ export interface AgentAuditLogUpdateEvent {
     /** Number of input tokens written into the provider's prompt cache (cache misses that created new entries). */
     cacheWriteInputTokens?: number;
 }
+/** The lane a knowledge-base search arrived through, recorded on its audit entry. */
+export declare const KB_SEARCH_AUDIT_SOURCES: readonly ["sdk", "agent-context", "agent-tool", "internal", "context-search"];
+/** One of {@link KB_SEARCH_AUDIT_SOURCES}. */
+export type KbSearchAuditSource = (typeof KB_SEARCH_AUDIT_SOURCES)[number];
+/**
+ * Maximum UTF-8 bytes of any free-text audit payload (agent instructions, retrieved content, tool
+ * results, KB query text). Keeps the entry under Kafka's ~1MB message limit with headroom for the rest
+ * of the event and JSON escaping.
+ */
+export declare const MAX_AUDIT_TEXT_BYTES = 500000;
+/** Truncates a free-text audit payload to {@link MAX_AUDIT_TEXT_BYTES}, marking the cut. */
+export declare function truncateAuditText(text: string): string;
+/**
+ * Maximum scopes / contextIds kept on a KB search audit entry. When exceeded, the list is cut and
+ * `__truncated` is appended as the final element — the `__` prefix is Squid's reserved scope
+ * namespace, so the sentinel can never collide with a real scope or context id from a resolver.
+ */
+export declare const MAX_KB_AUDIT_LIST_ENTRIES = 1000;
+/** Final element of a capped scopes/contextIds list on a KB search audit entry. */
+export declare const KB_AUDIT_TRUNCATED_SENTINEL = "__truncated";
+/** Caps an audited scopes/contextIds list, appending the sentinel when entries were dropped. */
+export declare function capKbAuditList(values: ReadonlyArray<string>): Array<string>;
+/**
+ * KB retrieval audit entry — one per search of an access-enforced knowledge base, across every
+ * search lane. Records what the caller asked, the access scopes they held, and which contexts
+ * (documents) the search returned. Only searches on a knowledge base with
+ * `accessControl.mode: 'enforced'` produce entries.
+ */
+export interface KbSearchAuditLogEvent {
+    appId: AppId;
+    knowledgeBaseId: string;
+    /** The search lane the query arrived through. */
+    source: KbSearchAuditSource;
+    /** The agent the search ran for; absent outside agent jobs. */
+    agentId?: string;
+    /** The agent job the search ran in; absent outside agent jobs. */
+    jobId?: JobId;
+    /** The query text, truncated to {@link MAX_AUDIT_TEXT_BYTES}. */
+    prompt: string;
+    /** Effective retrieval mode (`hybrid` | `vector` | `keyword`; `graph` is refused under enforcement). */
+    searchMode: string;
+    /** Access scopes the caller held for this search (the resolver's output), capped. */
+    scopes: Array<string>;
+    /** Unique context ids of the documents returned to the caller, capped. */
+    contextIds: Array<string>;
+    /** Number of chunks returned (post-limit). */
+    chunkCount: number;
+    durationMs: number;
+    /** Identity tags of the caller: {@link AUDIT_TAG_USER_ID} / auth type / client id / source IP. */
+    tags: Record<string, string>;
+    createdAt: Date;
+}
 /** 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. */
@@ -137,7 +190,7 @@ export declare const O11Y_TAG_ORG_ID = "organizationId";
 export declare const O11Y_TAG_APP_ID = "appId";
 /** Tag for metric and log events. */
 export declare const O11Y_TAG_INTEGRATION_ID = "integrationId";
-/** The integration's own type, which a per-type comparison of the two cores groups by. */
+/** The integration's own type, which per-type metrics are grouped by. */
 export declare const O11Y_TAG_INTEGRATION_TYPE = "integrationType";
 /** Whether the query also registered a subscription for its result. */
 export declare const O11Y_TAG_SUBSCRIBE = "subscribe";
@@ -217,7 +270,7 @@ export declare const O11Y_TAG_TRACE_ID = "trace_id";
 /** Tag for the span ID. Used in logs. */
 export declare const O11Y_TAG_SPAN_ID = "span_id";
 /**
- * Tag carrying Squid's own correlation id (the `n_`/`c_`/`k_` short id minted by
+ * Tag carrying Squid's own correlation id (the `n_`/`c_` short id minted by
  * `generateTraceId`). Distinct from `trace_id`/`span_id`, which hold the W3C ids from OTel.
  * Rides W3C baggage under the same key on internal hops; attached to spans and logs.
  */

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

@@ -31,6 +31,11 @@ export declare function cloneShallow<T>(value: T): T;
 export declare function deepMerge<T extends object, U extends object>(target: T, source: U): T & U;
 /** Returns true if the `value` is a defined object and is not an array. */
 export declare function isPlainObject(value: unknown): value is object;
+/**
+ * Returns true if the `value` is an object that JSON can hold as it is: a plain object whose values are JSON at any
+ * depth, with no `__proto__` key. A `Date` or another class instance is not one.
+ */
+export declare function isJsonObject(value: unknown): value is Record<string, unknown>;
 /** Compares 2 values. 'null' and 'undefined' values are considered equal and are less than any other values. */
 export declare function compareValues(v1: unknown, v2: unknown): number;
 /** Returns a new object with all top-level object fields re-mapped using `valueMapperFn`. */

package/dist/internal-common/src/utils/squid.constants.d.ts

@@ -1,6 +1,3 @@
 export declare const SQUID_SUPPORT_EMAIL = "support@getsquid.ai";
-/**
- * Error code when application is not found.
- * Must be in sync with Kotlin.
- */
+/** Error code when application is not found. */
 export declare const APPLICATION_NOT_FOUND_ERROR = "APPLICATION_NOT_FOUND";