@squidcloud/client 1.0.488 → 1.0.490

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

@@ -48,6 +48,14 @@ export interface AiApiOptions {
      * Defaults to no memory.
      */
     memoryOptions?: AiAgentMemoryOptions;
+    /**
+     * How long, in milliseconds, a single AI call of the loop may wait for the provider — endpoint
+     * selection, request-body creation and response analysis each get this budget on their own, so
+     * the whole call may run for a multiple of it. Values below the chat minimum of 20 000 ms are
+     * raised to it. Defaults to the standard chat timeout, or to the timeout of the chat this call
+     * runs inside when the caller is a nested one.
+     */
+    stageTimeoutMs?: number;
 }
 /**
  * Configuration options for AI agent MCP integration.

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

@@ -420,6 +420,26 @@ export interface IntegrationModelSpec {
  * @category AI
  */
 export type AiChatModelSelection = AiChatModelName | IntegrationModelSpec;
+/**
+ * A backup model together with the sampling settings to run it with. Use this form instead of a
+ * bare {@link AiChatModelSelection} when the backup needs settings of its own; anything left unset
+ * takes the backup model's own default rather than the primary model's value.
+ * @category AI
+ */
+export interface BackupModelOptions {
+    /** The model to fall back to. */
+    model: AiChatModelSelection;
+    /** The temperature to use when sampling from the backup model. */
+    temperature?: number;
+    /** The level of reasoning effort to apply; effective only for models with reasoning. */
+    reasoningEffort?: AiReasoningEffort;
+    /** The maximum number of input tokens Squid may send to the backup model. */
+    maxTokens?: number;
+    /** The maximum number of tokens the backup model should output. */
+    maxOutputTokens?: number;
+    /** 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
@@ -459,8 +479,24 @@ export interface BaseAiChatOptions {
     legacyKnowledgeBaseContext?: boolean;
     /** Rewrite prompt for RAG - defaults to false */
     enablePromptRewriteForRag?: boolean;
-    /** Whether to include references from the source context in the response. Default to false. */
+    /**
+     * Whether to include references from the source context in the response. Default to false.
+     * @deprecated Use citation instead. Kept for compatibility; renders the legacy Quote/Source format
+     * on the legacy upfront-RAG path only.
+     */
     includeReference?: boolean;
+    /**
+     * When true, the agent cites the sources behind its statements: source name, plus a download link
+     * when the agent's stored options set `allowSourceDownloads`. Takes precedence over the deprecated
+     * `includeReference`. Default to false.
+     */
+    citation?: boolean;
+    /**
+     * Allows citation links to the original source files (presigned, 1h expiry). Honored ONLY from the
+     * agent's stored options — the per-request value is ignored, so callers of public agents can never
+     * enable downloads. Default to false (citations render source names only).
+     */
+    allowSourceDownloads?: boolean;
     /**
      * The format of the response from the AI model. Defaults to 'text'. A `json_schema` format is
      * refused for a model whose provider has no way to carry a schema — see
@@ -512,6 +548,52 @@ export interface BaseAiChatOptions {
     pii?: AiPiiOptions;
     /** The LLM model to use. Can be a vendor model name (string) or an integration-based model (object). */
     model?: AiChatModelSelection;
+    /**
+     * The model to use when `model` cannot serve the conversation's very first request because its
+     * provider is unavailable — a rate limit, a capacity outage, or any other failure on the
+     * provider's side. A request that fails for its own reasons (an invalid prompt, a rejected
+     * schema, an exhausted Squid quota) is never retried on the backup, nor is any request after the
+     * first one, nor one that already produced output or ran a tool.
+     *
+     * A conversation that fell back then STAYS on that backup for the rest of its life, so an outage
+     * costs the primary's retry budget once rather than once per turn, and the model does not change
+     * mid-dialogue. The pin outlives the option that created it: changing or removing `backupModel`,
+     * changing the agent's own `model`, and the primary recovering all leave a pinned conversation
+     * where it is, and a pinned model that no longer resolves fails the request rather than moving the
+     * conversation. This is deliberate — a conversation accumulates provider-native file ids and a
+     * transcript in that provider's dialect, none of which survive a move. Pinning needs Squid-managed
+     * memory to have somewhere to record it; without memory every request is a first request anyway.
+     *
+     * A request carrying `fileIds` follows from the same reasoning, and the two cases differ. A first
+     * request does not fall back where that would cost it the attachments — to a model that cannot read
+     * ids the primary could, or that reads them without owning them — since answering from a model that
+     * never saw them is worse than reporting the outage. Where neither model reads file ids they are
+     * inert either way and the fallback proceeds. A
+     * conversation already pinned is held to less: it keeps running on its model, and if that model
+     * reads no file ids the ids are ignored there as they are anywhere else, because the alternative is
+     * a conversation that can never run again.
+     *
+     * Pass a model name for the model's own defaults, or a {@link BackupModelOptions} object to give
+     * the backup its own sampling settings. Everything else — instructions, functions, knowledge
+     * bases, connected agents, response format, memory — always comes from the primary configuration.
+     *
+     * On a turn the backup serves, the sampling settings are ITS settings alone: `temperature`,
+     * `reasoningEffort`, `maxTokens`, `maxOutputTokens` and `verbosity` are read from `backupModel`
+     * and nowhere else, so a value left unset there takes the backup model's own default even when
+     * the agent's profile or the request itself carries one. This holds for every turn of a pinned
+     * conversation, not only the one that fell back — tuning meant for one model is not evidence of
+     * what another should use.
+     *
+     * Applies to models served through Squid's own provider SDKs — the vendor models and
+     * `openai_compatible`, Bedrock and Vertex integrations. A model you serve yourself from backend
+     * code reports its failures as plain errors that carry no provider status, so a turn on one is
+     * never diagnosed as a provider outage and never falls back.
+     *
+     * The backup resolves its API key exactly as it would as the primary model, and is skipped
+     * silently when it cannot be resolved, when it reaches the same model as the primary, or when
+     * either model is a CLI-backed agent. Leave unset to keep a provider outage surfacing as an error.
+     */
+    backupModel?: AiChatModelSelection | BackupModelOptions;
     /** Which provider's reranker to use for reranking the context. Defaults to 'cohere'. */
     rerankProvider?: AiRerankProvider;
     /**
@@ -559,8 +641,21 @@ export interface BaseAiChatOptions {
      * Files are attached to the conversation and can be read/analyzed by the AI.
      */
     fileIds?: string[];
-    /** Timeout in milliseconds for the entire chat request. Defaults to 240,000 (4 minutes). */
+    /**
+     * Timeout in milliseconds for one model-call attempt of the chat (a single provider call,
+     * covering that call's tool loop). An attempt that produced nothing by this deadline is treated
+     * as a stalled provider connection and retried per `retriesOnStall`, each retry getting this
+     * full budget again — so the provider phase of a chat may take up to
+     * `(1 + retriesOnStall) * timeoutMs` in the worst case. Defaults to 240,000 (4 minutes).
+     */
     timeoutMs?: number;
+    /**
+     * How many times a stalled model-call attempt is reissued. A retry happens only when the
+     * attempt hit `timeoutMs` having produced nothing AND no AI function has executed in the turn,
+     * so a retry can never repeat a side effect; aborting the stalled attempt destroys its
+     * connection, so the retry cannot reuse it. `0` disables stall retries. Defaults to 1.
+     */
+    retriesOnStall?: number;
     /** Maximum number of tool-call iterations the model may perform in a single chat turn. Defaults to 50. */
     maxToolIterations?: number;
 }
@@ -607,6 +702,11 @@ export type { CanonicalReasoningEffort } from './ai-common.public-types';
  * - unknown string the model cannot place on the axis -> dropped, so the model's own default applies,
  *   with a warning;
  * - model without a reasoning knob -> ignored, with a warning.
+ *
+ * A model served through an `openai_compatible` integration is the exception: the value is sent to
+ * that endpoint exactly as written, with none of the resolution above, since the endpoint's model is
+ * the app's own choice and this registry cannot describe it. That is also how to reach a level the
+ * canonical set has no name for.
  * @category AI
  */
 export type AiReasoningEffort = CanonicalReasoningEffort | (string & {});
@@ -918,6 +1018,18 @@ export interface BaseUpsertContextStatus {
     /** The name of the context item, typically the title or filename. */
     name: string;
 }
+/**
+ * An image whose description failed during ingestion: the context is stored without that image's chunk.
+ * @category AI
+ */
+export interface ContextImageFailure {
+    /** Zero-based index of the page carrying the image. */
+    pageIndex: number;
+    /** Extraction-assigned id of the image within the document. */
+    imageId: string;
+    /** Why describing the image failed. */
+    errorMessage: string;
+}
 /**
  * Status of an individual context item after successfully upserting it.
  * @category AI
@@ -931,15 +1043,23 @@ export interface UpsertContextStatusSuccess extends BaseUpsertContextStatus {
      * surfaced so bulk operations can report which contexts fell outside the graph.
      */
     graphIndexingSkipped?: boolean;
+    /** First failed images (capped); 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;
 }
 /**
  * Machine-readable code identifying a specific upsert failure reason.
  *
  * `DUPLICATE_CONTENT` means the request omitted a contextId and its content is
  * byte-identical to an existing context in the same knowledge base.
+ *
+ * `EMBEDDING_FAILED` means extraction succeeded but embedding the context's chunks did not; the
+ * content was not written (an overwrite target keeps its previous content) and the request can be
+ * safely retried as-is.
  * @category AI
  */
-export type UpsertContextErrorCode = 'DUPLICATE_CONTENT';
+export type UpsertContextErrorCode = 'DUPLICATE_CONTENT' | 'EMBEDDING_FAILED';
 /**
  * The existing context a `DUPLICATE_CONTENT` rejection points at — where the byte-identical original
  * already lives.
@@ -972,6 +1092,10 @@ export interface UpsertContextStatusError extends BaseUpsertContextStatus {
      * rejection. `reference`/`folderPath` are present when the existing context carries them.
      */
     duplicateOf?: UpsertContextDuplicateOf;
+    /** First failed images (capped) when every image failed and the document had no text; otherwise absent. */
+    imageFailures?: Array<ContextImageFailure>;
+    /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
+    imageFailureCount?: number;
 }
 /**
  * Status of an individual context item after attempting to upsert it.
@@ -1164,7 +1288,7 @@ export interface UserAiChatOptions extends BaseAiChatOptions {
 export interface UserAiAskResponse {
     /** The response from the AI agent. */
     response?: string;
-    /** The number of input tokens used in the request. */
+    /** Prompt tokens used by the request, including any the prompt cache served. */
     inputTokens?: number;
     /** The number of output tokens generated by the AI agent. */
     outputTokens?: number;

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

@@ -2,7 +2,7 @@ import { UserAiChatModelName } from './backend.public-types';
 /**
  * @category AI
  */
-export declare const RERANK_PROVIDERS: readonly ["cohere", "none"];
+export declare const RERANK_PROVIDERS: readonly ["cohere", "voyage", "none"];
 /**
  * @category AI
  */
@@ -20,36 +20,48 @@ export type AiProviderType = (typeof AI_PROVIDER_TYPES)[number];
  * @category AI
  */
 export type CanonicalReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra';
+/**
+ * The AI providers that support file upload operations, and so are the only ones that resolve a
+ * pre-uploaded file id. Declared as the list, with the type derived from it, so the two cannot drift:
+ * a provider added to one is added to both.
+ */
+export declare const AI_FILE_PROVIDER_TYPES: readonly ["openai", "gemini", "anthropic", "grok"];
 /**
  * Type of AI provider that supports file upload operations.
  * Only a subset of AI providers support file management features.
  */
-export type AiFileProviderType = Extract<AiProviderType, 'openai' | 'gemini' | 'anthropic' | 'grok'>;
+export type AiFileProviderType = (typeof AI_FILE_PROVIDER_TYPES)[number];
+/**
+ * True when the provider resolves pre-uploaded file ids. Every other provider — the integration-backed
+ * and user-defined ones, which report no vendor identity of their own — ignores `fileIds` outright, so
+ * for them the ids are inert rather than wrong.
+ */
+export declare function isFileCapableProviderType(type: AiProviderType): type is AiFileProviderType;
 /**
  * Public OpenAI chat model names (active models only).
  * @category AI
  */
-export declare const OPENAI_CHAT_MODEL_NAMES: readonly ["gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"];
+export declare const OPENAI_CHAT_MODEL_NAMES: readonly ["gpt-5.5-pro", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"];
 /**
  * Public Gemini chat model names (active models only).
  * @category AI
  */
-export declare const GEMINI_CHAT_MODEL_NAMES: readonly ["gemini-3.1-pro", "gemini-3.6-flash", "gemini-3.5-flash-lite"];
+export declare const GEMINI_CHAT_MODEL_NAMES: readonly ["gemini-3.1-pro", "gemini-3.7-flash", "gemini-3.5-flash-lite"];
 /**
  * Public Grok chat model names (active models only).
  * @category AI
  */
-export declare const GROK_CHAT_MODEL_NAMES: readonly ["grok-4.5", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
+export declare const GROK_CHAT_MODEL_NAMES: readonly ["grok-4.6", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
 /**
  * Public Anthropic chat model names (active models only).
  * @category AI
  */
-export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-fable-5", "claude-haiku-4-5-20251001", "claude-opus-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", "claude-sonnet-5"];
 /**
  * The supported AI model names.
  * @category AI
  */
-export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "claude-fable-5", "claude-haiku-4-5-20251001", "claude-opus-5", "claude-sonnet-5", "gemini-3.1-pro", "gemini-3.6-flash", "gemini-3.5-flash-lite", "grok-4.5", "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning"];
+export declare const VENDOR_AI_CHAT_MODEL_NAMES: readonly ["gpt-5.5-pro", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "claude-fable-5", "claude-fable-5-1", "claude-haiku-4-5-20251001", "claude-opus-5", "claude-sonnet-5", "gemini-3.1-pro", "gemini-3.7-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;
 /**
@@ -59,7 +71,7 @@ export declare const OPENAI_EMBEDDINGS_MODEL_NAMES: readonly ["text-embedding-3-
 /**
  * @category AI
  */
-export declare const VOYAGE_EMBEDDING_MODEL_NAMES: readonly ["voyage-3-large"];
+export declare const VOYAGE_EMBEDDING_MODEL_NAMES: readonly ["voyage-3-large", "voyage-4-large", "voyage-4"];
 /**
  * @category AI
  */
@@ -67,7 +79,7 @@ export declare const BEDROCK_EMBEDDING_MODEL_NAMES: readonly ["titan-embed-text-
 /**
  * @category AI
  */
-export declare const AI_EMBEDDINGS_MODEL_NAMES: readonly ["text-embedding-3-small", "voyage-3-large", "titan-embed-text-v2"];
+export declare const AI_EMBEDDINGS_MODEL_NAMES: readonly ["text-embedding-3-small", "voyage-3-large", "voyage-4-large", "voyage-4", "titan-embed-text-v2"];
 /**
  * Checks if the given model name is a valid AI embeddings model name.
  * @category AI