@theokit/sdk 2.24.0 → 2.25.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 2.25.0
+
+### Minor Changes
+
+- 5067b50: **SE20 — `agent.skills.get(name)` (read a skill's full body).**
+
+  `agent.skills.list()` already returned skill metadata (name + description only); SE20 adds `agent.skills.get(name)` returning the skill INCLUDING its `instructions` (body) — read from the inline `createSkill` body, or from the filesystem SKILL.md (frontmatter stripped) for discovered skills. Returns `undefined` when no enabled skill matches (malformed skills stay excluded). New public type `SDKAgentSkillDetail`.
+
+  `list()` stays lean (the `<skills>` block only ever carries name + description); full bodies come only through `get`. Mirrors Mastra's `agent.getSkill(name)`. Additive + backward-compatible. From the Mastra Agent-skills comparison (SDK Evolution roadmap SE20).
+
+- 09865ee: **SE21 — `references` on `createSkill` (bundle supporting docs on an inline skill).**
+
+  `createSkill({ ..., references })` now accepts an optional `references` map (filename → content), mirroring a filesystem skill's `references/` directory. The docs travel on the inline skill object and surface to the app via `agent.skills.get(name)` (new `references` field on `SDKAgentSkillDetail`); they are NOT injected into the model prompt. Omitted when not provided (backward-compatible). Mirrors Mastra Agent-skills `references`.
+
+  Also closes a latent boundary leak surfaced by this change: `agent.skills.list()` now projects to the public shape (name + description only), so an inline skill's `instructions` / `references` / `source` never leak through `list()` — the body is reachable exclusively through `get()`, matching the documented `SystemPromptSkillRef` contract. From the Mastra Agent-skills comparison (SDK Evolution roadmap SE21).
+
+- abfcc5d: **SE22 — dynamic skills resolver (`skills: (ctx) => SkillsSettings`).**
+
+  `AgentOptions.skills` now accepts a resolver function in addition to the static `SkillsSettings` object. The resolver receives a per-send context (`agentId`, `cwd`, `model`, `userMessage`, `memory` — mirroring the systemPrompt resolver's context, minus the not-yet-resolved `skills`) and returns the `SkillsSettings` for that run. It is evaluated per `send()` before skill assembly, so a cached `getOrCreate` agent re-resolves each run — pick skills from runtime context (e.g. the user's role).
+
+  A static object behaves exactly as today. The agent-scoped `agent.skills` handle reflects the static/base config; the resolver drives the per-send `<skills>` block. The SDK imposes no timeout (wrap your own `Promise.race`); a throwing resolver fails the run — no silent fallback (Rule 8). Cloud agents reject a function resolver (it can't run on PaaS — resolve to a static object first), mirroring the systemPrompt-resolver cloud rule. New public types `SkillsResolver` + `SkillsResolverContext`. Mirrors Mastra Agent-skills `skills: ({ requestContext }) => SkillInput[]`. From the Mastra Agent-skills comparison (SDK Evolution roadmap SE22).
+
+- 0b9c0ac: **SE23 — `defineSkillReadTool` (opt-in model-facing lazy skill read).**
+
+  `defineSkillReadTool(skills)` returns a `skill_read` `CustomTool` the consumer explicitly adds to `AgentOptions.tools`. When the model calls it with a skill name, the handler returns that skill's `instructions` (+ SE21 `references`); an unknown-but-well-formed name returns a typed "not found" string listing the available skills — NOT a throw that kills the run (Rule 8). Malformed input (missing `name`) fails at the trust boundary via the input schema.
+
+  The SDK never auto-injects it — bring-your-own-tools stays intact (sibling of `defineSubAgent` / `workflowAsTool`). This is the LAZY read path that complements the eager `<skills>` block (name + description only): the block discloses which skills exist; `skill_read` loads a body on demand. The consumer controls exposure by choosing which skills to pass. See ADR 0007. Mirrors Mastra's `skill_read` — but opt-in, not auto-injected. From the Mastra Agent-skills comparison (SDK Evolution roadmap SE23).
+
 ## 2.24.0
 
 ### Minor Changes

package/dist/a2a/index.cjs

@@ -1553,7 +1553,8 @@ function stripSecretsFromOptions(options) {
     local: serializeLocal(options.local),
     cloud: serializeCloud(options.cloud),
     memory: serializeMemory(options.memory),
-    skills: serializeEnabledList(options.skills),
+    // SE22 — a SkillsResolver function isn't serializable; persist only the static form.
+    skills: serializeEnabledList(typeof options.skills === "function" ? void 0 : options.skills),
     // Code-`Plugin` objects are closures and cannot be persisted (like custom
     // tools); only the named-enable settings form is serialized.
     plugins: serializeEnabledList(asPluginsSettings(options.plugins)),
@@ -1883,6 +1884,7 @@ function serializeCloud2(cloud) {
   return result;
 }
 function serializeSkills(skills) {
+  if (typeof skills === "function") return void 0;
   if (skills?.enabled === void 0 || skills.enabled.length === 0) return void 0;
   return { enabled: [...skills.enabled] };
 }
@@ -3451,6 +3453,7 @@ var init_cloud_agent = __esm({
 function validateCloudToolParity(options) {
   if (options.cloud === void 0) return;
   rejectFunctionSystemPrompt(options);
+  rejectFunctionSkills(options);
   rejectStdioMcpLocalPaths(options);
 }
 function rejectFunctionSystemPrompt(options) {
@@ -3461,6 +3464,14 @@ function rejectFunctionSystemPrompt(options) {
     );
   }
 }
+function rejectFunctionSkills(options) {
+  if (typeof options.skills === "function") {
+    throw new ConfigurationError(
+      "Cloud agents require skills as a static settings object. SkillsResolver functions can't run on PaaS \u2014 resolve to a SkillsSettings object before Agent.create() or move the dynamic logic into a hook rule.",
+      { code: "cloud_incompatible_function_resolver" }
+    );
+  }
+}
 function rejectStdioMcpLocalPaths(options) {
   if (options.mcpServers === void 0) return;
   for (const [name, config] of Object.entries(options.mcpServers)) {
@@ -5693,9 +5704,235 @@ var init_subagents_loader = __esm({
   }
 });
 
+// src/internal/runtime/skills/skill-frontmatter.ts
+function asString(v) {
+  return typeof v === "string" ? v : void 0;
+}
+function toStringFields(raw) {
+  const out = {};
+  for (const [k, v] of Object.entries(raw)) out[k] = asString(v);
+  return out;
+}
+function parseSkillFrontmatter(raw, fallbackName) {
+  const fields = extractAndParseFrontmatter(raw, fallbackName);
+  const name = resolveName(fields, fallbackName);
+  ensureRequiredFields(fields, name);
+  return buildFrontmatter(fields, name);
+}
+function stripSkillFrontmatter(raw) {
+  const match = /^---\s*\n[\s\S]*?\n---\s*\n/.exec(raw);
+  return (match === null ? raw : raw.slice(match[0].length)).trim();
+}
+function extractAndParseFrontmatter(raw, fallbackName) {
+  const match = /^---\s*\n([\s\S]*?)\n---\s*\n/.exec(raw);
+  if (match === null) {
+    throw new ConfigurationError(`Skill ${fallbackName} is missing frontmatter`, {
+      code: "missing_frontmatter"
+    });
+  }
+  const frontmatter = match[1] ?? "";
+  try {
+    return toStringFields(parseSimpleYaml(frontmatter));
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new ConfigurationError(
+      `Skill ${fallbackName} has malformed YAML frontmatter: ${detail}`,
+      { code: "schema_invalid", cause }
+    );
+  }
+}
+function resolveName(fields, fallbackName) {
+  if (hasContent(fields.name)) return fields.name;
+  if (hasContent(fallbackName)) return fallbackName;
+  throw new ConfigurationError("Skill at unknown path is missing required field: name", {
+    code: "schema_invalid"
+  });
+}
+function ensureRequiredFields(fields, name) {
+  if (!hasContent(fields.description)) {
+    throw new ConfigurationError(`Skill ${name} is missing required field: description`, {
+      code: "schema_invalid"
+    });
+  }
+}
+function buildFrontmatter(fields, name) {
+  const description = fields.description;
+  if (description === void 0) {
+    throw new ConfigurationError(`Skill ${name} missing description`, { code: "schema_invalid" });
+  }
+  const result = { name, description };
+  if (hasContent(fields.category)) result.category = fields.category;
+  const deps = parseDependencies(fields.dependencies);
+  if (deps !== void 0) result.dependencies = deps;
+  return result;
+}
+function parseDependencies(raw) {
+  if (!hasContent(raw)) return void 0;
+  const deps = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return deps.length > 0 ? deps : void 0;
+}
+function hasContent(value) {
+  return value !== void 0 && value.trim().length > 0;
+}
+var init_skill_frontmatter = __esm({
+  "src/internal/runtime/skills/skill-frontmatter.ts"() {
+    init_errors();
+    init_yaml_frontmatter();
+  }
+});
+async function discoverSkills(dir, options) {
+  let entries;
+  try {
+    entries = await readWorkspaceDir(dir, "skills_read_error", "skills directory");
+  } catch {
+    return [];
+  }
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    let skillDir;
+    try {
+      skillDir = safePathJoin(dir, entry.name);
+      assertNoSymlinkEscape(skillDir, dir);
+    } catch {
+      continue;
+    }
+    const skillPath = path.join(skillDir, "SKILL.md");
+    let raw;
+    try {
+      raw = await promises.readFile(skillPath, "utf8");
+    } catch {
+      continue;
+    }
+    const skill = tryParseSkill(raw, entry.name, skillPath, options);
+    if (skill !== void 0) skills.push(skill);
+  }
+  return skills;
+}
+function tryParseSkill(raw, fallbackName, source, options) {
+  try {
+    const frontmatter = parseSkillFrontmatter(raw, fallbackName);
+    const skill = {
+      name: frontmatter.name,
+      description: frontmatter.description,
+      source
+    };
+    if (frontmatter.category !== void 0) skill.category = frontmatter.category;
+    if (frontmatter.dependencies !== void 0) skill.dependencies = frontmatter.dependencies;
+    return skill;
+  } catch (cause) {
+    if (cause instanceof ConfigurationError) {
+      options?.onInvalidSkill?.({
+        name: fallbackName,
+        source,
+        code: cause.code ?? "unknown",
+        message: cause.message
+      });
+      return void 0;
+    }
+    throw cause;
+  }
+}
+var init_discover_skills = __esm({
+  "src/internal/runtime/skills/discover-skills.ts"() {
+    init_errors();
+    init_path_guard();
+    init_workspace_dir();
+    init_skill_frontmatter();
+  }
+});
+var SkillsManager;
+var init_skills_manager = __esm({
+  "src/internal/runtime/skills/skills-manager.ts"() {
+    init_discover_skills();
+    init_skill_frontmatter();
+    SkillsManager = class {
+      constructor(cwd, _enabled, settingSourcesIncludeProject, skillsDir, inline) {
+        this.cwd = cwd;
+        this.settingSourcesIncludeProject = settingSourcesIncludeProject;
+        this.skillsDir = skillsDir;
+        this.inline = inline;
+      }
+      cwd;
+      settingSourcesIncludeProject;
+      skillsDir;
+      inline;
+      skills = [];
+      async initialize() {
+        if (!this.settingSourcesIncludeProject) {
+          this.skills = this.mergeInline([]);
+          return;
+        }
+        await this.refresh();
+      }
+      async refresh() {
+        const skillsRoot = this.skillsDir ?? path.join(this.cwd, ".theokit", "skills");
+        const discovered = await discoverSkills(skillsRoot, {
+          onInvalidSkill: (info) => {
+            process.stderr.write(
+              `[theokit-sdk] skill ${info.name} skipped (${info.code}): ${info.message}
+`
+            );
+          }
+        });
+        this.skills = this.mergeInline(discovered);
+      }
+      /** M22 — merge inline skills over discovered ones; inline wins on a name conflict. */
+      mergeInline(discovered) {
+        if (this.inline === void 0 || this.inline.length === 0) return discovered;
+        const inlineNames = new Set(this.inline.map((s) => s.name));
+        return [...discovered.filter((s) => !inlineNames.has(s.name)), ...this.inline];
+      }
+      list() {
+        return Promise.resolve(this.skills);
+      }
+      /**
+       * SE20 — resolve a skill by name INCLUDING its body. Inline (`createSkill`)
+       * skills carry `instructions` on the object; filesystem skills read the body
+       * from their `source` SKILL.md (frontmatter stripped). `undefined` when no
+       * enabled skill matches (malformed skills were already excluded at discovery).
+       */
+      async get(name) {
+        const skill = this.skills.find((s) => s.name === name);
+        if (skill === void 0) return void 0;
+        const instructions = typeof skill.instructions === "string" ? skill.instructions : stripSkillFrontmatter(await promises.readFile(skill.source, "utf8"));
+        const references = skill.references;
+        return {
+          name: skill.name,
+          description: skill.description,
+          instructions,
+          ...references !== void 0 ? { references } : {}
+        };
+      }
+    };
+  }
+});
+
 // src/internal/runtime/system-prompt/local-assembly.ts
-async function buildSystemPromptContext(inputs, userText, memoryFacts) {
-  const skills = inputs.skillsManager !== void 0 ? await inputs.skillsManager.list() : [];
+async function resolveSendSkills(inputs, userText, memoryFacts) {
+  const skills = inputs.options.skills;
+  if (typeof skills !== "function") {
+    return { manager: inputs.skillsManager, autoInject: skills?.autoInject ?? true };
+  }
+  const settings = await skills({
+    agentId: inputs.agentId,
+    cwd: inputs.workspaceCwd,
+    model: inputs.model,
+    userMessage: userText,
+    memory: memoryFacts.map((fact) => ({ text: fact.text }))
+  });
+  const manager = new SkillsManager(
+    inputs.workspaceCwd,
+    settings.enabled,
+    inputs.settingSourcesIncludeProject,
+    settings.skillsDir,
+    settings.inline
+  );
+  await manager.initialize();
+  return { manager, autoInject: settings.autoInject ?? true };
+}
+async function buildSystemPromptContext(inputs, userText, memoryFacts, manager = inputs.skillsManager) {
+  const skills = manager !== void 0 ? await manager.list() : [];
   return {
     agentId: inputs.agentId,
     cwd: inputs.workspaceCwd,
@@ -5706,10 +5943,11 @@ async function buildSystemPromptContext(inputs, userText, memoryFacts) {
   };
 }
 async function buildAssemblyContext(inputs, userText, baseSystemPrompt, memoryFacts, activeMemorySummary) {
-  const baseCtx = await buildSystemPromptContext(inputs, userText, memoryFacts);
+  const resolved = await resolveSendSkills(inputs, userText, memoryFacts);
+  const baseCtx = await buildSystemPromptContext(inputs, userText, memoryFacts, resolved.manager);
   const assemblyCtx = {
     ...baseCtx,
-    skillsAutoInject: inputs.options.skills?.autoInject ?? true,
+    skillsAutoInject: resolved.autoInject,
     memoryAutoInject: inputs.options.memory?.autoInject ?? true
   };
   if (baseSystemPrompt !== void 0) assemblyCtx.baseSystemPrompt = baseSystemPrompt;
@@ -5735,6 +5973,7 @@ async function assembleSystemPromptForSend(inputs, userText, baseSystemPrompt, m
 }
 var init_local_assembly = __esm({
   "src/internal/runtime/system-prompt/local-assembly.ts"() {
+    init_skills_manager();
   }
 });
 
@@ -7080,187 +7319,6 @@ var init_plugins_manager = __esm({
   }
 });
 
-// src/internal/runtime/skills/skill-frontmatter.ts
-function asString(v) {
-  return typeof v === "string" ? v : void 0;
-}
-function toStringFields(raw) {
-  const out = {};
-  for (const [k, v] of Object.entries(raw)) out[k] = asString(v);
-  return out;
-}
-function parseSkillFrontmatter(raw, fallbackName) {
-  const fields = extractAndParseFrontmatter(raw, fallbackName);
-  const name = resolveName(fields, fallbackName);
-  ensureRequiredFields(fields, name);
-  return buildFrontmatter(fields, name);
-}
-function extractAndParseFrontmatter(raw, fallbackName) {
-  const match = /^---\s*\n([\s\S]*?)\n---\s*\n/.exec(raw);
-  if (match === null) {
-    throw new ConfigurationError(`Skill ${fallbackName} is missing frontmatter`, {
-      code: "missing_frontmatter"
-    });
-  }
-  const frontmatter = match[1] ?? "";
-  try {
-    return toStringFields(parseSimpleYaml(frontmatter));
-  } catch (cause) {
-    const detail = cause instanceof Error ? cause.message : String(cause);
-    throw new ConfigurationError(
-      `Skill ${fallbackName} has malformed YAML frontmatter: ${detail}`,
-      { code: "schema_invalid", cause }
-    );
-  }
-}
-function resolveName(fields, fallbackName) {
-  if (hasContent(fields.name)) return fields.name;
-  if (hasContent(fallbackName)) return fallbackName;
-  throw new ConfigurationError("Skill at unknown path is missing required field: name", {
-    code: "schema_invalid"
-  });
-}
-function ensureRequiredFields(fields, name) {
-  if (!hasContent(fields.description)) {
-    throw new ConfigurationError(`Skill ${name} is missing required field: description`, {
-      code: "schema_invalid"
-    });
-  }
-}
-function buildFrontmatter(fields, name) {
-  const description = fields.description;
-  if (description === void 0) {
-    throw new ConfigurationError(`Skill ${name} missing description`, { code: "schema_invalid" });
-  }
-  const result = { name, description };
-  if (hasContent(fields.category)) result.category = fields.category;
-  const deps = parseDependencies(fields.dependencies);
-  if (deps !== void 0) result.dependencies = deps;
-  return result;
-}
-function parseDependencies(raw) {
-  if (!hasContent(raw)) return void 0;
-  const deps = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  return deps.length > 0 ? deps : void 0;
-}
-function hasContent(value) {
-  return value !== void 0 && value.trim().length > 0;
-}
-var init_skill_frontmatter = __esm({
-  "src/internal/runtime/skills/skill-frontmatter.ts"() {
-    init_errors();
-    init_yaml_frontmatter();
-  }
-});
-async function discoverSkills(dir, options) {
-  let entries;
-  try {
-    entries = await readWorkspaceDir(dir, "skills_read_error", "skills directory");
-  } catch {
-    return [];
-  }
-  const skills = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    let skillDir;
-    try {
-      skillDir = safePathJoin(dir, entry.name);
-      assertNoSymlinkEscape(skillDir, dir);
-    } catch {
-      continue;
-    }
-    const skillPath = path.join(skillDir, "SKILL.md");
-    let raw;
-    try {
-      raw = await promises.readFile(skillPath, "utf8");
-    } catch {
-      continue;
-    }
-    const skill = tryParseSkill(raw, entry.name, skillPath, options);
-    if (skill !== void 0) skills.push(skill);
-  }
-  return skills;
-}
-function tryParseSkill(raw, fallbackName, source, options) {
-  try {
-    const frontmatter = parseSkillFrontmatter(raw, fallbackName);
-    const skill = {
-      name: frontmatter.name,
-      description: frontmatter.description,
-      source
-    };
-    if (frontmatter.category !== void 0) skill.category = frontmatter.category;
-    if (frontmatter.dependencies !== void 0) skill.dependencies = frontmatter.dependencies;
-    return skill;
-  } catch (cause) {
-    if (cause instanceof ConfigurationError) {
-      options?.onInvalidSkill?.({
-        name: fallbackName,
-        source,
-        code: cause.code ?? "unknown",
-        message: cause.message
-      });
-      return void 0;
-    }
-    throw cause;
-  }
-}
-var init_discover_skills = __esm({
-  "src/internal/runtime/skills/discover-skills.ts"() {
-    init_errors();
-    init_path_guard();
-    init_workspace_dir();
-    init_skill_frontmatter();
-  }
-});
-var SkillsManager;
-var init_skills_manager = __esm({
-  "src/internal/runtime/skills/skills-manager.ts"() {
-    init_discover_skills();
-    SkillsManager = class {
-      constructor(cwd, _enabled, settingSourcesIncludeProject, skillsDir, inline) {
-        this.cwd = cwd;
-        this.settingSourcesIncludeProject = settingSourcesIncludeProject;
-        this.skillsDir = skillsDir;
-        this.inline = inline;
-      }
-      cwd;
-      settingSourcesIncludeProject;
-      skillsDir;
-      inline;
-      skills = [];
-      async initialize() {
-        if (!this.settingSourcesIncludeProject) {
-          this.skills = this.mergeInline([]);
-          return;
-        }
-        await this.refresh();
-      }
-      async refresh() {
-        const skillsRoot = this.skillsDir ?? path.join(this.cwd, ".theokit", "skills");
-        const discovered = await discoverSkills(skillsRoot, {
-          onInvalidSkill: (info) => {
-            process.stderr.write(
-              `[theokit-sdk] skill ${info.name} skipped (${info.code}): ${info.message}
-`
-            );
-          }
-        });
-        this.skills = this.mergeInline(discovered);
-      }
-      /** M22 — merge inline skills over discovered ones; inline wins on a name conflict. */
-      mergeInline(discovered) {
-        if (this.inline === void 0 || this.inline.length === 0) return discovered;
-        const inlineNames = new Set(this.inline.map((s) => s.name));
-        return [...discovered.filter((s) => !inlineNames.has(s.name)), ...this.inline];
-      }
-      list() {
-        return Promise.resolve(this.skills);
-      }
-    };
-  }
-});
-
 // src/internal/runtime/local-agent/local-agent-bootstrap.ts
 function registerLocalAgent(args) {
   registerAgent({
@@ -7296,16 +7354,23 @@ function bootstrapSubmanagers(args) {
     );
   }
   if (args.options.skills !== void 0 || args.settingSourcesIncludeProject) {
+    const staticSkills = typeof args.options.skills === "function" ? void 0 : args.options.skills;
     out.skillsManager = new SkillsManager(
       args.workspaceCwd,
-      args.options.skills?.enabled,
+      staticSkills?.enabled,
       args.settingSourcesIncludeProject,
       // M22 — custom skills directory + inline (code-defined) skills.
-      args.options.skills?.skillsDir,
-      args.options.skills?.inline
+      staticSkills?.skillsDir,
+      staticSkills?.inline
     );
     const localSkills = out.skillsManager;
-    out.skills = { list: () => localSkills.list() };
+    out.skills = {
+      // Project to the public shape (name + description only). Inline skills carry
+      // their body + references on the object; `list()` must never leak them —
+      // the body is reachable exclusively through `get()`.
+      list: async () => (await localSkills.list()).map((s) => ({ name: s.name, description: s.description })),
+      get: (name) => localSkills.get(name)
+    };
   }
   if (args.options.plugins !== void 0 || args.settingSourcesIncludePlugins) {
     out.pluginsManager = new PluginsManager(
@@ -17235,7 +17300,7 @@ var init_local_agent = __esm({
       }
       // biome-ignore format: G8 budget — thin accessor for the assembly inputs.
       assemblyInputs() {
-        return { agentId: this.agentId, workspaceCwd: this.workspaceCwd, model: this.model, options: this.options, context: this.context, skillsManager: this.skillsManager, systemPromptPipeline: this.systemPromptPipeline };
+        return { agentId: this.agentId, workspaceCwd: this.workspaceCwd, model: this.model, options: this.options, context: this.context, skillsManager: this.skillsManager, settingSourcesIncludeProject: this.settingSourcesIncludeProject, systemPromptPipeline: this.systemPromptPipeline };
       }
       async resolveSystemPrompt(userText, options, memoryFacts) {
         const base = await resolveSystemPromptForSend(