@frankieai/server 0.2.6 → 0.2.7

package/dist/control-server.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   createControlApp
-} from "./chunk-EYR3BV7U.js";
+} from "./chunk-4XAOVSTL.js";
 import {
   createFrankieApp,
   resolveStores
-} from "./chunk-WEHJH4FL.js";
+} from "./chunk-TPVDQKD3.js";
 
 // src/control-server.ts
 import { serve } from "@hono/node-server";
@@ -17,10 +17,10 @@ async function main() {
     console.error("[frankie] Set FRANKIE_ADMIN_TOKEN to run the control plane.");
     process.exit(1);
   }
-  const { tenants: store, sessions, knowledge, describe } = await resolveStores();
+  const { tenants: store, sessions, knowledge, rateLimiter, turnSignals, describe } = await resolveStores();
   const app = new Hono();
   app.route("/", createControlApp({ store, sessions, knowledge }));
-  app.route("/", createFrankieApp({ tenants: store, sessions, knowledge }));
+  app.route("/", createFrankieApp({ tenants: store, sessions, knowledge, ...rateLimiter ? { rateLimiter } : {}, ...turnSignals ? { turnSignals } : {} }));
   serve({ fetch: app.fetch, port, hostname: host }, () => {
     console.log(
       JSON.stringify({

package/dist/control-server.js.map

@@ -1 +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 { Hono } from \"hono\";\nimport { createFrankieApp } from \"./app.js\";\nimport { createControlApp } from \"./control/app.js\";\nimport { resolveStores } 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 { tenants: store, sessions, knowledge, describe } = await resolveStores();\n  const app = new Hono();\n  app.route(\"/\", createControlApp({ store, sessions, knowledge }));\n  app.route(\"/\", createFrankieApp({ tenants: store, sessions, knowledge }));\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;AACtB,SAAS,YAAY;AAKrB,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,SAAS,OAAO,UAAU,WAAW,SAAS,IAAI,MAAM,cAAc;AAC9E,QAAM,MAAM,IAAI,KAAK;AACrB,MAAI,MAAM,KAAK,iBAAiB,EAAE,OAAO,UAAU,UAAU,CAAC,CAAC;AAC/D,MAAI,MAAM,KAAK,iBAAiB,EAAE,SAAS,OAAO,UAAU,UAAU,CAAC,CAAC;AAExE,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":[]}
+{"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 { Hono } from \"hono\";\nimport { createFrankieApp } from \"./app.js\";\nimport { createControlApp } from \"./control/app.js\";\nimport { resolveStores } 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 { tenants: store, sessions, knowledge, rateLimiter, turnSignals, describe } = await resolveStores();\n  const app = new Hono();\n  app.route(\"/\", createControlApp({ store, sessions, knowledge }));\n  app.route(\"/\", createFrankieApp({ tenants: store, sessions, knowledge, ...(rateLimiter ? { rateLimiter } : {}), ...(turnSignals ? { turnSignals } : {}) }));\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;AACtB,SAAS,YAAY;AAKrB,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,SAAS,OAAO,UAAU,WAAW,aAAa,aAAa,SAAS,IAAI,MAAM,cAAc;AACxG,QAAM,MAAM,IAAI,KAAK;AACrB,MAAI,MAAM,KAAK,iBAAiB,EAAE,OAAO,UAAU,UAAU,CAAC,CAAC;AAC/D,MAAI,MAAM,KAAK,iBAAiB,EAAE,SAAS,OAAO,UAAU,WAAW,GAAI,cAAc,EAAE,YAAY,IAAI,CAAC,GAAI,GAAI,cAAc,EAAE,YAAY,IAAI,CAAC,EAAG,CAAC,CAAC;AAE1J,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

@@ -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,122 +112,6 @@ declare function safeEqual(a: string, b: string): boolean;
 /** Stable pseudonymous id for an anonymous visitor. */
 declare function anonymousUser(seed: string): VerifiedUser;
 
-/** 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;
-    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;
-    /** Human hand-offs the agent made in this conversation (the escalation inbox). */
-    escalations?: EscalationRecord[];
-}
-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>;
-}
-
 declare class ModelResolutionError extends Error {
 }
 interface ResolvedModel {
@@ -319,34 +203,6 @@ declare class MemoryTenantStore implements TenantStore {
     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;
-    /** Knowledge-base index for the docs-search tool; in-memory when omitted. */
-    knowledge?: KnowledgeStore;
-    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;
-    /** Shared with the chat API; each request counts against the tenant's message budget. */
-    rateLimiter?: RateLimiter;
-}
-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
@@ -410,6 +266,13 @@ interface SuggestedThemeRecord {
     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;
@@ -444,6 +307,12 @@ interface TenantRecord {
      * 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;
@@ -513,6 +382,13 @@ interface PublicTenant {
     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. */
@@ -592,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`. */
@@ -651,6 +533,7 @@ declare class FileTenantStore implements ControlStore {
     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
@@ -718,11 +601,211 @@ declare class PostgresTenantStore implements ControlStore {
     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;
@@ -731,6 +814,9 @@ 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;
 }
 /**
@@ -759,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>;
@@ -796,10 +893,44 @@ interface SkillGenerationInput {
 }
 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;
@@ -888,6 +1019,18 @@ interface RunTurnParams {
     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.
@@ -907,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 {
@@ -953,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.
@@ -997,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>;
 }
 /**
@@ -1029,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 };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createControlApp
-} from "./chunk-EYR3BV7U.js";
+} from "./chunk-4XAOVSTL.js";
 import {
   ConfigError,
   applyEnvOverrides,
@@ -42,7 +42,7 @@ import {
   runTurn,
   safeEqual,
   toPublicTenant
-} from "./chunk-WEHJH4FL.js";
+} from "./chunk-TPVDQKD3.js";
 export {
   API_TOOL_PREFIX,
   AuthError,

package/dist/server.js

@@ -7,7 +7,7 @@ import {
   ModelResolutionError,
   createFrankieApp,
   resolveStores
-} from "./chunk-WEHJH4FL.js";
+} from "./chunk-TPVDQKD3.js";
 
 // src/server.ts
 import { serve } from "@hono/node-server";
@@ -21,7 +21,13 @@ async function main() {
     if (multiTenant) {
       const resolved = await resolveStores();
       describe = `multi-tenant (${resolved.describe})`;
-      app = createFrankieApp({ tenants: resolved.tenants, sessions: resolved.sessions, knowledge: resolved.knowledge });
+      app = createFrankieApp({
+        tenants: resolved.tenants,
+        sessions: resolved.sessions,
+        knowledge: resolved.knowledge,
+        ...resolved.rateLimiter ? { rateLimiter: resolved.rateLimiter } : {},
+        ...resolved.turnSignals ? { turnSignals: resolved.turnSignals } : {}
+      });
     } else {
       app = createFrankieApp({ resolved: await loadResolvedConfig() });
     }

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { serve } from \"@hono/node-server\";\nimport { createFrankieApp } from \"./app.js\";\nimport { ModelResolutionError } from \"./agent/models.js\";\nimport { ConfigError, loadResolvedConfig } from \"./config.js\";\nimport { resolveStores } from \"./control/resolve-store.js\";\n\nasync function main(): Promise<void> {\n  const port = Number(process.env[\"PORT\"] ?? 8080);\n  const host = process.env[\"HOST\"] ?? \"0.0.0.0\";\n\n  // Two shapes, one binary. With DATABASE_URL (or FRANKIE_TENANTS_DIR) set, this\n  // serves every tenant the control plane wrote, resolved by publishable key —\n  // the hosted, multi-tenant shape. Otherwise it loads one frankie.config.json,\n  // the self-hosted, single-tenant shape.\n  const multiTenant = Boolean(process.env[\"DATABASE_URL\"] || process.env[\"FRANKIE_TENANTS_DIR\"]);\n  let app;\n  let describe = \"single-tenant\";\n  try {\n    if (multiTenant) {\n      const resolved = await resolveStores();\n      describe = `multi-tenant (${resolved.describe})`;\n      app = createFrankieApp({ tenants: resolved.tenants, sessions: resolved.sessions, knowledge: resolved.knowledge });\n    } else {\n      app = createFrankieApp({ resolved: await loadResolvedConfig() });\n    }\n  } catch (error) {\n    if (error instanceof ConfigError || error instanceof ModelResolutionError) {\n      console.error(`[frankie] ${error.message}`);\n      process.exit(1);\n    }\n    throw error;\n  }\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: \"listening\",\n        mode: describe,\n        url: `http://${host}:${port}`,\n      }),\n    );\n  });\n}\n\nvoid main();\n"],"mappings":";;;;;;;;;;;;AACA,SAAS,aAAa;AAMtB,eAAe,OAAsB;AACnC,QAAM,OAAO,OAAO,QAAQ,IAAI,MAAM,KAAK,IAAI;AAC/C,QAAM,OAAO,QAAQ,IAAI,MAAM,KAAK;AAMpC,QAAM,cAAc,QAAQ,QAAQ,IAAI,cAAc,KAAK,QAAQ,IAAI,qBAAqB,CAAC;AAC7F,MAAI;AACJ,MAAI,WAAW;AACf,MAAI;AACF,QAAI,aAAa;AACf,YAAM,WAAW,MAAM,cAAc;AACrC,iBAAW,iBAAiB,SAAS,QAAQ;AAC7C,YAAM,iBAAiB,EAAE,SAAS,SAAS,SAAS,UAAU,SAAS,UAAU,WAAW,SAAS,UAAU,CAAC;AAAA,IAClH,OAAO;AACL,YAAM,iBAAiB,EAAE,UAAU,MAAM,mBAAmB,EAAE,CAAC;AAAA,IACjE;AAAA,EACF,SAAS,OAAO;AACd,QAAI,iBAAiB,eAAe,iBAAiB,sBAAsB;AACzE,cAAQ,MAAM,aAAa,MAAM,OAAO,EAAE;AAC1C,cAAQ,KAAK,CAAC;AAAA,IAChB;AACA,UAAM;AAAA,EACR;AAEA,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,MAAM;AAAA,QACN,KAAK,UAAU,IAAI,IAAI,IAAI;AAAA,MAC7B,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AACH;AAEA,KAAK,KAAK;","names":[]}
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { serve } from \"@hono/node-server\";\nimport { createFrankieApp } from \"./app.js\";\nimport { ModelResolutionError } from \"./agent/models.js\";\nimport { ConfigError, loadResolvedConfig } from \"./config.js\";\nimport { resolveStores } from \"./control/resolve-store.js\";\n\nasync function main(): Promise<void> {\n  const port = Number(process.env[\"PORT\"] ?? 8080);\n  const host = process.env[\"HOST\"] ?? \"0.0.0.0\";\n\n  // Two shapes, one binary. With DATABASE_URL (or FRANKIE_TENANTS_DIR) set, this\n  // serves every tenant the control plane wrote, resolved by publishable key —\n  // the hosted, multi-tenant shape. Otherwise it loads one frankie.config.json,\n  // the self-hosted, single-tenant shape.\n  const multiTenant = Boolean(process.env[\"DATABASE_URL\"] || process.env[\"FRANKIE_TENANTS_DIR\"]);\n  let app;\n  let describe = \"single-tenant\";\n  try {\n    if (multiTenant) {\n      const resolved = await resolveStores();\n      describe = `multi-tenant (${resolved.describe})`;\n      app = createFrankieApp({\n        tenants: resolved.tenants,\n        sessions: resolved.sessions,\n        knowledge: resolved.knowledge,\n        ...(resolved.rateLimiter ? { rateLimiter: resolved.rateLimiter } : {}),\n        ...(resolved.turnSignals ? { turnSignals: resolved.turnSignals } : {}),\n      });\n    } else {\n      app = createFrankieApp({ resolved: await loadResolvedConfig() });\n    }\n  } catch (error) {\n    if (error instanceof ConfigError || error instanceof ModelResolutionError) {\n      console.error(`[frankie] ${error.message}`);\n      process.exit(1);\n    }\n    throw error;\n  }\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: \"listening\",\n        mode: describe,\n        url: `http://${host}:${port}`,\n      }),\n    );\n  });\n}\n\nvoid main();\n"],"mappings":";;;;;;;;;;;;AACA,SAAS,aAAa;AAMtB,eAAe,OAAsB;AACnC,QAAM,OAAO,OAAO,QAAQ,IAAI,MAAM,KAAK,IAAI;AAC/C,QAAM,OAAO,QAAQ,IAAI,MAAM,KAAK;AAMpC,QAAM,cAAc,QAAQ,QAAQ,IAAI,cAAc,KAAK,QAAQ,IAAI,qBAAqB,CAAC;AAC7F,MAAI;AACJ,MAAI,WAAW;AACf,MAAI;AACF,QAAI,aAAa;AACf,YAAM,WAAW,MAAM,cAAc;AACrC,iBAAW,iBAAiB,SAAS,QAAQ;AAC7C,YAAM,iBAAiB;AAAA,QACrB,SAAS,SAAS;AAAA,QAClB,UAAU,SAAS;AAAA,QACnB,WAAW,SAAS;AAAA,QACpB,GAAI,SAAS,cAAc,EAAE,aAAa,SAAS,YAAY,IAAI,CAAC;AAAA,QACpE,GAAI,SAAS,cAAc,EAAE,aAAa,SAAS,YAAY,IAAI,CAAC;AAAA,MACtE,CAAC;AAAA,IACH,OAAO;AACL,YAAM,iBAAiB,EAAE,UAAU,MAAM,mBAAmB,EAAE,CAAC;AAAA,IACjE;AAAA,EACF,SAAS,OAAO;AACd,QAAI,iBAAiB,eAAe,iBAAiB,sBAAsB;AACzE,cAAQ,MAAM,aAAa,MAAM,OAAO,EAAE;AAC1C,cAAQ,KAAK,CAAC;AAAA,IAChB;AACA,UAAM;AAAA,EACR;AAEA,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,MAAM;AAAA,QACN,KAAK,UAAU,IAAI,IAAI,IAAI;AAAA,MAC7B,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AACH;AAEA,KAAK,KAAK;","names":[]}