@squidcloud/client 1.0.498 → 1.0.500

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,5 @@
+/** Names of the Squid metrics; dashboards and metric queries key on these exact strings. */
+export declare const ALL_SQUID_METRIC_NAMES: readonly ["squid_functionExecution_count", "squid_functionExecution_time", "squid_aiChatbotContext_size", "squid_aiChatbotChatInputTokens_count", "squid_aiChatbotChatOutputTokens_count", "squid_aiChatbotChatReasoningTokens_count", "squid_aiChatbotChatCacheReadInputTokens_count", "squid_aiChatbotChatCacheWriteInputTokens_count", "squid_aiChatbotChatCostUsd_count", "squid_aiChatbotChatOutcome_count", "squid_aiSpendInputTokens_count", "squid_aiSpendOutputTokens_count", "squid_aiSpendReasoningTokens_count", "squid_aiSpendCacheReadTokens_count", "squid_aiSpendCacheWriteTokens_count", "squid_aiSpendPages_count", "squid_aiSpendImages_count", "squid_aiSpendAudioSeconds_count", "squid_aiSpendCharacters_count", "squid_aiSpendSearches_count", "squid_aiSpendCostUsd_count", "squid_aiImageGeneration_count", "squid_aiImageGeneration_time", "squid_aiRemoveBackground_count", "squid_aiRemoveBackground_time", "squid_aiAudioTranscribe_count", "squid_aiAudioTranscribe_time", "squid_aiAudioCreateSpeech_count", "squid_aiAudioCreateSpeech_time", "squid_aiVoiceCreateSession_count", "squid_aiVoiceCreateSession_time", "squid_aiVoiceAnswerOpenAiCall_count", "squid_aiVoiceAnswerOpenAiCall_time", "squid_aiVoiceStartOpenAiWebCall_count", "squid_aiVoiceStartOpenAiWebCall_time", "squid_aiOpenAiChatCompletions_count", "squid_aiOpenAiChatCompletions_time", "squid_aiIntegrationData_count", "squid_aiIntegrationData_time", "squid_aiIntegrationApi_count", "squid_aiIntegrationApi_time", "squid_apiControllerCall_count", "squid_apiControllerCall_time", "squid_aiContextUpsert_count", "squid_aiContextDelete_count", "squid_codeInitialization_count", "squid_codeInitialization_time", "squid_sourceCodeAnalysis_count", "squid_sourceCodeAnalysis_time", "squid_sourceCodeWorkspaceBytes_value", "squid_sourceCodeInputTokens_count", "squid_sourceCodeOutputTokens_count", "squid_deleteApiKey_count", "squid_deleteApiKey_time", "squid_deleteSecret_count", "squid_deleteSecret_time", "squid_discoverGraphQLConnectionSchema_count", "squid_discoverGraphQLConnectionSchema_time", "squid_discoverOpenApiSchema_count", "squid_discoverOpenApiSchema_time", "squid_discoverOpenApiSchemaFromFile_count", "squid_discoverOpenApiSchemaFromFile_time", "squid_executeBackendFunction_count", "squid_executeBackendFunction_time", "squid_apiControllerCall_count", "squid_apiControllerCall_time", "squid_getAiChatbotProfiles_count", "squid_getAiChatbotProfiles_time", "squid_getAllApiKeys_count", "squid_getAllApiKeys_time", "squid_getAllSecrets_count", "squid_getAllSecrets_time", "squid_getAppApiKey_count", "squid_getAppApiKey_time", "squid_getSecret_count", "squid_getSecret_time", "squid_graphql_count", "squid_graphql_time", "squid_graphqlQuery_count", "squid_graphqlQuery_time", "squid_integrationCount_value", "squid_mutate_count", "squid_mutate_time", "squid_metricQuery_count", "squid_metricQuery_time", "squid_metricReport_count", "squid_metricReport_time", "squid_nativeQuery_count", "squid_nativeQuery_time", "squid_openapi_count", "squid_openapi_time", "squid_produceTopicMessage_count", "squid_produceTopicMessage_time", "squid_query_count", "squid_query_time", "squid_queueMessageHandler_count", "squid_queueMessageHandler_time", "squid_registerQuery_count", "squid_registerQuery_time", "squid_rerankChunks_count", "squid_rerankChunks_time", "squid_schedulerJob_count", "squid_schedulerJob_time", "squid_eventHandler_count", "squid_eventHandler_time", "squid_schema_size", "squid_secrets_entries", "squid_storageDeleteFiles_count", "squid_storageDeleteFiles_time", "squid_storageGetDownloadUrl_count", "squid_storageGetDownloadUrl_time", "squid_storageGetFileMetadata_count", "squid_storageGetFileMetadata_time", "squid_storageListDirectoryContents_count", "squid_storageListDirectoryContents_time", "squid_storageUploadFile_count", "squid_storageUploadFile_time", "squid_subscribeToTopic_count", "squid_subscribeToTopic_time", "squid_tenantDependencyResolved_count", "squid_tenantBrowserSpawnAttempt_count", "squid_testGraphQLConnection_count", "squid_testGraphQLConnection_time", "squid_testAgentProtocolConnection_count", "squid_testAgentProtocolConnection_time", "squid_trigger_count", "squid_trigger_time", "squid_upsertApiKey_count", "squid_upsertApiKey_time", "squid_upsertSecret_count", "squid_upsertSecret_time", "squid_vectorChunks_count", "squid_vectorChunks_time", "squid_webhook_count", "squid_webhook_time", "squid_acquireLock_count", "squid_acquireLock_time", "squid_releaseLock_count", "squid_releaseLock_time"];
+export type MetricName = (typeof ALL_SQUID_METRIC_NAMES)[number];
+/** Common prefix for all Squid metrics. */
+export declare const SQUID_METRIC_NAME_PREFIX = "squid_";

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

@@ -421,7 +421,7 @@ export interface IntegrationModelSpec {
  */
 export type AiChatModelSelection = AiChatModelName | IntegrationModelSpec;
 /**
- * Lets a routing model pick which of several vendor models answers an `ask` request. The routing model
+ * Lets a routing model pick which of several vendor models answers an `ask` or `chat` request. The routing model
  * sees the question, the agent's instructions and a card per candidate (price, tier, reasoning,
  * context window) and names the one that should answer; that model then serves the request.
  * @category AI
@@ -433,12 +433,27 @@ export interface AiModelRoutingOptions {
     routingModel: VendorAiChatModelName;
 }
 /**
- * The model of an `ask` request: a concrete model, or a set of models a routing model chooses from.
+ * The model of an `ask` or `chat` request: a concrete model, or a set of models a routing model chooses from.
  * @category AI
  */
 export type AiAskModelSelection = AiChatModelSelection | AiModelRoutingOptions;
 /**
- * How an `ask` request whose `model` was an {@link AiModelRoutingOptions} was routed.
+ * What a `chat` job resolves to once its stream has ended; read it with `squid.jobs().awaitJob(jobId)`.
+ * @category AI
+ */
+export interface AiChatJobResult {
+    /** Set when `model` was an {@link AiModelRoutingOptions}: which model answered and what routing cost. */
+    routing?: AiModelRoutingResult;
+}
+/**
+ * Chat options as a request carries them: the model may also be a routing choice between several models.
+ * @category AI
+ */
+export type AiChatRequestOptions = Omit<AllAiAgentChatOptions, 'model'> & {
+    model?: AiAskModelSelection;
+};
+/**
+ * How a request whose `model` was an {@link AiModelRoutingOptions} was routed.
  * @category AI
  */
 export interface AiModelRoutingResult {
@@ -473,11 +488,28 @@ export interface BackupModelOptions {
     /** Response length and detail level; supported by OpenAI models only. */
     verbosity?: AiVerbosityLevel;
 }
-/**
- * The base AI agent chat options, should not be used directly.
- * @category AI
- */
+/** Configures independent answer validation and bounded correction. @category AI */
+export interface AiAnswerValidationOptions {
+    /** Judge model; defaults to the model that produced the initial answer. */
+    model?: AiChatModelSelection;
+    /** Additional acceptance criteria for the judge. */
+    instructions?: string;
+    /** Maximum answer attempts, including the initial answer. Defaults to 2; accepts 1–5. */
+    maxAttempts?: number;
+}
+/** Reports the judge's verdict for the returned answer. @category AI */
+export interface AiAnswerValidationResult {
+    /** Whether the returned answer passed validation; false also covers incomplete validation. */
+    passed: boolean;
+    /** Concise explanation of the verdict or validation failure. */
+    summary: string;
+    /** Actionable defects or reasons validation could not complete. */
+    issues: Array<string>;
+}
+/** Shared options for agent chat requests. @category AI */
 export interface BaseAiChatOptions {
+    /** Enables validation for non-CLI models; an empty object uses defaults. Judge read-only behavior is instruction-based. */
+    validation?: AiAnswerValidationOptions;
     /**
      * The maximum number of input tokens that Squid can use when making the request to the AI model.
      * Defaults to the max tokens the model can accept.
@@ -783,7 +815,7 @@ export type AiVerbosityLevel = 'low' | 'medium' | 'high';
  * **Example:**
  * ```typescript
  * {
- *   model: 'claude-sonnet-5',
+ *   model: 'claude-sonnet-5-5',
  *   responseFormat: {
  *     type: 'json_schema',
  *     schema: {
@@ -1430,6 +1462,8 @@ export interface DeleteAgentRequest {
  * @category AI
  */
 export interface AiAskResponse {
+    /** Judge verdict, present when answer validation is enabled. */
+    validation?: AiAnswerValidationResult;
     /** The response string from the agent */
     responseString: string;
     /** Optional annotations (e.g., file references) in the response */

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

@@ -61,12 +61,12 @@ export declare const GROK_CHAT_MODEL_NAMES: readonly ["grok-4.6", "grok-4-1-fast
  * Public Anthropic chat model names (active models only).
  * @category AI
  */
-export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5-20251001", "claude-opus-5-5", "claude-sonnet-5"];
+export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5-20251001", "claude-opus-5-5", "claude-sonnet-5-5"];
 /**
  * The supported AI model names.
  * @category AI
  */
-export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-6-astra", "gpt-6-luna", "gpt-6.1-sol", "claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5-20251001", "claude-opus-5-5", "claude-sonnet-5", "gemini-3.1-pro", "gemini-3.8-flash", "gemini-3.5-flash-lite", "grok-4.6", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
+export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-6-astra", "gpt-6-luna", "gpt-6.1-sol", "claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5-20251001", "claude-opus-5-5", "claude-sonnet-5-5", "gemini-3.1-pro", "gemini-3.8-flash", "gemini-3.5-flash-lite", "grok-4.6", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
 /** Checks if the given model name is a global AI chat model name.  */
 export declare function isVendorAiChatModelName(modelName: unknown): modelName is VendorAiChatModelName;
 /**

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

@@ -1189,6 +1189,11 @@ export interface GeneratedMetadataFieldDescription {
 export interface GetKnowledgeBaseGraphStatusRequest {
     /** The id of the AiKnowledgeBase. */
     knowledgeBaseId: AiKnowledgeBaseId;
+    /**
+     * Whether to include the topic table (`topics`, `topicEdges`). Default true. A poller that reads only the
+     * build state can pass false: on a large graph the table runs to thousands of topics.
+     */
+    includeTopics?: boolean;
 }
 /**
  * Response structure for a knowledge base's GraphRAG build/readiness status. Drives the ai-eval
@@ -1552,17 +1557,20 @@ export interface RebuildKnowledgeBaseGraphRequest {
      */
     ignoreActiveBulkJobs?: boolean;
 }
+/** Hard ceiling on the nodes one graph explore returns: a larger `nodeLimit` is clamped down to this value. */
+export declare const KNOWLEDGE_BASE_GRAPH_EXPLORE_MAX_NODES = 1000;
+/** Longest `search` text a graph explore accepts; a longer one is rejected. */
+export declare const KNOWLEDGE_BASE_GRAPH_SEARCH_MAX_LENGTH = 200;
 /**
- * Request structure for exploring a bounded subgraph of a knowledge base's graph (Phase 3 visualization).
- * Returns the highest-degree entities and the relationships among them. Seed-based exploration
- * (prompt/entity-name seeding + traversal depth) is a planned extension; its fields will be added
- * here once implemented.
+ * Request structure for exploring a bounded subgraph of a knowledge base's graph (visualization). By default
+ * it returns the highest-degree entities and the relationships among them; `topicId`, `entityId` and `search`
+ * select other entity pools, and `contextMetadataFilter` narrows any of them.
  * @category AI
  */
 export interface ExploreKnowledgeBaseGraphRequest {
     /** The id of the AiKnowledgeBase. */
     knowledgeBaseId: AiKnowledgeBaseId;
-    /** Hard cap on returned nodes. Default 200, max 1000. */
+    /** Hard cap on returned nodes. Default 200, at most {@link KNOWLEDGE_BASE_GRAPH_EXPLORE_MAX_NODES}. */
     nodeLimit?: number;
     /**
      * Restricts the subgraph to entities under the given topic node id — any hierarchy level; an entity
@@ -1570,6 +1578,30 @@ export interface ExploreKnowledgeBaseGraphRequest {
      * `TOPIC_NOT_FOUND`. Ids come from {@link KnowledgeBaseGraphTopic.id} and churn on rebuild.
      */
     topicId?: string;
+    /**
+     * Centers the subgraph on one entity: the entity plus its neighbors, strongest relationships first. Ids
+     * come from {@link KnowledgeBaseGraphNode.id} and churn on rebuild; an unknown id fails with
+     * `ENTITY_NOT_FOUND`. Cannot be combined with `topicId` or `search`.
+     */
+    entityId?: string;
+    /**
+     * Finds entities by name: exact names and aliases first, then prefixes, then substrings, each by degree.
+     * When no name matches, returns the entities nearest in meaning instead (`searchMatch: 'similar'`).
+     * At most {@link KNOWLEDGE_BASE_GRAPH_SEARCH_MAX_LENGTH} characters. Cannot be combined with `topicId` or
+     * `entityId`.
+     */
+    search?: string;
+    /**
+     * Keeps only the entities mentioned by contexts matching the filter. Without `entityId` or `search`, they
+     * are ranked by how many matching contexts mention them. Filters on context-record metadata only, not on
+     * per-chunk keys.
+     */
+    contextMetadataFilter?: AiContextMetadataFilter;
+    /**
+     * Whether to attach the topic table (`topics`). Default true. A caller that already holds it can pass false:
+     * on a large graph the table runs to thousands of topics.
+     */
+    includeTopics?: boolean;
 }
 /** A node in an {@link ExploreKnowledgeBaseGraphResponse}. @category AI */
 export interface KnowledgeBaseGraphNode {
@@ -1608,14 +1640,32 @@ export interface KnowledgeBaseGraphEdge {
 export interface ExploreKnowledgeBaseGraphResponse {
     /** The subgraph nodes. */
     nodes: Array<KnowledgeBaseGraphNode>;
-    /** The subgraph edges (outgoing only, both endpoints present in `nodes`). */
+    /**
+     * The subgraph edges (outgoing only, both endpoints present in `nodes`). Capped: past the cap only the
+     * heaviest are returned and {@link edgesTruncated} is set.
+     */
     edges: Array<KnowledgeBaseGraphEdge>;
+    /** True when the nodes are linked by more relationships than `edges` carries. */
+    edgesTruncated?: boolean;
     /**
      * The KB's topic (theme) nodes — the id→name/hierarchy table for the nodes' `topicPath` ids, so a
      * visualization can label and group by theme without extra round trips. Present when the concept
-     * layer has been built (a rebuild ran).
+     * layer has been built (a rebuild ran). Under `contextMetadataFilter`, `docCount` counts only the
+     * matching contexts.
      */
     topics?: Array<KnowledgeBaseGraphTopic>;
+    /**
+     * Size of the pool the subgraph was cut from — the entities in scope, the topic's members, the entity's
+     * neighbors or the search matches. Compare with `nodes.length` to offer more. Absent when not counted.
+     */
+    totalCount?: number;
+    /** How a `search` matched: by entity name, or by meaning when no name matched. */
+    searchMatch?: 'name' | 'similar';
+    /**
+     * True when `contextMetadataFilter` matched more contexts than one request reads; the subgraph then
+     * covers only the first of them.
+     */
+    scopeTruncated?: boolean;
 }
 /**
  * A topic (theme) node of the graph's concept layer, as referenced by
@@ -1656,12 +1706,14 @@ export interface KnowledgeBaseGraphTopicEdge {
  * round trip with a complete answer — no per-level walking.
  * @category AI
  */
-export type KnowledgeBaseGraphQueryOp = 'overview' | 'resolve' | 'describe' | 'subtree' | 'docsUnder' | 'conceptsOf' | 'neighborhood' | 'pathBetween' | 'globalSummary';
+export type KnowledgeBaseGraphQueryOp = 'overview' | 'resolve' | 'describe' | 'subtree' | 'docsUnder' | 'conceptsOf' | 'neighborhood' | 'pathBetween' | 'globalSummary' | 'relationship';
 /**
  * Request structure for querying a knowledge base's graph (documents, entities, topics, facets) through
  * the closed op set. `ref` accepts a facet nodeId (`facet_…` — exact; the only persistable concept
- * handles) or a name, resolved server-side (exact → alias → similarity). An unresolvable ref fails with
- * `CONCEPT_NOT_FOUND` plus the nearest matching names.
+ * handles), a topic id from {@link KnowledgeBaseGraphTopic.id} or an entity id from
+ * {@link KnowledgeBaseGraphNode.id} (both exact, both churn on rebuild) or a name, resolved server-side
+ * (exact → alias → similarity). An unresolvable ref fails with `CONCEPT_NOT_FOUND` plus the nearest
+ * matching names.
  * @category AI
  */
 export interface QueryKnowledgeBaseGraphRequest {
@@ -1669,9 +1721,12 @@ export interface QueryKnowledgeBaseGraphRequest {
     knowledgeBaseId: AiKnowledgeBaseId;
     /** The operation to run. */
     op: KnowledgeBaseGraphQueryOp;
-    /** Node ref (name or facet nodeId). Required by resolve/describe/subtree/docsUnder/neighborhood/pathBetween. */
+    /**
+     * Node ref (name, facet nodeId, topic id or entity id). Required by resolve/describe/subtree/docsUnder/
+     * neighborhood/pathBetween/relationship.
+     */
     ref?: string;
-    /** Second node ref for `pathBetween`. */
+    /** Second node ref for `pathBetween`, and the target entity for `relationship`. */
     refB?: string;
     /** The document's contextId for `conceptsOf`. */
     contextId?: string;
@@ -1683,8 +1738,16 @@ export interface QueryKnowledgeBaseGraphRequest {
     hops?: number;
     /** `docsUnder`: when true (default), include documents under the whole subtree, not just the node itself. */
     recursive?: boolean;
-    /** `docsUnder`: maximum documents returned. Default 25, max 100 (`totalDocs` always reports the full count). */
+    /**
+     * `docsUnder` and `relationship`: maximum documents returned. Default 25, max 100 (`totalDocs` always
+     * reports the full count).
+     */
     limit?: number;
+    /**
+     * `docsUnder` and `relationship`: keeps only the documents whose context matches the filter. Filters on
+     * context-record metadata only, not on per-chunk keys.
+     */
+    contextMetadataFilter?: AiContextMetadataFilter;
 }
 /** One node matched by a graph query (`resolve`, and the anchors of other ops). @category AI */
 export interface KnowledgeBaseGraphQueryMatch {
@@ -1767,6 +1830,27 @@ export interface KnowledgeBaseGraphQueryPath {
     /** Thematic tier: names of concepts both refs sit under. */
     sharedConcepts?: Array<string>;
 }
+/**
+ * A `relationship` answer: the direct relationship between two entities, in its asserted direction, and
+ * the documents asserting it.
+ * @category AI
+ */
+export interface KnowledgeBaseGraphQueryRelationship {
+    /** Source entity name. */
+    source: string;
+    /** Target entity name. */
+    target: string;
+    /** Relationship label. */
+    type: string;
+    /** Relationship description, when the extraction produced one. */
+    description?: string;
+    /** How many times the relationship was asserted. */
+    weight: number;
+    /** Documents asserting the relationship (capped by `limit`). */
+    documents: Array<KnowledgeBaseGraphQueryDoc>;
+    /** Number of documents asserting it (compare with `documents.length` for truncation). */
+    totalDocs: number;
+}
 /**
  * Response structure for a graph query. `op` echoes the request; exactly the fields that op produces
  * are set (e.g. `matches` for `resolve`, `tree` for `subtree`).
@@ -1803,6 +1887,13 @@ export interface QueryKnowledgeBaseGraphResponse {
     pathBetween?: KnowledgeBaseGraphQueryPath;
     /** `globalSummary`: the KB's topic summaries ranked against the query, most relevant first. */
     summaries?: Array<KnowledgeBaseGraphQueryGlobalSummary>;
+    /** `relationship`: the relationship between `ref` and `refB` and the documents asserting it. */
+    relationship?: KnowledgeBaseGraphQueryRelationship;
+    /**
+     * True when `contextMetadataFilter` matched more contexts than one request reads; the documents then come
+     * from only the first of them.
+     */
+    scopeTruncated?: boolean;
 }
 /**
  * One context to stage through bulk ingestion. Unlike the sync request, `imageExtractionModel` is not
@@ -1977,7 +2068,8 @@ export interface BulkIngestionJobStatusCounts {
  * cross it under load. So do `'SOURCE_UNREACHABLE'` (the provider could not fetch the source, which a
  * fresh link can fix) and `'PROVIDER_ACCESS_DENIED'` (the provider refused the credential or its quota is
  * spent, a fault of the environment). `'JOB_FULL'`: the job's request ceiling had no room left for this
- * file, so re-submit it in a fresh job; a file that alone exceeds the ceiling fails this way in every job.
+ * file when it was admitted — before any paid stage ran — so re-submit it in a fresh job; a file that
+ * alone exceeds the ceiling fails this way in every job.
  * @category AI
  */
 export type BulkIngestionFileErrorCode = 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'IMAGE_OVER_PROVIDER_LIMIT' | 'JOB_FULL' | 'NO_EMBEDDABLE_CONTENT' | 'PROVIDER_ACCESS_DENIED' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'SOURCE_UNREACHABLE' | 'UNREADABLE_DOCUMENT' | 'UNREADABLE_WORKBOOK' | 'UNSUPPORTED_FILE_TYPE';

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

@@ -9,6 +9,11 @@ export interface InvokeLangGraphOptions {
     input?: Record<string, unknown>;
     /** How long the run may take, in ms, before it stops and fails. At most, and by default, one hour. */
     timeoutMs?: number;
+    /**
+     * Context of the run, which every node reads as LangGraph's `runtime.context`. It is not stored, so a resume
+     * passes its own.
+     */
+    context?: Record<string, unknown>;
 }
 /**
  * Options for resuming an interrupted LangGraph thread.
@@ -17,6 +22,8 @@ export interface InvokeLangGraphOptions {
 export interface ResumeLangGraphOptions {
     /** How long the resumed run may take, in ms, before it stops and fails. At most, and by default, one hour. */
     timeoutMs?: number;
+    /** Context of the resumed run, which every node reads as LangGraph's `runtime.context`. */
+    context?: Record<string, unknown>;
 }
 /**
  * Successful result of a LangGraph invocation.

package/dist/internal-common/src/public-types-backend/api-call.public-context.d.ts

@@ -0,0 +1,30 @@
+import { ApiOptions } from '../public-types/api-client.public-types';
+import { ApiEndpointId, HttpMethod } from '../public-types/api.public-types';
+import { IntegrationId } from '../public-types/communication.public-types';
+/** The headers of an API call. */
+export type ApiHeaders = Record<string, string | number | boolean>;
+/** The context of an API call. */
+export declare class ApiCallContext {
+    readonly integrationId: IntegrationId;
+    readonly endpointId: ApiEndpointId;
+    readonly url: string;
+    readonly method: HttpMethod;
+    readonly body: unknown;
+    readonly options: ApiOptions;
+}
+/**
+ * Represents a request to call an API through a specified integration and endpoint.
+ * Includes optional method override and additional request options.
+ */
+export interface CallApiRequest<BodyType = any> {
+    /** The identifier of the integration through which the API is called. */
+    integrationId: IntegrationId;
+    /** Target API endpoint to invoke. */
+    endpointId: ApiEndpointId;
+    /** Optional request payload. */
+    body?: BodyType;
+    /** Optional HTTP method override. Default is POST. */
+    overrideMethod?: HttpMethod;
+    /** Additional request options. */
+    options: ApiOptions;
+}

package/dist/internal-common/src/public-types-backend/mutation.public-context.d.ts

@@ -0,0 +1,161 @@
+import { SquidDocIdObj, SquidDocument } from '../public-types/document.public-types';
+import { Paths } from '../public-types/typescript.public-types';
+/**
+ * The mutation type.
+ * @category Database
+ */
+export declare const MUTATION_TYPES: readonly ["insert", "update", "delete"];
+/**
+ * @category Database
+ */
+export type MutationType = (typeof MUTATION_TYPES)[number];
+/**
+ * Base fields shared by all document mutations.
+ * @category Database
+ */
+export interface BaseMutation {
+    /** The type of the mutation. */
+    type: MutationType;
+    /** The identity of the mutated document. */
+    squidDocIdObj: SquidDocIdObj;
+}
+/**
+ * A mutation on a document.
+ * @category Database
+ */
+export type Mutation<T = any> = UpdateMutation<T> | InsertMutation<T> | DeleteMutation;
+/**
+ * Represents a delete mutation on a document.
+ * @category Database
+ */
+export interface DeleteMutation extends BaseMutation {
+    /** Specifies that the mutation is a deletion. */
+    type: 'delete';
+}
+/**
+ * Represents an update mutation on a document.
+ * @category Database
+ */
+export interface UpdateMutation<T = any> extends BaseMutation {
+    /** Specifies that the mutation is an update. */
+    type: 'update';
+    /** The updated properties */
+    properties: {
+        [key in keyof T & string]?: Array<PropertyMutation<T[key]>>;
+    };
+}
+/**
+ * Represents an insert mutation on a document.
+ * @category Database
+ */
+export interface InsertMutation<T = any> extends BaseMutation {
+    /** Specifies that the mutation is an insertion. */
+    type: 'insert';
+    /** The inserted document */
+    properties: T;
+}
+/**
+ * A representation of a single property update.
+ * @category Database
+ */
+export type PropertyMutation<Value = any> = ApplyNumericFnPropertyMutation | ApplyStringFnPropertyMutation | ValueUpdatePropertyMutation<Value> | RemovePropertyMutation;
+/**
+ * A value update property mutation.
+ * @category Database
+ */
+export interface ValueUpdatePropertyMutation<Value = any> {
+    /** Specifies that the mutation updates a value. */
+    type: 'update';
+    /** New value to be set. */
+    value: Value;
+}
+/**
+ * Applying a numeric function to a property.
+ * @category Database
+ */
+export interface ApplyNumericFnPropertyMutation {
+    /** Specifies that the mutation applies a numeric function. */
+    type: 'applyNumericFn';
+    /** Numeric function to apply. */
+    fn: 'increment';
+    /** Value to use in the numeric function. */
+    value: number;
+}
+/**
+ * A property update that removes a property from a document.
+ * @category Database
+ */
+export interface RemovePropertyMutation {
+    /** Specifies that the mutation removes a property. */
+    type: 'removeProperty';
+}
+/**
+ * A property mutation that appends a value to the existing string.
+ * @category Database
+ */
+export interface ApplyExtendString {
+    /** Specifies that the mutation applies a string function. */
+    type: 'applyStringFn';
+    /** String function to extend the existing string. */
+    fn: 'extendString';
+    /** String value to append. */
+    value: string;
+}
+/**
+ * A property mutation that trims the existing string.
+ * @category Database
+ */
+export interface ApplyTrimString {
+    /** Specifies that the mutation applies a string function. */
+    type: 'applyStringFn';
+    /** String function to trim the existing string. */
+    fn: 'trim';
+}
+/**
+ * A property mutation that modifies a string.
+ * @category Database
+ */
+export type ApplyStringFnPropertyMutation = ApplyExtendString | ApplyTrimString;
+/**
+ * The before and after documents of a document change.
+ * @category Database
+ */
+export interface BeforeAndAfterDocs<T = SquidDocument> {
+    /** Document state before the mutation. */
+    before: T | undefined;
+    /** Document state after the mutation. */
+    after: T | undefined;
+}
+/**
+ * The mutation context that will be provided to the security function.
+ * @category Database
+ */
+export declare class MutationContext<T = any> {
+    readonly mutation: Mutation<T>;
+    readonly beforeAndAfterDocs: BeforeAndAfterDocs<T>;
+    readonly serverTimeStamp: Date;
+    /**
+     * Returns the state of the document before the mutation was applied.
+     */
+    get before(): T | undefined;
+    /**
+     * Returns the state of the document after the mutation was applied.
+     */
+    get after(): T | undefined;
+    /**
+     * Returns the type of the mutation (insert, update, or delete).
+     */
+    getMutationType(): MutationType;
+    /** Returns true if the mutation affects the provided path. */
+    affectsPath(path: Paths<T>): boolean;
+    /**
+     * Find all affected paths starting from a root path.
+     *
+     * @example
+     * doc before - { a: { b: 1, c: 2 }, d: 3 }
+     * doc after - { a: { b: 1, c: 3 }, d: 4 }
+     * doc.affectedPaths('a') // ['a.c']
+     */
+    affectedPaths(startingRoot?: Paths<T> | string): Array<Paths<T>>;
+    private checkPath;
+}

package/dist/internal-common/src/public-types-backend/native-query.public-context.d.ts

@@ -0,0 +1,75 @@
+import { IntegrationId } from '../public-types/communication.public-types';
+/**
+ * Represents the type of native query request, either relational, elastic or MongoDB.
+ * @category Database
+ */
+export type NativeQueryRequestType = 'relational' | 'mongo' | 'elasticsearch' | 'pure';
+/**
+ * Base fields shared by all native query contexts.
+ * @category Database
+ */
+export interface BaseNativeQueryContext {
+    /** Type of the native query request. */
+    type: NativeQueryRequestType;
+    /** Identifier for the integration. */
+    integrationId: IntegrationId;
+}
+/**
+ * Context for executing a relational database query.
+ * @category Database
+ */
+export interface RelationalNativeQueryContext extends BaseNativeQueryContext {
+    /** Specifies that the query is for a relational database. */
+    type: 'relational';
+    /** SQL query string to be executed. */
+    query: string;
+    /** Parameters to be used in the query. */
+    params: Record<string, any>;
+}
+/**
+ * Context for executing a MongoDB query.
+ * @category Database
+ */
+export interface MongoNativeQueryContext extends BaseNativeQueryContext {
+    /** Specifies that the query is for a Mongo database. */
+    type: 'mongo';
+    /** Name of the MongoDB collection to query. */
+    collectionName: string;
+    /** Array of aggregation pipeline stages. */
+    aggregationPipeline: Array<any | undefined>;
+}
+/**
+ * Context for executing an Elasticsearch query.
+ * @category Database
+ */
+export interface ElasticsearchNativeQueryContext {
+    /** Specifies that the query is for an Elasticsearch database. */
+    type: 'elasticsearch';
+    /** Elasticsearch index to query. */
+    index: string;
+    /** Elasticsearch query string. */
+    endpoint?: string;
+    /** HTTP method to use for the request. */
+    method?: 'GET' | 'POST';
+    /** Body of the request. */
+    body: Record<string, any>;
+    /** Headers to include in the request. */
+    integrationId: IntegrationId;
+}
+/**
+ * Context for executing a pure database query.
+ * @category Database
+ */
+export interface PureNativeQueryContext extends BaseNativeQueryContext {
+    /** Specifies that the query is for a relational database. */
+    type: 'pure';
+    /** SQL query string to be executed. */
+    query: string;
+    /** Parameters to be used in the query. */
+    params: Record<string, any>;
+}
+/**
+ * Union type representing either a relational or MongoDB native query context.
+ * @category Database
+ */
+export type NativeQueryContext = RelationalNativeQueryContext | MongoNativeQueryContext | ElasticsearchNativeQueryContext | PureNativeQueryContext;