@squidcloud/client 1.0.491 → 1.0.493

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_aiSpendInputTokens_count", "squid_aiSpendOutputTokens_count", "squid_aiSpendReasoningTokens_count", "squid_aiSpendCacheReadTokens_count", "squid_aiSpendCacheWriteTokens_count", "squid_aiSpendPages_count", "squid_aiSpendImages_count", "squid_aiSpendAudioSeconds_count", "squid_aiSpendCharacters_count", "squid_aiSpendSearches_count", "squid_aiSpendCostUsd_count", "squid_aiImageGeneration_count", "squid_aiImageGeneration_time", "squid_aiRemoveBackground_count", "squid_aiRemoveBackground_time", "squid_aiAudioTranscribe_count", "squid_aiAudioTranscribe_time", "squid_aiAudioCreateSpeech_count", "squid_aiAudioCreateSpeech_time", "squid_aiVoiceCreateSession_count", "squid_aiVoiceCreateSession_time", "squid_aiVoiceAnswerOpenAiCall_count", "squid_aiVoiceAnswerOpenAiCall_time", "squid_aiVoiceStartOpenAiWebCall_count", "squid_aiVoiceStartOpenAiWebCall_time", "squid_aiOpenAiChatCompletions_count", "squid_aiOpenAiChatCompletions_time", "squid_aiIntegrationData_count", "squid_aiIntegrationData_time", "squid_aiIntegrationApi_count", "squid_aiIntegrationApi_time", "squid_apiControllerCall_count", "squid_apiControllerCall_time", "squid_aiContextUpsert_count", "squid_aiContextDelete_count", "squid_codeInitialization_count", "squid_codeInitialization_time", "squid_sourceCodeAnalysis_count", "squid_sourceCodeAnalysis_time", "squid_sourceCodeWorkspaceBytes_value", "squid_sourceCodeInputTokens_count", "squid_sourceCodeOutputTokens_count", "squid_deleteApiKey_count", "squid_deleteApiKey_time", "squid_deleteSecret_count", "squid_deleteSecret_time", "squid_discoverGraphQLConnectionSchema_count", "squid_discoverGraphQLConnectionSchema_time", "squid_discoverOpenApiSchema_count", "squid_discoverOpenApiSchema_time", "squid_discoverOpenApiSchemaFromFile_count", "squid_discoverOpenApiSchemaFromFile_time", "squid_executeBackendFunction_count", "squid_executeBackendFunction_time", "squid_apiControllerCall_count", "squid_apiControllerCall_time", "squid_getAiChatbotProfiles_count", "squid_getAiChatbotProfiles_time", "squid_getAllApiKeys_count", "squid_getAllApiKeys_time", "squid_getAllSecrets_count", "squid_getAllSecrets_time", "squid_getAppApiKey_count", "squid_getAppApiKey_time", "squid_getSecret_count", "squid_getSecret_time", "squid_graphql_count", "squid_graphql_time", "squid_graphqlQuery_count", "squid_graphqlQuery_time", "squid_integrationCount_value", "squid_mutate_count", "squid_mutate_time", "squid_metricQuery_count", "squid_metricQuery_time", "squid_metricReport_count", "squid_metricReport_time", "squid_nativeQuery_count", "squid_nativeQuery_time", "squid_openapi_count", "squid_openapi_time", "squid_produceTopicMessage_count", "squid_produceTopicMessage_time", "squid_query_count", "squid_query_time", "squid_queueMessageHandler_count", "squid_queueMessageHandler_time", "squid_registerQuery_count", "squid_registerQuery_time", "squid_rerankChunks_count", "squid_rerankChunks_time", "squid_schedulerJob_count", "squid_schedulerJob_time", "squid_eventHandler_count", "squid_eventHandler_time", "squid_schema_size", "squid_secrets_entries", "squid_storageDeleteFiles_count", "squid_storageDeleteFiles_time", "squid_storageGetDownloadUrl_count", "squid_storageGetDownloadUrl_time", "squid_storageGetFileMetadata_count", "squid_storageGetFileMetadata_time", "squid_storageListDirectoryContents_count", "squid_storageListDirectoryContents_time", "squid_storageUploadFile_count", "squid_storageUploadFile_time", "squid_subscribeToTopic_count", "squid_subscribeToTopic_time", "squid_testGraphQLConnection_count", "squid_testGraphQLConnection_time", "squid_testAgentProtocolConnection_count", "squid_testAgentProtocolConnection_time", "squid_trigger_count", "squid_trigger_time", "squid_upsertApiKey_count", "squid_upsertApiKey_time", "squid_upsertSecret_count", "squid_upsertSecret_time", "squid_vectorChunks_count", "squid_vectorChunks_time", "squid_webhook_count", "squid_webhook_time", "squid_acquireLock_count", "squid_acquireLock_time", "squid_releaseLock_count", "squid_releaseLock_time"];
+export 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-connection.public-types.d.ts

@@ -0,0 +1,34 @@
+import type { AiConnectedIntegrationMetadata } from './ai-agent.public-types';
+import type { AiAgentId, IntegrationId } from './communication.public-types';
+import type { IntegrationType } from './integration.public-types';
+/**
+ * Event type emitted whenever an agent's connection to an integration is created, changed or removed:
+ * connecting a connector in Agent Studio, editing its settings, or disconnecting it, through the console
+ * or the SDK. Subscribe with `@eventHandler(AI_AGENT_CONNECTION_EVENT_TYPE)`; the payload is an
+ * {@link AiAgentConnectionEvent}.
+ * @category AI
+ */
+export declare const AI_AGENT_CONNECTION_EVENT_TYPE = "ai-agent-connection-event";
+/**
+ * What happened to the connection.
+ * @category AI
+ */
+export type AiAgentConnectionChange = 'created' | 'changed' | 'deleted';
+/**
+ * The payload broadcast on {@link AI_AGENT_CONNECTION_EVENT_TYPE}.
+ * @category AI
+ */
+export interface AiAgentConnectionEvent {
+    /** The agent whose connection changed. */
+    agentId: AiAgentId;
+    /** The integration the connection points at. */
+    integrationId: IntegrationId;
+    /** Type of that integration. */
+    integrationType: IntegrationType;
+    /** Whether the connection was created, changed or deleted. */
+    change: AiAgentConnectionChange;
+    /** The connection after the change; absent when it was removed. */
+    connection?: AiConnectedIntegrationMetadata;
+    /** The connection before the change; absent when it was created. */
+    previousConnection?: AiConnectedIntegrationMetadata;
+}

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

@@ -1,5 +1,5 @@
 import { JSONSchema } from 'json-schema-typed';
-import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, CanonicalReasoningEffort, GeminiChatModelName, GrokChatModelName, ModelIdSpec, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat, OpenAiImageModelName } from './ai-common.public-types';
+import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, CanonicalReasoningEffort, EmbeddingModelIdSpec, GeminiChatModelName, GrokChatModelName, ModelIdSpec, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat, OpenAiImageModelName } 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';
@@ -883,6 +883,12 @@ export declare const AGENT_STATUS_TITLE_ACCESSING_KB = "Accessing Knowledge Base
  * @category AI
  */
 export declare const AGENT_STATUS_TITLE_CALLING_AI_FUNCTION = "Calling AI Function";
+/**
+ * Status update title broadcast when an AI function callable returns, carrying the function's raw
+ * result in the body. Nested under the matching {@link AGENT_STATUS_TITLE_CALLING_AI_FUNCTION} event.
+ * @category AI
+ */
+export declare const AGENT_STATUS_TITLE_AI_FUNCTION_RESULT = "AI Function Result";
 /**
  * Status update title broadcast when the agent invokes a knowledge-base metadata-inspection callable
  * (the opt-in `enableMetadataInspection` tool). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB}
@@ -1236,7 +1242,10 @@ export type AiPiiOptions = {
     entities?: Array<AiPiiEntityType>;
     /** App-specific PII in plain language, e.g. `'internal case numbers like CASE-12345'`. */
     customRules?: Array<string>;
-    /** Model performing the screening. Defaults to {@link DEFAULT_PII_CLASSIFIER_MODEL}. */
+    /**
+     * Model performing the screening. Defaults to {@link DEFAULT_PII_CLASSIFIER_MODEL}. Each attempt is
+     * bounded at a minute, so an override has to answer within it.
+     */
     classifierModel?: AiChatModelSelection;
     /** Literal values that never count as PII, e.g. a shared support address. */
     allowList?: Array<string>;
@@ -1503,3 +1512,25 @@ export interface ListChatModelsResponse {
     /** All chat models available to the application. */
     models: Array<ModelIdSpec>;
 }
+/**
+ * Request options for listing the embedding models a new knowledge base can be created on.
+ * @category AI
+ */
+export interface ListEmbeddingModelsRequest {
+    /**
+     * When true, deprecated vendor models (those with `replacedBy`) are included.
+     * Defaults to false (only active models are returned).
+     */
+    includeDeprecated?: boolean;
+}
+/**
+ * Response containing the embedding models a new knowledge base can be created on: Squid-provided
+ * vendor models and the application's custom integration models. Exactly one entry carries `isDefault`.
+ * Deprecated vendor models are included only when requested via `includeDeprecated` and are marked
+ * with `replacedBy`; an existing knowledge base keeps its model regardless.
+ * @category AI
+ */
+export interface ListEmbeddingModelsResponse {
+    /** All embedding models available to the application. */
+    models: Array<EmbeddingModelIdSpec>;
+}

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

@@ -259,6 +259,35 @@ export interface ModelIdSpec {
      */
     source?: AiModelSource;
 }
+/**
+ * An embedding model a new knowledge base can be created on. `modelId` alone is not an identity: an
+ * integration can serve the same model name as a vendor, so `(modelId, integrationId)` is.
+ * @category AI
+ */
+export interface EmbeddingModelIdSpec {
+    /** The embedding model ID used for API calls. */
+    modelId: string;
+    /** The integration ID if this model comes from an integration. Undefined for Squid-provided models. */
+    integrationId?: string;
+    /** The embedding dimensions, present for integration-based models. */
+    dimensions?: number;
+    /** Human-readable display name for the model. */
+    displayName: string;
+    /** Where the model comes from: 'vendor' (Squid-provided) or 'connector' (an integration configured on the app). */
+    source: AiModelSource;
+    /**
+     * Set only on a deprecated vendor model, which is listed on request: the model a new knowledge base
+     * asking for this one is created on. Undefined for active models.
+     */
+    replacedBy?: AiEmbeddingsModelName;
+    /** True on exactly one entry of a non-empty list: the model to create on when the caller has no preference. */
+    isDefault?: boolean;
+}
+/**
+ * The `embeddingModel` a knowledge base is created with for a listed model.
+ * @category AI
+ */
+export declare function embeddingModelSelectionOf(model: EmbeddingModelIdSpec): AiEmbeddingsModelSelection;
 /**
  * Type guard to check if a model selection is integration-based.
  * @category AI

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

@@ -222,10 +222,18 @@ export interface AiKnowledgeBaseGraphConfig {
     entityTypes?: string[];
     /**
      * Quiet window (milliseconds) after the last graph activity before the sweep auto-builds the
-     * structure. Must be a positive integer. Defaults to the server's window (5 minutes); the sweep
-     * cadence (1 minute) bounds how promptly an elapsed window is picked up.
+     * structure. Must be a positive integer, and is floored at 3 seconds — a shorter window is not
+     * servable. Defaults to the server's window (5 minutes); the sweep cadence (1 minute) bounds how
+     * promptly an elapsed window is picked up.
      */
     autoBuildDebounceMs?: number;
+    /**
+     * When true, the sweep does not start automatic structural builds for this KB: activity keeps arming
+     * the build, and the first quiet window after the flag is cleared runs it. Meant for an ingestion
+     * campaign whose builds an operator wants to schedule by hand; `rebuildGraph` stays available.
+     * Defaults to false.
+     */
+    autoBuildPaused?: boolean;
     /** Concept-layer (facet taxonomy) configuration. Omitted ⇒ `facets: 'auto'`. */
     concepts?: AiKnowledgeBaseGraphConceptsConfig;
 }
@@ -479,7 +487,8 @@ export interface AiKnowledgeBaseContext {
     metadata: AiContextMetadata;
     /**
      * Names of metadata fields whose stored values were machine-extracted from the content
-     * (driven by the knowledge base's `metadataFields` schema) rather than user-supplied.
+     * (driven by the knowledge base's `metadataFields` schema, plus the reserved `lastModified` key
+     * every knowledge base derives from the document container) rather than user-supplied.
      * On re-upsert/replay, extracted values count as not-supplied (re-extracted fresh) while
      * user-supplied values are preserved; consumers can also use this to caveat extracted values.
      */
@@ -650,26 +659,6 @@ export declare const BULK_INGESTION_MAX_MULTIPART_FILE_BYTES: number;
  * @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
  */
@@ -1180,8 +1169,10 @@ export interface GetKnowledgeBaseGraphStatusRequest {
 export interface GetKnowledgeBaseGraphStatusResponse {
     /** Whether GraphRAG is enabled on the KB. */
     enabled: boolean;
-    /** Number of entities in the KB's graph partition. */
+    /** Number of live entities in the KB's graph partition (quarantined ones excluded). */
     entityCount: number;
+    /** Entities hidden by a dead-weight quarantine run; absent when the KB's graph store cannot quarantine. */
+    quarantinedEntityCount?: number;
     /** Number of outgoing relationships (mirrors excluded). */
     relationshipCount: number;
     /** Number of communities detected (Phase 3), 0 when none. */
@@ -1217,8 +1208,18 @@ export interface GetKnowledgeBaseGraphStatusResponse {
     buildJob?: KnowledgeBaseGraphBuildJob;
     /** Lifetime LLM usage of incremental graph ingestion (per-upsert extraction), when any was recorded. */
     ingestUsage?: KnowledgeBaseGraphUsage;
-    /** LLM usage of the most recent `rebuildGraph` run (including its re-extraction), when one ran. */
+    /**
+     * LLM usage of the most recent COMPLETED `rebuildGraph` run (including its re-extraction), when one
+     * ran. A build in flight leaves it on the previous build until it completes — read
+     * {@link buildUsageHistory} for the in-flight run.
+     */
     lastRebuildUsage?: KnowledgeBaseGraphUsage;
+    /**
+     * Per-build LLM usage of the KB's most recent `rebuildGraph` runs, newest first, bounded to the last
+     * 50 builds. Unlike {@link lastRebuildUsage} no build erases another's record, so back-to-back builds
+     * are all accounted for.
+     */
+    buildUsageHistory?: Array<KnowledgeBaseGraphBuildUsage>;
     /**
      * Lifetime LLM usage of the combined contextual-blurb + graph-extraction call (run automatically for
      * `ragType:'contextual'` graph-enabled KBs), when any was recorded. Covers BOTH the contextual blurb
@@ -1241,6 +1242,63 @@ export interface GetKnowledgeBaseGraphStatusResponse {
      * capped contextId-closure fallback. Absent when GraphRAG is disabled.
      */
     conceptScopeReady?: boolean;
+    /** The incremental entity-resolution sweep's latest readings, present once a sweep has sampled the KB. */
+    resolution?: KnowledgeBaseGraphResolutionStatus;
+}
+/**
+ * Readings the incremental entity-resolution sweep persists on a knowledge base: the dirty backlog it
+ * drains across sweeps and the duplicate-name fragmentation it exists to merge.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphResolutionStatus {
+    /** Entities rewritten since the sweep last examined them. */
+    backlog: number;
+    /** When `backlog` was sampled (epoch millis) — the start or end of a sweep. */
+    backlogSampledAt: number;
+    /** Entities sharing another entity's significant-name-token signature; absent until a sweep sampled it. */
+    duplicateNames?: number;
+    /** When `duplicateNames` was sampled (epoch millis). */
+    duplicateNamesSampledAt?: number;
+    /** The most recent sweep: the bounds it ran under and what it got through; absent until one has run. */
+    lastSweep?: KnowledgeBaseGraphResolutionSweep;
+}
+/**
+ * One incremental entity-resolution sweep's bounds and counters, as persisted at its start (counters
+ * zero) and again at its end.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphResolutionSweep {
+    /** Dirty entities one pass of the sweep examined at most. */
+    dirtyBatch: number;
+    /** Drain rounds the sweep ran at most. */
+    maxRounds: number;
+    /** Candidate pairs one drain round of the sweep adjudicated at most. */
+    maxPairsPerRound: number;
+    /** Resolution passes one drain round of the sweep ran at most. */
+    maxPasses: number;
+    /** Adjudication calls the sweep kept in flight. */
+    adjudicationConcurrency: number;
+    /** Dirty entities one pass of the sweep searched candidates for at once. */
+    proposalConcurrency: number;
+    /** Drain rounds the sweep ran. */
+    rounds: number;
+    /** Dirty entities the sweep examined. */
+    examined: number;
+    /** Candidate pairs the sweep sent to adjudication. */
+    pairsAdjudicated: number;
+    /** Candidate pairs adjudication confirmed as the same entity. */
+    pairsConfirmed: number;
+    /** Adjudication calls the sweep made; absent on a reading from a sweep that did not record calls. */
+    adjudicationCalls?: number;
+    /** Of those, calls the provider served the instruction prefix from its prompt cache; absent with them. */
+    adjudicationCachedCalls?: number;
+    /**
+     * Index-visibility wait tokens the sweep spent: a count of waits, not a duration. Absent on a reading
+     * from a sweep that did not record waits.
+     */
+    visibilityWaits?: number;
+    /** When this reading was written (epoch millis). */
+    sampledAt: number;
 }
 /** The most recent graph backfill/rebuild job of a knowledge base. @category AI */
 export interface KnowledgeBaseGraphBuildJob {
@@ -1251,6 +1309,46 @@ export interface KnowledgeBaseGraphBuildJob {
     /** When the job was enqueued (epoch millis). */
     startedAt?: number;
 }
+/**
+ * LLM usage of one graph build (`rebuildGraph` run), kept per build so a later build cannot erase it.
+ * Accumulated across the run's execution attempts — a resumed rebuild adds to the same record.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphBuildUsage {
+    /** Identity of the build, stable across its execution attempts. */
+    buildId: string;
+    /** The plan the build executed; `'resolution'` is the internal resolution-only continuation. */
+    mode: KnowledgeBaseGraphRebuildMode | 'resolution';
+    /** The build's lifecycle state. */
+    status: 'in_progress' | 'completed' | 'failed';
+    /** When the build started (epoch millis). */
+    startedAt: number;
+    /** When the build reached a terminal state (epoch millis); absent while it runs. */
+    completedAt?: number;
+    /** Contexts whose chunks the build re-extracted; `0` when it re-extracted nothing. */
+    contextsReextracted: number;
+    /** The build's total LLM usage, with its per-model split. */
+    usage: KnowledgeBaseGraphUsage;
+    /** The split of {@link usage} across the stages the build ran. */
+    stages: KnowledgeBaseGraphBuildStageUsage;
+}
+/**
+ * A graph build's LLM usage split by pipeline stage. A stage the build entered but spent nothing on
+ * reads zero; a stage it never ran (skipped by its plan, or by a resume) is absent.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphBuildStageUsage {
+    /** Entity/relationship re-extraction from the KB's chunks. */
+    reextraction?: KnowledgeBaseGraphUsage;
+    /** Entity resolution (duplicate-name adjudication and merges). */
+    resolution?: KnowledgeBaseGraphUsage;
+    /** The lexical mention backstop, which is deterministic and normally spends nothing. */
+    backstop?: KnowledgeBaseGraphUsage;
+    /** Topic clustering and topic summaries. */
+    topics?: KnowledgeBaseGraphUsage;
+    /** Facet tree construction. */
+    facets?: KnowledgeBaseGraphUsage;
+}
 /**
  * Aggregated LLM token usage (and best-effort cost) of graph work on a KB. Token counts are the
  * provider-reported ground truth; `estCostUsd` is estimated from model list prices at call time —
@@ -1351,6 +1449,13 @@ export interface RebuildKnowledgeBaseGraphRequest {
     knowledgeBaseId: AiKnowledgeBaseId;
     /** What to recompute (see {@link KnowledgeBaseGraphRebuildMode}). Default `'structural'`. */
     mode?: KnowledgeBaseGraphRebuildMode;
+    /**
+     * When true, starts the rebuild even while a bulk-ingestion job on the KB is still active. Off by
+     * default: such a rebuild is refused (`GRAPH_REBUILD_BLOCKED_BY_BULK_JOB`) because it re-extracts the
+     * contexts the job is still merging. Set it for a job that is wedged (its pod died and its deadline
+     * has not passed) when cancelling the job is not an option.
+     */
+    ignoreActiveBulkJobs?: boolean;
 }
 /**
  * Request structure for exploring a bounded subgraph of a knowledge base's graph (Phase 3 visualization).
@@ -1665,7 +1770,34 @@ export interface BulkIngestionUpsertContextsRequest {
     knowledgeBaseId: string;
     /** The contexts to stage; each becomes one bulk-ingestion file. */
     contexts: Array<BulkIngestionContext>;
+    /**
+     * How quickly this job must finish. A hint, not a command: Squid honours it where the job's models and
+     * its share of the ingestion pool allow, and otherwise runs the job the way it can. Read
+     * {@link BulkIngestionJobStatusResponse.transport} to see what it actually ran as.
+     */
+    speed?: BulkIngestionSpeed;
 }
+/**
+ * The optional half of a bulk-ingestion staging call.
+ * @category AI
+ */
+export interface BulkIngestionUpsertContextsOptions {
+    /** See {@link BulkIngestionUpsertContextsRequest.speed}. */
+    speed?: BulkIngestionSpeed;
+}
+/**
+ * How quickly a bulk-ingestion job must finish, and so which provider tier Squid buys for it. The model,
+ * the prompts and the resulting chunks are identical at every speed — only the queue in front of them
+ * differs.
+ *
+ * - `economy` — provider batch, cheapest, tails up to 24 hours.
+ * - `auto` — Squid decides from the job's size. The default.
+ * - `fast` — runs inline, minutes rather than hours, at full list price.
+ * @category AI
+ */
+export declare const BULK_INGESTION_SPEEDS: readonly ["economy", "auto", "fast"];
+/** See {@link BULK_INGESTION_SPEEDS}. */
+export type BulkIngestionSpeed = (typeof BULK_INGESTION_SPEEDS)[number];
 /**
  * Response for a staged bulk-ingestion request.
  * @category AI
@@ -1734,11 +1866,21 @@ export interface BulkIngestionFileStatus {
     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.
+     * Terminal — reported with `retryable: false` — are `'CONTENT_TOO_LARGE'` (past the per-context
+     * ceiling), `'ENCRYPTED_DOCUMENT'`, `'NO_EMBEDDABLE_CONTENT'`, `'SOURCE_OVER_PROVIDER_LIMIT'` (the
+     * bytes exceed what the extraction provider accepts) and `'UNSUPPORTED_FILE_TYPE'`.
+     * `'DUPLICATE_CONTENT'` is a skip rather than a failure: the KB already holds this content.
+     * `'EXTRACTION_TIMED_OUT'` stays retryable — the deadline is contended, so a borderline document can
+     * cross it under load. `'JOB_FULL'`: the job's request ceiling had no room left for this file, so re-submit it
+     * in a fresh job; a file that alone exceeds the ceiling fails this way in every job. Additive; absent for
+     * ordinary failures.
+     */
+    errorCode?: 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'JOB_FULL' | 'NO_EMBEDDABLE_CONTENT' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'UNSUPPORTED_FILE_TYPE';
+    /**
+     * Present only on a failed file: the same bytes fail the same way, so a caller must park the file
+     * instead of re-submitting it. Absence means retryable.
      */
-    errorCode?: 'DUPLICATE_CONTENT';
+    retryable?: false;
     /**
      * 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.
@@ -1747,6 +1889,20 @@ export interface BulkIngestionFileStatus {
     /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
     imageFailureCount?: number;
 }
+/**
+ * Why a whole bulk-ingestion staging call was refused, on the `details` of its 400 response. The
+ * refusal names the one context that caused it, so a caller recording per-file outcomes charges only
+ * that file.
+ * @category AI
+ */
+export interface BulkIngestionStagingRefusal {
+    /** The staged object exceeds the per-file source ceiling. */
+    errorCode: 'STAGED_OBJECT_TOO_LARGE';
+    /** The same bytes are refused the same way, so the named file must be parked rather than re-staged. */
+    retryable: false;
+    /** The context whose file caused the refusal. */
+    contextId: string;
+}
 /**
  * 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
@@ -1774,6 +1930,99 @@ export interface BulkIngestionProviderBatchStatus {
      * stopped, not that the batch is waiting. Read wait duration off {@link createdAt}.
      */
     updatedAt: Date;
+    /** The lanes of the requests the batch carries; empty when a batch of an older core cannot tell. */
+    lanes?: Array<BulkIngestionRequestLane>;
+    /**
+     * The provider's status at the newest poll, as the adapter reports it: provider-raw for OpenAI, normalized
+     * (`in_progress`, `completed`, …) for Anthropic and Mistral.
+     */
+    providerStatus?: string;
+    /** When a poll first saw {@link providerStatus}. */
+    providerStatusChangedAt?: Date;
+    /** When the provider started running the batch; absent while it has not. */
+    providerInProgressAt?: Date;
+    /** Per-request progress at the newest poll; absent for a provider that does not report it. */
+    requestCounts?: BulkIngestionProviderBatchRequestCounts;
+    /** When the poll that read {@link requestCounts} ran. */
+    requestCountsAt?: Date;
+}
+/**
+ * The lane a bulk-ingestion request belongs to; core's `BulkIngestionLane` is this type.
+ * @category AI
+ */
+export type BulkIngestionRequestLane = 'embeddings' | 'imageDescription' | 'spreadsheetSummary' | 'metadataExtraction' | 'chunkContext' | 'documentOcr';
+/**
+ * A provider batch's per-request progress as the provider reports it.
+ * @category AI
+ */
+export interface BulkIngestionProviderBatchRequestCounts {
+    /** Requests in the batch. */
+    total: number;
+    /**
+     * Requests the provider ran to a result, succeeded or failed. Requests it reports as cancelled or expired unrun are
+     * left out, so `total − completed` is not the count still in flight.
+     */
+    completed: number;
+    /** Of {@link completed}, the ones that failed, when the provider reports that breakdown. */
+    failed?: number;
+}
+/**
+ * Provider-side progress of one job's batches on one provider route (provider, endpoint and model). A route
+ * is the unit the provider queues, and one batch can carry several lanes, so progress is reported per route.
+ * @category AI
+ */
+export interface BulkIngestionProviderRouteThroughput {
+    /** The provider running the route's batches. */
+    provider: BulkIngestionProviderBatchStatus['provider'];
+    /** The provider API the route's batches ride. */
+    endpoint: BulkIngestionProviderBatchStatus['endpoint'];
+    /** The model the route's batches run on. */
+    model: string;
+    /** The lanes the route's batches carry. */
+    lanes: Array<BulkIngestionRequestLane>;
+    /** The route's batches created or submitted and not yet ended at the provider. */
+    batchesInFlight: number;
+    /** Requests in those batches the provider has not settled yet. */
+    requestsInFlight: number;
+    /** Requests the provider ran to a result, succeeded or failed, across the route's batches. */
+    requestsCompleted: number;
+    /** Of {@link requestsCompleted}, the ones that failed; absent when no batch reports that breakdown. */
+    requestsFailed?: number;
+    /**
+     * Requests the provider completed per minute over the last {@link BulkIngestionProviderThroughput.windowMinutes};
+     * absent when no batch of the route reports counts.
+     */
+    completedPerMinute?: number;
+    /**
+     * The oldest view of an in-flight batch: when its counts were read, else when its status last was, else when it
+     * was created. Older than a few minutes means polls lag or return no counts, not that the provider stalled:
+     * {@link completedPerMinute} then misses what the provider did since.
+     */
+    countsObservedAt?: Date;
+}
+/**
+ * One in-flight provider-batch budget of the app on the shared system credential.
+ * @category AI
+ */
+export interface BulkIngestionInFlightBatchBudget {
+    /** The lanes whose batches the budget gates. */
+    lanes: Array<BulkIngestionRequestLane>;
+    /** Batches of the WHOLE app holding the budget: another job of the app holds slots too. */
+    inFlight: number;
+    /** How many batches the budget admits right now; a lane whose budget is full waits for a slot. */
+    limit: number;
+}
+/**
+ * Whether a running job's provider batches are draining: per-route progress and the app's in-flight budgets.
+ * @category AI
+ */
+export interface BulkIngestionProviderThroughput {
+    /** The span, in minutes, the per-route completion rates cover. */
+    windowMinutes: number;
+    /** Progress per provider route the job has batches on. */
+    routes: Array<BulkIngestionProviderRouteThroughput>;
+    /** The app's in-flight budgets; absent when the job's batches run on the app's own provider key, which is not capped. */
+    inFlightBatchBudgets?: Array<BulkIngestionInFlightBatchBudget>;
 }
 /**
  * Response describing a bulk-ingestion job's current state and progress counts.
@@ -1831,6 +2080,12 @@ export interface BulkIngestionJobStatusResponse {
      * the wire: consumers must tolerate its absence.
      */
     phase?: 'extracting' | 'awaiting-provider-batch' | 'indexing';
+    /**
+     * Provider-side progress of the job's batches, so a saturated in-flight budget the provider is draining
+     * reads differently from one it completes nothing in. Present only while a `'batch'` job is `running`.
+     * Optional on the wire: consumers must tolerate its absence.
+     */
+    providerThroughput?: BulkIngestionProviderThroughput;
     /** Per-file status, one entry per staged context (bounded by the job's file cap). */
     files: Array<BulkIngestionFileStatus>;
 }