@theokit/sdk 2.19.0 → 2.20.0

package/dist/create-skill.d.ts

@@ -0,0 +1,29 @@
+/**
+ * M22 — `createSkill`: define a skill in TypeScript, without a `SKILL.md` file on disk.
+ *
+ * An inline skill is usable ALONGSIDE filesystem skills (`AgentOptions.skills.inline`), and points
+ * an agent at code-defined capabilities without a `.theokit/skills/<name>/SKILL.md`. Like file
+ * skills, its `name` + `description` surface in the `<skills>` system-prompt block; its
+ * `instructions` (the body) travel on the object for the consumer (the SDK injects name+description,
+ * not bodies — inline and file skills are symmetric there). Inline skills override file skills on a
+ * name conflict (mirrors the subagents-loader precedent).
+ */
+import type { Skill } from "./internal/runtime/skills/discover-skills.js";
+/** A code-defined skill (from {@link createSkill}) — a {@link Skill} plus its inline body. */
+export interface InlineSkill extends Skill {
+    /** The skill body/instructions (inline skills carry it here instead of a SKILL.md file). */
+    instructions: string;
+}
+/** Spec accepted by {@link createSkill}. */
+export interface CreateSkillSpec {
+    name: string;
+    description: string;
+    instructions: string;
+    category?: string;
+    dependencies?: string[];
+}
+/**
+ * Build an {@link InlineSkill} from a code spec. Fails fast on an empty `name`/`description`
+ * (error-handling.md). The synthetic `source` (`inline://<name>`) marks it as file-less.
+ */
+export declare function createSkill(spec: CreateSkillSpec): InlineSkill;

package/dist/{cron-D_wK1S-0.d.cts → cron-B8fqui49.d.cts}

@@ -680,6 +680,53 @@ interface ConversationStorageAdapter {
     dispose?(): Promise<void>;
 }
 
+/**
+ * A discovered skill's metadata. The skill BODY is never included — only the
+ * strict frontmatter fields plus the resolved `source` path.
+ *
+ * Public via `@theokit/sdk/skills`.
+ *
+ * @public
+ */
+interface Skill {
+    name: string;
+    description: string;
+    /** Absolute path to the discovered `SKILL.md`. */
+    source: string;
+    category?: string;
+    dependencies?: string[];
+}
+
+/**
+ * M22 — `createSkill`: define a skill in TypeScript, without a `SKILL.md` file on disk.
+ *
+ * An inline skill is usable ALONGSIDE filesystem skills (`AgentOptions.skills.inline`), and points
+ * an agent at code-defined capabilities without a `.theokit/skills/<name>/SKILL.md`. Like file
+ * skills, its `name` + `description` surface in the `<skills>` system-prompt block; its
+ * `instructions` (the body) travel on the object for the consumer (the SDK injects name+description,
+ * not bodies — inline and file skills are symmetric there). Inline skills override file skills on a
+ * name conflict (mirrors the subagents-loader precedent).
+ */
+
+/** A code-defined skill (from {@link createSkill}) — a {@link Skill} plus its inline body. */
+interface InlineSkill extends Skill {
+    /** The skill body/instructions (inline skills carry it here instead of a SKILL.md file). */
+    instructions: string;
+}
+/** Spec accepted by {@link createSkill}. */
+interface CreateSkillSpec {
+    name: string;
+    description: string;
+    instructions: string;
+    category?: string;
+    dependencies?: string[];
+}
+/**
+ * Build an {@link InlineSkill} from a code spec. Fails fast on an empty `name`/`description`
+ * (error-handling.md). The synthetic `source` (`inline://<name>`) marks it as file-less.
+ */
+declare function createSkill(spec: CreateSkillSpec): InlineSkill;
+
 /**
  * Context manager backend.
  *
@@ -1182,6 +1229,16 @@ interface SkillsSettings {
      * skills itself.
      */
     autoInject?: boolean;
+    /**
+     * M22 — discover skills from a CUSTOM directory (containing `<name>/SKILL.md`) instead of the
+     * default `<cwd>/.theokit/skills`. Absent ⇒ the default root.
+     */
+    skillsDir?: string;
+    /**
+     * M22 — code-defined skills (from `createSkill`) merged with the discovered ones. An inline skill
+     * overrides a discovered file skill of the same name.
+     */
+    inline?: InlineSkill[];
 }
 /**
  * Memory configuration accepted by `Agent.create()` via {@link AgentOptions.memory}.
@@ -2039,4 +2096,4 @@ declare class Cron {
     static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
 }
 
-export { type GoalResult as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type CloudRepo as D, type ContextBudget as E, type ContextManagerKind as F, type GetAgentOptions as G, type ContextSnapshot as H, type ContextSource as I, type ContextSourceStatus as J, Cron as K, type LocalOptions as L, type MemorySettings as M, type CronCreateOptions as N, type CronGetOptions as O, type ProviderRoutingSettings as P, type CronJob as Q, type CronJobStatus as R, type SystemPromptResolver as S, type CronListOptions as T, type CronOperationOptions as U, type CronRunOptions as V, type CronRuntime as W, type CronSchedulerStatus as X, type CronStartOptions as Y, type GoalEvent as Z, type GoalOptions as _, type AgentDefinition as a, type HookName as a0, type InvalidateCacheOptions as a1, type MemoryAdapter as a2, type MemoryAdapterCapabilities as a3, type MemoryContext as a4, type MemoryFact as a5, type MemoryProviderHandle as a6, type MemoryProviderInitOptions as a7, type MemoryRevision as a8, type MemoryToolSchema as a9, type MemoryTurnMessage as aa, type PersonalityPreset as ab, type PluginContext as ac, type PostAssistantReplyContext as ad, type PreToolCallContext as ae, type PreUserSendContext as af, type PreUserSendResult as ag, type ProviderCapability as ah, type ProviderRoute as ai, type RecordSessionSummaryArgs as aj, type ResolvedProviderRoute as ak, type RunUntilIterator as al, type SDKAgentPlugins as am, type SDKAgentSkills as an, type SDKArtifact as ao, type SDKContextManager as ap, type SDKPluginMetadata as aq, type SDKProvidersManager as ar, type SettingSource as as, type SystemPromptContext as at, type SystemPromptMemoryFact as au, type SystemPromptSkillRef as av, type TelemetrySettings as aw, definePlugin as ax, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, type Plugin as m, type ConversationStorageAdapter as n, type StoredMessage as o, type MemoryProvider as p, type MemoryId as q, type PreToolCallDecision as r, type SDKProvider as s, type ActiveMemoryPassArgs as t, type ActiveMemoryPassResult as u, type AgentMemory as v, type BudgetCheck as w, type BudgetTotal as x, type BudgetUsageEvent as y, type CloudEnv as z };
+export { type GoalOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type CloudRepo as D, type ContextBudget as E, type ContextManagerKind as F, type GetAgentOptions as G, type ContextSnapshot as H, type ContextSource as I, type ContextSourceStatus as J, type CreateSkillSpec as K, type LocalOptions as L, type MemorySettings as M, Cron as N, type CronCreateOptions as O, type ProviderRoutingSettings as P, type CronGetOptions as Q, type CronJob as R, type SystemPromptResolver as S, type CronJobStatus as T, type CronListOptions as U, type CronOperationOptions as V, type CronRunOptions as W, type CronRuntime as X, type CronSchedulerStatus as Y, type CronStartOptions as Z, type GoalEvent as _, type AgentDefinition as a, type GoalResult as a0, type HookName as a1, type InlineSkill as a2, type InvalidateCacheOptions as a3, type MemoryAdapter as a4, type MemoryAdapterCapabilities as a5, type MemoryContext as a6, type MemoryFact as a7, type MemoryProviderHandle as a8, type MemoryProviderInitOptions as a9, definePlugin as aA, type MemoryRevision as aa, type MemoryToolSchema as ab, type MemoryTurnMessage as ac, type PersonalityPreset as ad, type PluginContext as ae, type PostAssistantReplyContext as af, type PreToolCallContext as ag, type PreUserSendContext as ah, type PreUserSendResult as ai, type ProviderCapability as aj, type ProviderRoute as ak, type RecordSessionSummaryArgs as al, type ResolvedProviderRoute as am, type RunUntilIterator as an, type SDKAgentPlugins as ao, type SDKAgentSkills as ap, type SDKArtifact as aq, type SDKContextManager as ar, type SDKPluginMetadata as as, type SDKProvidersManager as at, type SettingSource as au, type SystemPromptContext as av, type SystemPromptMemoryFact as aw, type SystemPromptSkillRef as ax, type TelemetrySettings as ay, createSkill as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, type Plugin as m, type ConversationStorageAdapter as n, type StoredMessage as o, type MemoryProvider as p, type MemoryId as q, type PreToolCallDecision as r, type SDKProvider as s, type ActiveMemoryPassArgs as t, type ActiveMemoryPassResult as u, type AgentMemory as v, type BudgetCheck as w, type BudgetTotal as x, type BudgetUsageEvent as y, type CloudEnv as z };

package/dist/{cron-Cep07kTz.d.ts → cron-D2yLOrk2.d.ts}

@@ -680,6 +680,53 @@ interface ConversationStorageAdapter {
     dispose?(): Promise<void>;
 }
 
+/**
+ * A discovered skill's metadata. The skill BODY is never included — only the
+ * strict frontmatter fields plus the resolved `source` path.
+ *
+ * Public via `@theokit/sdk/skills`.
+ *
+ * @public
+ */
+interface Skill {
+    name: string;
+    description: string;
+    /** Absolute path to the discovered `SKILL.md`. */
+    source: string;
+    category?: string;
+    dependencies?: string[];
+}
+
+/**
+ * M22 — `createSkill`: define a skill in TypeScript, without a `SKILL.md` file on disk.
+ *
+ * An inline skill is usable ALONGSIDE filesystem skills (`AgentOptions.skills.inline`), and points
+ * an agent at code-defined capabilities without a `.theokit/skills/<name>/SKILL.md`. Like file
+ * skills, its `name` + `description` surface in the `<skills>` system-prompt block; its
+ * `instructions` (the body) travel on the object for the consumer (the SDK injects name+description,
+ * not bodies — inline and file skills are symmetric there). Inline skills override file skills on a
+ * name conflict (mirrors the subagents-loader precedent).
+ */
+
+/** A code-defined skill (from {@link createSkill}) — a {@link Skill} plus its inline body. */
+interface InlineSkill extends Skill {
+    /** The skill body/instructions (inline skills carry it here instead of a SKILL.md file). */
+    instructions: string;
+}
+/** Spec accepted by {@link createSkill}. */
+interface CreateSkillSpec {
+    name: string;
+    description: string;
+    instructions: string;
+    category?: string;
+    dependencies?: string[];
+}
+/**
+ * Build an {@link InlineSkill} from a code spec. Fails fast on an empty `name`/`description`
+ * (error-handling.md). The synthetic `source` (`inline://<name>`) marks it as file-less.
+ */
+declare function createSkill(spec: CreateSkillSpec): InlineSkill;
+
 /**
  * Context manager backend.
  *
@@ -1182,6 +1229,16 @@ interface SkillsSettings {
      * skills itself.
      */
     autoInject?: boolean;
+    /**
+     * M22 — discover skills from a CUSTOM directory (containing `<name>/SKILL.md`) instead of the
+     * default `<cwd>/.theokit/skills`. Absent ⇒ the default root.
+     */
+    skillsDir?: string;
+    /**
+     * M22 — code-defined skills (from `createSkill`) merged with the discovered ones. An inline skill
+     * overrides a discovered file skill of the same name.
+     */
+    inline?: InlineSkill[];
 }
 /**
  * Memory configuration accepted by `Agent.create()` via {@link AgentOptions.memory}.
@@ -2039,4 +2096,4 @@ declare class Cron {
     static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
 }
 
-export { type GoalResult as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type CloudRepo as D, type ContextBudget as E, type ContextManagerKind as F, type GetAgentOptions as G, type ContextSnapshot as H, type ContextSource as I, type ContextSourceStatus as J, Cron as K, type LocalOptions as L, type MemorySettings as M, type CronCreateOptions as N, type CronGetOptions as O, type ProviderRoutingSettings as P, type CronJob as Q, type CronJobStatus as R, type SystemPromptResolver as S, type CronListOptions as T, type CronOperationOptions as U, type CronRunOptions as V, type CronRuntime as W, type CronSchedulerStatus as X, type CronStartOptions as Y, type GoalEvent as Z, type GoalOptions as _, type AgentDefinition as a, type HookName as a0, type InvalidateCacheOptions as a1, type MemoryAdapter as a2, type MemoryAdapterCapabilities as a3, type MemoryContext as a4, type MemoryFact as a5, type MemoryProviderHandle as a6, type MemoryProviderInitOptions as a7, type MemoryRevision as a8, type MemoryToolSchema as a9, type MemoryTurnMessage as aa, type PersonalityPreset as ab, type PluginContext as ac, type PostAssistantReplyContext as ad, type PreToolCallContext as ae, type PreUserSendContext as af, type PreUserSendResult as ag, type ProviderCapability as ah, type ProviderRoute as ai, type RecordSessionSummaryArgs as aj, type ResolvedProviderRoute as ak, type RunUntilIterator as al, type SDKAgentPlugins as am, type SDKAgentSkills as an, type SDKArtifact as ao, type SDKContextManager as ap, type SDKPluginMetadata as aq, type SDKProvidersManager as ar, type SettingSource as as, type SystemPromptContext as at, type SystemPromptMemoryFact as au, type SystemPromptSkillRef as av, type TelemetrySettings as aw, definePlugin as ax, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, type Plugin as m, type ConversationStorageAdapter as n, type StoredMessage as o, type MemoryProvider as p, type MemoryId as q, type PreToolCallDecision as r, type SDKProvider as s, type ActiveMemoryPassArgs as t, type ActiveMemoryPassResult as u, type AgentMemory as v, type BudgetCheck as w, type BudgetTotal as x, type BudgetUsageEvent as y, type CloudEnv as z };
+export { type GoalOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type CloudRepo as D, type ContextBudget as E, type ContextManagerKind as F, type GetAgentOptions as G, type ContextSnapshot as H, type ContextSource as I, type ContextSourceStatus as J, type CreateSkillSpec as K, type LocalOptions as L, type MemorySettings as M, Cron as N, type CronCreateOptions as O, type ProviderRoutingSettings as P, type CronGetOptions as Q, type CronJob as R, type SystemPromptResolver as S, type CronJobStatus as T, type CronListOptions as U, type CronOperationOptions as V, type CronRunOptions as W, type CronRuntime as X, type CronSchedulerStatus as Y, type CronStartOptions as Z, type GoalEvent as _, type AgentDefinition as a, type GoalResult as a0, type HookName as a1, type InlineSkill as a2, type InvalidateCacheOptions as a3, type MemoryAdapter as a4, type MemoryAdapterCapabilities as a5, type MemoryContext as a6, type MemoryFact as a7, type MemoryProviderHandle as a8, type MemoryProviderInitOptions as a9, definePlugin as aA, type MemoryRevision as aa, type MemoryToolSchema as ab, type MemoryTurnMessage as ac, type PersonalityPreset as ad, type PluginContext as ae, type PostAssistantReplyContext as af, type PreToolCallContext as ag, type PreUserSendContext as ah, type PreUserSendResult as ai, type ProviderCapability as aj, type ProviderRoute as ak, type RecordSessionSummaryArgs as al, type ResolvedProviderRoute as am, type RunUntilIterator as an, type SDKAgentPlugins as ao, type SDKAgentSkills as ap, type SDKArtifact as aq, type SDKContextManager as ar, type SDKPluginMetadata as as, type SDKProvidersManager as at, type SettingSource as au, type SystemPromptContext as av, type SystemPromptMemoryFact as aw, type SystemPromptSkillRef as ax, type TelemetrySettings as ay, createSkill as az, type ContextSettings as b, type PluginsSettings as c, type SkillsSettings as d, type SDKAgent as e, type ListAgentsOptions as f, type ListResult as g, type SDKAgentInfo as h, type ListRunsOptions as i, type GetRunOptions as j, type AgentOperationOptions as k, type ProviderProfile as l, type Plugin as m, type ConversationStorageAdapter as n, type StoredMessage as o, type MemoryProvider as p, type MemoryId as q, type PreToolCallDecision as r, type SDKProvider as s, type ActiveMemoryPassArgs as t, type ActiveMemoryPassResult as u, type AgentMemory as v, type BudgetCheck as w, type BudgetTotal as x, type BudgetUsageEvent as y, type CloudEnv as z };

package/dist/cron.cjs

@@ -2269,6 +2269,24 @@ function salvagePartial(schema, raw) {
   }
   return out;
 }
+async function runReasoningPhase(options, deps) {
+  const reasoningOptions = {
+    model: options.model,
+    local: options.local,
+    ...options.systemPrompt !== void 0 ? { systemPrompt: options.systemPrompt } : {},
+    ...options.apiKey !== void 0 ? { apiKey: options.apiKey } : {},
+    ...options.providers !== void 0 ? { providers: options.providers } : {}
+  };
+  const reasoningAgent = await deps.create(reasoningOptions);
+  try {
+    const run = await reasoningAgent.send(options.prompt);
+    const result = await run.wait();
+    const text = result.result;
+    return typeof text === "string" ? text : options.prompt;
+  } finally {
+    await disposeAndDeleteTransient(reasoningAgent, deps.delete);
+  }
+}
 async function generateObjectImpl(options, deps) {
   const { jsonSchema, maxRetries, initialUsage } = setupStructuredOutput(
     options.schema,
@@ -2291,8 +2309,11 @@ async function generateObjectImpl(options, deps) {
     }
     throw new CaptureSentinel(input);
   });
+  const reasoningText = options.structuringModel !== void 0 ? await runReasoningPhase(options, deps) : void 0;
+  const structuringModel = options.structuringModel ?? options.model;
+  const structuringPrompt = reasoningText ?? options.prompt;
   const agentOptions = buildTransientAgentOptions({
-    model: options.model,
+    model: structuringModel,
     local: options.local,
     outputTool,
     ...options.systemPrompt !== void 0 ? { systemPrompt: options.systemPrompt } : {},
@@ -2301,7 +2322,7 @@ async function generateObjectImpl(options, deps) {
   });
   const agent = await deps.create(agentOptions);
   try {
-    const userMessage = buildToolPrompt(options.prompt);
+    const userMessage = buildToolPrompt(structuringPrompt);
     let lastParseError;
     for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
       capturedRaw = void 0;
@@ -8341,23 +8362,27 @@ function tryParseSkill(raw, fallbackName, source, options) {
 
 // src/internal/runtime/skills/skills-manager.ts
 var SkillsManager = class {
-  constructor(cwd, _enabled, settingSourcesIncludeProject) {
+  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.skills = this.mergeInline([]);
       return;
     }
     await this.refresh();
   }
   async refresh() {
-    const skillsRoot = path.join(this.cwd, ".theokit", "skills");
-    this.skills = await discoverSkills(skillsRoot, {
+    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}
@@ -8365,6 +8390,13 @@ var SkillsManager = class {
         );
       }
     });
+    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);
@@ -8409,7 +8441,10 @@ function bootstrapSubmanagers(args) {
     out.skillsManager = new SkillsManager(
       args.workspaceCwd,
       args.options.skills?.enabled,
-      args.settingSourcesIncludeProject
+      args.settingSourcesIncludeProject,
+      // M22 — custom skills directory + inline (code-defined) skills.
+      args.options.skills?.skillsDir,
+      args.options.skills?.inline
     );
     const localSkills = out.skillsManager;
     out.skills = { list: () => localSkills.list() };