@frankieai/server 0.1.0

package/dist/chunk-ZY4JZVCI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/control/app.ts"],"sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport { Hono } from \"hono\";\nimport type { Context } from \"hono\";\nimport { parseFrankieConfig } from \"@frankieai/core\";\nimport { safeEqual } from \"../auth.js\";\nimport { toPublicTenant, type ControlStore, type TenantRecord } from \"./store.js\";\n\nexport interface ControlOptions {\n  store: ControlStore;\n  /** Bearer token that gates the admin API. A stand-in for real user auth. */\n  adminToken?: string;\n  logger?: (event: Record<string, unknown>) => void;\n}\n\n/**\n * The control plane: create a tenant, hand back its keys, and manage how its\n * product connects — bring an MCP, point at an OpenAPI spec, or stay\n * knowledge-only. The dashboard and the setup CLI are thin clients over this.\n *\n * Admin auth here is a single shared token — deliberately the simplest thing\n * that is not \"nothing\", and the seam where real per-user accounts go.\n */\nexport function createControlApp(options: ControlOptions): Hono {\n  const { store } = options;\n  const adminToken = options.adminToken ?? process.env[\"FRANKIE_ADMIN_TOKEN\"];\n  const log = options.logger ?? ((event) => console.log(JSON.stringify({ ts: new Date().toISOString(), ...event })));\n\n  const app = new Hono();\n\n  app.use(\"/admin/*\", async (c, next) => {\n    if (!adminToken) {\n      return c.json({ error: \"Control plane is locked: set FRANKIE_ADMIN_TOKEN.\" }, 503);\n    }\n    const bearer = c.req.header(\"authorization\")?.replace(/^Bearer\\s+/i, \"\") ?? \"\";\n    if (!safeEqual(bearer, adminToken)) {\n      return c.json({ error: \"Unauthorized.\" }, 401);\n    }\n    await next();\n    return;\n  });\n\n  /* ------------------------------ create ------------------------------ */\n\n  /** The dashboard identifies the acting user with this header (e.g. \"github:42\"). */\n  const ownerOf = (c: Context): string | undefined => c.req.header(\"x-frankie-owner\") || undefined;\n\n  app.post(\"/admin/tenants\", async (c) => {\n    const body = (await readJson<CreateTenantBody>(c)) ?? {};\n    if (!body.name?.trim()) return c.json({ error: \"`name` is required.\" }, 400);\n    const ownerId = ownerOf(c);\n\n    // Ids are globally unique across owners, so two customers can both have an\n    // \"Acme\" without colliding: take the clean slug, or suffix it if taken.\n    let id = slug(body.name);\n    if (await store.get(id)) id = `${id}-${randomBytes(3).toString(\"hex\")}`;\n\n    const publishableKey = `pk_live_${randomBytes(12).toString(\"hex\")}`;\n    const jwtSecret = randomBytes(36).toString(\"base64\");\n    const sessionSecret = randomBytes(36).toString(\"base64\");\n\n    let config;\n    try {\n      config = parseFrankieConfig({\n        tenantId: id,\n        branding: { name: body.name },\n        agent: {\n          ...(body.goal ? { systemPrompt: body.goal } : {}),\n          ...(body.greeting ? { greeting: body.greeting } : {}),\n        },\n        auth: {\n          publishableKey,\n          allowedOrigins: body.allowedOrigins ?? [],\n          ...(body.allowAnonymous ? { allowAnonymous: true } : {}),\n        },\n      });\n    } catch (error) {\n      return c.json({ error: `Invalid tenant: ${(error as Error).message}` }, 400);\n    }\n\n    const now = new Date().toISOString();\n    const record: TenantRecord = {\n      id,\n      ...(ownerId ? { ownerId } : {}),\n      config,\n      jwtSecret,\n      sessionSecret,\n      createdAt: now,\n      updatedAt: now,\n    };\n    await store.put(record);\n    log({ level: \"info\", event: \"tenant_created\", tenant: id, ...(ownerId ? { owner: ownerId } : {}) });\n\n    // The JWT secret is shown exactly once: the customer's backend signs user\n    // tokens with it, and Frankie never needs to reveal it again.\n    return c.json(\n      {\n        tenant: toPublicTenant(record),\n        secrets: { publishableKey, jwtSecret },\n        next: \"Set FRANKIE_JWT_SECRET to the jwtSecret on your backend, then run `frankie init`.\",\n      },\n      201,\n    );\n  });\n\n  /* ------------------------------- read ------------------------------- */\n\n  // A tenant not owned by the caller is reported as absent, never as forbidden,\n  // so one owner can't probe another's tenant ids.\n  const own = async (c: Context): Promise<TenantRecord | null> => {\n    const id = c.req.param(\"id\");\n    const record = id ? await store.get(id) : null;\n    if (!record) return null;\n    const owner = ownerOf(c);\n    if (owner && record.ownerId && record.ownerId !== owner) return null;\n    return record;\n  };\n\n  app.get(\"/admin/tenants\", async (c) => {\n    return c.json({ tenants: (await store.list(ownerOf(c))).map(toPublicTenant) });\n  });\n\n  app.get(\"/admin/tenants/:id\", async (c) => {\n    const record = await own(c);\n    if (!record) return c.json({ error: \"No such tenant.\" }, 404);\n    return c.json({ tenant: toPublicTenant(record) });\n  });\n\n  /* ---------------------------- connection ---------------------------- */\n\n  /** Set how the tenant's product connects: MCP servers, an OpenAPI source, or neither. */\n  app.put(\"/admin/tenants/:id/connection\", async (c) => {\n    const record = await own(c);\n    if (!record) return c.json({ error: \"No such tenant.\" }, 404);\n\n    const body = (await readJson<ConnectionBody>(c)) ?? {};\n    let config;\n    try {\n      config = parseFrankieConfig({\n        ...record.config,\n        mcpServers: body.mcpServers ?? [],\n        apis: body.apis ?? [],\n      });\n    } catch (error) {\n      return c.json({ error: `Invalid connection: ${(error as Error).message}` }, 400);\n    }\n\n    const updated: TenantRecord = { ...record, config, updatedAt: new Date().toISOString() };\n    await store.put(updated);\n    log({ level: \"info\", event: \"tenant_connection_updated\", tenant: record.id });\n    return c.json({ tenant: toPublicTenant(updated) });\n  });\n\n  /** Set the sites allowed to open a chat for this tenant. */\n  app.put(\"/admin/tenants/:id/origins\", async (c) => {\n    const record = await own(c);\n    if (!record) return c.json({ error: \"No such tenant.\" }, 404);\n\n    const body = (await readJson<{ allowedOrigins?: string[] }>(c)) ?? {};\n    let config;\n    try {\n      config = parseFrankieConfig({\n        ...record.config,\n        auth: { ...record.config.auth, allowedOrigins: body.allowedOrigins ?? [] },\n      });\n    } catch (error) {\n      return c.json({ error: `Invalid origins: ${(error as Error).message}` }, 400);\n    }\n\n    const updated: TenantRecord = { ...record, config, updatedAt: new Date().toISOString() };\n    await store.put(updated);\n    return c.json({ tenant: toPublicTenant(updated) });\n  });\n\n  // Surface the real cause of an unhandled failure (usually a database\n  // connection error). The admin API is token-gated, so returning the message\n  // is safe and makes the dashboard show what actually went wrong.\n  app.onError((error, c) => {\n    const message = error instanceof Error ? error.message : \"Internal error.\";\n    log({ level: \"error\", event: \"control_error\", message });\n    return c.json({ error: `Control plane error: ${message}` }, 500);\n  });\n\n  return app;\n}\n\n/* -------------------------------- types --------------------------------- */\n\ninterface CreateTenantBody {\n  name?: string;\n  allowedOrigins?: string[];\n  goal?: string;\n  greeting?: string;\n  /** Let visitors chat without a host-signed token — for public onboarding pages. */\n  allowAnonymous?: boolean;\n}\n\ninterface ConnectionBody {\n  mcpServers?: unknown[];\n  apis?: unknown[];\n}\n\n/* -------------------------------- helpers -------------------------------- */\n\nasync function readJson<T>(c: Context): Promise<T | null> {\n  try {\n    return (await c.req.json()) as T;\n  } catch {\n    return null;\n  }\n}\n\nexport function slug(value: string): string {\n  return (\n    value\n      .toLowerCase()\n      .replace(/[^a-z0-9]+/g, \"-\")\n      .replace(/^-|-$/g, \"\")\n      .slice(0, 40) || \"tenant\"\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/control-server.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import {
+  createControlApp
+} from "./chunk-ZY4JZVCI.js";
+import {
+  resolveTenantStore
+} from "./chunk-ACXNDAOM.js";
+
+// src/control-server.ts
+import { serve } from "@hono/node-server";
+async function main() {
+  const port = Number(process.env["PORT"] ?? process.env["CONTROL_PORT"] ?? 8081);
+  const host = process.env["HOST"] ?? "0.0.0.0";
+  if (!process.env["FRANKIE_ADMIN_TOKEN"]) {
+    console.error("[frankie] Set FRANKIE_ADMIN_TOKEN to run the control plane.");
+    process.exit(1);
+  }
+  const { store, describe } = await resolveTenantStore();
+  const app = createControlApp({ store });
+  serve({ fetch: app.fetch, port, hostname: host }, () => {
+    console.log(
+      JSON.stringify({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        level: "info",
+        event: "control_listening",
+        store: describe,
+        url: `http://${host}:${port}`
+      })
+    );
+  });
+}
+void main();
+//# sourceMappingURL=control-server.js.map

package/dist/control-server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/control-server.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * The control plane, as its own process: the admin API the dashboard and the\n * setup CLI talk to. It writes tenants into FRANKIE_TENANTS_DIR — the same\n * directory the data-plane server reads — so what you create here is served\n * there with no further wiring.\n *\n *   FRANKIE_ADMIN_TOKEN=…  FRANKIE_TENANTS_DIR=./.frankie/tenants  \\\n *   pnpm --filter @frankieai/server start:control\n */\nimport { serve } from \"@hono/node-server\";\nimport { createControlApp } from \"./control/app.js\";\nimport { resolveTenantStore } from \"./control/resolve-store.js\";\n\nasync function main(): Promise<void> {\n  const port = Number(process.env[\"PORT\"] ?? process.env[\"CONTROL_PORT\"] ?? 8081);\n  const host = process.env[\"HOST\"] ?? \"0.0.0.0\";\n\n  if (!process.env[\"FRANKIE_ADMIN_TOKEN\"]) {\n    console.error(\"[frankie] Set FRANKIE_ADMIN_TOKEN to run the control plane.\");\n    process.exit(1);\n  }\n\n  const { store, describe } = await resolveTenantStore();\n  const app = createControlApp({ store });\n\n  serve({ fetch: app.fetch, port, hostname: host }, () => {\n    console.log(\n      JSON.stringify({\n        ts: new Date().toISOString(),\n        level: \"info\",\n        event: \"control_listening\",\n        store: describe,\n        url: `http://${host}:${port}`,\n      }),\n    );\n  });\n}\n\nvoid main();\n"],"mappings":";;;;;;;;;AAUA,SAAS,aAAa;AAItB,eAAe,OAAsB;AACnC,QAAM,OAAO,OAAO,QAAQ,IAAI,MAAM,KAAK,QAAQ,IAAI,cAAc,KAAK,IAAI;AAC9E,QAAM,OAAO,QAAQ,IAAI,MAAM,KAAK;AAEpC,MAAI,CAAC,QAAQ,IAAI,qBAAqB,GAAG;AACvC,YAAQ,MAAM,6DAA6D;AAC3E,YAAQ,KAAK,CAAC;AAAA,EAChB;AAEA,QAAM,EAAE,OAAO,SAAS,IAAI,MAAM,mBAAmB;AACrD,QAAM,MAAM,iBAAiB,EAAE,MAAM,CAAC;AAEtC,QAAM,EAAE,OAAO,IAAI,OAAO,MAAM,UAAU,KAAK,GAAG,MAAM;AACtD,YAAQ;AAAA,MACN,KAAK,UAAU;AAAA,QACb,KAAI,oBAAI,KAAK,GAAE,YAAY;AAAA,QAC3B,OAAO;AAAA,QACP,OAAO;AAAA,QACP,OAAO;AAAA,QACP,KAAK,UAAU,IAAI,IAAI,IAAI;AAAA,MAC7B,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AACH;AAEA,KAAK,KAAK;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,591 @@
+import { Hono } from 'hono';
+import { FrankieConfig, AuthConfig, FrankieServerEvent, McpServerConfig, ToolPolicy, ApiSourceConfig } from '@frankieai/core';
+import { AgentMessage, AgentTool } from '@earendil-works/pi-agent-core';
+import { JWTPayload } from 'jose';
+import { Models, Model, Api } from '@earendil-works/pi-ai';
+
+/**
+ * Secrets never live in the config file — the file names the env var that
+ * holds each one. `ResolvedConfig` is the config plus the resolved values.
+ */
+interface ResolvedConfig {
+    config: FrankieConfig;
+    secrets: {
+        /** HS256 secret the host signs end-user tokens with. Absent when using JWKS. */
+        jwtSecret?: string;
+        /** Signs Frankie's own session tokens. */
+        sessionSecret: string;
+        /** Key for the model provider named in `model.provider`. */
+        providerApiKey: string;
+    };
+}
+declare class ConfigError extends Error {
+}
+declare function loadConfigFromFile(path?: string): Promise<FrankieConfig>;
+/**
+ * A handful of fields have to move with the deployment rather than the config
+ * file — the model and the origin allowlist are what an operator most often
+ * wants to flip without a redeploy.
+ */
+declare function applyEnvOverrides(raw: Record<string, unknown>, env?: NodeJS.ProcessEnv): Record<string, unknown>;
+declare function resolveSecrets(config: FrankieConfig, env?: NodeJS.ProcessEnv): ResolvedConfig;
+declare function loadResolvedConfig(path?: string): Promise<ResolvedConfig>;
+
+/**
+ * Sliding-window counter. In-memory by default; swap in Redis for multi-instance
+ * deployments by implementing `RateLimiter`.
+ */
+interface RateLimiter {
+    /** Returns false when the caller is over budget. */
+    take(key: string, limit: number, windowSeconds: number): Promise<boolean>;
+}
+declare class MemoryRateLimiter implements RateLimiter {
+    private readonly hits;
+    private lastSweep;
+    take(key: string, limit: number, windowSeconds: number): Promise<boolean>;
+    /** Drop empty buckets occasionally so a long-lived process does not grow. */
+    private sweep;
+}
+
+interface VerifiedUser {
+    id: string;
+    displayName?: string;
+    email?: string;
+    anonymous: boolean;
+    /** Every claim from the host's token, for MCP forwarding and prompt context. */
+    claims: JWTPayload;
+}
+declare class AuthError extends Error {
+    readonly code: "unauthorized" | "forbidden_origin";
+    constructor(message: string, code?: "unauthorized" | "forbidden_origin");
+}
+/**
+ * Verifies the JWT the customer's backend mints for a signed-in end user, and
+ * issues/verifies Frankie's own short-lived session tokens.
+ */
+declare class TokenService {
+    private readonly auth;
+    private readonly sessionKey;
+    private readonly userKey?;
+    private jwks?;
+    constructor(auth: AuthConfig, secrets: {
+        sessionSecret: string;
+        jwtSecret?: string;
+    });
+    /** Verify a host-signed user token. Throws `AuthError` on any failure. */
+    verifyUserToken(token: string): Promise<VerifiedUser>;
+    /** Mint the bearer token the widget uses for the rest of the conversation. */
+    issueSessionToken(input: {
+        sessionId: string;
+        user: VerifiedUser;
+        tenantId: string;
+    }): Promise<{
+        token: string;
+        expiresAt: Date;
+    }>;
+    verifySessionToken(token: string): Promise<{
+        sessionId: string;
+        userId: string;
+        tenantId: string;
+    }>;
+}
+/**
+ * Exact-origin allowlist. Wildcards are deliberately unsupported: the widget
+ * runs on a page the customer controls, so the list is short and known.
+ * An empty list means "same-origin only", which is what a server mounted
+ * inside the host app wants.
+ */
+declare function isOriginAllowed(origin: string | undefined, allowed: readonly string[]): boolean;
+/** Constant-time string comparison for the publishable key check. */
+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;
+    /**
+     * The raw host-signed token, kept only so it can be forwarded to MCP servers
+     * the tenant has explicitly opted into. Never written to disk or logs.
+     */
+    userToken?: string;
+    /** Page context the host passed at session creation. */
+    context: Record<string, string | number | boolean | null>;
+    /**
+     * The conversation transcript. Frankie owns it outright — the agent loop is
+     * stateless between turns and is handed this array each time — which is what
+     * makes a session portable to a shared store, and exportable.
+     */
+    messages: AgentMessage[];
+    createdAt: number;
+    lastActiveAt: number;
+    messageCount: number;
+    costUsd: number;
+    /** Set while a turn is in flight, so a second concurrent turn is rejected. */
+    busy: boolean;
+}
+interface SessionStore {
+    create(session: ChatSession): Promise<void>;
+    get(id: string): Promise<ChatSession | undefined>;
+    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>;
+    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 {
+    models: Models;
+    model: Model<Api>;
+}
+/**
+ * Resolve the tenant's configured model against the provider catalogue.
+ *
+ * The catalogue already knows which wire API each model speaks — Kimi K2.6 and
+ * K2.7 on Fireworks answer the Anthropic Messages API, K3 the OpenAI
+ * completions API — so nothing here has to care, and swapping providers stays a
+ * config change.
+ */
+declare function resolveModel(config: FrankieConfig): ResolvedModel;
+/** Narrow a resolved model to a specific wire API, for callers that need it. */
+declare function modelHasApi<TApi extends Api>(model: Model<Api>, api: TApi): model is Model<TApi>;
+
+/**
+ * Everything a request handler needs to serve one tenant, built once and
+ * cached. The single-tenant server and the multi-tenant SaaS both run the same
+ * handlers; the only difference is where the `TenantRuntime` comes from.
+ */
+interface TenantRuntime {
+    config: FrankieConfig;
+    secrets: ResolvedConfig["secrets"];
+    tokens: TokenService;
+    models: ResolvedModel["models"];
+    model: ResolvedModel["model"];
+}
+/**
+ * Where per-tenant config comes from. One process serves many tenants by
+ * looking each one up by its publishable key at request time.
+ *
+ * The in-memory and single-tenant stores below are enough to run and test the
+ * data plane. A hosted deployment implements this against its own control
+ * plane — a database row per tenant, secrets from a vault — and nothing in the
+ * request path changes.
+ */
+interface TenantStore {
+    /** The resolved config for a publishable key, or null if no tenant owns it. */
+    byPublishableKey(key: string): Promise<ResolvedConfig | null>;
+}
+/**
+ * Turns a `TenantStore` into ready-to-serve `TenantRuntime`s, caching each
+ * tenant's `TokenService` and resolved model so the model catalogue is walked
+ * once per tenant rather than once per request.
+ */
+declare class TenantRegistry {
+    private readonly store;
+    private readonly cache;
+    constructor(store: TenantStore);
+    /**
+     * A registry over exactly one tenant. Builds the runtime eagerly so an
+     * invalid provider, model or secret fails at startup — the same contract the
+     * single-tenant server has always had — rather than on the first message.
+     */
+    static single(resolved: ResolvedConfig): TenantRegistry;
+    private build;
+    /**
+     * Resolve a publishable key to a tenant runtime, or null if the key is
+     * unknown. Building can throw (an invalid model in a tenant's config); the
+     * caller turns that into a 502 for that tenant alone, never a crash for the
+     * whole fleet.
+     */
+    resolve(publishableKey: string): Promise<TenantRuntime | null>;
+    /** Drop a cached runtime so the next request rebuilds it from the store. */
+    evict(publishableKey: string): void;
+}
+/** A store over a single resolved config — the self-hosted, one-tenant case. */
+declare class SingleTenantStore implements TenantStore {
+    private readonly resolved;
+    constructor(resolved: ResolvedConfig);
+    byPublishableKey(key: string): Promise<ResolvedConfig | null>;
+}
+/**
+ * An in-memory store indexed by publishable key. Good for tests and small
+ * fixed fleets; a real SaaS swaps this for its database without touching the
+ * request path.
+ */
+declare class MemoryTenantStore implements TenantStore {
+    private readonly byKey;
+    constructor(tenants?: ReadonlyArray<ResolvedConfig>);
+    /** Register (or replace) a tenant. Its publishable key is its lookup 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
+ * from the environment at resolve time, so a tenant record never carries it.
+ * The per-tenant secrets it does hold (the JWT verification secret the
+ * customer's backend signs with, and the session-token secret) live here for a
+ * self-hosted start; a hosted deployment swaps this file store for a vault.
+ */
+interface TenantRecord {
+    id: string;
+    /** Who owns this tenant — the dashboard user's stable id (e.g. "github:42"). */
+    ownerId?: string;
+    config: FrankieConfig;
+    jwtSecret?: string;
+    sessionSecret: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A tenant record with its secrets stripped — safe to return from the API. */
+interface PublicTenant {
+    id: string;
+    ownerId?: string;
+    name: string;
+    publishableKey: string;
+    allowedOrigins: string[];
+    allowAnonymous: boolean;
+    connection: "knowledge" | "mcp" | "openapi";
+    mcpServers: string[];
+    apis: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+declare function toPublicTenant(record: TenantRecord): PublicTenant;
+/**
+ * A `TenantStore` the control plane can also write to and list. The data plane
+ * only needs `byPublishableKey`; the control plane needs the rest. Both the
+ * file and Postgres stores implement this, so the admin API is written once
+ * against the interface.
+ */
+interface ControlStore extends TenantStore {
+    list(ownerId?: string): Promise<TenantRecord[]>;
+    get(id: string): Promise<TenantRecord | null>;
+    put(record: TenantRecord): Promise<void>;
+}
+/**
+ * The control plane's persistence, and at the same time a `TenantStore` the
+ * data plane can serve from — so what the dashboard writes, the agent reads.
+ *
+ * `MemoryTenantStore` is fine for tests; this one survives a restart by writing
+ * one JSON file per tenant under a directory. The provider key is injected from
+ * the environment at read time, keeping it out of the tenant files entirely.
+ */
+declare class FileTenantStore implements ControlStore {
+    private readonly dir;
+    private readonly providerKeyEnv;
+    private readonly env;
+    private index;
+    private byId;
+    private loaded;
+    constructor(options: {
+        dir: string;
+        providerKeyEnv?: string;
+        env?: NodeJS.ProcessEnv;
+    });
+    private load;
+    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>;
+}
+
+/**
+ * The minimal surface of a Postgres client (node-postgres `Pool` or a test
+ * double). Keeping the store to this interface means it never imports `pg`
+ * directly, so it runs against an in-memory Postgres in tests and a real one in
+ * production without changing a line.
+ */
+interface Queryable {
+    query(text: string, params?: unknown[]): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+}
+/**
+ * A `TenantStore` backed by Postgres — the production shape. The web app, the
+ * control plane and the data plane run as separate services (Vercel + Cloud
+ * Run) that share no filesystem, so tenants live in a database they all reach.
+ *
+ * One table, the full record as JSON with the two lookup keys pulled out as
+ * columns. The model provider key is still injected from the environment at
+ * read time and never written to the row.
+ */
+declare class PostgresTenantStore implements ControlStore {
+    private readonly db;
+    private readonly providerKeyEnv;
+    private readonly env;
+    private ready?;
+    constructor(options: {
+        db: Queryable;
+        providerKeyEnv?: string;
+        env?: NodeJS.ProcessEnv;
+    });
+    /**
+     * Create the table on first use, once. Lazy so the server can start listening
+     * before the database is reachable — a failed connection then surfaces on a
+     * request (logged, a 502) instead of crashing boot on Cloud Run.
+     */
+    private ensureReady;
+    /** Create the table if it isn't there yet. Safe to call repeatedly. */
+    init(): Promise<void>;
+    private parse;
+    byPublishableKey(key: string): Promise<ResolvedConfig | null>;
+    list(ownerId?: string): Promise<TenantRecord[]>;
+    get(id: string): Promise<TenantRecord | null>;
+    put(record: TenantRecord): Promise<void>;
+}
+
+interface ResolvedStore {
+    store: ControlStore;
+    describe: string;
+}
+interface ResolvedStores {
+    tenants: ControlStore;
+    sessions: SessionStore;
+    describe: string;
+}
+/**
+ * Both stores the data plane needs, sharing one Postgres pool when
+ * DATABASE_URL is set (so tenant config and chat transcripts live in the same
+ * database), or a file tenant store + in-memory sessions otherwise.
+ */
+declare function resolveStores(env?: NodeJS.ProcessEnv): Promise<ResolvedStores>;
+/**
+ * Pick the tenant store from the environment, so the same binary runs in every
+ * shape:
+ *
+ *   - DATABASE_URL set → Postgres, the production shape. The web app (Vercel),
+ *     the control plane and the data plane (Cloud Run) share no filesystem, so
+ *     tenants live in a database all three reach.
+ *   - otherwise → a file under FRANKIE_TENANTS_DIR, for a single host or local
+ *     development, where one persistent disk is shared.
+ */
+declare function resolveTenantStore(env?: NodeJS.ProcessEnv): Promise<ResolvedStore>;
+
+/**
+ * A `SessionStore` backed by Postgres, so a user's chat history survives a
+ * restart and is shared across instances — the hosted default. The whole
+ * `ChatSession` (transcript included) is stored as one JSON row keyed by id.
+ *
+ * A customer who would rather keep transcripts in their own store implements
+ * `SessionStore` against it and passes it to `createFrankieApp` — this class is
+ * just the batteries-included option.
+ */
+declare class PostgresSessionStore implements SessionStore {
+    private readonly db;
+    private readonly ttlMs;
+    private ready?;
+    constructor(options: {
+        db: Queryable;
+        ttlMs?: number;
+    });
+    /** Create the table on first use, once — lazy, so boot never blocks on the DB. */
+    private ensureReady;
+    init(): Promise<void>;
+    create(session: ChatSession): Promise<void>;
+    get(id: string): Promise<ChatSession | undefined>;
+    update(id: string, patch: Partial<ChatSession>): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+interface ControlOptions {
+    store: ControlStore;
+    /** Bearer token that gates the admin API. A stand-in for real user auth. */
+    adminToken?: string;
+    logger?: (event: Record<string, unknown>) => void;
+}
+/**
+ * The control plane: create a tenant, hand back its keys, and manage how its
+ * product connects — bring an MCP, point at an OpenAPI spec, or stay
+ * knowledge-only. The dashboard and the setup CLI are thin clients over this.
+ *
+ * Admin auth here is a single shared token — deliberately the simplest thing
+ * that is not "nothing", and the seam where real per-user accounts go.
+ */
+declare function createControlApp(options: ControlOptions): Hono;
+
+interface RunTurnParams {
+    config: FrankieConfig;
+    session: ChatSession;
+    message: string;
+    /** Provider API key, resolved from the env var the config names. */
+    apiKey: string;
+    /** Model and provider registry, resolved once at startup. */
+    model: Model<Api>;
+    models: Models;
+    signal: AbortSignal;
+    /** Called with the full transcript once the turn settles, to persist it. */
+    onTranscript?: (messages: AgentMessage[]) => void;
+    onWarning?: (message: string, detail: Record<string, unknown>) => void;
+}
+/**
+ * Run one user turn and stream it back as widget-facing events.
+ *
+ * The agent loop runs in this process: there is no subprocess and no
+ * translation shim, so the only thing between the browser and the provider is
+ * the mapping below.
+ */
+declare function runTurn(params: RunTurnParams): AsyncGenerator<FrankieServerEvent>;
+
+/** Tools are namespaced so one tenant's policy can name a server or a tool. */
+declare const MCP_TOOL_PREFIX = "mcp__";
+interface McpConnection {
+    tools: AgentTool[];
+    /** Servers that could not be reached, by name. */
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+    close(): Promise<void>;
+}
+interface ConnectMcpOptions {
+    servers: readonly McpServerConfig[];
+    session: ChatSession;
+    policy: ToolPolicy;
+    connectTimeoutMs?: number;
+    callTimeoutMs?: number;
+    onWarning?: (message: string, detail: Record<string, unknown>) => void;
+}
+/**
+ * Connect to the tenant's MCP servers and expose their tools to the agent.
+ *
+ * Connections are per turn rather than pooled. That costs one handshake per
+ * message, and buys three things worth more for an onboarding agent: a server
+ * restarting mid-conversation heals on the next turn, tool lists stay current,
+ * and no connection outlives the request that authorised it.
+ */
+declare function connectMcpTools(options: ConnectMcpOptions): Promise<McpConnection>;
+
+/** Generated API tools share the namespace shape of MCP tools. */
+declare const API_TOOL_PREFIX = "api__";
+declare class OpenApiError extends Error {
+}
+interface BuildApiToolsOptions {
+    sources: readonly ApiSourceConfig[];
+    session: ChatSession;
+    policy: ToolPolicy;
+    fetchImpl?: typeof fetch;
+    onWarning?: (message: string, detail: Record<string, unknown>) => void;
+}
+interface ApiToolSet {
+    tools: AgentTool[];
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/**
+ * Turn a tenant's OpenAPI document into agent tools.
+ *
+ * This is the third onboarding path: a customer who has no MCP server and does
+ * not want to write one points Frankie at their spec instead. The tools it
+ * produces are indistinguishable to the agent from MCP ones, and go through the
+ * same deny-by-default policy and the same identity forwarding.
+ */
+declare function buildApiTools(options: BuildApiToolsOptions): Promise<ApiToolSet>;
+interface OpenApiDoc {
+    servers?: Array<{
+        url?: string;
+    }>;
+    paths?: Record<string, unknown>;
+    components?: Record<string, unknown>;
+}
+declare function loadSpec(spec: string, fetchImpl?: typeof fetch): Promise<OpenApiDoc>;
+/**
+ * `/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;
+
+interface CollectToolsOptions {
+    config: FrankieConfig;
+    session: ChatSession;
+    fetchImpl?: typeof fetch;
+    onWarning?: (message: string, detail: Record<string, unknown>) => void;
+}
+interface CollectedTools {
+    tools: AgentTool[];
+    /** Sources that could not be reached or parsed, by name. */
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+    close(): Promise<void>;
+}
+/**
+ * Gather every tool the agent may use this turn, from both sources.
+ *
+ * A tenant can bring an MCP server, point at an OpenAPI document, or do both —
+ * the agent cannot tell the difference, and neither can the tool policy, which
+ * sees `mcp__<server>__<tool>` and `api__<name>__<operation>` in the same
+ * namespace.
+ *
+ * A source that fails is logged and skipped rather than failing the turn: one
+ * unreachable backend should not take the assistant down with it.
+ */
+declare function collectTools(options: CollectToolsOptions): Promise<CollectedTools>;
+
+/** The forwarding fields MCP servers and API sources have in common. */
+interface ForwardingConfig {
+    headers: Record<string, string>;
+    forwardUserTokenAs?: string | undefined;
+    forwardUserClaims: readonly string[];
+}
+/**
+ * Headers sent to a tenant's own backend, whether that is an MCP server or an
+ * HTTP API.
+ *
+ * `forwardUserTokenAs` is how the tenant's tools act *as* the signed-in user:
+ * their API authorises the call exactly as it would any other request from that
+ * person. It is opt-in per source precisely because it hands that source the
+ * user's identity token.
+ */
+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): 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, matchPath, modelHasApi, newSessionId, resolveModel, resolveSecrets, resolveStores, resolveTenantStore, runTurn, safeEqual, toPublicTenant };