@squidcloud/client 1.0.502 → 1.0.504

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

@@ -7,6 +7,7 @@ import { DocumentExtractionMethod } from './extraction.public-types';
 import { IntegrationType } from './integration.public-types';
 import { JobId } from './job.public-types';
 import { SecretKey } from './secret.public-types';
+import { UpsertSessionRequest } from './session.public-types';
 /**
  * @category AI
  */
@@ -653,6 +654,9 @@ export interface BaseAiChatOptions {
      * conversation, not only the one that fell back — tuning meant for one model is not evidence of
      * what another should use.
      *
+     * A turn the primary's safety classifier declines outright — no text at all came back — falls
+     * back the same way, since another model may well answer the same prompt.
+     *
      * 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
@@ -863,6 +867,19 @@ export interface AiChatRequestCredentials {
      */
     integrationAccessTokens?: Record<IntegrationId, string>;
 }
+/**
+ * The session (`squid.sessions()`) a chat request runs in. It is part of the request only: never stored with the agent.
+ * @category AI
+ */
+export interface AiChatRequestSession {
+    /**
+     * Every AI function the request calls gets the session as `context.session`. With the app API key, the request
+     * creates the session or updates the one with the same id. Without it, a new id creates the session with its data
+     * and a live one is attached as it is; the agent's `@secureAiAgent` rules see both and can refuse them. A call that
+     * skips the rules, to a public agent or with the agent's API key, cannot attach one.
+     */
+    session?: UpsertSessionRequest;
+}
 /**
  * Configuration for exposing an AI agent as an MCP server at `/mcp/<agentId>`.
  * @category AI
@@ -1279,6 +1296,14 @@ export type BaseAiContextOptions = {
     ragType?: AiRagType;
     /** Amount of chunk overlap, in characters. */
     chunkOverlap?: number;
+    /**
+     * Contextual RAG only. On a re-upsert, a chunk whose text is unchanged keeps its stored blurb and
+     * embedding, and only chunks with new text are sent to the LLM; with GraphRAG it also keeps its graph
+     * entities and is not extracted again. A chunk that carries an image is always written anew. A reused blurb
+     * was written against the previous version of the document; set false when an edit can change the meaning
+     * of text elsewhere in it. Defaults to true.
+     */
+    reuseChunkContext?: boolean;
 };
 /**
  * @category AI
@@ -1331,8 +1356,9 @@ export type AiPiiOptions = {
     /** 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}. Each attempt is
-     * bounded at a minute, so an override has to answer within it.
+     * Model performing the screening. Defaults to {@link DEFAULT_PII_CLASSIFIER_MODEL}, or the app's best
+     * available model when that one is unavailable. 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. */

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

@@ -51,7 +51,7 @@ export declare const OPENAI_CHAT_MODEL_NAMES: readonly ["gpt-5.6-sol", "gpt-5.6-
  * Public Gemini chat model names (active models only).
  * @category AI
  */
-export declare const GEMINI_CHAT_MODEL_NAMES: readonly ["gemini-3.1-pro", "gemini-3.8-flash", "gemini-3.5-flash-lite"];
+export declare const GEMINI_CHAT_MODEL_NAMES: readonly ["gemini-4-argon", "gemini-3.8-flash", "gemini-3.5-flash-lite"];
 /**
  * Public Grok chat model names (active models only).
  * @category AI
@@ -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-5"];
+export declare const ANTHROPIC_CHAT_MODEL_NAMES: readonly ["claude-fable-5", "claude-fable-5-1", "claude-haiku-5-5", "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-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-5-5", "claude-opus-5-5", "claude-sonnet-5-5", "gemini-4-argon", "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

@@ -220,6 +220,13 @@ export interface AiKnowledgeBaseGraphConfig {
     extractionModel?: AiChatModelSelection;
     /** Optional domain taxonomy hint (entity types) injected into the extraction prompt. */
     entityTypes?: string[];
+    /**
+     * How hard per-chunk extraction works. `'thorough'` allows about 40 entities per chunk instead of 15 and runs
+     * at high reasoning effort on OpenAI extraction models: more entities and relationships, a bigger graph (a
+     * listing yields ~40 entities per chunk) and about 1.5x the extraction cost. Like `extractionModel`, a change
+     * reaches already-indexed content on the next `full` rebuild. Defaults to `'standard'`.
+     */
+    extractionDepth?: 'standard' | 'thorough';
     /**
      * Quiet window (milliseconds) after the last graph activity before the sweep auto-builds the
      * structure. Must be a positive integer, and is floored at 3 seconds — a shorter window is not
@@ -528,6 +535,11 @@ export interface AiKnowledgeBaseContext {
      * carry none; their reupsert takes the defaults.
      */
     requestConfig?: AiKnowledgeBaseContextRequestConfig;
+    /**
+     * Set on an attachment of a OneNote section or email that the knowledge base indexed as its own context: the
+     * id of that container. Such contexts are managed with their container and left out of context listings.
+     */
+    parentContextId?: string;
 }
 /**
  * The ingestion request's options only. Everything else a reupsert needs lives on the context itself —
@@ -709,6 +721,14 @@ export type BaseAiKnowledgeBaseContextOptions = {
     ragType?: AiRagType;
     /** Amount of chunk overlap, in characters. */
     chunkOverlap?: number;
+    /**
+     * Contextual RAG only. On a re-upsert, a chunk whose text is unchanged keeps its stored blurb and
+     * embedding, and only chunks with new text are sent to the LLM; with GraphRAG it also keeps its graph
+     * entities and is not extracted again. A chunk that carries an image is always written anew. A reused blurb
+     * was written against the previous version of the document; set false when an edit can change the meaning
+     * of text elsewhere in it. Defaults to true.
+     */
+    reuseChunkContext?: boolean;
 };
 /**
  * Specific options for the AI knowledgebase search method.
@@ -795,9 +815,10 @@ export interface UpsertKnowledgeBaseContextResponse {
     /** List of the upsert status of each item sent in the request. */
     failure?: UpsertContextStatusError;
     /**
-     * Set when the context was stored (and is fully searchable via vector/keyword) but NOT graph-indexed
-     * because the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent; the
-     * singular counterpart of {@link UpsertKnowledgeBaseContextsResponse.graphIndexingSkippedContextIds}.
+     * Set when the context was stored (and is fully searchable via vector/keyword) but NOT graph-indexed by
+     * this upsert: the knowledge base is over its per-KB graph chunk cap, or its stale graph data could not be
+     * pruned, which a later graph rebuild repairs. Only GraphRAG coverage is absent; the singular counterpart
+     * of {@link UpsertKnowledgeBaseContextsResponse.graphIndexingSkippedContextIds}.
      */
     graphIndexingSkipped?: boolean;
     /**
@@ -838,9 +859,10 @@ export interface UpsertKnowledgeBaseContextsResponse {
      */
     contextIds?: Array<AiContextId>;
     /**
-     * Contexts that were stored (and are fully searchable via vector/keyword) but NOT graph-indexed because
-     * the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent; surfaced so a
-     * caller can report the graph-coverage gap. Absent/empty when nothing was skipped or graph is disabled.
+     * Contexts that were stored (and are fully searchable via vector/keyword) but NOT graph-indexed by this
+     * upsert: the knowledge base is over its per-KB graph chunk cap, or their stale graph data could not be
+     * pruned, which a later graph rebuild repairs. Only GraphRAG coverage is absent; surfaced so a caller can
+     * report the graph-coverage gap. Absent/empty when nothing was skipped or graph is disabled.
      */
     graphIndexingSkippedContextIds?: Array<AiContextId>;
     /**
@@ -1549,8 +1571,8 @@ export interface KnowledgeBaseGraphFacetValueStatus {
  *   documents into topics/facets.
  * - `'full'` — wipes the graph and re-extracts entities/relationships from every chunk with an LLM,
  *   then rebuilds the concept layer. The expensive deep-clean: re-extraction dominates its cost.
- *   Only needed when the extraction itself must be redone, e.g. after changing `entityTypes` or
- *   `extractionModel`.
+ *   Only needed when the extraction itself must be redone, e.g. after changing `entityTypes`,
+ *   `extractionModel` or `extractionDepth`.
  * @category AI
  */
 export type KnowledgeBaseGraphRebuildMode = 'full' | 'structural';

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

@@ -24,6 +24,11 @@ export interface AiQueryOptions {
     instructions?: string;
     /** Whether to enable raw results output. */
     enableRawResults?: boolean;
+    /**
+     * When the results are too large to analyze in the answer, skips the analysis and returns the raw results as
+     * files instead, for a caller that processes them itself (e.g. an agent with `executePythonCode`). Default: false.
+     */
+    largeResultsAsFiles?: boolean;
     /** Options for the collection selection stage. */
     selectCollectionsOptions?: AiQuerySelectCollectionsOptions;
     /** Options for the query generation stage. */

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

@@ -1,5 +1,6 @@
 import type { AllAiAgentChatOptions } from './ai-agent.public-types';
 import type { AiAgentId, IntegrationId } from './communication.public-types';
+import type { UpsertSessionRequest } from './session.public-types';
 /**
  * Providers that put a Squid agent on a phone call. `twilio` relays the call to Squid over a WebSocket
  * Squid serves; `openai` is an OpenAI Realtime call Squid answers itself, see
@@ -48,6 +49,11 @@ export interface CreateAiVoiceSessionRequest {
     connectTimeoutSeconds?: number;
     /** Public base URL of the application when it differs from the default, such as a tunnel in local development. */
     relayBaseUrl?: string;
+    /**
+     * The session (`squid.sessions()`) the call runs in: the AI functions of every turn get it as `context.session`.
+     * Attached once, when the call starts.
+     */
+    session?: UpsertSessionRequest;
 }
 /**
  * The opened voice session.
@@ -94,6 +100,11 @@ export interface AnswerOpenAiVoiceCallRequest {
     chatOptions?: AllAiAgentChatOptions;
     /** Free-form data echoed on every session event, for the caller's own bookkeeping. */
     metadata?: Record<string, unknown>;
+    /**
+     * The session (`squid.sessions()`) the call runs in: the AI functions of every turn get it as `context.session`.
+     * Attached once, when the call starts.
+     */
+    session?: UpsertSessionRequest;
 }
 /**
  * The answered OpenAI call.
@@ -148,6 +159,11 @@ export interface StartOpenAiWebVoiceCallRequest {
     chatOptions?: AllAiAgentChatOptions;
     /** Free-form data echoed on every session event, for the caller's own bookkeeping. */
     metadata?: Record<string, unknown>;
+    /**
+     * The session (`squid.sessions()`) the call runs in: the AI functions of every turn get it as `context.session`.
+     * Attached once, when the call starts.
+     */
+    session?: UpsertSessionRequest;
 }
 /**
  * The started browser call.

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

@@ -62,6 +62,8 @@ export interface RunContext {
     headers?: Record<string, any>;
     /** Additional context for OpenAPI requests */
     openApiContext?: OpenApiContext;
+    /** The id of the session (`squid.sessions()`) this request runs in, when the AI agent or LangGraph call attached one. */
+    sessionId?: string;
 }
 /** In the case of OpenAPI, the context of the request is provided in a separate object. */
 export interface OpenApiContext {

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

@@ -399,7 +399,7 @@ export interface DocumentMetadata {
     docModifiedAt?: string;
     /**
      * Source document type: `pdf` | `docx` | `doc` | `pptx` | `ppt` | `xlsx` | `xlsm` | `xls` | `xlsb` |
-     * `eml` | `msg` | `csv` | `tsv` | `md` | `html` | `txt`.
+     * `eml` | `msg` | `one` | `csv` | `tsv` | `md` | `html` | `txt`.
      */
     docType?: string;
 }

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", "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", "twilio", "elevenlabs", "openai_voice", "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", "twilio", "elevenlabs", "openai_voice", "mcp", "a2a", "legend", "teams", "openai_compatible", "openai_compatible_embedding", "bedrock_embedding", "sharepoint", "vertex"];
 /**
  * @category Database
  */

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

@@ -1,3 +1,4 @@
+import { UpsertSessionRequest } from './session.public-types';
 /**
  * Options for starting a new LangGraph run.
  * @category AI
@@ -14,6 +15,13 @@ export interface InvokeLangGraphOptions {
      * passes its own.
      */
     context?: Record<string, unknown>;
+    /**
+     * The session (`squid.sessions()`) the run runs in: nodes read its id from `RunContext.sessionId`. With the app API
+     * key, the run creates the session or updates the one with the same id. Without it, a new id creates the session
+     * with its data and a live one is attached as it is; the graph's `@secureLangGraph` rules see both and can refuse
+     * them.
+     */
+    session?: UpsertSessionRequest;
 }
 /**
  * Options for resuming an interrupted LangGraph thread.
@@ -24,6 +32,24 @@ export interface ResumeLangGraphOptions {
     timeoutMs?: number;
     /** Context of the resumed run, which every node reads as LangGraph's `runtime.context`. */
     context?: Record<string, unknown>;
+    /** The session the resumed run runs in, as for {@link InvokeLangGraphOptions.session}. */
+    session?: UpsertSessionRequest;
+}
+/**
+ * Options for streaming a new LangGraph run.
+ * @category AI
+ */
+export interface StreamLangGraphOptions extends InvokeLangGraphOptions {
+    /** Streams only the tokens of LLM calls with one of these tags, such as those set with `model.withConfig({ tags })`. */
+    tokenTags?: string[];
+}
+/**
+ * Options for streaming the resume of an interrupted LangGraph thread.
+ * @category AI
+ */
+export interface StreamResumeLangGraphOptions extends ResumeLangGraphOptions {
+    /** Streams only the tokens of LLM calls with one of these tags, such as those set with `model.withConfig({ tags })`. */
+    tokenTags?: string[];
 }
 /**
  * Successful result of a LangGraph invocation.
@@ -55,3 +81,63 @@ export interface GetLangGraphStateSuccessResult {
     /** Next nodes to execute. Empty if the graph has completed. */
     next: string[];
 }
+/**
+ * Data a node wrote to LangGraph's stream: `config.writer(data)` in TypeScript, `get_stream_writer()(data)` in Python.
+ * @category AI
+ */
+export interface LangGraphCustomEvent {
+    /** Always `custom`. */
+    type: 'custom';
+    /** What the node wrote, as JSON. */
+    data: unknown;
+}
+/**
+ * Text that an LLM call made by a node streamed. Consecutive tokens of one message can arrive merged.
+ * @category AI
+ */
+export interface LangGraphTokenEvent {
+    /** Always `token`. */
+    type: 'token';
+    /** The id of the message the text belongs to, which is also its id in the graph state. */
+    messageId?: string;
+    /** The node that made the LLM call. */
+    node: string;
+    /** The tags of the LLM call, such as those set with `model.withConfig({ tags })`. */
+    tags: string[];
+    /** The streamed text. */
+    text: string;
+}
+/**
+ * The text of an AI message that a node wrote whole, without streaming it from an LLM call.
+ * @category AI
+ */
+export interface LangGraphMessageEvent {
+    /** Always `message`. */
+    type: 'message';
+    /** The id of the message in the graph state. */
+    messageId?: string;
+    /** The node that wrote the message. */
+    node: string;
+    /** The text of the message. */
+    text: string;
+}
+/**
+ * The result of a streamed run, which is the stream's last event.
+ * @category AI
+ */
+export interface LangGraphResultEvent {
+    /** Always `result`. */
+    type: 'result';
+    /** The result of the run, as `invoke` returns it. */
+    result: InvokeLangGraphSuccessResult;
+    /**
+     * Set when some of the run's events may be missing from the stream: they were lost on the way or arrived too late.
+     * The result itself is complete.
+     */
+    incomplete?: boolean;
+}
+/**
+ * An event of a streamed LangGraph run.
+ * @category AI
+ */
+export type LangGraphStreamEvent = LangGraphCustomEvent | LangGraphTokenEvent | LangGraphMessageEvent | LangGraphResultEvent;

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

@@ -0,0 +1,82 @@
+/**
+ * An app-scoped record of JSON data under an id the app chooses, which expires. See `squid.sessions()`.
+ * @category Sessions
+ */
+export interface Session {
+    /** The id of the session. */
+    id: string;
+    /** The data of the session. */
+    data: Record<string, unknown>;
+    /** When the session was created. */
+    createdAt: Date;
+    /** When the session was last written. */
+    updatedAt: Date;
+    /** When the session expires, or `null` when it never does. */
+    expiresAt: Date | null;
+}
+/**
+ * How long a session lives after its last write: a TTL, or `'never'` to keep it until it is deleted.
+ * @category Sessions
+ */
+export type SessionExpiration = SessionTtl | 'never';
+/**
+ * An expiration a fixed time after the session's last write.
+ * @category Sessions
+ */
+export interface SessionTtl {
+    /** Milliseconds from the last write to the expiration. At least 1000. */
+    ttlMs: number;
+}
+/**
+ * Creates a session, or updates the one with the same id.
+ * @category Sessions
+ */
+export interface UpsertSessionRequest {
+    /** The id of the session: 1-256 characters, without control characters. */
+    id: string;
+    /** Top-level keys to set; other keys keep their values. The session's data is at most 64 KB. */
+    data?: Record<string, unknown>;
+    /** Top-level keys to remove. */
+    deleteKeys?: string[];
+    /** Replaces the session's expiration. A new session expires one day after its last write. */
+    expiration?: SessionExpiration;
+}
+/**
+ * A value a session listing matches a data key against.
+ * @category Sessions
+ */
+export type SessionFilterValue = string | number | boolean | null;
+/**
+ * Filters of a session listing.
+ * @category Sessions
+ */
+export interface ListSessionsFilter {
+    /** Top-level data keys that must equal the given values. */
+    data?: Record<string, SessionFilterValue>;
+    /** Only sessions created after this time. */
+    createdAfter?: Date;
+    /** Only sessions created before this time. */
+    createdBefore?: Date;
+}
+/**
+ * Asks for a page of sessions, newest first.
+ * @category Sessions
+ */
+export interface ListSessionsRequest {
+    /** The page size: 100 by default, at most 1000. */
+    limit?: number;
+    /** The `nextCursor` of the previous page. */
+    cursor?: string;
+    /** Filters of the listing. */
+    where?: ListSessionsFilter;
+}
+/**
+ * A page of sessions.
+ * @category Sessions
+ */
+export interface ListSessionsResponse {
+    /** The sessions of the page, newest first. */
+    sessions: Session[];
+    /** Pass it as `cursor` to get the next page. Absent on the last page. */
+    nextCursor?: string;
+}

package/dist/typescript-client/src/agent/ai-agent-client.types.d.ts

@@ -1,5 +1,5 @@
 import { Observable } from 'rxjs';
-import { AiAnnotation, AiAnswerValidationResult, AiAskModelSelection, AiChatModelSelection, AiChatOptions, AiChatRequestCredentials, AiModelRoutingResult } from '../../../internal-common/src/public-types/ai-agent.public-types';
+import { AiAnnotation, AiAnswerValidationResult, AiAskModelSelection, AiChatModelSelection, AiChatOptions, AiChatRequestCredentials, AiChatRequestSession, AiModelRoutingResult } from '../../../internal-common/src/public-types/ai-agent.public-types';
 /**
  * Response format for transcribing audio and generating a chat response.
  * Contains the transcribed text and a stream of AI-generated responses.
@@ -55,21 +55,21 @@ export interface AskWithVoiceResponse {
  */
 export type AiChatOptionsWithoutVoice<T extends AiAskModelSelection | undefined = undefined> = Omit<AiChatOptions<ConcreteModelOf<T>>, 'voiceOptions' | 'model'> & {
     model?: T;
-} & AiChatRequestCredentials;
+} & AiChatRequestCredentials & AiChatRequestSession;
 /**
  * Options for AI-generated responses that exclude voice-specific settings and smooth typing behavior.
  * @category AI
  */
 export type AiAskOptions<T extends AiAskModelSelection | undefined = undefined> = Omit<AiChatOptions<ConcreteModelOf<T>>, 'voiceOptions' | 'smoothTyping' | 'model'> & {
     model?: T;
-} & AiChatRequestCredentials;
+} & AiChatRequestCredentials & AiChatRequestSession;
 /**
  * Options for AI-generated responses that include voice-specific settings but excludes smooth typing.
  * @category AI
  */
 export type AiAskOptionsWithVoice<T extends AiAskModelSelection | undefined = undefined> = Omit<AiChatOptions<ConcreteModelOf<T>>, 'smoothTyping' | 'model'> & {
     model?: T;
-} & AiChatRequestCredentials;
+} & AiChatRequestCredentials & AiChatRequestSession;
 /**
  * The concrete model a request's model selection names, which picks the provider-specific option set;
  * a routing choice names none, so it gets the provider-agnostic options.

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

@@ -227,7 +227,7 @@ export declare class AiKnowledgeBaseReference {
      * entity graph (extracting only contexts never graph-indexed) and rebuilds just the concept layer
      * (topics + facets); `mode: 'full'` wipes the graph and re-extracts every context with an LLM —
      * expensive, and only needed when the extraction itself must be redone (e.g. after changing
-     * `entityTypes` or `extractionModel`). Requires `graphRag.enabled`. Track progress via
+     * `entityTypes`, `extractionModel` or `extractionDepth`). Requires `graphRag.enabled`. Track progress via
      * {@link getGraphStatus}'s `buildJob`; only one rebuild can run per knowledge base at a time.
      */
     rebuildGraph(request?: Omit<RebuildKnowledgeBaseGraphRequest, 'knowledgeBaseId'>): Promise<void>;

package/dist/typescript-client/src/index.d.ts

@@ -60,6 +60,7 @@ export * from './rpc.manager';
 export * from './runtime-options';
 export * from './scheduler-client';
 export * from './secret.client';
+export * from './session-client';
 export * from './socket.manager';
 export * from './squid';
 export * from './squid-http-client';

package/dist/typescript-client/src/langgraph-client.d.ts

@@ -1,5 +1,6 @@
+import { Observable } from 'rxjs';
 import { JobId } from '../../internal-common/src/public-types/job.public-types';
-import { GetLangGraphStateSuccessResult, InvokeLangGraphOptions, InvokeLangGraphSuccessResult, ResumeLangGraphOptions } from '../../internal-common/src/public-types/langgraph.public-types';
+import { GetLangGraphStateSuccessResult, InvokeLangGraphOptions, InvokeLangGraphSuccessResult, LangGraphStreamEvent, ResumeLangGraphOptions, StreamLangGraphOptions, StreamResumeLangGraphOptions } from '../../internal-common/src/public-types/langgraph.public-types';
 /**
  * Reference to a specific LangGraph.
  * @category AI
@@ -8,6 +9,7 @@ export declare class LangGraphReference {
     private readonly graphId;
     private readonly rpcManager;
     private readonly jobClient;
+    private readonly socketManager;
     /**
      * Starts a new LangGraph run and waits for the result.
      *
@@ -43,6 +45,24 @@ export declare class LangGraphReference {
      * @param options Optional timeout and context of the resumed run.
      */
     resumeAsync(threadId: string, resumePayload: unknown, options?: ResumeLangGraphOptions): Promise<JobId>;
+    /**
+     * Starts a new LangGraph run and streams its events: what nodes write with LangGraph's stream writer, the tokens
+     * of the LLM calls that nodes make, and the AI messages that nodes write whole. The last event is the result.
+     *
+     * Every subscription starts a run, and unsubscribing does not stop it. Streaming needs the client's socket, so a
+     * passive client throws.
+     *
+     * @param options Initial state, thread, timeout, context and session of the run, and which tokens to stream.
+     */
+    stream(options?: StreamLangGraphOptions): Observable<LangGraphStreamEvent>;
+    /**
+     * Resumes an interrupted LangGraph thread and streams the events of the resumed run, as {@link stream} does.
+     *
+     * @param threadId The thread to resume.
+     * @param resumePayload Value passed to the `interrupt()` call inside the graph.
+     * @param options Timeout, context and session of the resumed run, and which tokens to stream.
+     */
+    resumeStream(threadId: string, resumePayload: unknown, options?: StreamResumeLangGraphOptions): Observable<LangGraphStreamEvent>;
     /** Returns the current state of a LangGraph thread. */
     getState(threadId: string): Promise<GetLangGraphStateSuccessResult>;
     /**
@@ -53,4 +73,6 @@ export declare class LangGraphReference {
      * @param threadId The thread to delete.
      */
     deleteThread(threadId: string): Promise<void>;
+    /** Runs the request with its events sent to this client's socket, and ends the stream with the run's result. */
+    private streamRun;
 }

package/dist/typescript-client/src/public-types.d.ts

@@ -32,6 +32,7 @@ export * from '../../internal-common/src/public-types/scheduler.public-types';
 export * from '../../internal-common/src/public-types/schema.public-types';
 export * from '../../internal-common/src/public-types/secret.public-types';
 export * from '../../internal-common/src/public-types/serialized-query.public-types';
+export * from '../../internal-common/src/public-types/session.public-types';
 export * from '../../internal-common/src/public-types/socket.public-types';
 export * from '../../internal-common/src/public-types/source-code.public-types';
 export * from '../../internal-common/src/public-types/typescript.public-types';

package/dist/typescript-client/src/session-client.d.ts

@@ -0,0 +1,21 @@
+import { ListSessionsRequest, ListSessionsResponse, Session, UpsertSessionRequest } from './public-types';
+/**
+ * Stores sessions: app-scoped JSON records under ids the app chooses, which expire. Every call needs the app API key.
+ *
+ * A client without the API key starts a session, or attaches a live one, through an AI agent or LangGraph call.
+ * @category Sessions
+ */
+export declare class SessionClient {
+    private readonly rpcManager;
+    /**
+     * Creates the session, or updates the one with the same id, and returns it as stored. Every upsert moves the
+     * expiration to its TTL from now.
+     */
+    upsert(request: UpsertSessionRequest): Promise<Session>;
+    /** Returns the session, or `undefined` when it is missing or expired. */
+    get(id: string): Promise<Session | undefined>;
+    /** Deletes the session. Deleting a missing session does nothing. */
+    delete(id: string): Promise<void>;
+    /** Returns a page of sessions, newest first. */
+    list(request?: ListSessionsRequest): Promise<ListSessionsResponse>;
+}

package/dist/typescript-client/src/squid.d.ts

@@ -15,6 +15,7 @@ import { ObservabilityClient } from './observability-client';
 import { ApiKey, AppId, CollectionName, DocumentData, EnvironmentId, IntegrationId, SquidDeveloperId, SquidRegion } from './public-types';
 import { QueueManager } from './queue.manager';
 import { SchedulerClient } from './scheduler-client';
+import { SessionClient } from './session-client';
 import { StorageClient } from './storage-client';
 import { TransactionId } from './types';
 import { WebClient } from './web-client';
@@ -72,6 +73,12 @@ export interface SquidOptions {
      * In passive mode, real-time features (WebSocket) are disabled.
      */
     isPassiveMode?: boolean;
+    /**
+     * Overrides the Squid API URL derived from the region, e.g. an in-cluster address such as
+     * `http://core.default:8000`. Requests then identify the application with the `x-squid-appid` header.
+     * Public URLs such as the one `getWebhookUrl` returns keep using the region.
+     */
+    baseUrl?: string;
 }
 /**
  * Authentication data provider for Squid requests.
@@ -125,6 +132,7 @@ export declare class Squid {
     private readonly aiClient;
     private readonly jobClient;
     private readonly langGraphClient;
+    private readonly sessionClient;
     private readonly apiClient;
     private readonly adminClient;
     private readonly webClient;
@@ -335,6 +343,10 @@ export declare class Squid {
      * Returns a reference to a LangGraph by ID.
      */
     langGraph(graphId: string): LangGraphReference;
+    /**
+     * Returns a set of functionality for storing sessions: app-scoped JSON records that expire. Needs the app API key.
+     */
+    sessions(): SessionClient;
     /**
      * Returns a set of functionality for interacting with API integrations.
      */

package/dist/typescript-client/src/version.d.ts

@@ -2,4 +2,4 @@
  * The current version of the SquidCloud client package.
  * @category Platform
  */
-export declare const SQUIDCLOUD_CLIENT_PACKAGE_VERSION = "1.0.502";
+export declare const SQUIDCLOUD_CLIENT_PACKAGE_VERSION = "1.0.504";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/client",
-  "version": "1.0.502",
+  "version": "1.0.504",
   "description": "A typescript implementation of the Squid client",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",