@squidcloud/client 1.0.488 → 1.0.490

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

@@ -1,4 +1,4 @@
-import { AgentContextRequest, AiChatModelSelection, UpsertContextStatusError } from './ai-agent.public-types';
+import { AgentContextRequest, AiChatModelSelection, AiReasoningEffort, ContextImageFailure, UpsertContextStatusError } from './ai-agent.public-types';
 import { AiEmbeddingsModelSelection, AiRerankProvider } from './ai-common.public-types';
 import { AiContextId, AiKnowledgeBaseId, AppId } from './communication.public-types';
 import { DocumentExtractionMethod } from './extraction.public-types';
@@ -44,8 +44,8 @@ export interface AiKnowledgeBase {
     graphRag?: AiKnowledgeBaseGraphConfig;
     /**
      * Default RAG strategy for newly ingested contexts; a per-request `options.ragType` overrides it.
-     * Omitted ⇒ the server default (`'basic'`). Changing it affects future ingests only — existing chunks
-     * are not re-processed.
+     * Omitted ⇒ the server default (`'contextual'`). Changing it affects future ingests only — existing
+     * chunks are not re-processed.
      */
     ragType?: AiRagType;
     /**
@@ -54,9 +54,56 @@ export interface AiKnowledgeBase {
      * store. Under the combined-ingest strategy this stays ≈0 — growth is a visible fallback-rate signal.
      */
     contextualIngestUsage?: KnowledgeBaseGraphUsage;
+    /**
+     * Per-caller access control over retrieval. Omitted ⇒ `'none'`: stored scopes are ignored and every
+     * caller sees every chunk.
+     */
+    accessControl?: AiKnowledgeBaseAccessControl;
     /** The timestamp the knowledge base was last updated */
     updatedAt: Date;
 }
+/**
+ * The access-control modes a knowledge base can be in. See {@link AiKnowledgeBaseAccessControl}.
+ * @category AI
+ */
+export declare const AI_KB_ACCESS_CONTROL_MODES: readonly ["none", "enforced"];
+/**
+ * A knowledge base access-control mode. See {@link AI_KB_ACCESS_CONTROL_MODES}.
+ * @category AI
+ */
+export type AiKnowledgeBaseAccessControlMode = (typeof AI_KB_ACCESS_CONTROL_MODES)[number];
+/**
+ * Restricts what a search returns to the content its caller is entitled to.
+ *
+ * Under `'enforced'`, every chunk carries the access scopes of the context it came from, the caller is
+ * resolved to the scopes they hold, and the two are intersected inside the vector query — so a caller
+ * never retrieves a chunk they hold no scope for. A chunk stamped as public is visible to everyone; a
+ * chunk with no scopes at all (ingested before access control was enabled) is visible to no one.
+ *
+ * Enforcement covers retrieval channels that can apply the scope predicate. The raw-text scan (`grep`)
+ * and knowledge-graph (`queryGraph`, `searchMode: 'graph'`) channels read stores that carry no scopes,
+ * so an enforced knowledge base refuses them rather than answering unfiltered.
+ *
+ * Mutable, but enabling it on a populated knowledge base hides everything already ingested until those
+ * contexts are re-ingested with scopes.
+ *
+ * @category AI
+ */
+export interface AiKnowledgeBaseAccessControl {
+    /** `'none'` (the default) ignores stored scopes entirely; `'enforced'` intersects them per caller. */
+    mode: AiKnowledgeBaseAccessControlMode;
+    /**
+     * The backend function that resolves a caller into the access scopes they hold, as
+     * `'ServiceName:functionName'`. It runs once per search, receives a `ResolveKbScopesContext` and
+     * returns the scopes as an array of strings. Required under `'enforced'`.
+     *
+     * An `'enforced'` knowledge base whose function is not deployed fails every search rather than
+     * falling back to an unfiltered one.
+     *
+     * @pattern ^[^:]+:[^:]+$
+     */
+    scopeResolver?: string;
+}
 /**
  * Represents a field in an AI knowledge base metadata.
  */
@@ -225,6 +272,13 @@ export interface AiKnowledgeBaseGraphPathFacetConfig {
     /** Path segment separator. Defaults to `'/'`. */
     separator?: string;
 }
+/**
+ * The canonical declaration of {@link FOLDER_PATH_METADATA_FIELD_NAME}, shared by every writer that
+ * declares it on a knowledge base. `llmExtraction` is off, so a missing folder path stays absent
+ * instead of being guessed from document content.
+ * @category AI
+ */
+export declare const FOLDER_PATH_METADATA_FIELD: AiKnowledgeBaseMetadataField;
 /** A single entity surfaced in a graph search's {@link AiKnowledgeBaseGraphContext}. @category AI */
 export interface AiKnowledgeBaseGraphContextEntity {
     /** Canonical display name of the entity. */
@@ -271,6 +325,11 @@ export interface AiKnowledgeBaseChatOptions {
     includeMetadata?: boolean;
     /** Which provider's reranker to use for reranking the context. Defaults to 'cohere'. */
     rerankProvider?: AiRerankProvider;
+    /**
+     * Minimum reranker relevance score a chunk must reach to stay once at least 10 chunks are already kept.
+     * Defaults to 0.2. Lets an eval tune the drop threshold per reranker, whose score ranges differ.
+     */
+    rerankScoreThreshold?: number;
     /** The maximum number of results to return. Defaults to 30 */
     limit?: number;
     /** How many chunks to look over. Defaults to 100 */
@@ -452,6 +511,18 @@ export interface BaseAiKnowledgeBaseContextRequest {
     type: AiKnowledgeBaseContextType;
     /** Optional metadata associated with the context item. */
     metadata?: AiContextMetadata;
+    /**
+     * Access scopes granting read access to this context, stamped onto every chunk it produces. Only
+     * meaningful on a knowledge base with `accessControl.mode: 'enforced'`, where a caller retrieves the
+     * context only if they hold at least one of these scopes.
+     *
+     * Supplied here rather than through a follow-up call so a restricted context is never briefly
+     * readable by everyone between being indexed and being scoped. Omitted on a re-ingest keeps whatever
+     * scopes the context already had; an empty array makes it visible to every caller.
+     *
+     * Scopes are opaque strings the resolver and the ingest side agree on. The `__` prefix is reserved.
+     */
+    scopes?: Array<string>;
 }
 /**
  * Base options for upserting text content into the AI agent's context.
@@ -571,6 +642,34 @@ export interface AiKnowledgeBaseFileContextRequest extends BaseAiKnowledgeBaseCo
  * @category AI
  */
 export declare const BULK_INGESTION_MAX_MULTIPART_FILE_BYTES: number;
+/**
+ * Largest single file the platform's upload endpoints accept, per file: the multer limit core applies
+ * to every file-upload route (`COMMON_FILE_UPLOAD_OPTIONS`). By definition it also caps a bulk-ingestion
+ * source object, whichever way its bytes arrive: core re-enforces it on every staged object — rejecting
+ * the whole staging batch with the oversized object — so a staging caller pre-parks larger files.
+ * @category AI
+ */
+export declare const MAX_UPLOAD_FILE_BYTES: number;
+/**
+ * Embedding models the bulk-ingestion (batch embeddings) lane admits. A model needs a provider batch
+ * adapter to be listed here, but an adapter alone is not enough: a route is listed only once every core
+ * pod can take it, because a pod on an older image routes a job it cannot place to the wrong provider.
+ * This list IS that switch — adding a model here opens its route everywhere at once.
+ *
+ * Public and shared deliberately: `bulkUpsertContexts` answers a batch-transport job on any other model
+ * with a 501, but `createBulkUploadUrls` resolves no base at all, so a caller that stages before it upserts
+ * learns of the refusal only once the bytes are already uploaded. A caller that knows this bound can check
+ * the base up front and refuse the request instead — which only works while this list says what the
+ * deployment will really take. A base on an unlisted model keeps ingesting on the sync transport.
+ * @category AI
+ */
+export declare const BULK_INGESTION_EMBEDDING_MODELS: readonly ["text-embedding-3-small", "voyage-3-large", "voyage-4-large", "voyage-4"];
+/**
+ * Whether `model` is one of {@link BULK_INGESTION_EMBEDDING_MODELS}. Takes any embedding model selection
+ * (an integration-backed model spec is an object and is never supported).
+ * @category AI
+ */
+export declare function isBulkIngestionEmbeddingModel(model: unknown): model is (typeof BULK_INGESTION_EMBEDDING_MODELS)[number];
 /**
  * @category AI
  */
@@ -600,6 +699,11 @@ export interface AiKnowledgeBaseSearchOptions {
     limit?: number;
     /** Which provider's reranker to use for reranking the context. Defaults to 'cohere'. */
     rerankProvider?: AiRerankProvider;
+    /**
+     * Minimum reranker relevance score a chunk must reach to stay once at least 10 chunks are already kept.
+     * Defaults to 0.2. Lets an eval tune the drop threshold per reranker, whose score ranges differ.
+     */
+    rerankScoreThreshold?: number;
     /** How many chunks to look over. Defaults to 100 */
     chunkLimit?: number;
     /** Which chat model to use when asking the question */
@@ -668,6 +772,25 @@ export interface UpsertKnowledgeBaseContextResponse {
      * singular counterpart of {@link UpsertKnowledgeBaseContextsResponse.graphIndexingSkippedContextIds}.
      */
     graphIndexingSkipped?: boolean;
+    /**
+     * First images (capped) the context lacks a description for because describing them failed; the context
+     * is otherwise fully ingested. Absent when every image succeeded. `imageFailureCount` is the total.
+     */
+    imageFailures?: Array<ContextImageFailure>;
+    /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
+    imageFailureCount?: number;
+}
+/**
+ * The failed images of one context in a multi-context upsert.
+ * @category AI
+ */
+export interface UpsertContextImageFailures {
+    /** The context the images belong to. */
+    contextId: AiContextId;
+    /** First failed images (capped); `imageFailureCount` is the total. */
+    imageFailures: Array<ContextImageFailure>;
+    /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
+    imageFailureCount: number;
 }
 /**
  * Response structure for upserting contexts for an AiKnowledgeBase
@@ -692,6 +815,12 @@ export interface UpsertKnowledgeBaseContextsResponse {
      * caller can report the graph-coverage gap. Absent/empty when nothing was skipped or graph is disabled.
      */
     graphIndexingSkippedContextIds?: Array<AiContextId>;
+    /**
+     * Per stored context, the images that lack a description because describing them failed; each such
+     * context is otherwise fully ingested. A context that failed outright lists its images on its entry in
+     * `failures` instead. Absent when every image succeeded.
+     */
+    imageFailures?: Array<UpsertContextImageFailures>;
 }
 /**
  * Request structure for searching an AiKnowledgeBase
@@ -848,6 +977,11 @@ export interface BaseAiKnowledgeBaseSearchContextsRequest {
     rerank?: boolean;
     /** Which chat model to use when doing reranking */
     chatModel?: AiChatModelSelection;
+    /**
+     * Reasoning effort of the reranking model. A score needs little thought, so `'low'` is the usual
+     * choice; when unset the model applies its own default.
+     */
+    rerankReasoningEffort?: AiReasoningEffort;
 }
 /**
  * Request structure for searching AI contexts in the AiKnowledgeBase with prompt.
@@ -1099,6 +1233,14 @@ export interface GetKnowledgeBaseGraphStatusResponse {
      * is pending. Recomputed per poll — it moves forward while ingest activity continues.
      */
     nextAutoBuildAt?: number;
+    /**
+     * True when graph-scoped search (`graphFilter.underConcept`) runs on the index-native denormalized
+     * `conceptIds` pre-filter: the backend's search indexes serve the field AND the chunk copies are in
+     * sync with the doc nodes. False while either half is not ready (index still building, or a rebuild
+     * is in flight — a rebuild drops the sync gate for its duration); scoped search then uses the
+     * capped contextId-closure fallback. Absent when GraphRAG is disabled.
+     */
+    conceptScopeReady?: boolean;
 }
 /** The most recent graph backfill/rebuild job of a knowledge base. @category AI */
 export interface KnowledgeBaseGraphBuildJob {
@@ -1291,6 +1433,8 @@ export interface KnowledgeBaseGraphTopic {
     parentId?: string;
     /** Documents under the topic, when tracked. */
     docCount?: number;
+    /** Members of the topic: entities at level 0, child topics at higher levels. */
+    memberCount?: number;
 }
 /**
  * An aggregated relationship edge between two leaf topics: how many entity relationships cross
@@ -1359,6 +1503,8 @@ export interface KnowledgeBaseGraphQueryMatch {
     description?: string;
     /** Documents under the node, where tracked (topics and facet nodes). */
     docCount?: number;
+    /** Topics: members of the node (entities at level 0, child topics at higher levels). */
+    memberCount?: number;
 }
 /** A node in a `subtree` response: the resolved node with its children, recursively. @category AI */
 export interface KnowledgeBaseGraphQuerySubtreeNode {
@@ -1463,6 +1609,16 @@ export interface QueryKnowledgeBaseGraphResponse {
  * @category AI
  */
 export interface BulkIngestionContext {
+    /**
+     * The id of the context. Optional: when omitted, the server generates one and rejects the upload if
+     * another context in the knowledge base already holds identical content (content-level dedup). Provide
+     * an explicit id to address a specific context — that overwrites it unconditionally and allows duplicate
+     * content across different ids, exactly as the synchronous `upsertContexts` treats a supplied id. Must
+     * be unique within one request (each staged context becomes one per-file row keyed by this id), at most
+     * 512 UTF-8 bytes of letters, digits, `_`, `.`, `:`, `@` or `-` only, and the overwrite lands
+     * asynchronously when the job finalizes the file.
+     */
+    contextId?: AiContextId;
     /** `'text'` (the default) stages a text context; `'file'` consumes the next uploaded file positionally. */
     type?: 'text' | 'file';
     /** Title for a text context (required); optional display title for a file context. */
@@ -1489,6 +1645,14 @@ export interface BulkIngestionContext {
      * knowledge base's `metadataFields` schema when one is declared.
      */
     metadata?: Record<string, unknown>;
+    /**
+     * Access scopes granting read access to this context, stamped onto every chunk it produces when the
+     * job finalizes; mirrors {@link BaseAiKnowledgeBaseContextRequest.scopes}, with the same semantics:
+     * omitted keeps whatever scopes the context already had, an empty array makes it visible to every
+     * caller. On a knowledge base with `accessControl.mode: 'enforced'`, a context whose scopes resolve
+     * to nothing at finalize is stamped unreadable rather than public.
+     */
+    scopes?: Array<string>;
 }
 /**
  * Request structure for staging contexts through bulk ingestion: a durable, asynchronous lane that
@@ -1516,12 +1680,17 @@ export interface BulkIngestionUpsertContextsResponse {
      */
     contextIds: Array<string>;
     /**
-     * Contexts rejected because the knowledge base already holds identical content — either stored under an
-     * existing context or accepted earlier in this same call. Absent when nothing was rejected.
+     * Contexts rejected because the knowledge base already holds identical content — either stored under
+     * an existing context or accepted earlier in this same call. Absent when nothing was rejected.
      *
      * Same shape and `errorCode: 'DUPLICATE_CONTENT'` the synchronous `upsertContexts` returns, so a caller
      * handles a duplicate identically on both lanes. These contexts are NOT part of the job: they are not
      * extracted, not staged, and never appear in its per-file statuses.
+     *
+     * Covers TEXT contexts and MULTIPART file contexts (their bytes are in hand at staging). A file staged
+     * by `stagedObjectKey` is the one exception: its bytes are first read by the deferred extraction pass,
+     * so its duplicate surfaces asynchronously as a failed file with `errorCode: 'DUPLICATE_CONTENT'` in
+     * the job's per-file statuses instead.
      */
     duplicates?: Array<UpsertContextStatusError>;
 }
@@ -1563,6 +1732,48 @@ export interface BulkIngestionFileStatus {
     status: 'processing' | 'completed' | 'failed';
     /** Present only when status is 'failed': the terminal failure reason. */
     errorMessage?: string;
+    /**
+     * Machine-readable class of a failed file, for outcomes to treat differently from real failures.
+     * `'DUPLICATE_CONTENT'` marks a duplicate found by the deferred extraction pass (a presigned
+     * object's bytes are first read there) — a skip, not a failure: the KB already holds this content.
+     * Additive; absent for ordinary failures.
+     */
+    errorCode?: 'DUPLICATE_CONTENT';
+    /**
+     * First images (capped) the context lacks a description for because describing them failed; a
+     * `completed` file is otherwise fully ingested. Absent when every image succeeded.
+     */
+    imageFailures?: Array<ContextImageFailure>;
+    /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
+    imageFailureCount?: number;
+}
+/**
+ * One provider batch created for a bulk-ingestion job, so a caller can tell a job waiting on a
+ * submitted provider batch (healthy — the designed cost/latency tradeoff of the batch lane, with
+ * turnaround up to 24 hours) from a job that is actually stuck, and see since when.
+ * @category AI
+ */
+export interface BulkIngestionProviderBatchStatus {
+    /** The provider running the batch. Mirrors the core batch row's union, like {@link state}. */
+    provider: 'openai' | 'anthropic' | 'mistral' | 'voyage';
+    /** The provider API the batch rides. Mirrors the core batch row's union, like {@link state}. */
+    endpoint: '/v1/embeddings' | '/v1/messages/batches' | '/v1/chat/completions' | '/v1/ocr';
+    /**
+     * The batch's lifecycle state: `intent` (created, not yet submitted), `submitted` (waiting on the
+     * provider), `ended` (provider finished, results not yet absorbed), or terminal
+     * (`reconciled`/`cancelled`/`failed`).
+     */
+    state: 'intent' | 'submitted' | 'ended' | 'reconciled' | 'cancelled' | 'failed';
+    /** The provider's own batch id; absent until the batch is submitted. */
+    providerBatchId?: string;
+    /** When the batch was created — the "since when has this been waiting" clock for an in-flight batch. */
+    createdAt: Date;
+    /**
+     * When the batch row was last written. NOT a state-transition time: the poller refreshes it on every
+     * poll of an in-flight batch, so on a healthy job it is always recent — it freezing means polling
+     * stopped, not that the batch is waiting. Read wait duration off {@link createdAt}.
+     */
+    updatedAt: Date;
 }
 /**
  * Response describing a bulk-ingestion job's current state and progress counts.
@@ -1571,10 +1782,55 @@ export interface BulkIngestionFileStatus {
 export interface BulkIngestionJobStatusResponse {
     /** The job's lifecycle state (e.g. running, completed, failed, cancelled). */
     state: string;
+    /**
+     * The job's execution transport: `'batch'` rides provider batches (half price, tails up to 24
+     * hours), `'sync'` executes inline within minutes. Decided at staging from the job's size, with one
+     * transition — a defer-eligible job whose OCR routing lands on the provider batch is promoted
+     * `'sync'` to `'batch'` — and held from then on. Descriptive metadata ONLY: it says how the job
+     * runs, never whether a batch is draining right now, so it must not gate any wait/timeout policy;
+     * that is {@link activeProviderBatchCount}. Optional on the wire: consumers must tolerate its
+     * absence.
+     */
+    transport?: 'batch' | 'sync';
+    /**
+     * The lanes a `'batch'` job ROUTES inline — at the synchronous price, within minutes — rather than onto a
+     * provider batch: `embeddings`, whose batches are too small for the discount to beat the queue tail.
+     * Absent when every lane batches, and on a `'sync'` job (every lane of which runs inline). The job's
+     * routing policy, not a record of what ran: a lane handed to the inline transport by a cancelled
+     * provider-batch tail executes inline without being named here. Descriptive metadata, like {@link transport}.
+     */
+    inlineLanes?: Array<'embeddings' | 'imageDescription' | 'spreadsheetSummary' | 'metadataExtraction'>;
     /** Progress counters aggregated from the job's files and logical requests. */
     counts: BulkIngestionJobStatusCounts;
-    /** Provider batch ids submitted for this job. */
+    /** Provider batch ids created for this job, across every batch state — including already-drained ones. */
     providerBatchIds: Array<string>;
+    /**
+     * Number of provider batches still in flight (created, submitted, or awaiting result reconciliation).
+     * THE deferral signal: work is draining through a provider batch right now exactly when this is
+     * positive — unlike {@link providerBatchIds}, which keeps terminal batches, and unlike
+     * {@link transport}, which is descriptive metadata. Optional on the wire: consumers must tolerate
+     * its absence.
+     */
+    activeProviderBatchCount?: number;
+    /**
+     * Per-batch detail for every provider batch of the job, so a caller can tell a healthy wait on a
+     * submitted provider batch from a stall — and see since when. A SUPERSET of
+     * {@link providerBatchIds}, not index-aligned with it: an `intent` batch appears here with no
+     * `providerBatchId` while that list omits it. Optional on the wire: consumers must tolerate its
+     * absence.
+     */
+    providerBatches?: Array<BulkIngestionProviderBatchStatus>;
+    /**
+     * Coarse answer to "what is this job doing right now": `awaiting-provider-batch` while the
+     * PROVIDER is working — an `intent` or `submitted` batch (deferred OCR included; it wins whatever stage the
+     * files carry) or batch-route work still queued for submission — `extracting` while files still
+     * await or undergo extraction with no submitted batch, and `indexing` otherwise (inline/flex
+     * requests executing, `ended` batches' results being absorbed, contexts being written — our own
+     * work, however long it takes). Present only while the job {@link state} is `running`; the other
+     * non-terminal states (`finalizing`, `cancelling`) already name what the job is doing. Optional on
+     * the wire: consumers must tolerate its absence.
+     */
+    phase?: 'extracting' | 'awaiting-provider-batch' | 'indexing';
     /** Per-file status, one entry per staged context (bounded by the job's file cap). */
     files: Array<BulkIngestionFileStatus>;
 }

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 ["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"];
+export declare const CONNECTOR_IDS: readonly ["bitbucket", "confluence", "cotomi", "essentials", "freshdesk", "generic_site_ingester", "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

@@ -1,7 +1,12 @@
 /**
  * The extraction method to use for processing documents.
+ *
+ * `legacy` extracts text and embedded images in-process without any external model call.
+ * `legacy_with_llm` extracts the same text, and additionally renders each page to a screenshot that is
+ * described by a vision model — covering content the text layer cannot carry (figures, layout, scanned
+ * regions) at the cost of one model call per page. Both run with no external OCR provider.
  */
-export type DocumentExtractionMethod = 'mistral_ocr' | 'legacy' | 'amazon_textract' | 'azure_document_intelligence';
+export type DocumentExtractionMethod = 'mistral_ocr' | 'legacy' | 'legacy_with_llm' | 'amazon_textract' | 'azure_document_intelligence';
 /**
  * Options for customizing how data is extracted from a document.
  */
@@ -51,6 +56,14 @@ export interface ExtractDataFromDocumentOptions {
      * URL-based extraction ignores it and never returns `documentMetadata`.
      */
     collectDocumentMetadata?: boolean;
+    /**
+     * Safety-net storage expiration (seconds) registered WITH the long-term upload of the original file,
+     * before its bytes land — so a process crash at any later point (mid-OCR, before the caller ever
+     * learns the path) leaves a self-collecting object instead of a permanent orphan. The caller that
+     * sets this owns clearing the expiration once it durably references the path; leaving it unset keeps
+     * the original permanent from the moment it uploads.
+     */
+    originalFileExpirationSeconds?: number;
 }
 /**
  * Request payload for extracting data from a document via URL.
@@ -74,6 +87,10 @@ export interface ExtractDataFromDocumentFileRequest {
      */
     options?: ExtractDataFromDocumentOptions;
 }
+/**
+ * What an extracted image depicts: an image embedded in the page, or a full-page screenshot.
+ */
+export type ExtractedImageKind = 'embedded' | 'fullPage';
 /**
  * Representation of an image extracted from a document, for use in generated content.
  */
@@ -90,6 +107,11 @@ export interface ExtractDataFromDocumentImage {
      * The base64-encoded image data, prefixed with its MIME type (e.g., data:image/png;base64,...).
      */
     imageBase64Url: string;
+    /**
+     * What the image depicts. Absent means `embedded`. Selects the description prompt — a page
+     * screenshot is described as a complement to the page's stored text, an embedded image in full.
+     */
+    kind?: ExtractedImageKind;
 }
 /**
  * A single extracted page from the document, including structured content and images.
@@ -262,6 +284,11 @@ export interface ExtractDataFromDocumentResponse {
      * Array of pages containing extracted data.
      */
     pages: Array<ExtractDataFromDocumentPage>;
+    /**
+     * Pages the OCR provider reported as processed (billed), when it reports one. Can exceed
+     * `pages.length` — a blank page is billed but returns no content.
+     */
+    ocrPagesProcessed?: number;
     /**
      * Path to the original file in cloud storage, if applicable.
      */

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", "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"];
+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", "azure-entra-id", "dynamodb", "elasticsearch", "firebase_auth", "firestore", "gcs", "generic_site_ingester", "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
  */
@@ -8,7 +8,7 @@ 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"];
+export declare const AUTH_INTEGRATION_TYPES: readonly ["auth0", "jwt_rsa", "jwt_hmac", "cognito", "okta", "keycloak", "descope", "firebase_auth", "azure-entra-external-id", "azure-entra-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
@@ -48,9 +48,17 @@ export interface IntegrationInfo<ConfigurationType = Record<string, any> | undef
     creationDate?: Date;
     /** The date when the integration was last updated. */
     updateDate?: Date;
+    /**
+     * When false, the integration is disabled: runtime access is rejected and sync jobs skip it.
+     * Absent means enabled on create; an update that omits it keeps the stored value, so re-enabling
+     * requires an explicit `enabled: true`.
+     */
+    enabled?: boolean | null;
     /** The configuration object for the integration, if any. */
     configuration: ConfigurationType;
 }
+/** Returns true when the integration is explicitly disabled. An absent or null `enabled` means enabled. */
+export declare function isIntegrationDisabled(integration: Pick<IntegrationInfo, 'enabled'>): boolean;
 /** Integration IDs used for built-in integrations by Squid. */
 export declare const SQUID_BUILT_IN_INTEGRATION_IDS: readonly [string, string, string];
 /** Returns true if ID is a built-in integration ID in Squid. */

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

@@ -10,6 +10,14 @@ export declare const SOURCE_CODE_MAX_SUPPLEMENTAL_INSTRUCTIONS_LENGTH = 20000;
 export declare const SOURCE_CODE_ANALYZER_MODELS: readonly ["claude-code", "codex"];
 /** Identifies a CLI provider available for source-code analysis. */
 export type SourceCodeAnalyzerModel = (typeof SOURCE_CODE_ANALYZER_MODELS)[number];
+/** Lists trusted source-cache lifecycle strategies. */
+export declare const SOURCE_CODE_CACHE_STRATEGIES: readonly ["reuse", "recreate"];
+/** Selects how source analysis manages its pod-local trusted cache. */
+export type SourceCodeCacheStrategy = (typeof SOURCE_CODE_CACHE_STRATEGIES)[number];
+/** Lists the repository capabilities available to the configured CLI agent. */
+export declare const SOURCE_CODE_EXECUTION_MODES: readonly ["read-only", "write"];
+/** Selects whether the configured CLI agent may modify and publish repository state. */
+export type SourceCodeExecutionMode = (typeof SOURCE_CODE_EXECUTION_MODES)[number];
 /** Lists supported source-control providers. */
 export declare const SOURCE_CONTROL_PROVIDERS: readonly ["github", "bitbucket"];
 /** Identifies a supported source-control provider. */
@@ -30,6 +38,10 @@ export interface AiAgentSourceCodeIntegrationOptions {
     analyzerReasoningEffort?: CanonicalReasoningEffort;
     /** Provides supplemental code-analysis instructions. */
     analyzerInstructions?: string;
+    /** Reuses the pod-local trusted cache by default or recreates it for every analysis. */
+    cacheStrategy?: SourceCodeCacheStrategy;
+    /** Inspects repositories by default or enables unrestricted repository work. */
+    executionMode?: SourceCodeExecutionMode;
 }
 /** Stores the immutable GitHub identity and access metadata for a selected repository. */
 export interface GitHubRepositoryConfiguration {

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

@@ -6,7 +6,9 @@ export interface WebAiSearchRequest {
     query: string;
     /**
      * When provided, restricts the web search to these domains (subdomains are included).
-     * Cited URLs in the response are guaranteed to belong to one of the listed domains.
+     * Cited URLs in the response are guaranteed to belong to one of the listed domains, as are the
+     * consulted ones — see {@link WebAiSearchResponse.consultedUrls} for which of the two Squid
+     * enforces itself.
      */
     allowedDomains?: Array<string>;
 }
@@ -27,6 +29,21 @@ export interface WebAiSearchResponse {
     markdownText: string;
     /** A list of cited URLs included in the search response. */
     citedUrls: Array<WebAiSearchCitedUrl>;
+    /**
+     * Pages the search opened while answering, whether or not the answer cites them. Empty when the
+     * search reached nothing.
+     *
+     * This is what the search did, where {@link citedUrls} is what the answer leans on: a model may
+     * open ten pages and find the fact on one, and it may answer so tersely ("2026-08-16") that it
+     * cites nothing at all. Read this to show where the answer was looked for, or to establish that a
+     * search happened; read {@link citedUrls} to attribute a claim.
+     *
+     * A {@link WebAiSearchRequest.allowedDomains} restriction is applied to this list by Squid rather
+     * than relied upon from the provider, since these pages are reported through a channel the
+     * provider does not document as filtered. Citations arrive already filtered, being drawn from a
+     * restricted answer.
+     */
+    consultedUrls: Array<string>;
 }
 /**
  * Request to fetch content from a URL.

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

@@ -19,6 +19,14 @@ export interface UpsertContextsOptions {
      */
     onUploaded?: () => void;
 }
+/**
+ * Options for retrieving a knowledge base context.
+ * @category AI
+ */
+export interface GetContextOptions {
+    /** The number of characters after which text is truncated. Optional */
+    truncateTextAfter?: number;
+}
 /**
  * A reference to an AI knowledge base.
  */
@@ -73,9 +81,11 @@ export declare class AiKnowledgeBaseReference {
      */
     listContextIds(): Promise<Array<AiContextId>>;
     /**
-     * Retrieves a specific context by its ID.
+     * Retrieves a specific context by its ID. Pass `truncateTextAfter: 0` to omit the context's `text`
+     * field from the response when only its metadata (e.g. `contentHash`) is needed — the stored text
+     * can be multiple MB, and truncating it avoids sending that payload back in full.
      */
-    getContext(contextId: string): Promise<AiKnowledgeBaseContext | undefined>;
+    getContext(contextId: string, options?: GetContextOptions): Promise<AiKnowledgeBaseContext | undefined>;
     /**
      * Deletes a specific context by its ID.
      */
@@ -84,6 +94,20 @@ export declare class AiKnowledgeBaseReference {
      * Deletes multiple contexts.
      */
     deleteContexts(contextIds: Array<string>): Promise<void>;
+    /**
+     * Replaces the access scopes that grant read access to a context.
+     *
+     * Only meaningful on a knowledge base with `accessControl.mode: 'enforced'`: a search then returns a
+     * context only when the caller holds at least one of its scopes. Passing an empty array makes the
+     * context visible to every caller.
+     *
+     * The refresh primitive for permissions that changed at the source without the document itself
+     * changing. Pass `scopes` on the upsert instead when ingesting, so a restricted context is never
+     * briefly readable by everyone.
+     *
+     * @returns how many of the context's chunks were rewritten.
+     */
+    setContextScopes(contextId: string, scopes: Array<string>): Promise<number>;
     /**
      * Adds or updates a single context.
      */
@@ -164,12 +188,16 @@ export declare class AiKnowledgeBaseReference {
      * spreadsheet rows verbatim, and matches characters rather than meaning. The pattern is always a
      * literal — regex metacharacters in it are escaped — and matching is case-insensitive.
      * `options.metadataFilter` scopes the scan to the contexts it admits before any text is matched.
+     * Refused on a knowledge base with `accessControl.mode: 'enforced'` — the raw text carries no access
+     * scopes, so the scan cannot be filtered per caller.
      */
     grep(pattern: string, options?: GrepKnowledgeBaseOptions): Promise<GrepKnowledgeBaseResponse>;
     /**
      * Queries the knowledge base's graph (documents, entities, themes, facets) through the closed op set
      * — overview / resolve / describe / subtree / docsUnder / conceptsOf / neighborhood / pathBetween /
-     * globalSummary. Requires `graphRag.enabled` on the knowledge base.
+     * globalSummary. Requires `graphRag.enabled` on the knowledge base. Refused on a knowledge base with
+     * `accessControl.mode: 'enforced'` — the graph carries no access scopes, so its answers cannot be
+     * filtered per caller.
      */
     queryGraph(request: Omit<QueryKnowledgeBaseGraphRequest, 'knowledgeBaseId'>): Promise<QueryKnowledgeBaseGraphResponse>;
     /**