@squidcloud/client 1.0.482 → 1.0.484

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-integrations.public-types.d.ts

@@ -1,3 +1,4 @@
+import { AiAgentMemoryOptions } from './ai-agent.public-types';
 import { AiQueryOptions } from './ai-query.public-types';
 import { AiAgentId } from './communication.public-types';
 /**
@@ -41,6 +42,12 @@ export interface AiApiOptions {
      * user prompt. Default 4.
      */
     maxIterations?: number;
+    /**
+     * Conversation memory configuration. When provided, prior user prompts and AI answers under the same `memoryId`
+     * are provided as additional context to the AI, enabling cross-prompt follow-ups
+     * Defaults to no memory.
+     */
+    memoryOptions?: AiAgentMemoryOptions;
 }
 /**
  * Configuration options for AI agent MCP integration.

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

@@ -677,6 +677,8 @@ 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 */
@@ -722,6 +724,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
@@ -843,6 +852,12 @@ export interface BaseUpsertContextStatus {
 export interface UpsertContextStatusSuccess extends BaseUpsertContextStatus {
     /** Whether the context upsert was successful or got an error. */
     status: 'success';
+    /**
+     * Set when the context was stored and is fully searchable (vector/keyword), but was NOT graph-indexed
+     * because the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent;
+     * surfaced so bulk operations can report which contexts fell outside the graph.
+     */
+    graphIndexingSkipped?: boolean;
 }
 /**
  * Machine-readable code identifying a specific upsert failure reason.
@@ -939,7 +954,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;
@@ -1056,6 +1077,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

@@ -8,7 +8,7 @@ export declare const RERANK_PROVIDERS: readonly ["cohere", "none"];
  */
 export type AiRerankProvider = (typeof RERANK_PROVIDERS)[number];
 /** List of available AI provider types. See AiProviderType. */
-export declare const AI_PROVIDER_TYPES: readonly ["anthropic", "bedrock", "claude-code", "codex", "cohere", "flux", "gemini", "openai", "grok", "stability", "voyage", "mistral", "textract", "vertex", "external"];
+export declare const AI_PROVIDER_TYPES: readonly ["anthropic", "bedrock", "claude-code", "codex", "cohere", "flux", "gemini", "openai", "openai-compatible", "grok", "stability", "voyage", "mistral", "textract", "vertex", "external"];
 /**
  * Type of the AI provider.
  * References a single AI service, regardless of the model or other AI function it provides (like
@@ -29,7 +29,7 @@ export declare const OPENAI_CHAT_MODEL_NAMES: readonly ["gpt-5.4-mini", "gpt-5.4
  * Public Gemini chat model names (active models only).
  * @category AI
  */
-export declare const GEMINI_CHAT_MODEL_NAMES: readonly ["gemini-3.1-pro", "gemini-3.5-flash", "gemini-3.1-flash-lite"];
+export declare const GEMINI_CHAT_MODEL_NAMES: readonly ["gemini-3.1-pro", "gemini-3.6-flash", "gemini-3.5-flash-lite"];
 /**
  * Public Grok chat model names (active models only).
  * @category AI
@@ -39,12 +39,12 @@ export declare const GROK_CHAT_MODEL_NAMES: readonly ["grok-4.3", "grok-4-1-fast
  * Public Anthropic chat model names (active models only).
  * @category AI
  */
-export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-haiku-4-5-20251001", "claude-opus-4-8", "claude-sonnet-5"];
+export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-haiku-4-5-20251001", "claude-opus-5", "claude-sonnet-5"];
 /**
  * The supported AI model names.
  * @category AI
  */
-export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "claude-haiku-4-5-20251001", "claude-opus-4-8", "claude-sonnet-5", "gemini-3.1-pro", "gemini-3.5-flash", "gemini-3.1-flash-lite", "grok-4.3", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
+export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "claude-haiku-4-5-20251001", "claude-opus-5", "claude-sonnet-5", "gemini-3.1-pro", "gemini-3.6-flash", "gemini-3.5-flash-lite", "grok-4.3", "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

@@ -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;
@@ -634,6 +645,12 @@ export interface AiKnowledgeBaseSearchResultChunk {
 export interface UpsertKnowledgeBaseContextResponse {
     /** List of the upsert status of each item sent in the request. */
     failure?: UpsertContextStatusError;
+    /**
+     * Set when the context was stored (and is fully searchable via vector/keyword) but NOT graph-indexed
+     * because the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent; the
+     * singular counterpart of {@link UpsertKnowledgeBaseContextsResponse.graphIndexingSkippedContextIds}.
+     */
+    graphIndexingSkipped?: boolean;
 }
 /**
  * Response structure for upserting contexts for an AiKnowledgeBase
@@ -652,6 +669,12 @@ export interface UpsertKnowledgeBaseContextsResponse {
      * `undefined` at runtime — callers must handle its absence rather than trust it is always populated.
      */
     contextIds?: Array<AiContextId>;
+    /**
+     * Contexts that were stored (and are fully searchable via vector/keyword) but NOT graph-indexed because
+     * the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent; surfaced so a
+     * caller can report the graph-coverage gap. Absent/empty when nothing was skipped or graph is disabled.
+     */
+    graphIndexingSkippedContextIds?: Array<AiContextId>;
 }
 /**
  * Request structure for searching an AiKnowledgeBase
@@ -665,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/ai-query.public-types.d.ts

@@ -214,6 +214,12 @@ export interface AiSpreadsheetQueryOptions {
     instructions?: string;
     /** Overrides the model used to answer the query. */
     model?: AiChatModelName;
+    /**
+     * Background gathered by the calling agent (facts from retrieved chunks, chat history, or earlier
+     * spreadsheet queries in the same conversation). Injected into the sub-agent's prompt as reference
+     * data — not as instructions — so it starts oriented instead of rediscovering the caller's context.
+     */
+    context?: string;
 }
 /**
  * Request for executing an AI-powered query over spreadsheet files.

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[];
     /**
@@ -121,6 +128,116 @@ export interface SpreadsheetSheetInfo {
      * Number of columns in the sheet.
      */
     columnCount: number;
+    /**
+     * Present and true when the sheet is hidden (or very-hidden) in the workbook. Hidden sheets are
+     * extracted like visible ones; the flag lets downstream surfaces say so. Omitted for visible
+     * sheets to keep the stored inventory JSON compact.
+     */
+    hidden?: boolean;
+    /** Cells whose value is computed by a formula. Omitted when zero, keeping the stored JSON compact. */
+    formulaCellCount?: number;
+    /** Merged ranges declared on the sheet. Omitted when zero. */
+    mergedRangeCount?: number;
+    /**
+     * Sheet-qualified references to this sheet from formulas on OTHER VISIBLE sheets. Omitted when
+     * zero. Raw evidence of "a live sheet reads this one", which is why references from hidden sheets
+     * are excluded — those are reported through {@link disconnected}, which walks them transitively.
+     */
+    inboundRefCount?: number;
+    /**
+     * Sheet-qualified references from this sheet's formulas to other sheets OF THIS WORKBOOK. Omitted
+     * when zero. External references (`[Book.xlsx]Sheet1!A1`) are not counted — except in a legacy
+     * .xls, whose formula text does not mark them (see {@link disconnected}), so a reference into
+     * another workbook's same-named sheet counts here.
+     */
+    outboundRefCount?: number;
+    /** Formulas on the sheet containing a `#REF!` error, the signature of deleted precedents. Omitted when zero. */
+    refErrorCount?: number;
+    /**
+     * Present and true when the sheet is hidden AND takes no part in the workbook's live dependency
+     * graph: nothing the live model reads leads to it, and it reads no visible sheet itself.
+     *
+     * Reachability, not adjacency: a hidden sheet read by another hidden sheet that a visible sheet
+     * reads is live, and the walk crosses as many hidden hops as the workbook has. It follows the READ
+     * direction only. A hidden staging or print sheet that merely reads the live model — downstream of
+     * it, not orphaned from it — is spared by that second clause, but sparing it does not spare what
+     * feeds IT: were liveness to flow backwards, one legacy tab still pointing at the current dashboard
+     * would carry its whole cluster of stale detail sheets back into the live set.
+     *
+     * Deliberately conservative on two further counts. It is never asserted for visible sheets, which
+     * are orphaned by design far more often than not (cover pages, chart tabs, mapping tables). And it
+     * remains a heuristic for "legacy", not a proof: `INDIRECT()`, defined-name and VBA/Power Query
+     * references are all invisible to a formula scan, so a hidden sheet reached only that way is a
+     * false positive. Consumers should present it as the evidence it is, never as a verdict.
+     *
+     * It is also under-reported in the legacy .xls container, where a parsed external reference keeps
+     * only the other workbook's sheet NAME: a link to the model this file was copied from can be
+     * credited to that file's own leftover copy of the sheet and spare it the flag. Missing orphans
+     * that way, never inventing them, is the direction this signal can afford to be wrong in.
+     */
+    disconnected?: boolean;
+    /**
+     * Up to a few representative formulas ("C5=SUM(B2:B4)") for the summary preview. NOT persisted in
+     * the bounded inventory JSON — preview-time only.
+     */
+    formulaSample?: Array<string>;
+}
+/**
+ * Workbook-level parts the per-sheet CSV dump cannot express, counted from the container index so
+ * the summary can SAY what it cannot show (chart-locked figures, pivot views, staleness of
+ * external-workbook cached values). Every field is omitted when zero/false.
+ */
+export interface SpreadsheetWorkbookFeatures {
+    /** Charts embedded in the workbook; chart data is not extracted. */
+    chartCount?: number;
+    /** Pivot tables; their computed views are not extracted. */
+    pivotTableCount?: number;
+    /** External-link parts (other workbooks, DDE, or OLE); linked cells carry last-cached values that may be stale. */
+    externalLinkCount?: number;
+    /** Sheets carrying cell comments/notes (not extracted). */
+    commentPartCount?: number;
+    /** The workbook contains VBA macros. */
+    hasVbaMacros?: boolean;
+}
+/** One data series of a chart, with its cached categories and values. */
+export interface SpreadsheetChartSeries {
+    /** The series name. */
+    name?: string;
+    /** The categories (x-axis labels) for the series. */
+    categories: Array<string>;
+    /** The numeric values for the series. */
+    values: Array<number>;
+    /**
+     * The series' true cached point count, present ONLY when extraction retained fewer points than the
+     * series actually declares. Without it, a consumer cannot tell a complete 8-point series apart from
+     * the first 8 points of a 12-point one, and would describe a January-December series as ending in
+     * August.
+     */
+    totalPointCount?: number;
+}
+/** One chart's cached content. Cached values are what the chart last rendered; formulas are not evaluated. */
+export interface SpreadsheetChartInfo {
+    /** The chart's title, when it declares one. */
+    title?: string;
+    /** The worksheet the chart is anchored to, when the relationship graph resolves it. */
+    sheetName?: string;
+    /** The chart's data series, in declaration order. */
+    series: Array<SpreadsheetChartSeries>;
+    /**
+     * The chart's true series count, present ONLY when extraction retained fewer series than the chart
+     * actually declares — so an omitted-series count is computed against what the chart HAS, not against
+     * what survived extraction's own cap.
+     */
+    totalSeriesCount?: number;
+}
+/** One pivot table's identity and fields. Displayed aggregates are NOT extracted — only what it is built from. */
+export interface SpreadsheetPivotInfo {
+    /** The pivot table name. */
+    name?: string;
+    /** The worksheet the pivot table is anchored to. */
+    sheetName?: string;
+    /** The field names used in the pivot table. */
+    fields: Array<string>;
 }
 /**
  * Structural information about a parseable spreadsheet document.
@@ -130,6 +247,12 @@ export interface SpreadsheetDocumentInfo {
      * The sheets of the spreadsheet, in workbook order.
      */
     sheets: Array<SpreadsheetSheetInfo>;
+    /** Workbook-level parts the CSV dump cannot express (best-effort; absent for CSV/TSV and .xls). */
+    features?: SpreadsheetWorkbookFeatures;
+    /** Charts with their cached series (best-effort; absent for .xls and when none exist). */
+    charts?: Array<SpreadsheetChartInfo>;
+    /** Pivot tables with their field names (best-effort; absent for .xls/.xlsb and when none exist). */
+    pivots?: Array<SpreadsheetPivotInfo>;
 }
 /**
  * The full result of extracting data from a document, including all pages and any extracted images.

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