@kuralle-agents/core 0.13.0 → 0.14.0

package/dist/runtime/controlFlowSignal.js

@@ -0,0 +1,29 @@
+import { SuspendError } from './durable/RunStore.js';
+import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
+/**
+ * The run is not finished: stop the turn, keep the journal, resume when a signal arrives.
+ * It unwinds the stack like an error but is not a failure, so it must never be reported to
+ * the model as a tool error, shown to the user as an error, or journaled as one.
+ *
+ * Only `SuspendError` qualifies. An approval *denial* is deliberately not a signal — see
+ * `isApprovalDenial`.
+ */
+export function isControlFlowSignal(error) {
+    return error instanceof SuspendError;
+}
+/**
+ * A human answered "no". Neither a failure nor a suspend — the opposite of a suspend, in
+ * fact: a suspend defers the decision, a denial resolves it.
+ *
+ * Two rules follow, and they differ by who is driving the call:
+ *
+ * - It must never be degraded into "something went wrong on my side". Nothing went wrong;
+ *   saying so would be a lie to the user.
+ * - On the **model** path it becomes a tool result, because there is no author code to
+ *   catch it and the agent needs to be able to tell the user the request was declined.
+ *   On the **flow** path it keeps propagating, because an `action` node's author chose to
+ *   call the tool and can catch it or branch on `ctx.approve()` instead.
+ */
+export function isApprovalDenial(error) {
+    return error instanceof ToolApprovalDeniedError;
+}

package/dist/runtime/ctx.d.ts

@@ -1,7 +1,7 @@
 import type { LanguageModel } from 'ai';
 import type { Session } from '../types/session.js';
-import type { EffectToolExecutor, HookRunner, MemoryService, AutoRetrieveProvider, RunContext } from '../types/run-context.js';
-import type { HarnessStreamPart } from '../types/stream.js';
+import type { EffectToolExecutor, MemoryService, AutoRetrieveProvider, RunContext } from '../types/run-context.js';
+import type { StreamPart } from '../types/stream.js';
 import type { RefinementCapability } from '../capabilities/RefinementCapability.js';
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { InputProcessor, OutputProcessor } from '../types/processors.js';
@@ -19,7 +19,6 @@ export interface CtxDeps {
     runStore: RunStore;
     steps: StepRecord[];
     toolExecutor: EffectToolExecutor;
-    hookRunner?: HookRunner;
     model: LanguageModel;
     controlModel?: LanguageModel;
     outOfBandControl?: boolean;
@@ -34,7 +33,7 @@ export interface CtxDeps {
     bargeIn?: AbortSignal;
     abortSignal?: AbortSignal;
     clock?: EffectClock;
-    emit?: (part: HarnessStreamPart) => void;
+    emit?: (part: StreamPart) => void;
 }
 export declare function createRunContext(deps: CtxDeps): Promise<RunContext>;
 export {};

package/dist/runtime/ctx.js

@@ -14,6 +14,22 @@ function makeCtx(deps) {
     const emit = deps.emit ?? (() => { });
     // Mutable holder: handoff reassigns runCtx.toolExecutor; ctx.tool must see the swap.
     const toolExecutorHolder = { executor: deps.toolExecutor };
+    let pendingAppendTail = Promise.resolve();
+    const serializePendingAppend = (operation) => {
+        const previous = pendingAppendTail;
+        let release;
+        pendingAppendTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        return previous.then(async () => {
+            try {
+                return await operation();
+            }
+            finally {
+                release();
+            }
+        });
+    };
     const consumeCallsite = () => {
         const site = String(effectOrdinal);
         effectOrdinal += 1;
@@ -85,9 +101,28 @@ function makeCtx(deps) {
             }
         }
         const isRetry = hit?.status === 'running';
-        const stepIndex = options?.index ?? hit?.index ?? steps.length;
+        const stepIndex = options?.index ?? hit?.index;
         if (!isRetry) {
-            await appendPendingStep(key, kind, name, stepIndex);
+            const append = async () => {
+                let index = stepIndex;
+                if (index === undefined) {
+                    if (deps.runStore.reserveSteps) {
+                        index = (await deps.runStore.reserveSteps(deps.runState.runId, 1))[0];
+                    }
+                    else {
+                        // ctx.tool owns ordinal assignment: use the store's atomic reservation when available,
+                        // and serialize legacy stores that do not expose reserveSteps within this context.
+                        index = steps.length;
+                    }
+                }
+                await appendPendingStep(key, kind, name, index);
+            };
+            if (stepIndex === undefined && !deps.runStore.reserveSteps) {
+                await serializePendingAppend(append);
+            }
+            else {
+                await append();
+            }
         }
         let result;
         try {
@@ -131,7 +166,7 @@ function makeCtx(deps) {
         deps.runState.status = 'paused';
         deps.runState.updatedAt = Date.now();
         await deps.runStore.putRunState(deps.runState);
-        emit({ type: 'paused', waitingFor: signalName });
+        emit({ channel: 'internal', type: 'paused', payload: { waitingFor: signalName } });
         throw new SuspendError(signalName);
     };
     const pauseEffect = async (signalName, meta) => {
@@ -160,7 +195,6 @@ function makeCtx(deps) {
         set toolExecutor(executor) {
             toolExecutorHolder.executor = executor;
         },
-        hookRunner: deps.hookRunner ?? {},
         model: deps.model,
         controlModel: deps.controlModel ?? deps.model,
         outOfBandControl: deps.outOfBandControl ?? false,
@@ -223,7 +257,7 @@ function makeCtx(deps) {
                 toolCtx: options?.toolCtx,
             });
             if (def?.replay === false) {
-                const auditKey = `${key}:${steps.length}`;
+                const auditKey = `${key}:${steps.length}:${options?.index ?? callsite}`;
                 return replayOrExecute(auditKey, 'tool', name, executeTool, { index: options?.index });
             }
             return replayOrExecute(key, 'tool', name, executeTool, { index: options?.index });

package/dist/runtime/durable/RunStore.js

@@ -3,7 +3,7 @@ export class LogConflictError extends Error {
     expectedIndex;
     actualIndex;
     constructor(runId, expectedIndex, actualIndex) {
-        super(`Log conflict for run ${runId}: expected append at index ${expectedIndex}, current length is ${actualIndex}`);
+        super(`Log conflict for run ${runId}: expected append at index ${expectedIndex}, current length is ${actualIndex}. For parallel durable effects, use ctx.tool directly or reserve callsites with ctx.reserveCallsites(count) before supplying explicit indices.`);
         this.name = 'LogConflictError';
         this.runId = runId;
         this.expectedIndex = expectedIndex;

package/dist/runtime/grounding/gather.d.ts

@@ -1,4 +1,4 @@
-import type { SourceRef } from '../../types/voice.js';
+import type { SourceRef } from '../../types/knowledge.js';
 import type { GatherScope, RunContext } from '../../types/run-context.js';
 export type { GatherScope } from '../../types/run-context.js';
 export interface GatherResult {

package/dist/runtime/grounding/inMemoryKnowledge.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeProviderConfig, KnowledgeRetrieverAdapter } from '../../types/voice.js';
+import type { KnowledgeProviderConfig, KnowledgeRetrieverAdapter } from '../../types/knowledge.js';
 export interface InMemoryKnowledgeDocument {
     id?: string;
     text: string;

package/dist/runtime/grounding/knowledge.d.ts

@@ -1,7 +1,7 @@
 import type { AgentConfig } from '../../types/agentConfig.js';
 import type { AutoRetrieveProvider } from '../../types/run-context.js';
 import type { AnyTool } from '../../types/effectTool.js';
-import type { KnowledgeProviderConfig } from '../../types/voice.js';
+import type { KnowledgeProviderConfig } from '../../types/knowledge.js';
 import { KnowledgeProvider } from '../KnowledgeProvider.js';
 export declare function buildKnowledgeProvider(config: KnowledgeProviderConfig): KnowledgeProvider;
 export declare function buildAutoRetrieveProvider(provider: KnowledgeProvider, agent: AgentConfig): AutoRetrieveProvider | undefined;

package/dist/runtime/hostLoop.js

@@ -36,7 +36,7 @@ export async function hostLoop(options) {
             return { kind: 'paused' };
         }
         if (error instanceof LimitsExceededError) {
-            ctx.emit({ type: 'error', error: error.message });
+            ctx.emit({ channel: 'client', type: 'error', payload: { error: error.message } });
             return { kind: 'ended', reason: error.message };
         }
         throw error;
@@ -160,7 +160,11 @@ function guardVerdictToTelemetryVerdict(verdict) {
     return 'keep';
 }
 function emitHostGuardTelemetry(ctx, data) {
-    ctx.emit({ type: 'custom', name: 'host-guard', data });
+    ctx.emit({
+        channel: 'internal',
+        type: 'custom',
+        payload: { name: 'host-guard', data },
+    });
 }
 function guardVerdictToControl(verdict, agent) {
     const selection = verdictToSelection(verdict, agent);
@@ -174,7 +178,11 @@ function guardVerdictToControl(verdict, agent) {
 }
 async function executeHostControl(agent, run, driver, ctx, control) {
     if (!control) {
-        ctx.emit({ type: 'error', error: 'No valid host control target resolved' });
+        ctx.emit({
+            channel: 'client',
+            type: 'error',
+            payload: { error: 'No valid host control target resolved' },
+        });
         return { kind: 'ended', reason: 'dispatch_failed' };
     }
     if (control.type === 'enterFlow') {
@@ -182,18 +190,30 @@ async function executeHostControl(agent, run, driver, ctx, control) {
         if (flow) {
             return await runActiveFlow(flow, run, driver, ctx, agent);
         }
-        ctx.emit({ type: 'error', error: `Flow not found: ${control.flowName}` });
+        ctx.emit({
+            channel: 'client',
+            type: 'error',
+            payload: { error: `Flow not found: ${control.flowName}` },
+        });
         return { kind: 'ended', reason: 'flow_not_found' };
     }
     if (control.type === 'handoff') {
-        ctx.emit({ type: 'handoff', targetAgent: control.target, reason: control.reason });
+        ctx.emit({
+            channel: 'internal',
+            type: 'handoff',
+            payload: { targetAgent: control.target, reason: control.reason },
+        });
         return { kind: 'handoff', to: control.target, reason: control.reason };
     }
     if (control.type === 'end') {
         return { kind: 'ended', reason: control.reason };
     }
     if (control.type === 'escalate') {
-        ctx.emit({ type: 'handoff', targetAgent: 'human', reason: control.reason });
+        // No handoff part is emitted here. Runtime owns it: it emits one for any
+        // target in `terminalHandoffTargets` (default ['human']) on this exact
+        // return value. Emitting here too produced two handoff spans per escalation
+        // and a meaningless `human -> human` self-edge, which then mis-attributed
+        // every later span in the turn to `human`.
         return { kind: 'handoff', to: 'human', reason: control.reason, category: control.category };
     }
     if (control.type === 'recover') {

package/dist/runtime/index.d.ts

@@ -3,8 +3,7 @@ export type { RuntimeLike } from './RuntimeLike.js';
 export { TraceRecorder, runOnce, type TraceRecorderOptions } from './TraceRecorder.js';
 export type { AgentSpan, AgentTrace, SpanKind } from '../types/trace.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
-export { TextDriver, VoiceDriver } from './channels/index.js';
-export type { VoiceDriverConfig } from './channels/index.js';
+export { TextDriver } from './channels/index.js';
 export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
 export { userInputToText, mergeUserInputContents, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './userInput.js';
 export { isAbortSignal, type InterruptionEvent, type AbortOptions, type CancellationReason, } from '../types/index.js';

package/dist/runtime/index.js

@@ -1,7 +1,7 @@
 export { createRuntime, Runtime, } from './Runtime.js';
 export { TraceRecorder, runOnce } from './TraceRecorder.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
-export { TextDriver, VoiceDriver } from './channels/index.js';
+export { TextDriver } from './channels/index.js';
 // Pending-input buffer helpers — required by custom ChannelDriver authors to
 // implement awaitUser the same FIFO-aware way the built-in drivers do (the
 // buffer is an ordered queue since 0.3.13/H3, not a single slot).

package/dist/runtime/outcomeMarking.d.ts

@@ -1,9 +1,9 @@
 import type { Session } from '../types/session.js';
 import type { SessionStore } from '../session/SessionStore.js';
 import type { ConversationOutcome, ConversationOutcomeMarkedBy, ConversationOutcomeRecord } from '../outcomes/types.js';
-import type { HarnessStreamPart } from '../types/stream.js';
+import type { StreamPart } from '../types/stream.js';
 export declare function isTerminalOutcome(outcome: ConversationOutcome): boolean;
 export declare function markSessionOutcome(sessionStore: SessionStore, session: Session, outcome: ConversationOutcome, opts?: {
     reason?: string;
     markedBy?: ConversationOutcomeMarkedBy;
-}, emit?: (part: HarnessStreamPart) => void): Promise<ConversationOutcomeRecord>;
+}, emit?: (part: StreamPart) => void): Promise<ConversationOutcomeRecord>;

package/dist/runtime/outcomeMarking.js

@@ -22,8 +22,9 @@ export async function markSessionOutcome(sessionStore, session, outcome, opts =
     await sessionStore.save(session);
     if (emit) {
         emit({
+            channel: 'client',
             type: 'conversation-outcome',
-            outcome: record.outcome,
+            payload: { outcome: record.outcome },
         });
     }
     return record;

package/dist/runtime/policies/agentTurn.d.ts

@@ -1,6 +1,6 @@
 import type { TurnControl } from '../../types/channel.js';
 import type { ToolCallRecord } from '../../types/session.js';
-import type { SourceRef } from '../../types/voice.js';
+import type { SourceRef } from '../../types/knowledge.js';
 import type { RunContext } from '../../types/run-context.js';
 export interface PreTurnResult {
     proceed: boolean;

package/dist/runtime/runHookSafely.d.ts

@@ -0,0 +1,3 @@
+type HookCallback = () => void | Promise<void>;
+export declare function runHookSafely(name: string, callback: HookCallback | undefined): Promise<void>;
+export {};

package/dist/runtime/runHookSafely.js

@@ -0,0 +1,19 @@
+export function runHookSafely(name, callback) {
+    if (!callback)
+        return Promise.resolve();
+    try {
+        return Promise.resolve(callback()).catch((error) => reportHookError(name, error));
+    }
+    catch (error) {
+        reportHookError(name, error);
+        return Promise.resolve();
+    }
+}
+function reportHookError(name, error) {
+    try {
+        console.error(`Hook ${name} failed`, error);
+    }
+    catch {
+        // Hook failure reporting must not affect run correctness.
+    }
+}

package/dist/scheduler/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { Tool } from '../types/effectTool.js';
-import type { HarnessStreamPart, TurnHandle } from '../types/stream.js';
+import type { StreamPart, TurnHandle } from '../types/stream.js';
 /**
  * Deferred-work scheduling for proactive (agent-initiated) turns.
  *
@@ -51,7 +51,7 @@ export interface WakeDelivery {
     reason: string;
     payload?: Record<string, unknown>;
     /** Full stream of the wake turn (text, tool events, interactive parts…). */
-    parts: HarnessStreamPart[];
+    parts: StreamPart[];
     /** Concatenated assistant text of the wake turn. */
     text: string;
 }

package/dist/scheduler/index.js

@@ -60,7 +60,7 @@ export function createWakeJobRunner(runtime, opts) {
             for await (const part of handle.events) {
                 parts.push(part);
                 if (part.type === 'text-delta') {
-                    text += part.delta;
+                    text += part.payload.delta;
                 }
             }
             const result = await handle;

package/dist/services/TracingService.js

@@ -11,9 +11,8 @@ export class TracingService {
     }
     startSpan(name, attributes, parentSpanId) {
         if (!this.config) {
-            // Fallback or throw? Helpers threw.
-            // We will throw to maintain behavior, but maybe warn in future.
-            throw new Error('Tracing not initialized. Call initTracing() first.');
+            throw new Error('TracingService not initialized. Construct it with a config — ' +
+                'new TracingService(config) — or call .init(config) before startSpan().');
         }
         const span = {
             id: this.generateSpanId(),

package/dist/skills/collectSkills.d.ts

@@ -1,5 +1,6 @@
 import type { AnyTool } from '../types/effectTool.js';
-import type { SkillLike, SkillSource, SkillStoreLike } from '../types/skills.js';
+import type { FileSystem } from '../types/filesystem.js';
+import type { SkillEntry, SkillLike, SkillSource, SkillStoreLike } from '../types/skills.js';
 export interface SkillWireAgent {
     skills?: SkillSource;
     tools?: Record<string, AnyTool>;
@@ -8,10 +9,17 @@ export interface SkillWireAgent {
         name: string;
     }>;
 }
-export declare function isSkillStore(value: SkillSource): value is SkillStoreLike;
+export declare function isSkillStore(value: SkillEntry | SkillSource): value is SkillStoreLike;
 export declare function collectRegisteredNames(agent: SkillWireAgent): Set<string>;
 export declare function validateSkillAllowedTools(skills: SkillLike[], registered: Set<string>): void;
-export declare function prepareSkillStore(source: SkillSource): Promise<{
+/**
+ * Turns whatever the author wrote in `AgentConfig.skills` into one store.
+ *
+ * `fs` is the agent's workspace filesystem, needed only to resolve `string` entries. A path
+ * without a workspace is an authoring mistake, so it throws rather than silently yielding no
+ * skills — a missing skill is invisible at runtime and looks like the model ignoring it.
+ */
+export declare function prepareSkillStore(source: SkillSource, fs?: FileSystem): Promise<{
     store: SkillStoreLike;
     skills: SkillLike[];
 }>;

package/dist/skills/collectSkills.js

@@ -1,4 +1,6 @@
 import { InlineSkillStore } from './inlineSkillStore.js';
+import { CompositeSkillStore } from './compositeSkillStore.js';
+import { fsSkillStore } from './fsSkillStore.js';
 export function isSkillStore(value) {
     return (typeof value === 'object' &&
         value !== null &&
@@ -7,9 +9,6 @@ export function isSkillStore(value) {
         typeof value.list === 'function');
 }
 async function collectSkillsFromSource(source) {
-    if (!isSkillStore(source)) {
-        return Array.isArray(source) ? source : [source];
-    }
     if (typeof source.getAllSkills === 'function') {
         const all = source.getAllSkills();
         return Array.isArray(all) ? all : await all;
@@ -47,10 +46,54 @@ export function validateSkillAllowedTools(skills, registered) {
         }
     }
 }
-export async function prepareSkillStore(source) {
-    if (isSkillStore(source)) {
-        return { store: source, skills: await collectSkillsFromSource(source) };
+/**
+ * Turns whatever the author wrote in `AgentConfig.skills` into one store.
+ *
+ * `fs` is the agent's workspace filesystem, needed only to resolve `string` entries. A path
+ * without a workspace is an authoring mistake, so it throws rather than silently yielding no
+ * skills — a missing skill is invisible at runtime and looks like the model ignoring it.
+ */
+export async function prepareSkillStore(source, fs) {
+    const entries = Array.isArray(source)
+        ? [...source]
+        : [source];
+    // A lone store stays itself: wrapping one store in a composite would add a layer with
+    // nothing to compose, and lose any extra capability the store exposes.
+    if (entries.length === 1 && isSkillStore(entries[0])) {
+        const only = entries[0];
+        return { store: only, skills: await collectSkillsFromSource(only) };
+    }
+    const stores = [];
+    let inline = [];
+    const flushInline = () => {
+        if (inline.length > 0) {
+            stores.push(new InlineSkillStore(inline));
+            inline = [];
+        }
+    };
+    for (const entry of entries) {
+        if (typeof entry === 'string') {
+            if (!fs) {
+                throw new Error(`[skills] "${entry}" is a workspace path, but this agent has no \`workspace\` filesystem. ` +
+                    'Set `workspace` on the agent, or pass skills inline with defineSkill().');
+            }
+            flushInline();
+            stores.push(fsSkillStore(fs, [entry]));
+            continue;
+        }
+        if (isSkillStore(entry)) {
+            flushInline();
+            stores.push(entry);
+            continue;
+        }
+        // Consecutive inline skills share one store so ordering within a run is preserved.
+        inline.push(entry);
+    }
+    flushInline();
+    if (stores.length === 1) {
+        const only = stores[0];
+        return { store: only, skills: await collectSkillsFromSource(only) };
     }
-    const skills = Array.isArray(source) ? source : [source];
-    return { store: new InlineSkillStore(skills), skills };
+    const store = new CompositeSkillStore(stores);
+    return { store, skills: await collectSkillsFromSource(store) };
 }

package/dist/skills/compositeSkillStore.d.ts

@@ -0,0 +1,26 @@
+import type { SkillMeta, SkillStoreLike } from '../types/skills.js';
+/**
+ * Presents several skill stores as one, with **later stores winning** a name collision.
+ *
+ * Delegates rather than flattening on purpose: flattening would force every body and
+ * resource to load up front, which is exactly what progressive disclosure exists to avoid.
+ * Only `list()` (Level 1 — names and descriptions) is eager; bodies and resources stay
+ * behind their own calls.
+ */
+export declare class CompositeSkillStore implements SkillStoreLike {
+    private readonly stores;
+    /** Name → the store that owns it. Built on first `list()`, reused after. */
+    private owners?;
+    /** @param stores In precedence order, lowest first. */
+    constructor(stores: readonly SkillStoreLike[]);
+    list(): Promise<SkillMeta[]>;
+    loadBody(name: string): Promise<string>;
+    loadResource(name: string, path: string): Promise<string | Uint8Array>;
+    loadAllSkills(): Promise<{
+        name: string;
+        description: string;
+        body: string;
+    }[]>;
+    private ownerOf;
+    private resolveOwners;
+}

package/dist/skills/compositeSkillStore.js

@@ -0,0 +1,54 @@
+/**
+ * Presents several skill stores as one, with **later stores winning** a name collision.
+ *
+ * Delegates rather than flattening on purpose: flattening would force every body and
+ * resource to load up front, which is exactly what progressive disclosure exists to avoid.
+ * Only `list()` (Level 1 — names and descriptions) is eager; bodies and resources stay
+ * behind their own calls.
+ */
+export class CompositeSkillStore {
+    stores;
+    /** Name → the store that owns it. Built on first `list()`, reused after. */
+    owners;
+    /** @param stores In precedence order, lowest first. */
+    constructor(stores) {
+        this.stores = stores;
+    }
+    async list() {
+        const merged = new Map();
+        const owners = new Map();
+        for (const store of this.stores) {
+            for (const meta of await store.list()) {
+                merged.set(meta.name, meta);
+                owners.set(meta.name, store);
+            }
+        }
+        this.owners = owners;
+        return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async loadBody(name) {
+        return (await this.ownerOf(name)).loadBody(name);
+    }
+    async loadResource(name, path) {
+        return (await this.ownerOf(name)).loadResource(name, path);
+    }
+    async loadAllSkills() {
+        const owners = await this.resolveOwners();
+        const out = [];
+        for (const [name, store] of owners) {
+            out.push({ name, description: '', body: await store.loadBody(name) });
+        }
+        return out;
+    }
+    async ownerOf(name) {
+        const owner = (await this.resolveOwners()).get(name);
+        if (!owner)
+            throw new Error(`[skills] Skill "${name}" not found.`);
+        return owner;
+    }
+    async resolveOwners() {
+        if (!this.owners)
+            await this.list();
+        return this.owners;
+    }
+}

package/dist/skills/defineSkill.d.ts

@@ -0,0 +1,21 @@
+import type { SkillLike } from '../types/skills.js';
+export interface DefineSkillConfig {
+    /** Lowercase, hyphen-separated, ≤64 chars — the Agent Skills naming rule. */
+    name: string;
+    /** When the model should reach for this skill. Disclosed up front, so keep it specific. ≤1024 chars. */
+    description: string;
+    /** The skill body — Level 2, loaded only when the model calls `load_skill`. */
+    instructions: string;
+    /** Level 3: fetched individually via `read_skill_resource`, never loaded up front. */
+    resources?: Record<string, string | Uint8Array>;
+    /** Restricts this skill to a subset of the agent's tools. Unknown names fail at wiring time. */
+    allowedTools?: string[];
+}
+/**
+ * Authors a skill inline, with no filesystem involved.
+ *
+ * Validated against the same rules as a `SKILL.md` on disk — an inline skill that would be
+ * rejected as a file is rejected here too, so moving one to `agents/<id>/skills/` later
+ * cannot start failing.
+ */
+export declare function defineSkill(config: DefineSkillConfig): SkillLike;

package/dist/skills/defineSkill.js

@@ -0,0 +1,26 @@
+import { validateSkillDescription, validateSkillName } from './parseSkillFrontmatter.js';
+/**
+ * Authors a skill inline, with no filesystem involved.
+ *
+ * Validated against the same rules as a `SKILL.md` on disk — an inline skill that would be
+ * rejected as a file is rejected here too, so moving one to `agents/<id>/skills/` later
+ * cannot start failing.
+ */
+export function defineSkill(config) {
+    const name = config.name?.trim();
+    const description = config.description?.trim();
+    if (!name)
+        throw new Error('[skills] defineSkill requires a non-empty name.');
+    if (!description) {
+        throw new Error(`[skills] Skill "${name}" requires a non-empty description.`);
+    }
+    validateSkillName(name, name);
+    validateSkillDescription(description, name);
+    return {
+        name,
+        description,
+        body: config.instructions,
+        resources: config.resources,
+        allowedTools: config.allowedTools,
+    };
+}

package/dist/skills/fsSkillStore.d.ts

@@ -0,0 +1,3 @@
+import type { FileSystem } from '../types/filesystem.js';
+import type { SkillStoreLike } from '../types/skills.js';
+export declare function fsSkillStore(fs: FileSystem, orderedRoots?: readonly string[]): SkillStoreLike;