@anuma/sdk 6.33.1 → 6.34.0

package/dist/index.d.ts

@@ -1,126 +1,396 @@
-type AuthToken = string | undefined;
-interface Auth {
+/**
+ * Cross-platform primitive constants.
+ *
+ * This module is intentionally dependency-free and side-effect-free so it can
+ * be loaded by *any* consumer — including React Native / Hermes — without
+ * pulling in the rest of the SDK. It is published as the `@anuma/sdk/constants`
+ * subpath (which carries a `react-native` export condition); slim consumers
+ * such as the agent packages import values from here instead of the bare
+ * `@anuma/sdk` entry, whose Node/web bundle is not RN-safe.
+ *
+ * Only add genuinely pure, cross-platform constants here (numeric/string
+ * literals, default IDs, size caps). No classes, no runtime APIs, no imports.
+ */
+/** Character cap for multiline / textarea fields. Agent gateways (e.g. cf-tasks)
+ *  truncate values to this length before interpolating them into prompt templates.
+ *  Shared across all agent packages so a single change updates every journey
+ *  declaration simultaneously. */
+declare const MULTILINE_FIELD_MAX = 50000;
+
+/** Runtime environment where the agent can execute. */
+type AgentRuntime = "client" | "server";
+/** Strategy a consumer should use to extract text from an uploaded file before
+ *  feeding it into a skill journey field. The SDK only labels the strategy —
+ *  the actual extraction (pdf.js, OCR, etc.) is the consumer's responsibility. */
+type FileExtractionStrategy = "pdf-text" | "csv-text" | "image-ocr";
+
+/** Configuration for a single agent skill (task template). */
+interface SkillConfig {
+    /** Unique identifier. Convention: "domain.action" e.g. "housing.lease-review" */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** System prompt template with {{variable}} placeholders. */
+    promptTemplate: string;
     /**
-     * Which part of the request do we use to send the auth?
-     *
-     * @default 'header'
+     * User-turn template, interpolated with the same {{variable}} placeholders
+     * as `promptTemplate`. Optional, but strongly recommended for skill-driven
+     * (non-freeform) flows so the model receives a proper user turn — most
+     * Anthropic models reject requests that contain only a system message.
      */
-    in?: 'header' | 'query' | 'cookie';
+    userTemplate?: string;
+    /** MCP tool names this skill requires. */
+    requiredTools?: string[];
+    /** Preferred model when the caller doesn't specify one. */
+    preferredModel?: string;
+    /** Max agentic loop steps for this skill. */
+    maxSteps?: number;
+    /** Variables the promptTemplate expects at runtime. */
+    requiredVariables?: string[];
     /**
-     * Header or query parameter name.
+     * SMS-friendly question prompts keyed by variable name. The Anuma text
+     * gateway sends each prompt to the user one at a time and treats the
+     * user's reply as the slot value. Missing entries fall back to a
+     * generic "Please provide {name}." question in the gateway.
      *
-     * @default 'Authorization'
+     * Order of questions follows requiredVariables[] order.
      */
-    name?: string;
-    scheme?: 'basic' | 'bearer';
-    type: 'apiKey' | 'http';
+    smsPrompts?: Record<string, string>;
+    /** Additional context appended after the prompt template. */
+    contextSuffix?: string;
+    /** Lucide icon identifier (e.g. "FileSearch") for renderers that draw a skill icon. */
+    iconName?: string;
+    /** One-line announcement string shown when the skill is launched (channel-neutral). */
+    launchMessage?: string;
+    /** Conversational preamble shown after the user picks this skill, before the field
+     *  questions begin. Used by chat-native guided flows (web, mobile, SMS, voice). */
+    preamble?: string;
+    /** Closing line shown after the user finishes the last field and before the agent
+     *  starts the tool loop. Used by chat-native guided flows. */
+    closing?: string;
+    /** Fallback nudge for any required field on this skill that doesn't define its own
+     *  `requiredNudge` string. */
+    requiredNudgeDefault?: string;
 }
-
-interface SerializerOptions<T> {
-    /**
-     * @default true
-     */
-    explode: boolean;
-    style: T;
+/** Public-safe manifest describing an agent (no prompt or tool details). */
+interface AgentManifest {
+    id: string;
+    name: string;
+    description: string;
+    runtimes: AgentRuntime[];
+    skills: Array<{
+        id: string;
+        name: string;
+        requiredVariables?: string[];
+        smsPrompts?: Record<string, string>;
+    }>;
 }
-type ArrayStyle = 'form' | 'spaceDelimited' | 'pipeDelimited';
-type ObjectStyle = 'form' | 'deepObject';
-
-type QuerySerializer = (query: Record<string, unknown>) => string;
-type BodySerializer = (body: unknown) => unknown;
-type QuerySerializerOptionsObject = {
-    allowReserved?: boolean;
-    array?: Partial<SerializerOptions<ArrayStyle>>;
-    object?: Partial<SerializerOptions<ObjectStyle>>;
-};
-type QuerySerializerOptions = QuerySerializerOptionsObject & {
-    /**
-     * Per-parameter serialization overrides. When provided, these settings
-     * override the global array/object settings for specific parameter names.
-     */
-    parameters?: Record<string, QuerySerializerOptionsObject>;
-};
-
-type HttpMethod = 'connect' | 'delete' | 'get' | 'head' | 'options' | 'patch' | 'post' | 'put' | 'trace';
-type Client$1<RequestFn = never, Config = unknown, MethodFn = never, BuildUrlFn = never, SseFn = never> = {
-    /**
-     * Returns the final request URL.
-     */
-    buildUrl: BuildUrlFn;
-    getConfig: () => Config;
-    request: RequestFn;
-    setConfig: (config: Config) => Config;
-} & {
-    [K in HttpMethod]: MethodFn;
-} & ([SseFn] extends [never] ? {
-    sse?: never;
-} : {
-    sse: {
-        [K in HttpMethod]: SseFn;
-    };
+/** Allowed input types for skill journey form fields. */
+type SkillJourneyFieldType = "text" | "textarea" | "select";
+/** Properties shared by every skill journey field, regardless of input type. */
+interface SkillJourneyFieldBase {
+    key: string;
+    label: string;
+    placeholder: string;
+    helper?: string;
+    required?: boolean;
+    /** Conversational ask used by chat-native guided flows (web, mobile, SMS, voice).
+     *  Falls through to `label` when not set. */
+    chatPrompt?: string;
+    /** Skill-specific nudge shown when the user skips a required field. Falls through
+     *  to `SkillConfig.requiredNudgeDefault` when not set. */
+    requiredNudge?: string;
+    /** Server-side sanitiser cap on the value's character length. Today's gateways
+     *  truncate textarea fields at `MULTILINE_FIELD_MAX` characters. */
+    maxLength?: number;
+}
+/**
+ * A single field in a skill journey intake form. Discriminated on `type`:
+ * `select` requires `options`; `text` / `textarea` cannot carry options.
+ */
+type SkillJourneyField = (SkillJourneyFieldBase & {
+    type: "text" | "textarea";
+}) | (SkillJourneyFieldBase & {
+    type: "select";
+    options: string[];
 });
-interface Config$1 {
-    /**
-     * Auth token or a function returning auth token. The resolved value will be
-     * added to the request payload as defined by its `security` array.
-     */
-    auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
-    /**
-     * A function for serializing request body parameter. By default,
-     * {@link JSON.stringify()} will be used.
-     */
-    bodySerializer?: BodySerializer | null;
-    /**
-     * An object containing any HTTP headers that you want to pre-populate your
-     * `Headers` object with.
-     *
-     * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
-     */
-    headers?: RequestInit['headers'] | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined | unknown>;
-    /**
-     * The request method.
-     *
-     * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
-     */
-    method?: Uppercase<HttpMethod>;
-    /**
-     * A function for serializing request query parameters. By default, arrays
-     * will be exploded in form style, objects will be exploded in deepObject
-     * style, and reserved characters are percent-encoded.
-     *
-     * This method will have no effect if the native `paramsSerializer()` Axios
-     * API function is used.
-     *
-     * {@link https://swagger.io/docs/specification/serialization/#query View examples}
-     */
-    querySerializer?: QuerySerializer | QuerySerializerOptions;
-    /**
-     * A function validating request data. This is useful if you want to ensure
-     * the request conforms to the desired shape, so it can be safely sent to
-     * the server.
-     */
-    requestValidator?: (data: unknown) => Promise<unknown>;
-    /**
-     * A function transforming response data before it's returned. This is useful
-     * for post-processing data, e.g., converting ISO strings into Date objects.
-     */
-    responseTransformer?: (data: unknown) => Promise<unknown>;
+/** Full definition for rendering a skill intake form and building the prompt. */
+interface SkillJourneyDefinition {
+    title: string;
+    description: string;
+    steps: string[];
+    /** When true, the journey renders a file upload step before the fields. */
+    acceptsFiles: boolean;
+    /** Label for the file upload step. Only meaningful when `acceptsFiles` is true. */
+    fileLabel?: string;
+    /** Helper text for the file upload step. Only meaningful when `acceptsFiles` is true. */
+    fileHint?: string;
+    /** Per-skill copy for the file upload step prompt. Only meaningful when `acceptsFiles` is true. */
+    filePrompt?: string;
+    /** How consumers should derive text from an attached file. Describes extraction
+     *  only — it is **not** a file-type filter. Files outside the strategy's expected
+     *  MIME type (e.g. photos when the strategy is `pdf-text`) are still uploaded and
+     *  forwarded to the agent as attachments; they are simply not text-extracted.
+     *  The extracted text is written to the variable named by `extractedTextTarget`.
+     *  Only meaningful when `acceptsFiles` is true. */
+    fileExtractionStrategy?: FileExtractionStrategy;
+    /** Variable name to write extracted text into. May coincide with a field's `key`
+     *  (the upload replaces typed input for that field, e.g. `lease_text`) or name a
+     *  separate template variable not tied to any field (e.g. `rent_notice_text`,
+     *  `supporting_document_text`). Only meaningful when `acceptsFiles` is true and
+     *  `fileExtractionStrategy` is set. */
+    extractedTextTarget?: string;
+    fields: SkillJourneyField[];
     /**
-     * A function validating response data. This is useful if you want to ensure
-     * the response conforms to the desired shape, so it can be safely passed to
-     * the transformers and returned to the user.
+     * When true, the journey expects substantive input — at least one of an
+     * `acceptsFiles` upload or a text/textarea field — for the agent to act on.
+     * Consumers (form renderers and direct API callers alike) should enforce
+     * "file or text provided" before invoking the skill.
      */
-    responseValidator?: (data: unknown) => Promise<unknown>;
+    requiresContext: boolean;
+    submitLabel: string;
+    promptTitle: string;
+    /** Extra system prompt context injected per-skill for structured output guidance. */
+    systemContext?: string;
 }
-
-type ServerSentEventsOptions<TData = unknown> = Omit<RequestInit, 'method'> & Pick<Config$1, 'method' | 'responseTransformer' | 'responseValidator'> & {
-    /**
-     * Fetch API implementation. You can use this option to provide a custom
-     * fetch instance.
-     *
-     * @default globalThis.fetch
-     */
-    fetch?: typeof fetch;
+/** Marketplace filter the agent should appear under in the picker UI. */
+type AgentMarketplaceFamily = "text" | "lifestyle";
+/** What kind of action the marketplace card's primary CTA performs. */
+type AgentPrimaryActionKind = "text" | "group" | "guided";
+/** Visual tone for a transcript section heading. */
+type AgentTranscriptTone = "danger" | "warning" | "success";
+/** A single bullet inside a marketplace analysis transcript section. */
+interface AgentTranscriptItem {
+    title: string;
+    detail: string;
+}
+/** A grouped block of bullets in a marketplace analysis transcript. */
+interface AgentAnalysisSection {
+    title: string;
+    tone: AgentTranscriptTone;
+    items: AgentTranscriptItem[];
+}
+/** A todo entry inside a marketplace agenda transcript. */
+interface AgentAgendaItem {
+    title: string;
+    badge?: string;
+    badgeTone?: "warning" | "danger";
+}
+/** A schedule entry inside a marketplace agenda transcript. */
+interface AgentScheduleItem {
+    title: string;
+    time: string;
+}
+/** Marketplace transcript shape for productivity / agenda style agents. */
+interface AgentAgendaTranscript {
+    kind: "agenda";
+    userMessage: string;
+    intro: string;
+    todos: AgentAgendaItem[];
+    schedule: AgentScheduleItem[];
+    followUp: string;
+    actions: string[];
+}
+/** Marketplace transcript shape for analysis / dispute style agents. */
+interface AgentAnalysisTranscript {
+    kind: "analysis";
+    userMessage: string;
+    intro: string;
+    sections: AgentAnalysisSection[];
+    followUp: string;
+    actions: string[];
+}
+/** A scripted marketplace conversation preview, discriminated on `kind`. */
+type AgentMarketplaceTranscript = AgentAgendaTranscript | AgentAnalysisTranscript;
+/** Marketplace card content for an agent — the data the picker UI renders. */
+interface AgentMarketplaceContent {
+    family: AgentMarketplaceFamily;
+    roleLabel: string;
+    primaryActionLabel: string;
+    primaryActionKind: AgentPrimaryActionKind;
+    cardUseCases: string[];
+    cardKnowledge: string[];
+    quickPrompts: string[];
+    emptyStateDescription: string;
+    transcript: AgentMarketplaceTranscript;
+}
+/** A single (user, agent) example conversation entry, keyed by i18n string ids. */
+interface AgentExampleConversation {
+    userKey: string;
+    agentKey: string;
+}
+/** UI metadata used by clients when the portal doesn't supply richer data. */
+interface AgentUiMetadata {
+    /** Hex color used by the agent card and accents. */
+    color: string;
+    /** Lucide icon identifier (e.g. "users"). */
+    icon: string;
+    /** i18n keys for the per-agent feature bullets. */
+    features: string[];
+    /** i18n keys for the example conversation strings. */
+    exampleConversations: AgentExampleConversation[];
+    /** Memory folder names this agent typically uses. */
+    suggestedMemoryFolders?: string[];
+}
+/** Full agent configuration including prompt, skills, tools, and model settings. */
+interface AgentConfig {
+    id: string;
+    runtimes: AgentRuntime[];
+    prompt: string;
+    skills: SkillConfig[];
+    /** Tool configs are agent-specific, so we keep this generic. */
+    tools: unknown[];
+    model: {
+        default: string;
+        allowed?: string[];
+    };
+    manifest: AgentManifest;
+    /** Form schemas for rendering skill intake forms on the client. */
+    skillJourneys?: Record<string, SkillJourneyDefinition>;
+    /** First assistant message shown when the agent is opened. Supports the
+     *  `{{agent_name}}` placeholder so consumers can substitute the portal-display
+     *  name without changing this string. */
+    greeting?: string;
+    /** Sub-copy shown under the agent picker / guided-flow header. Supports the
+     *  `{{agent_name}}` placeholder, same as `greeting`. */
+    guidedFlowSubcopy?: string;
+    /** Marketplace card content rendered in the agent picker. */
+    marketplace?: AgentMarketplaceContent;
+    /** UI metadata (color, icon, example conversations) for renderer fallbacks. */
+    uiMetadata?: AgentUiMetadata;
+    /** One-time disclaimer shown in a popup the first time a user opens
+     *  a chat with this agent. Plain text; consumers split on `\n\n` for paragraphs.
+     *  May include `{{agent_name}}` placeholder. */
+    firstTimeDisclaimer?: string;
+    /** Persistent one-line disclaimer rendered under the chat input
+     *  whenever this agent's chat is open. May include `{{agent_name}}`
+     *  placeholder. */
+    persistentFooter?: string;
+}
+
+type AuthToken = string | undefined;
+interface Auth {
+    /**
+     * Which part of the request do we use to send the auth?
+     *
+     * @default 'header'
+     */
+    in?: 'header' | 'query' | 'cookie';
+    /**
+     * Header or query parameter name.
+     *
+     * @default 'Authorization'
+     */
+    name?: string;
+    scheme?: 'basic' | 'bearer';
+    type: 'apiKey' | 'http';
+}
+
+interface SerializerOptions<T> {
+    /**
+     * @default true
+     */
+    explode: boolean;
+    style: T;
+}
+type ArrayStyle = 'form' | 'spaceDelimited' | 'pipeDelimited';
+type ObjectStyle = 'form' | 'deepObject';
+
+type QuerySerializer = (query: Record<string, unknown>) => string;
+type BodySerializer = (body: unknown) => unknown;
+type QuerySerializerOptionsObject = {
+    allowReserved?: boolean;
+    array?: Partial<SerializerOptions<ArrayStyle>>;
+    object?: Partial<SerializerOptions<ObjectStyle>>;
+};
+type QuerySerializerOptions = QuerySerializerOptionsObject & {
+    /**
+     * Per-parameter serialization overrides. When provided, these settings
+     * override the global array/object settings for specific parameter names.
+     */
+    parameters?: Record<string, QuerySerializerOptionsObject>;
+};
+
+type HttpMethod = 'connect' | 'delete' | 'get' | 'head' | 'options' | 'patch' | 'post' | 'put' | 'trace';
+type Client$1<RequestFn = never, Config = unknown, MethodFn = never, BuildUrlFn = never, SseFn = never> = {
+    /**
+     * Returns the final request URL.
+     */
+    buildUrl: BuildUrlFn;
+    getConfig: () => Config;
+    request: RequestFn;
+    setConfig: (config: Config) => Config;
+} & {
+    [K in HttpMethod]: MethodFn;
+} & ([SseFn] extends [never] ? {
+    sse?: never;
+} : {
+    sse: {
+        [K in HttpMethod]: SseFn;
+    };
+});
+interface Config$1 {
+    /**
+     * Auth token or a function returning auth token. The resolved value will be
+     * added to the request payload as defined by its `security` array.
+     */
+    auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
+    /**
+     * A function for serializing request body parameter. By default,
+     * {@link JSON.stringify()} will be used.
+     */
+    bodySerializer?: BodySerializer | null;
+    /**
+     * An object containing any HTTP headers that you want to pre-populate your
+     * `Headers` object with.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
+     */
+    headers?: RequestInit['headers'] | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined | unknown>;
+    /**
+     * The request method.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
+     */
+    method?: Uppercase<HttpMethod>;
+    /**
+     * A function for serializing request query parameters. By default, arrays
+     * will be exploded in form style, objects will be exploded in deepObject
+     * style, and reserved characters are percent-encoded.
+     *
+     * This method will have no effect if the native `paramsSerializer()` Axios
+     * API function is used.
+     *
+     * {@link https://swagger.io/docs/specification/serialization/#query View examples}
+     */
+    querySerializer?: QuerySerializer | QuerySerializerOptions;
+    /**
+     * A function validating request data. This is useful if you want to ensure
+     * the request conforms to the desired shape, so it can be safely sent to
+     * the server.
+     */
+    requestValidator?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function transforming response data before it's returned. This is useful
+     * for post-processing data, e.g., converting ISO strings into Date objects.
+     */
+    responseTransformer?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function validating response data. This is useful if you want to ensure
+     * the response conforms to the desired shape, so it can be safely passed to
+     * the transformers and returned to the user.
+     */
+    responseValidator?: (data: unknown) => Promise<unknown>;
+}
+
+type ServerSentEventsOptions<TData = unknown> = Omit<RequestInit, 'method'> & Pick<Config$1, 'method' | 'responseTransformer' | 'responseValidator'> & {
+    /**
+     * Fetch API implementation. You can use this option to provide a custom
+     * fetch instance.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: typeof fetch;
     /**
      * Implementing clients can call request interceptors inside this hook.
      */
@@ -7226,22 +7496,68 @@ type LlmapiChatCompletionResponse = Omit<LlmapiChatCompletionResponse$1, "usage"
 };
 
 /**
- * PII detection patterns for structured data types.
+ * True when a text part is the attachment-contents part built by {@link buildAttachedFilesText}.
  *
- * Each pattern has a category (used for placeholder tags like [EMAIL_1]),
- * a regex, and an optional validator for reducing false positives.
+ * Matches the whole generated shape — opening tag plus the fixed header line, and the closing
+ * tag — not just the tag, so user text that merely starts with `<attached_files>` is still
+ * treated as the user's prompt.
  */
-type PiiCategory = "EMAIL" | "PHONE" | "SSN" | "CREDIT_CARD" | "IP_ADDRESS" | "API_KEY" | "US_ADDRESS" | "DATE_OF_BIRTH";
-interface PiiPattern {
-    /**
-     * Placeholder tag prefix for matches. Built-ins use {@link PiiCategory};
-     * custom patterns may use any string (e.g. "PASSPORT", "IBAN").
-     */
-    category: PiiCategory | (string & {});
-    regex: RegExp;
-    /** Optional post-match validation to reduce false positives. */
-    validate?: (match: string) => boolean;
-    /**
+declare function isAttachedFilesText(text: string | undefined | null): boolean;
+/**
+ * Wrap a turn's extracted file contents (the `[Extracted content from <name>]`
+ * blocks `preprocessFiles` emits) in the tagged part that rides on that turn's
+ * user message.
+ */
+declare function buildAttachedFilesText(fileContext: string): string;
+/**
+ * Put the current turn's extracted attachment contents on the last user
+ * message, as a text part inserted right after that message's LAST text part:
+ * after everything the user wrote, and before any parts that follow it
+ * (typically images). With interleaved parts such as `[text, image, text,
+ * image]` it lands between the second text and the second image.
+ *
+ * Why not a system message: a detached system message at the front of the
+ * request ("the user has attached files to this conversation") is separated
+ * from the words that refer to it by the whole system prompt, tool catalog and
+ * history. In a long, multi-file conversation fast models stopped connecting
+ * the two and told users the attachment was unreadable even though its text
+ * was in the request. Keeping the contents on the turn that attached them is
+ * how native file attachments work on every provider, and survives the auto
+ * router switching models between turns.
+ *
+ * The part goes AFTER the user's own text because the portal's query
+ * classifier routes on the first text part of the last user message — it must
+ * keep reading the user's prompt, not the document.
+ *
+ * Returns a new array; the input is not mutated. When there is no user
+ * message the messages are returned unchanged.
+ */
+declare function attachFileContextToLastUserMessage(messages: LlmapiMessage[], fileContext: string): LlmapiMessage[];
+
+/**
+ * Value of the `origin` column on a row the SDK synthesised for a turn's tool results (v44, #866).
+ *
+ * `satisfies MessageOrigin` so this constant and the column's union cannot drift apart silently.
+ */
+declare const TOOL_RESULT_ORIGIN = "tool_result";
+
+/**
+ * PII detection patterns for structured data types.
+ *
+ * Each pattern has a category (used for placeholder tags like [EMAIL_1]),
+ * a regex, and an optional validator for reducing false positives.
+ */
+type PiiCategory = "EMAIL" | "PHONE" | "SSN" | "CREDIT_CARD" | "IP_ADDRESS" | "API_KEY" | "US_ADDRESS" | "DATE_OF_BIRTH";
+interface PiiPattern {
+    /**
+     * Placeholder tag prefix for matches. Built-ins use {@link PiiCategory};
+     * custom patterns may use any string (e.g. "PASSPORT", "IBAN").
+     */
+    category: PiiCategory | (string & {});
+    regex: RegExp;
+    /** Optional post-match validation to reduce false positives. */
+    validate?: (match: string) => boolean;
+    /**
      * Optional context guard. When set, a match is only redacted if this regex
      * matches the text immediately preceding it (a short window). Used to require
      * a cue word — e.g. only treat a date as a date-of-birth when "DOB" / "born"
@@ -7263,23 +7579,6 @@ interface PiiPattern {
  */
 declare const PII_PATTERNS: PiiPattern[];
 
-/**
- * NER detector contract for PII redaction.
- *
- * The regex layer in {@link ./patterns} handles *structured* PII (email, phone,
- * SSN, credit card, …). It cannot detect *unstructured* PII — person names,
- * locations, organizations — which need a named-entity-recognition model.
- *
- * Rather than bundle a model (and a runtime) into the SDK, we define a small
- * runtime-agnostic contract: a {@link NerDetector} takes text and returns the
- * spans it found. Consumers supply an implementation appropriate to their
- * platform — a Transformers.js model in the browser/Node (see
- * `./detectors/transformers`), an `onnxruntime-react-native` model on mobile,
- * a remote service, or a fake in tests. The SDK keeps detection *on-device* by
- * never calling out itself; it only consumes the spans a detector returns and
- * merges them into the existing placeholder map.
- */
-
 /**
  * A character-offset span of detected PII. `start`/`end` are indices into the
  * text passed to {@link NerDetector.detect} (`end` exclusive). `category`
@@ -7308,17 +7607,6 @@ interface NerDetector {
     detect(text: string): Promise<PiiSpan[]>;
 }
 
-/**
- * PII redaction engine.
- *
- * Scans text for personally identifiable information, replaces matches with
- * tagged placeholders ([EMAIL_1], [PHONE_2], …), and maintains a mapping
- * table so the original values can be restored in LLM responses.
- *
- * One `PiiRedactor` instance should be used per conversation to keep
- * placeholder numbering consistent across turns.
- */
-
 interface PiiMatch {
     category: PiiCategory | (string & {});
     original: string;
@@ -7604,36 +7892,6 @@ declare function createStreamingDeAnonymizer(redactor: PiiRedactor, emit: (chunk
     flush: () => void;
 };
 
-/**
- * Union type for API responses - raw pass-through from server.
- * Responses API returns LlmapiResponseResponse (with output[]).
- * Completions API returns LlmapiChatCompletionResponse (with choices[]).
- */
-type ApiResponse = LlmapiResponseResponse | LlmapiChatCompletionResponse;
-/**
- * Portal-side fields live under `response.portal` for the Chat Completions API
- * (new OpenAI-compliant wire shape) and at the top level for the Responses API.
- *
- * The SDK's `buildFinalResponse` mirrors portal fields back onto the top level
- * (and into `usage`) for backwards compatibility, so for streaming chat
- * completions both paths carry the data. For non-streaming chat completions
- * the wire ships only the portal-nested form.
- *
- * Precedence is per *field*, not per object: `portal?.x ?? legacy.x` reads the
- * portal field when it is non-nullish and otherwise falls through to the legacy
- * location — so a present-but-partial `portal` (e.g. checksum set, cost unset)
- * still resolves each field from wherever it actually carries a value.
- */
-declare function getToolCallEvents(r: ApiResponse): LlmapiToolCallEvent[] | undefined;
-declare function getCostMicroUsd(r: ApiResponse): number | undefined;
-declare function getCreditsUsed(r: ApiResponse): number | undefined;
-/**
- * Image model the portal resolved for the request (set when an image-generation
- * tool ran). Chat Completions ships it under `portal.image_model` with a legacy
- * top-level mirror; the Responses API keeps it at the top level.
- */
-declare function getImageModel(r: ApiResponse): string | undefined;
-
 /**
  * Tool executor function type
  */
@@ -7710,11 +7968,100 @@ type ToolConfig = LlmapiChatCompletionTool & {
 };
 
 /**
- * Server-side tools caching module
+ * Union type for API responses - raw pass-through from server.
+ * Responses API returns LlmapiResponseResponse (with output[]).
+ * Completions API returns LlmapiChatCompletionResponse (with choices[]).
+ */
+type ApiResponse = LlmapiResponseResponse | LlmapiChatCompletionResponse;
+/**
+ * Portal-side fields live under `response.portal` for the Chat Completions API
+ * (new OpenAI-compliant wire shape) and at the top level for the Responses API.
+ *
+ * The SDK's `buildFinalResponse` mirrors portal fields back onto the top level
+ * (and into `usage`) for backwards compatibility, so for streaming chat
+ * completions both paths carry the data. For non-streaming chat completions
+ * the wire ships only the portal-nested form.
+ *
+ * Precedence is per *field*, not per object: `portal?.x ?? legacy.x` reads the
+ * portal field when it is non-nullish and otherwise falls through to the legacy
+ * location — so a present-but-partial `portal` (e.g. checksum set, cost unset)
+ * still resolves each field from wherever it actually carries a value.
+ */
+declare function getToolCallEvents(r: ApiResponse): LlmapiToolCallEvent[] | undefined;
+declare function getCostMicroUsd(r: ApiResponse): number | undefined;
+declare function getCreditsUsed(r: ApiResponse): number | undefined;
+/**
+ * Image model the portal resolved for the request (set when an image-generation
+ * tool ran). Chat Completions ships it under `portal.image_model` with a legacy
+ * top-level mirror; the Responses API keeps it at the top level.
+ */
+declare function getImageModel(r: ApiResponse): string | undefined;
+
+/**
+ * Drop every cached plaintext title and pending decrypt promise.
+ *
+ * Wired into `clearAllEncryptionState()` via the listener registry in
+ * `useEncryption.ts`. Also exported so consumers can clear the cache
+ * proactively (e.g. on wallet switch within a session before the
+ * full encryption-state teardown lands).
+ */
+declare function clearLazyTitleCache(): void;
+/**
+ * Decrypt a single conversation title on demand.
+ *
+ * Designed for the lazy display path: pair with `listConversationsLazy`
+ * and call this once a row is actually visible.
+ *
+ * Behavior:
+ *   - Plaintext input (no `enc:` prefix) is returned unchanged. This
+ *     covers conversations created before encryption was enabled and
+ *     keeps the helper safe to call unconditionally from rendering
+ *     code that may receive a mix of encrypted and plaintext titles.
+ *   - Encrypted input is decrypted via `decryptField`, which uses the
+ *     same per-version cached `CryptoKey` as the eager path — no new
+ *     key derivations are triggered.
+ *   - Concurrent calls for the same `(address, encryptedTitle)` share
+ *     a single decrypt promise.
+ *   - The result is memoized in a 256-entry LRU.
+ *
+ * Throws if the encryption key for `address` isn't loaded. (The
+ * underlying `decryptField` would otherwise silently return the
+ * ciphertext, which would surface to the UI as a literal `enc:v3:...`
+ * title — strictly worse than a thrown error the caller can catch.)
+ *
+ * @param encryptedTitle - The stored title. May be ciphertext or plaintext.
+ * @param address - Wallet address that owns the encryption key.
+ * @returns The decrypted plaintext title.
+ */
+declare function decryptConversationTitle(encryptedTitle: string, address: string): Promise<string>;
+
+/**
+ * Why a file was not (fully) read. Paired with {@link FileProcessingStatus}.
+ *
+ * - `too_large`: over `maxFileSizeBytes`
+ * - `unsupported_type`: no processor handles the file's type
+ * - `no_data`: the file has no URL/data to read
+ * - `empty`: the file was read but contained no extractable content
+ * - `timeout`: processing exceeded `timeoutMs`
+ * - `error`: the processor threw (corrupt, password-protected, …)
+ */
+type FileProcessingReason = "too_large" | "unsupported_type" | "no_data" | "empty" | "timeout" | "error";
+/**
+ * What happened to one attached file during preprocessing — so the app can tell the user
+ * precisely which attachment the model could not read, and why.
  *
- * Fetches and caches tools from /api/v1/tools endpoint
- * with configurable expiration and localStorage persistence.
+ * - `extracted`: its full text reached the model
+ * - `truncated`: part of it reached the model (a size/row/image budget cut the rest)
+ * - `rendered_as_images`: some or all pages were sent as images (scanned PDF)
+ * - `skipped`: not processed (see `reason`)
+ * - `failed`: processing was attempted and failed (see `reason`)
  */
+interface FileProcessingStatus {
+    fileId: string;
+    fileName: string;
+    status: "extracted" | "truncated" | "rendered_as_images" | "skipped" | "failed";
+    reason?: FileProcessingReason;
+}
 
 /**
  * Server tool definition with parameters field.
@@ -7951,723 +8298,153 @@ declare function createServerToolsFilter(options?: CreateServerToolsFilterOption
  */
 declare const DEFAULT_EXCLUDED_SERVER_TOOLS: readonly string[];
 /** Default match options for the server-tools filter (limit 5, minSim 0.5). */
-declare const DEFAULT_SERVER_TOOLS_MATCH_OPTIONS: ToolMatchOptions;
-/**
- * Pre-configured server-tools filter ready to drop into `useChatStorage`'s
- * `serverTools` option. Semantic matching against the user prompt with the
- * default exclusion list applied, plus call-chain expansion via
- * {@link SERVER_TOOL_DEPENDENCY_SETS} so continuation tools (read-after-search,
- * geocode-before-weather) ride in with their entry tool.
- *
- * @example
- * ```ts
- * import { defaultServerToolsFilter, useChatStorage } from "@anuma/sdk/react";
- *
- * useChatStorage({
- *   ...,
- *   serverTools: defaultServerToolsFilter,
- * });
- * ```
- *
- * If you need to customize (extra excludes, different limits, opt into
- * tool-set expansion), call `createServerToolsFilter` directly.
- */
-declare const defaultServerToolsFilter: ServerToolsFilterFunction;
-/**
- * Type for a server-tools filter — a function that takes prompt embeddings
- * and the full server tool catalog and returns the names of tools to keep.
- * Matches `useChatStorage`'s `serverTools` callback signature.
- */
-type ServerToolsFilterFunction = ((embeddings: number[] | number[][], tools: ServerTool[]) => string[]) & {
-    /**
-     * The unconditional exclusions this filter applies, exposed by
-     * {@link createServerToolsFilter} so defer-loading can honour them without the caller
-     * repeating the list — see {@link resolveDeferredServerTools}. Absent on a hand-written
-     * filter, or on one wrapped in a plain closure.
-     */
-    readonly excludeTools?: readonly string[];
-};
-/**
- * Options for selectServerSideTools
- */
-interface SelectServerSideToolsOptions {
-    /** The user prompt to match tools against */
-    prompt: string;
-    /** Function to get auth token (uses Authorization: Bearer header) */
-    getToken?: () => Promise<string | null>;
-    /** Direct API key for server-side usage (uses X-API-Key header) */
-    apiKey?: string;
-    /** Base URL for the API */
-    baseUrl?: string;
-    /** Cache expiration in ms (default: 24h) */
-    cacheExpirationMs?: number;
-    /** Force refresh tools cache */
-    forceRefresh?: boolean;
-    /** Embedding model to use */
-    embeddingModel?: string;
-    /** Max tools to return (default: 10) */
-    limit?: number;
-    /** Minimum cosine similarity 0-1 (default: 0.3) */
-    minSimilarity?: number;
-    /** API format for returned tools (default: "responses") */
-    apiType?: "responses" | "completions";
-}
-/**
- * Select server tools that are semantically relevant to a prompt.
- *
- * Fetches available tools (with caching), generates embeddings for the prompt,
- * runs cosine-similarity matching, and returns tool schemas in the requested
- * API format (Responses or Completions).
- *
- * @example
- * ```ts
- * import { selectServerSideTools } from "@anuma/sdk/tools";
- *
- * const tools = await selectServerSideTools({
- *   prompt: "Draw me a cat",
- *   getToken: async () => identityToken,
- * });
- *
- * const response = await postApiV1Responses({
- *   body: {
- *     messages: [{ role: "user", content: [{ type: "text", text: "Draw me a cat" }] }],
- *     model: "fireworks/accounts/fireworks/models/kimi-k2p5",
- *     tools,
- *   },
- *   headers: { Authorization: `Bearer ${identityToken}` },
- * });
- * ```
- */
-declare function selectServerSideTools(options: SelectServerSideToolsOptions): Promise<Array<Record<string, unknown>>>;
-
-/**
- * Connector tool catalog + denied-tools system-prompt rider.
- *
- * Granular connector access works by ALLOW/DENY-ing individual SDK tools.
- * Denying a tool means it's never handed to the model that turn, so it
- * physically can't be called — bypass-proof at the model layer.
- *
- * Consumer contract (this PR ships the foundation only — it does NOT wire
- * anything into runtime filtering or the client; those are later phases):
- *
- *   1. Hide the denied tools from the model — pass the denied tool names as
- *      `createServerToolsFilter({ excludeTools })` so they're dropped from the
- *      toolset before it reaches the LLM.
- *   2. Tell the user how to re-enable — append `buildDeniedToolsRider(denied)`
- *      to the system prompt. Because the tool is absent, the model can't name
- *      it on its own and would give a generic "I don't have access". The rider
- *      gives it the specific capability names (grouped by connector) so it can
- *      tell the user to re-enable that exact tool in Connected Apps settings.
- *
- * `TOOL_CATALOG` is the single source of truth for connector tool → friendly
- * label + provider. `provider` is the canonical logical-provider identifier the
- * portal and SDK already key on (matches `internal/oauth/providers.go` and the
- * `createConnectorTokenGetter` call sites) — Phase 2/3 use it to group and
- * persist per-tool denial. `connector` is the human-facing UI display string.
- * Consumers (portal, client) read this on a version bump rather than re-encoding
- * tool names. Labels are placeholders that will be refined later — keep them
- * sensible.
- */
-
-interface ToolCatalogEntry {
-    label: string;
-    /** Canonical logical-provider id (e.g. "gmail", "gcalendar", "gdrive"). */
-    provider: string;
-    /** Human-facing connector display name (UI label). */
-    connector: string;
-}
-declare const TOOL_CATALOG: Record<string, ToolCatalogEntry>;
-/**
- * Build a system-prompt fragment telling the model which connector capabilities
- * the user has turned off, so it can give the specific "re-enable this tool"
- * message instead of a generic refusal.
- *
- * Unknown names (not in {@link TOOL_CATALOG}) are skipped. Returns `""` when the
- * input is empty or every name is unknown — callers append the result
- * conditionally, so an empty string is a no-op.
- */
-declare function buildDeniedToolsRider(deniedToolNames: Iterable<string>): string;
-interface ConnectorGuidanceInput {
-    /** The candidate tools for this turn (the final assembled set). */
-    tools: ToolConfig[];
-    /**
-     * Logical provider codes connected for the user — the same codes used as
-     * {@link TOOL_CATALOG} `provider` values (e.g. "gmail", "gcalendar",
-     * "gdrive", "notion", "github", "dropbox").
-     */
-    connectedProviders: string[];
-    /** Exact SDK tool-name strings the user turned off ({@link TOOL_CATALOG} keys). */
-    deniedToolNames: string[];
-}
-interface ConnectorGuidance {
-    /** `input.tools` with any denied tool removed (the helper owns filtering). */
-    tools: ToolConfig[];
-    /** Compact system-prompt block, or "" when there's nothing actionable. */
-    rider: string;
-}
-/**
- * Single helper both web and mobile use so neither re-implements connector
- * tool filtering or the accuracy messaging. It enforces denial (drops denied
- * tools from the turn's toolset) AND builds a compact rider letting the model
- * give an accurate message for each connector state instead of a generic
- * "I don't have access":
- *
- * 1. Toggled off — connected provider whose tool is denied → "turned off,
- *    re-enable in Connected Apps".
- * 2a. Pruned / 2b. no tool — covered by a general line telling the model not to
- *    claim no-access for a connected app. It rides along only when another
- *    section is present (on its own it isn't actionable).
- * 3. Not connected — catalog provider absent from `connectedProviders` →
- *    "connect it in Connected Apps".
- *
- * State 3 is derived from {@link TOOL_CATALOG}'s provider set — providers with
- * no tools (e.g. Disconnect-only Dropbox) aren't actionable via tools, so they
- * aren't surfaced here. Everything is sorted alphabetically for deterministic
- * output (no cache / snapshot churn). `rider` is "" when nothing is actionable
- * (every catalog provider connected and nothing denied).
- */
-declare function buildConnectorGuidance(input: ConnectorGuidanceInput): ConnectorGuidance;
-
-/**
- * Idle-keepalive wrapper for SSE streams produced by the generated
- * SSE client in `src/client/core/serverSentEvents.gen.ts`.
- *
- * The generated SSE client does not enforce an idle timeout, so if the
- * upstream server dies without sending `FIN`, a consumer can sit forever
- * on a half-open socket. This wrapper:
- *
- *   - Tracks the timestamp of the last event yielded by the source.
- *   - Starts an idle timer (default 60s, configurable via `idleMs`).
- *   - Resets the timer on every event.
- *   - Invokes `onIdle()` if the timer fires, and then closes the stream
- *     by throwing a typed {@link SseIdleTimeoutError} out of the iterator.
- *
- * This file lives outside `src/client/` on purpose: `@hey-api/openapi-ts`
- * wipes its output directory on every regeneration, so anything inside
- * `src/client/` would be clobbered by `pnpm run generate`.
- */
-/**
- * Options accepted by {@link withSseKeepalive}.
- */
-interface SseKeepaliveOptions {
-    /**
-     * Idle window, in milliseconds. If no event is yielded by the source for
-     * this long, the stream is considered dead and is torn down.
-     *
-     * Set to `0` or a negative number to disable the idle timer (in which
-     * case the wrapper is a straight passthrough).
-     *
-     * @default 60000
-     */
-    idleMs?: number;
-    /**
-     * Invoked when the idle timer fires. The callback runs before the
-     * wrapper closes the stream, so consumers can log, emit metrics, or
-     * attempt reconnects from here.
-     *
-     * The callback is best-effort — thrown errors are swallowed so they do
-     * not mask the {@link SseIdleTimeoutError} that follows.
-     */
-    onIdle?: (info: {
-        idleMs: number;
-        lastEventAt: number;
-    }) => void;
-}
-/**
- * Thrown by {@link withSseKeepalive} when no event arrives within the
- * configured idle window. Callers can `instanceof`-check this to
- * distinguish idle timeouts from other stream errors.
- */
-declare class SseIdleTimeoutError extends Error {
-    readonly idleMs: number;
-    readonly lastEventAt: number;
-    constructor(idleMs: number, lastEventAt: number);
-}
-/**
- * Wrap an SSE-style async iterable with an idle timeout. If no value is
- * yielded by `source` within `idleMs`, `onIdle` fires and the wrapper
- * throws {@link SseIdleTimeoutError}, which propagates to the consumer's
- * `for await` loop and, via the iterator protocol, calls `source.return()`
- * so the underlying fetch/reader is cancelled.
- *
- * Typical usage with the generated SSE client:
- *
- * ```ts
- * import { createSseClient } from "@anuma/sdk/client/core/serverSentEvents.gen";
- * import { withSseKeepalive } from "@anuma/sdk";
- *
- * const { stream } = createSseClient({ url });
- * for await (const event of withSseKeepalive(stream, {
- *   idleMs: 60_000,
- *   onIdle: ({ idleMs }) => logger.warn(`SSE idle for ${idleMs}ms`),
- * })) {
- *   // ...
- * }
- * ```
- *
- * The wrapper is a pure passthrough when `idleMs <= 0`.
- */
-declare function withSseKeepalive<T>(source: AsyncIterable<T>, options?: SseKeepaliveOptions): AsyncGenerator<T, void, unknown>;
-
-/**
- * Cross-platform primitive constants.
- *
- * This module is intentionally dependency-free and side-effect-free so it can
- * be loaded by *any* consumer — including React Native / Hermes — without
- * pulling in the rest of the SDK. It is published as the `@anuma/sdk/constants`
- * subpath (which carries a `react-native` export condition); slim consumers
- * such as the agent packages import values from here instead of the bare
- * `@anuma/sdk` entry, whose Node/web bundle is not RN-safe.
- *
- * Only add genuinely pure, cross-platform constants here (numeric/string
- * literals, default IDs, size caps). No classes, no runtime APIs, no imports.
- */
-/** Character cap for multiline / textarea fields. Agent gateways (e.g. cf-tasks)
- *  truncate values to this length before interpolating them into prompt templates.
- *  Shared across all agent packages so a single change updates every journey
- *  declaration simultaneously. */
-declare const MULTILINE_FIELD_MAX = 50000;
-
-/** Runtime environment where the agent can execute. */
-type AgentRuntime = "client" | "server";
-/** Strategy a consumer should use to extract text from an uploaded file before
- *  feeding it into a skill journey field. The SDK only labels the strategy —
- *  the actual extraction (pdf.js, OCR, etc.) is the consumer's responsibility. */
-type FileExtractionStrategy = "pdf-text" | "csv-text" | "image-ocr";
-
-/** Configuration for a single agent skill (task template). */
-interface SkillConfig {
-    /** Unique identifier. Convention: "domain.action" e.g. "housing.lease-review" */
-    id: string;
-    /** Human-readable name. */
-    name: string;
-    /** System prompt template with {{variable}} placeholders. */
-    promptTemplate: string;
-    /**
-     * User-turn template, interpolated with the same {{variable}} placeholders
-     * as `promptTemplate`. Optional, but strongly recommended for skill-driven
-     * (non-freeform) flows so the model receives a proper user turn — most
-     * Anthropic models reject requests that contain only a system message.
-     */
-    userTemplate?: string;
-    /** MCP tool names this skill requires. */
-    requiredTools?: string[];
-    /** Preferred model when the caller doesn't specify one. */
-    preferredModel?: string;
-    /** Max agentic loop steps for this skill. */
-    maxSteps?: number;
-    /** Variables the promptTemplate expects at runtime. */
-    requiredVariables?: string[];
-    /**
-     * SMS-friendly question prompts keyed by variable name. The Anuma text
-     * gateway sends each prompt to the user one at a time and treats the
-     * user's reply as the slot value. Missing entries fall back to a
-     * generic "Please provide {name}." question in the gateway.
-     *
-     * Order of questions follows requiredVariables[] order.
-     */
-    smsPrompts?: Record<string, string>;
-    /** Additional context appended after the prompt template. */
-    contextSuffix?: string;
-    /** Lucide icon identifier (e.g. "FileSearch") for renderers that draw a skill icon. */
-    iconName?: string;
-    /** One-line announcement string shown when the skill is launched (channel-neutral). */
-    launchMessage?: string;
-    /** Conversational preamble shown after the user picks this skill, before the field
-     *  questions begin. Used by chat-native guided flows (web, mobile, SMS, voice). */
-    preamble?: string;
-    /** Closing line shown after the user finishes the last field and before the agent
-     *  starts the tool loop. Used by chat-native guided flows. */
-    closing?: string;
-    /** Fallback nudge for any required field on this skill that doesn't define its own
-     *  `requiredNudge` string. */
-    requiredNudgeDefault?: string;
-}
-/** Public-safe manifest describing an agent (no prompt or tool details). */
-interface AgentManifest {
-    id: string;
-    name: string;
-    description: string;
-    runtimes: AgentRuntime[];
-    skills: Array<{
-        id: string;
-        name: string;
-        requiredVariables?: string[];
-        smsPrompts?: Record<string, string>;
-    }>;
-}
-/** Allowed input types for skill journey form fields. */
-type SkillJourneyFieldType = "text" | "textarea" | "select";
-/** Properties shared by every skill journey field, regardless of input type. */
-interface SkillJourneyFieldBase {
-    key: string;
-    label: string;
-    placeholder: string;
-    helper?: string;
-    required?: boolean;
-    /** Conversational ask used by chat-native guided flows (web, mobile, SMS, voice).
-     *  Falls through to `label` when not set. */
-    chatPrompt?: string;
-    /** Skill-specific nudge shown when the user skips a required field. Falls through
-     *  to `SkillConfig.requiredNudgeDefault` when not set. */
-    requiredNudge?: string;
-    /** Server-side sanitiser cap on the value's character length. Today's gateways
-     *  truncate textarea fields at `MULTILINE_FIELD_MAX` characters. */
-    maxLength?: number;
-}
-/**
- * A single field in a skill journey intake form. Discriminated on `type`:
- * `select` requires `options`; `text` / `textarea` cannot carry options.
- */
-type SkillJourneyField = (SkillJourneyFieldBase & {
-    type: "text" | "textarea";
-}) | (SkillJourneyFieldBase & {
-    type: "select";
-    options: string[];
-});
-/** Full definition for rendering a skill intake form and building the prompt. */
-interface SkillJourneyDefinition {
-    title: string;
-    description: string;
-    steps: string[];
-    /** When true, the journey renders a file upload step before the fields. */
-    acceptsFiles: boolean;
-    /** Label for the file upload step. Only meaningful when `acceptsFiles` is true. */
-    fileLabel?: string;
-    /** Helper text for the file upload step. Only meaningful when `acceptsFiles` is true. */
-    fileHint?: string;
-    /** Per-skill copy for the file upload step prompt. Only meaningful when `acceptsFiles` is true. */
-    filePrompt?: string;
-    /** How consumers should derive text from an attached file. Describes extraction
-     *  only — it is **not** a file-type filter. Files outside the strategy's expected
-     *  MIME type (e.g. photos when the strategy is `pdf-text`) are still uploaded and
-     *  forwarded to the agent as attachments; they are simply not text-extracted.
-     *  The extracted text is written to the variable named by `extractedTextTarget`.
-     *  Only meaningful when `acceptsFiles` is true. */
-    fileExtractionStrategy?: FileExtractionStrategy;
-    /** Variable name to write extracted text into. May coincide with a field's `key`
-     *  (the upload replaces typed input for that field, e.g. `lease_text`) or name a
-     *  separate template variable not tied to any field (e.g. `rent_notice_text`,
-     *  `supporting_document_text`). Only meaningful when `acceptsFiles` is true and
-     *  `fileExtractionStrategy` is set. */
-    extractedTextTarget?: string;
-    fields: SkillJourneyField[];
-    /**
-     * When true, the journey expects substantive input — at least one of an
-     * `acceptsFiles` upload or a text/textarea field — for the agent to act on.
-     * Consumers (form renderers and direct API callers alike) should enforce
-     * "file or text provided" before invoking the skill.
-     */
-    requiresContext: boolean;
-    submitLabel: string;
-    promptTitle: string;
-    /** Extra system prompt context injected per-skill for structured output guidance. */
-    systemContext?: string;
-}
-/** Marketplace filter the agent should appear under in the picker UI. */
-type AgentMarketplaceFamily = "text" | "lifestyle";
-/** What kind of action the marketplace card's primary CTA performs. */
-type AgentPrimaryActionKind = "text" | "group" | "guided";
-/** Visual tone for a transcript section heading. */
-type AgentTranscriptTone = "danger" | "warning" | "success";
-/** A single bullet inside a marketplace analysis transcript section. */
-interface AgentTranscriptItem {
-    title: string;
-    detail: string;
-}
-/** A grouped block of bullets in a marketplace analysis transcript. */
-interface AgentAnalysisSection {
-    title: string;
-    tone: AgentTranscriptTone;
-    items: AgentTranscriptItem[];
-}
-/** A todo entry inside a marketplace agenda transcript. */
-interface AgentAgendaItem {
-    title: string;
-    badge?: string;
-    badgeTone?: "warning" | "danger";
-}
-/** A schedule entry inside a marketplace agenda transcript. */
-interface AgentScheduleItem {
-    title: string;
-    time: string;
-}
-/** Marketplace transcript shape for productivity / agenda style agents. */
-interface AgentAgendaTranscript {
-    kind: "agenda";
-    userMessage: string;
-    intro: string;
-    todos: AgentAgendaItem[];
-    schedule: AgentScheduleItem[];
-    followUp: string;
-    actions: string[];
-}
-/** Marketplace transcript shape for analysis / dispute style agents. */
-interface AgentAnalysisTranscript {
-    kind: "analysis";
-    userMessage: string;
-    intro: string;
-    sections: AgentAnalysisSection[];
-    followUp: string;
-    actions: string[];
-}
-/** A scripted marketplace conversation preview, discriminated on `kind`. */
-type AgentMarketplaceTranscript = AgentAgendaTranscript | AgentAnalysisTranscript;
-/** Marketplace card content for an agent — the data the picker UI renders. */
-interface AgentMarketplaceContent {
-    family: AgentMarketplaceFamily;
-    roleLabel: string;
-    primaryActionLabel: string;
-    primaryActionKind: AgentPrimaryActionKind;
-    cardUseCases: string[];
-    cardKnowledge: string[];
-    quickPrompts: string[];
-    emptyStateDescription: string;
-    transcript: AgentMarketplaceTranscript;
-}
-/** A single (user, agent) example conversation entry, keyed by i18n string ids. */
-interface AgentExampleConversation {
-    userKey: string;
-    agentKey: string;
-}
-/** UI metadata used by clients when the portal doesn't supply richer data. */
-interface AgentUiMetadata {
-    /** Hex color used by the agent card and accents. */
-    color: string;
-    /** Lucide icon identifier (e.g. "users"). */
-    icon: string;
-    /** i18n keys for the per-agent feature bullets. */
-    features: string[];
-    /** i18n keys for the example conversation strings. */
-    exampleConversations: AgentExampleConversation[];
-    /** Memory folder names this agent typically uses. */
-    suggestedMemoryFolders?: string[];
-}
-/** Full agent configuration including prompt, skills, tools, and model settings. */
-interface AgentConfig {
-    id: string;
-    runtimes: AgentRuntime[];
-    prompt: string;
-    skills: SkillConfig[];
-    /** Tool configs are agent-specific, so we keep this generic. */
-    tools: unknown[];
-    model: {
-        default: string;
-        allowed?: string[];
-    };
-    manifest: AgentManifest;
-    /** Form schemas for rendering skill intake forms on the client. */
-    skillJourneys?: Record<string, SkillJourneyDefinition>;
-    /** First assistant message shown when the agent is opened. Supports the
-     *  `{{agent_name}}` placeholder so consumers can substitute the portal-display
-     *  name without changing this string. */
-    greeting?: string;
-    /** Sub-copy shown under the agent picker / guided-flow header. Supports the
-     *  `{{agent_name}}` placeholder, same as `greeting`. */
-    guidedFlowSubcopy?: string;
-    /** Marketplace card content rendered in the agent picker. */
-    marketplace?: AgentMarketplaceContent;
-    /** UI metadata (color, icon, example conversations) for renderer fallbacks. */
-    uiMetadata?: AgentUiMetadata;
-    /** One-time disclaimer shown in a popup the first time a user opens
-     *  a chat with this agent. Plain text; consumers split on `\n\n` for paragraphs.
-     *  May include `{{agent_name}}` placeholder. */
-    firstTimeDisclaimer?: string;
-    /** Persistent one-line disclaimer rendered under the chat input
-     *  whenever this agent's chat is open. May include `{{agent_name}}`
-     *  placeholder. */
-    persistentFooter?: string;
-}
-
-/**
- * Pluggable logger for the Anuma SDK.
- *
- * By default all SDK logging goes to `console`. Call {@link setLogger} at app
- * init (or use `<LoggerProvider>` in React) to redirect output to your own
- * logging infrastructure (PostHog, Datadog, Sentry, etc.).
- *
- * @example
- * ```ts
- * import { setLogger, type Logger } from "@anuma/sdk";
- *
- * const myLogger: Logger = {
- *   debug: () => {},
- *   info: (...args) => posthog.capture("sdk_info", { message: args }),
- *   warn: (...args) => console.warn("[SDK]", ...args),
- *   error: (...args) => Sentry.captureMessage(args.join(" ")),
- * };
- *
- * setLogger(myLogger);
- * ```
- */
-interface Logger {
-    debug: (...args: unknown[]) => void;
-    /** Used for outcomes that are noteworthy but expected — a consolidation
-     * refusal that preserved a memory, for example. Keep genuinely-wrong things at
-     * `warn` so the two stay distinguishable in a log search. */
-    info: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    error: (...args: unknown[]) => void;
-}
-/** Default logger that delegates to the global `console` object. */
-declare const consoleLogger: Logger;
-/** Silent logger that discards all output. */
-declare const noopLogger: Logger;
-/** Replace the active SDK logger. Pass {@link consoleLogger} to restore defaults. */
-declare function setLogger(logger: Logger): void;
-/** Return the active SDK logger. */
-declare function getLogger(): Logger;
-
-/** A single section in the system prompt. */
-interface PromptSection {
-    /** Unique identifier (used for disabling/overriding). */
-    key: string;
-    /** Lower priority = earlier in the prompt. Sections sort ascending. */
-    priority: number;
-    /** Return text to append, or null to skip this section. */
-    render: (ctx: PromptContext) => string | null;
-}
-/** Context passed to every section renderer. */
-interface PromptContext {
-    /** Base personality prompt (from PersonaConfig.prompt). */
-    basePrompt: string;
-    /** User-set "act as X" communication preference. */
-    persona?: string | null;
-    /** Analyzed user communication style profile. */
-    styleProfile?: string | null;
-    /** Detected user sentiment. */
-    sentiment?: "frustrated" | "positive" | "neutral" | null;
-    /** ISO 639-1 language code, 'other', or null for English/undetected. */
-    preferredLanguage?: string | null;
-    /** Platform-specific formatting instructions from PersonaConfig. */
-    platformFormatting?: string | null;
-    /** Available tools. */
-    toolSummaries?: Array<{
-        name: string;
-        description: string;
-    }>;
-    /** Consumer-specific data for custom sections. */
-    extra?: Record<string, unknown>;
-}
-/** Configurable template strings for built-in section renderers. */
-interface PromptTemplates {
-    tools: string;
-    persona: string;
-    style: string;
-    sentiment: {
-        frustrated: string;
-        positive: string;
-    };
-    language: string;
-    languageGeneric: string;
-    platformFormatting: string;
-}
-/** Options for buildSystemPrompt(). */
-interface BuildPromptOptions {
-    /** Additional sections appended to defaults. */
-    extraSections?: PromptSection[];
-    /** Section keys to skip. */
-    disabled?: string[];
-    /** Max total prompt length in characters. 0 = unlimited. */
-    maxLength?: number;
-    /** Override default template strings. */
-    templates?: Partial<PromptTemplates>;
-}
-/** Result of buildSystemPrompt(). */
-interface BuildPromptResult {
-    /** The assembled prompt string. */
-    prompt: string;
-    /** Keys of sections that rendered (in order). */
-    activeSections: string[];
-}
-/** Options for analyzeStyle(). */
-interface AnalyzeStyleOptions {
-    /** Recent conversation messages. */
-    messages: Array<{
-        role: string;
-        content: string;
-    }>;
-    /** Callback to send messages to an LLM and get a text response. */
-    callLlm: (messages: Array<{
-        role: string;
-        content: string;
-    }>) => Promise<string | null>;
-    /** Max user messages to consider (default: 10). */
-    maxInputMessages?: number;
-    /** Minimum user messages required (default: 3). */
-    minMessages?: number;
-    /** Max profile length in characters (default: 200). */
-    maxProfileLength?: number;
-    /** Custom system prompt for the analysis model. */
-    analysisPrompt?: string;
-    /** Regex to filter out document-embedded messages. */
-    documentPattern?: RegExp;
-}
-/** Result of analyzeStyle(). */
-interface AnalyzeStyleResult {
-    /** The style profile string, or null if skipped/failed. */
-    profile: string | null;
-}
-/** Input for shouldAnalyzeStyle(). */
-interface StyleAnalysisSchedule {
-    /** Current message count for the user. */
-    messageCount: number;
-    /** Whether the user already has a style profile. */
-    hasProfile: boolean;
-    /** Whether analysis has ever run (updatedAt timestamp is set). */
-    hasBeenAnalyzed: boolean;
-    /** Whether the user opted out (updatedAt set but profile is null). */
-    optedOut: boolean;
-    /** Trigger analysis after this many messages (default: 5). */
-    analyzeAfterMessages?: number;
-    /** Re-analyze every N messages (default: 20). */
-    refreshEveryMessages?: number;
+declare const DEFAULT_SERVER_TOOLS_MATCH_OPTIONS: ToolMatchOptions;
+/**
+ * Pre-configured server-tools filter ready to drop into `useChatStorage`'s
+ * `serverTools` option. Semantic matching against the user prompt with the
+ * default exclusion list applied, plus call-chain expansion via
+ * {@link SERVER_TOOL_DEPENDENCY_SETS} so continuation tools (read-after-search,
+ * geocode-before-weather) ride in with their entry tool.
+ *
+ * @example
+ * ```ts
+ * import { defaultServerToolsFilter, useChatStorage } from "@anuma/sdk/react";
+ *
+ * useChatStorage({
+ *   ...,
+ *   serverTools: defaultServerToolsFilter,
+ * });
+ * ```
+ *
+ * If you need to customize (extra excludes, different limits, opt into
+ * tool-set expansion), call `createServerToolsFilter` directly.
+ */
+declare const defaultServerToolsFilter: ServerToolsFilterFunction;
+/**
+ * Type for a server-tools filter — a function that takes prompt embeddings
+ * and the full server tool catalog and returns the names of tools to keep.
+ * Matches `useChatStorage`'s `serverTools` callback signature.
+ */
+type ServerToolsFilterFunction = ((embeddings: number[] | number[][], tools: ServerTool[]) => string[]) & {
+    /**
+     * The unconditional exclusions this filter applies, exposed by
+     * {@link createServerToolsFilter} so defer-loading can honour them without the caller
+     * repeating the list — see {@link resolveDeferredServerTools}. Absent on a hand-written
+     * filter, or on one wrapped in a plain closure.
+     */
+    readonly excludeTools?: readonly string[];
+};
+/**
+ * Options for selectServerSideTools
+ */
+interface SelectServerSideToolsOptions {
+    /** The user prompt to match tools against */
+    prompt: string;
+    /** Function to get auth token (uses Authorization: Bearer header) */
+    getToken?: () => Promise<string | null>;
+    /** Direct API key for server-side usage (uses X-API-Key header) */
+    apiKey?: string;
+    /** Base URL for the API */
+    baseUrl?: string;
+    /** Cache expiration in ms (default: 24h) */
+    cacheExpirationMs?: number;
+    /** Force refresh tools cache */
+    forceRefresh?: boolean;
+    /** Embedding model to use */
+    embeddingModel?: string;
+    /** Max tools to return (default: 10) */
+    limit?: number;
+    /** Minimum cosine similarity 0-1 (default: 0.3) */
+    minSimilarity?: number;
+    /** API format for returned tools (default: "responses") */
+    apiType?: "responses" | "completions";
 }
-
-declare const DEFAULT_ANALYSIS_PROMPT = "Analyze these user messages and describe their communication style in 1-2 concise sentences. Focus on: tone (formal/casual/playful), message length preference, vocabulary level, and any notable patterns. Output only the style description, nothing else.";
-declare const DEFAULT_MAX_INPUT_MESSAGES = 10;
-declare const DEFAULT_MIN_MESSAGES = 3;
-declare const DEFAULT_MAX_PROFILE_LENGTH = 200;
-declare const DEFAULT_ANALYZE_AFTER_MESSAGES = 5;
-declare const DEFAULT_REFRESH_EVERY_MESSAGES = 20;
-declare const DEFAULT_DOCUMENT_PATTERN: RegExp;
-declare function shouldAnalyzeStyle(schedule: StyleAnalysisSchedule): boolean;
-declare function analyzeStyle(options: AnalyzeStyleOptions): Promise<AnalyzeStyleResult>;
-
-declare const DEFAULT_PROMPT_TEMPLATES: PromptTemplates;
-/** Collapse runs of 3+ double-quotes to a single quote to prevent prompt injection. */
-declare function sanitizeQuotes(s: string): string;
-/** Replace {content} in a template with sanitized value. Returns null if value is falsy. */
-declare function renderTemplate(value: string | null | undefined, template: string): string | null;
-declare function buildSystemPrompt(ctx: PromptContext, options?: BuildPromptOptions): BuildPromptResult;
-
 /**
- * Why a file was not (fully) read. Paired with {@link FileProcessingStatus}.
+ * Select server tools that are semantically relevant to a prompt.
  *
- * - `too_large`: over `maxFileSizeBytes`
- * - `unsupported_type`: no processor handles the file's type
- * - `no_data`: the file has no URL/data to read
- * - `empty`: the file was read but contained no extractable content
- * - `timeout`: processing exceeded `timeoutMs`
- * - `error`: the processor threw (corrupt, password-protected, …)
+ * Fetches available tools (with caching), generates embeddings for the prompt,
+ * runs cosine-similarity matching, and returns tool schemas in the requested
+ * API format (Responses or Completions).
+ *
+ * @example
+ * ```ts
+ * import { selectServerSideTools } from "@anuma/sdk/tools";
+ *
+ * const tools = await selectServerSideTools({
+ *   prompt: "Draw me a cat",
+ *   getToken: async () => identityToken,
+ * });
+ *
+ * const response = await postApiV1Responses({
+ *   body: {
+ *     messages: [{ role: "user", content: [{ type: "text", text: "Draw me a cat" }] }],
+ *     model: "fireworks/accounts/fireworks/models/kimi-k2p5",
+ *     tools,
+ *   },
+ *   headers: { Authorization: `Bearer ${identityToken}` },
+ * });
+ * ```
  */
-type FileProcessingReason = "too_large" | "unsupported_type" | "no_data" | "empty" | "timeout" | "error";
+declare function selectServerSideTools(options: SelectServerSideToolsOptions): Promise<Array<Record<string, unknown>>>;
+
+interface ToolCatalogEntry {
+    label: string;
+    /** Canonical logical-provider id (e.g. "gmail", "gcalendar", "gdrive"). */
+    provider: string;
+    /** Human-facing connector display name (UI label). */
+    connector: string;
+}
+declare const TOOL_CATALOG: Record<string, ToolCatalogEntry>;
 /**
- * What happened to one attached file during preprocessing — so the app can tell the user
- * precisely which attachment the model could not read, and why.
+ * Build a system-prompt fragment telling the model which connector capabilities
+ * the user has turned off, so it can give the specific "re-enable this tool"
+ * message instead of a generic refusal.
  *
- * - `extracted`: its full text reached the model
- * - `truncated`: part of it reached the model (a size/row/image budget cut the rest)
- * - `rendered_as_images`: some or all pages were sent as images (scanned PDF)
- * - `skipped`: not processed (see `reason`)
- * - `failed`: processing was attempted and failed (see `reason`)
+ * Unknown names (not in {@link TOOL_CATALOG}) are skipped. Returns `""` when the
+ * input is empty or every name is unknown — callers append the result
+ * conditionally, so an empty string is a no-op.
  */
-interface FileProcessingStatus {
-    fileId: string;
-    fileName: string;
-    status: "extracted" | "truncated" | "rendered_as_images" | "skipped" | "failed";
-    reason?: FileProcessingReason;
+declare function buildDeniedToolsRider(deniedToolNames: Iterable<string>): string;
+interface ConnectorGuidanceInput {
+    /** The candidate tools for this turn (the final assembled set). */
+    tools: ToolConfig[];
+    /**
+     * Logical provider codes connected for the user — the same codes used as
+     * {@link TOOL_CATALOG} `provider` values (e.g. "gmail", "gcalendar",
+     * "gdrive", "notion", "github", "dropbox").
+     */
+    connectedProviders: string[];
+    /** Exact SDK tool-name strings the user turned off ({@link TOOL_CATALOG} keys). */
+    deniedToolNames: string[];
+}
+interface ConnectorGuidance {
+    /** `input.tools` with any denied tool removed (the helper owns filtering). */
+    tools: ToolConfig[];
+    /** Compact system-prompt block, or "" when there's nothing actionable. */
+    rider: string;
 }
+/**
+ * Single helper both web and mobile use so neither re-implements connector
+ * tool filtering or the accuracy messaging. It enforces denial (drops denied
+ * tools from the turn's toolset) AND builds a compact rider letting the model
+ * give an accurate message for each connector state instead of a generic
+ * "I don't have access":
+ *
+ * 1. Toggled off — connected provider whose tool is denied → "turned off,
+ *    re-enable in Connected Apps".
+ * 2a. Pruned / 2b. no tool — covered by a general line telling the model not to
+ *    claim no-access for a connected app. It rides along only when another
+ *    section is present (on its own it isn't actionable).
+ * 3. Not connected — catalog provider absent from `connectedProviders` →
+ *    "connect it in Connected Apps".
+ *
+ * State 3 is derived from {@link TOOL_CATALOG}'s provider set — providers with
+ * no tools (e.g. Disconnect-only Dropbox) aren't actionable via tools, so they
+ * aren't surfaced here. Everything is sorted alphabetically for deterministic
+ * output (no cache / snapshot churn). `rider` is "" when nothing is actionable
+ * (every catalog provider connected and nothing denied).
+ */
+declare function buildConnectorGuidance(input: ConnectorGuidanceInput): ConnectorGuidance;
 
 interface StoredConversation {
     uniqueId: string;
@@ -8707,15 +8484,43 @@ interface LazyStoredConversation extends Omit<StoredConversation, "title"> {
 }
 
 /**
- * Memory Retrieval Embeddings
+ * Pluggable logger for the Anuma SDK.
+ *
+ * By default all SDK logging goes to `console`. Call {@link setLogger} at app
+ * init (or use `<LoggerProvider>` in React) to redirect output to your own
+ * logging infrastructure (PostHog, Datadog, Sentry, etc.).
+ *
+ * @example
+ * ```ts
+ * import { setLogger, type Logger } from "@anuma/sdk";
+ *
+ * const myLogger: Logger = {
+ *   debug: () => {},
+ *   info: (...args) => posthog.capture("sdk_info", { message: args }),
+ *   warn: (...args) => console.warn("[SDK]", ...args),
+ *   error: (...args) => Sentry.captureMessage(args.join(" ")),
+ * };
  *
- * Message-level embedding + persistence helpers: find messages via the
- * WatermelonDB-backed `db/chat/operations`, embed their content, and store the
- * vectors/chunks back. The raw "text → embedding" calls live in `./generate`
- * (dependency-free so the tool-selection engine can import them without the DB
- * layer) and are re-exported here so existing importers of
- * `../memoryEngine/embeddings` and the `../memoryEngine` barrel keep working.
+ * setLogger(myLogger);
+ * ```
  */
+interface Logger {
+    debug: (...args: unknown[]) => void;
+    /** Used for outcomes that are noteworthy but expected — a consolidation
+     * refusal that preserved a memory, for example. Keep genuinely-wrong things at
+     * `warn` so the two stay distinguishable in a log search. */
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/** Default logger that delegates to the global `console` object. */
+declare const consoleLogger: Logger;
+/** Silent logger that discards all output. */
+declare const noopLogger: Logger;
+/** Replace the active SDK logger. Pass {@link consoleLogger} to restore defaults. */
+declare function setLogger(logger: Logger): void;
+/** Return the active SDK logger. */
+declare function getLogger(): Logger;
 
 /**
  * An ordinary message whose chunk vectors were built over `enc:v3:` ciphertext
@@ -8824,42 +8629,6 @@ declare function dequantizeEmbedding({ data, scale }: QuantizedEmbedding): Float
  */
 declare function cosineInt8(a: Int8Array, scaleA: number, b: Int8Array, scaleB: number): number;
 
-/**
- * Storage encoding for `MessageChunk.vector`.
- *
- * Chunk vectors are persisted inside the `chunks` column as JSON. Since #732
- * their values are canonically float32 — `generateEmbeddings` round-trips its
- * return value through a `Float32Array` so a cache hit and a cache miss agree —
- * which paradoxically made the JSON LONGER: `JSON.stringify` emits the shortest
- * decimal that round-trips to the float64, and a binary32-exact value needs ~17
- * significant digits. Measured at 4096 dims (`qwen/qwen3-embedding-8b`): 54.5 KB
- * of JSON before #732, 84.5 KB after.
- *
- * Base64-encoding the `Float32Array` stores the same bits as 4 bytes per value
- * instead of ~21 characters — 21.3 KB at 4096 dims. Because the data already IS
- * float32, the encoding is EXACTLY lossless, so the round-trip assertion is
- * equality and never a tolerance.
- *
- * Rollout (sdk#862). `decodeChunkVector` accepts both encodings and ships first;
- * `encodeChunkVector` is deliberately NOT wired into the write path yet. Every
- * stored chunk on every device is still a JSON array, and chat history syncs
- * those rows between devices verbatim — the backup push spreads the whole raw
- * row and the restore copies every column — so a device on an older build would
- * meet a base64 string where it expects `number[]`. It does not throw, and it
- * does not fall back: the row still HAS chunks, so the old build takes the chunk
- * branch and never reaches the whole-message one. `Float32Array.from` over the
- * string yields one NaN per character, `cosineSimilarity` returns 0 on the
- * dimension mismatch, and the default `minSimilarity` cuts it — the row leaves
- * search entirely. The old build then caches what it built: ~87 KB of NaN per
- * chunk, so ~54 MB resident for a 620-chunk row, on exactly the device this
- * sequencing exists to protect. The writer flips in a later release, once a
- * build that reads both encodings has saturated; the single flip site is
- * `updateMessageChunksOp`.
- *
- * Byte order is the platform's, since this reads the `Float32Array` bytes
- * directly. Every runtime the SDK targets (browsers, iOS, Android, Node on
- * x86/ARM) is little-endian.
- */
 /**
  * Encode an embedding as base64 float32 for storage.
  *
@@ -8867,73 +8636,150 @@ declare function cosineInt8(a: Int8Array, scaleA: number, b: Int8Array, scaleB:
  * narrowed to float32 first, which is lossless for anything `generateEmbeddings`
  * produced and is what makes the decode byte-exact.
  */
-declare function encodeChunkVector(vector: ArrayLike<number>): string;
-/**
- * Read a stored chunk vector in either encoding: a base64 float32 string, or the
- * legacy `number[]` that every row written before the writer flip still holds.
- *
- * Returns a zero-length `Float32Array` for a missing, empty, or unreadable
- * value, which callers already treat as "this chunk has no vector" — the same
- * degradation a malformed `chunks` JSON gets today, rather than a throw that
- * would take down a whole search pass over one bad row.
- *
- * That one return value covers two different situations, and a caller cannot
- * tell them apart: a chunk that legitimately has no vector, and a chunk whose
- * vector is corrupt. `onMalformed` separates them. It fires only on the corrupt
- * paths, never on an absent or empty value, so a caller can count corruption
- * without counting normal empties.
- *
- * Nothing is logged here. A corrupt row holds hundreds of chunks and this runs
- * once per chunk, so the caller aggregates and reports once per pass — the shape
- * `searchChunksOp` already uses for stale-model vectors.
- */
-declare function decodeChunkVector(vector: number[] | string | null | undefined, onMalformed?: () => void): Float32Array<ArrayBuffer>;
-
-/**
- * Value of the `origin` column on a row the SDK synthesised for a turn's tool results (v44, #866).
- *
- * `satisfies MessageOrigin` so this constant and the column's union cannot drift apart silently.
- */
-declare const TOOL_RESULT_ORIGIN = "tool_result";
-
-/**
- * True when a text part is the attachment-contents part built by {@link buildAttachedFilesText}.
- *
- * Matches the whole generated shape — opening tag plus the fixed header line, and the closing
- * tag — not just the tag, so user text that merely starts with `<attached_files>` is still
- * treated as the user's prompt.
- */
-declare function isAttachedFilesText(text: string | undefined | null): boolean;
-/**
- * Wrap a turn's extracted file contents (the `[Extracted content from <name>]`
- * blocks `preprocessFiles` emits) in the tagged part that rides on that turn's
- * user message.
- */
-declare function buildAttachedFilesText(fileContext: string): string;
+declare function encodeChunkVector(vector: ArrayLike<number>): string;
 /**
- * Put the current turn's extracted attachment contents on the last user
- * message, as a text part inserted right after that message's LAST text part:
- * after everything the user wrote, and before any parts that follow it
- * (typically images). With interleaved parts such as `[text, image, text,
- * image]` it lands between the second text and the second image.
+ * Read a stored chunk vector in either encoding: a base64 float32 string, or the
+ * legacy `number[]` that every row written before the writer flip still holds.
  *
- * Why not a system message: a detached system message at the front of the
- * request ("the user has attached files to this conversation") is separated
- * from the words that refer to it by the whole system prompt, tool catalog and
- * history. In a long, multi-file conversation fast models stopped connecting
- * the two and told users the attachment was unreadable even though its text
- * was in the request. Keeping the contents on the turn that attached them is
- * how native file attachments work on every provider, and survives the auto
- * router switching models between turns.
+ * Returns a zero-length `Float32Array` for a missing, empty, or unreadable
+ * value, which callers already treat as "this chunk has no vector" — the same
+ * degradation a malformed `chunks` JSON gets today, rather than a throw that
+ * would take down a whole search pass over one bad row.
  *
- * The part goes AFTER the user's own text because the portal's query
- * classifier routes on the first text part of the last user message — it must
- * keep reading the user's prompt, not the document.
+ * That one return value covers two different situations, and a caller cannot
+ * tell them apart: a chunk that legitimately has no vector, and a chunk whose
+ * vector is corrupt. `onMalformed` separates them. It fires only on the corrupt
+ * paths, never on an absent or empty value, so a caller can count corruption
+ * without counting normal empties.
  *
- * Returns a new array; the input is not mutated. When there is no user
- * message the messages are returned unchanged.
+ * Nothing is logged here. A corrupt row holds hundreds of chunks and this runs
+ * once per chunk, so the caller aggregates and reports once per pass — the shape
+ * `searchChunksOp` already uses for stale-model vectors.
  */
-declare function attachFileContextToLastUserMessage(messages: LlmapiMessage[], fileContext: string): LlmapiMessage[];
+declare function decodeChunkVector(vector: number[] | string | null | undefined, onMalformed?: () => void): Float32Array<ArrayBuffer>;
+
+/** A single section in the system prompt. */
+interface PromptSection {
+    /** Unique identifier (used for disabling/overriding). */
+    key: string;
+    /** Lower priority = earlier in the prompt. Sections sort ascending. */
+    priority: number;
+    /** Return text to append, or null to skip this section. */
+    render: (ctx: PromptContext) => string | null;
+}
+/** Context passed to every section renderer. */
+interface PromptContext {
+    /** Base personality prompt (from PersonaConfig.prompt). */
+    basePrompt: string;
+    /** User-set "act as X" communication preference. */
+    persona?: string | null;
+    /** Analyzed user communication style profile. */
+    styleProfile?: string | null;
+    /** Detected user sentiment. */
+    sentiment?: "frustrated" | "positive" | "neutral" | null;
+    /** ISO 639-1 language code, 'other', or null for English/undetected. */
+    preferredLanguage?: string | null;
+    /** Platform-specific formatting instructions from PersonaConfig. */
+    platformFormatting?: string | null;
+    /** Available tools. */
+    toolSummaries?: Array<{
+        name: string;
+        description: string;
+    }>;
+    /** Consumer-specific data for custom sections. */
+    extra?: Record<string, unknown>;
+}
+/** Configurable template strings for built-in section renderers. */
+interface PromptTemplates {
+    tools: string;
+    persona: string;
+    style: string;
+    sentiment: {
+        frustrated: string;
+        positive: string;
+    };
+    language: string;
+    languageGeneric: string;
+    platformFormatting: string;
+}
+/** Options for buildSystemPrompt(). */
+interface BuildPromptOptions {
+    /** Additional sections appended to defaults. */
+    extraSections?: PromptSection[];
+    /** Section keys to skip. */
+    disabled?: string[];
+    /** Max total prompt length in characters. 0 = unlimited. */
+    maxLength?: number;
+    /** Override default template strings. */
+    templates?: Partial<PromptTemplates>;
+}
+/** Result of buildSystemPrompt(). */
+interface BuildPromptResult {
+    /** The assembled prompt string. */
+    prompt: string;
+    /** Keys of sections that rendered (in order). */
+    activeSections: string[];
+}
+/** Options for analyzeStyle(). */
+interface AnalyzeStyleOptions {
+    /** Recent conversation messages. */
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** Callback to send messages to an LLM and get a text response. */
+    callLlm: (messages: Array<{
+        role: string;
+        content: string;
+    }>) => Promise<string | null>;
+    /** Max user messages to consider (default: 10). */
+    maxInputMessages?: number;
+    /** Minimum user messages required (default: 3). */
+    minMessages?: number;
+    /** Max profile length in characters (default: 200). */
+    maxProfileLength?: number;
+    /** Custom system prompt for the analysis model. */
+    analysisPrompt?: string;
+    /** Regex to filter out document-embedded messages. */
+    documentPattern?: RegExp;
+}
+/** Result of analyzeStyle(). */
+interface AnalyzeStyleResult {
+    /** The style profile string, or null if skipped/failed. */
+    profile: string | null;
+}
+/** Input for shouldAnalyzeStyle(). */
+interface StyleAnalysisSchedule {
+    /** Current message count for the user. */
+    messageCount: number;
+    /** Whether the user already has a style profile. */
+    hasProfile: boolean;
+    /** Whether analysis has ever run (updatedAt timestamp is set). */
+    hasBeenAnalyzed: boolean;
+    /** Whether the user opted out (updatedAt set but profile is null). */
+    optedOut: boolean;
+    /** Trigger analysis after this many messages (default: 5). */
+    analyzeAfterMessages?: number;
+    /** Re-analyze every N messages (default: 20). */
+    refreshEveryMessages?: number;
+}
+
+declare const DEFAULT_ANALYSIS_PROMPT = "Analyze these user messages and describe their communication style in 1-2 concise sentences. Focus on: tone (formal/casual/playful), message length preference, vocabulary level, and any notable patterns. Output only the style description, nothing else.";
+declare const DEFAULT_MAX_INPUT_MESSAGES = 10;
+declare const DEFAULT_MIN_MESSAGES = 3;
+declare const DEFAULT_MAX_PROFILE_LENGTH = 200;
+declare const DEFAULT_ANALYZE_AFTER_MESSAGES = 5;
+declare const DEFAULT_REFRESH_EVERY_MESSAGES = 20;
+declare const DEFAULT_DOCUMENT_PATTERN: RegExp;
+declare function shouldAnalyzeStyle(schedule: StyleAnalysisSchedule): boolean;
+declare function analyzeStyle(options: AnalyzeStyleOptions): Promise<AnalyzeStyleResult>;
+
+declare const DEFAULT_PROMPT_TEMPLATES: PromptTemplates;
+/** Collapse runs of 3+ double-quotes to a single quote to prevent prompt injection. */
+declare function sanitizeQuotes(s: string): string;
+/** Replace {content} in a template with sanitized value. Returns null if value is falsy. */
+declare function renderTemplate(value: string | null | undefined, template: string): string | null;
+declare function buildSystemPrompt(ctx: PromptContext, options?: BuildPromptOptions): BuildPromptResult;
 
 /**
  * One line per file the model did NOT get, saying why — e.g.
@@ -8948,71 +8794,85 @@ declare function formatFileProcessingNotes(statuses: FileProcessingStatus[], opt
 }): string | null;
 
 /**
- * Lazy decryption helpers for conversation titles.
- *
- * Today the SDK eagerly decrypts every conversation title returned from
- * `getConversationsOp` so callers can render them immediately. For users
- * with hundreds or thousands of conversations this means hundreds of
- * plaintext title strings sitting in client RAM at all times — a
- * non-trivial memory cost on long-lived tabs, and an unnecessary one
- * since only the visible rows actually need plaintext.
+ * Idle-keepalive wrapper for SSE streams produced by the generated
+ * SSE client in `src/client/core/serverSentEvents.gen.ts`.
  *
- * `decryptConversationTitle` is the opt-in alternative. Callers pair it
- * with the lazy `listConversationsLazy` operation (see operations.ts) to
- * keep encrypted titles in their store and decrypt only on row visibility
- * (e.g. inside an IntersectionObserver callback or a virtualized list's
- * `renderItem`).
+ * The generated SSE client does not enforce an idle timeout, so if the
+ * upstream server dies without sending `FIN`, a consumer can sit forever
+ * on a half-open socket. This wrapper:
  *
- * The helper is a thin wrapper over `decryptField` plus:
- *   - a small bounded LRU so a row that briefly leaves and re-enters the
- *     viewport doesn't trigger a fresh decrypt;
- *   - in-flight dedupe so concurrent calls for the same encrypted title
- *     run a single decrypt rather than racing the same WebCrypto call;
- *   - a hard error when the encryption key isn't loaded — `decryptField`
- *     itself silently returns the ciphertext on key-missing, which is
- *     useful for backwards-compatible reads but actively misleading for
- *     a lazy display path (the UI would render `enc:v3:...` as the title).
+ *   - Tracks the timestamp of the last event yielded by the source.
+ *   - Starts an idle timer (default 60s, configurable via `idleMs`).
+ *   - Resets the timer on every event.
+ *   - Invokes `onIdle()` if the timer fires, and then closes the stream
+ *     by throwing a typed {@link SseIdleTimeoutError} out of the iterator.
  *
- * The LRU is cleared on every `clearAllEncryptionState()` so a shared
- * browser can't leak the previous user's titles after logout.
+ * This file lives outside `src/client/` on purpose: `@hey-api/openapi-ts`
+ * wipes its output directory on every regeneration, so anything inside
+ * `src/client/` would be clobbered by `pnpm run generate`.
  */
 /**
- * Drop every cached plaintext title and pending decrypt promise.
- *
- * Wired into `clearAllEncryptionState()` via the listener registry in
- * `useEncryption.ts`. Also exported so consumers can clear the cache
- * proactively (e.g. on wallet switch within a session before the
- * full encryption-state teardown lands).
+ * Options accepted by {@link withSseKeepalive}.
  */
-declare function clearLazyTitleCache(): void;
+interface SseKeepaliveOptions {
+    /**
+     * Idle window, in milliseconds. If no event is yielded by the source for
+     * this long, the stream is considered dead and is torn down.
+     *
+     * Set to `0` or a negative number to disable the idle timer (in which
+     * case the wrapper is a straight passthrough).
+     *
+     * @default 60000
+     */
+    idleMs?: number;
+    /**
+     * Invoked when the idle timer fires. The callback runs before the
+     * wrapper closes the stream, so consumers can log, emit metrics, or
+     * attempt reconnects from here.
+     *
+     * The callback is best-effort — thrown errors are swallowed so they do
+     * not mask the {@link SseIdleTimeoutError} that follows.
+     */
+    onIdle?: (info: {
+        idleMs: number;
+        lastEventAt: number;
+    }) => void;
+}
 /**
- * Decrypt a single conversation title on demand.
+ * Thrown by {@link withSseKeepalive} when no event arrives within the
+ * configured idle window. Callers can `instanceof`-check this to
+ * distinguish idle timeouts from other stream errors.
+ */
+declare class SseIdleTimeoutError extends Error {
+    readonly idleMs: number;
+    readonly lastEventAt: number;
+    constructor(idleMs: number, lastEventAt: number);
+}
+/**
+ * Wrap an SSE-style async iterable with an idle timeout. If no value is
+ * yielded by `source` within `idleMs`, `onIdle` fires and the wrapper
+ * throws {@link SseIdleTimeoutError}, which propagates to the consumer's
+ * `for await` loop and, via the iterator protocol, calls `source.return()`
+ * so the underlying fetch/reader is cancelled.
  *
- * Designed for the lazy display path: pair with `listConversationsLazy`
- * and call this once a row is actually visible.
+ * Typical usage with the generated SSE client:
  *
- * Behavior:
- *   - Plaintext input (no `enc:` prefix) is returned unchanged. This
- *     covers conversations created before encryption was enabled and
- *     keeps the helper safe to call unconditionally from rendering
- *     code that may receive a mix of encrypted and plaintext titles.
- *   - Encrypted input is decrypted via `decryptField`, which uses the
- *     same per-version cached `CryptoKey` as the eager path — no new
- *     key derivations are triggered.
- *   - Concurrent calls for the same `(address, encryptedTitle)` share
- *     a single decrypt promise.
- *   - The result is memoized in a 256-entry LRU.
+ * ```ts
+ * import { createSseClient } from "@anuma/sdk/client/core/serverSentEvents.gen";
+ * import { withSseKeepalive } from "@anuma/sdk";
  *
- * Throws if the encryption key for `address` isn't loaded. (The
- * underlying `decryptField` would otherwise silently return the
- * ciphertext, which would surface to the UI as a literal `enc:v3:...`
- * title — strictly worse than a thrown error the caller can catch.)
+ * const { stream } = createSseClient({ url });
+ * for await (const event of withSseKeepalive(stream, {
+ *   idleMs: 60_000,
+ *   onIdle: ({ idleMs }) => logger.warn(`SSE idle for ${idleMs}ms`),
+ * })) {
+ *   // ...
+ * }
+ * ```
  *
- * @param encryptedTitle - The stored title. May be ciphertext or plaintext.
- * @param address - Wallet address that owns the encryption key.
- * @returns The decrypted plaintext title.
+ * The wrapper is a pure passthrough when `idleMs <= 0`.
  */
-declare function decryptConversationTitle(encryptedTitle: string, address: string): Promise<string>;
+declare function withSseKeepalive<T>(source: AsyncIterable<T>, options?: SseKeepaliveOptions): AsyncGenerator<T, void, unknown>;
 
 /**
  * Class-B task types — the vocabulary of the `X-Anuma-Task-Type` header.