@frankieai/core 0.2.2 → 0.2.4

package/dist/index.d.cts

@@ -19,6 +19,10 @@ declare const widgetThemeSchema: z.ZodPrefault<z.ZodObject<{
         dark: "dark";
         system: "system";
     }>>;
+    source: z.ZodDefault<z.ZodEnum<{
+        custom: "custom";
+        inherit: "inherit";
+    }>>;
 }, z.core.$strip>>;
 declare const thinkingLevelSchema: z.ZodEnum<{
     minimal: "minimal";
@@ -51,6 +55,24 @@ declare const modelChoiceSchema: z.ZodObject<{
     label: z.ZodString;
     provider: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * The Fireworks-hosted models Frankie offers in the dashboard's model-picker
+ * dropdown, so an admin can choose one instead of typing a raw model id. Any
+ * other provider model can still be entered by hand. Kept here so the dashboard
+ * and docs share one source.
+ *
+ * Deliberately limited to models that speak Fireworks' OpenAI-completions API:
+ * on Fireworks the Anthropic-Messages models inline their reasoning into the
+ * visible answer, which leaks the chain-of-thought into the chat, whereas the
+ * completions API keeps reasoning on a separate channel. All are large-context
+ * and tool-capable. (The leaky Anthropic-Messages models — e.g. Kimi K2.6 /
+ * K2.7 Code — are still reachable via the "Other" free-text option.)
+ */
+declare const FIREWORKS_MODELS: readonly {
+    id: string;
+    label: string;
+    note: string;
+}[];
 /**
  * Optional, opt-in chat capabilities the SDK consumer turns on per workspace.
  * Everything here is OFF by default: an embedded agent only gets a wider surface
@@ -76,6 +98,7 @@ declare const featuresConfigSchema: z.ZodPrefault<z.ZodObject<{
 }, z.core.$strip>>;
 declare const mcpServerSchema: z.ZodObject<{
     name: z.ZodString;
+    displayName: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     enabled: z.ZodDefault<z.ZodBoolean>;
     selectedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     discoveredTools: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -112,6 +135,7 @@ declare const apiCapabilitySchema: z.ZodObject<{
 }, z.core.$strip>;
 declare const apiSourceSchema: z.ZodObject<{
     name: z.ZodString;
+    displayName: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     spec: z.ZodString;
     baseUrl: z.ZodOptional<z.ZodString>;
     operations: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -124,6 +148,10 @@ declare const apiSourceSchema: z.ZodObject<{
         DELETE: "DELETE";
     }>>>;
     enabled: z.ZodDefault<z.ZodBoolean>;
+    execution: z.ZodDefault<z.ZodEnum<{
+        server: "server";
+        client: "client";
+    }>>;
     selectedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     exposeAsMcp: z.ZodDefault<z.ZodBoolean>;
     capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -151,10 +179,25 @@ declare const toolPolicySchema: z.ZodObject<{
     deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
     denyByDefault: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
+/**
+ * A starter card shown on the empty chat screen: a title and short description
+ * the reader sees, and the message that is sent as if they typed it when they
+ * click the card. Configured per workspace in the dashboard's Appearance tab.
+ */
+declare const starterPromptSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    message: z.ZodString;
+}, z.core.$strip>;
 declare const agentConfigSchema: z.ZodObject<{
     systemPrompt: z.ZodDefault<z.ZodString>;
     greeting: z.ZodDefault<z.ZodString>;
     suggestedPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    starterPrompts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        message: z.ZodString;
+    }, z.core.$strip>>>;
     maxTurns: z.ZodDefault<z.ZodNumber>;
     maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
     tools: z.ZodPrefault<z.ZodObject<{
@@ -167,6 +210,10 @@ declare const agentConfigSchema: z.ZodObject<{
 declare const authConfigSchema: z.ZodObject<{
     publishableKey: z.ZodString;
     allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    userCredential: z.ZodDefault<z.ZodEnum<{
+        jwt: "jwt";
+        opaque: "opaque";
+    }>>;
     allowAnonymous: z.ZodDefault<z.ZodBoolean>;
     jwtSecretEnv: z.ZodDefault<z.ZodString>;
     jwksUrl: z.ZodOptional<z.ZodString>;
@@ -209,6 +256,10 @@ declare const frankieConfigSchema: z.ZodObject<{
             dark: "dark";
             system: "system";
         }>>;
+        source: z.ZodDefault<z.ZodEnum<{
+            custom: "custom";
+            inherit: "inherit";
+        }>>;
     }, z.core.$strip>>;
     model: z.ZodPrefault<z.ZodObject<{
         provider: z.ZodDefault<z.ZodString>;
@@ -231,6 +282,11 @@ declare const frankieConfigSchema: z.ZodObject<{
         systemPrompt: z.ZodDefault<z.ZodString>;
         greeting: z.ZodDefault<z.ZodString>;
         suggestedPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        starterPrompts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            message: z.ZodString;
+        }, z.core.$strip>>>;
         maxTurns: z.ZodDefault<z.ZodNumber>;
         maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
         tools: z.ZodPrefault<z.ZodObject<{
@@ -243,6 +299,10 @@ declare const frankieConfigSchema: z.ZodObject<{
     auth: z.ZodObject<{
         publishableKey: z.ZodString;
         allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        userCredential: z.ZodDefault<z.ZodEnum<{
+            jwt: "jwt";
+            opaque: "opaque";
+        }>>;
         allowAnonymous: z.ZodDefault<z.ZodBoolean>;
         jwtSecretEnv: z.ZodDefault<z.ZodString>;
         jwksUrl: z.ZodOptional<z.ZodString>;
@@ -253,6 +313,7 @@ declare const frankieConfigSchema: z.ZodObject<{
     }, z.core.$strip>;
     mcpServers: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
+        displayName: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         selectedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         discoveredTools: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -270,6 +331,7 @@ declare const frankieConfigSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     apis: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
+        displayName: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
         spec: z.ZodString;
         baseUrl: z.ZodOptional<z.ZodString>;
         operations: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -282,6 +344,10 @@ declare const frankieConfigSchema: z.ZodObject<{
             DELETE: "DELETE";
         }>>>;
         enabled: z.ZodDefault<z.ZodBoolean>;
+        execution: z.ZodDefault<z.ZodEnum<{
+            server: "server";
+            client: "client";
+        }>>;
         selectedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         exposeAsMcp: z.ZodDefault<z.ZodBoolean>;
         capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -371,6 +437,14 @@ type StopReason = "end_turn" | "max_tokens" | "max_turns" | "stop_sequence" | "a
 interface UsageSummary {
     inputTokens: number;
     outputTokens: number;
+    /**
+     * Prompt-cache hits and writes, when the provider reports them. A cached
+     * input token costs a fraction of a fresh one, so this is what says whether
+     * the stable prefix — system prompt, tools, earlier turns — is actually being
+     * served from cache or re-read every turn.
+     */
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
     /** Present only when the upstream provider reports a price. */
     costUsd?: number;
 }
@@ -410,6 +484,21 @@ type FrankieServerEvent = {
     toolUseId: string;
     name: string;
     reason: string;
+}
+/**
+ * Client-side tool execution: the server asks the widget to make one HTTP
+ * call to the host's own API, from the user's browser and on the user's
+ * existing session, and to POST the outcome back to `/v1/chat/tool-result`
+ * with this `callId`. Emitted only for API sources marked
+ * `execution: "client"`. The turn's agent loop is paused on this call until
+ * the result arrives (or the turn times out). See `HostToolRequest`.
+ */
+ | {
+    type: "tool_call_request";
+    callId: string;
+    toolUseId: string;
+    name: string;
+    request: HostToolRequest;
 } | {
     type: "turn_end";
     stopReason: StopReason;
@@ -422,6 +511,38 @@ type FrankieServerEvent = {
 } | {
     type: "ping";
 };
+/**
+ * One HTTP call Frankie asks the browser to make against the host's own API,
+ * on the signed-in user's existing session. `path` is always relative (path +
+ * query, no scheme or host): the widget resolves it against the `api.baseUrl`
+ * the host configured, and attaches the user's own credentials (cookies or a
+ * bearer token). Frankie sends no credential of its own — the host API is the
+ * authorization boundary, exactly as for any request from the host's frontend.
+ */
+interface HostToolRequest {
+    /** The API source the operation belongs to (`api__<source>__...`). Diagnostic only. */
+    source: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Path + query string relative to `api.baseUrl`, params already interpolated. */
+    path: string;
+    /** JSON request body, when the operation declares one. */
+    body?: unknown;
+}
+/** The browser's outcome for a `tool_call_request`, POSTed back to the server. */
+interface HostToolResult {
+    /** HTTP status the host API returned, or 0 when the fetch itself failed. */
+    status: number;
+    /** Response body text as returned by the host API. */
+    body?: string;
+    /** A transport-level error (network failure, no host API configured). */
+    error?: string;
+}
+/** Client -> server body for `POST /v1/chat/tool-result`. */
+interface ToolResultBody {
+    /** The `callId` from the `tool_call_request` this answers. */
+    callId: string;
+    result: HostToolResult;
+}
 type FrankieErrorCode = "unauthorized" | "forbidden_origin" | "rate_limited" | "session_not_found" | "upstream_error" | "budget_exceeded" | "internal";
 /** Display metadata only; instructions never enter the public SDK config. */
 interface LoadedSkill {
@@ -488,6 +609,12 @@ interface CreateSessionResponse {
         anonymous: boolean;
     };
 }
+/** A starter card on the empty chat screen: what the reader sees, and the message clicking it sends. */
+interface StarterPrompt {
+    title: string;
+    description?: string;
+    message: string;
+}
 /** The subset of tenant config the widget is allowed to see. */
 interface PublicWidgetConfig {
     tenantId: string;
@@ -499,6 +626,8 @@ interface PublicWidgetConfig {
     };
     greeting: string;
     suggestedPrompts: string[];
+    /** Explicit starter cards (title + description + message). Take precedence over `suggestedPrompts` on the empty screen. Optional so older servers stay compatible. */
+    starterPrompts?: StarterPrompt[];
     theme: WidgetTheme;
     /** Whether the widget may open a session without a host-signed user token. */
     allowAnonymous: boolean;
@@ -537,6 +666,12 @@ interface WidgetTheme {
     radius?: string;
     fontFamily?: string;
     mode?: "light" | "dark" | "system";
+    /**
+     * "inherit" tells the widget to sample the host page's own colors instead
+     * of using the ones configured here, which then serve only as a fallback.
+     * Defaults to "custom" (use the configured colors) when unset.
+     */
+    source?: "custom" | "inherit";
 }
 
 interface ToolDecision {
@@ -575,6 +710,7 @@ interface InstallPlan {
     specPath: string;
     operationCount: number;
     needsAuthSetup: boolean;
+    authStrategy: AuthStrategy;
     notes: string[];
 }
 /** Last gate before generated files enter GitHub or a local checkout. */
@@ -583,6 +719,8 @@ declare function assertNoCommittedFrankieKeys(files: Array<{
     content: string;
 }>): void;
 declare function planHostedInstall(input: InstallProject): InstallPlan;
+/** Where the generated token endpoint gets the signed-in user from. */
+type AuthStrategy = "firebase" | "nextauth" | "supabase" | "custom" | "existing" | "anonymous" | "unconfigured";
 
 declare const skillSchema: z.ZodObject<{
     id: z.ZodString;
@@ -600,8 +738,46 @@ type WorkspaceSkill = z.infer<typeof skillSchema>;
 declare function activeSkills(config: FrankieConfig, availableTools?: string[]): WorkspaceSkill[];
 /** Only explicitly selected, currently enabled operations may execute through a skill. */
 declare function approvedSkillTools(config: FrankieConfig): string[];
-/** Deterministic starter, not a claim that new API code has been generated. */
-declare function draftSkill(goal: string, tools: string[]): string;
+/**
+ * What each tool identifier actually does, drawn from the connected sources'
+ * own inventories — the same data the dashboard shows next to each checkbox.
+ * Skill generation is only as concrete as the material it's given: a bare
+ * list of ids like `api__product__listItems` tells a model nothing about
+ * what to ask the user, what order to call things in, or how to summarize a
+ * result. This hands it the method/path/summary (or MCP description) for
+ * every tool a skill is being written for. Falls back to the bare id for a
+ * tool that isn't found (already removed, or awaiting a fresh inventory).
+ */
+declare function toolDescriptions(config: FrankieConfig, toolIds: string[]): Array<{
+    id: string;
+    description: string;
+}>;
+/**
+ * Starter suggestion prompts derived from the workspace's own published,
+ * runnable skills, so an empty chat offers what this assistant can actually do
+ * instead of a blank screen. Each entry is a clean action title ("Generate a
+ * lesson"), optionally with a short subtitle after " — " when the skill's goal
+ * adds real information. The chat empty state shows the title as the card title
+ * and the subtitle beneath it, and sends only the title. Auto-generated skill
+ * names (e.g. "product · generate lesson") and their boilerplate CRUD goals are
+ * cleaned up so the cards read like real suggestions, not internal ids. Used
+ * only when the workspace hasn't authored its own `suggestedPrompts`; deduped
+ * and capped to the config limit (6).
+ */
+declare function suggestedPromptsFromSkills(config: FrankieConfig): string[];
+/**
+ * Deterministic starter for the manual editor — not a claim that anything
+ * was executed, and not model-generated. Follows the same structure asked of
+ * AI-generated instructions (trigger recap, required inputs, numbered steps,
+ * reporting, error handling) so a hand-written skill starts from a useful
+ * shape instead of a blank textarea. `label` is each tool's own description
+ * when the caller has one (e.g. from the dashboard's approved-tools list);
+ * falls back to the bare id.
+ */
+declare function draftSkill(goal: string, tools: Array<{
+    id: string;
+    label?: string;
+}>): string;
 
 /** A repository-owned updater. No customer token is stored by Frankie. */
 declare function sdkUpdateWorkflow(mode: "manual" | "automatic"): string;
@@ -631,4 +807,4 @@ declare function compareApiDocuments(before: ApiDocument, after: ApiDocument): {
     unchangedIds: string[];
 };
 
-export { type AgentConfig, type ApiCapability, type ApiDocument, type ApiSourceConfig, type ApiToolInventory, type AuthConfig, type BrandingConfig, type ChatAttachment, type ChatRequestBody, type CreateSessionBody, type CreateSessionResponse, type FeaturesConfig, type FrankieConfig, type FrankieConfigInput, type FrankieErrorCode, type FrankieServerEvent, type InstallPlan, type InstallProject, type LimitsConfig, type LoadedSkill, type McpServerConfig, type ModelChoice, type ModelConfig, type PublicFeatures, type PublicWidgetConfig, type StopReason, type ThinkingLevel, type ToolDecision, type ToolPolicy, type UsageSummary, type WidgetTheme, type WidgetThemeConfig, type WorkspaceSkill, activeSkills, agentConfigSchema, apiCapabilitySchema, apiMethods, apiOperations, apiSourceSchema, approvedSkillTools, assertNoCommittedFrankieKeys, authConfigSchema, brandingConfigSchema, canonicalJson, compareApiDocuments, defineFrankieConfig, describeTool, draftSkill, evaluateToolPolicy, featuresConfigSchema, frankieConfigSchema, limitsConfigSchema, matchPath, mcpServerSchema, modelChoiceSchema, modelConfigSchema, operationId, parseFrankieConfig, planHostedInstall, sdkUpdateWorkflow, skillSchema, thinkingLevelSchema, toolPolicySchema, validateApiDocument, widgetThemeSchema };
+export { type AgentConfig, type ApiCapability, type ApiDocument, type ApiSourceConfig, type ApiToolInventory, type AuthConfig, type AuthStrategy, type BrandingConfig, type ChatAttachment, type ChatRequestBody, type CreateSessionBody, type CreateSessionResponse, FIREWORKS_MODELS, type FeaturesConfig, type FrankieConfig, type FrankieConfigInput, type FrankieErrorCode, type FrankieServerEvent, type HostToolRequest, type HostToolResult, type InstallPlan, type InstallProject, type LimitsConfig, type LoadedSkill, type McpServerConfig, type ModelChoice, type ModelConfig, type PublicFeatures, type PublicWidgetConfig, type StarterPrompt, type StopReason, type ThinkingLevel, type ToolDecision, type ToolPolicy, type ToolResultBody, type UsageSummary, type WidgetTheme, type WidgetThemeConfig, type WorkspaceSkill, activeSkills, agentConfigSchema, apiCapabilitySchema, apiMethods, apiOperations, apiSourceSchema, approvedSkillTools, assertNoCommittedFrankieKeys, authConfigSchema, brandingConfigSchema, canonicalJson, compareApiDocuments, defineFrankieConfig, describeTool, draftSkill, evaluateToolPolicy, featuresConfigSchema, frankieConfigSchema, limitsConfigSchema, matchPath, mcpServerSchema, modelChoiceSchema, modelConfigSchema, operationId, parseFrankieConfig, planHostedInstall, sdkUpdateWorkflow, skillSchema, starterPromptSchema, suggestedPromptsFromSkills, thinkingLevelSchema, toolDescriptions, toolPolicySchema, validateApiDocument, widgetThemeSchema };

package/dist/index.d.ts

@@ -19,6 +19,10 @@ declare const widgetThemeSchema: z.ZodPrefault<z.ZodObject<{
         dark: "dark";
         system: "system";
     }>>;
+    source: z.ZodDefault<z.ZodEnum<{
+        custom: "custom";
+        inherit: "inherit";
+    }>>;
 }, z.core.$strip>>;
 declare const thinkingLevelSchema: z.ZodEnum<{
     minimal: "minimal";
@@ -51,6 +55,24 @@ declare const modelChoiceSchema: z.ZodObject<{
     label: z.ZodString;
     provider: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * The Fireworks-hosted models Frankie offers in the dashboard's model-picker
+ * dropdown, so an admin can choose one instead of typing a raw model id. Any
+ * other provider model can still be entered by hand. Kept here so the dashboard
+ * and docs share one source.
+ *
+ * Deliberately limited to models that speak Fireworks' OpenAI-completions API:
+ * on Fireworks the Anthropic-Messages models inline their reasoning into the
+ * visible answer, which leaks the chain-of-thought into the chat, whereas the
+ * completions API keeps reasoning on a separate channel. All are large-context
+ * and tool-capable. (The leaky Anthropic-Messages models — e.g. Kimi K2.6 /
+ * K2.7 Code — are still reachable via the "Other" free-text option.)
+ */
+declare const FIREWORKS_MODELS: readonly {
+    id: string;
+    label: string;
+    note: string;
+}[];
 /**
  * Optional, opt-in chat capabilities the SDK consumer turns on per workspace.
  * Everything here is OFF by default: an embedded agent only gets a wider surface
@@ -76,6 +98,7 @@ declare const featuresConfigSchema: z.ZodPrefault<z.ZodObject<{
 }, z.core.$strip>>;
 declare const mcpServerSchema: z.ZodObject<{
     name: z.ZodString;
+    displayName: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     enabled: z.ZodDefault<z.ZodBoolean>;
     selectedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     discoveredTools: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -112,6 +135,7 @@ declare const apiCapabilitySchema: z.ZodObject<{
 }, z.core.$strip>;
 declare const apiSourceSchema: z.ZodObject<{
     name: z.ZodString;
+    displayName: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     spec: z.ZodString;
     baseUrl: z.ZodOptional<z.ZodString>;
     operations: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -124,6 +148,10 @@ declare const apiSourceSchema: z.ZodObject<{
         DELETE: "DELETE";
     }>>>;
     enabled: z.ZodDefault<z.ZodBoolean>;
+    execution: z.ZodDefault<z.ZodEnum<{
+        server: "server";
+        client: "client";
+    }>>;
     selectedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     exposeAsMcp: z.ZodDefault<z.ZodBoolean>;
     capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -151,10 +179,25 @@ declare const toolPolicySchema: z.ZodObject<{
     deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
     denyByDefault: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
+/**
+ * A starter card shown on the empty chat screen: a title and short description
+ * the reader sees, and the message that is sent as if they typed it when they
+ * click the card. Configured per workspace in the dashboard's Appearance tab.
+ */
+declare const starterPromptSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    message: z.ZodString;
+}, z.core.$strip>;
 declare const agentConfigSchema: z.ZodObject<{
     systemPrompt: z.ZodDefault<z.ZodString>;
     greeting: z.ZodDefault<z.ZodString>;
     suggestedPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    starterPrompts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        message: z.ZodString;
+    }, z.core.$strip>>>;
     maxTurns: z.ZodDefault<z.ZodNumber>;
     maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
     tools: z.ZodPrefault<z.ZodObject<{
@@ -167,6 +210,10 @@ declare const agentConfigSchema: z.ZodObject<{
 declare const authConfigSchema: z.ZodObject<{
     publishableKey: z.ZodString;
     allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    userCredential: z.ZodDefault<z.ZodEnum<{
+        jwt: "jwt";
+        opaque: "opaque";
+    }>>;
     allowAnonymous: z.ZodDefault<z.ZodBoolean>;
     jwtSecretEnv: z.ZodDefault<z.ZodString>;
     jwksUrl: z.ZodOptional<z.ZodString>;
@@ -209,6 +256,10 @@ declare const frankieConfigSchema: z.ZodObject<{
             dark: "dark";
             system: "system";
         }>>;
+        source: z.ZodDefault<z.ZodEnum<{
+            custom: "custom";
+            inherit: "inherit";
+        }>>;
     }, z.core.$strip>>;
     model: z.ZodPrefault<z.ZodObject<{
         provider: z.ZodDefault<z.ZodString>;
@@ -231,6 +282,11 @@ declare const frankieConfigSchema: z.ZodObject<{
         systemPrompt: z.ZodDefault<z.ZodString>;
         greeting: z.ZodDefault<z.ZodString>;
         suggestedPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        starterPrompts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            message: z.ZodString;
+        }, z.core.$strip>>>;
         maxTurns: z.ZodDefault<z.ZodNumber>;
         maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
         tools: z.ZodPrefault<z.ZodObject<{
@@ -243,6 +299,10 @@ declare const frankieConfigSchema: z.ZodObject<{
     auth: z.ZodObject<{
         publishableKey: z.ZodString;
         allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        userCredential: z.ZodDefault<z.ZodEnum<{
+            jwt: "jwt";
+            opaque: "opaque";
+        }>>;
         allowAnonymous: z.ZodDefault<z.ZodBoolean>;
         jwtSecretEnv: z.ZodDefault<z.ZodString>;
         jwksUrl: z.ZodOptional<z.ZodString>;
@@ -253,6 +313,7 @@ declare const frankieConfigSchema: z.ZodObject<{
     }, z.core.$strip>;
     mcpServers: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
+        displayName: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         selectedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         discoveredTools: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -270,6 +331,7 @@ declare const frankieConfigSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     apis: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
+        displayName: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
         spec: z.ZodString;
         baseUrl: z.ZodOptional<z.ZodString>;
         operations: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -282,6 +344,10 @@ declare const frankieConfigSchema: z.ZodObject<{
             DELETE: "DELETE";
         }>>>;
         enabled: z.ZodDefault<z.ZodBoolean>;
+        execution: z.ZodDefault<z.ZodEnum<{
+            server: "server";
+            client: "client";
+        }>>;
         selectedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         exposeAsMcp: z.ZodDefault<z.ZodBoolean>;
         capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -371,6 +437,14 @@ type StopReason = "end_turn" | "max_tokens" | "max_turns" | "stop_sequence" | "a
 interface UsageSummary {
     inputTokens: number;
     outputTokens: number;
+    /**
+     * Prompt-cache hits and writes, when the provider reports them. A cached
+     * input token costs a fraction of a fresh one, so this is what says whether
+     * the stable prefix — system prompt, tools, earlier turns — is actually being
+     * served from cache or re-read every turn.
+     */
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
     /** Present only when the upstream provider reports a price. */
     costUsd?: number;
 }
@@ -410,6 +484,21 @@ type FrankieServerEvent = {
     toolUseId: string;
     name: string;
     reason: string;
+}
+/**
+ * Client-side tool execution: the server asks the widget to make one HTTP
+ * call to the host's own API, from the user's browser and on the user's
+ * existing session, and to POST the outcome back to `/v1/chat/tool-result`
+ * with this `callId`. Emitted only for API sources marked
+ * `execution: "client"`. The turn's agent loop is paused on this call until
+ * the result arrives (or the turn times out). See `HostToolRequest`.
+ */
+ | {
+    type: "tool_call_request";
+    callId: string;
+    toolUseId: string;
+    name: string;
+    request: HostToolRequest;
 } | {
     type: "turn_end";
     stopReason: StopReason;
@@ -422,6 +511,38 @@ type FrankieServerEvent = {
 } | {
     type: "ping";
 };
+/**
+ * One HTTP call Frankie asks the browser to make against the host's own API,
+ * on the signed-in user's existing session. `path` is always relative (path +
+ * query, no scheme or host): the widget resolves it against the `api.baseUrl`
+ * the host configured, and attaches the user's own credentials (cookies or a
+ * bearer token). Frankie sends no credential of its own — the host API is the
+ * authorization boundary, exactly as for any request from the host's frontend.
+ */
+interface HostToolRequest {
+    /** The API source the operation belongs to (`api__<source>__...`). Diagnostic only. */
+    source: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Path + query string relative to `api.baseUrl`, params already interpolated. */
+    path: string;
+    /** JSON request body, when the operation declares one. */
+    body?: unknown;
+}
+/** The browser's outcome for a `tool_call_request`, POSTed back to the server. */
+interface HostToolResult {
+    /** HTTP status the host API returned, or 0 when the fetch itself failed. */
+    status: number;
+    /** Response body text as returned by the host API. */
+    body?: string;
+    /** A transport-level error (network failure, no host API configured). */
+    error?: string;
+}
+/** Client -> server body for `POST /v1/chat/tool-result`. */
+interface ToolResultBody {
+    /** The `callId` from the `tool_call_request` this answers. */
+    callId: string;
+    result: HostToolResult;
+}
 type FrankieErrorCode = "unauthorized" | "forbidden_origin" | "rate_limited" | "session_not_found" | "upstream_error" | "budget_exceeded" | "internal";
 /** Display metadata only; instructions never enter the public SDK config. */
 interface LoadedSkill {
@@ -488,6 +609,12 @@ interface CreateSessionResponse {
         anonymous: boolean;
     };
 }
+/** A starter card on the empty chat screen: what the reader sees, and the message clicking it sends. */
+interface StarterPrompt {
+    title: string;
+    description?: string;
+    message: string;
+}
 /** The subset of tenant config the widget is allowed to see. */
 interface PublicWidgetConfig {
     tenantId: string;
@@ -499,6 +626,8 @@ interface PublicWidgetConfig {
     };
     greeting: string;
     suggestedPrompts: string[];
+    /** Explicit starter cards (title + description + message). Take precedence over `suggestedPrompts` on the empty screen. Optional so older servers stay compatible. */
+    starterPrompts?: StarterPrompt[];
     theme: WidgetTheme;
     /** Whether the widget may open a session without a host-signed user token. */
     allowAnonymous: boolean;
@@ -537,6 +666,12 @@ interface WidgetTheme {
     radius?: string;
     fontFamily?: string;
     mode?: "light" | "dark" | "system";
+    /**
+     * "inherit" tells the widget to sample the host page's own colors instead
+     * of using the ones configured here, which then serve only as a fallback.
+     * Defaults to "custom" (use the configured colors) when unset.
+     */
+    source?: "custom" | "inherit";
 }
 
 interface ToolDecision {
@@ -575,6 +710,7 @@ interface InstallPlan {
     specPath: string;
     operationCount: number;
     needsAuthSetup: boolean;
+    authStrategy: AuthStrategy;
     notes: string[];
 }
 /** Last gate before generated files enter GitHub or a local checkout. */
@@ -583,6 +719,8 @@ declare function assertNoCommittedFrankieKeys(files: Array<{
     content: string;
 }>): void;
 declare function planHostedInstall(input: InstallProject): InstallPlan;
+/** Where the generated token endpoint gets the signed-in user from. */
+type AuthStrategy = "firebase" | "nextauth" | "supabase" | "custom" | "existing" | "anonymous" | "unconfigured";
 
 declare const skillSchema: z.ZodObject<{
     id: z.ZodString;
@@ -600,8 +738,46 @@ type WorkspaceSkill = z.infer<typeof skillSchema>;
 declare function activeSkills(config: FrankieConfig, availableTools?: string[]): WorkspaceSkill[];
 /** Only explicitly selected, currently enabled operations may execute through a skill. */
 declare function approvedSkillTools(config: FrankieConfig): string[];
-/** Deterministic starter, not a claim that new API code has been generated. */
-declare function draftSkill(goal: string, tools: string[]): string;
+/**
+ * What each tool identifier actually does, drawn from the connected sources'
+ * own inventories — the same data the dashboard shows next to each checkbox.
+ * Skill generation is only as concrete as the material it's given: a bare
+ * list of ids like `api__product__listItems` tells a model nothing about
+ * what to ask the user, what order to call things in, or how to summarize a
+ * result. This hands it the method/path/summary (or MCP description) for
+ * every tool a skill is being written for. Falls back to the bare id for a
+ * tool that isn't found (already removed, or awaiting a fresh inventory).
+ */
+declare function toolDescriptions(config: FrankieConfig, toolIds: string[]): Array<{
+    id: string;
+    description: string;
+}>;
+/**
+ * Starter suggestion prompts derived from the workspace's own published,
+ * runnable skills, so an empty chat offers what this assistant can actually do
+ * instead of a blank screen. Each entry is a clean action title ("Generate a
+ * lesson"), optionally with a short subtitle after " — " when the skill's goal
+ * adds real information. The chat empty state shows the title as the card title
+ * and the subtitle beneath it, and sends only the title. Auto-generated skill
+ * names (e.g. "product · generate lesson") and their boilerplate CRUD goals are
+ * cleaned up so the cards read like real suggestions, not internal ids. Used
+ * only when the workspace hasn't authored its own `suggestedPrompts`; deduped
+ * and capped to the config limit (6).
+ */
+declare function suggestedPromptsFromSkills(config: FrankieConfig): string[];
+/**
+ * Deterministic starter for the manual editor — not a claim that anything
+ * was executed, and not model-generated. Follows the same structure asked of
+ * AI-generated instructions (trigger recap, required inputs, numbered steps,
+ * reporting, error handling) so a hand-written skill starts from a useful
+ * shape instead of a blank textarea. `label` is each tool's own description
+ * when the caller has one (e.g. from the dashboard's approved-tools list);
+ * falls back to the bare id.
+ */
+declare function draftSkill(goal: string, tools: Array<{
+    id: string;
+    label?: string;
+}>): string;
 
 /** A repository-owned updater. No customer token is stored by Frankie. */
 declare function sdkUpdateWorkflow(mode: "manual" | "automatic"): string;
@@ -631,4 +807,4 @@ declare function compareApiDocuments(before: ApiDocument, after: ApiDocument): {
     unchangedIds: string[];
 };
 
-export { type AgentConfig, type ApiCapability, type ApiDocument, type ApiSourceConfig, type ApiToolInventory, type AuthConfig, type BrandingConfig, type ChatAttachment, type ChatRequestBody, type CreateSessionBody, type CreateSessionResponse, type FeaturesConfig, type FrankieConfig, type FrankieConfigInput, type FrankieErrorCode, type FrankieServerEvent, type InstallPlan, type InstallProject, type LimitsConfig, type LoadedSkill, type McpServerConfig, type ModelChoice, type ModelConfig, type PublicFeatures, type PublicWidgetConfig, type StopReason, type ThinkingLevel, type ToolDecision, type ToolPolicy, type UsageSummary, type WidgetTheme, type WidgetThemeConfig, type WorkspaceSkill, activeSkills, agentConfigSchema, apiCapabilitySchema, apiMethods, apiOperations, apiSourceSchema, approvedSkillTools, assertNoCommittedFrankieKeys, authConfigSchema, brandingConfigSchema, canonicalJson, compareApiDocuments, defineFrankieConfig, describeTool, draftSkill, evaluateToolPolicy, featuresConfigSchema, frankieConfigSchema, limitsConfigSchema, matchPath, mcpServerSchema, modelChoiceSchema, modelConfigSchema, operationId, parseFrankieConfig, planHostedInstall, sdkUpdateWorkflow, skillSchema, thinkingLevelSchema, toolPolicySchema, validateApiDocument, widgetThemeSchema };
+export { type AgentConfig, type ApiCapability, type ApiDocument, type ApiSourceConfig, type ApiToolInventory, type AuthConfig, type AuthStrategy, type BrandingConfig, type ChatAttachment, type ChatRequestBody, type CreateSessionBody, type CreateSessionResponse, FIREWORKS_MODELS, type FeaturesConfig, type FrankieConfig, type FrankieConfigInput, type FrankieErrorCode, type FrankieServerEvent, type HostToolRequest, type HostToolResult, type InstallPlan, type InstallProject, type LimitsConfig, type LoadedSkill, type McpServerConfig, type ModelChoice, type ModelConfig, type PublicFeatures, type PublicWidgetConfig, type StarterPrompt, type StopReason, type ThinkingLevel, type ToolDecision, type ToolPolicy, type ToolResultBody, type UsageSummary, type WidgetTheme, type WidgetThemeConfig, type WorkspaceSkill, activeSkills, agentConfigSchema, apiCapabilitySchema, apiMethods, apiOperations, apiSourceSchema, approvedSkillTools, assertNoCommittedFrankieKeys, authConfigSchema, brandingConfigSchema, canonicalJson, compareApiDocuments, defineFrankieConfig, describeTool, draftSkill, evaluateToolPolicy, featuresConfigSchema, frankieConfigSchema, limitsConfigSchema, matchPath, mcpServerSchema, modelChoiceSchema, modelConfigSchema, operationId, parseFrankieConfig, planHostedInstall, sdkUpdateWorkflow, skillSchema, starterPromptSchema, suggestedPromptsFromSkills, thinkingLevelSchema, toolDescriptions, toolPolicySchema, validateApiDocument, widgetThemeSchema };