@tangle-network/agent-app 0.18.0 → 0.20.0

package/dist/model-resolution/index.js

@@ -0,0 +1,76 @@
+// src/model-resolution/index.ts
+function canonicalModelId(model) {
+  if (model.id.includes("/")) return model.id;
+  const provider = model._provider ?? model.provider;
+  return provider ? `${provider}/${model.id}` : model.id;
+}
+function resolveChatModel(input) {
+  const request = cleanModelId(input.requestModel);
+  if (request) return { model: request, source: "request" };
+  const workspace = cleanModelId(input.workspaceModel);
+  if (workspace) return { model: workspace, source: "workspace" };
+  const env = cleanModelId(input.envModel);
+  if (env) return { model: env, source: "env" };
+  return { model: input.defaultModel, source: "default" };
+}
+async function validateChatModelId(modelId, input) {
+  const cleaned = cleanModelId(modelId);
+  if (!cleaned) return { succeeded: false, error: "Model id must be a non-empty string." };
+  if (!isWellFormedModelId(cleaned)) return { succeeded: false, error: `Model id is malformed: ${cleaned}` };
+  const allowed = new Set(input.allowlist ?? []);
+  if (allowed.has(cleaned)) return { succeeded: true, value: cleaned };
+  if (cleanModelId(input.envModel) === cleaned) return { succeeded: true, value: cleaned };
+  if (!input.loadModels || typeof input.routerBaseUrl !== "string" || input.routerBaseUrl.length === 0) {
+    return { succeeded: false, error: `Model is not available: ${cleaned}` };
+  }
+  let catalog;
+  try {
+    catalog = await input.loadModels(input.routerBaseUrl);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { succeeded: false, error: `Could not validate model catalog: ${message}` };
+  }
+  const ids = new Set(catalog.flatMap(catalogIdsForModel));
+  if (ids.has(cleaned)) return { succeeded: true, value: cleaned };
+  if (!cleaned.includes("/")) {
+    const canonicalBySuffix = /* @__PURE__ */ new Map();
+    for (const model of catalog) {
+      if (typeof model.id !== "string" || !model.id.trim()) continue;
+      const canonical = canonicalModelId(model);
+      if (!canonical.includes("/")) continue;
+      const suffix = canonical.split("/").slice(1).join("/");
+      const entries = canonicalBySuffix.get(suffix);
+      if (entries) entries.push(canonical);
+      else canonicalBySuffix.set(suffix, [canonical]);
+    }
+    const matches = canonicalBySuffix.get(cleaned);
+    if (matches && matches.length === 1) return { succeeded: true, value: matches[0] };
+  }
+  return { succeeded: false, error: `Model is not available: ${cleaned}` };
+}
+function cleanModelId(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function isWellFormedModelId(modelId) {
+  if (modelId.length > 200) return false;
+  return /^[A-Za-z0-9._/@:-]+$/.test(modelId);
+}
+function catalogIdsForModel(model) {
+  const ids = /* @__PURE__ */ new Set();
+  if (typeof model.id === "string" && model.id.trim()) ids.add(model.id.trim());
+  if (typeof model.id === "string" && model.id.trim() && !model.id.includes("/")) {
+    const canonical = canonicalModelId(model);
+    if (canonical.includes("/")) ids.add(canonical);
+  }
+  return [...ids];
+}
+export {
+  catalogIdsForModel,
+  cleanModelId,
+  isWellFormedModelId,
+  resolveChatModel,
+  validateChatModelId
+};
+//# sourceMappingURL=index.js.map

package/dist/model-resolution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/model-resolution/index.ts"],"sourcesContent":["/**\n * Canonical chat-model resolution — identical across every agent app.\n *\n * The ONLY per-app inputs are DATA, never logic: the default model, the\n * allowlist, the env value the deployment set, and the catalog-fetch loader.\n * The logic is one precedence ladder + one fail-closed validator that every\n * product uses the same way — there is no per-product variant, no env-var name\n * baked in, and no backend dimension (router-vs-sandbox is the harness/dispatch\n * concern, not model resolution; a sandbox's provider default lives in the\n * sandbox subpath).\n *\n * - resolveChatModel: request > workspace > env > default. The product reads its\n *   own deploy env var and passes the VALUE as `envModel`; the shell knows no\n *   env-var names. Source is canonical: 'request' | 'workspace' | 'env' | 'default'.\n * - validateChatModelId: fail-closed. Admit an id that is in the allowlist, or\n *   equals the operator-set env model, or is served by the live router catalog\n *   (exact, or a bare id resolved to its canonical id when the suffix is unique).\n */\n\n/** The router /v1/models entry shape this module reads. Minimal on purpose. */\nexport interface ModelInfo {\n  id: string\n  name?: string\n  _provider?: string\n  provider?: string\n}\n\n/** Canonical (provider-prefixed) id for a catalog entry: pass through an id that\n *  already carries a provider, else prefix the entry's provider when present. */\nfunction canonicalModelId(model: ModelInfo): string {\n  if (model.id.includes('/')) return model.id\n  const provider = model._provider ?? model.provider\n  return provider ? `${provider}/${model.id}` : model.id\n}\n\nexport type ChatModelSource = 'request' | 'workspace' | 'env' | 'default'\n\nexport interface ResolvedChatModel {\n  model: string\n  source: ChatModelSource\n}\n\nexport interface ChatModelValidationSuccess {\n  succeeded: true\n  value: string\n}\n\nexport interface ChatModelValidationFailure {\n  succeeded: false\n  error: string\n}\n\nexport type ChatModelValidationResult = ChatModelValidationSuccess | ChatModelValidationFailure\n\n/** The catalog-fetch boundary: maps a router base URL to the raw model list. */\nexport type LoadModels = (routerBaseUrl: string) => Promise<ModelInfo[]>\n\nexport interface ResolveChatModelInput {\n  /** Per-request override (highest precedence). */\n  requestModel?: string\n  /** Persisted workspace-pinned model. */\n  workspaceModel?: string\n  /** The value the deployment's model env var holds (the product reads its own\n   *  var name and passes the value — the shell stays env-var-name agnostic). */\n  envModel?: string\n  /** Final fallback (the product's default, typically profile.model.default). */\n  defaultModel: string\n}\n\n/** Resolve the chat-turn model by the one canonical precedence. Blank values are\n *  treated as absent. */\nexport function resolveChatModel(input: ResolveChatModelInput): ResolvedChatModel {\n  const request = cleanModelId(input.requestModel)\n  if (request) return { model: request, source: 'request' }\n  const workspace = cleanModelId(input.workspaceModel)\n  if (workspace) return { model: workspace, source: 'workspace' }\n  const env = cleanModelId(input.envModel)\n  if (env) return { model: env, source: 'env' }\n  return { model: input.defaultModel, source: 'default' }\n}\n\nexport interface ValidateChatModelIdInput {\n  /** Ids accepted without a catalog round-trip (defaults + operator-trusted). */\n  allowlist?: Iterable<string>\n  /** The operator-set env model value — always admitted (operator-trusted). */\n  envModel?: string\n  /** Catalog loader; required to reach the catalog path. */\n  loadModels?: LoadModels\n  /** Catalog endpoint base; required to reach the catalog path. */\n  routerBaseUrl?: string\n}\n\n/**\n * Fail-closed model-id validation. Accepts an id only when it is well-formed AND\n * (in the allowlist, or equals the operator-set env model, or served by the live\n * catalog). A bare id (no provider prefix) resolves to its canonical id only when\n * the suffix is unique across the catalog — an ambiguous suffix is rejected\n * rather than silently assigned a provider.\n */\nexport async function validateChatModelId(\n  modelId: unknown,\n  input: ValidateChatModelIdInput,\n): Promise<ChatModelValidationResult> {\n  const cleaned = cleanModelId(modelId)\n  if (!cleaned) return { succeeded: false, error: 'Model id must be a non-empty string.' }\n  if (!isWellFormedModelId(cleaned)) return { succeeded: false, error: `Model id is malformed: ${cleaned}` }\n\n  const allowed = new Set(input.allowlist ?? [])\n  if (allowed.has(cleaned)) return { succeeded: true, value: cleaned }\n\n  // The operator-set env model is trusted without a catalog round-trip.\n  if (cleanModelId(input.envModel) === cleaned) return { succeeded: true, value: cleaned }\n\n  if (!input.loadModels || typeof input.routerBaseUrl !== 'string' || input.routerBaseUrl.length === 0) {\n    return { succeeded: false, error: `Model is not available: ${cleaned}` }\n  }\n\n  let catalog: ModelInfo[]\n  try {\n    catalog = await input.loadModels(input.routerBaseUrl)\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    return { succeeded: false, error: `Could not validate model catalog: ${message}` }\n  }\n\n  const ids = new Set(catalog.flatMap(catalogIdsForModel))\n  if (ids.has(cleaned)) return { succeeded: true, value: cleaned }\n\n  if (!cleaned.includes('/')) {\n    const canonicalBySuffix = new Map<string, string[]>()\n    for (const model of catalog) {\n      if (typeof model.id !== 'string' || !model.id.trim()) continue\n      const canonical = canonicalModelId(model)\n      if (!canonical.includes('/')) continue\n      const suffix = canonical.split('/').slice(1).join('/')\n      const entries = canonicalBySuffix.get(suffix)\n      if (entries) entries.push(canonical)\n      else canonicalBySuffix.set(suffix, [canonical])\n    }\n    const matches = canonicalBySuffix.get(cleaned)\n    if (matches && matches.length === 1) return { succeeded: true, value: matches[0]! }\n  }\n\n  return { succeeded: false, error: `Model is not available: ${cleaned}` }\n}\n\nexport function cleanModelId(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const trimmed = value.trim()\n  return trimmed.length > 0 ? trimmed : undefined\n}\n\nexport function isWellFormedModelId(modelId: string): boolean {\n  if (modelId.length > 200) return false\n  return /^[A-Za-z0-9._/@:-]+$/.test(modelId)\n}\n\nexport function catalogIdsForModel(model: ModelInfo): string[] {\n  const ids = new Set<string>()\n  if (typeof model.id === 'string' && model.id.trim()) ids.add(model.id.trim())\n  if (typeof model.id === 'string' && model.id.trim() && !model.id.includes('/')) {\n    const canonical = canonicalModelId(model)\n    if (canonical.includes('/')) ids.add(canonical)\n  }\n  return [...ids]\n}\n"],"mappings":";AA6BA,SAAS,iBAAiB,OAA0B;AAClD,MAAI,MAAM,GAAG,SAAS,GAAG,EAAG,QAAO,MAAM;AACzC,QAAM,WAAW,MAAM,aAAa,MAAM;AAC1C,SAAO,WAAW,GAAG,QAAQ,IAAI,MAAM,EAAE,KAAK,MAAM;AACtD;AAsCO,SAAS,iBAAiB,OAAiD;AAChF,QAAM,UAAU,aAAa,MAAM,YAAY;AAC/C,MAAI,QAAS,QAAO,EAAE,OAAO,SAAS,QAAQ,UAAU;AACxD,QAAM,YAAY,aAAa,MAAM,cAAc;AACnD,MAAI,UAAW,QAAO,EAAE,OAAO,WAAW,QAAQ,YAAY;AAC9D,QAAM,MAAM,aAAa,MAAM,QAAQ;AACvC,MAAI,IAAK,QAAO,EAAE,OAAO,KAAK,QAAQ,MAAM;AAC5C,SAAO,EAAE,OAAO,MAAM,cAAc,QAAQ,UAAU;AACxD;AAoBA,eAAsB,oBACpB,SACA,OACoC;AACpC,QAAM,UAAU,aAAa,OAAO;AACpC,MAAI,CAAC,QAAS,QAAO,EAAE,WAAW,OAAO,OAAO,uCAAuC;AACvF,MAAI,CAAC,oBAAoB,OAAO,EAAG,QAAO,EAAE,WAAW,OAAO,OAAO,0BAA0B,OAAO,GAAG;AAEzG,QAAM,UAAU,IAAI,IAAI,MAAM,aAAa,CAAC,CAAC;AAC7C,MAAI,QAAQ,IAAI,OAAO,EAAG,QAAO,EAAE,WAAW,MAAM,OAAO,QAAQ;AAGnE,MAAI,aAAa,MAAM,QAAQ,MAAM,QAAS,QAAO,EAAE,WAAW,MAAM,OAAO,QAAQ;AAEvF,MAAI,CAAC,MAAM,cAAc,OAAO,MAAM,kBAAkB,YAAY,MAAM,cAAc,WAAW,GAAG;AACpG,WAAO,EAAE,WAAW,OAAO,OAAO,2BAA2B,OAAO,GAAG;AAAA,EACzE;AAEA,MAAI;AACJ,MAAI;AACF,cAAU,MAAM,MAAM,WAAW,MAAM,aAAa;AAAA,EACtD,SAAS,KAAK;AACZ,UAAM,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC/D,WAAO,EAAE,WAAW,OAAO,OAAO,qCAAqC,OAAO,GAAG;AAAA,EACnF;AAEA,QAAM,MAAM,IAAI,IAAI,QAAQ,QAAQ,kBAAkB,CAAC;AACvD,MAAI,IAAI,IAAI,OAAO,EAAG,QAAO,EAAE,WAAW,MAAM,OAAO,QAAQ;AAE/D,MAAI,CAAC,QAAQ,SAAS,GAAG,GAAG;AAC1B,UAAM,oBAAoB,oBAAI,IAAsB;AACpD,eAAW,SAAS,SAAS;AAC3B,UAAI,OAAO,MAAM,OAAO,YAAY,CAAC,MAAM,GAAG,KAAK,EAAG;AACtD,YAAM,YAAY,iBAAiB,KAAK;AACxC,UAAI,CAAC,UAAU,SAAS,GAAG,EAAG;AAC9B,YAAM,SAAS,UAAU,MAAM,GAAG,EAAE,MAAM,CAAC,EAAE,KAAK,GAAG;AACrD,YAAM,UAAU,kBAAkB,IAAI,MAAM;AAC5C,UAAI,QAAS,SAAQ,KAAK,SAAS;AAAA,UAC9B,mBAAkB,IAAI,QAAQ,CAAC,SAAS,CAAC;AAAA,IAChD;AACA,UAAM,UAAU,kBAAkB,IAAI,OAAO;AAC7C,QAAI,WAAW,QAAQ,WAAW,EAAG,QAAO,EAAE,WAAW,MAAM,OAAO,QAAQ,CAAC,EAAG;AAAA,EACpF;AAEA,SAAO,EAAE,WAAW,OAAO,OAAO,2BAA2B,OAAO,GAAG;AACzE;AAEO,SAAS,aAAa,OAAoC;AAC/D,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,QAAM,UAAU,MAAM,KAAK;AAC3B,SAAO,QAAQ,SAAS,IAAI,UAAU;AACxC;AAEO,SAAS,oBAAoB,SAA0B;AAC5D,MAAI,QAAQ,SAAS,IAAK,QAAO;AACjC,SAAO,uBAAuB,KAAK,OAAO;AAC5C;AAEO,SAAS,mBAAmB,OAA4B;AAC7D,QAAM,MAAM,oBAAI,IAAY;AAC5B,MAAI,OAAO,MAAM,OAAO,YAAY,MAAM,GAAG,KAAK,EAAG,KAAI,IAAI,MAAM,GAAG,KAAK,CAAC;AAC5E,MAAI,OAAO,MAAM,OAAO,YAAY,MAAM,GAAG,KAAK,KAAK,CAAC,MAAM,GAAG,SAAS,GAAG,GAAG;AAC9E,UAAM,YAAY,iBAAiB,KAAK;AACxC,QAAI,UAAU,SAAS,GAAG,EAAG,KAAI,IAAI,SAAS;AAAA,EAChD;AACA,SAAO,CAAC,GAAG,GAAG;AAChB;","names":[]}

package/dist/profile/index.d.ts

@@ -0,0 +1,149 @@
+import { AgentProfileFileMount, AgentProfileMcpServer, AgentProfile } from '@tangle-network/sandbox';
+import { profile } from '@tangle-network/agent-eval';
+export { profile } from '@tangle-network/agent-eval';
+import { SkillEntry } from '../skills/index.js';
+export { ComposeShellResourcesInput, CorpusEntry, CorpusLoadResult, GlobModules, LoadCorpusOptions, composeShellResources, corpusSkills, loadMarkdownCorpus, registrySkills, skillMountPath } from '../skills/index.js';
+
+/**
+ * Profile composer + evolvable-section seam for agent products.
+ *
+ * The standard "load a deployable AgentProfile, including skills, plus the
+ * skills the end user added to their own instance" entry point. A product holds
+ * a canonical base `AgentProfile` (role/environment/tool-conventions rendered
+ * into `prompt.systemPrompt`, baseline skills, baseline MCP). At deploy/turn
+ * time it layers four file-mount channels onto `resources.files` —
+ *
+ *   1. skills      — the always-mounted product skill corpus
+ *   2. knowledge   — a second always-mounted corpus (domain knowledge pack)
+ *   3. registry    — the tier-gated installable registry (free -> boot-mounted)
+ *   4. userSkills  — per-user / per-workspace skills the END USER adds to their
+ *                    own instance, mounted at `~/.claude/skills/<id>/SKILL.md`
+ *                    exactly like the registry's free tier
+ *
+ * plus an optional MCP overlay (delegation + per-turn app-tool side channel), a
+ * per-turn `systemPrompt` override, and a `name` override. The merge is the SDK
+ * `mergeAgentProfiles`: `mcp` is last-wins per key (base -> overlay), `resources`
+ * arrays are concatenated (base ++ overlay), `prompt` is shallow-merged so an
+ * overlay carrying only `systemPrompt` overrides it while keeping base
+ * instructions. The compose algebra is DATA — the product injects the base
+ * profile, the channel mounts (built with the `skills` subpath primitives), the
+ * delegation/app-tool MCP map, and the override strings; nothing here reaches
+ * for env, a glob, or a specific product's profile.
+ *
+ * The evolvable-section seam is the loader closure. A product's single
+ * self-improvable domain section (the one `applyDomainPatch` targets) loads its
+ * body from a deployed markdown override, falling back to an in-tree baseline.
+ * The `import.meta.glob('<lit>', ...)` literal must stay at the CONSUMER call
+ * site (Vite static-analyzes it), so `makeEvolvableSection` takes the loader as
+ * a closure and a REQUIRED `baseline` — it never constructs a glob and never
+ * defaults the baseline, so a product can't render an empty learned-guidance
+ * section. `stripComments` is the shared "is this addendum really empty?" test.
+ */
+
+/** The file-mount channels layered onto `resources.files`. The first three
+ *  mirror {@link ComposeShellResourcesInput}; `userSkills` is the per-user /
+ *  per-workspace channel — skills the END USER added to their own instance,
+ *  mounted at the harness skill-discovery path like the registry's free tier. */
+interface ProfileChannels {
+    /** Always-mounted skill corpus (pass `corpusSkills(...)`). */
+    skills?: AgentProfileFileMount[];
+    /** Always-mounted knowledge corpus (pass `corpusSkills(...)` for the pack). */
+    knowledge?: AgentProfileFileMount[];
+    /** Single-file evolvable / learned-guidance corpora, if mounted as files. */
+    evolvable?: AgentProfileFileMount[];
+    /** Tier-gated installable registry (pass the registry array; free tier is
+     *  mounted, paid is install-on-demand). Gated through {@link registrySkills}. */
+    registry?: SkillEntry[];
+    /** Per-user / per-workspace skills the end user adds to their own instance.
+     *  Mounted at `~/.claude/skills/<id>/SKILL.md`, the same harness path the
+     *  registry uses, so a user skill and a registry skill with the same id
+     *  collide deterministically (the user skill, appended last, wins). */
+    userSkills?: UserSkill[];
+    /** Final skip filter applied to the composed mount list by mount `path`. */
+    filesPredicate?: (mount: AgentProfileFileMount) => boolean;
+}
+/** A per-user / per-workspace skill: an id and an inline `SKILL.md` body. The
+ *  user-facing analogue of a registry {@link SkillEntry} with no tier gate —
+ *  every user skill is mounted (the user opted in by adding it). */
+interface UserSkill {
+    id: string;
+    /** Inline `SKILL.md` body mounted at {@link skillMountPath}. */
+    skillMd: string;
+}
+/** Overlay overrides applied on top of the channel mounts. */
+interface ProfileOverlay {
+    /** Extra MCP servers merged into the profile `mcp` map (last-wins per key over
+     *  the base servers). The product builds this from its delegation MCP entry
+     *  and any per-turn app-tool side-channel servers. An absent/`undefined` entry
+     *  is dropped — pass only the servers that resolved (fail-closed at the seam,
+     *  not here). */
+    mcp?: Record<string, AgentProfileMcpServer>;
+    /** Per-turn system-prompt override. When set, replaces the base
+     *  `prompt.systemPrompt` while keeping base `prompt.instructions`. When unset,
+     *  the base prompt passes through unchanged. */
+    systemPrompt?: string;
+    /** Extra instruction lines merged onto the active prompt (e.g. a per-turn
+     *  domain/integration directive). Appended to base `prompt.instructions` by
+     *  the SDK merge. */
+    instructions?: string[];
+    /** Profile `name` override. When unset, the base name is kept. */
+    name?: string;
+}
+/** Project per-user skills onto SDK file mounts at the harness skill-discovery
+ *  path. No tier gate — a user skill is mounted because the user added it.
+ *  Sorted by path for determinism (matches {@link registrySkills}). */
+declare function userSkillMounts(userSkills: UserSkill[]): AgentProfileFileMount[];
+/**
+ * Compose a deployable `AgentProfile` from a canonical base plus the four
+ * file-mount channels and the overlay overrides.
+ *
+ * Files: base `resources.files` come first; the four channels follow in
+ * `skills -> knowledge -> evolvable -> registry -> userSkills` order (so a
+ * userSkill that mounts at the same path as a registry skill is the last write
+ * and wins). MCP: base servers first, the overlay `mcp` last (last-wins per
+ * key). Prompt: the overlay `systemPrompt`, when set, replaces the base one;
+ * base instructions are preserved. Name: the overlay `name`, when set, wins.
+ *
+ * The merge delegates to the SDK `mergeAgentProfiles` (overlay-wins on records,
+ * arrays concatenated) — the deterministic algebra is the overlay we hand it,
+ * not a hand-rolled spread. `mergeAgentProfiles(base, overlay)` returns
+ * `undefined` only when BOTH are `undefined`; `base` is always defined here, so
+ * the result is non-`undefined` by construction and we assert that to the caller.
+ */
+declare function composeAgentProfile(base: AgentProfile, channels?: ProfileChannels, overlay?: ProfileOverlay): AgentProfile;
+/** True body of an addendum file with HTML comments stripped — an all-comment
+ *  placeholder counts as empty, so the loader falls back to the baseline. */
+declare function stripComments(raw: string): string;
+/** Inputs to {@link makeEvolvableSection}. */
+interface EvolvableSectionInput {
+    /** Section id the self-improvement loop targets with `applyDomainPatch`. */
+    id: string;
+    /** Section title rendered as `### <title>`. */
+    title: string;
+    /**
+     * Load the deployed section body. The CONSUMER supplies this closure and runs
+     * its own `import.meta.glob('<lit>', { eager: true, query: '?raw', import:
+     * 'default' })` inside it — the literal must stay at the call site so Vite can
+     * static-analyze it; a glob constructed here would not resolve the product's
+     * files. Return the raw markdown (comments and all); `makeEvolvableSection`
+     * applies {@link stripComments} to decide whether it is really populated.
+     */
+    load: () => string;
+    /**
+     * The in-tree fallback body, used when `load()` returns an
+     * all-comments/empty placeholder. REQUIRED — no internal default — so a
+     * product can never accidentally render an empty evolvable section.
+     */
+    baseline: string;
+}
+/**
+ * Build the one evolvable (`evolvable: true`) domain section whose body comes
+ * from the product's loader, falling back to the required baseline when the
+ * loaded body is empty after stripping comments. Returns the agent-eval
+ * `AgentProfileSection` shape — drop it straight into `prodProfile`'s shipped
+ * sections. The loader is the only seam; the empty-vs-populated rule and the
+ * baseline fallback are the lifted algebra.
+ */
+declare function makeEvolvableSection(input: EvolvableSectionInput): profile.AgentProfileSection;
+
+export { type EvolvableSectionInput, type ProfileChannels, type ProfileOverlay, SkillEntry, type UserSkill, composeAgentProfile, makeEvolvableSection, stripComments, userSkillMounts };

package/dist/profile/index.js

@@ -0,0 +1,75 @@
+import {
+  composeShellResources,
+  corpusSkills,
+  loadMarkdownCorpus,
+  registrySkills,
+  skillMountPath
+} from "../chunk-KOG473C4.js";
+
+// src/profile/index.ts
+import { mergeAgentProfiles } from "@tangle-network/sandbox";
+import { profile } from "@tangle-network/agent-eval";
+function userSkillMounts(userSkills) {
+  return userSkills.map(
+    (s) => ({
+      path: skillMountPath(s.id),
+      resource: { kind: "inline", name: s.id, content: s.skillMd }
+    })
+  ).sort((a, b) => a.path.localeCompare(b.path));
+}
+function composeAgentProfile(base, channels = {}, overlay = {}) {
+  const shellInput = {
+    skills: channels.skills,
+    knowledge: channels.knowledge,
+    evolvable: channels.evolvable,
+    registry: channels.registry ? registrySkills(channels.registry) : void 0,
+    predicate: channels.filesPredicate
+  };
+  const channelFiles = composeShellResources(shellInput);
+  const userFiles = channels.userSkills ? userSkillMounts(channels.userSkills) : [];
+  const overlayFiles = channels.filesPredicate ? userFiles.filter(channels.filesPredicate) : userFiles;
+  const files = [...channelFiles, ...overlayFiles];
+  const promptOverlay = {};
+  if (overlay.systemPrompt) promptOverlay.systemPrompt = overlay.systemPrompt;
+  if (overlay.instructions && overlay.instructions.length > 0) promptOverlay.instructions = overlay.instructions;
+  const overlayProfile = {
+    ...overlay.name ? { name: overlay.name } : {},
+    ...Object.keys(promptOverlay).length > 0 ? { prompt: promptOverlay } : {},
+    ...overlay.mcp ? { mcp: overlay.mcp } : {},
+    resources: { files }
+  };
+  const merged = mergeAgentProfiles(base, overlayProfile);
+  if (!merged)
+    throw new Error("composeAgentProfile: mergeAgentProfiles returned undefined for a defined base");
+  return pruneEmptyResourceChannels(merged);
+}
+function pruneEmptyResourceChannels(profile2) {
+  if (!profile2.resources) return profile2;
+  const kept = Object.fromEntries(
+    Object.entries(profile2.resources).filter(([, value]) => !(Array.isArray(value) && value.length === 0))
+  );
+  const out = { ...profile2, resources: kept };
+  if (kept && Object.keys(kept).length === 0) delete out.resources;
+  return out;
+}
+function stripComments(raw) {
+  return raw.replace(/<!--[\s\S]*?-->/g, "").trim();
+}
+function makeEvolvableSection(input) {
+  const loaded = input.load();
+  const body = stripComments(loaded) ? loaded.trim() : input.baseline;
+  return { id: input.id, title: input.title, body, evolvable: true };
+}
+export {
+  composeAgentProfile,
+  composeShellResources,
+  corpusSkills,
+  loadMarkdownCorpus,
+  makeEvolvableSection,
+  profile,
+  registrySkills,
+  skillMountPath,
+  stripComments,
+  userSkillMounts
+};
+//# sourceMappingURL=index.js.map

package/dist/profile/index.js.map

@@ -0,0 +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"]}

package/dist/prompt/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * System-prompt assembler for agent products.
+ *
+ * Every agent product composes its system prompt the same way: a base profile
+ * prompt (the operator persona + tools block + any skills section the consumer
+ * already rendered), an always-on operating directive, then an ordered list of
+ * optional per-turn context sections (known-context, board, approval history,
+ * learned-style, pending questions, the active artifact). The ORDERING and the
+ * whitespace contract are identical across products; only the section BODIES are
+ * domain. This module owns the ordering and the joins; the product injects every
+ * body as an already-rendered string through the `sections` array.
+ *
+ * Whitespace contract (preserves the join/concat/trim algebra of the per-product
+ * pre-lift composers — a product adopting this asserts byte-for-byte parity in
+ * its own suite):
+ *   - base is emitted verbatim, with no leading/trailing normalization.
+ *   - directive is appended after base with a single `\n\n` join.
+ *   - each section in `sections` is appended with NO separator: a section is
+ *     either '' (absent — contributes nothing) or already carries its own
+ *     leading `\n\n` (and its `## ` heading). The assembler concatenates them
+ *     unconditionally, which is why the conditional-prefix-or-empty contract
+ *     lives in the product's section renderers, not here.
+ *   - `trim` (default false) applies a final `.trim()` to the whole result.
+ *     Branches that historically trimmed pass `trim: true`; branches that did
+ *     not (e.g. the new-workspace paths) leave it false, preserving that
+ *     asymmetry rather than silently changing trailing whitespace.
+ *
+ * Pure string composition: no SDK runtime symbol, no node builtins, no glob.
+ * The base profile prompt and the skills-section insertion point both live
+ * INSIDE the product-built `base` string — the assembler never reaches into an
+ * AgentProfile and never loads a corpus. The sibling
+ * `@tangle-network/agent-app/skills` subpath loads the corpus and returns file
+ * mounts (`AgentProfileFileMount[]`); the PRODUCT renders any `## Skills` text
+ * section and folds it into `base` before calling this assembler. This module
+ * never renders a skills heading.
+ */
+/** Inputs to {@link assembleSystemPrompt}. */
+interface AssembleSystemPromptInput {
+    /** The product's already-composed base block: persona/system prompt + tools
+     *  block + (optionally) the rendered skills section. The product is
+     *  responsible for resolving its profile system prompt and failing loud if it
+     *  is absent — an empty base reaches this assembler only as a programmer
+     *  error, which it rejects (see {@link AssembleResult}). */
+    base: string;
+    /** The always-on operating directive, placed immediately after base with a
+     *  `\n\n` join. Pass '' to omit it (the join is then suppressed). */
+    directive?: string;
+    /** Ordered per-turn context sections, each already rendered by the product to
+     *  either '' (absent) or a `\n\n## …`-prefixed string. Concatenated in order
+     *  with no added separator. */
+    sections?: string[];
+    /** Apply a final `.trim()` to the composed result. Default false — set true
+     *  only on branches whose pre-lift output was trimmed. */
+    trim?: boolean;
+}
+/** Typed outcome of {@link assembleSystemPrompt}. `succeeded: false` is returned
+ *  for a programmer error (an empty base) rather than emitting a roleless
+ *  prompt — callers MUST inspect `succeeded` before using `prompt`. */
+type AssembleResult = {
+    succeeded: true;
+    prompt: string;
+} | {
+    succeeded: false;
+    error: string;
+};
+/**
+ * Assemble a system prompt from a base block, an operating directive, and an
+ * ordered list of pre-rendered context sections.
+ *
+ * Returns a typed outcome: an empty/blank `base` is a defect (an agent with no
+ * persona/system prompt), so it fails loud instead of silently producing a
+ * prompt with no role. The product resolves and validates its profile prompt
+ * upstream; this is the last-line guard at the seam.
+ */
+declare function assembleSystemPrompt(input: AssembleSystemPromptInput): AssembleResult;
+
+export { type AssembleResult, type AssembleSystemPromptInput, assembleSystemPrompt };

package/dist/prompt/index.js

@@ -0,0 +1,22 @@
+// src/prompt/index.ts
+function isBlank(value) {
+  return value.trim().length === 0;
+}
+function assembleSystemPrompt(input) {
+  const { base, directive = "", sections = [], trim = false } = input;
+  if (isBlank(base)) {
+    return {
+      succeeded: false,
+      error: "assembleSystemPrompt: base is empty \u2014 a system prompt with no persona/base block is a defect, not a default"
+    };
+  }
+  let prompt = directive.length > 0 ? `${base}
+
+${directive}` : base;
+  for (const section of sections) prompt += section;
+  return { succeeded: true, prompt: trim ? prompt.trim() : prompt };
+}
+export {
+  assembleSystemPrompt
+};
+//# sourceMappingURL=index.js.map

package/dist/prompt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/prompt/index.ts"],"sourcesContent":["/**\n * System-prompt assembler for agent products.\n *\n * Every agent product composes its system prompt the same way: a base profile\n * prompt (the operator persona + tools block + any skills section the consumer\n * already rendered), an always-on operating directive, then an ordered list of\n * optional per-turn context sections (known-context, board, approval history,\n * learned-style, pending questions, the active artifact). The ORDERING and the\n * whitespace contract are identical across products; only the section BODIES are\n * domain. This module owns the ordering and the joins; the product injects every\n * body as an already-rendered string through the `sections` array.\n *\n * Whitespace contract (preserves the join/concat/trim algebra of the per-product\n * pre-lift composers — a product adopting this asserts byte-for-byte parity in\n * its own suite):\n *   - base is emitted verbatim, with no leading/trailing normalization.\n *   - directive is appended after base with a single `\\n\\n` join.\n *   - each section in `sections` is appended with NO separator: a section is\n *     either '' (absent — contributes nothing) or already carries its own\n *     leading `\\n\\n` (and its `## ` heading). The assembler concatenates them\n *     unconditionally, which is why the conditional-prefix-or-empty contract\n *     lives in the product's section renderers, not here.\n *   - `trim` (default false) applies a final `.trim()` to the whole result.\n *     Branches that historically trimmed pass `trim: true`; branches that did\n *     not (e.g. the new-workspace paths) leave it false, preserving that\n *     asymmetry rather than silently changing trailing whitespace.\n *\n * Pure string composition: no SDK runtime symbol, no node builtins, no glob.\n * The base profile prompt and the skills-section insertion point both live\n * INSIDE the product-built `base` string — the assembler never reaches into an\n * AgentProfile and never loads a corpus. The sibling\n * `@tangle-network/agent-app/skills` subpath loads the corpus and returns file\n * mounts (`AgentProfileFileMount[]`); the PRODUCT renders any `## Skills` text\n * section and folds it into `base` before calling this assembler. This module\n * never renders a skills heading.\n */\n\n/** Inputs to {@link assembleSystemPrompt}. */\nexport interface AssembleSystemPromptInput {\n  /** The product's already-composed base block: persona/system prompt + tools\n   *  block + (optionally) the rendered skills section. The product is\n   *  responsible for resolving its profile system prompt and failing loud if it\n   *  is absent — an empty base reaches this assembler only as a programmer\n   *  error, which it rejects (see {@link AssembleResult}). */\n  base: string\n  /** The always-on operating directive, placed immediately after base with a\n   *  `\\n\\n` join. Pass '' to omit it (the join is then suppressed). */\n  directive?: string\n  /** Ordered per-turn context sections, each already rendered by the product to\n   *  either '' (absent) or a `\\n\\n## …`-prefixed string. Concatenated in order\n   *  with no added separator. */\n  sections?: string[]\n  /** Apply a final `.trim()` to the composed result. Default false — set true\n   *  only on branches whose pre-lift output was trimmed. */\n  trim?: boolean\n}\n\n/** Typed outcome of {@link assembleSystemPrompt}. `succeeded: false` is returned\n *  for a programmer error (an empty base) rather than emitting a roleless\n *  prompt — callers MUST inspect `succeeded` before using `prompt`. */\nexport type AssembleResult =\n  | { succeeded: true; prompt: string }\n  | { succeeded: false; error: string }\n\n/** True when a string is empty or whitespace-only. */\nfunction isBlank(value: string): boolean {\n  return value.trim().length === 0\n}\n\n/**\n * Assemble a system prompt from a base block, an operating directive, and an\n * ordered list of pre-rendered context sections.\n *\n * Returns a typed outcome: an empty/blank `base` is a defect (an agent with no\n * persona/system prompt), so it fails loud instead of silently producing a\n * prompt with no role. The product resolves and validates its profile prompt\n * upstream; this is the last-line guard at the seam.\n */\nexport function assembleSystemPrompt(input: AssembleSystemPromptInput): AssembleResult {\n  const { base, directive = '', sections = [], trim = false } = input\n\n  if (isBlank(base)) {\n    return {\n      succeeded: false,\n      error: 'assembleSystemPrompt: base is empty — a system prompt with no persona/base block is a defect, not a default',\n    }\n  }\n\n  let prompt = directive.length > 0 ? `${base}\\n\\n${directive}` : base\n  for (const section of sections) prompt += section\n\n  return { succeeded: true, prompt: trim ? prompt.trim() : prompt }\n}"],"mappings":";AAiEA,SAAS,QAAQ,OAAwB;AACvC,SAAO,MAAM,KAAK,EAAE,WAAW;AACjC;AAWO,SAAS,qBAAqB,OAAkD;AACrF,QAAM,EAAE,MAAM,YAAY,IAAI,WAAW,CAAC,GAAG,OAAO,MAAM,IAAI;AAE9D,MAAI,QAAQ,IAAI,GAAG;AACjB,WAAO;AAAA,MACL,WAAW;AAAA,MACX,OAAO;AAAA,IACT;AAAA,EACF;AAEA,MAAI,SAAS,UAAU,SAAS,IAAI,GAAG,IAAI;AAAA;AAAA,EAAO,SAAS,KAAK;AAChE,aAAW,WAAW,SAAU,WAAU;AAE1C,SAAO,EAAE,WAAW,MAAM,QAAQ,OAAO,OAAO,KAAK,IAAI,OAAO;AAClE;","names":[]}

package/dist/run/index.d.ts

@@ -0,0 +1,64 @@
+import { Harness } from '../harness/index.js';
+
+/**
+ * Execution-mode dispatch — the shell entry that infers *how* to run an agent
+ * from its profile's harness, so a product hands over one profile and the
+ * framework routes to the router tool loop or a sandbox without separate wiring.
+ *
+ * The discriminator is the harness: absent / null / 'router' => the router tool
+ * agent (`@tangle-network/agent-app/runtime`); any member of `KNOWN_HARNESSES`
+ * (opencode, claude-code, …) => a sandbox (`@tangle-network/agent-app/sandbox`).
+ * `KNOWN_HARNESSES` is exactly the set of sandbox backends; the *absence* of a
+ * harness is the router signal.
+ *
+ * `runAgent` owns the inference + routing; the two branch runners are injected,
+ * because their inputs and event shapes legitimately differ (the router loop
+ * yields `LoopEvent`s, the sandbox yields its own events). A product supplies a
+ * `router`/`sandbox` thunk and can lazy-import the sandbox driver inside its own
+ * thunk, so a router-only app never resolves `@tangle-network/sandbox`.
+ */
+
+type ExecutionMode = 'router' | 'sandbox';
+/** The router pseudo-harness — the absence of a sandbox backend. Not a member
+ *  of `KNOWN_HARNESSES`; callers may pass it explicitly instead of null. */
+declare const ROUTER_HARNESS: "router";
+type RouterHarness = typeof ROUTER_HARNESS;
+type ProfileHarness = Harness | RouterHarness | null | undefined;
+/**
+ * Infer the execution mode from a profile's harness. Absent / null / 'router'
+ * => 'router'; a known sandbox harness => 'sandbox'. An unrecognized non-null
+ * string is treated as a sandbox backend (the box installs all harnesses, so an
+ * unknown id is a sandbox the runtime resolves, not a router) — callers that
+ * want strictness can validate against `KNOWN_HARNESSES` first.
+ */
+declare function resolveExecutionMode(harness: ProfileHarness): ExecutionMode;
+/** True when `harness` names a sandbox backend the SDK knows about. */
+declare function isKnownSandboxHarness(harness: ProfileHarness): harness is Harness;
+/**
+ * The superset the dispatch reads: the SDK `AgentProfile` plus the harness
+ * discriminator. Intentionally pins only `harness` — the rest of the profile is
+ * carried opaquely so this module stays free of the SDK type (router-only apps
+ * import it without `@tangle-network/sandbox`).
+ */
+interface ShellProfile {
+    harness?: ProfileHarness;
+}
+/** Execution mode for a profile — `harness` omitted/null => router. */
+declare function executionModeForProfile(profile: ShellProfile): ExecutionMode;
+/** The two branch runners. Each returns (or resolves to) an async iterable of
+ *  the product's own event type — the shapes differ, so the product owns them.
+ *  A `sandbox` thunk can `await import('@tangle-network/agent-app/sandbox')`
+ *  internally so the SDK is pulled only on the sandbox path. */
+interface RunAgentBranches<T> {
+    router: () => AsyncIterable<T> | Promise<AsyncIterable<T>>;
+    sandbox: () => AsyncIterable<T> | Promise<AsyncIterable<T>>;
+}
+/**
+ * Route a turn to the branch the harness selects and stream its events through.
+ * The shell does the inference; the product supplies how each branch runs. The
+ * unselected branch's thunk is never invoked — so its dependencies (e.g. the
+ * sandbox SDK) are never loaded on the other path.
+ */
+declare function runAgent<T>(harness: ProfileHarness, branches: RunAgentBranches<T>): AsyncGenerator<T>;
+
+export { type ExecutionMode, type ProfileHarness, ROUTER_HARNESS, type RouterHarness, type RunAgentBranches, type ShellProfile, executionModeForProfile, isKnownSandboxHarness, resolveExecutionMode, runAgent };

package/dist/run/index.js

@@ -0,0 +1,30 @@
+import {
+  KNOWN_HARNESSES
+} from "../chunk-SD2H4FWY.js";
+
+// src/run/index.ts
+var ROUTER_HARNESS = "router";
+function resolveExecutionMode(harness) {
+  if (harness == null || harness === ROUTER_HARNESS) return "router";
+  return "sandbox";
+}
+function isKnownSandboxHarness(harness) {
+  return harness != null && harness !== ROUTER_HARNESS && KNOWN_HARNESSES.includes(harness);
+}
+function executionModeForProfile(profile) {
+  return resolveExecutionMode(profile.harness);
+}
+async function* runAgent(harness, branches) {
+  const mode = resolveExecutionMode(harness);
+  const source = mode === "sandbox" ? branches.sandbox() : branches.router();
+  const iterable = await source;
+  for await (const event of iterable) yield event;
+}
+export {
+  ROUTER_HARNESS,
+  executionModeForProfile,
+  isKnownSandboxHarness,
+  resolveExecutionMode,
+  runAgent
+};
+//# sourceMappingURL=index.js.map

package/dist/run/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/run/index.ts"],"sourcesContent":["/**\n * Execution-mode dispatch — the shell entry that infers *how* to run an agent\n * from its profile's harness, so a product hands over one profile and the\n * framework routes to the router tool loop or a sandbox without separate wiring.\n *\n * The discriminator is the harness: absent / null / 'router' => the router tool\n * agent (`@tangle-network/agent-app/runtime`); any member of `KNOWN_HARNESSES`\n * (opencode, claude-code, …) => a sandbox (`@tangle-network/agent-app/sandbox`).\n * `KNOWN_HARNESSES` is exactly the set of sandbox backends; the *absence* of a\n * harness is the router signal.\n *\n * `runAgent` owns the inference + routing; the two branch runners are injected,\n * because their inputs and event shapes legitimately differ (the router loop\n * yields `LoopEvent`s, the sandbox yields its own events). A product supplies a\n * `router`/`sandbox` thunk and can lazy-import the sandbox driver inside its own\n * thunk, so a router-only app never resolves `@tangle-network/sandbox`.\n */\n\nimport { KNOWN_HARNESSES, type Harness } from '../harness/index'\n\nexport type ExecutionMode = 'router' | 'sandbox'\n\n/** The router pseudo-harness — the absence of a sandbox backend. Not a member\n *  of `KNOWN_HARNESSES`; callers may pass it explicitly instead of null. */\nexport const ROUTER_HARNESS = 'router' as const\nexport type RouterHarness = typeof ROUTER_HARNESS\n\nexport type ProfileHarness = Harness | RouterHarness | null | undefined\n\n/**\n * Infer the execution mode from a profile's harness. Absent / null / 'router'\n * => 'router'; a known sandbox harness => 'sandbox'. An unrecognized non-null\n * string is treated as a sandbox backend (the box installs all harnesses, so an\n * unknown id is a sandbox the runtime resolves, not a router) — callers that\n * want strictness can validate against `KNOWN_HARNESSES` first.\n */\nexport function resolveExecutionMode(harness: ProfileHarness): ExecutionMode {\n  if (harness == null || harness === ROUTER_HARNESS) return 'router'\n  return 'sandbox'\n}\n\n/** True when `harness` names a sandbox backend the SDK knows about. */\nexport function isKnownSandboxHarness(harness: ProfileHarness): harness is Harness {\n  return harness != null && harness !== ROUTER_HARNESS && (KNOWN_HARNESSES as readonly string[]).includes(harness)\n}\n\n/**\n * The superset the dispatch reads: the SDK `AgentProfile` plus the harness\n * discriminator. Intentionally pins only `harness` — the rest of the profile is\n * carried opaquely so this module stays free of the SDK type (router-only apps\n * import it without `@tangle-network/sandbox`).\n */\nexport interface ShellProfile {\n  harness?: ProfileHarness\n}\n\n/** Execution mode for a profile — `harness` omitted/null => router. */\nexport function executionModeForProfile(profile: ShellProfile): ExecutionMode {\n  return resolveExecutionMode(profile.harness)\n}\n\n/** The two branch runners. Each returns (or resolves to) an async iterable of\n *  the product's own event type — the shapes differ, so the product owns them.\n *  A `sandbox` thunk can `await import('@tangle-network/agent-app/sandbox')`\n *  internally so the SDK is pulled only on the sandbox path. */\nexport interface RunAgentBranches<T> {\n  router: () => AsyncIterable<T> | Promise<AsyncIterable<T>>\n  sandbox: () => AsyncIterable<T> | Promise<AsyncIterable<T>>\n}\n\n/**\n * Route a turn to the branch the harness selects and stream its events through.\n * The shell does the inference; the product supplies how each branch runs. The\n * unselected branch's thunk is never invoked — so its dependencies (e.g. the\n * sandbox SDK) are never loaded on the other path.\n */\nexport async function* runAgent<T>(\n  harness: ProfileHarness,\n  branches: RunAgentBranches<T>,\n): AsyncGenerator<T> {\n  const mode = resolveExecutionMode(harness)\n  const source = mode === 'sandbox' ? branches.sandbox() : branches.router()\n  const iterable = await source\n  for await (const event of iterable) yield event\n}\n"],"mappings":";;;;;AAwBO,IAAM,iBAAiB;AAYvB,SAAS,qBAAqB,SAAwC;AAC3E,MAAI,WAAW,QAAQ,YAAY,eAAgB,QAAO;AAC1D,SAAO;AACT;AAGO,SAAS,sBAAsB,SAA6C;AACjF,SAAO,WAAW,QAAQ,YAAY,kBAAmB,gBAAsC,SAAS,OAAO;AACjH;AAaO,SAAS,wBAAwB,SAAsC;AAC5E,SAAO,qBAAqB,QAAQ,OAAO;AAC7C;AAiBA,gBAAuB,SACrB,SACA,UACmB;AACnB,QAAM,OAAO,qBAAqB,OAAO;AACzC,QAAM,SAAS,SAAS,YAAY,SAAS,QAAQ,IAAI,SAAS,OAAO;AACzE,QAAM,WAAW,MAAM;AACvB,mBAAiB,SAAS,SAAU,OAAM;AAC5C;","names":[]}

package/dist/runtime/index.d.ts

@@ -5,7 +5,8 @@ export { C as CatalogModel, M as ModelCatalog, R as RouterModel, _ as __resetCat
 export { C as CreateTangleRouterModelConfigOptions, D as DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR, a as DEFAULT_TANGLE_ROUTER_BASE_URL, R as ResolveModelOptions, b as ResolveUserTangleExecutionKeyForUserOptions, c as ResolveUserTangleExecutionKeyOptions, d as ResolvedTangleExecutionKey, T as TangleBillingEnforcementOptions, e as TangleExecutionEnvironment, f as TangleExecutionKeyError, g as TangleExecutionKeyErrorCode, h as TangleExecutionKeyHttpError, i as TangleExecutionKeySource, j as TangleModelConfig, k as createTangleRouterModelConfig, l as isTangleBillingEnforcementDisabled, m as isTangleExecutionKeyError, r as resolveTangleExecutionEnvironment, n as resolveTangleModelConfig, o as resolveUserTangleExecutionKey, p as resolveUserTangleExecutionKeyForUser, t as tangleExecutionKeyHttpError } from '../model-CKzniMMr.js';
 import { b as AppToolContext, e as AppToolProducedEvent, f as AppToolTaxonomy, c as AppToolHandlers, d as AppToolOutcome } from '../types-2rOJo8Hc.js';
 import { CertifiedProfile } from '@tangle-network/agent-runtime/intelligence';
-import { a as AppToolMcpServer } from '../mcp-eZCmkgCF.js';
+import { A as AppToolMcpServer } from '../mcp-BShTlESm.js';
+import '../auth-BlS9GWfL.js';
 
 /**
  * OpenAI-compatible stream → `LoopEvent` adapter, for NON-sandbox copilots.