@frankieai/core 0.2.0 → 0.2.2

package/dist/index.cjs

@@ -23,11 +23,15 @@ __export(index_exports, {
   activeSkills: () => activeSkills,
   agentConfigSchema: () => agentConfigSchema,
   apiCapabilitySchema: () => apiCapabilitySchema,
+  apiMethods: () => apiMethods,
+  apiOperations: () => apiOperations,
   apiSourceSchema: () => apiSourceSchema,
   approvedSkillTools: () => approvedSkillTools,
   assertNoCommittedFrankieKeys: () => assertNoCommittedFrankieKeys,
   authConfigSchema: () => authConfigSchema,
   brandingConfigSchema: () => brandingConfigSchema,
+  canonicalJson: () => canonicalJson,
+  compareApiDocuments: () => compareApiDocuments,
   defineFrankieConfig: () => defineFrankieConfig,
   describeTool: () => describeTool,
   draftSkill: () => draftSkill,
@@ -35,15 +39,18 @@ __export(index_exports, {
   featuresConfigSchema: () => featuresConfigSchema,
   frankieConfigSchema: () => frankieConfigSchema,
   limitsConfigSchema: () => limitsConfigSchema,
+  matchPath: () => matchPath,
   mcpServerSchema: () => mcpServerSchema,
   modelChoiceSchema: () => modelChoiceSchema,
   modelConfigSchema: () => modelConfigSchema,
+  operationId: () => operationId,
   parseFrankieConfig: () => parseFrankieConfig,
   planHostedInstall: () => planHostedInstall,
   sdkUpdateWorkflow: () => sdkUpdateWorkflow,
   skillSchema: () => skillSchema,
   thinkingLevelSchema: () => thinkingLevelSchema,
   toolPolicySchema: () => toolPolicySchema,
+  validateApiDocument: () => validateApiDocument,
   widgetThemeSchema: () => widgetThemeSchema
 });
 module.exports = __toCommonJS(index_exports);
@@ -106,7 +113,7 @@ var skillSchema = import_zod.z.object({
 function activeSkills(config, availableTools) {
   const approved = new Set(approvedSkillTools(config));
   const available = availableTools ? new Set(availableTools) : approved;
-  return config.skills.filter((skill) => skill.status === "published" && skill.tools.every((tool) => approved.has(tool) && available.has(tool)));
+  return config.skills.filter((skill) => skill.status === "published").map((skill) => ({ ...skill, tools: skill.tools.filter((tool) => approved.has(tool) && available.has(tool)) })).filter((skill) => skill.tools.length > 0);
 }
 function approvedSkillTools(config) {
   const candidates = [
@@ -147,10 +154,16 @@ var modelConfigSchema = import_zod2.z.object({
    */
   provider: import_zod2.z.string().min(1).default("fireworks"),
   /**
-   * Model id within that provider. The default is Kimi K2.7 on Fireworks,
-   * which serves a native Anthropic-Messages endpoint and a 262K window.
+   * Model id within that provider. The default is Kimi K3 on Fireworks, served
+   * over the OpenAI-completions API. Crucially for an embedded chat widget, that
+   * endpoint returns the model's reasoning in a separate `reasoning_content`
+   * field (surfaced as a thinking stream the client gates off), rather than
+   * inlining it in the visible text channel — so the model's private planning
+   * never leaks into the user-facing reply. The earlier Anthropic-Messages Kimi
+   * builds emitted that reasoning as plain text on Fireworks, which no marker or
+   * prompt reliably suppressed.
    */
-  model: import_zod2.z.string().default("accounts/fireworks/models/kimi-k2p7-code"),
+  model: import_zod2.z.string().default("accounts/fireworks/models/kimi-k3"),
   /** Env var holding the provider key. Never put the key in config itself. */
   apiKeyEnv: import_zod2.z.string().default("FIREWORKS_API_KEY"),
   /** Override the provider's base URL (self-hosted gateways, tests). */
@@ -224,7 +237,16 @@ var apiCapabilitySchema = import_zod2.z.object({
   operationId: import_zod2.z.string().min(1),
   method: import_zod2.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
   path: import_zod2.z.string().min(1),
-  summary: import_zod2.z.string().optional()
+  summary: import_zod2.z.string().optional(),
+  /**
+   * True when this is a write operation the spec requires auth for, but the
+   * source has no way to authorize it as the specific calling user — no
+   * forwarded user token or claim, only (at best) a static/shared credential.
+   * A configured `security` credential never clears this on its own: it
+   * authorizes every call the same way regardless of who is chatting, which
+   * is a backend gap to flag, not something a spec or credential change fixes.
+   */
+  authGap: import_zod2.z.boolean().default(false)
 });
 var apiSourceSchema = import_zod2.z.object({
   name: import_zod2.z.string().min(1).regex(/^[a-z0-9][a-z0-9_-]*$/i, "API source names must be alphanumeric with - or _"),
@@ -263,6 +285,17 @@ var apiSourceSchema = import_zod2.z.object({
   forwardUserTokenAs: import_zod2.z.string().optional(),
   /** Extra claims from the user token to forward as `x-frankie-<claim>`. */
   forwardUserClaims: import_zod2.z.array(import_zod2.z.string()).default([]),
+  /**
+   * Credentials for the spec's own `components.securitySchemes`, keyed by
+   * scheme name. Frankie applies each per-operation `security` requirement at
+   * the location and with the prefix the scheme declares (an `apiKey` scheme
+   * goes to its named header/query/cookie; an `http` `bearer` or `oauth2`
+   * scheme becomes an `Authorization: Bearer` header; `http` `basic` takes a
+   * `user:pass` value and is base64-encoded automatically). Without this, a
+   * spec with per-operation auth falls back to the source's static `headers`
+   * for every operation, which is often wrong for at least some of them.
+   */
+  security: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.string()).default({}),
   /** Per-call timeout. */
   timeoutMs: import_zod2.z.number().int().positive().default(3e4),
   /** Response bodies longer than this are truncated before the model sees them. */
@@ -348,8 +381,16 @@ var frankieConfigSchema = import_zod2.z.object({
   /** Opt-in end-user chat capabilities (attachments, model picker). */
   features: featuresConfigSchema
 });
+var LEAKY_MODEL_MIGRATION = {
+  "accounts/fireworks/models/kimi-k2p7-code": "accounts/fireworks/models/kimi-k3"
+};
 function parseFrankieConfig(input) {
-  return frankieConfigSchema.parse(input);
+  const config = frankieConfigSchema.parse(input);
+  if (config.model.provider === "fireworks") {
+    const migrated = LEAKY_MODEL_MIGRATION[config.model.model];
+    if (migrated) config.model.model = migrated;
+  }
+  return config;
 }
 function defineFrankieConfig(config) {
   return config;
@@ -387,7 +428,7 @@ function planHostedInstall(input) {
   const tokenPath = appRoot + "api/frankie/token/route.ts";
   const needsAuthSetup = !workspace.allowAnonymous && !files[tokenPath] && !firebase && !authJs;
   if (needsAuthSetup) notes.push("Connect getCurrentUser in the generated token endpoint to your server session. It rejects requests until configured.");
-  pkg.dependencies = { ...pkg.dependencies, "@frankieai/react": pkg.dependencies["@frankieai/react"] ?? "^0.2.0", ...!workspace.allowAnonymous ? { jose: pkg.dependencies.jose ?? "^6.0.11" } : {} };
+  pkg.dependencies = { ...pkg.dependencies, "@frankieai/react": pkg.dependencies["@frankieai/react"] ?? "^0.2.1", ...!workspace.allowAnonymous ? { jose: pkg.dependencies.jose ?? "^6.0.11" } : {} };
   out.set(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
   const authProp = workspace.allowAnonymous ? "" : " getUserToken={getUserToken}";
   const shared = `import { FrankieProvider, FrankieWidget, FrankieChatPage } from "@frankieai/react";
@@ -494,29 +535,34 @@ export async function POST() {
     } catch {
     }
   }
+  const middlewareMatchers = nextMiddlewareMatchers(files, sourceRoot, root);
   const paths = {};
-  if (!doc) for (const [file, content] of Object.entries(files)) {
+  let withheld = 0;
+  for (const [file, content] of Object.entries(files)) {
     if (/\.(test|spec)\.[tj]sx?$/.test(file)) continue;
     const nextRoute = file.match(/(?:^|\/)app(\/.*)\/route\.[tj]s$/);
     if (nextRoute) {
       const path = nextRoute[1].replace(/\/\([^/]+\)/g, "").replace(/\[([^\]]+)\]/g, "{$1}");
       if (path.includes("...") || /\/(?:auth|frankie)(?:\/|$)/.test(path)) continue;
-      for (const method of ["GET"]) {
-        if (new RegExp("export\\s+(?:(?:async\\s+)?function\\s+" + method + "\\b|(?:const|let)\\s+" + method + "\\s*=)").test(content))
-          addInstallOperation(paths, method, path, file);
+      const guarded = matchesAnyMatcher(middlewareMatchers, path);
+      for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE"]) {
+        if (new RegExp("export\\s+(?:(?:async\\s+)?function\\s+" + method + "\\b|(?:const|let)\\s+" + method + "\\s*=)").test(content)) {
+          if (!addInstallOperation(paths, method, path, file, guarded)) withheld += 1;
+        }
       }
     } else if (/\.[tj]s$/.test(file) && /(?:routes?|api)\//.test(file)) {
-      for (const match of content.matchAll(/\b(?:app|router|fastify)\.(get|post|put|patch|delete)(?:\s*<[^;]{1,1600}?>)?\s*\(\s*["']([^"']+)["']/g))
-        addInstallOperation(paths, match[1].toUpperCase(), match[2].replace(/:([A-Za-z0-9_]+)/g, "{$1}"), file);
+      for (const match of content.matchAll(/\b(?:app|router|fastify)\.(get|post|put|patch|delete)(?:\s*<[^;]{1,1600}?>)?\s*\(\s*["']([^"']+)["'](\s*,\s*[A-Za-z_$][\w$]*\s*,)?/g))
+        if (!addInstallOperation(paths, match[1].toUpperCase(), match[2].replace(/:([A-Za-z0-9_]+)/g, "{$1}"), file, Boolean(match[3]))) withheld += 1;
     }
   }
-  doc ??= { openapi: "3.0.3", info: { title: workspace.name + " API", version: "1.0.0", description: "Read-only generated route inventory. Review schemas, authorization, and the deployed origin before enabling tools." }, paths };
-  doc = { ...doc, paths: Object.fromEntries(Object.entries(doc.paths).filter(([, item]) => item.get).map(([path, item]) => [path, { ...item.parameters ? { parameters: item.parameters } : {}, get: item.get }])) };
+  doc ??= { openapi: "3.0.3", info: { title: workspace.name + " API", version: "1.0.0", description: "Generated route inventory. Review schemas, authorization, and the deployed origin before enabling tools." }, paths };
+  for (const [path, item] of Object.entries(paths)) doc.paths[path] = { ...item, ...doc.paths[path] };
   const specPath = root + "public/frankie.openapi.json";
   const operationCount = Object.values(doc.paths).reduce((n, item) => n + Object.keys(item).filter((m) => /^(get|post|put|patch|delete)$/.test(m)).length, 0);
   out.set(specPath, JSON.stringify(doc, null, 2) + "\n");
   if (!operationCount) notes.push("No supported API routes detected. The OpenAPI draft has no operations; add the real schema before connecting tools.");
-  notes.push("Generated OpenAPI is read-only (GET only). Add write operations only to a reviewed, user-authorized schema.");
+  if (withheld) notes.push(`Withheld ${withheld} newly discovered write operation(s) with no detected authorization guard (an Express/Fastify middleware argument, or a Next.js middleware.ts matcher covering the route). Add them to the spec yourself once they're protected.`);
+  notes.push("Generated OpenAPI includes read and write routes. Review schemas before approving tools; new connections still default to GET-only access.");
   notes.push("Verify the public spec URL is reachable without dashboard authentication before connecting it.");
   notes.push("The token endpoint issues a signed user JWT, but your product API must validate it and enforce user/resource permissions before exposing tools.");
   const envPath = root + ".env.example";
@@ -530,7 +576,7 @@ Workspace: ${workspace.name}
 ${workspace.allowAnonymous ? "" : "2. Add FRANKIE_JWT_SECRET from this workspace to the server hosting /api/frankie/token. Never commit the value.\n"}3. Run your package manager and commit the updated lockfile (for pnpm: pnpm install --lockfile-only). The remote GitHub installer cannot safely synthesize a lockfile.
 4. Confirm https://YOUR_APP/frankie.openapi.json is public. If your Next.js middleware protects all paths, explicitly bypass /frankie.openapi.json before connecting it.
 5. Open ${chatPath}. It is created inside the detected authenticated dashboard group when one exists; add its link to the host sidebar during review.
-6. Connect https://YOUR_APP/frankie.openapi.json in Frankie \u2192 Tools & MCP. The generated document contains only read-only GET operations.
+6. Connect https://YOUR_APP/frankie.openapi.json in Frankie \u2192 Tools & MCP. The document includes read and write routes; approve tools and choose access limits separately.
 7. Forwarding sends the Frankie-signed JWT. Your API must validate it and enforce user/resource permissions. It is not automatically interchangeable with a Firebase or OAuth access token.
 8. Add NEXT_PUBLIC_FRANKIE_KEY to every frontend deployment environment (Preview and Production). ${workspace.allowAnonymous ? "" : "Add FRANKIE_JWT_SECRET only to the server environment running /api/frankie/token; never expose it to the browser.\n"}9. Review conversations in Workspace \u2192 Chat sessions.
 
@@ -542,8 +588,10 @@ ${notes.map((n) => "- " + n).join("\n")}
   assertNoCommittedFrankieKeys(planned);
   return { files: planned, root, chatPath, specPath, operationCount, needsAuthSetup, notes };
 }
-function addInstallOperation(paths, method, path, file) {
-  if (method !== "GET" || path.includes("*") || !path.startsWith("/") || /\/(?:auth|frankie)(?:\/|$)/.test(path)) return;
+var WRITE_METHODS = /* @__PURE__ */ new Set(["post", "put", "patch", "delete"]);
+function addInstallOperation(paths, method, path, file, guarded) {
+  if (path.includes("*") || !path.startsWith("/") || /\/(?:auth|frankie)(?:\/|$)/.test(path)) return true;
+  if (WRITE_METHODS.has(method.toLowerCase()) && !guarded) return false;
   (paths[path] ??= {})[method.toLowerCase()] = {
     operationId: (method.toLowerCase() + "_" + path).replace(/[^a-zA-Z0-9_]+/g, "_"),
     summary: method + " " + path,
@@ -552,6 +600,32 @@ function addInstallOperation(paths, method, path, file) {
     responses: { "200": { description: "Successful response" } },
     "x-frankie-review-required": true
   };
+  return true;
+}
+function nextMiddlewareMatchers(files, sourceRoot, root) {
+  const candidates = [.../* @__PURE__ */ new Set([sourceRoot + "middleware.ts", sourceRoot + "middleware.js", root + "middleware.ts", root + "middleware.js"])];
+  for (const candidate of candidates) {
+    const content = files[candidate];
+    if (typeof content !== "string") continue;
+    const config = content.match(/export\s+const\s+config\s*=\s*\{([^}]*)\}/);
+    if (!config) continue;
+    const matcher = config[1].match(/matcher\s*:\s*(\[[^\]]*\]|["'`][^"'`]*["'`])/);
+    if (!matcher) return [];
+    const raw = matcher[1];
+    return raw.startsWith("[") ? [...raw.matchAll(/["'`]([^"'`]+)["'`]/g)].map((m) => m[1]) : [raw.slice(1, -1)];
+  }
+  return [];
+}
+function matchesAnyMatcher(matchers, path) {
+  return matchers.some((pattern) => {
+    if (/[()|]/.test(pattern)) return false;
+    const glob = pattern.replace(/:[A-Za-z0-9_]+\*/g, "**").replace(/:[A-Za-z0-9_]+\+?/g, "*");
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const trailingDeep = escaped.endsWith("/**");
+    const body = trailingDeep ? escaped.slice(0, -3) : escaped;
+    const regexBody = body.split("**").map((chunk) => chunk.replace(/\*/g, "[^/]*")).join(".*") + (trailingDeep ? "(?:/.*)?" : "");
+    return new RegExp(`^${regexBody}$`).test(path);
+  });
 }
 
 // src/sdk-updates.ts
@@ -578,20 +652,20 @@ jobs:
     outputs:
       base: $GH steps.base.outputs.sha }}
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
         with:
           persist-credentials: false
       - id: base
         run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444
         with:
-          node-version: 22
+          node-version: 24
       - name: Install pinned pnpm
         run: npm install --global --ignore-scripts pnpm@10.33.0
       - name: Prepare SDK and lockfile together
         run: |
           test -f pnpm-lock.yaml
-          pnpm --recursive --include-workspace-root update '@frankieai/react@latest' '@frankieai/core@latest' '@frankieai/cli@latest' '@frankieai/server@latest' --lockfile-only --ignore-scripts --ignore-pnpmfile
+          pnpm --recursive --include-workspace-root update '@frankieai/react@latest' '@frankieai/core@latest' '@frankieai/cli@latest' '@frankieai/server@latest' --lockfile-only --ignore-scripts --ignore-pnpmfile --config.manage-package-manager-versions=false --config.package-manager-strict-version=false
       - name: Package allowlisted changes
         run: |
           node --input-type=module <<'NODE'
@@ -607,7 +681,7 @@ jobs:
           mkdirSync('frankie-update-artifact', {recursive:true});
           writeFileSync('frankie-update-artifact/changes.json', JSON.stringify(files));
           NODE
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: frankie-sdk-update
           path: frankie-update-artifact/changes.json
@@ -621,11 +695,11 @@ jobs:
       pull-requests: write
     steps:
       # Separate runner: no checkout, repository hooks, install scripts, or builds.
-      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
         with:
           name: frankie-sdk-update
           path: artifact
-      - uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b
+      - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
         env:
           BASE_SHA: $GH needs.prepare.outputs.base }}
         with:
@@ -642,6 +716,7 @@ jobs:
             if (current.data.object.sha !== base) throw Error('Default branch changed. Run the updater again.');
             const existing = await github.paginate(github.rest.pulls.list, {owner,repo,state:'open',per_page:100});
             if (existing.some(pr => pr.head.repo?.full_name === owner + '/' + repo && pr.head.ref.startsWith('frankie/sdk-update-'))) { core.notice('An SDK update PR already exists; review it first.'); return; }
+            const canonical = value => Array.isArray(value) ? '[' + value.map(canonical).join(',') + ']' : value && typeof value === 'object' ? '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}' : JSON.stringify(value);
             const clean = value => {
               const copy = JSON.parse(JSON.stringify(value));
               for (const group of ['dependencies','devDependencies','optionalDependencies']) {
@@ -649,6 +724,7 @@ jobs:
               }
               return copy;
             };
+            let sdkChanged = false;
             const seen = new Set();
             for (const file of files) {
               if (!file || typeof file.path !== 'string' || typeof file.content !== 'string' || seen.has(file.path)) throw Error('Invalid update file');
@@ -659,14 +735,16 @@ jobs:
                 const original = await github.rest.repos.getContent({owner,repo,path:file.path,ref:base});
                 const before = JSON.parse(Buffer.from(original.data.content, 'base64').toString());
                 const after = JSON.parse(file.content);
-                if (JSON.stringify(clean(before)) !== JSON.stringify(clean(after))) throw Error('Non-SDK manifest change');
+                if (canonical(clean(before)) !== canonical(clean(after))) throw Error('Non-SDK manifest change in ' + file.path);
                 for (const group of ['dependencies','devDependencies','optionalDependencies']) {
                   const sdkKeys = value => Object.keys(value[group] || {}).filter(key => key.startsWith('@frankieai/')).sort();
                   if (JSON.stringify(sdkKeys(before)) !== JSON.stringify(sdkKeys(after))) throw Error('SDK dependency added or removed');
+                  if (sdkKeys(after).some(key => before[group][key] !== after[group][key])) sdkChanged = true;
                   for (const [key, value] of Object.entries(after[group] || {})) if (key.startsWith('@frankieai/') && !/^[~^]?\d+\.\d+\.\d+$/.test(value)) throw Error('Only stable SDK releases are supported');
                 }
               }
             }
+            if (!sdkChanged) { core.notice('Frankie SDK versions are unchanged; no formatting-only update PR is needed.'); return; }
             if (!seen.has('pnpm-lock.yaml')) throw Error('SDK update must include the lockfile');
             const parent = await github.rest.git.getCommit({owner,repo,commit_sha:base});
             const tree = await github.rest.git.createTree({owner,repo,base_tree:parent.data.tree.sha,tree:files.map(f => ({...f,mode:'100644',type:'blob'}))});
@@ -676,16 +754,132 @@ jobs:
             await github.rest.git.createRef({owner,repo,ref:'refs/heads/' + branch,sha:commit.data.sha});
             await github.rest.pulls.create({owner,repo,head:branch,base:context.payload.repository.default_branch,draft:true,title:'Update Frankie SDK',body:'Updates the SDK and pnpm lockfile together. No auto-merge. Review release notes and breaking changes, run CI, and test signed-in chat and tool authorization. PRs made with GITHUB_TOKEN may need a maintainer to trigger CI; this workflow does not bypass that protection.'});
 `;
+
+// src/openapi-review.ts
+var apiMethods = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+function canonicalJson(value) {
+  if (Array.isArray(value)) return "[" + value.map(canonicalJson).join(",") + "]";
+  if (value && typeof value === "object") return "{" + Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => JSON.stringify(k) + ":" + canonicalJson(v)).join(",") + "}";
+  return JSON.stringify(value) ?? "null";
+}
+function validateApiDocument(value) {
+  const doc = value;
+  if (!doc || typeof doc !== "object" || !/^3\.(0|1)\./.test(doc.openapi) || !doc.paths || typeof doc.paths !== "object" || Array.isArray(doc.paths)) throw new Error("Use an OpenAPI 3.0 or 3.1 document with a paths object.");
+  const ids = /* @__PURE__ */ new Set();
+  const walk = (node, depth = 0) => {
+    if (depth > 80) throw new Error("Spec nesting is too deep.");
+    if (!node || typeof node !== "object") return;
+    for (const [key, item] of Object.entries(node)) {
+      if (["__proto__", "prototype", "constructor"].includes(key)) throw new Error("Spec contains an unsafe property.");
+      if (key === "$ref" && (typeof item !== "string" || !item.startsWith("#/"))) throw new Error("Bundle external references into this spec before refreshing.");
+      walk(item, depth + 1);
+    }
+  };
+  walk(doc);
+  for (const [path, item] of Object.entries(doc.paths)) {
+    if (!path.startsWith("/") || !item || typeof item !== "object" || Array.isArray(item) || item.$ref) throw new Error("Use inline path items with absolute API paths.");
+    for (const method of apiMethods) {
+      const op = item[method];
+      if (!op) continue;
+      if (typeof op !== "object" || Array.isArray(op)) throw new Error("Invalid API operation.");
+      const id = operationId(method, path, op);
+      const toolId = id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 48);
+      if (ids.has(toolId)) throw new Error("Operation IDs must be unique, including their tool-safe names.");
+      ids.add(toolId);
+    }
+  }
+}
+function operationId(method, path, op) {
+  return typeof op.operationId === "string" ? op.operationId : `${method}_${path.replace(/[{}]/g, "").replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_|_$/g, "")}`;
+}
+function resolvePointer(doc, ref) {
+  let current = doc;
+  for (const segment of ref.slice(2).split("/")) {
+    if (!current || typeof current !== "object") return void 0;
+    current = current[segment.replace(/~1/g, "/").replace(/~0/g, "~")];
+  }
+  return current;
+}
+function reachableDefinitions(doc, roots) {
+  const resolved = {};
+  const visit = (node) => {
+    if (Array.isArray(node)) {
+      for (const entry of node) visit(entry);
+      return;
+    }
+    if (!node || typeof node !== "object") return;
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "$ref" && typeof value === "string") {
+        if (value in resolved) continue;
+        const target = resolvePointer(doc, value);
+        resolved[value] = target ?? null;
+        visit(target);
+        continue;
+      }
+      visit(value);
+    }
+  };
+  for (const root of roots) visit(root);
+  return resolved;
+}
+function apiOperations(doc) {
+  const operations = /* @__PURE__ */ new Map();
+  for (const [path, item] of Object.entries(doc.paths)) {
+    const parameters = Object.fromEntries(Object.entries(item).filter(([key]) => !apiMethods.includes(key)));
+    for (const method of apiMethods) {
+      const operation = item[method];
+      if (!operation) continue;
+      operations.set(method.toUpperCase() + " " + path, {
+        id: operationId(method, path, operation),
+        // Fingerprint what the operation's contract actually depends on: itself,
+        // the path item's shared fields, the definitions it reaches by `$ref`, and
+        // the document-level `security` that applies only where it declares none.
+        // Folding in the whole document instead meant one unrelated schema — or an
+        // `openapi` version bump — revoked every approval on the source.
+        // Document-level `servers` stays out deliberately: a refresh whose servers
+        // moved is already rejected unless the operator pinned an explicit baseUrl,
+        // and that override wins over the spec anyway (see agent/openapi.ts).
+        fingerprint: canonicalJson({
+          operation,
+          parameters,
+          security: operation["security"] === void 0 ? doc.security ?? null : null,
+          definitions: reachableDefinitions(doc, [operation, parameters])
+        })
+      });
+    }
+  }
+  return operations;
+}
+function matchPath(glob, path) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const trailingDeep = escaped.endsWith("/**");
+  const body = trailingDeep ? escaped.slice(0, -3) : escaped;
+  const pattern = body.split("**").map((chunk) => chunk.replace(/\*/g, "[^/]*")).join(".*") + (trailingDeep ? "(?:/.*)?" : "");
+  return new RegExp(`^${pattern}$`).test(path);
+}
+function compareApiDocuments(before, after) {
+  const old = apiOperations(before), next = apiOperations(after);
+  return {
+    added: [...next.keys()].filter((key) => !old.has(key)),
+    changed: [...next.keys()].filter((key) => old.has(key) && old.get(key).fingerprint !== next.get(key).fingerprint),
+    removed: [...old.keys()].filter((key) => !next.has(key)),
+    unchangedIds: [...next].filter(([key, value]) => old.get(key)?.fingerprint === value.fingerprint).map(([, value]) => value.id)
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   activeSkills,
   agentConfigSchema,
   apiCapabilitySchema,
+  apiMethods,
+  apiOperations,
   apiSourceSchema,
   approvedSkillTools,
   assertNoCommittedFrankieKeys,
   authConfigSchema,
   brandingConfigSchema,
+  canonicalJson,
+  compareApiDocuments,
   defineFrankieConfig,
   describeTool,
   draftSkill,
@@ -693,15 +887,18 @@ jobs:
   featuresConfigSchema,
   frankieConfigSchema,
   limitsConfigSchema,
+  matchPath,
   mcpServerSchema,
   modelChoiceSchema,
   modelConfigSchema,
+  operationId,
   parseFrankieConfig,
   planHostedInstall,
   sdkUpdateWorkflow,
   skillSchema,
   thinkingLevelSchema,
   toolPolicySchema,
+  validateApiDocument,
   widgetThemeSchema
 });
 //# sourceMappingURL=index.cjs.map