@tangle-network/agent-app 0.60.228 → 0.60.230

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,21 +1,3 @@
1
- /**
2
- * The sequences MCP tool registry — what the in-sandbox agent sees over the
3
- * live agent→timeline channel. Each entry carries an LLM-facing description,
4
- * a JSON Schema for the arguments, and the typed dispatch that converts
5
- * seconds→frames exactly once, validates the resulting operations, applies
6
- * them through the store, and records ONE decision row per mutating call.
7
- *
8
- * Tool arguments speak SECONDS (the unit an LLM reasons in); everything past
9
- * this edge is integer frames at the sequence fps. Results come back in
10
- * snake_case with both seconds and `m:ss.ff` timecodes so the model can quote
11
- * positions back to the user without doing frame math.
12
- *
13
- * Every mutation funnels through the ./validate + ./apply kernel: the WHOLE
14
- * operation batch validates against pre-state before the first write. Errors
15
- * thrown anywhere in a tool run (argument shape, validation, store) carry the
16
- * precise reason — the handler surfaces them verbatim as `isError` tool
17
- * results the model can act on.
18
- */
19
1
  import type { SequenceStore } from './store';
20
2
  /** Everything one tool invocation needs. Constructed per request by the
21
3
  * handler — the store is already scoped + authorized by the product. The
@@ -83,6 +83,18 @@ export interface SkillSupportFile {
83
83
  path: string;
84
84
  content: string;
85
85
  }
86
+ /** Optional naming and reconciliation policies for skill support files. */
87
+ export interface SkillSupportFileOptions {
88
+ /** Resource name for newly created mounts. Defaults to `<skillId>/<path>`. */
89
+ resourceName?: (file: SkillSupportFile) => string;
90
+ /**
91
+ * `retain` (default) keeps identical mounts at their desired paths.
92
+ * `replace` removes owned mounts and appends canonical mounts in file order.
93
+ * Foreign mounts always keep their paths. On a supported harness, if they
94
+ * occupy every desired path, `replace` leaves the original profile unchanged.
95
+ */
96
+ reconcileExisting?: 'retain' | 'replace';
97
+ }
86
98
  /** Inline file mounts placing a skill's support files beside its entry on
87
99
  * `harness`: `<skillDir>/<skillId>/<path>`. Empty when the harness has no
88
100
  * cwd skill dir — the same posture as `resources.skills` itself (the
@@ -94,7 +106,7 @@ export interface SkillSupportFile {
94
106
  * mounts — never in an env var: runtimeSecrets values are capped (8192
95
107
  * chars on the sandbox SDK) and a skill tree outgrew that cap in production
96
108
  * once, taking every isolated turn down with a secret-provider refusal. */
97
- export declare function skillSupportFileMounts(harness: Harness, skillId: string, files: readonly SkillSupportFile[]): AgentProfileFileMount[];
109
+ export declare function skillSupportFileMounts(harness: Harness, skillId: string, files: readonly SkillSupportFile[], options?: Pick<SkillSupportFileOptions, 'resourceName'>): AgentProfileFileMount[];
98
110
  /** Attach a skill's support files to `profile` for `harness`, idempotently.
99
111
  *
100
112
  * Replacement is by EXACT CONTENT under the skill's own subtree (any path
@@ -103,7 +115,8 @@ export declare function skillSupportFileMounts(harness: Harness, skillId: string
103
115
  * own mounts wherever they previously pointed, while pack-declared files
104
116
  * with similar paths stay untouched. With no skill dir the skill's own
105
117
  * mounts are dropped (and nothing added) — mirroring how the platform
106
- * treats the skill entry itself on that harness. */
118
+ * treats the skill entry itself on that harness. `options` can customize
119
+ * new resource names and opt into replacing owned mounts in file order. */
107
120
  export declare function withSkillSupportFiles<P extends {
108
121
  resources?: AgentProfile['resources'];
109
- }>(profile: P, harness: Harness, skillId: string, files: readonly SkillSupportFile[]): P;
122
+ }>(profile: P, harness: Harness, skillId: string, files: readonly SkillSupportFile[], options?: SkillSupportFileOptions): P;
@@ -56,17 +56,20 @@ function composeSkillsForHarness(input) {
56
56
  `composeSkillsForHarness: "${harness}" has no native skill-mount directory. Inlining ${relevant.length} skill(s) (${bytes} bytes) into its system prompt would silently convert mounted skills into prompt text \u2014 a 151,882-byte prompt shipped this way once, and oversized prompts degrade toward empty answers. Mount the skills instead: pick a harness with native skill support (${mountable.join(", ")}), or pass onNoSkillDir: 'inline' to opt in explicitly and accept the inlined bytes.`
57
57
  );
58
58
  }
59
- function skillSupportFileMounts(harness, skillId, files) {
59
+ function skillSupportFileMounts(harness, skillId, files, options = {}) {
60
60
  const skillDir = resolveSkillDir(harness);
61
61
  if (!skillDir || files.length === 0) return [];
62
62
  return files.map((file) => ({
63
63
  path: `${skillDir}/${skillId}/${file.path}`,
64
- resource: defineInlineResource(`${skillId}/${file.path}`, file.content)
64
+ resource: defineInlineResource(
65
+ options.resourceName ? options.resourceName(file) : `${skillId}/${file.path}`,
66
+ file.content
67
+ )
65
68
  }));
66
69
  }
67
- function withSkillSupportFiles(profile, harness, skillId, files) {
70
+ function withSkillSupportFiles(profile, harness, skillId, files, options = {}) {
68
71
  const hasSkillDir = resolveSkillDir(harness) !== null;
69
- const desired = skillSupportFileMounts(harness, skillId, files);
72
+ const desired = skillSupportFileMounts(harness, skillId, files, options);
70
73
  const desiredByPath = new Map(
71
74
  desired.map((mount) => [mount.path, mount.resource])
72
75
  );
@@ -76,18 +79,19 @@ function withSkillSupportFiles(profile, harness, skillId, files) {
76
79
  const at = path.lastIndexOf(suffix);
77
80
  return at < 0 ? null : path.slice(at + suffix.length);
78
81
  };
79
- const isStaleOurs = (mount) => {
82
+ const shouldDropMount = (mount) => {
80
83
  if (mount.resource.kind !== "inline") return false;
81
84
  const rel = relUnderSkill(mount.path);
82
85
  if (rel === null || byRelPath.get(rel) !== mount.resource.content) return false;
86
+ if (options.reconcileExisting === "replace") return true;
83
87
  const desiredHere = desiredByPath.get(mount.path);
84
88
  return !hasSkillDir || desiredHere === void 0 || desiredHere.kind !== "inline" || desiredHere.content !== mount.resource.content;
85
89
  };
86
90
  const existing = profile.resources?.files ?? [];
87
- const retained = existing.filter((mount) => !isStaleOurs(mount));
91
+ const retained = existing.filter((mount) => !shouldDropMount(mount));
88
92
  const taken = new Set(retained.map((mount) => mount.path));
89
93
  const additions = desired.filter((mount) => !taken.has(mount.path));
90
- if (retained.length === existing.length && additions.length === 0) return profile;
94
+ if (additions.length === 0 && (retained.length === existing.length || hasSkillDir && options.reconcileExisting === "replace")) return profile;
91
95
  return {
92
96
  ...profile,
93
97
  resources: { ...profile.resources ?? {}, files: [...retained, ...additions] }
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/skills-placement/index.ts"],"sourcesContent":["/**\n * Harness-native skill directory resolution — the one place agent-app binds\n * to the platform's authoritative per-harness skill-dir map.\n *\n * `../skills` renders skill CONTENT (parse, tier-filter, `inline`/`mounted`\n * delivery) but deliberately stops short of naming WHICH cwd path a `mounted`\n * skill lands at on a given harness — that mapping is owned by the platform\n * materializer (`@tangle-network/agent-profile-materialize`'s\n * `skillDirForHarness`), not by app-shell. This subpath exists so no product\n * — and no other agent-app module — ever writes a skill path literal\n * (`~/.claude/skills/...`, `.opencode/skills`, ...) of its own; it bridges\n * agent-app's `Harness` taxonomy onto the platform's `HarnessId` and asks the\n * platform for the answer.\n *\n * Requires the OPTIONAL peer `@tangle-network/agent-profile-materialize`.\n * Products that don't install it simply don't import this subpath — every\n * other agent-app skills surface (`../skills`, `ProfileChannels.skillRefs`)\n * works without it, falling back to `inline` delivery.\n */\n\nimport {\n defineInlineResource,\n type AgentProfile,\n type AgentProfileFileMount,\n} from '@tangle-network/agent-interface'\nimport { KNOWN_HARNESSES, type Harness } from '../harness/index'\nimport { skillDirForHarness, type HarnessId } from '@tangle-network/agent-profile-materialize'\nimport { composeSkills, renderInlineSkills, type ComposedSkills, type SkillEntry } from '../skills/index'\n\n/** agent-app `Harness` -> platform `HarnessId`, identity-mapped for exactly\n * the harnesses the platform map covers. Harnesses absent here (`amp`,\n * `factory-droids`, `forge`, `acp`, `cursor`, `cli-base`) resolve to `null` —\n * {@link composeSkillsForHarness} refuses by default rather than silently\n * delivering `inline`; a caller that genuinely needs `inline` on one of\n * these opts in explicitly (`onNoSkillDir: 'inline'`). `cursor`'s adapter\n * supports `resources.skills` bespokely but isn't in the platform map yet;\n * treating it as unbridged is the safe posture until the map covers it,\n * rather than guessing its cwd skill dir here. */\nconst HARNESS_BRIDGE: Partial<Record<Harness, HarnessId>> = {\n opencode: 'opencode',\n 'claude-code': 'claude-code',\n nanoclaw: 'nanoclaw',\n 'kimi-code': 'kimi-code',\n codex: 'codex',\n pi: 'pi',\n prime: 'prime',\n hermes: 'hermes',\n openclaw: 'openclaw',\n}\n\n/** Resolve the cwd-relative skill dir `resources.skills` refs materialize\n * into on `harness` — via the platform's `skillDirForHarness`. `null` when\n * `harness` isn't bridged (see {@link HARNESS_BRIDGE}) or when the platform\n * itself has no cwd skill primitive for it (e.g. `hermes`, user-dir-only). */\nexport function resolveSkillDir(harness: Harness): string | null {\n const bridged = HARNESS_BRIDGE[harness]\n if (!bridged) return null\n return skillDirForHarness(bridged)\n}\n\n/** Filter `harnesses` down to those with no mounted skill dir (deduped,\n * first-seen order preserved) — the set that must fall back to `inline`\n * delivery, or that a caller should warn about before offering \"mounted\"\n * install UX. */\nexport function unsupportedSkillHarnesses(harnesses: Iterable<Harness>): Harness[] {\n const seen = new Set<Harness>()\n const out: Harness[] = []\n for (const harness of harnesses) {\n if (resolveSkillDir(harness) !== null) continue\n if (seen.has(harness)) continue\n seen.add(harness)\n out.push(harness)\n }\n return out\n}\n\n/** Inputs to {@link composeSkillsForHarness}. */\nexport interface ComposeSkillsForHarnessInput {\n skills: SkillEntry[]\n harness: Harness\n tier?: string\n heading?: string\n /**\n * What to do when `harness` has no native skill-mount directory (see\n * {@link resolveSkillDir}). Default `'throw'`: refuse rather than silently\n * inlining every skill BODY into the system prompt. Pass `'inline'` only as\n * a deliberate, auditable opt-in — the caller has decided every skill must\n * reach this harness even though it will be concatenated into the prompt.\n */\n onNoSkillDir?: 'throw' | 'inline'\n}\n\n/** `KNOWN_HARNESSES` filtered to those the platform materializer can mount\n * skill files onto natively (a non-null {@link resolveSkillDir}). Computed\n * fresh rather than cached — the platform map can grow without a release\n * here. Used only to build the actionable error in\n * {@link composeSkillsForHarness}; not exported because it duplicates\n * {@link unsupportedSkillHarnesses}'s complement and callers should reach\n * for that instead when they need the harness list at runtime. */\nfunction nativeSkillMountHarnesses(): Harness[] {\n return KNOWN_HARNESSES.filter((harness) => resolveSkillDir(harness) !== null)\n}\n\n/**\n * Compose {@link ComposedSkills} for `harness`.\n *\n * `mounted` delivery is the standard path: whenever the platform names a cwd\n * skill dir for `harness`, skills ride the typed `resources.skills` channel\n * and the platform materializer writes each one to that directory as a real\n * file — the agent reads it on demand with its own file tools.\n *\n * `inline` delivery — every skill BODY rendered straight into the system\n * prompt — is a NARROW fallback for harnesses with no native skill dir, never\n * a co-equal mode. An `AgentProfile` is a RECIPE that materializes into a\n * sandbox, not a prompt template: skill bodies belong in a file mount, and\n * `prompt.systemPrompt` should carry only what the agent must obey without a\n * tool call (identity, tool-call contract, safety rules, output format) plus\n * a short index of what's mounted. Concatenating skill bodies into the prompt\n * degrades the model toward empty answers once it grows large enough — one\n * product reproduced a 151,882-byte prompt exactly this way, from an\n * unnoticed inline fallback.\n *\n * Because of that, `onNoSkillDir` defaults to `'throw'`: a harness with no\n * skill dir refuses instead of silently inlining. The thrown error names the\n * harness, the skill count, the byte size that would have been inlined, and\n * the harnesses that DO support native mounting. Pass `onNoSkillDir:\n * 'inline'` only as a deliberate, auditable opt-in when every skill genuinely\n * must reach this harness regardless of prompt cost.\n *\n * The one function a product calls instead of hand-checking `resolveSkillDir`\n * and branching between {@link composeSkills}'s two modes itself.\n */\nexport function composeSkillsForHarness(input: ComposeSkillsForHarnessInput): ComposedSkills {\n const { skills, harness, tier, heading, onNoSkillDir = 'throw' } = input\n const skillDir = resolveSkillDir(harness)\n if (skillDir) return composeSkills({ skills, mode: 'mounted', skillDir, tier, heading })\n if (onNoSkillDir === 'inline') return composeSkills({ skills, mode: 'inline', tier, heading })\n\n const relevant = tier ? skills.filter((s) => s.tier === tier) : skills\n const promptSection = renderInlineSkills({ skills, tier, heading })\n const bytes = new TextEncoder().encode(promptSection).byteLength\n const mountable = nativeSkillMountHarnesses()\n throw new Error(\n `composeSkillsForHarness: \"${harness}\" has no native skill-mount directory. ` +\n `Inlining ${relevant.length} skill(s) (${bytes} bytes) into its system prompt would silently ` +\n `convert mounted skills into prompt text — a 151,882-byte prompt shipped this way once, and ` +\n `oversized prompts degrade toward empty answers. Mount the skills instead: pick a harness with ` +\n `native skill support (${mountable.join(', ')}), or pass onNoSkillDir: 'inline' to opt in ` +\n `explicitly and accept the inlined bytes.`,\n )\n}\n\nexport type { ComposedSkills, SkillEntry } from '../skills/index'\n\n/** A file that rides BESIDE a skill entry (kit sources, references, pinned\n * requirements — anything the SKILL.md tells the agent to read or run).\n * `path` is skill-dir-relative (`kit/iso-kit.mjs`, `references/x.md`). */\nexport interface SkillSupportFile {\n path: string\n content: string\n}\n\n/** Inline file mounts placing a skill's support files beside its entry on\n * `harness`: `<skillDir>/<skillId>/<path>`. Empty when the harness has no\n * cwd skill dir — the same posture as `resources.skills` itself (the\n * platform skips skills there too), so nothing orphan lands in a workspace\n * a harness will never read.\n *\n * This is the placement primitive for kit-carrying skills (vendored\n * executable kits, reference trees). A growing program belongs in THESE\n * mounts — never in an env var: runtimeSecrets values are capped (8192\n * chars on the sandbox SDK) and a skill tree outgrew that cap in production\n * once, taking every isolated turn down with a secret-provider refusal. */\nexport function skillSupportFileMounts(\n harness: Harness,\n skillId: string,\n files: readonly SkillSupportFile[],\n): AgentProfileFileMount[] {\n const skillDir = resolveSkillDir(harness)\n if (!skillDir || files.length === 0) return []\n return files.map((file) => ({\n path: `${skillDir}/${skillId}/${file.path}`,\n resource: defineInlineResource(`${skillId}/${file.path}`, file.content),\n }))\n}\n\n/** Attach a skill's support files to `profile` for `harness`, idempotently.\n *\n * Replacement is by EXACT CONTENT under the skill's own subtree (any path\n * ending `/<skillId>/<path>` whose bytes match a support file of THIS call):\n * re-deriving the same profile for another harness replaces this skill's\n * own mounts wherever they previously pointed, while pack-declared files\n * with similar paths stay untouched. With no skill dir the skill's own\n * mounts are dropped (and nothing added) — mirroring how the platform\n * treats the skill entry itself on that harness. */\nexport function withSkillSupportFiles<\n P extends { resources?: AgentProfile['resources'] },\n>(profile: P, harness: Harness, skillId: string, files: readonly SkillSupportFile[]): P {\n const hasSkillDir = resolveSkillDir(harness) !== null\n const desired = skillSupportFileMounts(harness, skillId, files)\n const desiredByPath = new Map(\n desired.map((mount) => [mount.path, mount.resource] as const),\n )\n const byRelPath = new Map(files.map((file) => [file.path, file.content] as const))\n const suffix = `/${skillId}/`\n const relUnderSkill = (path: string): string | null => {\n const at = path.lastIndexOf(suffix)\n return at < 0 ? null : path.slice(at + suffix.length)\n }\n // \"Ours\" = a mount under THIS skill's subtree whose bytes match a support\n // file of this call. It is STALE when the harness has no skill dir (there\n // is nowhere to place it — mirroring how the platform skips the skill\n // entry itself) or when this call would place it at a different path\n // (re-derivation for another harness). Exact-content identity only: a\n // foreign mount at one of our paths keeps the location (pack-declared\n // files win at their declared paths), and a mount already identical to\n // what we would add is kept as-is, so re-deriving for the SAME harness\n // returns the profile unchanged.\n const isStaleOurs = (mount: AgentProfileFileMount): boolean => {\n if (mount.resource.kind !== 'inline') return false\n const rel = relUnderSkill(mount.path)\n if (rel === null || byRelPath.get(rel) !== mount.resource.content) return false\n const desiredHere = desiredByPath.get(mount.path)\n return (\n !hasSkillDir ||\n desiredHere === undefined ||\n desiredHere.kind !== 'inline' ||\n desiredHere.content !== mount.resource.content\n )\n }\n const existing = profile.resources?.files ?? []\n const retained = existing.filter((mount) => !isStaleOurs(mount))\n const taken = new Set(retained.map((mount) => mount.path))\n const additions = desired.filter((mount) => !taken.has(mount.path))\n if (retained.length === existing.length && additions.length === 0) return profile\n return {\n ...profile,\n resources: { ...(profile.resources ?? {}), files: [...retained, ...additions] },\n }\n}\n"],"mappings":"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","names":[]}
1
+ {"version":3,"sources":["../../src/skills-placement/index.ts"],"sourcesContent":["/**\n * Harness-native skill directory resolution — the one place agent-app binds\n * to the platform's authoritative per-harness skill-dir map.\n *\n * `../skills` renders skill CONTENT (parse, tier-filter, `inline`/`mounted`\n * delivery) but deliberately stops short of naming WHICH cwd path a `mounted`\n * skill lands at on a given harness — that mapping is owned by the platform\n * materializer (`@tangle-network/agent-profile-materialize`'s\n * `skillDirForHarness`), not by app-shell. This subpath exists so no product\n * — and no other agent-app module — ever writes a skill path literal\n * (`~/.claude/skills/...`, `.opencode/skills`, ...) of its own; it bridges\n * agent-app's `Harness` taxonomy onto the platform's `HarnessId` and asks the\n * platform for the answer.\n *\n * Requires the OPTIONAL peer `@tangle-network/agent-profile-materialize`.\n * Products that don't install it simply don't import this subpath — every\n * other agent-app skills surface (`../skills`, `ProfileChannels.skillRefs`)\n * works without it, falling back to `inline` delivery.\n */\n\nimport {\n defineInlineResource,\n type AgentProfile,\n type AgentProfileFileMount,\n} from '@tangle-network/agent-interface'\nimport { KNOWN_HARNESSES, type Harness } from '../harness/index'\nimport { skillDirForHarness, type HarnessId } from '@tangle-network/agent-profile-materialize'\nimport { composeSkills, renderInlineSkills, type ComposedSkills, type SkillEntry } from '../skills/index'\n\n/** agent-app `Harness` -> platform `HarnessId`, identity-mapped for exactly\n * the harnesses the platform map covers. Harnesses absent here (`amp`,\n * `factory-droids`, `forge`, `acp`, `cursor`, `cli-base`) resolve to `null` —\n * {@link composeSkillsForHarness} refuses by default rather than silently\n * delivering `inline`; a caller that genuinely needs `inline` on one of\n * these opts in explicitly (`onNoSkillDir: 'inline'`). `cursor`'s adapter\n * supports `resources.skills` bespokely but isn't in the platform map yet;\n * treating it as unbridged is the safe posture until the map covers it,\n * rather than guessing its cwd skill dir here. */\nconst HARNESS_BRIDGE: Partial<Record<Harness, HarnessId>> = {\n opencode: 'opencode',\n 'claude-code': 'claude-code',\n nanoclaw: 'nanoclaw',\n 'kimi-code': 'kimi-code',\n codex: 'codex',\n pi: 'pi',\n prime: 'prime',\n hermes: 'hermes',\n openclaw: 'openclaw',\n}\n\n/** Resolve the cwd-relative skill dir `resources.skills` refs materialize\n * into on `harness` — via the platform's `skillDirForHarness`. `null` when\n * `harness` isn't bridged (see {@link HARNESS_BRIDGE}) or when the platform\n * itself has no cwd skill primitive for it (e.g. `hermes`, user-dir-only). */\nexport function resolveSkillDir(harness: Harness): string | null {\n const bridged = HARNESS_BRIDGE[harness]\n if (!bridged) return null\n return skillDirForHarness(bridged)\n}\n\n/** Filter `harnesses` down to those with no mounted skill dir (deduped,\n * first-seen order preserved) — the set that must fall back to `inline`\n * delivery, or that a caller should warn about before offering \"mounted\"\n * install UX. */\nexport function unsupportedSkillHarnesses(harnesses: Iterable<Harness>): Harness[] {\n const seen = new Set<Harness>()\n const out: Harness[] = []\n for (const harness of harnesses) {\n if (resolveSkillDir(harness) !== null) continue\n if (seen.has(harness)) continue\n seen.add(harness)\n out.push(harness)\n }\n return out\n}\n\n/** Inputs to {@link composeSkillsForHarness}. */\nexport interface ComposeSkillsForHarnessInput {\n skills: SkillEntry[]\n harness: Harness\n tier?: string\n heading?: string\n /**\n * What to do when `harness` has no native skill-mount directory (see\n * {@link resolveSkillDir}). Default `'throw'`: refuse rather than silently\n * inlining every skill BODY into the system prompt. Pass `'inline'` only as\n * a deliberate, auditable opt-in — the caller has decided every skill must\n * reach this harness even though it will be concatenated into the prompt.\n */\n onNoSkillDir?: 'throw' | 'inline'\n}\n\n/** `KNOWN_HARNESSES` filtered to those the platform materializer can mount\n * skill files onto natively (a non-null {@link resolveSkillDir}). Computed\n * fresh rather than cached — the platform map can grow without a release\n * here. Used only to build the actionable error in\n * {@link composeSkillsForHarness}; not exported because it duplicates\n * {@link unsupportedSkillHarnesses}'s complement and callers should reach\n * for that instead when they need the harness list at runtime. */\nfunction nativeSkillMountHarnesses(): Harness[] {\n return KNOWN_HARNESSES.filter((harness) => resolveSkillDir(harness) !== null)\n}\n\n/**\n * Compose {@link ComposedSkills} for `harness`.\n *\n * `mounted` delivery is the standard path: whenever the platform names a cwd\n * skill dir for `harness`, skills ride the typed `resources.skills` channel\n * and the platform materializer writes each one to that directory as a real\n * file — the agent reads it on demand with its own file tools.\n *\n * `inline` delivery — every skill BODY rendered straight into the system\n * prompt — is a NARROW fallback for harnesses with no native skill dir, never\n * a co-equal mode. An `AgentProfile` is a RECIPE that materializes into a\n * sandbox, not a prompt template: skill bodies belong in a file mount, and\n * `prompt.systemPrompt` should carry only what the agent must obey without a\n * tool call (identity, tool-call contract, safety rules, output format) plus\n * a short index of what's mounted. Concatenating skill bodies into the prompt\n * degrades the model toward empty answers once it grows large enough — one\n * product reproduced a 151,882-byte prompt exactly this way, from an\n * unnoticed inline fallback.\n *\n * Because of that, `onNoSkillDir` defaults to `'throw'`: a harness with no\n * skill dir refuses instead of silently inlining. The thrown error names the\n * harness, the skill count, the byte size that would have been inlined, and\n * the harnesses that DO support native mounting. Pass `onNoSkillDir:\n * 'inline'` only as a deliberate, auditable opt-in when every skill genuinely\n * must reach this harness regardless of prompt cost.\n *\n * The one function a product calls instead of hand-checking `resolveSkillDir`\n * and branching between {@link composeSkills}'s two modes itself.\n */\nexport function composeSkillsForHarness(input: ComposeSkillsForHarnessInput): ComposedSkills {\n const { skills, harness, tier, heading, onNoSkillDir = 'throw' } = input\n const skillDir = resolveSkillDir(harness)\n if (skillDir) return composeSkills({ skills, mode: 'mounted', skillDir, tier, heading })\n if (onNoSkillDir === 'inline') return composeSkills({ skills, mode: 'inline', tier, heading })\n\n const relevant = tier ? skills.filter((s) => s.tier === tier) : skills\n const promptSection = renderInlineSkills({ skills, tier, heading })\n const bytes = new TextEncoder().encode(promptSection).byteLength\n const mountable = nativeSkillMountHarnesses()\n throw new Error(\n `composeSkillsForHarness: \"${harness}\" has no native skill-mount directory. ` +\n `Inlining ${relevant.length} skill(s) (${bytes} bytes) into its system prompt would silently ` +\n `convert mounted skills into prompt text — a 151,882-byte prompt shipped this way once, and ` +\n `oversized prompts degrade toward empty answers. Mount the skills instead: pick a harness with ` +\n `native skill support (${mountable.join(', ')}), or pass onNoSkillDir: 'inline' to opt in ` +\n `explicitly and accept the inlined bytes.`,\n )\n}\n\nexport type { ComposedSkills, SkillEntry } from '../skills/index'\n\n/** A file that rides BESIDE a skill entry (kit sources, references, pinned\n * requirements — anything the SKILL.md tells the agent to read or run).\n * `path` is skill-dir-relative (`kit/iso-kit.mjs`, `references/x.md`). */\nexport interface SkillSupportFile {\n path: string\n content: string\n}\n\n/** Optional naming and reconciliation policies for skill support files. */\nexport interface SkillSupportFileOptions {\n /** Resource name for newly created mounts. Defaults to `<skillId>/<path>`. */\n resourceName?: (file: SkillSupportFile) => string\n /**\n * `retain` (default) keeps identical mounts at their desired paths.\n * `replace` removes owned mounts and appends canonical mounts in file order.\n * Foreign mounts always keep their paths. On a supported harness, if they\n * occupy every desired path, `replace` leaves the original profile unchanged.\n */\n reconcileExisting?: 'retain' | 'replace'\n}\n\n/** Inline file mounts placing a skill's support files beside its entry on\n * `harness`: `<skillDir>/<skillId>/<path>`. Empty when the harness has no\n * cwd skill dir — the same posture as `resources.skills` itself (the\n * platform skips skills there too), so nothing orphan lands in a workspace\n * a harness will never read.\n *\n * This is the placement primitive for kit-carrying skills (vendored\n * executable kits, reference trees). A growing program belongs in THESE\n * mounts — never in an env var: runtimeSecrets values are capped (8192\n * chars on the sandbox SDK) and a skill tree outgrew that cap in production\n * once, taking every isolated turn down with a secret-provider refusal. */\nexport function skillSupportFileMounts(\n harness: Harness,\n skillId: string,\n files: readonly SkillSupportFile[],\n options: Pick<SkillSupportFileOptions, 'resourceName'> = {},\n): AgentProfileFileMount[] {\n const skillDir = resolveSkillDir(harness)\n if (!skillDir || files.length === 0) return []\n return files.map((file) => ({\n path: `${skillDir}/${skillId}/${file.path}`,\n resource: defineInlineResource(\n options.resourceName ? options.resourceName(file) : `${skillId}/${file.path}`,\n file.content,\n ),\n }))\n}\n\n/** Attach a skill's support files to `profile` for `harness`, idempotently.\n *\n * Replacement is by EXACT CONTENT under the skill's own subtree (any path\n * ending `/<skillId>/<path>` whose bytes match a support file of THIS call):\n * re-deriving the same profile for another harness replaces this skill's\n * own mounts wherever they previously pointed, while pack-declared files\n * with similar paths stay untouched. With no skill dir the skill's own\n * mounts are dropped (and nothing added) — mirroring how the platform\n * treats the skill entry itself on that harness. `options` can customize\n * new resource names and opt into replacing owned mounts in file order. */\nexport function withSkillSupportFiles<\n P extends { resources?: AgentProfile['resources'] },\n>(\n profile: P,\n harness: Harness,\n skillId: string,\n files: readonly SkillSupportFile[],\n options: SkillSupportFileOptions = {},\n): P {\n const hasSkillDir = resolveSkillDir(harness) !== null\n const desired = skillSupportFileMounts(harness, skillId, files, options)\n const desiredByPath = new Map(\n desired.map((mount) => [mount.path, mount.resource] as const),\n )\n const byRelPath = new Map(files.map((file) => [file.path, file.content] as const))\n const suffix = `/${skillId}/`\n const relUnderSkill = (path: string): string | null => {\n const at = path.lastIndexOf(suffix)\n return at < 0 ? null : path.slice(at + suffix.length)\n }\n // \"Ours\" = a mount under THIS skill's subtree whose bytes match a support\n // file of this call. It is STALE when the harness has no skill dir (there\n // is nowhere to place it — mirroring how the platform skips the skill\n // entry itself) or when this call would place it at a different path\n // (re-derivation for another harness). Exact-content identity only: a\n // foreign mount at one of our paths keeps the location (pack-declared\n // files win at their declared paths). By default an identical mount is\n // kept as-is; the replace policy regenerates owned mounts in file order.\n const shouldDropMount = (mount: AgentProfileFileMount): boolean => {\n if (mount.resource.kind !== 'inline') return false\n const rel = relUnderSkill(mount.path)\n if (rel === null || byRelPath.get(rel) !== mount.resource.content) return false\n if (options.reconcileExisting === 'replace') return true\n const desiredHere = desiredByPath.get(mount.path)\n return (\n !hasSkillDir ||\n desiredHere === undefined ||\n desiredHere.kind !== 'inline' ||\n desiredHere.content !== mount.resource.content\n )\n }\n const existing = profile.resources?.files ?? []\n const retained = existing.filter((mount) => !shouldDropMount(mount))\n const taken = new Set(retained.map((mount) => mount.path))\n const additions = desired.filter((mount) => !taken.has(mount.path))\n // Preserve the replace policy's no-op when foreign mounts occupy every\n // destination; without a skill dir, owned mounts are still removed.\n if (additions.length === 0 && (\n retained.length === existing.length ||\n (hasSkillDir && options.reconcileExisting === 'replace')\n )) return profile\n return {\n ...profile,\n resources: { ...(profile.resources ?? {}), files: [...retained, ...additions] },\n }\n}\n"],"mappings":"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","names":[]}
@@ -0,0 +1,4 @@
1
+ export declare function isRecord(value: unknown): value is Record<string, unknown>;
2
+ export declare function requireString(args: Record<string, unknown>, name: string): string;
3
+ export declare function requireEnum<T extends string>(args: Record<string, unknown>, name: string, values: readonly T[]): T;
4
+ export declare function objectSchema(properties: Record<string, unknown>, required: string[]): Record<string, unknown>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tangle-network/agent-app",
3
- "version": "0.60.228",
3
+ "version": "0.60.230",
4
4
  "packageManager": "pnpm@11.24.0",
5
5
  "description": "Build agent applications with typed chat, tools, sandboxes, integrations, billing, and evaluation.",
6
6
  "keywords": [