@tangle-network/agent-app 0.43.24 → 0.43.26

package/dist/profile/index.js

@@ -9,6 +9,37 @@ import {
 // src/profile/index.ts
 import { mergeAgentProfiles } from "@tangle-network/sandbox";
 import { profile } from "@tangle-network/agent-eval";
+var DEFAULT_MAX_SYSTEM_PROMPT_BYTES = 4e4;
+function largestPromptSections(prompt, top = 3) {
+  const encoder = new TextEncoder();
+  const sections = [];
+  let title = "(preamble)";
+  let start = 0;
+  const flush = (end) => {
+    const body = prompt.slice(start, end);
+    if (body.trim()) sections.push({ title, bytes: encoder.encode(body).byteLength });
+  };
+  const headingRe = /^#{1,6}\s+(.+)$/gm;
+  for (const match of prompt.matchAll(headingRe)) {
+    flush(match.index);
+    title = (match[1] ?? "").trim() || "(untitled section)";
+    start = match.index;
+  }
+  flush(prompt.length);
+  return sections.sort((a, b) => b.bytes - a.bytes).slice(0, top);
+}
+function assertSystemPromptWithinBudget(systemPrompt, budget = {}) {
+  const max = budget.maxSystemPromptBytes ?? DEFAULT_MAX_SYSTEM_PROMPT_BYTES;
+  const bytes = new TextEncoder().encode(systemPrompt).byteLength;
+  if (bytes <= max) return;
+  const sections = largestPromptSections(systemPrompt).map((s) => `"${s.title}" (${s.bytes}B)`).join(", ");
+  const message = `composed systemPrompt is ${bytes} bytes \u2014 over the ${max}-byte budget (oversized prompts degrade to empty answers). ` + (sections ? `Largest sections: ${sections}. ` : "") + `Trim the prompt, move content to skills/knowledge mounts, or raise maxSystemPromptBytes deliberately.`;
+  if (budget.warnOnly) {
+    console.warn(`[profile] ${message}`);
+    return;
+  }
+  throw new Error(message);
+}
 function userSkillMounts(userSkills) {
   return userSkills.map(
     (s) => ({
@@ -17,7 +48,7 @@ function userSkillMounts(userSkills) {
     })
   ).sort((a, b) => a.path.localeCompare(b.path));
 }
-function composeAgentProfile(base, channels = {}, overlay = {}) {
+function composeAgentProfile(base, channels = {}, overlay = {}, budget = {}) {
   const shellInput = {
     skills: channels.skills,
     knowledge: channels.knowledge,
@@ -41,6 +72,8 @@ function composeAgentProfile(base, channels = {}, overlay = {}) {
   const merged = mergeAgentProfiles(base, overlayProfile);
   if (!merged)
     throw new Error("composeAgentProfile: mergeAgentProfiles returned undefined for a defined base");
+  const systemPrompt = merged.prompt?.systemPrompt;
+  if (typeof systemPrompt === "string") assertSystemPromptWithinBudget(systemPrompt, budget);
   return pruneEmptyResourceChannels(merged);
 }
 function pruneEmptyResourceChannels(profile2) {
@@ -61,9 +94,12 @@ function makeEvolvableSection(input) {
   return { id: input.id, title: input.title, body, evolvable: true };
 }
 export {
+  DEFAULT_MAX_SYSTEM_PROMPT_BYTES,
+  assertSystemPromptWithinBudget,
   composeAgentProfile,
   composeShellResources,
   corpusSkills,
+  largestPromptSections,
   loadMarkdownCorpus,
   makeEvolvableSection,
   profile,

package/dist/profile/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/profile/index.ts"],"sourcesContent":["/**\n * Profile composer + evolvable-section seam for agent products.\n *\n * The standard \"load a deployable AgentProfile, including skills, plus the\n * skills the end user added to their own instance\" entry point. A product holds\n * a canonical base `AgentProfile` (role/environment/tool-conventions rendered\n * into `prompt.systemPrompt`, baseline skills, baseline MCP). At deploy/turn\n * time it layers four file-mount channels onto `resources.files` —\n *\n *   1. skills      — the always-mounted product skill corpus\n *   2. knowledge   — a second always-mounted corpus (domain knowledge pack)\n *   3. registry    — the tier-gated installable registry (free -> boot-mounted)\n *   4. userSkills  — per-user / per-workspace skills the END USER adds to their\n *                    own instance, mounted at `~/.claude/skills/<id>/SKILL.md`\n *                    exactly like the registry's free tier\n *\n * plus an optional MCP overlay (delegation + per-turn app-tool side channel), a\n * per-turn `systemPrompt` override, and a `name` override. The merge is the SDK\n * `mergeAgentProfiles`: `mcp` is last-wins per key (base -> overlay), `resources`\n * arrays are concatenated (base ++ overlay), `prompt` is shallow-merged so an\n * overlay carrying only `systemPrompt` overrides it while keeping base\n * instructions. The compose algebra is DATA — the product injects the base\n * profile, the channel mounts (built with the `skills` subpath primitives), the\n * delegation/app-tool MCP map, and the override strings; nothing here reaches\n * for env, a glob, or a specific product's profile.\n *\n * The evolvable-section seam is the loader closure. A product's single\n * self-improvable domain section (the one `applyDomainPatch` targets) loads its\n * body from a deployed markdown override, falling back to an in-tree baseline.\n * The `import.meta.glob('<lit>', ...)` literal must stay at the CONSUMER call\n * site (Vite static-analyzes it), so `makeEvolvableSection` takes the loader as\n * a closure and a REQUIRED `baseline` — it never constructs a glob and never\n * defaults the baseline, so a product can't render an empty learned-guidance\n * section. `stripComments` is the shared \"is this addendum really empty?\" test.\n */\n\nimport type {\n  AgentProfile,\n  AgentProfileFileMount,\n  AgentProfileMcpServer,\n} from '@tangle-network/sandbox'\nimport { mergeAgentProfiles } from '@tangle-network/sandbox'\nimport { profile } from '@tangle-network/agent-eval'\nimport {\n  composeShellResources,\n  registrySkills,\n  skillMountPath,\n  type ComposeShellResourcesInput,\n  type SkillEntry,\n} from '../skills/index'\n\n/** Re-expose the agent-eval section/render substrate so a product wires the\n *  evolvable surface through ONE subpath: `makeEvolvableSection` builds the\n *  section, `profile.renderProfile` renders it, `profile.applyDomainPatch` lets\n *  the loop patch it by id. The rendering/patching engine stays in agent-eval;\n *  reach it through this namespace (re-exporting the bare fns would leak\n *  agent-eval's un-nameable AgentProfile type into our generated d.ts). */\nexport { profile }\n\n/** The file-mount channels layered onto `resources.files`. The first three\n *  mirror {@link ComposeShellResourcesInput}; `userSkills` is the per-user /\n *  per-workspace channel — skills the END USER added to their own instance,\n *  mounted at the harness skill-discovery path like the registry's free tier. */\nexport interface ProfileChannels {\n  /** Always-mounted skill corpus (pass `corpusSkills(...)`). */\n  skills?: AgentProfileFileMount[]\n  /** Always-mounted knowledge corpus (pass `corpusSkills(...)` for the pack). */\n  knowledge?: AgentProfileFileMount[]\n  /** Single-file evolvable / learned-guidance corpora, if mounted as files. */\n  evolvable?: AgentProfileFileMount[]\n  /** Tier-gated installable registry (pass the registry array; free tier is\n   *  mounted, paid is install-on-demand). Gated through {@link registrySkills}. */\n  registry?: SkillEntry[]\n  /** Per-user / per-workspace skills the end user adds to their own instance.\n   *  Mounted at `~/.claude/skills/<id>/SKILL.md`, the same harness path the\n   *  registry uses, so a user skill and a registry skill with the same id\n   *  collide deterministically (the user skill, appended last, wins). */\n  userSkills?: UserSkill[]\n  /** Final skip filter applied to the composed mount list by mount `path`. */\n  filesPredicate?: (mount: AgentProfileFileMount) => boolean\n}\n\n/** A per-user / per-workspace skill: an id and an inline `SKILL.md` body. The\n *  user-facing analogue of a registry {@link SkillEntry} with no tier gate —\n *  every user skill is mounted (the user opted in by adding it). */\nexport interface UserSkill {\n  id: string\n  /** Inline `SKILL.md` body mounted at {@link skillMountPath}. */\n  skillMd: string\n}\n\n/** Overlay overrides applied on top of the channel mounts. */\nexport interface ProfileOverlay {\n  /** Extra MCP servers merged into the profile `mcp` map (last-wins per key over\n   *  the base servers). The product builds this from its delegation MCP entry\n   *  and any per-turn app-tool side-channel servers. An absent/`undefined` entry\n   *  is dropped — pass only the servers that resolved (fail-closed at the seam,\n   *  not here). */\n  mcp?: Record<string, AgentProfileMcpServer>\n  /** Per-turn system-prompt override. When set, replaces the base\n   *  `prompt.systemPrompt` while keeping base `prompt.instructions`. When unset,\n   *  the base prompt passes through unchanged. */\n  systemPrompt?: string\n  /** Extra instruction lines merged onto the active prompt (e.g. a per-turn\n   *  domain/integration directive). Appended to base `prompt.instructions` by\n   *  the SDK merge. */\n  instructions?: string[]\n  /** Profile `name` override. When unset, the base name is kept. */\n  name?: string\n}\n\n/** Project per-user skills onto SDK file mounts at the harness skill-discovery\n *  path. No tier gate — a user skill is mounted because the user added it.\n *  Sorted by path for determinism (matches {@link registrySkills}). */\nexport function userSkillMounts(userSkills: UserSkill[]): AgentProfileFileMount[] {\n  return userSkills\n    .map(\n      (s) =>\n        ({\n          path: skillMountPath(s.id),\n          resource: { kind: 'inline', name: s.id, content: s.skillMd },\n        }) satisfies AgentProfileFileMount,\n    )\n    .sort((a, b) => a.path.localeCompare(b.path))\n}\n\n/**\n * Compose a deployable `AgentProfile` from a canonical base plus the four\n * file-mount channels and the overlay overrides.\n *\n * Files: base `resources.files` come first; the four channels follow in\n * `skills -> knowledge -> evolvable -> registry -> userSkills` order (so a\n * userSkill that mounts at the same path as a registry skill is the last write\n * and wins). MCP: base servers first, the overlay `mcp` last (last-wins per\n * key). Prompt: the overlay `systemPrompt`, when set, replaces the base one;\n * base instructions are preserved. Name: the overlay `name`, when set, wins.\n *\n * The merge delegates to the SDK `mergeAgentProfiles` (overlay-wins on records,\n * arrays concatenated) — the deterministic algebra is the overlay we hand it,\n * not a hand-rolled spread. `mergeAgentProfiles(base, overlay)` returns\n * `undefined` only when BOTH are `undefined`; `base` is always defined here, so\n * the result is non-`undefined` by construction and we assert that to the caller.\n */\nexport function composeAgentProfile(\n  base: AgentProfile,\n  channels: ProfileChannels = {},\n  overlay: ProfileOverlay = {},\n): AgentProfile {\n  const shellInput: ComposeShellResourcesInput = {\n    skills: channels.skills,\n    knowledge: channels.knowledge,\n    evolvable: channels.evolvable,\n    registry: channels.registry ? registrySkills(channels.registry) : undefined,\n    predicate: channels.filesPredicate,\n  }\n  const channelFiles = composeShellResources(shellInput)\n  const userFiles = channels.userSkills ? userSkillMounts(channels.userSkills) : []\n  const overlayFiles = channels.filesPredicate\n    ? userFiles.filter(channels.filesPredicate)\n    : userFiles\n  const files = [...channelFiles, ...overlayFiles]\n\n  const promptOverlay: { systemPrompt?: string; instructions?: string[] } = {}\n  if (overlay.systemPrompt) promptOverlay.systemPrompt = overlay.systemPrompt\n  if (overlay.instructions && overlay.instructions.length > 0) promptOverlay.instructions = overlay.instructions\n\n  const overlayProfile: AgentProfile = {\n    ...(overlay.name ? { name: overlay.name } : {}),\n    ...(Object.keys(promptOverlay).length > 0 ? { prompt: promptOverlay } : {}),\n    ...(overlay.mcp ? { mcp: overlay.mcp } : {}),\n    resources: { files },\n  }\n\n  const merged = mergeAgentProfiles(base, overlayProfile)\n  if (!merged)\n    throw new Error('composeAgentProfile: mergeAgentProfiles returned undefined for a defined base')\n  return pruneEmptyResourceChannels(merged)\n}\n\n/** Drop empty resource channels the SDK merge normalizes in (`tools`/`skills`/\n *  `agents`/`commands`: `[]`), so the composed profile's wire payload carries\n *  only the channels that actually have content — one canonical shape every app\n *  emits, instead of a sidecar payload full of empty arrays. */\nfunction pruneEmptyResourceChannels(profile: AgentProfile): AgentProfile {\n  if (!profile.resources) return profile\n  const kept = Object.fromEntries(\n    Object.entries(profile.resources).filter(([, value]) => !(Array.isArray(value) && value.length === 0)),\n  ) as AgentProfile['resources']\n  const out: AgentProfile = { ...profile, resources: kept }\n  if (kept && Object.keys(kept).length === 0) delete out.resources\n  return out\n}\n\n/** True body of an addendum file with HTML comments stripped — an all-comment\n *  placeholder counts as empty, so the loader falls back to the baseline. */\nexport function stripComments(raw: string): string {\n  return raw.replace(/<!--[\\s\\S]*?-->/g, '').trim()\n}\n\n/** Inputs to {@link makeEvolvableSection}. */\nexport interface EvolvableSectionInput {\n  /** Section id the self-improvement loop targets with `applyDomainPatch`. */\n  id: string\n  /** Section title rendered as `### <title>`. */\n  title: string\n  /**\n   * Load the deployed section body. The CONSUMER supplies this closure and runs\n   * its own `import.meta.glob('<lit>', { eager: true, query: '?raw', import:\n   * 'default' })` inside it — the literal must stay at the call site so Vite can\n   * static-analyze it; a glob constructed here would not resolve the product's\n   * files. Return the raw markdown (comments and all); `makeEvolvableSection`\n   * applies {@link stripComments} to decide whether it is really populated.\n   */\n  load: () => string\n  /**\n   * The in-tree fallback body, used when `load()` returns an\n   * all-comments/empty placeholder. REQUIRED — no internal default — so a\n   * product can never accidentally render an empty evolvable section.\n   */\n  baseline: string\n}\n\n/**\n * Build the one evolvable (`evolvable: true`) domain section whose body comes\n * from the product's loader, falling back to the required baseline when the\n * loaded body is empty after stripping comments. Returns the agent-eval\n * `AgentProfileSection` shape — drop it straight into `prodProfile`'s shipped\n * sections. The loader is the only seam; the empty-vs-populated rule and the\n * baseline fallback are the lifted algebra.\n */\nexport function makeEvolvableSection(input: EvolvableSectionInput): profile.AgentProfileSection {\n  const loaded = input.load()\n  const body = stripComments(loaded) ? loaded.trim() : input.baseline\n  return { id: input.id, title: input.title, body, evolvable: true }\n}\n\nexport {\n  composeShellResources,\n  corpusSkills,\n  loadMarkdownCorpus,\n  registrySkills,\n  skillMountPath,\n} from '../skills/index'\nexport type {\n  ComposeShellResourcesInput,\n  CorpusEntry,\n  CorpusLoadResult,\n  GlobModules,\n  LoadCorpusOptions,\n  SkillEntry,\n} from '../skills/index'\n"],"mappings":";;;;;;;;;AAyCA,SAAS,0BAA0B;AACnC,SAAS,eAAe;AAwEjB,SAAS,gBAAgB,YAAkD;AAChF,SAAO,WACJ;AAAA,IACC,CAAC,OACE;AAAA,MACC,MAAM,eAAe,EAAE,EAAE;AAAA,MACzB,UAAU,EAAE,MAAM,UAAU,MAAM,EAAE,IAAI,SAAS,EAAE,QAAQ;AAAA,IAC7D;AAAA,EACJ,EACC,KAAK,CAAC,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,IAAI,CAAC;AAChD;AAmBO,SAAS,oBACd,MACA,WAA4B,CAAC,GAC7B,UAA0B,CAAC,GACb;AACd,QAAM,aAAyC;AAAA,IAC7C,QAAQ,SAAS;AAAA,IACjB,WAAW,SAAS;AAAA,IACpB,WAAW,SAAS;AAAA,IACpB,UAAU,SAAS,WAAW,eAAe,SAAS,QAAQ,IAAI;AAAA,IAClE,WAAW,SAAS;AAAA,EACtB;AACA,QAAM,eAAe,sBAAsB,UAAU;AACrD,QAAM,YAAY,SAAS,aAAa,gBAAgB,SAAS,UAAU,IAAI,CAAC;AAChF,QAAM,eAAe,SAAS,iBAC1B,UAAU,OAAO,SAAS,cAAc,IACxC;AACJ,QAAM,QAAQ,CAAC,GAAG,cAAc,GAAG,YAAY;AAE/C,QAAM,gBAAoE,CAAC;AAC3E,MAAI,QAAQ,aAAc,eAAc,eAAe,QAAQ;AAC/D,MAAI,QAAQ,gBAAgB,QAAQ,aAAa,SAAS,EAAG,eAAc,eAAe,QAAQ;AAElG,QAAM,iBAA+B;AAAA,IACnC,GAAI,QAAQ,OAAO,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;AAAA,IAC7C,GAAI,OAAO,KAAK,aAAa,EAAE,SAAS,IAAI,EAAE,QAAQ,cAAc,IAAI,CAAC;AAAA,IACzE,GAAI,QAAQ,MAAM,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC;AAAA,IAC1C,WAAW,EAAE,MAAM;AAAA,EACrB;AAEA,QAAM,SAAS,mBAAmB,MAAM,cAAc;AACtD,MAAI,CAAC;AACH,UAAM,IAAI,MAAM,+EAA+E;AACjG,SAAO,2BAA2B,MAAM;AAC1C;AAMA,SAAS,2BAA2BA,UAAqC;AACvE,MAAI,CAACA,SAAQ,UAAW,QAAOA;AAC/B,QAAM,OAAO,OAAO;AAAA,IAClB,OAAO,QAAQA,SAAQ,SAAS,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,KAAK,KAAK,MAAM,WAAW,EAAE;AAAA,EACvG;AACA,QAAM,MAAoB,EAAE,GAAGA,UAAS,WAAW,KAAK;AACxD,MAAI,QAAQ,OAAO,KAAK,IAAI,EAAE,WAAW,EAAG,QAAO,IAAI;AACvD,SAAO;AACT;AAIO,SAAS,cAAc,KAAqB;AACjD,SAAO,IAAI,QAAQ,oBAAoB,EAAE,EAAE,KAAK;AAClD;AAiCO,SAAS,qBAAqB,OAA2D;AAC9F,QAAM,SAAS,MAAM,KAAK;AAC1B,QAAM,OAAO,cAAc,MAAM,IAAI,OAAO,KAAK,IAAI,MAAM;AAC3D,SAAO,EAAE,IAAI,MAAM,IAAI,OAAO,MAAM,OAAO,MAAM,WAAW,KAAK;AACnE;","names":["profile"]}
+{"version":3,"sources":["../../src/profile/index.ts"],"sourcesContent":["/**\n * Profile composer + evolvable-section seam for agent products.\n *\n * The standard \"load a deployable AgentProfile, including skills, plus the\n * skills the end user added to their own instance\" entry point. A product holds\n * a canonical base `AgentProfile` (role/environment/tool-conventions rendered\n * into `prompt.systemPrompt`, baseline skills, baseline MCP). At deploy/turn\n * time it layers four file-mount channels onto `resources.files` —\n *\n *   1. skills      — the always-mounted product skill corpus\n *   2. knowledge   — a second always-mounted corpus (domain knowledge pack)\n *   3. registry    — the tier-gated installable registry (free -> boot-mounted)\n *   4. userSkills  — per-user / per-workspace skills the END USER adds to their\n *                    own instance, mounted at `~/.claude/skills/<id>/SKILL.md`\n *                    exactly like the registry's free tier\n *\n * plus an optional MCP overlay (delegation + per-turn app-tool side channel), a\n * per-turn `systemPrompt` override, and a `name` override. The merge is the SDK\n * `mergeAgentProfiles`: `mcp` is last-wins per key (base -> overlay), `resources`\n * arrays are concatenated (base ++ overlay), `prompt` is shallow-merged so an\n * overlay carrying only `systemPrompt` overrides it while keeping base\n * instructions. The compose algebra is DATA — the product injects the base\n * profile, the channel mounts (built with the `skills` subpath primitives), the\n * delegation/app-tool MCP map, and the override strings; nothing here reaches\n * for env, a glob, or a specific product's profile.\n *\n * The evolvable-section seam is the loader closure. A product's single\n * self-improvable domain section (the one `applyDomainPatch` targets) loads its\n * body from a deployed markdown override, falling back to an in-tree baseline.\n * The `import.meta.glob('<lit>', ...)` literal must stay at the CONSUMER call\n * site (Vite static-analyzes it), so `makeEvolvableSection` takes the loader as\n * a closure and a REQUIRED `baseline` — it never constructs a glob and never\n * defaults the baseline, so a product can't render an empty learned-guidance\n * section. `stripComments` is the shared \"is this addendum really empty?\" test.\n */\n\nimport type {\n  AgentProfile,\n  AgentProfileFileMount,\n  AgentProfileMcpServer,\n} from '@tangle-network/sandbox'\nimport { mergeAgentProfiles } from '@tangle-network/sandbox'\nimport { profile } from '@tangle-network/agent-eval'\nimport {\n  composeShellResources,\n  registrySkills,\n  skillMountPath,\n  type ComposeShellResourcesInput,\n  type SkillEntry,\n} from '../skills/index'\n\n/** Re-expose the agent-eval section/render substrate so a product wires the\n *  evolvable surface through ONE subpath: `makeEvolvableSection` builds the\n *  section, `profile.renderProfile` renders it, `profile.applyDomainPatch` lets\n *  the loop patch it by id. The rendering/patching engine stays in agent-eval;\n *  reach it through this namespace (re-exporting the bare fns would leak\n *  agent-eval's un-nameable AgentProfile type into our generated d.ts). */\nexport { profile }\n\n/** The file-mount channels layered onto `resources.files`. The first three\n *  mirror {@link ComposeShellResourcesInput}; `userSkills` is the per-user /\n *  per-workspace channel — skills the END USER added to their own instance,\n *  mounted at the harness skill-discovery path like the registry's free tier. */\nexport interface ProfileChannels {\n  /** Always-mounted skill corpus (pass `corpusSkills(...)`). */\n  skills?: AgentProfileFileMount[]\n  /** Always-mounted knowledge corpus (pass `corpusSkills(...)` for the pack). */\n  knowledge?: AgentProfileFileMount[]\n  /** Single-file evolvable / learned-guidance corpora, if mounted as files. */\n  evolvable?: AgentProfileFileMount[]\n  /** Tier-gated installable registry (pass the registry array; free tier is\n   *  mounted, paid is install-on-demand). Gated through {@link registrySkills}. */\n  registry?: SkillEntry[]\n  /** Per-user / per-workspace skills the end user adds to their own instance.\n   *  Mounted at `~/.claude/skills/<id>/SKILL.md`, the same harness path the\n   *  registry uses, so a user skill and a registry skill with the same id\n   *  collide deterministically (the user skill, appended last, wins). */\n  userSkills?: UserSkill[]\n  /** Final skip filter applied to the composed mount list by mount `path`. */\n  filesPredicate?: (mount: AgentProfileFileMount) => boolean\n}\n\n/** A per-user / per-workspace skill: an id and an inline `SKILL.md` body. The\n *  user-facing analogue of a registry {@link SkillEntry} with no tier gate —\n *  every user skill is mounted (the user opted in by adding it). */\nexport interface UserSkill {\n  id: string\n  /** Inline `SKILL.md` body mounted at {@link skillMountPath}. */\n  skillMd: string\n}\n\n/** Overlay overrides applied on top of the channel mounts. */\nexport interface ProfileOverlay {\n  /** Extra MCP servers merged into the profile `mcp` map (last-wins per key over\n   *  the base servers). The product builds this from its delegation MCP entry\n   *  and any per-turn app-tool side-channel servers. An absent/`undefined` entry\n   *  is dropped — pass only the servers that resolved (fail-closed at the seam,\n   *  not here). */\n  mcp?: Record<string, AgentProfileMcpServer>\n  /** Per-turn system-prompt override. When set, replaces the base\n   *  `prompt.systemPrompt` while keeping base `prompt.instructions`. When unset,\n   *  the base prompt passes through unchanged. */\n  systemPrompt?: string\n  /** Extra instruction lines merged onto the active prompt (e.g. a per-turn\n   *  domain/integration directive). Appended to base `prompt.instructions` by\n   *  the SDK merge. */\n  instructions?: string[]\n  /** Profile `name` override. When unset, the base name is kept. */\n  name?: string\n}\n\n/** Byte budget on the FINAL composed `prompt.systemPrompt`. Past this the\n *  model degrades sharply (a 122,659-byte prompt shipped once and the model\n *  returned empty answers), so the default gate throws well before that. */\nexport const DEFAULT_MAX_SYSTEM_PROMPT_BYTES = 40_000\n\n/** Budget config for the composed system prompt. */\nexport interface ComposeProfileBudget {\n  /** Byte cap on the composed `prompt.systemPrompt`.\n   *  Default {@link DEFAULT_MAX_SYSTEM_PROMPT_BYTES}. */\n  maxSystemPromptBytes?: number\n  /** Downgrade the over-budget throw to a `console.warn` — the escape hatch\n   *  for a product with a known-big prompt that must still ship (it yells on\n   *  every compose instead of blocking). */\n  warnOnly?: boolean\n}\n\n/** Largest markdown-heading-delimited sections of a prompt, by UTF-8 bytes.\n *  Cheap heuristic: split on `#`-heading lines; the preamble before the first\n *  heading reports as \"(preamble)\". */\nexport function largestPromptSections(\n  prompt: string,\n  top = 3,\n): Array<{ title: string; bytes: number }> {\n  const encoder = new TextEncoder()\n  const sections: Array<{ title: string; bytes: number }> = []\n  let title = '(preamble)'\n  let start = 0\n  const flush = (end: number) => {\n    const body = prompt.slice(start, end)\n    if (body.trim()) sections.push({ title, bytes: encoder.encode(body).byteLength })\n  }\n  const headingRe = /^#{1,6}\\s+(.+)$/gm\n  for (const match of prompt.matchAll(headingRe)) {\n    flush(match.index)\n    title = (match[1] ?? '').trim() || '(untitled section)'\n    start = match.index\n  }\n  flush(prompt.length)\n  return sections.sort((a, b) => b.bytes - a.bytes).slice(0, top)\n}\n\n/** Enforce {@link ComposeProfileBudget} on a composed system prompt: over\n *  budget throws (or warns with `warnOnly`) with the actual size and the\n *  top-3 largest sections. Exported so a product assembling its prompt\n *  outside {@link composeAgentProfile} (e.g. via the `/prompt` assembler) can\n *  run the same gate at its own final-composition point. */\nexport function assertSystemPromptWithinBudget(\n  systemPrompt: string,\n  budget: ComposeProfileBudget = {},\n): void {\n  const max = budget.maxSystemPromptBytes ?? DEFAULT_MAX_SYSTEM_PROMPT_BYTES\n  const bytes = new TextEncoder().encode(systemPrompt).byteLength\n  if (bytes <= max) return\n  const sections = largestPromptSections(systemPrompt)\n    .map((s) => `\"${s.title}\" (${s.bytes}B)`)\n    .join(', ')\n  const message =\n    `composed systemPrompt is ${bytes} bytes — over the ${max}-byte budget ` +\n    `(oversized prompts degrade to empty answers). ` +\n    (sections ? `Largest sections: ${sections}. ` : '') +\n    `Trim the prompt, move content to skills/knowledge mounts, or raise maxSystemPromptBytes deliberately.`\n  if (budget.warnOnly) {\n    console.warn(`[profile] ${message}`)\n    return\n  }\n  throw new Error(message)\n}\n\n/** Project per-user skills onto SDK file mounts at the harness skill-discovery\n *  path. No tier gate — a user skill is mounted because the user added it.\n *  Sorted by path for determinism (matches {@link registrySkills}). */\nexport function userSkillMounts(userSkills: UserSkill[]): AgentProfileFileMount[] {\n  return userSkills\n    .map(\n      (s) =>\n        ({\n          path: skillMountPath(s.id),\n          resource: { kind: 'inline', name: s.id, content: s.skillMd },\n        }) satisfies AgentProfileFileMount,\n    )\n    .sort((a, b) => a.path.localeCompare(b.path))\n}\n\n/**\n * Compose a deployable `AgentProfile` from a canonical base plus the four\n * file-mount channels and the overlay overrides.\n *\n * Files: base `resources.files` come first; the four channels follow in\n * `skills -> knowledge -> evolvable -> registry -> userSkills` order (so a\n * userSkill that mounts at the same path as a registry skill is the last write\n * and wins). MCP: base servers first, the overlay `mcp` last (last-wins per\n * key). Prompt: the overlay `systemPrompt`, when set, replaces the base one;\n * base instructions are preserved. Name: the overlay `name`, when set, wins.\n *\n * The merge delegates to the SDK `mergeAgentProfiles` (overlay-wins on records,\n * arrays concatenated) — the deterministic algebra is the overlay we hand it,\n * not a hand-rolled spread. `mergeAgentProfiles(base, overlay)` returns\n * `undefined` only when BOTH are `undefined`; `base` is always defined here, so\n * the result is non-`undefined` by construction and we assert that to the caller.\n *\n * The composed `prompt.systemPrompt` is byte-budgeted here — the single point\n * where the FINAL prompt exists ({@link assertSystemPromptWithinBudget};\n * default {@link DEFAULT_MAX_SYSTEM_PROMPT_BYTES}, `warnOnly` escape hatch).\n */\nexport function composeAgentProfile(\n  base: AgentProfile,\n  channels: ProfileChannels = {},\n  overlay: ProfileOverlay = {},\n  budget: ComposeProfileBudget = {},\n): AgentProfile {\n  const shellInput: ComposeShellResourcesInput = {\n    skills: channels.skills,\n    knowledge: channels.knowledge,\n    evolvable: channels.evolvable,\n    registry: channels.registry ? registrySkills(channels.registry) : undefined,\n    predicate: channels.filesPredicate,\n  }\n  const channelFiles = composeShellResources(shellInput)\n  const userFiles = channels.userSkills ? userSkillMounts(channels.userSkills) : []\n  const overlayFiles = channels.filesPredicate\n    ? userFiles.filter(channels.filesPredicate)\n    : userFiles\n  const files = [...channelFiles, ...overlayFiles]\n\n  const promptOverlay: { systemPrompt?: string; instructions?: string[] } = {}\n  if (overlay.systemPrompt) promptOverlay.systemPrompt = overlay.systemPrompt\n  if (overlay.instructions && overlay.instructions.length > 0) promptOverlay.instructions = overlay.instructions\n\n  const overlayProfile: AgentProfile = {\n    ...(overlay.name ? { name: overlay.name } : {}),\n    ...(Object.keys(promptOverlay).length > 0 ? { prompt: promptOverlay } : {}),\n    ...(overlay.mcp ? { mcp: overlay.mcp } : {}),\n    resources: { files },\n  }\n\n  const merged = mergeAgentProfiles(base, overlayProfile)\n  if (!merged)\n    throw new Error('composeAgentProfile: mergeAgentProfiles returned undefined for a defined base')\n  // Byte-budget gate on the FINAL composed systemPrompt — this is the single\n  // point where every channel and overlay has been merged in.\n  const systemPrompt = merged.prompt?.systemPrompt\n  if (typeof systemPrompt === 'string') assertSystemPromptWithinBudget(systemPrompt, budget)\n  return pruneEmptyResourceChannels(merged)\n}\n\n/** Drop empty resource channels the SDK merge normalizes in (`tools`/`skills`/\n *  `agents`/`commands`: `[]`), so the composed profile's wire payload carries\n *  only the channels that actually have content — one canonical shape every app\n *  emits, instead of a sidecar payload full of empty arrays. */\nfunction pruneEmptyResourceChannels(profile: AgentProfile): AgentProfile {\n  if (!profile.resources) return profile\n  const kept = Object.fromEntries(\n    Object.entries(profile.resources).filter(([, value]) => !(Array.isArray(value) && value.length === 0)),\n  ) as AgentProfile['resources']\n  const out: AgentProfile = { ...profile, resources: kept }\n  if (kept && Object.keys(kept).length === 0) delete out.resources\n  return out\n}\n\n/** True body of an addendum file with HTML comments stripped — an all-comment\n *  placeholder counts as empty, so the loader falls back to the baseline. */\nexport function stripComments(raw: string): string {\n  return raw.replace(/<!--[\\s\\S]*?-->/g, '').trim()\n}\n\n/** Inputs to {@link makeEvolvableSection}. */\nexport interface EvolvableSectionInput {\n  /** Section id the self-improvement loop targets with `applyDomainPatch`. */\n  id: string\n  /** Section title rendered as `### <title>`. */\n  title: string\n  /**\n   * Load the deployed section body. The CONSUMER supplies this closure and runs\n   * its own `import.meta.glob('<lit>', { eager: true, query: '?raw', import:\n   * 'default' })` inside it — the literal must stay at the call site so Vite can\n   * static-analyze it; a glob constructed here would not resolve the product's\n   * files. Return the raw markdown (comments and all); `makeEvolvableSection`\n   * applies {@link stripComments} to decide whether it is really populated.\n   */\n  load: () => string\n  /**\n   * The in-tree fallback body, used when `load()` returns an\n   * all-comments/empty placeholder. REQUIRED — no internal default — so a\n   * product can never accidentally render an empty evolvable section.\n   */\n  baseline: string\n}\n\n/**\n * Build the one evolvable (`evolvable: true`) domain section whose body comes\n * from the product's loader, falling back to the required baseline when the\n * loaded body is empty after stripping comments. Returns the agent-eval\n * `AgentProfileSection` shape — drop it straight into `prodProfile`'s shipped\n * sections. The loader is the only seam; the empty-vs-populated rule and the\n * baseline fallback are the lifted algebra.\n */\nexport function makeEvolvableSection(input: EvolvableSectionInput): profile.AgentProfileSection {\n  const loaded = input.load()\n  const body = stripComments(loaded) ? loaded.trim() : input.baseline\n  return { id: input.id, title: input.title, body, evolvable: true }\n}\n\nexport {\n  composeShellResources,\n  corpusSkills,\n  loadMarkdownCorpus,\n  registrySkills,\n  skillMountPath,\n} from '../skills/index'\nexport type {\n  ComposeShellResourcesInput,\n  CorpusEntry,\n  CorpusLoadResult,\n  GlobModules,\n  LoadCorpusOptions,\n  SkillEntry,\n} from '../skills/index'\n"],"mappings":"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","names":["profile"]}

package/dist/sandbox/index.d.ts

@@ -384,6 +384,52 @@ interface WriteProfileFilesOptions {
     maxRetries?: number;
 }
 declare function writeProfileFilesToBox(box: SandboxInstance, files: AgentProfileFileMount[], options?: WriteProfileFilesOptions): Promise<Outcome<void>>;
+/** Gate on the provision body: the platform orchestrator caps the create
+ *  payload at 256 KiB; 240 KB leaves headroom for transport framing. An
+ *  over-cap payload fails provisioning 100% of the time (a 282 KB payload
+ *  shipped once and no sandbox could ever be created). */
+declare const PROVISION_PAYLOAD_MAX_BYTES = 240000;
+/** Per-variable env gate: the kernel rejects any single `NAME=value` env entry
+ *  over MAX_ARG_STRLEN (131072 bytes) with E2BIG, killing every exec inside
+ *  the box. 120 KB leaves headroom for the name and framing. */
+declare const ENV_VALUE_MAX_BYTES = 120000;
+/** Total env gate: the whole environment block shares the payload budget with
+ *  the profile; past 200 KB the provision body cannot stay under the cap. */
+declare const ENV_TOTAL_MAX_BYTES = 200000;
+/** Structural slice of the profile the payload gate reads: it only measures
+ *  the profile's serialized size and names `resources.files` in the breakdown,
+ *  so callers composing a payload outside the SDK (products, tests) can pass a
+ *  plain object without casting through `AgentProfile`. */
+interface ProvisionProfileSection {
+    resources?: {
+        files?: readonly unknown[];
+    };
+}
+/** The provision-payload sections the size gates need to see. Structural so
+ *  the gate is testable without the SDK's (unexported) create-payload type. */
+interface ProvisionPayloadSections {
+    env?: Record<string, string>;
+    secrets?: readonly string[];
+    /** `profile` may also be a named-profile string ref (the SDK's
+     *  `BackendConfig` union) — a string ref is tiny and has no files channel. */
+    backend?: {
+        profile?: string | ProvisionProfileSection;
+    };
+}
+/**
+ * Throw when the serialized provision payload exceeds
+ * {@link PROVISION_PAYLOAD_MAX_BYTES}. The error carries a per-section byte
+ * breakdown (profile/files/env/secrets) so the offending channel is named, not
+ * guessed.
+ */
+declare function assertProvisionPayloadWithinCap(payload: ProvisionPayloadSections): void;
+/**
+ * Throw when any single env value exceeds {@link ENV_VALUE_MAX_BYTES} or the
+ * whole env block exceeds {@link ENV_TOTAL_MAX_BYTES}, naming the offending
+ * variable. This is the E2BIG incident class: the box may even provision, but
+ * every exec inside it dies on the oversized entry.
+ */
+declare function assertEnvWithinLimits(env: Record<string, string>): void;
 declare function ensureWorkspaceSandbox(shell: SandboxRuntimeConfig, options: EnsureWorkspaceSandboxOptions): Promise<SandboxInstance>;
 interface ResolvedModel {
     model: string;
@@ -485,4 +531,4 @@ declare function classifySeveredStream(event: unknown): SandboxStepTransition |
 declare function isTerminalPromptEvent(event: unknown): boolean;
 declare function detectInteractiveQuestion(event: unknown): string | null;
 
-export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type Outcome, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxPermissionLevel, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, readSecret, resetClientCache, resolveModel, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, splitDeferredProfileFiles, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };
+export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type Outcome, PROVISION_PAYLOAD_MAX_BYTES, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxPermissionLevel, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, readSecret, resetClientCache, resolveModel, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, splitDeferredProfileFiles, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };

package/dist/sandbox/index.js

@@ -1,6 +1,11 @@
 import {
   DEFAULT_SANDBOX_RESOURCES,
+  ENV_TOTAL_MAX_BYTES,
+  ENV_VALUE_MAX_BYTES,
+  PROVISION_PAYLOAD_MAX_BYTES,
   SandboxRuntimeAuthRefreshError,
+  assertEnvWithinLimits,
+  assertProvisionPayloadWithinCap,
   attachReasoningEffort,
   bearerSubprotocolToken,
   bearerToken,
@@ -48,7 +53,7 @@ import {
   verifySandboxTerminalToken,
   verifyTerminalProxyToken,
   writeProfileFilesToBox
-} from "../chunk-3PK3T4KD.js";
+} from "../chunk-JJGZ54EB.js";
 import "../chunk-E7QYOOON.js";
 import "../chunk-3II3AWHY.js";
 import "../chunk-7EVZUIHW.js";
@@ -56,7 +61,12 @@ import "../chunk-7W5XSTUF.js";
 import "../chunk-MFRCM32T.js";
 export {
   DEFAULT_SANDBOX_RESOURCES,
+  ENV_TOTAL_MAX_BYTES,
+  ENV_VALUE_MAX_BYTES,
+  PROVISION_PAYLOAD_MAX_BYTES,
   SandboxRuntimeAuthRefreshError,
+  assertEnvWithinLimits,
+  assertProvisionPayloadWithinCap,
   attachReasoningEffort,
   bearerSubprotocolToken,
   bearerToken,

package/dist/sso-CNOsARMJ.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Request guards for agent-app routes: session auth (302 redirect for pages,
+ * JSON 401 for APIs), admin allowlisting (404 — the route stays invisible to
+ * non-admins), and the billable-balance gate (402 with a stable code).
+ * Session resolution is a seam; thrown Responses follow the router convention
+ * of surfacing a thrown Response as the route result.
+ */
+interface AuthGuardOptions<Session> {
+    /** e.g. a better-auth `auth.api.getSession` wrapped by the app. */
+    getSession(request: Request): Promise<Session | null | undefined>;
+    /** Default '/login'. */
+    loginPath?: string;
+}
+interface AuthGuard<Session> {
+    /** Page guard — throws a 302 redirect Response to `loginPath`. */
+    requireUser(request: Request): Promise<Session>;
+    /** API guard — throws JSON 401 `{ error: 'Unauthorized', code: 'auth.unauthenticated' }`. */
+    requireApiUser(request: Request): Promise<Session>;
+    /** `apiResponse` selects the 401 JSON path over the redirect. */
+    requireSession(request: Request, opts?: {
+        apiResponse?: boolean;
+    }): Promise<Session>;
+    getOptionalSession(request: Request): Promise<Session | null>;
+}
+declare function createAuthGuard<Session>(opts: AuthGuardOptions<Session>): AuthGuard<Session>;
+type GuardResolution<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    response: Response;
+};
+/**
+ * Adapt a guard that THROWS a Response (the quartet above — the router
+ * convention) to the `{ok: true, value} | {ok: false, response}` resolution
+ * shape the route factories take (`/chat-routes` `authorize`,
+ * `/interactions` `resolveConnection`, `/chat-routes` upload `authorize`).
+ * Every product wrote this try/catch by hand; it lives here once.
+ */
+declare function guardResolution<T>(run: () => Promise<T>): Promise<GuardResolution<T>>;
+/** Comma/whitespace separated → trimmed, lowercased, empties dropped. */
+declare function parseAdminEmails(raw: string | null | undefined): string[];
+interface AdminGuardOptions<Session> {
+    requireUser(request: Request): Promise<Session>;
+    emailOf(session: Session): string | null | undefined;
+    /** Resolved per request; an EMPTY allowlist refuses everyone. */
+    allowedEmails(): string[];
+}
+/** Non-admins (and empty allowlists) get 404, keeping the route invisible —
+ *  better than a "forbidden" footprint that advertises its existence. */
+declare function createAdminGuard<Session>(opts: AdminGuardOptions<Session>): (request: Request) => Promise<Session>;
+interface BillableBalanceState {
+    overageAllowed: boolean;
+    remainingBalanceUsd: number;
+}
+interface AssertBillableBalanceOptions {
+    env?: Record<string, string | undefined>;
+    /** App-specific enforcement override flag (e.g. 'GTM_BILLING_ENFORCEMENT'),
+     *  fed to `isTangleBillingEnforcementDisabled`. */
+    enforcementEnvVar?: string;
+    /** Default 'Add balance or upgrade your plan to invoke this agent.'. */
+    errorMessage?: string;
+    /** Merged into the 402 JSON body (e.g. `{ organizationId }`). */
+    errorBody?: Record<string, unknown>;
+}
+/**
+ * Gate a billable turn: passes when enforcement is disabled (dev default),
+ * the tier allows overage, or remaining balance is positive. Otherwise throws
+ * a 402 Response with the stable `billing.balance_required` code so clients
+ * can route to the billing screen.
+ */
+declare function assertBillableBalance(state: BillableBalanceState, opts?: AssertBillableBalanceOptions): void;
+
+/**
+ * Cross-site Tangle SSO for agent apps: signed-state CSRF cookies plus the
+ * full start/callback orchestration against the platform's /cross-site
+ * bridge. The platform wire client and account persistence are structural
+ * seams (`TangleSsoAuthClient` / `TangleSsoAccountStore`), so this module
+ * never imports agent-runtime, an auth framework, or a database driver.
+ * WebCrypto only — runs in workerd without node compatibility flags.
+ */
+interface SsoStateConfig {
+    /** HMAC-SHA256 secret (e.g. the app's auth secret). */
+    secret: string;
+    /** State lifetime in ms. Default 600 000. */
+    ttlMs?: number;
+    /** Injectable clock (ms since epoch). Default Date.now. */
+    now?: () => number;
+}
+/** Mint a `<randomHex32>.<timestamp36>.<hmacHex>` state value. The timestamp
+ *  is inside the signed payload, so expiry survives cookie-attribute tampering. */
+declare function createSignedSsoState(config: SsoStateConfig): Promise<string>;
+/** Verify the MAC (constant-time) and the signed TTL. */
+declare function verifySignedSsoState(state: string, config: SsoStateConfig): Promise<boolean>;
+interface TangleSsoExchangeResult {
+    apiKey: string;
+    user: {
+        id: string;
+        email: string;
+        name?: string | null;
+    };
+    plan?: {
+        tier: string;
+    } | null;
+}
+/** Structural mirror of the platform auth wire client — any object with these
+ *  two methods satisfies it without this module importing the concrete class. */
+interface TangleSsoAuthClient {
+    authorizeUrl(options: {
+        state: string;
+        redirectUri?: string;
+    }): string;
+    exchange(code: string): Promise<TangleSsoExchangeResult>;
+}
+/** Thrown by `upsertUserByEmail` when the app-local user row cannot be
+ *  created; the callback handler maps it to `?error=tangle_user_create_failed`.
+ *  Any other store error propagates. */
+declare class TangleSsoUserCreateError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Account persistence seam. Covers both storage styles in use: link-table
+ * apps (a per-user platform-link row) and session-column apps (the key on the
+ * session row) — `saveTangleLink` receives both `userId` and `sessionToken`,
+ * and each app persists with the key it needs. `createSession` runs first so
+ * the token is always available to `saveTangleLink`.
+ */
+interface TangleSsoAccountStore {
+    /** Find-or-create the app-local user. `tangleUserId` is the platform's
+     *  stable user id — match on it first when the app stores it (emails are
+     *  mutable on the platform; the id is not), falling back to email for
+     *  first-time logins. */
+    upsertUserByEmail(input: {
+        email: string;
+        name: string | null;
+        tangleUserId: string;
+    }): Promise<{
+        userId: string;
+    }>;
+    /** Create an app session row; returns the session-cookie token value. */
+    createSession(input: {
+        userId: string;
+        expiresAt: Date;
+        ipAddress: string | null;
+        userAgent: string | null;
+    }): Promise<{
+        token: string;
+    }>;
+    /** Persist the platform link (API key + platform identity). */
+    saveTangleLink(input: {
+        userId: string;
+        sessionToken: string;
+        tangleUserId: string;
+        email: string;
+        name: string | null;
+        apiKey: string;
+        planTier: string | null;
+    }): Promise<void>;
+}
+/** Successful-login context handed to the `setSessionCookie` seam. */
+interface TangleSsoSessionCookieArgs {
+    /** Session token returned by `store.createSession`. */
+    token: string;
+    /** Session expiry (now + `sessionTtlSeconds`). */
+    expiresAt: Date;
+    /** Mirrors `sessionTtlSeconds` after defaulting. */
+    ttlSeconds: number;
+    /** Mirrors `TangleSsoHandlerOptions.secureCookies`. */
+    secure: boolean;
+}
+/**
+ * Sign a session token to better-call's signed-cookie contract — the value
+ * better-auth's `getSignedCookie` verifies: `<token>.<signature>` where the
+ * signature is the raw HMAC-SHA256 of the token under `secret`, encoded as
+ * STANDARD base64 WITH padding (32 bytes → 44 chars ending `=`; better-call
+ * rejects any other length or suffix, so url-safe/unpadded variants read back
+ * as a null session). The joined value is percent-encoded once at cookie
+ * serialization, matching better-call's `serializeSignedCookie` byte-exactly.
+ */
+declare function signSessionCookieValue(token: string, secret: string): Promise<string>;
+/** Structural slice of a `betterAuth()` instance — only what cookie minting
+ *  reads. No better-auth import: the signing contract is implemented by
+ *  `signSessionCookieValue`, byte-compatible with better-auth's own
+ *  `makeSignature`. */
+interface BetterAuthSessionCookieSource {
+    $context: PromiseLike<{
+        secret: string;
+        authCookies: {
+            sessionToken: {
+                /** Final cookie name — better-auth decides the `__Secure-` prefix
+                 *  (and any `advanced.cookiePrefix`) once at `betterAuth()` init. */
+                name: string;
+                attributes: {
+                    secure?: boolean;
+                    sameSite?: string;
+                    path?: string;
+                    httpOnly?: boolean;
+                    domain?: string;
+                };
+            };
+        };
+    }>;
+}
+interface BetterAuthSessionCookieMinterOptions {
+    /** Receives the shadowed-cookie-name warning (see below). Default
+     *  console.warn. */
+    warn?: (message: string) => void;
+}
+/**
+ * Canonical `setSessionCookie` wiring for better-auth apps: mint the session
+ * Set-Cookie exactly as better-auth's own login flows do — name + attributes
+ * from `auth.$context.authCookies.sessionToken` (better-auth stays
+ * authoritative over prefix/name/attributes) and the value signed to
+ * better-call's `getSignedCookie` contract. A raw unprefixed
+ * `better-auth.session_token` left by an earlier login is explicitly expired
+ * so it cannot shadow the real cookie.
+ *
+ * Warns when the app's session cookie still has better-auth's DEFAULT name:
+ * the Tangle platform (id.tangle.tools) sets a `Domain=.tangle.tools` cookie
+ * under that exact name, and equal-path cookies are sent oldest-first — the
+ * platform's cookie is always older (the user signs in there before the app's
+ * callback runs), so the app reads the platform's token, fails its own
+ * signature check, and every fresh login lands logged-out. Per-app
+ * `advanced.cookiePrefix` is the fix.
+ *
+ * Throws on a domain-scoped session cookie for the same reason: a
+ * `Domain=`-wide session cookie is exactly the shadowing footgun.
+ */
+declare function createBetterAuthSessionCookieMinter(auth: BetterAuthSessionCookieSource, options?: BetterAuthSessionCookieMinterOptions): (args: TangleSsoSessionCookieArgs) => Promise<string[]>;
+interface TangleSsoHandlerOptions {
+    auth: TangleSsoAuthClient;
+    store: TangleSsoAccountStore;
+    /** HMAC secret for the state cookie. */
+    stateSecret: string;
+    /** Absolute callback URL registered with the platform. */
+    callbackUrl: string;
+    stateCookieName: string;
+    /** Default 'better-auth.session_token'. Ignored when `setSessionCookie` is
+     *  provided. The default path prepends `__Secure-` iff `secureCookies`. */
+    sessionCookieName?: string;
+    /** Mint the host auth framework's own session cookie(s); return complete
+     *  Set-Cookie header values (the handler appends them verbatim and sets no
+     *  session cookie itself). Supply this when the framework should stay
+     *  authoritative over name/prefix/signing/attributes — e.g. better-auth:
+     *  `auth.$context.authCookies.sessionToken` + `makeSignature`. */
+    setSessionCookie?: (args: TangleSsoSessionCookieArgs) => readonly string[] | Promise<readonly string[]>;
+    /** HMAC-SHA256 secret the host auth framework verifies session cookies with
+     *  (better-auth: its `secret`). Required when `setSessionCookie` is absent —
+     *  the default cookie is minted to better-call's signed contract via
+     *  `signSessionCookieValue`; an unsigned or mis-signed value reads back as a
+     *  null session, so there is deliberately no fallback to `stateSecret`
+     *  (which is not guaranteed to be the auth secret). */
+    sessionCookieSecret?: string;
+    /** Adds `Secure` to every cookie this module sets, and (default session
+     *  cookie only) the `__Secure-` name prefix. Must match the auth
+     *  framework's own secure-cookie decision (better-auth: https `baseURL` /
+     *  `advanced.useSecureCookies`), or it will look up a different cookie name
+     *  than the one set here. */
+    secureCookies: boolean;
+    /** Default 604 800 (7 days). */
+    sessionTtlSeconds?: number;
+    /** Default 600. Applies to both the cookie Max-Age and the signed TTL. */
+    stateTtlSeconds?: number;
+    /** Default '/app'. */
+    defaultRedirectPath?: string;
+    /** Default '/login'. */
+    loginPath?: string;
+    /** Failure log hook (e.g. console.error). Default no-op. */
+    log?: (message: string, error?: unknown) => void;
+    now?: () => number;
+}
+interface TangleSsoHandlers {
+    /** GET start route: mint + sign state, set the state cookie, 302 to the
+     *  platform authorize URL. `?redirect=` carries the post-login path. */
+    start(request: Request): Promise<Response>;
+    /** GET callback route: verify state, exchange the code, upsert the user,
+     *  create the session, save the platform link, set the session cookie
+     *  (via the `setSessionCookie` seam, else signed to better-call's contract
+     *  with `sessionCookieSecret`), 302 to the saved redirect. Every failure
+     *  302s to `loginPath?error=…` with the state cookie cleared. */
+    callback(request: Request): Promise<Response>;
+}
+declare function createTangleSsoHandlers(opts: TangleSsoHandlerOptions): TangleSsoHandlers;
+
+export { type AuthGuard as A, type BetterAuthSessionCookieMinterOptions as B, type GuardResolution as G, type SsoStateConfig as S, type TangleSsoHandlers as T, type TangleSsoAuthClient as a, type TangleSsoAccountStore as b, type AdminGuardOptions as c, type AssertBillableBalanceOptions as d, type AuthGuardOptions as e, type BetterAuthSessionCookieSource as f, type BillableBalanceState as g, type TangleSsoExchangeResult as h, type TangleSsoHandlerOptions as i, type TangleSsoSessionCookieArgs as j, TangleSsoUserCreateError as k, assertBillableBalance as l, createAdminGuard as m, createAuthGuard as n, createBetterAuthSessionCookieMinter as o, createSignedSsoState as p, createTangleSsoHandlers as q, guardResolution as r, parseAdminEmails as s, signSessionCookieValue as t, verifySignedSsoState as v };

package/dist/stream/index.js

@@ -23,7 +23,7 @@ import {
   resolveChatTurn,
   resolveToolId,
   resolveToolName
-} from "../chunk-77RLNLFP.js";
+} from "../chunk-ATRJULKZ.js";
 export {
   TURN_EVENTS_MIGRATION_SQL,
   TURN_STATUS_SCOPE_MIGRATION_SQL,

package/dist/teams/index.js

@@ -3,6 +3,15 @@ import {
   isInviteTokenShape,
   validateInviteToken
 } from "../chunk-3SVAA3MA.js";
+import {
+  INVITATION_EXPIRY_DAYS,
+  generateInvitationToken,
+  getInvitationExpiresAt,
+  inviteUrlForToken,
+  normalizeInvitationEmail,
+  parseInvitationPermission,
+  renderInvitationEmail
+} from "../chunk-WEBBJBDH.js";
 import {
   ASSIGNABLE_WORKSPACE_ROLES,
   ORGANIZATION_ROLES,
@@ -18,15 +27,6 @@ import {
   workspaceRoleToCollaborationAccess,
   workspaceRoleToSandboxRole
 } from "../chunk-63CE7FEZ.js";
-import {
-  INVITATION_EXPIRY_DAYS,
-  generateInvitationToken,
-  getInvitationExpiresAt,
-  inviteUrlForToken,
-  normalizeInvitationEmail,
-  parseInvitationPermission,
-  renderInvitationEmail
-} from "../chunk-WEBBJBDH.js";
 export {
   ASSIGNABLE_WORKSPACE_ROLES,
   INVITATION_EXPIRY_DAYS,

package/dist/teams/invitations-api.js

@@ -2,9 +2,6 @@ import {
   SeatLimitError
 } from "../chunk-SWUVTGMR.js";
 import "../chunk-3SVAA3MA.js";
-import {
-  hasWorkspaceRole
-} from "../chunk-63CE7FEZ.js";
 import {
   generateInvitationToken,
   getInvitationExpiresAt,
@@ -12,6 +9,9 @@ import {
   normalizeInvitationEmail,
   parseInvitationPermission
 } from "../chunk-WEBBJBDH.js";
+import {
+  hasWorkspaceRole
+} from "../chunk-63CE7FEZ.js";
 
 // src/teams/invitations-api.ts
 import { and, eq, lte, sql } from "drizzle-orm";