theokit 0.73.0 → 0.74.1

package/dist/{chunk-R7G2B2WH.js.map → chunk-HKF6YNY4.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/server/scan/agent-scan.ts","../src/server/scan/detect-agent-policy.ts"],"sourcesContent":["/* eslint-disable security/detect-non-literal-fs-filename --\n * Build-time scanner: walks `<projectRoot>/agents/` derived from cwd.\n * No HTTP input ever reaches these fs calls.\n */\nimport { existsSync, readFileSync, statSync } from 'node:fs'\nimport { extname, join, relative } from 'node:path'\n\nimport { walkSourceFiles } from '../_internal/scan-walker.js'\n\nimport { declaresAgentPolicy } from './detect-agent-policy.js'\nimport { MissingAgentPolicyError } from './errors.js'\nimport { createFileStampCache } from './file-stamp-cache.js'\n\nconst AGENT_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx'])\n// Convention § 5: a co-located test file is not an agent.\nconst TEST_FILE = /\\.(test|spec)$/\n\n/**\n * Folder-semantic discovery (Eve-style \"file = identity\"): an agent may be a self-contained folder that\n * co-locates its composition — `agents/<name>/{index.ts, tools/, skills/, prompts/, lib/}`. Files INSIDE\n * these conventional sub-folders are that concern (a tool, a skill, a prompt, a helper), NOT a routed\n * agent, so the scanner skips any file whose path passes through one of them. Only `<name>.ts` or\n * `<name>/index.ts` is served at `/api/agents/<name>`. A flat file literally named `tools.ts` is still a\n * valid agent (the reserved names only apply to intermediate DIRECTORIES, never the agent file itself).\n */\nconst AGENT_SUBFOLDERS = new Set([\n  'tools',\n  'skills',\n  'prompts',\n  'lib',\n  'hooks',\n  'channels',\n  'connections',\n  'subagents',\n  'schedules',\n  'sandbox',\n  'workflows',\n  'evals',\n  'memory',\n])\n\n/**\n * A discovered agent file. `name` is the client-facing key; `agentPath` is the mounted\n * SSE route (M0/M1 `UIMessageStream`).\n */\nexport interface AgentNode {\n  filePath: string\n  agentPath: string\n  name: string\n}\n\n/**\n * M2 — scan the TOP-LEVEL `agents/` convention (sibling of `server/`, per the LOCKED naming\n * decision). Mirrors `scanWebSocketRoutes`: one file → one endpoint, `index` stripped.\n */\n/**\n * Resolved paths already reported, so a per-request scan says it once — B-249, NFR-001.\n *\n * Keyed by the RESOLVED path rather than by the process: a test harness legitimately scans two\n * roots, and each distinct mistake deserves its own line. Same shape as `warnedAboutLegacySalt` in\n * `packages/http/src/action-encryption.ts`, and for the same reason: `scanAgents` runs per request\n * on a scanned deploy target, so an unbounded warning is a log flood on the exact path an anonymous\n * caller can drive.\n */\nconst reportedMissingDirs = new Set<string>()\n\nexport function scanAgents(projectRoot: string, configured?: string): AgentNode[] {\n  const agentsDirName = configured ?? 'agents'\n  // `agentsDirName` (config `agentsDir`, default \"agents\") — the dir holding `<name>.ts` agent\n  // definitions, relative to the project root. May be nested (e.g. \"core/agents\"). (#95 follow-up)\n  const agentsDir = join(projectRoot, agentsDirName)\n  if (!existsSync(agentsDir) || !statSync(agentsDir).isDirectory()) {\n    // B-249 — the same `[]` as before, and no longer the same silence.\n    //\n    // A configured value that resolves to nothing produced a result byte-identical to \"this app\n    // declares no agents\", so a deployed `/api/agents/<name>` answered 404 with an empty log and an\n    // operator had no reason to suspect configuration. The loudest way in is an ABSOLUTE path —\n    // this parameter is a NAME joined onto the root, so `join()` silently yields\n    // `<root><abs>` — but a typo, a missing nesting level and a directory a build did not copy all\n    // land in exactly the same place, and one rule covers all four.\n    //\n    // Silent when NOTHING was configured: a project with no agents is the ordinary case, and a gate\n    // that fires on ordinary work is a gate somebody disables. The parameter is OPTIONAL rather\n    // than defaulted for exactly that reason — a default erases the difference between \"nobody\n    // configured this\" and \"somebody configured 'agents'\", and only the first should stay quiet.\n    //\n    // The return value does not move (FR-003) and the contract stays relative (FR-004): reporting a\n    // path that does not exist tells the operator what went wrong without widening a documented\n    // public contract, which is a decision for a plan rather than a repair.\n    if (configured !== undefined && !reportedMissingDirs.has(agentsDir)) {\n      reportedMissingDirs.add(agentsDir)\n      console.warn(\n        `[theokit] agentsDir ${JSON.stringify(agentsDirName)} resolves to ${JSON.stringify(agentsDir)}, ` +\n          `which is not a directory, so NO agents were found and every /api/agents/* route will 404. ` +\n          `The value is a path relative to the project root ${JSON.stringify(projectRoot)} — an ` +\n          `absolute path is joined onto it and cannot resolve.`,\n      )\n    }\n    return []\n  }\n\n  const results: AgentNode[] = []\n  walkSourceFiles(agentsDir, { extensions: AGENT_EXTENSIONS }, (absPath) => {\n    let rel = relative(agentsDir, absPath)\n    rel = rel.replace(/\\\\/g, '/')\n    rel = rel.slice(0, -extname(rel).length)\n    if (TEST_FILE.test(rel)) return\n    // Eve-style: a file living under a composition sub-folder (tools/, skills/, prompts/, …) is that\n    // concern, not a routed agent. Check the intermediate DIRECTORIES only — the agent file itself may\n    // be named anything.\n    const dirs = rel.split('/').slice(0, -1)\n    if (dirs.some((segment) => AGENT_SUBFOLDERS.has(segment))) return\n    // Unlike routes/ws, an agent needs an explicit name — a bare `agents/index.ts`\n    // (name `''` → `/api/agents/`) is nonsensical for a typed `useAgent(name)` binding.\n    // `agents/foo/index.ts` still collapses to `foo` (a named nested agent).\n    if (rel.endsWith('/index')) rel = rel.slice(0, -6)\n    if (rel === 'index' || rel === '') return\n    const agentPath = `/api/agents/${rel}`\n    assertAgentDeclaresPolicy(absPath, agentPath)\n    results.push({\n      filePath: absPath,\n      agentPath,\n      name: rel,\n    })\n  })\n  return results\n}\n\n/**\n * Cache of the policy-declaration answer, keyed by path + mtime + size.\n *\n * `theokit dev` re-scans the agents directory on EVERY request, so parsing each agent file with the\n * TypeScript AST per request would turn a build-time check into per-request latency. Keying on the\n * file's own mtime and size means an edit invalidates the entry without anyone remembering to, and\n * a `theokit build` (one process, one scan) never notices the cache exists.\n */\nconst policyDeclarationCache = createFileStampCache<boolean>()\n\n/** Test seam — the module-level cache would otherwise outlive a fixture directory. */\nexport function _resetAgentPolicyCacheForTests(): void {\n  policyDeclarationCache.clear()\n}\n\n/**\n * Refuse an agent file that declares no access policy (usetheokit/theokit#365).\n *\n * The refusal lives in the scanner, next to the reserved-name and empty-name refusals, because this\n * is the one place every entry point passes through: `theokit build`, `theokit start`, `theokit dev`\n * and the manifest generator all reach agents by calling `scanAgents`.\n *\n * The blast radius stops at the file system, exactly as it does for routes. A module handed to\n * `mountAgent` in memory — a test, an embedder, an `@Expose`d controller method — never passed a\n * scanner, and `admitAgentRequest` still treats an undeclared policy as \"not declared\" rather than\n * as denial. Absence is refused where an application DECLARES its agents, not where a caller passes\n * one.\n */\nfunction assertAgentDeclaresPolicy(filePath: string, agentPath: string): void {\n  // The stamping and the `has`-vs-truthy subtlety moved into `createFileStampCache` (#417), where\n  // the route scanner shares them rather than growing a second copy keyed \"the same way\".\n  const declared = policyDeclarationCache.get(filePath, () =>\n    declaresAgentPolicy(filePath, readFileSync(filePath, 'utf8')),\n  )\n  if (!declared) throw new MissingAgentPolicyError({ file: filePath, agentPath })\n}\n","/**\n * Does this agent file declare an access policy? (usetheokit/theokit#365)\n *\n * The sibling of `detect-route-policy.ts`, and deliberately the same instrument: the TypeScript\n * AST rather than a regex, because `// policy: ...` in a comment and the word `policy` in a doc\n * block are both things an agent file legitimately contains, and neither declares anything.\n *\n * ## What it looks for, and why it is simpler than the route detector\n *\n * A route file declares one policy PER exported HTTP method, so the route detector has to return a\n * set and reason about which method carried which config. An agent file is one agent, so the\n * question is a single yes or no: is there a top-level export named `policy`?\n *\n * ```ts\n * export const policy = 'public'\n * export const policy = ({ subject, params }) => requireOwner(subject, ownerOf(params.sessionId))\n * const policy = ...; export { policy }\n * export { agentPolicy as policy } from './shared'   // ← also counts; see below\n * ```\n *\n * ## Where this is deliberately laxer than the route detector\n *\n * The route detector refuses `export { GET } from './shared'`, on the reasoning that it cannot see\n * whether the re-exported value declares a policy. Here there is nothing to look inside: the export\n * IS the policy, so a re-export names one as surely as a local const does. The value's SHAPE is\n * checked at runtime by `readAgentPolicy`, which throws on anything that is neither `'public'` nor\n * a function — so a wrong type fails loudly rather than being served open.\n */\nimport { createRequire } from 'node:module'\n\nimport type * as TS from 'typescript'\n\nconst require_ = createRequire(import.meta.url)\n\nconst ts = require_('typescript') as typeof TS\n\nconst POLICY_EXPORT = 'policy'\n\nfunction hasExportModifier(modifiers: readonly TS.Modifier[] | undefined): boolean {\n  if (!modifiers) return false\n  for (const m of modifiers) {\n    if (m.kind === ts.SyntaxKind.ExportKeyword) return true\n  }\n  return false\n}\n\n/** `export const policy = ...` (also `let`/`var`, which are legal if unusual). */\nfunction variableStatementDeclaresPolicy(stmt: TS.VariableStatement): boolean {\n  if (!hasExportModifier(ts.getModifiers(stmt))) return false\n  return stmt.declarationList.declarations.some(\n    (decl) => ts.isIdentifier(decl.name) && decl.name.text === POLICY_EXPORT,\n  )\n}\n\n/** `export { policy }`, `export { p as policy }`, `export { p as policy } from './shared'`. */\nfunction exportDeclarationDeclaresPolicy(stmt: TS.ExportDeclaration): boolean {\n  if (!stmt.exportClause || !ts.isNamedExports(stmt.exportClause)) return false\n  return stmt.exportClause.elements.some((spec) => spec.name.text === POLICY_EXPORT)\n}\n\n/** `export function policy() {}` — a function declaration is a policy as much as a const is. */\nfunction functionDeclarationDeclaresPolicy(stmt: TS.FunctionDeclaration): boolean {\n  return hasExportModifier(ts.getModifiers(stmt)) && stmt.name?.text === POLICY_EXPORT\n}\n\n/**\n * True when the file has a top-level export named `policy`.\n *\n * `content` is passed in rather than read here so the caller reads each file once — the same\n * contract `detectRoutePolicyKinds` follows.\n */\nexport function declaresAgentPolicy(filePath: string, content: string): boolean {\n  const sourceFile = ts.createSourceFile(\n    filePath,\n    content,\n    ts.ScriptTarget.Latest,\n    /* setParentNodes */ false,\n    ts.ScriptKind.TS,\n  )\n  for (const stmt of sourceFile.statements) {\n    if (ts.isVariableStatement(stmt) && variableStatementDeclaresPolicy(stmt)) return true\n    if (ts.isExportDeclaration(stmt) && exportDeclarationDeclaresPolicy(stmt)) return true\n    if (ts.isFunctionDeclaration(stmt) && functionDeclarationDeclaresPolicy(stmt)) return true\n  }\n  return false\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/server/scan/agent-scan.ts","../src/server/scan/detect-agent-policy.ts"],"sourcesContent":["/* eslint-disable security/detect-non-literal-fs-filename --\n * Build-time scanner: walks `<projectRoot>/agents/` derived from cwd.\n * No HTTP input ever reaches these fs calls.\n */\nimport { existsSync, readFileSync, statSync } from 'node:fs'\nimport { extname, join, relative } from 'node:path'\n\nimport { walkSourceFiles } from '../_internal/scan-walker.js'\n\nimport { declaresAgentPolicy } from './detect-agent-policy.js'\nimport { MissingAgentPolicyError } from './errors.js'\nimport { createFileStampCache } from './file-stamp-cache.js'\n\nconst AGENT_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx'])\n// Convention § 5: a co-located test file is not an agent.\nconst TEST_FILE = /\\.(test|spec)$/\n\n/**\n * Folder-semantic discovery (Eve-style \"file = identity\"): an agent may be a self-contained folder that\n * co-locates its composition — `agents/<name>/{index.ts, tools/, skills/, prompts/, lib/}`. Files INSIDE\n * these conventional sub-folders are that concern (a tool, a skill, a prompt, a helper), NOT a routed\n * agent, so the scanner skips any file whose path passes through one of them. Only `<name>.ts` or\n * `<name>/index.ts` is served at `/api/agents/<name>`. A flat file literally named `tools.ts` is still a\n * valid agent (the reserved names only apply to intermediate DIRECTORIES, never the agent file itself).\n */\nconst AGENT_SUBFOLDERS = new Set([\n  'tools',\n  'skills',\n  'prompts',\n  'lib',\n  'hooks',\n  'channels',\n  'connections',\n  'subagents',\n  'schedules',\n  'sandbox',\n  'workflows',\n  'evals',\n  'memory',\n])\n\n/**\n * A discovered agent file. `name` is the client-facing key; `agentPath` is the mounted\n * SSE route (M0/M1 `UIMessageStream`).\n */\nexport interface AgentNode {\n  filePath: string\n  agentPath: string\n  name: string\n}\n\n/**\n * M2 — scan the TOP-LEVEL `agents/` convention (sibling of `server/`, per the LOCKED naming\n * decision). Mirrors `scanWebSocketRoutes`: one file → one endpoint, `index` stripped.\n */\n/**\n * Resolved paths already reported, so a per-request scan says it once — B-249, NFR-001.\n *\n * Keyed by the RESOLVED path rather than by the process: a test harness legitimately scans two\n * roots, and each distinct mistake deserves its own line. Same shape as `warnedAboutLegacySalt` in\n * `packages/http/src/action-encryption.ts`, and for the same reason: `scanAgents` runs per request\n * on a scanned deploy target, so an unbounded warning is a log flood on the exact path an anonymous\n * caller can drive.\n */\nconst reportedMissingDirs = new Set<string>()\n\nexport function scanAgents(projectRoot: string, configured?: string): AgentNode[] {\n  const agentsDirName = configured ?? 'agents'\n  // `agentsDirName` (config `agentsDir`, default \"agents\") — the dir holding `<name>.ts` agent\n  // definitions, relative to the project root. May be nested (e.g. \"core/agents\"). (#95 follow-up)\n  const agentsDir = join(projectRoot, agentsDirName)\n  if (!existsSync(agentsDir) || !statSync(agentsDir).isDirectory()) {\n    // B-249 — the same `[]` as before, and no longer the same silence.\n    //\n    // A configured value that resolves to nothing produced a result byte-identical to \"this app\n    // declares no agents\", so a deployed `/api/agents/<name>` answered 404 with an empty log and an\n    // operator had no reason to suspect configuration. The loudest way in is an ABSOLUTE path —\n    // this parameter is a NAME joined onto the root, so `join()` silently yields\n    // `<root><abs>` — but a typo, a missing nesting level and a directory a build did not copy all\n    // land in exactly the same place, and one rule covers all four.\n    //\n    // Silent when NOTHING was configured: a project with no agents is the ordinary case, and a gate\n    // that fires on ordinary work is a gate somebody disables. The parameter is OPTIONAL rather\n    // than defaulted for exactly that reason — a default erases the difference between \"nobody\n    // configured this\" and \"somebody configured 'agents'\", and only the first should stay quiet.\n    //\n    // The return value does not move (FR-003) and the contract stays relative (FR-004): reporting a\n    // path that does not exist tells the operator what went wrong without widening a documented\n    // public contract, which is a decision for a plan rather than a repair.\n    if (configured !== undefined && !reportedMissingDirs.has(agentsDir)) {\n      reportedMissingDirs.add(agentsDir)\n      console.warn(\n        `[theokit] agentsDir ${JSON.stringify(agentsDirName)} resolves to ${JSON.stringify(agentsDir)}, ` +\n          `which is not a directory, so NO agents were found and every /api/agents/* route will 404. ` +\n          `The value is a path relative to the project root ${JSON.stringify(projectRoot)} — an ` +\n          `absolute path is joined onto it and cannot resolve.`,\n      )\n    }\n    return []\n  }\n\n  const results: AgentNode[] = []\n  walkSourceFiles(agentsDir, { extensions: AGENT_EXTENSIONS }, (absPath) => {\n    let rel = relative(agentsDir, absPath)\n    rel = rel.replace(/\\\\/g, '/')\n    rel = rel.slice(0, -extname(rel).length)\n    if (TEST_FILE.test(rel)) return\n    // Eve-style: a file living under a composition sub-folder (tools/, skills/, prompts/, …) is that\n    // concern, not a routed agent. Check the intermediate DIRECTORIES only — the agent file itself may\n    // be named anything.\n    const dirs = rel.split('/').slice(0, -1)\n    if (dirs.some((segment) => AGENT_SUBFOLDERS.has(segment))) return\n    // Unlike routes/ws, an agent needs an explicit name — a bare `agents/index.ts`\n    // (name `''` → `/api/agents/`) is nonsensical for a typed `useAgent(name)` binding.\n    // `agents/foo/index.ts` still collapses to `foo` (a named nested agent).\n    if (rel.endsWith('/index')) rel = rel.slice(0, -6)\n    if (rel === 'index' || rel === '') return\n    const agentPath = `/api/agents/${rel}`\n    assertAgentDeclaresPolicy(absPath, agentPath)\n    results.push({\n      filePath: absPath,\n      agentPath,\n      name: rel,\n    })\n  })\n  return results\n}\n\n/**\n * Cache of the policy-declaration answer, keyed by path + mtime + size.\n *\n * `theokit dev` re-scans the agents directory on EVERY request, so parsing each agent file with the\n * TypeScript AST per request would turn a build-time check into per-request latency. Keying on the\n * file's own mtime and size means an edit invalidates the entry without anyone remembering to, and\n * a `theokit build` (one process, one scan) never notices the cache exists.\n */\nconst policyDeclarationCache = createFileStampCache<boolean>()\n\n/** Test seam — the module-level cache would otherwise outlive a fixture directory. */\nexport function _resetAgentPolicyCacheForTests(): void {\n  policyDeclarationCache.clear()\n}\n\n/**\n * Refuse an agent file that declares no access policy (usetheokit/theokit#365).\n *\n * The refusal lives in the scanner, next to the reserved-name and empty-name refusals, because this\n * is the one place every entry point passes through: `theokit build`, `theokit start`, `theokit dev`\n * and the manifest generator all reach agents by calling `scanAgents`.\n *\n * The blast radius stops at the file system, exactly as it does for routes. A module handed to\n * `mountAgent` in memory — a test, an embedder, an `@Expose`d controller method — never passed a\n * scanner, and `admitAgentRequest` still treats an undeclared policy as \"not declared\" rather than\n * as denial. Absence is refused where an application DECLARES its agents, not where a caller passes\n * one.\n */\nfunction assertAgentDeclaresPolicy(filePath: string, agentPath: string): void {\n  // The stamping and the `has`-vs-truthy subtlety moved into `createFileStampCache` (#417), where\n  // the route scanner shares them rather than growing a second copy keyed \"the same way\".\n  const declared = policyDeclarationCache.get(filePath, () =>\n    declaresAgentPolicy(filePath, readFileSync(filePath, 'utf8')),\n  )\n  if (!declared) throw new MissingAgentPolicyError({ file: filePath, agentPath })\n}\n","/**\n * Does this agent file declare an access policy? (usetheokit/theokit#365)\n *\n * The sibling of `detect-route-policy.ts`, and deliberately the same instrument: the TypeScript\n * AST rather than a regex, because `// policy: ...` in a comment and the word `policy` in a doc\n * block are both things an agent file legitimately contains, and neither declares anything.\n *\n * ## What it looks for, and why it is simpler than the route detector\n *\n * A route file declares one policy PER exported HTTP method, so the route detector has to return a\n * set and reason about which method carried which config. An agent file is one agent, so the\n * question is a single yes or no: is there a top-level export named `policy`?\n *\n * ```ts\n * export const policy = 'public'\n * export const policy = ({ subject, params }) => requireOwner(subject, ownerOf(params.sessionId))\n * const policy = ...; export { policy }\n * export { agentPolicy as policy } from './shared'   // ← also counts; see below\n * ```\n *\n * ## Where this is deliberately laxer than the route detector\n *\n * The route detector refuses `export { GET } from './shared'`, on the reasoning that it cannot see\n * whether the re-exported value declares a policy. Here there is nothing to look inside: the export\n * IS the policy, so a re-export names one as surely as a local const does. The value's SHAPE is\n * checked at runtime by `readAgentPolicy`, which throws on anything that is neither `'public'` nor\n * a function — so a wrong type fails loudly rather than being served open.\n */\nimport { createRequire } from 'node:module'\n\nimport type * as TS from 'typescript'\n\n/**\n * The compiler, loaded on first use and never at import time.\n *\n * This was module scope, and a Cloudflare deploy found what that costs: `theokit/server/scan` is\n * imported by the generated worker (through `agent-scan.ts`), Cloudflare EXECUTES the module during\n * validation, and there `import.meta.url` is undefined — so `createRequire` threw before the worker\n * ever answered a request (B-263, error 10021). `wrangler deploy --dry-run` had returned exit 0 on\n * the same bundle minutes earlier: it bundles and does not execute.\n *\n * The second reason is independent of Workers and would hold anyway: this is a BUILD-TIME AST\n * scanner, and nothing that merely imports the module should pay for the TypeScript compiler.\n *\n * Cached, so scanning many files still loads it once.\n */\nlet compiler: typeof TS | undefined\n\nfunction ts_(): typeof TS {\n  compiler ??= createRequire(import.meta.url)('typescript') as typeof TS\n  return compiler\n}\n\nconst POLICY_EXPORT = 'policy'\n\nfunction hasExportModifier(modifiers: readonly TS.Modifier[] | undefined): boolean {\n  if (!modifiers) return false\n  for (const m of modifiers) {\n    if (m.kind === ts_().SyntaxKind.ExportKeyword) return true\n  }\n  return false\n}\n\n/** `export const policy = ...` (also `let`/`var`, which are legal if unusual). */\nfunction variableStatementDeclaresPolicy(stmt: TS.VariableStatement): boolean {\n  if (!hasExportModifier(ts_().getModifiers(stmt))) return false\n  return stmt.declarationList.declarations.some(\n    (decl) => ts_().isIdentifier(decl.name) && decl.name.text === POLICY_EXPORT,\n  )\n}\n\n/** `export { policy }`, `export { p as policy }`, `export { p as policy } from './shared'`. */\nfunction exportDeclarationDeclaresPolicy(stmt: TS.ExportDeclaration): boolean {\n  if (!stmt.exportClause || !ts_().isNamedExports(stmt.exportClause)) return false\n  return stmt.exportClause.elements.some((spec) => spec.name.text === POLICY_EXPORT)\n}\n\n/** `export function policy() {}` — a function declaration is a policy as much as a const is. */\nfunction functionDeclarationDeclaresPolicy(stmt: TS.FunctionDeclaration): boolean {\n  return hasExportModifier(ts_().getModifiers(stmt)) && stmt.name?.text === POLICY_EXPORT\n}\n\n/**\n * True when the file has a top-level export named `policy`.\n *\n * `content` is passed in rather than read here so the caller reads each file once — the same\n * contract `detectRoutePolicyKinds` follows.\n */\nexport function declaresAgentPolicy(filePath: string, content: string): boolean {\n  const sourceFile = ts_().createSourceFile(\n    filePath,\n    content,\n    ts_().ScriptTarget.Latest,\n    /* setParentNodes */ false,\n    ts_().ScriptKind.TS,\n  )\n  for (const stmt of sourceFile.statements) {\n    if (ts_().isVariableStatement(stmt) && variableStatementDeclaresPolicy(stmt)) return true\n    if (ts_().isExportDeclaration(stmt) && exportDeclarationDeclaresPolicy(stmt)) return true\n    if (ts_().isFunctionDeclaration(stmt) && functionDeclarationDeclaresPolicy(stmt)) return true\n  }\n  return false\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-IJQQNHL7.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import "tsx/esm";
+import {
+  findRootDiv
+} from "./chunk-3PWQQWT6.js";
+
+// src/adapters/deployed-document-shell.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+function readDocumentShell(cwd, streaming) {
+  if (!streaming) return {};
+  const indexPath = resolve(cwd, ".theokit/client/index.html");
+  if (!existsSync(indexPath)) {
+    throw new Error(
+      `[adapter-cloudflare] ssrStreaming is on but ${indexPath} does not exist, so the worker would serve a document with no <head> and no client entry. Run the client build first, or set ssrStreaming: false in theo.config.ts.`
+    );
+  }
+  const indexHtml = readFileSync(indexPath, "utf-8");
+  const rootDiv = findRootDiv(indexHtml);
+  if (rootDiv === void 0) {
+    throw new Error(
+      `[adapter-cloudflare] ${indexPath} has no <div id="root">, so the streamed document has nowhere to put the app. Add one, or set ssrStreaming: false in theo.config.ts.`
+    );
+  }
+  return {
+    htmlHead: indexHtml.slice(0, rootDiv.insertAt),
+    htmlTail: indexHtml.slice(rootDiv.insertAt)
+  };
+}
+
+export {
+  readDocumentShell
+};
+//# sourceMappingURL=chunk-IJQQNHL7.js.map

package/dist/chunk-IJQQNHL7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/deployed-document-shell.ts"],"sourcesContent":["/**\n * Where the app goes inside the built client shell, for a target that renders the document itself.\n *\n * Extracted from `cloudflare.ts` on 2026-09-28 (B-317), when the Vercel target gained a document branch\n * and needed the same knowledge. One adapter importing another is the coupling `deployed-baked-routes.ts`\n * was extracted to avoid, and this is the second instance of that shape rather than a new one.\n *\n * It THROWS rather than degrading, in both directions, and the messages say what to do. A target that\n * renders a document with no `<head>` and no client entry produces a page that loads nothing and reports\n * no error — the failure this refuses to ship.\n */\nimport { existsSync, readFileSync } from 'node:fs'\nimport { resolve } from 'node:path'\n\nimport { findRootDiv } from '../core/contracts/find-root-div.js'\n\nexport function readDocumentShell(\n  cwd: string,\n  streaming: boolean,\n): { htmlHead?: string; htmlTail?: string } {\n  if (!streaming) return {}\n\n  const indexPath = resolve(cwd, '.theokit/client/index.html')\n  // eslint-disable-next-line security/detect-non-literal-fs-filename -- a constant suffix under the caller's project root\n  if (!existsSync(indexPath)) {\n    throw new Error(\n      `[adapter-cloudflare] ssrStreaming is on but ${indexPath} does not exist, so the worker ` +\n        `would serve a document with no <head> and no client entry. Run the client build first, ` +\n        `or set ssrStreaming: false in theo.config.ts.`,\n    )\n  }\n\n  // eslint-disable-next-line security/detect-non-literal-fs-filename -- the same path, proven above\n  const indexHtml = readFileSync(indexPath, 'utf-8')\n  const rootDiv = findRootDiv(indexHtml)\n  if (rootDiv === undefined) {\n    throw new Error(\n      `[adapter-cloudflare] ${indexPath} has no <div id=\"root\">, so the streamed document has ` +\n        `nowhere to put the app. Add one, or set ssrStreaming: false in theo.config.ts.`,\n    )\n  }\n\n  return {\n    htmlHead: indexHtml.slice(0, rootDiv.insertAt),\n    htmlTail: indexHtml.slice(rootDiv.insertAt),\n  }\n}\n"],"mappings":";;;;;;;AAWA,SAAS,YAAY,oBAAoB;AACzC,SAAS,eAAe;AAIjB,SAAS,kBACd,KACA,WAC0C;AAC1C,MAAI,CAAC,UAAW,QAAO,CAAC;AAExB,QAAM,YAAY,QAAQ,KAAK,4BAA4B;AAE3D,MAAI,CAAC,WAAW,SAAS,GAAG;AAC1B,UAAM,IAAI;AAAA,MACR,+CAA+C,SAAS;AAAA,IAG1D;AAAA,EACF;AAGA,QAAM,YAAY,aAAa,WAAW,OAAO;AACjD,QAAM,UAAU,YAAY,SAAS;AACrC,MAAI,YAAY,QAAW;AACzB,UAAM,IAAI;AAAA,MACR,wBAAwB,SAAS;AAAA,IAEnC;AAAA,EACF;AAEA,SAAO;AAAA,IACL,UAAU,UAAU,MAAM,GAAG,QAAQ,QAAQ;AAAA,IAC7C,UAAU,UAAU,MAAM,QAAQ,QAAQ;AAAA,EAC5C;AACF;","names":[]}

package/dist/chunk-NPQ5A3RU.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import "tsx/esm";
+
+// src/adapters/bundle-deployed-function.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname, resolve, sep } from "path";
+import { build as viteBuild } from "vite";
+var PathOutsideProjectRootError = class extends Error {
+  name = "PathOutsideProjectRootError";
+  constructor(field, value, resolved, projectRoot) {
+    super(
+      `bundleDeployedFunction: \`${field}\` must stay inside \`projectRoot\`. Given ${JSON.stringify(value)}, which resolves to ${JSON.stringify(resolved)}, outside ${JSON.stringify(projectRoot)}.`
+    );
+  }
+};
+async function bundleDeployedFunction(options) {
+  const rootAbs = resolve(options.projectRoot);
+  const isInside = (candidate) => candidate === rootAbs || candidate.startsWith(`${rootAbs}${sep}`);
+  const stageAbs = resolve(rootAbs, options.stagePath);
+  if (!isInside(stageAbs)) {
+    throw new PathOutsideProjectRootError("stagePath", options.stagePath, stageAbs, rootAbs);
+  }
+  mkdirSync(dirname(stageAbs), { recursive: true });
+  writeFileSync(stageAbs, options.entrySource, "utf8");
+  await viteBuild({
+    root: options.projectRoot,
+    // The project's own vite config is for its APP. Reading it here would apply its plugins, its
+    // aliases and its `build.outDir` to a server entry that wants none of them.
+    configFile: false,
+    logLevel: "warn",
+    // The whole point: without this, vite externalises every bare specifier and the output has the
+    // same unresolvable imports the input had.
+    ssr: { noExternal: true },
+    build: {
+      ssr: true,
+      outDir: options.outDir,
+      emptyOutDir: true,
+      // Measured: with `root` at the project, vite otherwise copies `index.html`, `logo.png`,
+      // `favicon.svg` and `robots.txt` into the function directory — a lambda carrying the site's
+      // static assets, and an `index.html` sitting beside a handler.
+      copyPublicDir: false,
+      rollupOptions: {
+        input: stageAbs,
+        output: { entryFileNames: options.entryFileName, format: "esm" }
+      }
+    }
+  });
+}
+
+export {
+  bundleDeployedFunction
+};
+//# sourceMappingURL=chunk-NPQ5A3RU.js.map

package/dist/chunk-NPQ5A3RU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/bundle-deployed-function.ts"],"sourcesContent":["import { mkdirSync, writeFileSync } from 'node:fs'\nimport { dirname, resolve, sep } from 'node:path'\n\nimport { build as viteBuild } from 'vite'\n\n/** What the caller has to say to get a self-contained function out. */\nexport interface BundleDeployedFunctionOptions {\n  /** The project being built. Everything else is resolved against it. */\n  projectRoot: string\n  /** The generated entry source, as the adapter rendered it. */\n  entrySource: string\n  /**\n   * Where the staged entry is written, relative to `projectRoot`.\n   *\n   * Inside the root is not a preference. Measured while establishing ADR 0020: an entry staged in\n   * `/tmp` makes rollup resolve `theokit/server/scan` from `/tmp` and the build fails with an\n   * unresolved import, because a specifier resolves relative to the importing FILE.\n   */\n  stagePath: string\n  /**\n   * The directory the platform will upload, absolute.\n   *\n   * It reaches vite with `emptyOutDir: true`, so whatever is there is DELETED. Emptying a build\n   * output directory is the point, and it is why this must be a directory the caller owns — it is not\n   * required to sit inside `projectRoot` (the test for this function passes a sibling, deliberately),\n   * so nothing here can check it for you.\n   */\n  outDir: string\n  /** The file name the platform expects inside `outDir`. */\n  entryFileName: string\n}\n\n/**\n * Bundle a generated entry into a directory that loads with no `node_modules` beside it.\n *\n * ## Why this exists at all\n *\n * A platform either resolves the entry's bare specifiers or it does not, and three answers are in\n * play. `wrangler` bundles with esbuild at deploy time; Bun resolves against the project's own\n * `node_modules` at run time; **Vercel's Build Output API v3 uploads a `.func` directory as it is**,\n * and AWS Lambda does the same with a zip. Measured 2026-09-26 on this repository's own scaffold:\n *\n *     cp -a .vercel/output/functions/api.func/. /tmp/fn/ && cd /tmp/fn\n *     node -e \"import('./index.mjs')\"\n *     -> ERR_MODULE_NOT_FOUND: Cannot find package 'theokit'\n *\n * So the adapter bundles when the platform will not. The decision, the rejected alternatives and the\n * measurements are ADR 0020; this is its one implementation, shared rather than copied per target\n * because B-315 is what five copies of one call look like after a while.\n *\n * ## Why vite\n *\n * The parsimony ladder's fourth rung. `esbuild` resolves from neither the repository root nor\n * `packages/theo` — it is an undeclared transitive dependency — while `vite` is declared and\n * `adapters/node.ts` already runs `viteBuild` for the same shape of job. Reuse over addition.\n *\n * ## What it does NOT do\n *\n * It does not verify the bundle answers a request. That needs the platform. What it establishes is\n * the property that was false: the directory loads on its own.\n */\n/**\n * Thrown at BUILD time when a path this function would write to leaves the project.\n *\n * Named like `UnserialisableRateLimitError` next door, because the adapters report a build-time\n * refusal as a typed domain error rather than a string (`rules/error-handling.md`).\n *\n * The invariant was DECLARED and unenforced. `stagePath`'s own docblock says \"inside the root is not a\n * preference\", and nothing checked it — `resolve(root, '../outside/entry.mjs')` wrote the entry outside\n * the project, and `resolve(root, '/etc/theo-entry.mjs')` discarded the root entirely and was stopped\n * only by filesystem permissions (`EACCES`, measured 2026-09-28).\n *\n * It covers `stagePath` and NOT `outDir`, which is a correction rather than an omission. A first\n * version checked both, and the pre-existing test for this function passes an `outDir` that is a\n * SIBLING of `projectRoot` — which the option's contract permits, since it is documented as \"the\n * directory the platform will upload, absolute\" and nothing more. The invariant was invented, the test\n * refused it, and the test was right.\n */\nexport class PathOutsideProjectRootError extends Error {\n  override readonly name = 'PathOutsideProjectRootError'\n\n  constructor(field: string, value: string, resolved: string, projectRoot: string) {\n    super(\n      `bundleDeployedFunction: \\`${field}\\` must stay inside \\`projectRoot\\`. ` +\n        `Given ${JSON.stringify(value)}, which resolves to ${JSON.stringify(resolved)}, ` +\n        `outside ${JSON.stringify(projectRoot)}.`,\n    )\n  }\n}\n\nexport async function bundleDeployedFunction(\n  options: BundleDeployedFunctionOptions,\n): Promise<void> {\n  // Validated at the boundary, before anything is written — `rules/error-handling.md`: reject invalid\n  // input before processing, and this function's first act is a write.\n  const rootAbs = resolve(options.projectRoot)\n  const isInside = (candidate: string): boolean =>\n    candidate === rootAbs || candidate.startsWith(`${rootAbs}${sep}`)\n\n  const stageAbs = resolve(rootAbs, options.stagePath)\n  if (!isInside(stageAbs)) {\n    throw new PathOutsideProjectRootError('stagePath', options.stagePath, stageAbs, rootAbs)\n  }\n  // `stageAbs` is proven above to resolve inside `projectRoot`, and it is a build-time path rather\n  // than request input. The exemption is per-call rather than per-file on purpose: a file-scope\n  // disable would silently cover an fs call somebody adds later, whose path nothing proved.\n  // eslint-disable-next-line security/detect-non-literal-fs-filename -- proven inside projectRoot above\n  mkdirSync(dirname(stageAbs), { recursive: true })\n  // eslint-disable-next-line security/detect-non-literal-fs-filename -- proven inside projectRoot above\n  writeFileSync(stageAbs, options.entrySource, 'utf8')\n\n  await viteBuild({\n    root: options.projectRoot,\n    // The project's own vite config is for its APP. Reading it here would apply its plugins, its\n    // aliases and its `build.outDir` to a server entry that wants none of them.\n    configFile: false,\n    logLevel: 'warn',\n    // The whole point: without this, vite externalises every bare specifier and the output has the\n    // same unresolvable imports the input had.\n    ssr: { noExternal: true },\n    build: {\n      ssr: true,\n      outDir: options.outDir,\n      emptyOutDir: true,\n      // Measured: with `root` at the project, vite otherwise copies `index.html`, `logo.png`,\n      // `favicon.svg` and `robots.txt` into the function directory — a lambda carrying the site's\n      // static assets, and an `index.html` sitting beside a handler.\n      copyPublicDir: false,\n      rollupOptions: {\n        input: stageAbs,\n        output: { entryFileNames: options.entryFileName, format: 'esm' },\n      },\n    },\n  })\n}\n"],"mappings":";;;;AAAA,SAAS,WAAW,qBAAqB;AACzC,SAAS,SAAS,SAAS,WAAW;AAEtC,SAAS,SAAS,iBAAiB;AA2E5B,IAAM,8BAAN,cAA0C,MAAM;AAAA,EACnC,OAAO;AAAA,EAEzB,YAAY,OAAe,OAAe,UAAkB,aAAqB;AAC/E;AAAA,MACE,6BAA6B,KAAK,8CACvB,KAAK,UAAU,KAAK,CAAC,uBAAuB,KAAK,UAAU,QAAQ,CAAC,aAClE,KAAK,UAAU,WAAW,CAAC;AAAA,IAC1C;AAAA,EACF;AACF;AAEA,eAAsB,uBACpB,SACe;AAGf,QAAM,UAAU,QAAQ,QAAQ,WAAW;AAC3C,QAAM,WAAW,CAAC,cAChB,cAAc,WAAW,UAAU,WAAW,GAAG,OAAO,GAAG,GAAG,EAAE;AAElE,QAAM,WAAW,QAAQ,SAAS,QAAQ,SAAS;AACnD,MAAI,CAAC,SAAS,QAAQ,GAAG;AACvB,UAAM,IAAI,4BAA4B,aAAa,QAAQ,WAAW,UAAU,OAAO;AAAA,EACzF;AAKA,YAAU,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;AAEhD,gBAAc,UAAU,QAAQ,aAAa,MAAM;AAEnD,QAAM,UAAU;AAAA,IACd,MAAM,QAAQ;AAAA;AAAA;AAAA,IAGd,YAAY;AAAA,IACZ,UAAU;AAAA;AAAA;AAAA,IAGV,KAAK,EAAE,YAAY,KAAK;AAAA,IACxB,OAAO;AAAA,MACL,KAAK;AAAA,MACL,QAAQ,QAAQ;AAAA,MAChB,aAAa;AAAA;AAAA;AAAA;AAAA,MAIb,eAAe;AAAA,MACf,eAAe;AAAA,QACb,OAAO;AAAA,QACP,QAAQ,EAAE,gBAAgB,QAAQ,eAAe,QAAQ,MAAM;AAAA,MACjE;AAAA,IACF;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/{chunk-D3M7LPHY.js → chunk-NQZIQJFH.js}

@@ -13,7 +13,7 @@ import {
   isAgentCardPath,
   matchAgentAuxRoute,
   serveMatchedAuxRoute
-} from "./chunk-6U67SO5U.js";
+} from "./chunk-HK57MPSZ.js";
 import {
   admitAgentRequest,
   agentAccessDenied,
@@ -29,7 +29,7 @@ import {
   securitySchema,
   storageSchema,
   uploadSchema
-} from "./chunk-WBB3MEEN.js";
+} from "./chunk-2NG5T77O.js";
 import {
   broadcastToDevtools
 } from "./chunk-OIGJOYX6.js";
@@ -84,10 +84,10 @@ import {
   scanServerActions,
   scanServerRoutes,
   scanWebSocketRoutes
-} from "./chunk-4CIHLTSI.js";
+} from "./chunk-V7ISZGNS.js";
 import {
   scanAgents
-} from "./chunk-FHQP23Z5.js";
+} from "./chunk-6R5F5YF2.js";
 import {
   resolveProvider
 } from "./chunk-ICXXHV4V.js";
@@ -1871,24 +1871,42 @@ async function runConfigureServer(server, ctx) {
   server.watcher.on("unlink", handleRouteChange);
   if (ctx.resolvedOpenApi !== void 0) {
     const openApiCfg = ctx.resolvedOpenApi;
-    const { reEmitOpenApi } = await import("./dev-emit-7KZFUA7M.js");
+    const { reEmitOpenApi } = await import("./dev-emit-T3X6RR7M.js");
     const openApiServerDir = ctx.serverDir;
     const openApiDistDir = resolve7(ctx.projectRoot, ctx.resolvedDistDir);
     const isRouteFileForOpenApi = (file) => file.startsWith(openApiServerDir) && /\.(ts|tsx|js|mjs)$/.test(file);
-    void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
+    void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg, ctx.projectRoot, ctx.agentsDir);
     server.watcher.on("change", (file) => {
       if (isRouteFileForOpenApi(file)) {
-        void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
+        void reEmitOpenApi(
+          openApiServerDir,
+          openApiDistDir,
+          openApiCfg,
+          ctx.projectRoot,
+          ctx.agentsDir
+        );
       }
     });
     server.watcher.on("add", (file) => {
       if (isRouteFileForOpenApi(file)) {
-        void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
+        void reEmitOpenApi(
+          openApiServerDir,
+          openApiDistDir,
+          openApiCfg,
+          ctx.projectRoot,
+          ctx.agentsDir
+        );
       }
     });
     server.watcher.on("unlink", (file) => {
       if (isRouteFileForOpenApi(file)) {
-        void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
+        void reEmitOpenApi(
+          openApiServerDir,
+          openApiDistDir,
+          openApiCfg,
+          ctx.projectRoot,
+          ctx.agentsDir
+        );
       }
     });
   }
@@ -2618,7 +2636,26 @@ function generateStreamingEntry(options) {
   const appTree = buildAppTreeJs(options);
   return [
     `import React, { Suspense } from 'react'`,
-    `import { renderToPipeableStream, renderToReadableStream } from 'react-dom/server'`,
+    // A NAMESPACE import, deliberately. `react-dom/server` resolves to `server.bun.js` under Bun,
+    // which exports `renderToReadableStream`, `renderToStaticMarkup`, `renderToString`, `resume` and
+    // `version` — and NOT `renderToPipeableStream`, the Node-only API. A NAMED import of a missing
+    // export is a link-time error, so importing both by name made this entire bundle unloadable on
+    // every Web runtime, and the Web renderer it exists to provide could never be reached:
+    //
+    //     SyntaxError: Export named 'renderToPipeableStream' not found in module
+    //       .../react-dom/server.bun.js
+    //
+    // Measured on Bun 1.3.14 and Node 22 by importing the namespace on both: it loads on both, and the
+    // Node-only binding is a function on Node and `undefined` on Bun. The Node renderers below are
+    // never reached on a Web runtime — `renderBunEntry` calls `renderStreamingWeb` and nothing else —
+    // so the destructure is safe and the call sites keep their original text.
+    //
+    // A lazy `await import('react-dom/server')` was tried first and rejected: it cost a helper, an
+    // await inside a Promise executor that is not async, and it broke
+    // `entry-server-web-execution.test.ts`, which materializes the generated module in a temp
+    // directory where a dynamic specifier does not resolve.
+    `import * as __theoReactDOMServer from 'react-dom/server'`,
+    `const { renderToReadableStream, renderToPipeableStream } = __theoReactDOMServer`,
     `import { createStaticHandler, createStaticRouter, StaticRouterProvider, matchRoutes } from 'react-router'`,
     `import { routes, __theoPreloadMap, __theoPreloadPathsFor } from '/@theo/route-manifest'`,
     `import { NonceProvider } from 'theokit/client'`,
@@ -3030,19 +3067,21 @@ async function theoPluginAsync(rootOrOptions) {
   }
   const { assetsMapPlugin } = await import("./assets-map-CV2YZ3MY.js");
   const assetsMap = assetsMapPlugin({ appDir: resolve9(projectRoot, options.appDir ?? "app") });
-  const { appTypedClientPlugin } = await import("./app-typed-client-ILLQYTXP.js");
+  const { appTypedClientPlugin } = await import("./app-typed-client-EOA3A2AR.js");
   const appClientPlugin = appTypedClientPlugin({
     cwd: projectRoot,
     serverDir: serverDirAbs,
-    distDir: resolve9(projectRoot, ".theokit")
+    distDir: resolve9(projectRoot, ".theokit"),
+    // B-313 — the same name line 226 already passes. This call passed neither it nor the root.
+    agentsDir: agentsDirName
   });
-  const { actionsVirtualModule } = await import("./actions-virtual-module-OHENNMQG.js");
+  const { actionsVirtualModule } = await import("./actions-virtual-module-J2HYO7QZ.js");
   const actionsPlugin = actionsVirtualModule({
     serverDir: serverDirAbs,
     distDir: resolve9(projectRoot, ".theokit")
   });
   const { agentsTypedClientPlugin } = await import("./agents-typed-client-PVUZU65B.js");
-  const { generateManifest } = await import("./internal-api-6XNLCNI5.js");
+  const { generateManifest } = await import("./internal-api-ZUBUYGCQ.js");
   const agentsClientPlugin = agentsTypedClientPlugin({
     projectRoot,
     agentsDir: agentsDirName,
@@ -3059,7 +3098,7 @@ async function theoPluginAsync(rootOrOptions) {
   const controllerTransformPlugin = controllerSwcTransformPlugin({
     serverDir: serverDirAbs
   });
-  const { serverOnlyImportBoundary } = await import("./server-boundary-E5GFVPLB.js");
+  const { serverOnlyImportBoundary } = await import("./server-boundary-RTRPHX5I.js");
   const serverBoundaryPlugin = serverOnlyImportBoundary({
     projectRoot,
     serverDir: serverDirAbs
@@ -3087,7 +3126,7 @@ function buildOptimizeDepsInclude(projectRoot, viteOptimizeDeps) {
   if (existsSync8(resolve9(projectRoot, "node_modules", "lucide-react"))) {
     include.push("lucide-react");
   }
-  include.push("devalue");
+  include.push("theokit > devalue");
   if (Array.isArray(viteOptimizeDeps)) {
     for (const pkg of viteOptimizeDeps) {
       if (typeof pkg === "string" && pkg.length > 0 && !include.includes(pkg)) {
@@ -3241,6 +3280,7 @@ export {
   IntegrationRouteCollisionError,
   createIntegrationRegistry,
   theoPluginAsync,
+  buildOptimizeDepsInclude,
   theoPlugin
 };
-//# sourceMappingURL=chunk-D3M7LPHY.js.map
+//# sourceMappingURL=chunk-NQZIQJFH.js.map