@theokit/sdk 2.24.0 → 2.26.0

package/dist/create-skill.d.ts

@@ -13,6 +13,12 @@ import type { Skill } from "./internal/runtime/skills/discover-skills.js";
 export interface InlineSkill extends Skill {
     /** The skill body/instructions (inline skills carry it here instead of a SKILL.md file). */
     instructions: string;
+    /**
+     * SE21 — supporting documents bundled with the skill (filename → content),
+     * mirroring a filesystem skill's `references/` directory. Surfaced to the app
+     * via `agent.skills.get(name)`; not injected into the model prompt.
+     */
+    references?: Record<string, string>;
 }
 /** Spec accepted by {@link createSkill}. */
 export interface CreateSkillSpec {
@@ -21,6 +27,8 @@ export interface CreateSkillSpec {
     instructions: string;
     category?: string;
     dependencies?: string[];
+    /** SE21 — supporting documents (filename → content), like a filesystem skill's `references/`. */
+    references?: Record<string, string>;
 }
 /**
  * Build an {@link InlineSkill} from a code spec. Fails fast on an empty `name`/`description`

package/dist/{cron-vjod0qVQ.d.ts → cron-BR1NCSk1.d.cts}

@@ -1,4 +1,4 @@
-import { C as CustomTool, M as ModelSelection, Z as SDKUserMessage, $ as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, F as RunToCompletionOptions, H as RunToCompletionResult, S as SDKMessage, a6 as StreamToCompletionResult, a as McpServerConfig } from './run-Cr0C6cOM.js';
+import { C as CustomTool, M as ModelSelection, a4 as SDKUserMessage, a6 as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, N as RunToCompletionOptions, Q as RunToCompletionResult, S as SDKMessage, ad as StreamToCompletionResult, a as McpServerConfig, P as Processor } from './run-CdWiihyU.cjs';
 import * as zod from 'zod';
 
 /**
@@ -751,6 +751,12 @@ interface Skill {
 interface InlineSkill extends Skill {
     /** The skill body/instructions (inline skills carry it here instead of a SKILL.md file). */
     instructions: string;
+    /**
+     * SE21 — supporting documents bundled with the skill (filename → content),
+     * mirroring a filesystem skill's `references/` directory. Surfaced to the app
+     * via `agent.skills.get(name)`; not injected into the model prompt.
+     */
+    references?: Record<string, string>;
 }
 /** Spec accepted by {@link createSkill}. */
 interface CreateSkillSpec {
@@ -759,6 +765,8 @@ interface CreateSkillSpec {
     instructions: string;
     category?: string;
     dependencies?: string[];
+    /** SE21 — supporting documents (filename → content), like a filesystem skill's `references/`. */
+    references?: Record<string, string>;
 }
 /**
  * Build an {@link InlineSkill} from a code spec. Fails fast on an empty `name`/`description`
@@ -1187,8 +1195,27 @@ interface SystemPromptSkillRef {
  *
  * @public
  */
+/**
+ * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
+ * {@link SystemPromptSkillRef} (name + description only), this carries the full
+ * `instructions` — read from the SKILL.md for filesystem skills or the inline
+ * `createSkill` body. @public
+ */
+interface SDKAgentSkillDetail {
+    name: string;
+    description: string;
+    instructions: string;
+    /** SE21 — supporting documents bundled with the skill (filename → content), when present. */
+    references?: Record<string, string>;
+}
 interface SDKAgentSkills {
     list(): Promise<ReadonlyArray<SystemPromptSkillRef>>;
+    /**
+     * SE20 — resolve a skill by name INCLUDING its body (`instructions`). Returns
+     * `undefined` when no enabled skill matches. `list()` stays lean (name +
+     * description); full bodies come only through `get`.
+     */
+    get(name: string): Promise<SDKAgentSkillDetail | undefined>;
 }
 /**
  * Public plugin metadata returned by `agent.plugins.list()`. Mirrors the
@@ -1279,6 +1306,36 @@ interface SkillsSettings {
      */
     inline?: InlineSkill[];
 }
+/**
+ * SE22 — context passed to a {@link SkillsResolver}. Mirrors
+ * {@link SystemPromptContext} MINUS `skills`: the resolver runs BEFORE skills
+ * are assembled, so the resolved list does not exist yet.
+ *
+ * @public
+ */
+interface SkillsResolverContext {
+    agentId: string;
+    /** Workspace cwd. `string | undefined` mirrors {@link SystemPromptContext}; a local agent always passes a concrete path. */
+    cwd: string | undefined;
+    model: ModelSelection | undefined;
+    userMessage: string;
+    /** Recalled durable facts when memory is enabled. */
+    memory: ReadonlyArray<SystemPromptMemoryFact>;
+}
+/**
+ * SE22 — a resolver that produces {@link SkillsSettings} per run from runtime
+ * context (e.g. the user's role). Mirrors the {@link SystemPromptResolver}
+ * pattern: evaluated per `send()` BEFORE skill assembly, so a cached
+ * `getOrCreate` agent re-resolves on every run.
+ *
+ * The SDK imposes NO timeout — wrap your own `Promise.race` for slow sources. 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
+ * {@link SkillsSettings} object before `Agent.create()`.
+ *
+ * @public
+ */
+type SkillsResolver = (ctx: SkillsResolverContext) => SkillsSettings | Promise<SkillsSettings>;
 /**
  * Memory configuration accepted by `Agent.create()` via {@link AgentOptions.memory}.
  *
@@ -1425,8 +1482,24 @@ interface AgentOptions {
      * The two forms are mutually exclusive — pass one or the other.
      */
     plugins?: PluginsSettings | readonly Plugin[];
-    /** Skills configuration. See `agent.skills`. */
-    skills?: SkillsSettings;
+    /**
+     * Skills configuration. Either a static {@link SkillsSettings} object or —
+     * SE22 — a {@link SkillsResolver} evaluated per `send()` to pick skills from
+     * runtime context (e.g. user role). A cached agent re-resolves each run. The
+     * agent-scoped `agent.skills` handle reflects the STATIC/base config; the
+     * resolver drives the per-send `<skills>` block.
+     */
+    skills?: SkillsSettings | SkillsResolver;
+    /**
+     * SE24 — guardrail processors. `inputProcessors` run in order before the LLM
+     * (normalize / validate / block / rewrite the user message); `outputProcessors`
+     * run on the model's final text before it reaches the caller (redact / block).
+     * A processor that `abort()`s stops the run with a {@link RunResult.tripwire}
+     * (+ a `tripwire` run-event). Empty/absent ⇒ unchanged behavior. See
+     * {@link Processor}.
+     */
+    inputProcessors?: readonly Processor[];
+    outputProcessors?: readonly Processor[];
     /** Memory configuration. Persists durable facts; auto-recalled on send. */
     memory?: MemorySettings;
     /**
@@ -2146,4 +2219,4 @@ declare class Cron {
     static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
 }
 
-export { type CronStartOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type BudgetUsageEvent as D, type CloudEnv as E, type CloudRepo as F, type GetAgentOptions as G, type ContextBudget as H, type ContextManagerKind as I, type ContextSnapshot as J, type ContextSource as K, type LocalOptions as L, type MemorySettings as M, type ContextSourceStatus as N, type CreateSkillSpec as O, type ProviderRoutingSettings as P, Cron as Q, type CronCreateOptions as R, type SystemPromptResolver as S, type CronGetOptions as T, type CronJob as U, type CronJobStatus as V, type CronListOptions as W, type CronOperationOptions as X, type CronRunOptions as Y, type CronRuntime as Z, type CronSchedulerStatus as _, type AgentDefinition as a, type GoalEvent as a0, type GoalOptions as a1, type GoalResult as a2, type HookName as a3, type InlineSkill as a4, type InvalidateCacheOptions as a5, type MemoryAdapter as a6, type MemoryAdapterCapabilities as a7, type MemoryContext as a8, type MemoryFact as a9, type TelemetrySettings as aA, createSkill as aB, definePlugin as aC, type MemoryProviderHandle as aa, type MemoryProviderInitOptions as ab, type MemoryRevision as ac, type MemoryToolSchema as ad, type MemoryTurnMessage as ae, type PersonalityPreset as af, type PluginContext as ag, type PostAssistantReplyContext as ah, type PreToolCallContext as ai, type PreUserSendContext as aj, type PreUserSendResult as ak, type ProviderCapability as al, type ProviderRoute as am, type RecordSessionSummaryArgs as an, type ResolvedProviderRoute as ao, type RunUntilIterator as ap, type SDKAgentPlugins as aq, type SDKAgentSkills as ar, type SDKArtifact as as, type SDKContextManager as at, type SDKPluginMetadata as au, type SDKProvidersManager as av, type SettingSource as aw, type SystemPromptContext as ax, type SystemPromptMemoryFact as ay, type SystemPromptSkillRef 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 SessionMeta as p, type SessionMetaPatch as q, type MemoryProvider as r, type MemoryId as s, type PreToolCallDecision as t, type SDKProvider as u, type ActiveMemoryPassArgs as v, type ActiveMemoryPassResult as w, type AgentMemory as x, type BudgetCheck as y, type BudgetTotal as z };
+export { type CronSchedulerStatus as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type BudgetUsageEvent as D, type CloudEnv as E, type CloudRepo as F, type GetAgentOptions as G, type ContextBudget as H, type InlineSkill as I, type ContextManagerKind as J, type ContextSnapshot as K, type LocalOptions as L, type MemorySettings as M, type ContextSource as N, type ContextSourceStatus as O, type ProviderRoutingSettings as P, type CreateSkillSpec as Q, Cron as R, type SystemPromptResolver as S, type CronCreateOptions as T, type CronGetOptions as U, type CronJob as V, type CronJobStatus as W, type CronListOptions as X, type CronOperationOptions as Y, type CronRunOptions as Z, type CronRuntime as _, type AgentDefinition as a, type CronStartOptions as a0, type GoalEvent as a1, type GoalOptions as a2, type GoalResult as a3, type HookName as a4, type InvalidateCacheOptions as a5, type MemoryAdapter as a6, type MemoryAdapterCapabilities as a7, type MemoryContext as a8, type MemoryFact as a9, type SystemPromptContext as aA, type SystemPromptMemoryFact as aB, type SystemPromptSkillRef as aC, type TelemetrySettings as aD, createSkill as aE, definePlugin as aF, type MemoryProviderHandle as aa, type MemoryProviderInitOptions as ab, type MemoryRevision as ac, type MemoryToolSchema as ad, type MemoryTurnMessage as ae, type PersonalityPreset as af, type PluginContext as ag, type PostAssistantReplyContext as ah, type PreToolCallContext as ai, type PreUserSendContext as aj, type PreUserSendResult as ak, type ProviderCapability as al, type ProviderRoute as am, type RecordSessionSummaryArgs as an, type ResolvedProviderRoute as ao, type RunUntilIterator as ap, type SDKAgentPlugins as aq, type SDKAgentSkillDetail as ar, type SDKAgentSkills as as, type SDKArtifact as at, type SDKContextManager as au, type SDKPluginMetadata as av, type SDKProvidersManager as aw, type SettingSource as ax, type SkillsResolver as ay, type SkillsResolverContext 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 SessionMeta as p, type SessionMetaPatch as q, type MemoryProvider as r, type MemoryId as s, type PreToolCallDecision as t, type SDKProvider as u, type ActiveMemoryPassArgs as v, type ActiveMemoryPassResult as w, type AgentMemory as x, type BudgetCheck as y, type BudgetTotal as z };

package/dist/{cron-Bd2oRD7A.d.cts → cron-DgEQCJ2i.d.ts}

@@ -1,4 +1,4 @@
-import { C as CustomTool, M as ModelSelection, Z as SDKUserMessage, $ as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, F as RunToCompletionOptions, H as RunToCompletionResult, S as SDKMessage, a6 as StreamToCompletionResult, a as McpServerConfig } from './run-Cr0C6cOM.cjs';
+import { C as CustomTool, M as ModelSelection, a4 as SDKUserMessage, a6 as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, N as RunToCompletionOptions, Q as RunToCompletionResult, S as SDKMessage, ad as StreamToCompletionResult, a as McpServerConfig, P as Processor } from './run-CdWiihyU.js';
 import * as zod from 'zod';
 
 /**
@@ -751,6 +751,12 @@ interface Skill {
 interface InlineSkill extends Skill {
     /** The skill body/instructions (inline skills carry it here instead of a SKILL.md file). */
     instructions: string;
+    /**
+     * SE21 — supporting documents bundled with the skill (filename → content),
+     * mirroring a filesystem skill's `references/` directory. Surfaced to the app
+     * via `agent.skills.get(name)`; not injected into the model prompt.
+     */
+    references?: Record<string, string>;
 }
 /** Spec accepted by {@link createSkill}. */
 interface CreateSkillSpec {
@@ -759,6 +765,8 @@ interface CreateSkillSpec {
     instructions: string;
     category?: string;
     dependencies?: string[];
+    /** SE21 — supporting documents (filename → content), like a filesystem skill's `references/`. */
+    references?: Record<string, string>;
 }
 /**
  * Build an {@link InlineSkill} from a code spec. Fails fast on an empty `name`/`description`
@@ -1187,8 +1195,27 @@ interface SystemPromptSkillRef {
  *
  * @public
  */
+/**
+ * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
+ * {@link SystemPromptSkillRef} (name + description only), this carries the full
+ * `instructions` — read from the SKILL.md for filesystem skills or the inline
+ * `createSkill` body. @public
+ */
+interface SDKAgentSkillDetail {
+    name: string;
+    description: string;
+    instructions: string;
+    /** SE21 — supporting documents bundled with the skill (filename → content), when present. */
+    references?: Record<string, string>;
+}
 interface SDKAgentSkills {
     list(): Promise<ReadonlyArray<SystemPromptSkillRef>>;
+    /**
+     * SE20 — resolve a skill by name INCLUDING its body (`instructions`). Returns
+     * `undefined` when no enabled skill matches. `list()` stays lean (name +
+     * description); full bodies come only through `get`.
+     */
+    get(name: string): Promise<SDKAgentSkillDetail | undefined>;
 }
 /**
  * Public plugin metadata returned by `agent.plugins.list()`. Mirrors the
@@ -1279,6 +1306,36 @@ interface SkillsSettings {
      */
     inline?: InlineSkill[];
 }
+/**
+ * SE22 — context passed to a {@link SkillsResolver}. Mirrors
+ * {@link SystemPromptContext} MINUS `skills`: the resolver runs BEFORE skills
+ * are assembled, so the resolved list does not exist yet.
+ *
+ * @public
+ */
+interface SkillsResolverContext {
+    agentId: string;
+    /** Workspace cwd. `string | undefined` mirrors {@link SystemPromptContext}; a local agent always passes a concrete path. */
+    cwd: string | undefined;
+    model: ModelSelection | undefined;
+    userMessage: string;
+    /** Recalled durable facts when memory is enabled. */
+    memory: ReadonlyArray<SystemPromptMemoryFact>;
+}
+/**
+ * SE22 — a resolver that produces {@link SkillsSettings} per run from runtime
+ * context (e.g. the user's role). Mirrors the {@link SystemPromptResolver}
+ * pattern: evaluated per `send()` BEFORE skill assembly, so a cached
+ * `getOrCreate` agent re-resolves on every run.
+ *
+ * The SDK imposes NO timeout — wrap your own `Promise.race` for slow sources. 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
+ * {@link SkillsSettings} object before `Agent.create()`.
+ *
+ * @public
+ */
+type SkillsResolver = (ctx: SkillsResolverContext) => SkillsSettings | Promise<SkillsSettings>;
 /**
  * Memory configuration accepted by `Agent.create()` via {@link AgentOptions.memory}.
  *
@@ -1425,8 +1482,24 @@ interface AgentOptions {
      * The two forms are mutually exclusive — pass one or the other.
      */
     plugins?: PluginsSettings | readonly Plugin[];
-    /** Skills configuration. See `agent.skills`. */
-    skills?: SkillsSettings;
+    /**
+     * Skills configuration. Either a static {@link SkillsSettings} object or —
+     * SE22 — a {@link SkillsResolver} evaluated per `send()` to pick skills from
+     * runtime context (e.g. user role). A cached agent re-resolves each run. The
+     * agent-scoped `agent.skills` handle reflects the STATIC/base config; the
+     * resolver drives the per-send `<skills>` block.
+     */
+    skills?: SkillsSettings | SkillsResolver;
+    /**
+     * SE24 — guardrail processors. `inputProcessors` run in order before the LLM
+     * (normalize / validate / block / rewrite the user message); `outputProcessors`
+     * run on the model's final text before it reaches the caller (redact / block).
+     * A processor that `abort()`s stops the run with a {@link RunResult.tripwire}
+     * (+ a `tripwire` run-event). Empty/absent ⇒ unchanged behavior. See
+     * {@link Processor}.
+     */
+    inputProcessors?: readonly Processor[];
+    outputProcessors?: readonly Processor[];
     /** Memory configuration. Persists durable facts; auto-recalled on send. */
     memory?: MemorySettings;
     /**
@@ -2146,4 +2219,4 @@ declare class Cron {
     static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
 }
 
-export { type CronStartOptions as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type BudgetUsageEvent as D, type CloudEnv as E, type CloudRepo as F, type GetAgentOptions as G, type ContextBudget as H, type ContextManagerKind as I, type ContextSnapshot as J, type ContextSource as K, type LocalOptions as L, type MemorySettings as M, type ContextSourceStatus as N, type CreateSkillSpec as O, type ProviderRoutingSettings as P, Cron as Q, type CronCreateOptions as R, type SystemPromptResolver as S, type CronGetOptions as T, type CronJob as U, type CronJobStatus as V, type CronListOptions as W, type CronOperationOptions as X, type CronRunOptions as Y, type CronRuntime as Z, type CronSchedulerStatus as _, type AgentDefinition as a, type GoalEvent as a0, type GoalOptions as a1, type GoalResult as a2, type HookName as a3, type InlineSkill as a4, type InvalidateCacheOptions as a5, type MemoryAdapter as a6, type MemoryAdapterCapabilities as a7, type MemoryContext as a8, type MemoryFact as a9, type TelemetrySettings as aA, createSkill as aB, definePlugin as aC, type MemoryProviderHandle as aa, type MemoryProviderInitOptions as ab, type MemoryRevision as ac, type MemoryToolSchema as ad, type MemoryTurnMessage as ae, type PersonalityPreset as af, type PluginContext as ag, type PostAssistantReplyContext as ah, type PreToolCallContext as ai, type PreUserSendContext as aj, type PreUserSendResult as ak, type ProviderCapability as al, type ProviderRoute as am, type RecordSessionSummaryArgs as an, type ResolvedProviderRoute as ao, type RunUntilIterator as ap, type SDKAgentPlugins as aq, type SDKAgentSkills as ar, type SDKArtifact as as, type SDKContextManager as at, type SDKPluginMetadata as au, type SDKProvidersManager as av, type SettingSource as aw, type SystemPromptContext as ax, type SystemPromptMemoryFact as ay, type SystemPromptSkillRef 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 SessionMeta as p, type SessionMetaPatch as q, type MemoryProvider as r, type MemoryId as s, type PreToolCallDecision as t, type SDKProvider as u, type ActiveMemoryPassArgs as v, type ActiveMemoryPassResult as w, type AgentMemory as x, type BudgetCheck as y, type BudgetTotal as z };
+export { type CronSchedulerStatus as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type BudgetUsageEvent as D, type CloudEnv as E, type CloudRepo as F, type GetAgentOptions as G, type ContextBudget as H, type InlineSkill as I, type ContextManagerKind as J, type ContextSnapshot as K, type LocalOptions as L, type MemorySettings as M, type ContextSource as N, type ContextSourceStatus as O, type ProviderRoutingSettings as P, type CreateSkillSpec as Q, Cron as R, type SystemPromptResolver as S, type CronCreateOptions as T, type CronGetOptions as U, type CronJob as V, type CronJobStatus as W, type CronListOptions as X, type CronOperationOptions as Y, type CronRunOptions as Z, type CronRuntime as _, type AgentDefinition as a, type CronStartOptions as a0, type GoalEvent as a1, type GoalOptions as a2, type GoalResult as a3, type HookName as a4, type InvalidateCacheOptions as a5, type MemoryAdapter as a6, type MemoryAdapterCapabilities as a7, type MemoryContext as a8, type MemoryFact as a9, type SystemPromptContext as aA, type SystemPromptMemoryFact as aB, type SystemPromptSkillRef as aC, type TelemetrySettings as aD, createSkill as aE, definePlugin as aF, type MemoryProviderHandle as aa, type MemoryProviderInitOptions as ab, type MemoryRevision as ac, type MemoryToolSchema as ad, type MemoryTurnMessage as ae, type PersonalityPreset as af, type PluginContext as ag, type PostAssistantReplyContext as ah, type PreToolCallContext as ai, type PreUserSendContext as aj, type PreUserSendResult as ak, type ProviderCapability as al, type ProviderRoute as am, type RecordSessionSummaryArgs as an, type ResolvedProviderRoute as ao, type RunUntilIterator as ap, type SDKAgentPlugins as aq, type SDKAgentSkillDetail as ar, type SDKAgentSkills as as, type SDKArtifact as at, type SDKContextManager as au, type SDKPluginMetadata as av, type SDKProvidersManager as aw, type SettingSource as ax, type SkillsResolver as ay, type SkillsResolverContext 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 SessionMeta as p, type SessionMetaPatch as q, type MemoryProvider as r, type MemoryId as s, type PreToolCallDecision as t, type SDKProvider as u, type ActiveMemoryPassArgs as v, type ActiveMemoryPassResult as w, type AgentMemory as x, type BudgetCheck as y, type BudgetTotal as z };