@frankieai/core 0.2.1 → 0.2.3

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<{
@@ -108,9 +131,11 @@ declare const apiCapabilitySchema: z.ZodObject<{
     }>;
     path: z.ZodString;
     summary: z.ZodOptional<z.ZodString>;
+    authGap: z.ZodDefault<z.ZodBoolean>;
 }, 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>>;
@@ -123,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<{
@@ -136,10 +165,12 @@ declare const apiSourceSchema: z.ZodObject<{
         }>;
         path: z.ZodString;
         summary: z.ZodOptional<z.ZodString>;
+        authGap: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>>;
     headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     forwardUserTokenAs: z.ZodOptional<z.ZodString>;
     forwardUserClaims: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    security: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     timeoutMs: z.ZodDefault<z.ZodNumber>;
     maxResponseChars: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
@@ -164,6 +195,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>;
@@ -206,6 +241,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>;
@@ -240,6 +279,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>;
@@ -250,6 +293,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<{
@@ -267,6 +311,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>>;
@@ -279,6 +324,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<{
@@ -292,10 +341,12 @@ declare const frankieConfigSchema: z.ZodObject<{
             }>;
             path: z.ZodString;
             summary: z.ZodOptional<z.ZodString>;
+            authGap: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>>>;
         headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
         forwardUserTokenAs: z.ZodOptional<z.ZodString>;
         forwardUserClaims: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        security: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
         timeoutMs: z.ZodDefault<z.ZodNumber>;
         maxResponseChars: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>>;
@@ -366,6 +417,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;
 }
@@ -373,6 +432,9 @@ interface UsageSummary {
 type FrankieServerEvent = {
     type: "skills_loaded";
     skills: LoadedSkill[];
+} | {
+    type: "tools_active";
+    apis: ApiToolInventory[];
 } | {
     type: "session";
     sessionId: string;
@@ -402,6 +464,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;
@@ -414,6 +491,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 {
@@ -421,6 +530,16 @@ interface LoadedSkill {
     name: string;
     revision: number;
 }
+/**
+ * Which OpenAPI source is live for this turn, and a content fingerprint of the
+ * exact spec loaded — so a host or a signed-in admin can see that a refresh
+ * actually changed what chat is calling, without exposing the spec itself.
+ */
+interface ApiToolInventory {
+    name: string;
+    specHash: string;
+    operationCount: number;
+}
 /** A file the end user attached to a turn. `data` is base64 (no data-URL prefix). */
 interface ChatAttachment {
     name: string;
@@ -519,6 +638,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 {
@@ -557,6 +682,7 @@ interface InstallPlan {
     specPath: string;
     operationCount: number;
     needsAuthSetup: boolean;
+    authStrategy: AuthStrategy;
     notes: string[];
 }
 /** Last gate before generated files enter GitHub or a local checkout. */
@@ -565,6 +691,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;
@@ -582,8 +710,33 @@ 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;
+}>;
+/**
+ * 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;
@@ -600,6 +753,12 @@ declare function apiOperations(doc: ApiDocument): Map<string, {
     id: string;
     fingerprint: string;
 }>;
+/**
+ * `/projects/*` matches one path segment; `/projects/**` matches any depth and
+ * the base path itself, since a tenant writing that plainly means "this part of
+ * the API" rather than "everything under it but not it".
+ */
+declare function matchPath(glob: string, path: string): boolean;
 declare function compareApiDocuments(before: ApiDocument, after: ApiDocument): {
     added: string[];
     changed: string[];
@@ -607,4 +766,4 @@ declare function compareApiDocuments(before: ApiDocument, after: ApiDocument): {
     unchangedIds: string[];
 };
 
-export { type AgentConfig, type ApiCapability, type ApiDocument, type ApiSourceConfig, 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, 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 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, 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<{
@@ -108,9 +131,11 @@ declare const apiCapabilitySchema: z.ZodObject<{
     }>;
     path: z.ZodString;
     summary: z.ZodOptional<z.ZodString>;
+    authGap: z.ZodDefault<z.ZodBoolean>;
 }, 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>>;
@@ -123,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<{
@@ -136,10 +165,12 @@ declare const apiSourceSchema: z.ZodObject<{
         }>;
         path: z.ZodString;
         summary: z.ZodOptional<z.ZodString>;
+        authGap: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>>;
     headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     forwardUserTokenAs: z.ZodOptional<z.ZodString>;
     forwardUserClaims: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    security: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     timeoutMs: z.ZodDefault<z.ZodNumber>;
     maxResponseChars: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
@@ -164,6 +195,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>;
@@ -206,6 +241,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>;
@@ -240,6 +279,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>;
@@ -250,6 +293,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<{
@@ -267,6 +311,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>>;
@@ -279,6 +324,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<{
@@ -292,10 +341,12 @@ declare const frankieConfigSchema: z.ZodObject<{
             }>;
             path: z.ZodString;
             summary: z.ZodOptional<z.ZodString>;
+            authGap: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>>>;
         headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
         forwardUserTokenAs: z.ZodOptional<z.ZodString>;
         forwardUserClaims: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        security: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
         timeoutMs: z.ZodDefault<z.ZodNumber>;
         maxResponseChars: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>>;
@@ -366,6 +417,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;
 }
@@ -373,6 +432,9 @@ interface UsageSummary {
 type FrankieServerEvent = {
     type: "skills_loaded";
     skills: LoadedSkill[];
+} | {
+    type: "tools_active";
+    apis: ApiToolInventory[];
 } | {
     type: "session";
     sessionId: string;
@@ -402,6 +464,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;
@@ -414,6 +491,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 {
@@ -421,6 +530,16 @@ interface LoadedSkill {
     name: string;
     revision: number;
 }
+/**
+ * Which OpenAPI source is live for this turn, and a content fingerprint of the
+ * exact spec loaded — so a host or a signed-in admin can see that a refresh
+ * actually changed what chat is calling, without exposing the spec itself.
+ */
+interface ApiToolInventory {
+    name: string;
+    specHash: string;
+    operationCount: number;
+}
 /** A file the end user attached to a turn. `data` is base64 (no data-URL prefix). */
 interface ChatAttachment {
     name: string;
@@ -519,6 +638,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 {
@@ -557,6 +682,7 @@ interface InstallPlan {
     specPath: string;
     operationCount: number;
     needsAuthSetup: boolean;
+    authStrategy: AuthStrategy;
     notes: string[];
 }
 /** Last gate before generated files enter GitHub or a local checkout. */
@@ -565,6 +691,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;
@@ -582,8 +710,33 @@ 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;
+}>;
+/**
+ * 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;
@@ -600,6 +753,12 @@ declare function apiOperations(doc: ApiDocument): Map<string, {
     id: string;
     fingerprint: string;
 }>;
+/**
+ * `/projects/*` matches one path segment; `/projects/**` matches any depth and
+ * the base path itself, since a tenant writing that plainly means "this part of
+ * the API" rather than "everything under it but not it".
+ */
+declare function matchPath(glob: string, path: string): boolean;
 declare function compareApiDocuments(before: ApiDocument, after: ApiDocument): {
     added: string[];
     changed: string[];
@@ -607,4 +766,4 @@ declare function compareApiDocuments(before: ApiDocument, after: ApiDocument): {
     unchangedIds: string[];
 };
 
-export { type AgentConfig, type ApiCapability, type ApiDocument, type ApiSourceConfig, 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, 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 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, thinkingLevelSchema, toolDescriptions, toolPolicySchema, validateApiDocument, widgetThemeSchema };