@frankieai/core 0.2.6 → 0.2.8

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  API_SYNC_WORKFLOW_PATH: () => API_SYNC_WORKFLOW_PATH,
   FIREWORKS_MODELS: () => FIREWORKS_MODELS,
   SKILL_TOOL_NAME: () => SKILL_TOOL_NAME,
   STANDARD_AGENT_IDS: () => STANDARD_AGENT_IDS,
@@ -30,12 +31,15 @@ __export(index_exports, {
   apiMethods: () => apiMethods,
   apiOperations: () => apiOperations,
   apiSourceSchema: () => apiSourceSchema,
+  apiSyncWorkflow: () => apiSyncWorkflow,
   approvedSkillTools: () => approvedSkillTools,
   assertNoCommittedFrankieKeys: () => assertNoCommittedFrankieKeys,
   authConfigSchema: () => authConfigSchema,
   brandingConfigSchema: () => brandingConfigSchema,
   canonicalJson: () => canonicalJson,
   compareApiDocuments: () => compareApiDocuments,
+  conversationLog: () => conversationLog,
+  conversationLogFileName: () => conversationLogFileName,
   defineFrankieConfig: () => defineFrankieConfig,
   describeTool: () => describeTool,
   draftSkill: () => draftSkill,
@@ -46,7 +50,9 @@ __export(index_exports, {
   insertImport: () => insertImport,
   installAgentIds: () => installAgentIds,
   installBranch: () => installBranch,
+  installPrompt: () => installPrompt,
   installTitle: () => installTitle,
+  isSafeRepositoryPath: () => isSafeRepositoryPath,
   knowledgeBaseSchema: () => knowledgeBaseSchema,
   knowledgeSourceSchema: () => knowledgeSourceSchema,
   limitsConfigSchema: () => limitsConfigSchema,
@@ -63,6 +69,7 @@ __export(index_exports, {
   operationId: () => operationId,
   parseFrankieConfig: () => parseFrankieConfig,
   personaEnvKey: () => personaEnvKey,
+  personaInstructions: () => personaInstructions,
   personaProfileSchema: () => personaProfileSchema,
   plainText: () => plainText,
   planHostedInstall: () => planHostedInstall,
@@ -75,6 +82,7 @@ __export(index_exports, {
   thinkingLevelSchema: () => thinkingLevelSchema,
   toolDescriptions: () => toolDescriptions,
   toolPolicySchema: () => toolPolicySchema,
+  userLabel: () => userLabel,
   validateApiDocument: () => validateApiDocument,
   widgetThemeSchema: () => widgetThemeSchema,
   withDependencies: () => withDependencies
@@ -532,7 +540,14 @@ var agentConfigSchema = import_zod2.z.object({
   maxBudgetUsd: import_zod2.z.number().positive().optional(),
   tools: toolPolicySchema.prefault({}),
   /** Show tool activity in the transcript. */
-  showToolActivity: import_zod2.z.boolean().default(true)
+  showToolActivity: import_zod2.z.boolean().default(true),
+  /**
+   * Ask the user before any action that changes data runs. The chat shows the
+   * action with Approve and Cancel; it runs only on Approve, with exactly the
+   * inputs shown. Reads never ask. Applies to chats from an SDK that can show
+   * the card; older SDK versions and headless callers run as before.
+   */
+  confirmWrites: import_zod2.z.boolean().default(true)
 });
 var authConfigSchema = import_zod2.z.object({
   /**
@@ -612,6 +627,18 @@ var personaProfileSchema = import_zod2.z.object({
    * sign in.
    */
   allowAnonymous: import_zod2.z.boolean().optional(),
+  /**
+   * What this agent helps with, in the team's own words ("pricing, plans,
+   * getting started"). The one thing a team needs to write; the agent's role,
+   * greeting and instructions come from defaults. It is added to the agent's
+   * instructions at runtime (see `personaInstructions`).
+   */
+  scope: import_zod2.z.string().trim().max(2e3).optional(),
+  /**
+   * Where to send people when the agent can't answer and it doesn't hand the
+   * chat to the team itself: a contact page (https) or an email (mailto:).
+   */
+  contactUrl: import_zod2.z.string().trim().max(500).regex(/^(?:https:\/\/[^\s]+|mailto:[^\s@]+@[^\s@]+)$/, "Use an https:// link or a mailto: address.").optional(),
   /**
    * Shallow-merged over the workspace branding. Each field is optional with no
    * default, so only the keys the persona sets override the workspace's — an
@@ -652,7 +679,13 @@ var frankieConfigSchema = import_zod2.z.object({
    * is the primary persona. Each entry resolves to its own one-agent config via
    * its own publishable key, so the data plane still sees one config per key.
    */
-  personas: import_zod2.z.array(personaProfileSchema).max(8).default([])
+  personas: import_zod2.z.array(personaProfileSchema).max(8).default([]),
+  /**
+   * Which agent a *resolved* config is: absent for the primary (product)
+   * agent, the persona's id (support, docs, …) otherwise. Set only by
+   * resolvePersonaConfig at request time; never stored.
+   */
+  agentId: import_zod2.z.string().min(1).max(64).optional()
 });
 var LEAKY_MODEL_MIGRATION = {
   "accounts/fireworks/models/kimi-k2p7-code": "accounts/fireworks/models/kimi-k3"
@@ -675,14 +708,24 @@ function resolvePersonaConfig(config, publishableKey) {
   return parseFrankieConfig({
     ...config,
     personas: [],
+    agentId: persona.id,
     branding: { ...config.branding, ...persona.branding ?? {} },
     auth: { ...config.auth, publishableKey: persona.publishableKey, allowAnonymous: persona.allowAnonymous ?? config.auth.allowAnonymous },
     pagePatterns: persona.pagePatterns,
-    agent: persona.agent,
+    agent: { ...persona.agent, systemPrompt: personaInstructions(persona) },
     features: persona.features,
     knowledgeBase: persona.knowledgeBase
   });
 }
+function personaInstructions(persona) {
+  const base = persona.agent.systemPrompt.trim();
+  const scope = persona.scope?.trim();
+  const handsOff = persona.features.escalation.enabled;
+  const contact = !handsOff ? persona.contactUrl?.trim() : void 0;
+  const fallback = handsOff ? "" : contact ? `When you can't answer from what you know, or someone asks for a person, say so briefly and point them to ${contact} to reach the team. Never guess.` : "When you can't answer from what you know, say so plainly. Never guess, and never promise that someone will follow up.";
+  const boundary = "Stay within this. If someone asks about something outside it, say briefly that it isn't something you can help with here" + (handsOff ? ", and offer to connect them with the team." : contact ? ", and share the contact link." : ".");
+  return [base, scope ? "What you help with, in the team's own words:\n" + scope + "\n\n" + boundary : "", fallback].filter(Boolean).join("\n\n");
+}
 function normalizeRoutePath(value) {
   let path = (value || "/").split(/[?#]/)[0].trim();
   if (!path.startsWith("/")) path = "/" + path;
@@ -1336,6 +1379,65 @@ function relativeImport(fromFile, module2) {
   return up === 0 ? `./${rel}` : rel;
 }
 
+// src/install-prompt.ts
+function installPrompt(options = {}) {
+  const workspace = options.workspaceId || "<workspace-id>";
+  const key = options.publishableKey || "<publishable-key>";
+  const anonymous = options.allowAnonymous ?? false;
+  const cli = "npx @frankieai/cli@latest setup --workspace " + workspace + " --key " + key + (anonymous ? " --anonymous" : "");
+  return `Add Frankie, an in-app AI assistant, to this app. Work in this repository only and keep the change small.
+
+## What Frankie is
+- The chat is a React component (@frankieai/react) that runs in this app's frontend.
+- The agent runs on Frankie's hosted cloud. Do not add a Frankie server, a model provider or any AI API key to this project.
+- Actions run in the user's browser against this app's own API, with the user's existing session. Do not add API credentials for Frankie.
+- Workspace ID: ${workspace}
+- Publishable key: ${key} (public, safe in the browser)
+- FRANKIE_JWT_SECRET is server-only. Never write its value anywhere, never print it, never commit it. Only reference it as an environment variable.
+
+## Steps
+1. Inspect the repository: the framework, the package manager, and how users sign in today (Auth.js/NextAuth, Firebase session cookies, Supabase, Clerk, a custom session\u2026). In a monorepo, pick the app users sign in to and tell me which one you chose.
+
+2. If it is a Next.js App Router app, use Frankie's installer instead of writing files by hand:
+   - Make sure the git tree is clean and the default branch is checked out.
+   - Preview: ${cli} --dry-run
+   - Monorepo: add --app <path-to-app>, for example --app apps/dashboard
+   - Then run it with --no-pr to write the files and commit them on a new branch.
+   - Read the generated FRANKIE_SETUP.md and app/api/frankie/token/route.ts. If the installer could not detect sign-in, implement getCurrentUser in lib/frankie-auth.ts using the app's existing session (see step 3b), and commit that too.
+
+3. Otherwise (any other React app), add it by hand:
+   a. Install @frankieai/react with the project's package manager.
+   b. Mount it once, at the root of the signed-in part of the app (a client component in frameworks that need one):
+      import { FrankieProvider, FrankieWidget } from "@frankieai/react";
+      import "@frankieai/react/styles.css";
+      <FrankieProvider publishableKey={/* the public key from env */}${anonymous ? "" : `
+        getUserToken={async () => {
+          const res = await fetch("/api/frankie/token", { method: "POST" });
+          return res.ok ? (await res.json()).token : undefined;
+        }}`}>
+        <FrankieWidget />
+      </FrankieProvider>
+      Read the key from a public environment variable using the framework's convention (NEXT_PUBLIC_FRANKIE_KEY, VITE_FRANKIE_KEY, \u2026).
+      If the app's API is on a different origin than its pages, also pass api={{ baseUrl: "<that origin>", credentials: "include" }}.${anonymous ? "" : `
+   c. Add a server endpoint POST /api/frankie/token on the app's own backend:
+      - Look up the signed-in user with the session code the app already uses. Never invent a new auth system.
+      - Not signed in: respond 401.
+      - Signed in: respond { "token": "<jwt>" }, a JWT signed HS256 with process.env.FRANKIE_JWT_SECRET, subject = the user's stable id, optional name and email claims, expiring in 5 minutes (the "jose" package works well).`}
+
+4. Add the variables to .env.example (or the project's equivalent) with empty values and a one-line comment each: the public key variable${anonymous ? "" : " and FRANKIE_JWT_SECRET (server only)"}. Do not put real values in any committed file.
+
+5. Run the project's typecheck, lint and build, and fix anything this change broke. Do not change unrelated code.
+
+6. Finish with a short summary:
+   - The files you added or changed, and the branch they are on.
+   - What I still need to do:
+     - Set the variables in my deployment and in my local env file. The values are in Frankie, under the workspace's Keys & settings.
+     - Add every origin the app runs on, including local development like http://localhost:3000, to Allowed sites in Frankie (Keys & settings).
+     - Push the branch and open a pull request titled "Install Frankie".
+     - Connect this repository on the workspace's Install tab so Frankie tracks the pull request.
+   - Anything you could not do, and why.`;
+}
+
 // src/sdk-updates.ts
 function sdkUpdateWorkflow(mode) {
   if (mode !== "manual" && mode !== "automatic") throw new Error("Invalid update mode.");
@@ -1602,6 +1704,7 @@ function oklchToHex(l, c, hDeg) {
 var NUMBER = String.raw`-?\d*\.?\d+`;
 var parts = (body) => body.replace(/\/.*$/, "").split(/[\s,]+/).filter(Boolean);
 function normalizeColor(raw) {
+  if (raw.length > 200) return void 0;
   const value = raw.trim().replace(/\s*!important$/, "").toLowerCase();
   let match = value.match(/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/);
   if (match) {
@@ -1628,20 +1731,57 @@ function normalizeColor(raw) {
   }
   return void 0;
 }
+function cssBlocks(source) {
+  const blocks = [];
+  let lastBrace = -1;
+  let open = -1;
+  let selectorStart = 0;
+  for (let index = 0; index < source.length; index++) {
+    const char = source.charCodeAt(index);
+    if (char === 123) {
+      selectorStart = lastBrace + 1;
+      open = index;
+      lastBrace = index;
+    } else if (char === 125) {
+      if (open !== -1) blocks.push([source.slice(selectorStart, open), source.slice(open + 1, index)]);
+      open = -1;
+      lastBrace = index;
+    }
+  }
+  return blocks;
+}
+function customProperty(declaration) {
+  const colon = declaration.indexOf(":");
+  if (colon === -1) return void 0;
+  const name = declaration.slice(0, colon).trim();
+  const value = declaration.slice(colon + 1).trim();
+  return name.length <= 100 && value.length <= 200 && /^--[\w-]+$/.test(name) && value ? [name, value] : void 0;
+}
 function rootVariables(css) {
   const vars = /* @__PURE__ */ new Map();
-  const source = css.replace(/\/\*[\s\S]*?\*\//g, "");
-  const blocks = /([^{}]*)\{([^{}]*)\}/g;
-  for (let block = blocks.exec(source); block; block = blocks.exec(source)) {
-    const selector = block[1].split(";").pop().trim();
+  const source = stripComments(css);
+  for (const [rawSelector, body] of cssBlocks(source)) {
+    const selector = rawSelector.split(";").pop().trim();
+    if (selector.length > 1e3) continue;
     if (!/(?:^|[\s,]):root\b(?![^,]*\.dark)|^@theme\b/.test(selector) || /\.dark|\[data-theme/.test(selector)) continue;
-    for (const declaration of block[2].split(";")) {
-      const found = declaration.match(/^\s*(--[\w-]+)\s*:\s*([\s\S]+?)\s*$/);
-      if (found && !vars.has(found[1])) vars.set(found[1], found[2]);
+    for (const declaration of body.split(";")) {
+      const found = customProperty(declaration);
+      if (found && !vars.has(found[0])) vars.set(found[0], found[1]);
     }
   }
   return vars;
 }
+function stripComments(css) {
+  let out = "";
+  for (let at = 0; ; ) {
+    const start = css.indexOf("/*", at);
+    if (start === -1) return out + css.slice(at);
+    out += css.slice(at, start);
+    const end = css.indexOf("*/", start + 2);
+    if (end === -1) return out;
+    at = end + 2;
+  }
+}
 function resolve(value, vars, depth = 0) {
   if (depth > 4) return void 0;
   const reference = value.match(/^(?:(hsla?|oklch|rgba?)\(\s*)?var\(\s*(--[\w-]+)\s*(?:,[^)]*)?\)\s*\)?$/i);
@@ -1657,6 +1797,61 @@ function radiusOption(value) {
   const rem = match[2] === "px" ? parseFloat(match[1]) / 16 : parseFloat(match[1]);
   return rem < 0.525 ? "0.35" : rem < 0.9 ? "0.7" : "1.1";
 }
+function saturationLightness(hex) {
+  const [r, g, b] = [1, 3, 5].map((at) => parseInt(hex.slice(at, at + 2), 16) / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const lightness = (max + min) / 2;
+  const saturation = max === min ? 0 : (max - min) / (1 - Math.abs(2 * lightness - 1));
+  return [saturation, lightness];
+}
+function isVivid(hex) {
+  if (!hex || !/^#[0-9a-f]{6}$/i.test(hex)) return false;
+  const [saturation, lightness] = saturationLightness(hex);
+  return saturation >= 0.35 && lightness >= 0.2 && lightness <= 0.8;
+}
+var BUTTON_SELECTOR = /(?:^|[\s,>+~])(?:button|\.btn[\w-]*|\.button[\w-]*|\[type=["']?submit["']?\]|\.primary[\w-]*)(?![\w-])/i;
+var PAGE_SELECTOR = /^(?:html|body|:root)(?:\s*,\s*(?:html|body|:root))*$/i;
+function pageColors(css, vars) {
+  const out = {};
+  const source = stripComments(css);
+  const declarations = (body) => body.split(";").filter((part) => part.length <= 300).map((part) => {
+    const colon = part.indexOf(":");
+    if (colon === -1) return void 0;
+    let value = part.slice(colon + 1).trim();
+    if (value.toLowerCase().endsWith("!important")) value = value.slice(0, -"!important".length).trim();
+    return [part.slice(0, colon).trim().toLowerCase(), value];
+  }).filter((entry) => Boolean(entry));
+  const colorOf = (value) => resolve(value, vars) ?? value.split(/\s+(?![^(]*\))/).map((part) => resolve(part, vars)).find(Boolean);
+  for (const [rawSelector, body] of cssBlocks(source)) {
+    const selector = rawSelector.split(";").pop().trim();
+    if (selector.length > 1e3 || /\.dark|\[data-theme|:hover|:active|:disabled|:focus/.test(selector)) continue;
+    if (PAGE_SELECTOR.test(selector)) {
+      for (const [property, value] of declarations(body)) {
+        if (!out.background && (property === "background" || property === "background-color")) out.background = colorOf(value);
+        if (!out.foreground && property === "color") out.foreground = colorOf(value);
+      }
+    } else if (!out.button && BUTTON_SELECTOR.test(selector) && !/ghost|outline|secondary|link|danger|red|cancel/i.test(selector)) {
+      for (const [property, value] of declarations(body)) {
+        if (property === "background" || property === "background-color" || /^--[\w-]*(?:bg|background)$/.test(property)) {
+          const color = colorOf(value);
+          if (isVivid(color)) {
+            out.button = color;
+            break;
+          }
+        }
+      }
+    }
+  }
+  const counts = /* @__PURE__ */ new Map();
+  const seen = /var\(\s*(--[\w-]+)\s*[,)]/g;
+  for (let match = seen.exec(source); match; match = seen.exec(source)) {
+    const color = resolve("var(" + match[1] + ")", vars);
+    if (isVivid(color)) counts.set(color, (counts.get(color) ?? 0) + 1);
+  }
+  out.mostUsed = [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+  return out;
+}
 var CSS_PRIORITY = [/(?:^|\/)app\/globals\.css$/, /(?:^|\/)styles\/globals\.css$/, /globals\.css$/, /\.css$/];
 var PRIMARY_VARS = ["--primary", "--color-primary", "--brand", "--color-brand", "--accent", "--color-accent"];
 function rank(path) {
@@ -1685,6 +1880,13 @@ function inferTheme(files, root = "") {
   for (const name of ["--background", "--color-background"]) if (vars.has(name)) set("background", resolve(vars.get(name), vars), varPath.get(name));
   for (const name of ["--foreground", "--color-foreground"]) if (vars.has(name)) set("foreground", resolve(vars.get(name), vars), varPath.get(name));
   if (vars.has("--radius")) set("radius", radiusOption(vars.get("--radius")), varPath.get("--radius"));
+  const guessedPrimary = [];
+  for (const path of cssFiles) {
+    const used = pageColors(files[path], vars);
+    set("background", used.background, path);
+    set("foreground", used.foreground, path);
+    guessedPrimary.push([used.button ?? used.mostUsed, path]);
+  }
   for (const path of Object.keys(files).filter((p) => inRoot(p) && /(?:^|\/)tailwind\.config\.[cm]?[jt]s$/.test(p)).sort()) {
     const source = files[path];
     for (const key of ["primary", "brand", "accent"]) {
@@ -1706,11 +1908,242 @@ function inferTheme(files, root = "") {
     } catch {
     }
   }
+  for (const [color, path] of guessedPrimary) set("primary", color, path);
   if (!theme.primary) return void 0;
   return { theme: { ...theme, primary: theme.primary }, sources };
 }
+
+// src/conversation-log.ts
+function userLabel(user) {
+  if (user.displayName?.trim()) return user.displayName.trim();
+  if (user.email?.trim()) return user.email.trim();
+  if (user.anonymous) return "Anonymous visitor";
+  return "Signed-in user \xB7 " + shortId(user.id);
+}
+function shortId(id) {
+  const plain = id.replace(/^[a-z]+[:_]/i, "");
+  return plain.length > 8 ? plain.slice(0, 8) : plain;
+}
+function conversationLog(conversation, options = {}) {
+  const { user, messages, agentMessages } = conversation;
+  const tools = messages.flatMap(toolsOf);
+  const failedTools = tools.filter((tool) => tool.status === "failed" || tool.status === "denied").length;
+  const out = [];
+  out.push("# Frankie conversation log", "");
+  out.push(
+    "Frankie is an AI assistant embedded in a customer's app. This log has the chat as the person saw it, then the agent's full trace: model messages, tool calls with their inputs, tool results and errors. Use it to explain what happened and why.",
+    ""
+  );
+  out.push("## Summary", "");
+  out.push(`- Conversation: ${conversation.title || "Untitled"} (\`${conversation.id}\`)`);
+  if (options.workspace) out.push(`- Workspace: ${options.workspace.name} (\`${options.workspace.id}\`)`);
+  out.push(`- Person: ${userLabel(user)} (\`${user.id}\`, ${user.anonymous ? "anonymous" : "signed in"})`);
+  if (options.agent) out.push(`- Agent: ${options.agent}`);
+  out.push(`- Started: ${iso(conversation.createdAt)}`);
+  out.push(`- Last active: ${iso(conversation.updatedAt)}`);
+  out.push(`- Messages: ${messages.length} \xB7 Actions: ${tools.length}${failedTools ? ` (${failedTools} failed)` : ""}`);
+  out.push(`- Cost: ${conversation.costUsd > 0 ? "$" + conversation.costUsd.toFixed(4) : "not reported"}`);
+  out.push(`- State: ${conversation.busy ? "still responding" : "finished"}`);
+  out.push("");
+  const escalations = conversation.escalations ?? [];
+  if (escalations.length) {
+    out.push("## Handed to the team", "");
+    for (const escalation of escalations) {
+      const contact = [escalation.name, escalation.email].filter(Boolean).join(", ");
+      out.push(`- ${iso(escalation.at)}: ${escalation.reason}${contact ? ` (left ${contact})` : ""}`);
+      if (escalation.summary) out.push(`  ${escalation.summary.replace(/\n+/g, " ")}`);
+    }
+    out.push("");
+  }
+  out.push("## Chat (what the person saw)", "");
+  if (!messages.length) out.push("_The chat widget saved no messages for this conversation._", "");
+  for (const message of messages) {
+    const item = record(message);
+    if (!item) continue;
+    const role = str(item.role) ?? "message";
+    const speaker = role === "user" ? `Person (${userLabel(user)})` : role === "assistant" ? options.agent ?? "Agent" : role;
+    const at = num(item.createdAt);
+    out.push(`### ${speaker}${at ? ` \xB7 ${iso(at)}` : ""}`, "");
+    const text = textOf(item);
+    if (text) out.push(clip(text), "");
+    for (const file of list(item.attachments)) out.push(`_Attached: ${str(file.name) ?? "file"} (${str(file.mimeType) ?? "unknown type"})_`);
+    const messageTools = toolsOf(item);
+    if (messageTools.length) {
+      out.push("Actions:");
+      for (const tool of messageTools) {
+        const detail = str(tool.error) ?? str(tool.detail);
+        out.push(`- [${str(tool.status) ?? "done"}] ${str(tool.label) ?? str(tool.name) ?? "tool"}${tool.name ? ` (\`${str(tool.name)}\`)` : ""}${detail ? `: ${oneLine(detail, 300)}` : ""}`);
+      }
+    }
+    const error = str(item.error);
+    if (error || item.status === "error") out.push("", `**This reply didn't finish:** ${error ?? "no error was recorded"}`);
+    out.push("");
+  }
+  out.push("## Agent trace (model messages, tool calls and results)", "");
+  if (!agentMessages.length) out.push("_The server recorded no agent messages for this conversation._", "");
+  agentMessages.forEach((message, index) => {
+    const item = record(message);
+    if (!item) return;
+    const role = str(item.role) ?? "message";
+    const at = num(item.timestamp);
+    if (role === "toolResult" || role === "tool_result") {
+      const failed = item.isError === true;
+      out.push(`### ${index + 1}. Tool result \xB7 \`${str(item.toolName) ?? "tool"}\`${failed ? " \xB7 ERROR" : ""}${at ? ` \xB7 ${iso(at)}` : ""}`, "");
+      out.push(fence(contentText(item.content)), "");
+      return;
+    }
+    const heading = [`${index + 1}. ${role === "assistant" ? "Assistant" : role === "user" ? "User" : role}`];
+    if (role === "assistant") {
+      if (str(item.model)) heading.push(str(item.model));
+      if (str(item.stopReason)) heading.push(`stop: ${str(item.stopReason)}`);
+    }
+    if (at) heading.push(iso(at));
+    out.push(`### ${heading.join(" \xB7 ")}`, "");
+    const errorMessage = str(item.errorMessage) ?? str(item.error);
+    if (errorMessage) out.push(`**Error:** ${errorMessage}`, "");
+    if (typeof item.content === "string") {
+      out.push(clip(item.content), "");
+      return;
+    }
+    const before = out.length;
+    for (const block of list(item.content)) {
+      const type = str(block.type);
+      if (type === "text") {
+        if (str(block.text)) out.push(clip(str(block.text)), "");
+      } else if (type === "thinking") {
+        if (str(block.thinking) && block.redacted !== true) out.push("Thinking:", fence(str(block.thinking)), "");
+      } else if (type === "toolCall") out.push(`Tool call \`${str(block.name) ?? "tool"}\`${str(block.id) ? ` (id \`${str(block.id)}\`)` : ""}:`, fence(json(block.arguments ?? {}), "json"), "");
+      else if (type === "image") out.push(`_[image: ${str(block.mimeType) ?? "image"}, not included]_`, "");
+      else if (type) out.push(`${type}:`, fence(json(stripLarge(block)), "json"), "");
+    }
+    if (out.length === before && !errorMessage) out.push("_(empty: no text and no tool calls)_", "");
+  });
+  return out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+function conversationLogFileName(conversation) {
+  const slug = (conversation.title || "conversation").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "conversation";
+  return `frankie-${slug}-${conversation.id.slice(0, 12)}.md`;
+}
+var BLOCK_LIMIT = 12e3;
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function list(value) {
+  return Array.isArray(value) ? value.map(record).filter((item) => Boolean(item)) : [];
+}
+function str(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function iso(at) {
+  const date = new Date(at);
+  return Number.isNaN(date.getTime()) ? "unknown time" : date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function toolsOf(message) {
+  return list(record(message)?.tools);
+}
+function textOf(item) {
+  if (typeof item.text === "string") return item.text;
+  if (typeof item.content === "string") return item.content;
+  return contentText(item.content);
+}
+function contentText(content) {
+  if (typeof content === "string") return content;
+  return list(content).map((block) => block.type === "image" ? `[image: ${str(block.mimeType) ?? "image"}, not included]` : str(block.text) ?? "").filter(Boolean).join("\n");
+}
+function stripLarge(block) {
+  const out = {};
+  for (const [key, value] of Object.entries(block)) {
+    if (/signature$/i.test(key)) continue;
+    out[key] = typeof value === "string" && value.length > 2e3 && /^[A-Za-z0-9+/=]+$/.test(value) ? `[${value.length} characters of binary data]` : value;
+  }
+  return out;
+}
+function json(value) {
+  try {
+    return JSON.stringify(value, null, 2) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+function clip(text, limit = BLOCK_LIMIT) {
+  return text.length > limit ? `${text.slice(0, limit)}
+\u2026 [${text.length - limit} more characters cut]` : text;
+}
+function oneLine(text, limit) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > limit ? `${flat.slice(0, limit)}\u2026` : flat;
+}
+function fence(text, lang = "") {
+  const body = clip(text || "(empty)");
+  const longest = Math.max(2, ...Array.from(body.matchAll(/`+/g), (match) => match[0].length));
+  const ticks = "`".repeat(longest + 1);
+  return `${ticks}${lang}
+${body}
+${ticks}`;
+}
+
+// src/api-sync.ts
+var API_SYNC_WORKFLOW_PATH = ".github/workflows/frankie-api-sync.yml";
+function apiSyncWorkflow(options) {
+  const { url, workspace, api, path } = options;
+  if (!/^https:\/\/[a-z0-9.-]+(?::\d+)?(?:\/[\w./-]*)?$/i.test(url) && !/^http:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?$/.test(url)) throw new Error("Invalid Frankie URL.");
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/i.test(workspace)) throw new Error("Invalid workspace id.");
+  if (!/^[\w.-]{1,80}$/.test(api)) throw new Error("Invalid API name.");
+  if (!isSafeRepositoryPath(path)) throw new Error("Choose a JSON or YAML file in the repository, like public/openapi.json.");
+  return template2.replaceAll("__PATH__", path).replaceAll("__URL__", url.replace(/\/+$/, "")).replaceAll("__WORKSPACE__", workspace).replaceAll("__API__", api);
+}
+function isSafeRepositoryPath(path) {
+  return /^[\w@.-]+(?:\/[\w@.-]+)*\.(?:json|ya?ml)$/i.test(path) && !path.split("/").some((part) => part === ".." || part === ".");
+}
+var template2 = String.raw`# Managed by Frankie: keeps Frankie's copy of your API description in step.
+# frankie-api-sync: __WORKSPACE__/__API__
+# Runs when __PATH__ changes on the default branch. No secrets: GitHub's OIDC
+# token proves which repository and commit this is. New or changed actions
+# stay off in Frankie until you allow them.
+name: Frankie API sync
+on:
+  push:
+    paths:
+      - "__PATH__"
+  workflow_dispatch:
+permissions:
+  contents: read
+  id-token: write
+concurrency:
+  group: frankie-api-sync
+  cancel-in-progress: true
+jobs:
+  sync:
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+        with:
+          persist-credentials: false
+          sparse-checkout: __PATH__
+          sparse-checkout-cone-mode: false
+      - name: Send the API description to Frankie
+        env:
+          FRANKIE_URL: "__URL__"
+          FRANKIE_WORKSPACE: "__WORKSPACE__"
+          FRANKIE_API: "__API__"
+          SPEC_PATH: "__PATH__"
+        run: |
+          test -f "$SPEC_PATH"
+          token="$(curl -sSf -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=frankie" | jq -r .value)"
+          jq -n --arg workspace "$FRANKIE_WORKSPACE" --arg api "$FRANKIE_API" --arg path "$SPEC_PATH" --rawfile spec "$SPEC_PATH" \
+            '{workspace: $workspace, api: $api, path: $path, spec: $spec}' > "$RUNNER_TEMP/frankie-api.json"
+          curl -sS --fail-with-body -X POST "$FRANKIE_URL/github/api-sync" \
+            -H "Authorization: Bearer $token" -H "content-type: application/json" \
+            --data "@$RUNNER_TEMP/frankie-api.json"
+`;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  API_SYNC_WORKFLOW_PATH,
   FIREWORKS_MODELS,
   SKILL_TOOL_NAME,
   STANDARD_AGENT_IDS,
@@ -1721,12 +2154,15 @@ function inferTheme(files, root = "") {
   apiMethods,
   apiOperations,
   apiSourceSchema,
+  apiSyncWorkflow,
   approvedSkillTools,
   assertNoCommittedFrankieKeys,
   authConfigSchema,
   brandingConfigSchema,
   canonicalJson,
   compareApiDocuments,
+  conversationLog,
+  conversationLogFileName,
   defineFrankieConfig,
   describeTool,
   draftSkill,
@@ -1737,7 +2173,9 @@ function inferTheme(files, root = "") {
   insertImport,
   installAgentIds,
   installBranch,
+  installPrompt,
   installTitle,
+  isSafeRepositoryPath,
   knowledgeBaseSchema,
   knowledgeSourceSchema,
   limitsConfigSchema,
@@ -1754,6 +2192,7 @@ function inferTheme(files, root = "") {
   operationId,
   parseFrankieConfig,
   personaEnvKey,
+  personaInstructions,
   personaProfileSchema,
   plainText,
   planHostedInstall,
@@ -1766,6 +2205,7 @@ function inferTheme(files, root = "") {
   thinkingLevelSchema,
   toolDescriptions,
   toolPolicySchema,
+  userLabel,
   validateApiDocument,
   widgetThemeSchema,
   withDependencies