@squidcloud/client 1.0.483 → 1.0.485

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

@@ -0,0 +1,35 @@
+/**
+ * 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

@@ -0,0 +1,14 @@
+/**
+ * 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_aiImageGeneration_count", "squid_aiImageGeneration_time", "squid_aiRemoveBackground_count", "squid_aiRemoveBackground_time", "squid_aiAudioTranscribe_count", "squid_aiAudioTranscribe_time", "squid_aiAudioCreateSpeech_count", "squid_aiAudioCreateSpeech_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_sourceCodeLeaseWait_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 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

@@ -1,5 +1,5 @@
 import { JSONSchema } from 'json-schema-typed';
-import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, GeminiChatModelName, GrokChatModelName, ModelIdSpec, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat, OpenAiImageModelName } from './ai-common.public-types';
+import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, CanonicalReasoningEffort, GeminiChatModelName, GrokChatModelName, ModelIdSpec, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat, OpenAiImageModelName } 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';
@@ -575,7 +575,7 @@ export interface OpenAiChatOptions extends BaseAiChatOptions {
  * not support the exact requested level.
  * @category AI
  */
-export type CanonicalReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+export type { CanonicalReasoningEffort } from './ai-common.public-types';
 /**
  * AI reasoning effort. Pass one of the canonical levels for portable, autocomplete-friendly usage, or
  * a raw provider-native string when a model exposes a level outside the canonical set.
@@ -660,6 +660,56 @@ export type AiChatOptions<T extends AiChatModelSelection | undefined = undefined
 export type AllAiAgentChatOptions = {
     [K in keyof BaseAiChatOptions | keyof GeminiChatOptions | keyof GrokChatOptions | keyof OpenAiChatOptions | keyof AnthropicChatOptions]?: (K extends keyof BaseAiChatOptions ? BaseAiChatOptions[K] : never) | (K extends keyof GeminiChatOptions ? GeminiChatOptions[K] : never) | (K extends keyof GrokChatOptions ? GrokChatOptions[K] : never) | (K extends keyof OpenAiChatOptions ? OpenAiChatOptions[K] : never) | (K extends keyof AnthropicChatOptions ? AnthropicChatOptions[K] : never);
 };
+/**
+ * Configuration for exposing an AI agent as an MCP server at `/mcp/<agentId>`.
+ * @category AI
+ */
+export interface AiAgentMcpServerConfig {
+    /** Whether the agent is exposed as an MCP server. */
+    enabled: boolean;
+    /**
+     * Description of the MCP server, served as the `instructions` field of the MCP initialize
+     * result. Defaults to the agent description when not provided.
+     */
+    description?: string;
+    /**
+     * Description of the MCP `ask` tool, exposed in the tools manifest.
+     * Defaults to a generic ask-the-agent description when not provided.
+     */
+    toolDescription?: string;
+    /**
+     * ID of an auth integration used to OAuth-protect the MCP server. When set, MCP requests must
+     * include a valid bearer token from this integration. Without this and `requireApiKey`, the
+     * MCP endpoint is public.
+     */
+    oauthIntegrationId?: IntegrationId;
+    /**
+     * When true, MCP requests must present the agent's API key as a bearer token
+     * (`Authorization: Bearer <agent API key>` or the `x-squid-agent-api-key` header). Can be
+     * combined with `oauthIntegrationId`, in which case either credential is accepted.
+     */
+    requireApiKey?: boolean;
+}
+/**
+ * Request to AI-generate the MCP server and tool descriptions for an agent based on its
+ * instructions and connected resources.
+ * @category AI
+ */
+export interface GenerateAgentMcpDescriptionsRequest {
+    /** The ID of the agent to generate MCP descriptions for. */
+    agentId: AiAgentId;
+}
+/**
+ * AI-generated MCP descriptions for an agent. Returned without persisting — the caller saves them
+ * onto the agent's MCP server configuration.
+ * @category AI
+ */
+export interface GenerateAgentMcpDescriptionsResponse {
+    /** Generated description of the MCP server. */
+    description: string;
+    /** Generated description of the MCP `ask` tool. */
+    toolDescription: string;
+}
 /**
  * A definition of an AI agent with its properties and default chat options.
  * @category AI
@@ -677,10 +727,14 @@ export interface AiAgent<T extends AiChatModelSelection | undefined = undefined>
     isPublic?: boolean;
     /** Enables audit logging for the agent's activities if true; defaults to false. */
     auditLog?: boolean;
+    /** Records the full agent context in the audit log — assembled system instructions on the chat-start entry and retrieved knowledge-base content in KB tool-call updates; requires auditLog; defaults to false. */
+    auditLogFullContext?: boolean;
     /** The default chat options for the agent, overridable by the user during use. */
     options: AiChatOptions<T>;
     /** Optional api key used specifically for operations on this agent */
     apiKey?: string;
+    /** Optional configuration for exposing the agent as an MCP server. */
+    mcpServer?: AiAgentMcpServerConfig;
 }
 /**
  * @category AI
@@ -722,6 +776,13 @@ export declare const AGENT_STATUS_TITLE_INSPECTING_KB_METADATA = "Inspecting Kno
  * @category AI
  */
 export declare const AGENT_STATUS_TITLE_QUERYING_KB_GRAPH = "Querying Knowledge Base Graph";
+/**
+ * Status update title emitted when the agent runs the `grepKnowledgeBase` tool (a literal/regex scan over
+ * the knowledge base's raw extracted text). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB} so a
+ * caller can tell an exact-match scan apart from ranked retrieval.
+ * @category AI
+ */
+export declare const AGENT_STATUS_TITLE_GREPPING_KB = "Searching Knowledge Base Text";
 /**
  * Status update title broadcast when the agent queries a spreadsheet file callable.
  * @category AI
@@ -945,7 +1006,13 @@ export interface TextContextRequest extends BaseContextRequest {
 export interface FileContextRequest extends BaseContextRequest {
     /** Specifies the context type as 'file'. */
     type: 'file';
-    /** Whether to extract images from the file; defaults to false. */
+    /**
+     * Whether to extract images from the file, describe them with a vision model, and index those
+     * descriptions alongside the text. Defaults to true — a document's charts, diagrams and scanned pages
+     * carry content the text layer does not. Note that the text context request has no such option:
+     * inline images in a text payload are extracted only for a knowledge-base text context, and default
+     * to OFF there.
+     */
     extractImages?: boolean;
     /** The minimum size for extracted images, if applicable. */
     imageMinSizePixels?: number;
@@ -1062,6 +1129,15 @@ export type AiSessionContext = {
     agentId: string;
     /** The ID of the job associated with the session. */
     jobId: JobId;
+    /**
+     * The conversation this call belongs to, as the caller named it (`memoryOptions.memoryId`, or the
+     * deprecated `chatId`). Stable across the turns of one chat and different for two chats, including
+     * two chats of the same client, which `clientId` is not: a client id belongs to a connection, and
+     * one connection can carry several conversations. Not the id chat history is keyed by — that one
+     * falls back to `clientId` — so do not read it as one. Absent for callers that named no conversation
+     * (a direct function call, security rules).
+     */
+    conversationId?: string;
     /**
      * ID of the status update that triggered this session (e.g. the agent's "Calling AI Function"
      * event). Status updates emitted on behalf of this session nest under it in the status feed.

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

@@ -15,6 +15,11 @@ export declare const AI_PROVIDER_TYPES: readonly ["anthropic", "bedrock", "claud
  * chat/search/transcribe etc...).
  */
 export type AiProviderType = (typeof AI_PROVIDER_TYPES)[number];
+/**
+ * Canonical reasoning-effort levels, ordered from least to most effort.
+ * @category AI
+ */
+export type CanonicalReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra';
 /**
  * Type of AI provider that supports file upload operations.
  * Only a subset of AI providers support file management features.
@@ -219,6 +224,10 @@ export type AiModelSource = (typeof AI_MODEL_SOURCES)[number];
 export interface ModelIdSpec {
     /** The model ID used for API calls. */
     modelId: AiChatModelName;
+    /** The provider serving this model when Squid can determine it from the model registry. */
+    providerType?: AiProviderType;
+    /** Canonical reasoning-effort levels accepted natively by this model. */
+    reasoningEfforts?: CanonicalReasoningEffort[];
     /** The integration ID if this model comes from an integration (OpenAI-compatible, Bedrock). Is undefined for Squid-provided models. */
     integrationId?: string;
     /** Human-readable display name for the model (e.g. "GPT-4o"). */

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

@@ -3,6 +3,14 @@ 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';
+/**
+ * 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).
+ * - `worker`: the state lives in one worker's memory, so the worker itself has to be reused.
+ */
+export declare const FUNCTION_AFFINITY_SCOPES: readonly ["pod", "worker"];
+/** See {@link FUNCTION_AFFINITY_SCOPES}. */
+export type FunctionAffinityScope = (typeof FUNCTION_AFFINITY_SCOPES)[number];
 /** Defines the structure of a parameter for an AI function. */
 export interface AiFunctionParam {
     /** Name of the parameter. */
@@ -15,6 +23,34 @@ export interface AiFunctionParam {
     required: boolean;
     /** List of possible values for the parameter, if applicable. */
     enum?: Array<Omit<AiFunctionParamType, 'date'>>;
+    /**
+     * 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
+     * same worker) for as long as it is alive. Use it for functions that keep state outside the
+     * request. Only one `string` parameter of a function may declare it, and declaring it on a
+     * parameter of any other type fails the bundle build.
+     *
+     * A value of `undefined`, `null` or `''` means no affinity at all — the call is routed normally, to
+     * an arbitrary pod. Blank is deliberately not a key: a caller that leaves the parameter empty must
+     * get an instance of its own rather than share one with every other caller that also left it empty.
+     *
+     * The value is a namespace within the application, the function's SERVICE **and the calling job**
+     * (falling back to the conversation for callers without one): two agent requests that pick the same
+     * value are routed independently, so the value only has to be unique within one request's own
+     * calls. That matches where such values come from — a model authoring a session name is told
+     * nothing about other requests, and unrelated callers routinely land on the same word. A caller
+     * with neither a job nor a conversation gets no affinity at all rather than a namespace shared with
+     * every other such caller. Two callers cannot be routed to one instance on purpose by agreeing on a
+     * value; a function that needs genuinely shared state needs shared storage, not shared routing.
+     *
+     * The domain is the service rather than the single function so that companion functions of one
+     * service reach each other's state — a release function must land on the worker whose interpreter
+     * its key names, or it would no-op against an empty domain of its own and report success.
+     *
+     * The guarantee is routing, not durability: when the pod or worker goes away, so does whatever it
+     * held, and the next call lands on a fresh one. The function has to detect that itself and cope.
+     */
+    affinity?: FunctionAffinityScope;
 }
 /** Represents an AI function response that also includes files. */
 export interface AiFunctionResponseWithFiles<ResponseType = unknown> {

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

@@ -494,7 +494,10 @@ export interface AiKnowledgeBaseTextContextRequest extends BaseAiKnowledgeBaseCo
      */
     format?: AiKnowledgeBaseTextFormat;
     /**
-     * Whether to extract images embedded in markdown/HTML text. Defaults to false.
+     * Whether to extract images embedded in markdown/HTML text. Defaults to FALSE — deliberately the
+     * opposite of {@link AiKnowledgeBaseFileContextRequest.extractImages}. A pasted blob's inline images
+     * are usually layout chrome, whereas an uploaded document's images are part of its content. Uploading
+     * the same markdown as a `.md` file is therefore the file case, and defaults to images ON.
      *
      * When true and the text is detected as (or declared to be) markdown/HTML, image references inside the
      * text (`![alt](url)` or `<img src="...">`) are fetched, stored, and have descriptions generated
@@ -524,7 +527,15 @@ export interface AiKnowledgeBaseFileContextRequest extends BaseAiKnowledgeBaseCo
     contextId?: AiContextId;
     /** Specifies the context type as 'file'. */
     type: 'file';
-    /** Whether to extract images from the file; defaults to false. */
+    /**
+     * Whether to extract images from the file, describe them with a vision model, and index those
+     * descriptions alongside the text. Defaults to TRUE — a document's charts, diagrams and scanned pages
+     * carry content the text layer does not, so a file context captures them unless asked not to.
+     *
+     * Note this is the opposite of {@link AiKnowledgeBaseTextContextRequest.extractImages}, which defaults
+     * to false: images referenced from a pasted markdown/HTML blob are usually layout chrome, and fetching
+     * them means following URLs the caller supplied.
+     */
     extractImages?: boolean;
     /** The minimum size for extracted images, if applicable. */
     imageMinSizePixels?: number;
@@ -677,6 +688,134 @@ export interface AiKnowledgeBaseSearchRequest {
     /** The search options for this search */
     options: AiKnowledgeBaseSearchOptions;
 }
+/** Default number of grep matches returned when the caller does not ask for a specific number. */
+export declare const GREP_KNOWLEDGE_BASE_DEFAULT_MAX_MATCHES = 50;
+/** Hard ceiling on grep matches: a larger `maxMatches` is clamped down to this value. */
+export declare const GREP_KNOWLEDGE_BASE_MAX_MATCHES = 200;
+/**
+ * Longest accepted grep pattern. A literal needle is short by nature; the cap exists so an
+ * adversarially long pattern cannot be used to inflate matching cost on a shared server.
+ */
+export declare const GREP_KNOWLEDGE_BASE_MAX_PATTERN_CHARS = 500;
+/** Longest `line` / `context` a single match returns; anything longer is clipped with an ellipsis. */
+export declare const GREP_KNOWLEDGE_BASE_MAX_MATCH_LINE_CHARS = 500;
+/**
+ * Options for a literal scan over a knowledge base's raw extracted text.
+ * @category AI
+ */
+export interface GrepKnowledgeBaseOptions {
+    /**
+     * Scopes the scan to the contexts whose metadata matches this filter — the same grammar knowledge-base
+     * chunk search accepts, including `$and`/`$or` composition and the `$underPath` folder operator. The
+     * filter selects the contexts BEFORE any text is matched.
+     */
+    metadataFilter?: AiContextMetadataFilter;
+    /**
+     * The maximum number of matches to return. Defaults to {@link GREP_KNOWLEDGE_BASE_DEFAULT_MAX_MATCHES}
+     * and is clamped to {@link GREP_KNOWLEDGE_BASE_MAX_MATCHES}.
+     */
+    maxMatches?: number;
+}
+/**
+ * Request structure for a literal scan over a knowledge base's raw extracted text.
+ * @category AI
+ */
+export interface GrepKnowledgeBaseRequest {
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /**
+     * The literal substring to look for. Every regex metacharacter in it is escaped, so punctuation and
+     * symbols mean themselves, and it may span lines. Capped at
+     * {@link GREP_KNOWLEDGE_BASE_MAX_PATTERN_CHARS} characters.
+     *
+     * Matching is case-insensitive for ASCII letters only: `acme` finds `ACME`, but `café` does not find
+     * `CAFÉ`. The store and the server run two different regex engines, and their `i` flags disagree on
+     * non-ASCII folding — matching ASCII-only is what keeps them in step, so a hit is never reported as an
+     * absence. Search the exact casing for non-ASCII text.
+     */
+    pattern: string;
+    /** Scan options. */
+    options?: GrepKnowledgeBaseOptions;
+}
+/**
+ * One matching line found by {@link GrepKnowledgeBaseRequest}.
+ * @category AI
+ */
+export interface AiKnowledgeBaseGrepMatch {
+    /** The id of the context the match was found in. */
+    contextId: AiContextId;
+    /** The source file name (or context title for text contexts). */
+    fileName: string;
+    /** The locator within the file: a sheet/section title when the extractor supplied one, else `page N`. */
+    part: string;
+    /** The 1-based line number the match starts on within its part. */
+    lineNumber: number;
+    /** The matching line, clipped to {@link GREP_KNOWLEDGE_BASE_MAX_MATCH_LINE_CHARS} with an ellipsis. */
+    line: string;
+    /**
+     * The matching line plus a small window of the lines around it, joined by newlines and clipped to
+     * {@link GREP_KNOWLEDGE_BASE_MAX_MATCH_LINE_CHARS}. Wide spreadsheet rows are the normal case here, so
+     * the clip is what keeps a full result set from overflowing an agent's context window.
+     */
+    context: string;
+}
+/**
+ * Why a grep result does not cover everything the caller asked for. Absent means the scan was complete
+ * over the requested scope, and only then may an empty `matches` be read as the pattern being absent.
+ * At most one applies; the server picks the most significant.
+ *
+ * - `timedOut` — the scan hit its server-side deadline. Routine on large knowledge bases, since the
+ *   match is unindexed. Says nothing at all about whether the pattern occurs.
+ * - `noIndexedText` — nothing in scope has stored text, so nothing was searched. Contexts ingested
+ *   before literal search existed sit here until they are re-ingested.
+ * - `filterMatchedNoContexts` — `metadataFilter`, composed with any visibility filter the application
+ *   applies, admitted no contexts, so the scan had nothing to read.
+ * - `scopeTruncated` — `metadataFilter` admitted more contexts than one scan can cover, so only a prefix
+ *   of them was searched. Narrow the filter.
+ * - `partsCapReached` — the scan filled its per-call budget of matching pages/sheets, so more matching
+ *   places exist than it read.
+ * - `partialCoverage` — some contexts in scope have stored text and some do not; see
+ *   {@link GrepKnowledgeBaseResponse.unscannedContextCount}.
+ * - `truncatedContent` — some in-scope text was cut at ingest, either because one page or sheet exceeded
+ *   the per-part storage cap or because a document had more pages than the per-document cap, so that
+ *   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.
+ * @category AI
+ */
+export type GrepScanLimitation = 'timedOut' | 'noIndexedText' | 'filterMatchedNoContexts' | 'scopeTruncated' | 'partsCapReached' | 'partialCoverage' | 'truncatedContent' | 'coverageUnknown';
+/**
+ * Response structure for a literal scan over a knowledge base's raw extracted text.
+ * @category AI
+ */
+export interface GrepKnowledgeBaseResponse {
+    /** The matches found, in context/part/line order. */
+    matches: Array<AiKnowledgeBaseGrepMatch>;
+    /**
+     * True when the returned list stopped at `maxMatches` — more matches exist than were returned. This
+     * means ONLY that: every other way a scan can fall short of the request lives in {@link limitation},
+     * so a caller branching on this one field never mistakes an incomplete scan for "there are more hits".
+     */
+    truncated: boolean;
+    /**
+     * Why the scan did not cover the full requested scope, if it did not. Absent means it did — which is
+     * the only case where an empty `matches` is evidence that the pattern does not occur. The whole point
+     * of this API is to make absence claims trustworthy, so callers must branch on this before concluding
+     * anything from an empty result.
+     */
+    limitation?: GrepScanLimitation;
+    /**
+     * With `limitation: 'partialCoverage'`, how many contexts in scope have no stored text and were
+     * therefore never scanned. The result is silent about those contexts.
+     */
+    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.
+     */
+    truncatedContentFileNames?: Array<string>;
+}
 /**
  * Request structure for searching AI contexts in the AiKnowledgeBase.
  * @category AI

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

@@ -4,7 +4,7 @@
  * 'CONNECTOR_PACKAGES_TO_EXCLUDE_FROM_AUTO_SYNC' in ConnectorsService (console-backend).
  * @category Platform
  */
-export declare const CONNECTOR_IDS: readonly ["confluence", "cotomi", "essentials", "freshdesk", "github", "google_calendar", "google_drive", "hubspot", "sharepoint", "jira", "jira_jsm", "linear", "mail", "onedrive", "outlook", "salesforce", "servicenow_csm", "slack", "teams", "ticketmind_companion", "zendesk"];
+export declare const CONNECTOR_IDS: readonly ["bitbucket", "confluence", "cotomi", "essentials", "freshdesk", "github", "google_calendar", "google_drive", "hubspot", "sharepoint", "jira", "jira_jsm", "linear", "mail", "onedrive", "outlook", "salesforce", "servicenow_csm", "slack", "teams", "ticketmind_companion", "zendesk"];
 /**
  * Unique connector package name.
  * @category Platform

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

@@ -11,11 +11,18 @@ export interface ExtractDataFromDocumentOptions {
      */
     imageMinSizePixels?: number;
     /**
-     * Whether to extract embedded images from the document.
+     * Whether to extract embedded images from the document. Defaults to true.
      */
     extractImages?: boolean;
     /**
-     * Specific page indexes to extract from the document (0-based). If omitted, all pages are extracted.
+     * Specific page indexes to extract from the document (0-based whole numbers). If omitted or empty, all
+     * pages are extracted. Duplicates are collapsed, order does not matter, and a selection containing no
+     * whole page number at all is rejected.
+     *
+     * An index past the end of the document is ignored, and a selection naming only such indexes is
+     * rejected — but only where the document is read here. Extracting a PDF *by URL* through an OCR
+     * provider hands it over without reading it, so its length is unknown and what an out-of-range index
+     * does is up to that provider. Upload the file instead to have the whole selection checked.
      */
     pageIndexes?: number[];
     /**

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

@@ -1,6 +1,6 @@
 import { IntegrationId } from './communication.public-types';
 /** List of all integration types supported by Squid. */
-export declare const INTEGRATION_TYPES: readonly ["active_directory", "ai_agents", "ai_chatbot", "algolia", "alloydb", "api", "auth0", "bedrock", "azure_blob", "azure_cosmosdb", "azure_postgresql", "azure_sql", "bigquery", "built_in_azure_blob", "built_in_db", "built_in_gcs", "built_in_queue", "built_in_s3", "cassandra", "clickhouse", "cloudsql", "cockroach", "cognito", "connected_knowledgebases", "confluence", "confluent", "datadog", "db2", "descope", "documentdb", "azure-entra-external-id", "dynamodb", "elasticsearch", "firebase_auth", "firestore", "gcs", "github", "google_calendar", "google_docs", "google_drive", "graphql", "hubspot", "jira", "jira_jsm", "jwt_hmac", "jwt_rsa", "kafka", "keycloak", "linear", "mariadb", "monday", "mongo", "mssql", "databricks", "mysql", "newrelic", "okta", "onedrive", "outlook", "oracledb", "pinecone", "postgres", "redis", "s3", "salesforce", "sap_hana", "sentry", "snowflake", "spanner", "xata", "zendesk", "servicenow_csm", "freshdesk", "mail", "slack", "mcp", "a2a", "legend", "teams", "openai_compatible", "openai_compatible_embedding", "sharepoint", "vertex"];
+export declare const INTEGRATION_TYPES: readonly ["active_directory", "ai_agents", "ai_chatbot", "algolia", "alloydb", "api", "auth0", "bedrock", "azure_blob", "azure_cosmosdb", "azure_postgresql", "azure_sql", "bigquery", "bitbucket", "built_in_azure_blob", "built_in_db", "built_in_gcs", "built_in_queue", "built_in_s3", "cassandra", "clickhouse", "cloudsql", "cockroach", "cognito", "connected_knowledgebases", "confluence", "confluent", "datadog", "db2", "descope", "documentdb", "azure-entra-external-id", "dynamodb", "elasticsearch", "firebase_auth", "firestore", "gcs", "github", "google_calendar", "google_docs", "google_drive", "graphql", "hubspot", "jira", "jira_jsm", "jwt_hmac", "jwt_rsa", "kafka", "keycloak", "linear", "mariadb", "monday", "mongo", "mssql", "databricks", "mysql", "newrelic", "okta", "onedrive", "outlook", "oracledb", "pinecone", "postgres", "redis", "s3", "salesforce", "sap_hana", "sentry", "snowflake", "spanner", "xata", "zendesk", "servicenow_csm", "freshdesk", "mail", "slack", "mcp", "a2a", "legend", "teams", "openai_compatible", "openai_compatible_embedding", "sharepoint", "vertex"];
 /**
  * @category Database
  */
@@ -9,6 +9,12 @@ export declare const DATA_INTEGRATION_TYPES: readonly ["bigquery", "built_in_db"
  * @category Auth
  */
 export declare const AUTH_INTEGRATION_TYPES: readonly ["auth0", "jwt_rsa", "jwt_hmac", "cognito", "okta", "keycloak", "descope", "firebase_auth", "azure-entra-external-id"];
+/**
+ * Auth integration types that can OAuth-protect an MCP server (see `McpOAuthOptions` and
+ * `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"];
 /** Supported integration types for GraphQL-based services. */
 export declare const GRAPHQL_INTEGRATION_TYPES: readonly ["graphql"];
 /** Supported integration types for HTTP-based services. */