@theokit/sdk 2.24.0 → 2.25.0

package/dist/index.cjs

@@ -575,10 +575,10 @@ function buildToolPrompt(prompt) {
 Respond by calling the \`output\` tool with the structured answer that matches the schema.`;
 }
 function setupStructuredOutput(schema, maxRetries) {
-  const z8 = requireZod();
+  const z9 = requireZod();
   const jsonSchema = toJsonSchema(schema, { unrepresentable: "any" });
   return {
-    z: z8,
+    z: z9,
     jsonSchema,
     maxRetries: maxRetries ?? 1,
     initialUsage: { inputTokens: 0, outputTokens: 0 }
@@ -6046,7 +6046,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)),
@@ -6354,6 +6355,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] };
 }
@@ -7734,6 +7736,7 @@ init_errors();
 function validateCloudToolParity(options) {
   if (options.cloud === void 0) return;
   rejectFunctionSystemPrompt(options);
+  rejectFunctionSkills(options);
   rejectStdioMcpLocalPaths(options);
 }
 function rejectFunctionSystemPrompt(options) {
@@ -7744,6 +7747,14 @@ function rejectFunctionSystemPrompt(options) {
     );
   }
 }
+function rejectFunctionSkills(options) {
+  if (typeof options.skills === "function") {
+    throw new exports.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)) {
@@ -9570,9 +9581,224 @@ function parseFrontmatterFields(frontmatter) {
   return out;
 }
 
+// src/internal/runtime/skills/discover-skills.ts
+init_errors();
+init_path_guard();
+
+// src/internal/runtime/skills/skill-frontmatter.ts
+init_errors();
+init_yaml_frontmatter();
+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 exports.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 exports.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 exports.ConfigurationError("Skill at unknown path is missing required field: name", {
+    code: "schema_invalid"
+  });
+}
+function ensureRequiredFields(fields, name) {
+  if (!hasContent(fields.description)) {
+    throw new exports.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 exports.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;
+}
+
+// src/internal/runtime/skills/discover-skills.ts
+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 exports.ConfigurationError) {
+      options?.onInvalidSkill?.({
+        name: fallbackName,
+        source,
+        code: cause.code ?? "unknown",
+        message: cause.message
+      });
+      return void 0;
+    }
+    throw cause;
+  }
+}
+
+// src/internal/runtime/skills/skills-manager.ts
+var 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,
@@ -9583,10 +9809,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;
@@ -10839,177 +11066,6 @@ async function loadPluginManifestFromMarkdown(pluginsRoot, folderName) {
   return metadata;
 }
 
-// src/internal/runtime/skills/discover-skills.ts
-init_errors();
-init_path_guard();
-
-// src/internal/runtime/skills/skill-frontmatter.ts
-init_errors();
-init_yaml_frontmatter();
-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 exports.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 exports.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 exports.ConfigurationError("Skill at unknown path is missing required field: name", {
-    code: "schema_invalid"
-  });
-}
-function ensureRequiredFields(fields, name) {
-  if (!hasContent(fields.description)) {
-    throw new exports.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 exports.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;
-}
-
-// src/internal/runtime/skills/discover-skills.ts
-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 exports.ConfigurationError) {
-      options?.onInvalidSkill?.({
-        name: fallbackName,
-        source,
-        code: cause.code ?? "unknown",
-        message: cause.message
-      });
-      return void 0;
-    }
-    throw cause;
-  }
-}
-
-// src/internal/runtime/skills/skills-manager.ts
-var 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({
@@ -11045,16 +11101,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(
@@ -17968,7 +18031,7 @@ var LocalAgent = class {
   }
   // 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(
@@ -19088,7 +19151,8 @@ function createSkill(spec) {
     source: `inline://${spec.name}`,
     instructions: spec.instructions,
     ...spec.category !== void 0 ? { category: spec.category } : {},
-    ...spec.dependencies !== void 0 ? { dependencies: spec.dependencies } : {}
+    ...spec.dependencies !== void 0 ? { dependencies: spec.dependencies } : {},
+    ...spec.references !== void 0 ? { references: spec.references } : {}
   };
 }
 
@@ -19515,6 +19579,46 @@ function defineProvider(profile, opts) {
   };
 }
 
+// src/define-skill-read-tool.ts
+init_to_json_schema();
+var SkillReadInputSchema = zod.z.object({
+  name: zod.z.string().min(1, "skill_read: `name` is required.")
+});
+function renderSkill(skill) {
+  const parts = [`# Skill: ${skill.name}`, "", skill.instructions];
+  const refs = skill.references;
+  if (refs !== void 0 && Object.keys(refs).length > 0) {
+    parts.push("", "## References");
+    for (const [file, content] of Object.entries(refs)) {
+      parts.push("", `### ${file}`, content);
+    }
+  }
+  return parts.join("\n");
+}
+function defineSkillReadTool(skills) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const skill of skills) {
+    if (seen.has(skill.name)) {
+      throw new Error(`defineSkillReadTool: duplicate skill name "${skill.name}".`);
+    }
+    seen.add(skill.name);
+  }
+  return {
+    name: "skill_read",
+    description: "Read a skill's full instructions (and any bundled reference documents) by its name. Use this to load the body of a skill listed in the <skills> block before acting on it.",
+    inputSchema: toJsonSchema(SkillReadInputSchema),
+    handler: (input) => {
+      const { name } = SkillReadInputSchema.parse(input);
+      const skill = skills.find((s) => s.name === name);
+      if (skill === void 0) {
+        const available = skills.map((s) => s.name).join(", ");
+        return `Skill "${name}" not found. Available skills: ${available.length > 0 ? available : "(none)"}.`;
+      }
+      return renderSkill(skill);
+    }
+  };
+}
+
 // src/define-tool.ts
 init_to_json_schema();
 function shapeToolResult(spec, out) {
@@ -21440,6 +21544,7 @@ exports.createSkill = createSkill;
 exports.createSquad = createSquad;
 exports.definePlugin = definePlugin;
 exports.defineProvider = defineProvider;
+exports.defineSkillReadTool = defineSkillReadTool;
 exports.defineTool = defineTool;
 exports.emitRunEvent = emitRunEvent;
 exports.extractRawId = extractRawId;