@frankieai/server 0.2.5 → 0.2.7

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Hono } from 'hono';
-import { FrankieConfig, AuthConfig, WorkspaceSkill, HostToolRequest, HostToolResult, ChatAttachment, FrankieServerEvent, McpServerConfig, ToolPolicy, ApiToolInventory, ApiSourceConfig } from '@frankieai/core';
+import { FrankieConfig, AuthConfig, HostToolResult, ActionPreview, WorkspaceSkill, HostToolRequest, ChatAttachment, FrankieServerEvent, McpServerConfig, ToolPolicy, ApiToolInventory, ApiSourceConfig } from '@frankieai/core';
 export { matchPath } from '@frankieai/core';
 import { AgentMessage, AgentTool } from '@earendil-works/pi-agent-core';
 import { JWTPayload } from 'jose';
@@ -112,57 +112,6 @@ declare function safeEqual(a: string, b: string): boolean;
 /** Stable pseudonymous id for an anonymous visitor. */
 declare function anonymousUser(seed: string): VerifiedUser;
 
-interface ChatSession {
-    id: string;
-    tenantId: string;
-    user: VerifiedUser;
-    /** Raw host-signed token, forwarded only to tenant tools that explicitly opt in. */
-    userToken?: string;
-    origin?: string;
-    context: Record<string, string | number | boolean | null>;
-    /** Agent transcript used to continue the model conversation on the server. */
-    messages: AgentMessage[];
-    /** UI transcript kept separately so the exact rendered chat can sync across devices. */
-    clientMessages?: unknown[];
-    /** User-editable title, otherwise derived from the first user message. */
-    title?: string;
-    createdAt: number;
-    lastActiveAt: number;
-    messageCount: number;
-    costUsd: number;
-    busy: boolean;
-}
-interface SessionStore {
-    create(session: ChatSession): Promise<void>;
-    get(id: string): Promise<ChatSession | undefined>;
-    /** List one user's conversations for a tenant, newest first. */
-    listByUser(tenantId: string, userId: string): Promise<ChatSession[]>;
-    /** Workspace-owner history view. This is only exposed through the authenticated control plane. */
-    listByTenant(tenantId: string): Promise<ChatSession[]>;
-    /**
-     * Non-expired conversation count per tenant id, in one pass. Used by the
-     * workspace directory to show a workspace as "Live" once it has real chats —
-     * cheaper than a listByTenant call per workspace.
-     */
-    countsByTenant(): Promise<Record<string, number>>;
-    update(id: string, patch: Partial<ChatSession>): Promise<void>;
-    delete(id: string): Promise<void>;
-}
-declare class MemorySessionStore implements SessionStore {
-    private readonly ttlMs;
-    private readonly sessions;
-    constructor(ttlMs?: number);
-    create(session: ChatSession): Promise<void>;
-    get(id: string): Promise<ChatSession | undefined>;
-    listByUser(tenantId: string, userId: string): Promise<ChatSession[]>;
-    listByTenant(tenantId: string): Promise<ChatSession[]>;
-    countsByTenant(): Promise<Record<string, number>>;
-    update(id: string, patch: Partial<ChatSession>): Promise<void>;
-    delete(id: string): Promise<void>;
-    private evictExpired;
-}
-declare function newSessionId(): string;
-
 declare class ModelResolutionError extends Error {
 }
 interface ResolvedModel {
@@ -249,35 +198,11 @@ declare class SingleTenantStore implements TenantStore {
 declare class MemoryTenantStore implements TenantStore {
     private readonly byKey;
     constructor(tenants?: ReadonlyArray<ResolvedConfig>);
-    /** Register (or replace) a tenant. Its publishable key is its lookup key. */
+    /** Register (or replace) a tenant, under its base key and each persona's key. */
     add(resolved: ResolvedConfig): void;
     byPublishableKey(key: string): Promise<ResolvedConfig | null>;
 }
 
-interface CreateAppOptions {
-    /** A single tenant, resolved at startup — the self-hosted case. */
-    resolved?: ResolvedConfig;
-    /** Many tenants, each resolved by publishable key at request time — the SaaS case. */
-    tenants?: TenantStore | TenantRegistry;
-    sessions?: SessionStore;
-    rateLimiter?: RateLimiter;
-    logger?: (event: Record<string, unknown>) => void;
-}
-type AppEnv = {
-    Variables: {
-        tenant: TenantRuntime;
-    };
-};
-declare function createFrankieApp(options: CreateAppOptions): Hono<AppEnv>;
-
-interface McpHostOptions {
-    tenants: TenantStore | TenantRegistry;
-    logger?: (event: Record<string, unknown>) => void;
-    /** Injected in tests so generated API tools hit a stub rather than the network. */
-    fetchImpl?: typeof fetch;
-}
-declare function createMcpHostApp(options: McpHostOptions): Hono;
-
 /**
  * What the control plane stores per tenant. The model provider key is *not*
  * here — in the hosted shape that key is Frankie's own, one shared key read
@@ -302,6 +227,10 @@ interface RepositoryInstallRecord {
     pullRequestState?: "draft" | "open" | "closed" | "merged";
     checkRollup?: "success" | "pending" | "failure" | "none";
     checkedAt?: string;
+    /** The current integration stage (see apps/web/lib/integration-status.ts), so Overview renders it on first paint. */
+    stage?: string;
+    /** The fully-integrated checklist rows that are done (apps/web/lib/integration-checklist.ts) — the funnel position. */
+    checklist?: string[];
     updatedAt: string;
 }
 /**
@@ -322,6 +251,28 @@ interface VercelLinkRecord {
 }
 /** `VercelLinkRecord` with the token stripped — what the dashboard sees. */
 type PublicVercelLink = Omit<VercelLinkRecord, "accessToken">;
+/** What the installer read from the repository's own styling (see @frankieai/core inferTheme). */
+interface SuggestedThemeRecord {
+    theme: {
+        primary: string;
+        background?: string;
+        foreground?: string;
+        radius?: string;
+    };
+    sources: Array<{
+        field: "primary" | "background" | "foreground" | "radius";
+        path: string;
+    }>;
+    repository: string;
+    inferredAt: string;
+}
+/** An uploaded file's text, kept so every re-index includes it. */
+interface KnowledgeDocument {
+    id: string;
+    name: string;
+    text: string;
+    addedAt: string;
+}
 interface TenantRecord {
     apiSpecSync?: Record<string, {
         repository: string;
@@ -343,8 +294,25 @@ interface TenantRecord {
     sessionSecret: string;
     /** When true, the workspace is protected: it cannot be deleted until unlocked. */
     locked?: boolean;
+    /** When true, the dashboard applies a changed repository spec on its own (new operations still land unapproved). */
+    apiAutoRefresh?: boolean;
+    /** A widget theme inferred from the repository at install time, awaiting Accept / Keep in the Theme editor. */
+    suggestedTheme?: SuggestedThemeRecord;
     /** Durable repository-install state surfaced in the dashboard and setup chat. */
     repositoryInstall?: RepositoryInstallRecord;
+    /**
+     * Per-persona repository-install state, keyed by persona id. The primary
+     * agent keeps `repositoryInstall`; each embedded persona (see
+     * `config.personas`) gets its own install record here, so a workspace can
+     * open a separate scoped-install PR per agent.
+     */
+    personaInstalls?: Record<string, RepositoryInstallRecord>;
+    /**
+     * Files the team uploaded for its agents to answer from (an FAQ, a guide),
+     * as extracted text. Indexed alongside the crawled pages; never sent to the
+     * dashboard in full.
+     */
+    knowledgeDocuments?: KnowledgeDocument[];
     /** Deployment provider connection, when the workspace has connected Vercel. */
     vercel?: VercelLinkRecord;
     createdAt: string;
@@ -407,14 +375,30 @@ interface PublicTenant {
     }>;
     /** Protected from deletion until unlocked. */
     locked: boolean;
+    /** Apply a changed repository spec without a click (see TenantRecord). */
+    apiAutoRefresh: boolean;
+    suggestedTheme?: SuggestedThemeRecord;
     /** A submitted or in-progress SDK installation for this workspace. */
     repositoryInstall?: RepositoryInstallRecord;
+    /** A submitted or in-progress scoped-install PR per persona id (`config.personas`). */
+    personaInstalls?: Record<string, RepositoryInstallRecord>;
+    /** Uploaded files agents answer from: names and sizes only. */
+    knowledgeDocuments: Array<{
+        id: string;
+        name: string;
+        chars: number;
+        addedAt: string;
+    }>;
     /** The connected Vercel installation and matched project — never its token. */
     vercel?: PublicVercelLink;
     /** The customer's brand theme for the widget, so the dashboard can edit it. */
     theme: TenantRecord["config"]["theme"];
     /** Opt-in chat capabilities (attachments, model picker) for the dashboard to edit. */
     features: TenantRecord["config"]["features"];
+    /** Documentation sources indexed for the knowledge-base agent, for the dashboard to edit. */
+    knowledgeBase: TenantRecord["config"]["knowledgeBase"];
+    /** Embedded page-scoped personas (extra agents) on this workspace, for the dashboard to edit. Their publishable keys are public. */
+    personas: TenantRecord["config"]["personas"];
     /** Editable chat copy: the greeting and the starter cards shown on the empty screen. */
     agent: {
         greeting: string;
@@ -453,6 +437,27 @@ interface PlatformAdminRecord {
     grantedBy: string;
     createdAt: string;
 }
+/** Billing plan tiers. Free is the default; Pro lifts the workspace cap. */
+type Plan = "free" | "pro";
+/**
+ * A per-org (owner id) billing subscription. One org, one subscription,
+ * covering all its workspaces and members — matching the model where inviting
+ * someone grants access to every workspace. The Stripe ids are written only by
+ * the webhook (platform admin), never by the org itself, so an org can't
+ * self-upgrade. Absent record ⇒ the Free plan.
+ */
+interface SubscriptionRecord {
+    /** The org's owner id, e.g. "github:42". */
+    org: string;
+    plan: Plan;
+    /** Mirrors the Stripe subscription status; anything but active/trialing is treated as Free. */
+    status: "active" | "trialing" | "past_due" | "canceled" | "incomplete";
+    stripeCustomerId?: string;
+    stripeSubscriptionId?: string;
+    /** ISO timestamp the current paid period ends, for display. */
+    currentPeriodEnd?: string;
+    updatedAt: string;
+}
 interface ControlStore extends TenantStore {
     listOrganizations(): Promise<string[]>;
     listPlatformAdmins(): Promise<PlatformAdminRecord[]>;
@@ -463,6 +468,12 @@ interface ControlStore extends TenantStore {
     list(ownerId?: string): Promise<TenantRecord[]>;
     get(id: string): Promise<TenantRecord | null>;
     put(record: TenantRecord): Promise<void>;
+    /**
+     * Store a brand-new tenant, never replacing one: false when the id (or its
+     * publishable key) is already taken. Creating a workspace must use this, so
+     * a colliding id can't overwrite someone else's workspace.
+     */
+    insert(record: TenantRecord): Promise<boolean>;
     /** Remove a tenant for good. A no-op if it does not exist. */
     delete(id: string): Promise<void>;
     /** All members of the org owned by `org`. */
@@ -473,6 +484,10 @@ interface ControlStore extends TenantStore {
     deleteMember(org: string, login: string): Promise<void>;
     /** Every org membership held by a given login, across all orgs. */
     membershipsForLogin(login: string): Promise<MembershipRecord[]>;
+    /** The org's billing subscription, or null for an org on the Free plan. */
+    getSubscription(org: string): Promise<SubscriptionRecord | null>;
+    /** Create or replace an org's subscription. Written by the Stripe webhook. */
+    putSubscription(subscription: SubscriptionRecord): Promise<void>;
 }
 /**
  * The control plane's persistence, and at the same time a `TenantStore` the
@@ -495,6 +510,7 @@ declare class FileTenantStore implements ControlStore {
     private index;
     private byId;
     private members;
+    private subscriptions;
     private loaded;
     private static memberKey;
     constructor(options: {
@@ -508,13 +524,23 @@ declare class FileTenantStore implements ControlStore {
     putMember(member: MembershipRecord): Promise<void>;
     deleteMember(org: string, login: string): Promise<void>;
     membershipsForLogin(login: string): Promise<MembershipRecord[]>;
+    private persistSubscriptions;
+    getSubscription(org: string): Promise<SubscriptionRecord | null>;
+    putSubscription(subscription: SubscriptionRecord): Promise<void>;
     private remember;
     byPublishableKey(key: string): Promise<ResolvedConfig | null>;
     /** All tenants, or — when an owner is given — only that owner's. */
     list(ownerId?: string): Promise<TenantRecord[]>;
     get(id: string): Promise<TenantRecord | null>;
     put(record: TenantRecord): Promise<void>;
+    insert(record: TenantRecord): Promise<boolean>;
     compareAndSwap(previous: TenantRecord, next: TenantRecord): Promise<boolean>;
+    /**
+     * A record holds the workspace's signing and session secrets and source
+     * credentials: owner-only permissions, and written whole (temp file, then
+     * rename) so a crash never leaves half a record behind.
+     */
+    private write;
     delete(id: string): Promise<void>;
 }
 
@@ -557,6 +583,7 @@ declare class PostgresTenantStore implements ControlStore {
     private ensureReady;
     /** Create the table if it isn't there yet. Safe to call repeatedly. */
     init(): Promise<void>;
+    private subscriptionRow;
     private memberRow;
     private adminRow;
     listOrganizations(): Promise<string[]>;
@@ -567,16 +594,218 @@ declare class PostgresTenantStore implements ControlStore {
     listMembers(org: string): Promise<MembershipRecord[]>;
     putMember(member: MembershipRecord): Promise<void>;
     deleteMember(org: string, login: string): Promise<void>;
+    getSubscription(org: string): Promise<SubscriptionRecord | null>;
+    putSubscription(subscription: SubscriptionRecord): Promise<void>;
     membershipsForLogin(login: string): Promise<MembershipRecord[]>;
     private parse;
     byPublishableKey(key: string): Promise<ResolvedConfig | null>;
     list(ownerId?: string): Promise<TenantRecord[]>;
     get(id: string): Promise<TenantRecord | null>;
+    insert(record: TenantRecord): Promise<boolean>;
     put(record: TenantRecord): Promise<void>;
     delete(id: string): Promise<void>;
     compareAndSwap(previous: TenantRecord, next: TenantRecord): Promise<boolean>;
 }
 
+/**
+ * Something said about a running turn from a request that may have landed on a
+ * different server instance than the one running it: the user pressed Stop,
+ * or their browser finished a tool call the turn is waiting on.
+ */
+type TurnSignal = {
+    kind: "stop";
+} | {
+    kind: "tool_result";
+    callId: string;
+    result: HostToolResult;
+};
+/**
+ * Carries turn signals between instances. A turn polls for its session's
+ * signals while it runs; a request that can't reach the turn locally sends one.
+ * Single-instance deployments don't need it: everything is local.
+ */
+interface TurnSignals {
+    send(sessionId: string, signal: TurnSignal): Promise<void>;
+    /** Signals for the session after `afterId`, oldest first. */
+    poll(sessionId: string, afterId: number): Promise<Array<{
+        id: number;
+        signal: TurnSignal;
+    }>>;
+    /** The newest signal id, so a turn starting now ignores everything before it. */
+    latestId(sessionId: string): Promise<number>;
+}
+
+/** One recorded hand-off to the workspace's team. Stored on the conversation. */
+interface EscalationRecord {
+    id: string;
+    at: number;
+    /** Why the agent escalated (its own words / the visitor's ask). */
+    reason: string;
+    /** A short recap of what the visitor needs and what was already tried. */
+    summary: string;
+    /** How to reach the visitor, when they provided it. */
+    email?: string;
+    name?: string;
+}
+/** What the tool hands back to the app: the record plus who/where it came from. */
+interface EscalationEvent extends EscalationRecord {
+    tenantId: string;
+    conversationId: string;
+    userId: string;
+}
+type EscalationSink = (event: EscalationEvent) => Promise<void>;
+
+interface ChatSession {
+    id: string;
+    tenantId: string;
+    user: VerifiedUser;
+    /** Raw host-signed token, forwarded only to tenant tools that explicitly opt in. */
+    userToken?: string;
+    origin?: string;
+    /**
+     * The publishable key the chat was opened with: the workspace's own key or
+     * one of its agents' keys. Lets the dashboard say which agent answered.
+     */
+    agentKey?: string;
+    context: Record<string, string | number | boolean | null>;
+    /** Agent transcript used to continue the model conversation on the server. */
+    messages: AgentMessage[];
+    /** UI transcript kept separately so the exact rendered chat can sync across devices. */
+    clientMessages?: unknown[];
+    /** User-editable title, otherwise derived from the first user message. */
+    title?: string;
+    createdAt: number;
+    lastActiveAt: number;
+    messageCount: number;
+    costUsd: number;
+    /** True while a chat turn holds this session; see `busySince` for how long. */
+    busy: boolean;
+    /**
+     * When the running turn took the lock. A turn can only hold the session for
+     * as long as its timeout, so a lock older than that is one whose release
+     * never landed (the instance was frozen or restarted mid-turn) and is free
+     * for the taking — otherwise the session would answer 409 forever.
+     */
+    busySince?: number;
+    /** When someone pressed Stop for a turn running on another instance; that turn then doesn't save its reply. */
+    stopRequestedAt?: number;
+    /** Human hand-offs the agent made in this conversation (the escalation inbox). */
+    escalations?: EscalationRecord[];
+    /** An action that changes data, paused until the user approves or cancels it. */
+    pendingAction?: PendingAction;
+}
+/**
+ * A write the agent asked for and the user hasn't answered yet. On Approve the
+ * server runs exactly this call, with these inputs, not whatever the model
+ * would ask for next time.
+ */
+interface PendingAction {
+    toolUseId: string;
+    name: string;
+    label: string;
+    args: unknown;
+    preview: ActionPreview;
+    createdAt: number;
+}
+interface SessionStore {
+    create(session: ChatSession): Promise<void>;
+    get(id: string): Promise<ChatSession | undefined>;
+    /** List one user's conversations for a tenant, newest first. */
+    listByUser(tenantId: string, userId: string): Promise<ChatSession[]>;
+    /** Workspace-owner history view. This is only exposed through the authenticated control plane. */
+    listByTenant(tenantId: string): Promise<ChatSession[]>;
+    /**
+     * Non-expired conversation count per tenant id, in one pass. Used by the
+     * workspace directory to show a workspace as "Live" once it has real chats —
+     * cheaper than a listByTenant call per workspace.
+     */
+    countsByTenant(): Promise<Record<string, number>>;
+    update(id: string, patch: Partial<ChatSession>): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+declare class MemorySessionStore implements SessionStore {
+    private readonly ttlMs;
+    private readonly sessions;
+    constructor(ttlMs?: number);
+    create(session: ChatSession): Promise<void>;
+    get(id: string): Promise<ChatSession | undefined>;
+    listByUser(tenantId: string, userId: string): Promise<ChatSession[]>;
+    listByTenant(tenantId: string): Promise<ChatSession[]>;
+    countsByTenant(): Promise<Record<string, number>>;
+    update(id: string, patch: Partial<ChatSession>): Promise<void>;
+    delete(id: string): Promise<void>;
+    private evictExpired;
+}
+declare function newSessionId(): string;
+
+/** One indexed passage of a document, with its embedding vector. */
+interface KnowledgeChunk {
+    id: string;
+    url: string;
+    title: string;
+    text: string;
+    embedding: number[];
+}
+/** A retrieval result: the passage and how close it was to the query. */
+interface KnowledgeHit {
+    url: string;
+    title: string;
+    text: string;
+    score: number;
+}
+/** What the dashboard shows about a workspace's index. */
+interface KnowledgeStats {
+    chunks: number;
+    pages: number;
+    sources: string[];
+    ingestedAt?: number;
+}
+interface KnowledgeStore {
+    /** Replace a workspace's whole index with a freshly ingested set (atomic swap). */
+    replace(tenantId: string, chunks: KnowledgeChunk[], meta: {
+        sources: string[];
+        pages: number;
+        ingestedAt: number;
+    }): Promise<void>;
+    /** Top-k passages by cosine similarity to the query vector. */
+    search(tenantId: string, queryVector: readonly number[], k: number): Promise<KnowledgeHit[]>;
+    stats(tenantId: string): Promise<KnowledgeStats>;
+    clear(tenantId: string): Promise<void>;
+}
+
+interface CreateAppOptions {
+    /** A single tenant, resolved at startup — the self-hosted case. */
+    resolved?: ResolvedConfig;
+    /** Many tenants, each resolved by publishable key at request time — the SaaS case. */
+    tenants?: TenantStore | TenantRegistry;
+    sessions?: SessionStore;
+    /** Knowledge-base index for the docs-search tool; in-memory when omitted. */
+    knowledge?: KnowledgeStore;
+    rateLimiter?: RateLimiter;
+    /**
+     * Reaches a turn running on another instance: Stop, and browser tool
+     * results. Needed whenever more than one instance serves chat.
+     */
+    turnSignals?: TurnSignals;
+    logger?: (event: Record<string, unknown>) => void;
+}
+type AppEnv = {
+    Variables: {
+        tenant: TenantRuntime;
+    };
+};
+declare function createFrankieApp(options: CreateAppOptions): Hono<AppEnv>;
+
+interface McpHostOptions {
+    tenants: TenantStore | TenantRegistry;
+    logger?: (event: Record<string, unknown>) => void;
+    /** Injected in tests so generated API tools hit a stub rather than the network. */
+    fetchImpl?: typeof fetch;
+    /** Shared with the chat API; each request counts against the tenant's message budget. */
+    rateLimiter?: RateLimiter;
+}
+declare function createMcpHostApp(options: McpHostOptions): Hono;
+
 interface ResolvedStore {
     store: ControlStore;
     describe: string;
@@ -584,6 +813,10 @@ interface ResolvedStore {
 interface ResolvedStores {
     tenants: ControlStore;
     sessions: SessionStore;
+    knowledge: KnowledgeStore;
+    /** Shared across instances with Postgres; undefined means in-memory (one instance). */
+    rateLimiter?: RateLimiter;
+    turnSignals?: TurnSignals;
     describe: string;
 }
 /**
@@ -612,10 +845,21 @@ declare class PostgresSessionStore implements SessionStore {
     private readonly db;
     private readonly ttlMs;
     private ready?;
+    private lastPurge;
     constructor(options: {
         db: Queryable;
         ttlMs?: number;
     });
+    /** Deletes every conversation idle past the TTL. Returns how many went. */
+    purgeExpired(): Promise<number>;
+    /**
+     * Purges at most hourly, piggybacking on the reads that scan the table
+     * anyway. Housekeeping must never fail the read it rides on: a slow DELETE
+     * hitting a statement timeout, or a role that can read but not delete,
+     * would otherwise turn a user's conversation list into an error. The
+     * expired rows are still filtered out of every read regardless.
+     */
+    private purgeIfDue;
     private ensureReady;
     init(): Promise<void>;
     create(session: ChatSession): Promise<void>;
@@ -641,20 +885,57 @@ interface SkillGenerationInput {
      */
     toolDetails?: Array<{
         id: string;
-        description: string;
+        description: string; /** What the tool takes (`describeInputs`), when the inventory knows. */
+        inputs?: string;
     }>;
     /** Present when refining an existing skill rather than starting fresh. */
     instructions?: string;
 }
 declare function generateSkill(resolved: ResolvedConfig, input: SkillGenerationInput): Promise<WorkspaceSkill>;
 
+interface ConversationQuestion {
+    /** The full conversation log (see `conversationLog` in @frankieai/core), built server-side. */
+    log: string;
+    question: string;
+    /** Earlier questions and answers in this thread, oldest first. */
+    history: Array<{
+        role: "user" | "assistant";
+        text: string;
+    }>;
+}
+/** Answer one question about one conversation with the workspace's own model. */
+declare function askAboutConversation(resolved: ResolvedConfig, input: ConversationQuestion): Promise<string>;
+
+/** What a GitHub Actions OIDC token says about the run that minted it. */
+interface GithubRunClaims {
+    /** "owner/name" of the repository the workflow ran in. */
+    repository: string;
+    /** e.g. "refs/heads/main". */
+    ref: string;
+    /** The commit the run is for. */
+    sha: string;
+    /** "push", "workflow_dispatch", … */
+    eventName: string;
+}
+/**
+ * Verify a token GitHub Actions minted for a workflow run (`id-token: write`).
+ * It proves which repository and commit the request comes from without any
+ * secret stored in the repository: GitHub signs it, we check the signature
+ * against GitHub's published keys, the issuer, the audience and its expiry.
+ */
+declare function verifyGithubRunToken(token: string): Promise<GithubRunClaims>;
+
 interface ControlOptions {
     /** Immutable GitHub IDs configured by the platform operator, never by a client. */
     bootstrapSuperAdmins?: string[];
     generateSkill?: typeof generateSkill;
+    askAboutConversation?: typeof askAboutConversation;
+    verifyGithubRunToken?: typeof verifyGithubRunToken;
     store: ControlStore;
     /** Durable session store shared with the data plane when Postgres is configured. */
     sessions?: SessionStore;
+    /** Knowledge index shared with the data plane, so a dashboard-triggered ingest is what the docs-search tool reads. */
+    knowledge?: KnowledgeStore;
     /** Bearer token that gates the admin API. A stand-in for real user auth. */
     adminToken?: string;
     /**
@@ -679,6 +960,26 @@ interface ControlOptions {
  */
 declare function createControlApp(options: ControlOptions): Hono;
 
+/** Where and how to compute embeddings — an OpenAI-compatible `/embeddings` endpoint. */
+interface EmbeddingConfig {
+    endpoint: string;
+    apiKey: string;
+    model: string;
+}
+/**
+ * Embed a batch of texts. Sends them in bounded requests so a large ingest
+ * doesn't build one enormous body. Returns one vector per input, in order.
+ */
+declare function embedTexts(texts: string[], config: EmbeddingConfig, fetchImpl?: typeof fetch, batchSize?: number): Promise<number[][]>;
+
+/** Everything the retrieval tool needs, injected by the runner from the app. */
+interface KnowledgeDeps {
+    store: KnowledgeStore;
+    embedding: EmbeddingConfig;
+    /** Override the embed call in tests. */
+    embedImpl?: typeof embedTexts;
+}
+
 /**
  * The per-turn handle an API tool uses to run itself in the user's browser
  * instead of on Frankie's server. `available` says whether a live widget
@@ -713,7 +1014,23 @@ interface RunTurnParams {
     signal: AbortSignal;
     /** Called with the full transcript once the turn settles, to persist it. */
     onTranscript?: (messages: AgentMessage[]) => void;
+    /** Receives a human-escalation when the built-in escalation tool is called. */
+    onEscalation?: EscalationSink;
     onWarning?: (message: string, detail: Record<string, unknown>) => void;
+    /** Knowledge-base index + embedding config for the docs-search tool. */
+    knowledge?: KnowledgeDeps;
+    /**
+     * Pause every action that changes data until the user approves it. Set when
+     * the workspace asks for it and the chat can show the approval card.
+     */
+    confirmWrites?: boolean;
+    /** The user's answer to the action the previous turn paused. */
+    decision?: {
+        action: PendingAction;
+        approved: boolean;
+    };
+    /** Called when this turn pauses an action for approval, so the caller can keep it. */
+    onPendingAction?: (action: PendingAction) => void;
 }
 /**
  * Run one user turn and stream it back as widget-facing events.
@@ -733,6 +1050,8 @@ interface McpConnection {
         name: string;
         error: string;
     }>;
+    /** Tools that may change data: every tool its server doesn't mark `readOnlyHint`. */
+    writes: Set<string>;
     close(): Promise<void>;
 }
 interface ConnectMcpOptions {
@@ -779,6 +1098,11 @@ interface ApiToolSet {
     }>;
     /** One entry per source that built successfully, for chat-facing visibility. */
     apis: ApiToolInventory[];
+    /** Tools that change data (any method but GET), by tool name, for the approval card. */
+    writes: Map<string, {
+        method: string;
+        path: string;
+    }>;
 }
 /**
  * Turn a tenant's OpenAPI document into agent tools.
@@ -808,6 +1132,10 @@ interface CollectToolsOptions {
     accountApiUrl?: string;
     /** Browser channel for API sources marked `execution: "client"`. */
     clientBridge?: ClientToolBridge;
+    /** Knowledge-base index + embedding config for the docs-search tool. */
+    knowledge?: KnowledgeDeps;
+    /** Receives a human-escalation when the built-in escalation tool is called. */
+    onEscalation?: EscalationSink;
     onWarning?: (message: string, detail: Record<string, unknown>) => void;
 }
 interface CollectedTools {
@@ -819,6 +1147,14 @@ interface CollectedTools {
     }>;
     /** OpenAPI sources that built successfully this turn, for chat-facing visibility. */
     apis: ApiToolInventory[];
+    /**
+     * Tools that change data, by name, with the HTTP method and path when there
+     * is one. These ask the user before they run (`agent.confirmWrites`).
+     */
+    writes: Map<string, {
+        method?: string;
+        path?: string;
+    }>;
     close(): Promise<void>;
 }
 /**
@@ -851,11 +1187,8 @@ interface ForwardingConfig {
  */
 declare function buildForwardedHeaders(source: ForwardingConfig, session: ChatSession): Record<string, string>;
 
-/**
- * The runtime's own operating instructions, followed by whatever the tenant
- * configured. Host-supplied page context is fenced off as data: it comes from
- * a web page and must never be able to redirect the agent.
- */
-declare function buildSystemPrompt(config: FrankieConfig, session: ChatSession, availableTools?: string[]): string;
+declare function buildSystemPrompt(config: FrankieConfig, session: ChatSession, availableTools?: string[], options?: {
+    confirmWrites?: boolean;
+}): string;
 
 export { API_TOOL_PREFIX, type ApiToolSet, AuthError, type BuildApiToolsOptions, type ChatSession, type CollectToolsOptions, type CollectedTools, ConfigError, type ConnectMcpOptions, type ControlOptions, type ControlStore, type CreateAppOptions, FileTenantStore, type ForwardingConfig, MCP_TOOL_PREFIX, type McpConnection, type McpHostOptions, MemoryRateLimiter, MemorySessionStore, MemoryTenantStore, ModelResolutionError, OpenApiError, PostgresSessionStore, PostgresTenantStore, type PublicTenant, type Queryable, type RateLimiter, type ResolvedConfig, type ResolvedModel, type ResolvedStore, type ResolvedStores, type RunTurnParams, type SessionStore, SingleTenantStore, type TenantRecord, TenantRegistry, type TenantRuntime, type TenantStore, TokenService, type VerifiedUser, anonymousUser, applyEnvOverrides, buildApiTools, buildForwardedHeaders, buildSystemPrompt, collectTools, connectMcpTools, createControlApp, createFrankieApp, createMcpHostApp, isOriginAllowed, loadConfigFromFile, loadResolvedConfig, loadSpec, modelHasApi, newSessionId, resolveModel, resolveSecrets, resolveStores, resolveTenantStore, runTurn, safeEqual, toPublicTenant };