@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/structs/kits/presentation/events.d.ts

@@ -1,23 +1,47 @@
-export type AgentOutputEvent = {
+/**
+ * Presentation event contract for the Presentation Kit.
+ *
+ * Place in the package: an optional App-side output protocol between a validated reply and the
+ * transport that displays it. Events describe already-validated text; they never represent
+ * upstream model generation or an unvalidated draft.
+ *
+ * Exports: `AgentOutputEvent`, `ReplyBubbleInput`, `ReplyDeliveryOptions`.
+ */
+/** One output event of a delivered reply. */
+export type AgentOutputEvent = 
+/** Visible text chunk to append. */
+{
     type: 'text';
     text: string;
-} | {
+}
+/** Preview of the bubbles to be delivered, emitted before any text. */
+ | {
     type: 'preview';
     bubbles: string[];
-} | {
+}
+/** Replaces everything delivered so far with `text`. */
+ | {
     type: 'replace';
     text: string;
-} | {
+}
+/** Separates the next text chunk into a new bubble. */
+ | {
     type: 'bubble';
 };
+/** Reply pieces accepted by the bubble helpers; non-string entries are ignored. */
 export interface ReplyBubbleInput {
+    /** Primary reply text. */
     text?: unknown;
+    /** Additional bubbles appended after `text`, when the value is an array. */
     bubbles?: unknown;
 }
 /** Host-controlled delivery of already validated text; not upstream model generation. */
 export interface ReplyDeliveryOptions {
+    /** Characters per emitted text event; defaults to 240 and must be a positive integer. */
     chunkSize?: number;
+    /** Delay between chunks in milliseconds; defaults to 0. */
     intervalMs?: number;
+    /** Delay between bubbles in milliseconds; defaults to 0. */
     bubblePauseMs?: number;
     /** Upper bound on intentional pacing time; backpressure and network time are independent. */
     maxDurationMs?: number;

package/dist/esm/structs/kits/presentation/outputs.d.ts

@@ -1,45 +1,82 @@
+/**
+ * Structured output contract for the Presentation Kit.
+ *
+ * Place in the package: an optional App-side catalog that turns a generated record into a typed
+ * output. Ownership decides where each field value comes from; the catalog validates references
+ * and renders the model-visible schema, while the meaning of every output stays with the App.
+ *
+ * Exports: `OutputField`, `OutputDefinition`, `OutputProvider`, `OutputIssue`,
+ * `OutputComposeInput`, `OutputResult`, `OutputCatalogOptions`.
+ */
 import type { SchemaAdapter, OperationContext, Issue } from '../../common.js';
+/** One field of an output definition. */
 export interface OutputField {
+    /** Field id, used as the property name and as a master-template slot name. */
     readonly id: string;
+    /**
+     * Where the value comes from: `generated` (model writes it), `bound` (provider resolves it),
+     * `constant` (fixed `constantValue`) or `semantic` (model picks one of `semanticKeys`).
+     */
     readonly owner: 'generated' | 'bound' | 'constant' | 'semantic';
+    /** Whether the model must provide the field; defaults to true. */
     readonly required?: boolean;
-    /** Defaults to a string parser when omitted. */
+    /** Value parser and schema. Defaults to a string parser when omitted. */
     readonly valueSchema?: SchemaAdapter<unknown>;
+    /** Provider that resolves `bound` and `semantic` fields; required for those owners. */
     readonly providerId?: string;
+    /** Fixed value for `constant` fields; snapshotted at registration. */
     readonly constantValue?: unknown;
+    /** Allowlist for `semantic` fields; must be non-empty and unique. */
     readonly semanticKeys?: readonly string[];
 }
+/** One output shape. */
 export interface OutputDefinition {
+    /** Output id; duplicate ids are rejected. */
     readonly id: string;
+    /** Shape family. `text` holds one required field; `group` holds program-assigned items. */
     readonly kind: 'text' | 'master' | 'record' | 'group';
+    /** Fields of `text`, `master` and `record` outputs; forbidden for groups. */
     readonly fields?: readonly OutputField[];
+    /** Master template for `master` outputs; its slots must match the field ids exactly. */
     readonly master?: string;
+    /** Output ids a group may contain; required and unique for groups. */
     readonly allowedOutputIds?: readonly string[];
+    /** Maximum group members; required for groups and at least 1. */
     readonly maxItems?: number;
 }
+/** App-owned value provider for `bound` and `semantic` fields. */
 export interface OutputProvider<App> {
     readonly id: string;
+    /** Produces the value; `key` carries the selected semantic key, when there is one. */
     resolve(request: {
         readonly key?: string;
     }, context: OperationContext<App>): unknown;
 }
+/** Output problem with a guaranteed field path. */
 export interface OutputIssue extends Issue {
     readonly path: readonly (string | number)[];
 }
+/** Input for composing one output: model values plus program-assigned group members. */
 export interface OutputComposeInput {
+    /** Values already produced for this output's fields, keyed by field id. */
     readonly generated?: Readonly<Record<string, unknown>>;
+    /** Group members supplied by the program, in order. */
     readonly items?: readonly {
         readonly id: string;
         readonly outputId: string;
         readonly input: OutputComposeInput;
     }[];
 }
+/** Composed output value. */
 export interface OutputResult {
     readonly outputId: string;
     readonly kind: OutputDefinition['kind'];
     readonly value: unknown;
 }
+/** Catalog construction options. */
 export interface OutputCatalogOptions<App = unknown> {
+    /** Providers referenced by `bound` and `semantic` fields. */
     readonly providers?: readonly OutputProvider<App>[];
+    /** Observer invoked with every composed result. */
     readonly observe?: (result: OutputResult) => void | Promise<void>;
 }

package/dist/esm/structs/kits/presentation/templates.d.ts

@@ -1,11 +1,26 @@
+/**
+ * Template contract for the Presentation Kit.
+ *
+ * Place in the package: an optional App-side text master and a semantic-key allowlist. The program
+ * owns the master; inserted model text is only a value substituted into it, never a new template.
+ *
+ * Exports: `TextTemplateOptions`, `SemanticSlotDefinition`.
+ */
+/** Text template construction options. */
 export interface TextTemplateOptions {
+    /** Observer invoked with every rendered text. */
     readonly observe?: (result: string) => void | Promise<void>;
+    /** Builds the error for a slot the caller did not supply; receives the slot name. */
     readonly errors?: {
         readonly missingField?: (key: string) => Error | string;
     };
 }
+/** Declares the `{{namespace:key}}` slots a model may use, and how often. */
 export interface SemanticSlotDefinition {
+    /** Slot namespace; must match `^[a-z][a-z0-9-]*$`. */
     readonly namespace: string;
+    /** Allowed keys after the namespace; any other key makes the text invalid. */
     readonly keys: readonly string[];
+    /** Maximum total occurrences across the text; must be a non-negative integer. */
     readonly maxOccurrences: number;
 }

package/dist/esm/structs/kits/projection.d.ts

@@ -1,15 +1,36 @@
+/**
+ * Projection contract for the Projection Kit.
+ *
+ * Place in the package: an optional App-side helper that fits structured values into a character
+ * budget while keeping valid JSON. Callers choose the budget, rendering strategy and fallback text;
+ * the Kit only shrinks values and verifies the result fits.
+ *
+ * Exports: `ContentProjection`, `ContentProjectionOptions`, `TreeProjectionOptions`.
+ */
+/** Projection output. */
 export interface ContentProjection {
+    /** Rendered text that fits the requested budget. */
     readonly text: string;
+    /** True when anything was shortened or replaced by the fallback. */
     readonly truncated: boolean;
 }
+/** Candidate strategy for content projection. */
 export interface ContentProjectionOptions {
+    /** Maximum array items to keep, tried in order before moving to the next length. */
     readonly counts: readonly number[];
+    /** Maximum characters per string, tried in order inside each count candidate. */
     readonly lengths: readonly number[];
+    /** Renders a shortened value; must be synchronous. */
     readonly render: (excerpt: unknown) => string;
+    /** Builds fallback text for a limit, used when no candidate fits; must be synchronous. */
     readonly fallback: (limit: number) => string;
 }
+/** Depth- and record-level traversal options for tree projection. */
 export interface TreeProjectionOptions<Context> {
+    /** Maximum included depth; deeper values are omitted. Must be a non-negative integer. */
     readonly maxDepth: number;
+    /** Drops a value when it returns true; must be synchronous boolean. */
     readonly omit?: (value: unknown, depth: number, context: Context) => boolean;
+    /** Observes every retained record, for example to record which fields were kept. */
     readonly visitRecord?: (value: Record<string, unknown>, depth: number, context: Context) => void;
 }

package/dist/esm/structs/kits/reflection.d.ts

@@ -1,75 +1,134 @@
+/**
+ * Reflection contract for the Reflection Kit.
+ *
+ * Place in the package: an optional App-side diagnostic agent that inspects recorded execution
+ * evidence and answers a question about it. It reads metadata through an App-provided source, never
+ * the original event payloads, and reports what the evidence supports rather than asserting facts
+ * Core cannot prove. Reports are request-local and never persisted here.
+ *
+ * Exports: `reflectionIdentityFields`, `ReflectionEvidence`, `ReflectionQuery`, `ReflectionPage`,
+ * `ReflectionSource`, `reflectionFindingKinds`, `ReflectionFinding`, `ReflectionReport`,
+ * `ReflectionDefinition`, `ReflectionTask`.
+ */
 import type { ModelRunner } from '../../model/runner.js';
 import type { OperationContext, MaybePromise } from '../common.js';
 import type { ToolDefinition } from '../support/tools.js';
 import type { DiagnosticIdentity } from '../diagnostics.js';
+/** Identity fields an evidence item may project from the original diagnostic identity. */
 export declare const reflectionIdentityFields: readonly ["spanId", "parentSpanId", "invocationId", "parentInvocationId", "agentId", "branchId", "agentVersionId", "parentBranchId", "parentAgentVersionId", "forkPointId", "workflowInvocationId", "workflowNodeId", "nodeRole", "definitionId"];
 /** Explicit metadata projection, not an arbitrary original event/payload. */
-export interface ReflectionEvidence extends Partial<Pick<DiagnosticIdentity, typeof reflectionIdentityFields[number]>> {
+export interface ReflectionEvidence extends Partial<Pick<DiagnosticIdentity, (typeof reflectionIdentityFields)[number]>> {
+    /** Evidence id cited by findings when they rely on this item. */
     readonly id: string;
+    /** Run the item belongs to; queries are scoped by run. */
     readonly runId: string;
+    /** Evidence type, matched against `ReflectionQuery.types`. */
     readonly type: string;
     readonly occurredAtMs?: number;
+    /** Ordering key inside the source; ascending. */
     readonly sequence?: number;
     readonly stageId?: string;
     readonly status?: string;
+    /** Error or protocol code recorded on the item. */
     readonly code?: string;
+    /** Model or tool calls represented by the item. */
     readonly calls?: number;
     readonly durationMs?: number;
     readonly inputChars?: number;
     readonly outputChars?: number;
+    /** Instant after which the item is no longer retained by the source. */
     readonly expiresAtMs?: number;
 }
+/** One evidence query. */
 export interface ReflectionQuery {
+    /** Run to inspect; omitted means the App chooses the scope. */
     readonly run?: string;
+    /** Evidence types to include; omitted means all types. */
     readonly types?: readonly string[];
+    /** Opaque continuation cursor from a previous page. */
     readonly cursor?: string;
+    /** Maximum items requested; at least 1, clamped to the remaining evidence budget. */
     readonly limit: number;
 }
+/** One page of evidence plus an honest statement of its coverage. */
 export interface ReflectionPage {
+    /** Items in source order. */
     readonly items: readonly ReflectionEvidence[];
+    /** Continuation cursor; absent when the source has no further items. */
     readonly cursor?: string;
     readonly coverage: {
+        /** `best-effort` may miss items; `snapshot` reflects one consistent point in time. */
         readonly consistency: 'best-effort' | 'snapshot';
+        /** `true` complete, `false` known incomplete, `null` unknown. */
         readonly complete: boolean | null;
+        /** Human-readable descriptions of known gaps. */
         readonly gaps: readonly string[];
     };
 }
+/** App-owned evidence source, including its own authorization. */
 export interface ReflectionSource<App> {
     readonly id: string;
     readonly description: string;
+    /** Guards one query; runs before any evidence is read. */
     authorize(query: ReflectionQuery, context: OperationContext<App>): MaybePromise<void>;
+    /** Returns one page; an invalid page shape aborts the reflection. */
     query(query: ReflectionQuery, context: OperationContext<App>): Promise<ReflectionPage>;
 }
+/** Allowed finding kinds, from observed facts to advisory conclusions. */
 export declare const reflectionFindingKinds: readonly ["observed", "hypothesis", "recommendation"];
+/** One finding, always tied to the evidence it rests on. */
 export interface ReflectionFinding {
-    readonly kind: typeof reflectionFindingKinds[number];
+    /** `observed` must cite evidence; `hypothesis` and `recommendation` are advisory. */
+    readonly kind: (typeof reflectionFindingKinds)[number];
+    /** What the reflection claims. */
     readonly claim: string;
+    /** Evidence ids supporting the claim. */
     readonly evidenceIds: readonly string[];
 }
+/** Request-local reflection result. */
 export interface ReflectionReport {
     readonly id: string;
+    /** `incomplete` when evidence, model budget or the timeout stopped the work early. */
     readonly status: 'completed' | 'incomplete';
+    /** Question as submitted; at most 2000 characters. */
     readonly question: string;
     readonly findings: readonly ReflectionFinding[];
+    /** Known limitations, for example exhausted budgets or incomplete coverage. */
     readonly limitations: readonly string[];
+    /** Evidence items the reflection actually saw. */
     readonly evidence: readonly ReflectionEvidence[];
+    /** Coverage statement of each page that was read. */
     readonly coverage: readonly ReflectionPage['coverage'][];
     readonly createdAtMs: number;
     readonly expiresAtMs?: number;
+    /** Marker: a report is returned to the caller and never stored by the Kit. */
     readonly persisted: false;
 }
+/** Configuration for compiling a reflection task. */
 export interface ReflectionDefinition<App> {
+    /** Parent runner; the reflection creates a child and preserves the parent's reserve. */
     readonly model: Pick<ModelRunner, 'createChild' | 'remainingCalls'>;
+    /** Evidence source queried through the reflection tools. */
     readonly source: ReflectionSource<App>;
+    /** Additional tools exposed to the reflection model. */
     readonly tools?: readonly ToolDefinition<any, any, App>[];
+    /** Model calls the child may use; defaults to 4. */
     readonly maxCalls?: number;
+    /** Parent calls kept untouched; defaults to 1. */
     readonly reserveCalls?: number;
+    /** Wall-clock limit for the whole reflection in milliseconds; defaults to 30000. */
     readonly timeoutMs?: number;
+    /** Maximum evidence pages read; defaults to 4. */
     readonly maxPages?: number;
+    /** Maximum evidence items collected; defaults to 64. */
     readonly maxEvents?: number;
+    /** Maximum evidence characters placed in the model context; defaults to 12000. */
     readonly maxEvidenceChars?: number;
+    /** Guards one reflection request; runs before any model call. */
     authorize(question: string, context: OperationContext<App>): MaybePromise<void>;
 }
+/** Compiled reflection task. */
 export interface ReflectionTask<App> {
+    /** Answers the question from evidence; never throws for incomplete evidence alone. */
     run(question: string, context: OperationContext<App>): Promise<ReflectionReport>;
 }

package/dist/esm/structs/kits/reflection.js

@@ -1,4 +1,19 @@
-export const reflectionIdentityFields = Object.freeze(['spanId', 'parentSpanId', 'invocationId', 'parentInvocationId',
-    'agentId', 'branchId', 'agentVersionId', 'parentBranchId', 'parentAgentVersionId', 'forkPointId',
-    'workflowInvocationId', 'workflowNodeId', 'nodeRole', 'definitionId']);
+/** Identity fields an evidence item may project from the original diagnostic identity. */
+export const reflectionIdentityFields = Object.freeze([
+    'spanId',
+    'parentSpanId',
+    'invocationId',
+    'parentInvocationId',
+    'agentId',
+    'branchId',
+    'agentVersionId',
+    'parentBranchId',
+    'parentAgentVersionId',
+    'forkPointId',
+    'workflowInvocationId',
+    'workflowNodeId',
+    'nodeRole',
+    'definitionId',
+]);
+/** Allowed finding kinds, from observed facts to advisory conclusions. */
 export const reflectionFindingKinds = ['observed', 'hypothesis', 'recommendation'];

package/dist/esm/structs/kits/retrieval.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Retrieval contract for the Retrieval Kit.
+ *
+ * Place in the package: an optional App-side library for one query round-trip. Data access,
+ * authorization, state and result semantics are host ports; the Kit owns the fixed order — state,
+ * preparation, assertions, duplicate/budget checks, authorization, adapter call, result validation,
+ * source naming and declared effects.
+ *
+ * Exports: `RetrievalSource`, `RetrievalResult`, `RetrievalState`, `RetrievalReceipt`,
+ * `RetrievalReason`, `RetrievalEffect`, `RetrievalPorts`, `RetrievalRunner`, `RetrievalDefinition`.
+ */
 /** Request-local citation reference; the App may separately carry its content entity id. */
 export interface RetrievalSource {
     sourceId: string;
@@ -7,34 +18,53 @@ export interface RetrievalResult<Source extends RetrievalSource> {
 }
 /** Request-owned state. Clearing current evidence must not replenish spent budgets or seen keys. */
 export interface RetrievalState<Source extends RetrievalSource> {
+    /** Successful queries so far; compared against the current limit. */
     queryCount: number;
+    /** Query keys already attempted, including rejected ones, so retries count as duplicates. */
     readonly seen: Set<string>;
+    /** Sources from successful queries, in acceptance order. */
     readonly sources: Source[];
 }
+/** Facts of one accepted query. */
 export interface RetrievalReceipt<Query, Source extends RetrievalSource, Result extends RetrievalResult<Source>> {
+    /** Query after `prepare`, exactly as executed. */
     readonly query: Query;
+    /** Deduplication key reserved before the adapter call. */
     readonly key: string;
+    /** One-based position of this query within the request. */
     readonly sequence: number;
+    /** Adapter start instant in epoch milliseconds. */
     readonly startedAtMs: number;
+    /** Adapter output before source naming; rejected results never produce a receipt. */
     readonly rawResult: Result;
+    /** Same result with every `sourceId` replaced by the Kit-assigned name. */
     readonly result: Result;
     /** Domain attachments are computed from real results, not model-supplied receipts. */
     readonly extensions: Record<string, unknown>;
 }
+/** Lazy rejection wording: a fixed message, a pre-built error, or a factory bound to the query. */
 export type RetrievalReason<Query, Context> = Error | string | ((query: Query, context: Context) => Error | string);
+/** One effect applied after a successful query, in declaration order. */
 export interface RetrievalEffect<Query, Source extends RetrievalSource, Result extends RetrievalResult<Source>, Context> {
     readonly id: string;
     readonly description: string;
+    /** Applies the effect synchronously; a throw stops later effects without rollback. */
     handle(receipt: RetrievalReceipt<Query, Source, Result>, context: Context): void;
 }
+/** Host ports and policy for one retrieval kind. */
 export interface RetrievalPorts<Query, Source extends RetrievalSource, Result extends RetrievalResult<Source>, Context> {
     readonly id: string;
     readonly description: string;
     readonly tags?: readonly string[];
+    /** Normalizes the query before assertions run; must be synchronous. */
     readonly prepare?: (query: Query, context: Context) => Query;
+    /** Rejects a malformed query; must be synchronous and return void. */
     readonly assertInput: (query: Query, context: Context) => void;
+    /** Returns the request-owned state that holds counters and sources. */
     readonly state: (context: Context) => RetrievalState<Source>;
+    /** Maximum accepted queries for the current state. */
     readonly limit: (context: Context) => number;
+    /** Deduplication key; defaults to a canonical serialization of the query. */
     readonly key?: (query: Query) => string;
     readonly errors?: {
         readonly duplicate?: RetrievalReason<Query, Context>;
@@ -42,16 +72,24 @@ export interface RetrievalPorts<Query, Source extends RetrievalSource, Result ex
     };
     /** Resource authorization runs after duplicate/budget checks and before reserving a key. */
     readonly authorize?: (query: Query, context: Context) => void;
+    /** Performs the actual read; must be synchronous. Throwing does not refund the query key. */
     readonly execute: (query: Query, context: Context) => Result;
+    /** Validates the adapter result; a throw leaves the query counted as seen but not successful. */
     readonly assertResult?: (result: Result, query: Query, context: Context) => void;
+    /** Names a source; the assigned value replaces `sourceId` in the receipt result. */
     readonly sourceId?: (source: Source, query: Query, sequence: number, context: Context) => string;
     readonly effects?: readonly RetrievalEffect<Query, Source, Result, Context>[];
+    /** Clock override for receipt timestamps; defaults to `Date.now`. */
     readonly now?: () => number;
 }
+/** Compiled retrieval runner. */
 export interface RetrievalRunner<Query, Source extends RetrievalSource, Result extends RetrievalResult<Source>, Context> {
     readonly id: string;
     readonly description: string;
+    /** Effects that run after every accepted query. */
     readonly effects: readonly RetrievalEffect<Query, Source, Result, Context>[];
+    /** Executes one query in the fixed lifecycle order and returns its receipt. */
     run(input: Query, context: Context): RetrievalReceipt<Query, Source, Result>;
 }
+/** Retrieval ports specialized to an App operation context. */
 export type RetrievalDefinition<Query, Source extends RetrievalSource, Result extends RetrievalResult<Source>, App> = RetrievalPorts<Query, Source, Result, import('../common.js').OperationContext<App>>;

package/dist/esm/structs/kits/search.d.ts

@@ -1,32 +1,54 @@
+/**
+ * Text search contract for the Text Search Kit.
+ *
+ * Place in the package: an optional App-side full-text index. The Kit owns the index, declarative
+ * field validation and snapshot compatibility; the corpus, tokenization policy, storage, identity,
+ * filters and persistence stay with the App.
+ *
+ * Exports: `TextSearchOptions`, `TextSearchHit`, `TextSearchQuery`, `TextSearchSnapshot`.
+ */
 import type { SearchHit } from '../common.js';
 /** App supplies fields, tokenizer and its own schema/tokenizer revision. */
 export interface TextSearchOptions<Document extends {
     id: string;
 }> {
+    /** App-owned revision of the field/tokenizer configuration; a change invalidates snapshots. */
     readonly indexRevision: string;
+    /** Fields that are indexed and searchable. */
     readonly fields: readonly (keyof Document & string)[];
+    /** Fields returned in a hit; the indexed body is not implicitly returned. */
     readonly storedFields: readonly (keyof Document & string)[];
+    /** Tokenizer override; defaults to MiniSearch's default tokenizer. */
     readonly tokenize?: (text: string, fieldName?: string) => string[];
+    /** Per-field relevance multiplier; omitted fields keep the default weight. */
     readonly boost?: Readonly<Partial<Record<keyof Document & string, number>>>;
+    /** How multiple query terms combine; defaults to the engine default (OR). */
     readonly combineWith?: 'AND' | 'OR';
 }
 export interface TextSearchHit<Document extends {
     id: string;
 }> extends SearchHit<Partial<Document>> {
+    /** Matched terms, as reported by the engine after tokenization. */
     readonly terms: readonly string[];
 }
 export interface TextSearchQuery<Document extends {
     id: string;
 }> {
+    /** Maximum number of hits returned. */
     readonly limit: number;
     /** Required on every query; the application owns authorization and applicability. */
     readonly filter: (document: Readonly<Partial<Document>> & {
         id: string;
     }) => boolean;
 }
+/** Serialized index; the revision pair proves the snapshot matches the current configuration. */
 export interface TextSearchSnapshot {
+    /** Snapshot format version; other versions are not loaded. */
     readonly version: 2;
+    /** Engine that produced the snapshot; a different engine cannot restore it. */
     readonly engine: 'minisearch-7';
+    /** Fingerprint of the field and tokenizer configuration that built the index. */
     readonly configurationFingerprint: string;
+    /** Serialized MiniSearch index. */
     readonly serializedIndex: string;
 }

package/dist/esm/structs/kits/text-skills.d.ts

@@ -1,25 +1,50 @@
+/**
+ * Text skill contract for the Text Skills Kit.
+ *
+ * Place in the package: an optional App-side loader for text-only skill documents. A skill is
+ * metadata plus instructions read from a document; nothing here executes code, imports modules or
+ * calls tools. Ids, entry paths and header fields are validated against the declared limits.
+ *
+ * Exports: `TextSkillRegistration`, `TextSkill`, `TextSkillHeader`, `TextSkillLoaderDefinition`,
+ * `TextSkillReadPorts`, `TextSkillLoader`.
+ */
 import type { BreakReason } from '../utils/rules.js';
+/** Catalog entry of one text skill, before its document is read. */
 export interface TextSkillRegistration {
+    /** Skill id, lowercase kebab case, bounded by `maxIdChars` (64 by default). */
     readonly id: string;
+    /** Document path; must equal the loader's `entryFor(id)` result. */
     readonly entry: string;
+    /** Only text workflow skills are supported. */
     readonly kind: 'text-workflow';
+    /** Tool ids the instructions may reference; validated by the caller, not executed here. */
     readonly toolIds: readonly string[];
 }
+/** Loaded skill: registration plus the parsed document text. */
 export interface TextSkill extends TextSkillRegistration {
+    /** Description taken from the document header and matching the registration. */
     readonly description: string;
+    /** Instruction body without the header, bounded by `maxInstructionChars`. */
     readonly instructions: string;
 }
+/** Header every skill document must carry. */
 export interface TextSkillHeader {
     readonly id: string;
     readonly description: string;
 }
+/** Loader limits, parsing hooks and rejection wording. */
 export interface TextSkillLoaderDefinition {
+    /** Maximum characters of the instruction body; larger documents are rejected. */
     readonly maxInstructionChars: number;
+    /** Maximum characters of the description header. */
     readonly maxDescriptionChars: number;
+    /** Maximum id length; defaults to 64. */
     readonly maxIdChars?: number;
+    /** Maps an id to its expected document path; defaults to `<id>/SKILL.md`. */
     readonly entryFor?: (id: string) => string;
     /** Default parser accepts the strict name/description header; hosts can inject a YAML parser. */
     readonly parseHeader?: (instructions: string) => TextSkillHeader | undefined;
+    /** Diagnostic tags attached to loader rejections. */
     readonly tags?: readonly string[];
     readonly errors?: {
         readonly catalog?: BreakReason;
@@ -27,10 +52,21 @@ export interface TextSkillLoaderDefinition {
         readonly document?: BreakReason;
     };
 }
+/** Host port that reads one skill document by path. */
 export interface TextSkillReadPorts {
+    /** Returns the document text; throwing aborts the load. */
     read(entry: string): string;
 }
+/** Compiled loader. */
 export interface TextSkillLoader {
+    /**
+     * Reads and validates every registered skill.
+     *
+     * @param request - `entries` is the untrusted catalog array; shape is validated here.
+     * @param ports - Document reader supplied by the host.
+     * @returns Frozen skills in catalog order.
+     * @throws When the catalog, a registration, an entry path or a document is invalid.
+     */
     load(request: {
         readonly entries: unknown;
     }, ports: TextSkillReadPorts): readonly TextSkill[];