@jangts/agent-core 0.1.1 → 0.2.0

package/dist/esm/support/schema.d.ts

@@ -1,11 +1,41 @@
 import type { SchemaAdapter, JsonSchema } from '../structs/common.js';
 import type { JsonSchemaOptions } from '../structs/support/schema.js';
-/** Uses a caller-owned typed compiler. A plain schema without a typed compiler remains unknown. */
+/**
+ * Build an adapter from a caller-owned typed JSON Schema compiler.
+ *
+ * The schema is cloned and frozen before it reaches the compiler, so later mutation of the input
+ * cannot change validation. Compilation and validation must both be synchronous.
+ *
+ * @param schema JSON Schema describing the accepted value.
+ * @param options Compiler plus an optional error factory for rejected values.
+ * @returns A frozen adapter exposing `jsonSchema` and a `parse` that returns the input as `Value`.
+ * @throws {TypeError} When the compiler is asynchronous or does not return a validator, or when no
+ *   custom error applies; also when the validator is asynchronous or does not return a boolean.
+ */
 export declare function fromJsonSchema<Value = unknown>(schema: JsonSchema, options: JsonSchemaOptions<Value>): SchemaAdapter<Value>;
+/**
+ * Wrap a library schema that already parses values (for example Zod or Valibot style).
+ *
+ * `parse` is delegated unchanged, so the library keeps ownership of coercion and error reporting;
+ * only the JSON Schema projection is produced here.
+ *
+ * @param schema Object exposing a `parse` method.
+ * @param options Converter that projects the schema into JSON Schema.
+ * @returns A frozen adapter whose `parse` returns the wrapped parser's result type.
+ * @throws {TypeError} When the JSON Schema conversion is asynchronous.
+ */
 export declare function fromParserSchema<Schema extends {
     parse(value: unknown): unknown;
 }>(schema: Schema, options: {
     toJsonSchema(schema: Schema): JsonSchema;
 }): SchemaAdapter<ReturnType<Schema['parse']>>;
+/**
+ * Re-snapshot an existing adapter without changing its behavior.
+ *
+ * Used to detach a caller-owned adapter from later mutation before it is exposed or reused.
+ *
+ * @param definition Adapter to copy.
+ * @returns A frozen adapter with the same validation and parsing behavior.
+ */
 export declare function defineSchema<Value>(definition: SchemaAdapter<Value>): SchemaAdapter<Value>;
 export type * from '../structs/support/schema.js';

package/dist/esm/support/schema.js

@@ -1,7 +1,27 @@
+/**
+ * Schema adapter helpers: turn JSON Schema compilers and library parsers into Core adapters.
+ *
+ * Support supplies the adapter shape and snapshotting; the compiler, validator package and error
+ * messages remain application choices. A plain JSON Schema without a typed compiler stays unknown
+ * instead of being silently treated as permissive.
+ *
+ * Main exports: `fromJsonSchema`, `fromParserSchema` and `defineSchema`.
+ */
 import { snapshotSchemaAdapter } from '../utils/schema-adapter.js';
 import { freezeSchema } from '../utils/object.js';
 import { booleanResult, synchronous } from '../utils/synchronous.js';
-/** Uses a caller-owned typed compiler. A plain schema without a typed compiler remains unknown. */
+/**
+ * Build an adapter from a caller-owned typed JSON Schema compiler.
+ *
+ * The schema is cloned and frozen before it reaches the compiler, so later mutation of the input
+ * cannot change validation. Compilation and validation must both be synchronous.
+ *
+ * @param schema JSON Schema describing the accepted value.
+ * @param options Compiler plus an optional error factory for rejected values.
+ * @returns A frozen adapter exposing `jsonSchema` and a `parse` that returns the input as `Value`.
+ * @throws {TypeError} When the compiler is asynchronous or does not return a validator, or when no
+ *   custom error applies; also when the validator is asynchronous or does not return a boolean.
+ */
 export function fromJsonSchema(schema, options) {
     const jsonSchema = structuredClone(schema);
     freezeSchema(jsonSchema);
@@ -9,19 +29,41 @@ export function fromJsonSchema(schema, options) {
     if (typeof validate !== 'function')
         throw new TypeError('Schema compilers must return a validator');
     const error = options.error?.bind(options);
-    return snapshotSchemaAdapter({ jsonSchema, parse(value) {
+    return snapshotSchemaAdapter({
+        jsonSchema,
+        parse(value) {
             const valid = booleanResult(validate(value), 'Schema validators must be synchronous', 'Schema validators must return boolean');
             if (!valid)
-                throw synchronous(error?.(value, validate.errors), 'Schema error factories must be synchronous') ?? new TypeError('Input does not match JSON Schema');
+                throw (synchronous(error?.(value, validate.errors), 'Schema error factories must be synchronous') ?? new TypeError('Input does not match JSON Schema'));
             return value;
-        } });
+        },
+    });
 }
+/**
+ * Wrap a library schema that already parses values (for example Zod or Valibot style).
+ *
+ * `parse` is delegated unchanged, so the library keeps ownership of coercion and error reporting;
+ * only the JSON Schema projection is produced here.
+ *
+ * @param schema Object exposing a `parse` method.
+ * @param options Converter that projects the schema into JSON Schema.
+ * @returns A frozen adapter whose `parse` returns the wrapped parser's result type.
+ * @throws {TypeError} When the JSON Schema conversion is asynchronous.
+ */
 export function fromParserSchema(schema, options) {
     return snapshotSchemaAdapter({
         jsonSchema: synchronous(options.toJsonSchema(schema), 'Schema conversion must be synchronous'),
         parse: schema.parse.bind(schema),
     });
 }
+/**
+ * Re-snapshot an existing adapter without changing its behavior.
+ *
+ * Used to detach a caller-owned adapter from later mutation before it is exposed or reused.
+ *
+ * @param definition Adapter to copy.
+ * @returns A frozen adapter with the same validation and parsing behavior.
+ */
 export function defineSchema(definition) {
     return snapshotSchemaAdapter(definition);
 }

package/dist/esm/support/stream-events.d.ts

@@ -1,2 +1,23 @@
-/** One-slot rendezvous: consuming an event releases the producer; no unbounded model-output queue. */
+/**
+ * Bounded event plumbing for applications that must forward streamed output under cancellation.
+ *
+ * A producer pushes events one at a time and waits for each to be consumed; the consumer pulls
+ * from an async iterable. There is no unbounded queue, so a slow consumer slows the producer
+ * instead of growing memory, and aborting the signal closes both sides.
+ *
+ * Main export: `streamEvents`.
+ */
+/**
+ * Bridge a push-style producer to a pull-style async iterable with a one-slot rendezvous.
+ *
+ * The producer must await every `emit` call before emitting again; concurrent emissions are
+ * rejected rather than buffered. The slot is released only after the consumer receives the event,
+ * so backpressure is exact.
+ *
+ * @param operation Producer that receives an `emit` callback and runs to completion.
+ * @param context Execution context carrying the abort signal used to close the rendezvous.
+ * @returns An async iterable yielding each event in production order.
+ * @throws The producer's error, or the signal's abort reason when cancelled. Also rejects an
+ *   `emit` that overlaps another, occurs after close, or is never consumed by the consumer.
+ */
 export declare function streamEvents<Event>(operation: (emit: (event: Event) => Promise<void>) => Promise<void>, { signal }: import('../structs/common.js').ExecutionContext): AsyncIterable<Event>;

package/dist/esm/support/stream-events.js

@@ -1,4 +1,25 @@
-/** One-slot rendezvous: consuming an event releases the producer; no unbounded model-output queue. */
+/**
+ * Bounded event plumbing for applications that must forward streamed output under cancellation.
+ *
+ * A producer pushes events one at a time and waits for each to be consumed; the consumer pulls
+ * from an async iterable. There is no unbounded queue, so a slow consumer slows the producer
+ * instead of growing memory, and aborting the signal closes both sides.
+ *
+ * Main export: `streamEvents`.
+ */
+/**
+ * Bridge a push-style producer to a pull-style async iterable with a one-slot rendezvous.
+ *
+ * The producer must await every `emit` call before emitting again; concurrent emissions are
+ * rejected rather than buffered. The slot is released only after the consumer receives the event,
+ * so backpressure is exact.
+ *
+ * @param operation Producer that receives an `emit` callback and runs to completion.
+ * @param context Execution context carrying the abort signal used to close the rendezvous.
+ * @returns An async iterable yielding each event in production order.
+ * @throws The producer's error, or the signal's abort reason when cancelled. Also rejects an
+ *   `emit` that overlaps another, occurs after close, or is never consumed by the consumer.
+ */
 export async function* streamEvents(operation, { signal }) {
     let slot;
     let wake;
@@ -6,24 +27,53 @@ export async function* streamEvents(operation, { signal }) {
     let sending = false;
     let failure;
     let rejectSend;
-    const notify = () => { wake?.(); wake = undefined; };
-    const abort = () => { closed = true; rejectSend?.(signal.reason ?? new Error('Stream closed')); notify(); };
+    const notify = () => {
+        wake?.();
+        wake = undefined;
+    };
+    const abort = () => {
+        closed = true;
+        rejectSend?.(signal.reason ?? new Error('Stream closed'));
+        notify();
+    };
     signal.addEventListener('abort', abort, { once: true });
     if (signal.aborted)
         abort();
-    const producer = Promise.resolve().then(() => {
+    const producer = Promise.resolve()
+        .then(() => {
         signal.throwIfAborted();
         // Before the producer starts, only abort can close this rendezvous; the
         // signal check above already rejects it with the original reason.
-        return operation(event => {
+        return operation((event) => {
             if (closed || signal.aborted)
                 return Promise.reject(signal.reason ?? new Error('Stream closed'));
             if (sending)
                 return Promise.reject(new Error('Event producers must await delivery'));
             sending = true;
-            return new Promise((resolve, reject) => { rejectSend = reject; slot = { event, release: () => { sending = false; resolve(); }, cancel: () => { sending = false; reject(new Error('Stream closed before event consumption')); } }; notify(); });
+            return new Promise((resolve, reject) => {
+                rejectSend = reject;
+                slot = {
+                    event,
+                    release: () => {
+                        sending = false;
+                        resolve();
+                    },
+                    cancel: () => {
+                        sending = false;
+                        reject(new Error('Stream closed before event consumption'));
+                    },
+                };
+                notify();
+            });
         });
-    }).catch(error => { failure = { error }; }).finally(() => { done = true; notify(); });
+    })
+        .catch((error) => {
+        failure = { error };
+    })
+        .finally(() => {
+        done = true;
+        notify();
+    });
     try {
         while (true) {
             signal.throwIfAborted();
@@ -48,7 +98,9 @@ export async function* streamEvents(operation, { signal }) {
                 return;
             }
             else
-                await new Promise(resolve => { wake = resolve; });
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
         }
     }
     finally {

package/dist/esm/support/tool-runtime.d.ts

@@ -1 +1,7 @@
+/**
+ * Re-export barrel: exposes the Core tool registry factory to Support consumers.
+ *
+ * Core owns the registry implementation; Support only re-exports it so applications can bind a
+ * `ToolCatalog` without importing internal paths. No behavior is added here.
+ */
 export { createToolRegistry } from '../capabilities/tool-runtime.js';

package/dist/esm/support/tool-runtime.js

@@ -1 +1,7 @@
+/**
+ * Re-export barrel: exposes the Core tool registry factory to Support consumers.
+ *
+ * Core owns the registry implementation; Support only re-exports it so applications can bind a
+ * `ToolCatalog` without importing internal paths. No behavior is added here.
+ */
 export { createToolRegistry } from '../capabilities/tool-runtime.js';

package/dist/esm/support/tools.d.ts

@@ -1,6 +1,28 @@
 import type { ToolDefinition, ToolCatalog, CompiledTool } from '../structs/support/tools.js';
+/**
+ * Validate one tool declaration and freeze a detached copy of it.
+ *
+ * `authorize` must settle with `void`; a rejection has to be thrown, so a returned `false` cannot
+ * silently pass. Handlers are bound to the declaration object, and the input schema is
+ * re-snapshotted so later mutation cannot widen the accepted input.
+ *
+ * @param definition Tool declaration whose `id` is preserved as a literal type.
+ * @returns A frozen tool definition with a snapshotted `inputSchema`.
+ * @throws {TypeError} When `id`, `kind` or `description` is blank, when a handler is missing, or
+ *   when `authorize` returns a value instead of throwing.
+ */
 export declare function defineTool<Input, Output, App, const Id extends string = string>(definition: ToolDefinition<Input, Output, App> & {
     readonly id: Id;
 }): ToolDefinition<Input, Output, App, Id>;
+/**
+ * Compile tool declarations into a frozen catalog with model capabilities and runtime binding.
+ *
+ * Each tool becomes a model capability whose resolver returns `{ toolId, input }`; the model only
+ * chooses among registered tools, it never invokes them directly.
+ *
+ * @param definitions Tool declarations in catalog order.
+ * @returns A frozen catalog with `capabilities`, `select` and `bind`.
+ * @throws {TypeError} When a tool declaration is invalid or a tool ID is duplicated.
+ */
 export declare function defineToolCatalog<App, const Definitions extends readonly ToolDefinition<any, any, App>[] = readonly ToolDefinition<any, any, App>[]>(definitions: Definitions): ToolCatalog<App, CompiledTool<App, Definitions[number]>>;
 export type * from '../structs/support/tools.js';

package/dist/esm/support/tools.js

@@ -1,39 +1,108 @@
+/**
+ * Tool support: turn typed application tool definitions into a Core-schedulable tool catalog.
+ *
+ * A tool declaration pairs an input schema with authorization, execution and output parsing. The
+ * catalog projects those tools into model capabilities and binds them to the Core tool registry
+ * when a runtime request supplies the application. Support only assembles the registration; Core
+ * still performs authorization, invocation, budgets and cancellation.
+ *
+ * Main exports: `defineTool` and `defineToolCatalog`.
+ */
 import { ModelCapabilityRegistry } from '../capabilities/model.js';
 import { createToolRegistry } from './tool-runtime.js';
 import { defineSchema } from './schema.js';
 import { readonlyCatalog } from '../utils/catalog.js';
 import { maybeAssertion } from '../utils/synchronous.js';
+/**
+ * Validate one tool declaration and freeze a detached copy of it.
+ *
+ * `authorize` must settle with `void`; a rejection has to be thrown, so a returned `false` cannot
+ * silently pass. Handlers are bound to the declaration object, and the input schema is
+ * re-snapshotted so later mutation cannot widen the accepted input.
+ *
+ * @param definition Tool declaration whose `id` is preserved as a literal type.
+ * @returns A frozen tool definition with a snapshotted `inputSchema`.
+ * @throws {TypeError} When `id`, `kind` or `description` is blank, when a handler is missing, or
+ *   when `authorize` returns a value instead of throwing.
+ */
 export function defineTool(definition) {
     const { id, kind, description } = definition;
     if (!id?.trim() || !kind?.trim() || !description?.trim())
         throw new TypeError('Invalid tool identity');
-    if (typeof definition.authorize !== 'function' || typeof definition.execute !== 'function' || typeof definition.parseOutput !== 'function')
+    if (typeof definition.authorize !== 'function' ||
+        typeof definition.execute !== 'function' ||
+        typeof definition.parseOutput !== 'function')
         throw new TypeError('Missing tool handler');
     const inputSchema = defineSchema(definition.inputSchema);
     const authorize = definition.authorize.bind(definition);
-    return Object.freeze({ id, kind, description, inputSchema,
+    return Object.freeze({
+        id,
+        kind,
+        description,
+        inputSchema,
         authorize(input, context) {
             return maybeAssertion(authorize(input, context), 'Authorization must return void; rejection must throw');
         },
         execute: definition.execute.bind(definition),
         debugSteps: definition.debugSteps?.bind(definition),
-        parseOutput: definition.parseOutput.bind(definition), });
+        parseOutput: definition.parseOutput.bind(definition),
+    });
 }
+/**
+ * Compile tool declarations into a frozen catalog with model capabilities and runtime binding.
+ *
+ * Each tool becomes a model capability whose resolver returns `{ toolId, input }`; the model only
+ * chooses among registered tools, it never invokes them directly.
+ *
+ * @param definitions Tool declarations in catalog order.
+ * @returns A frozen catalog with `capabilities`, `select` and `bind`.
+ * @throws {TypeError} When a tool declaration is invalid or a tool ID is duplicated.
+ */
 export function defineToolCatalog(definitions) {
-    const entries = definitions.map(definition => defineTool(definition));
-    const view = readonlyCatalog(entries, id => new TypeError(`Unknown tool: ${id}`));
-    const capabilities = new ModelCapabilityRegistry(entries.map(tool => ({ id: tool.id, description: tool.description, inputSchema: defineSchema({ jsonSchema: tool.inputSchema.jsonSchema, parse: (input) => input }),
+    const entries = definitions.map((definition) => defineTool(definition));
+    const view = readonlyCatalog(entries, (id) => new TypeError(`Unknown tool: ${id}`));
+    const capabilities = new ModelCapabilityRegistry(entries.map((tool) => ({
+        id: tool.id,
+        description: tool.description,
+        inputSchema: defineSchema({
+            jsonSchema: tool.inputSchema.jsonSchema,
+            parse: (input) => input,
+        }),
         resolve: (input) => ({ toolId: tool.id, input }),
     }))).seal();
-    return Object.freeze({ ...view, capabilities,
-        select(ids) { capabilities.select(ids); return defineToolCatalog(ids.map(id => view.require(id))); },
+    return Object.freeze({
+        ...view,
+        capabilities,
+        /**
+         * Narrow the catalog to the given tool IDs, preserving their declaration order.
+         *
+         * @param ids Registered tool IDs to keep.
+         * @returns A new catalog containing only the selected tools.
+         * @throws {TypeError} When an ID is not registered in this catalog.
+         */
+        select(ids) {
+            capabilities.select(ids);
+            return defineToolCatalog(ids.map((id) => view.require(id)));
+        },
+        /**
+         * Bind the catalog to one application runtime request.
+         *
+         * @param request Runtime request supplying the app and optional execution/error ports.
+         * @returns A frozen runtime whose `invoke`/`invokeSync` delegate to the Core tool registry.
+         * @throws {TypeError} When the request does not carry an `app`.
+         */
         bind(request) {
             if (!request || !('app' in request))
                 throw new TypeError('A runtime request requires app');
             const registry = createToolRegistry(entries, request.app, {
-                execution: request.execution, errors: request.errors,
+                execution: request.execution,
+                errors: request.errors,
             });
-            return Object.freeze({ capabilities, get events() { return registry.events; },
+            return Object.freeze({
+                capabilities,
+                get events() {
+                    return registry.events;
+                },
                 invokeSync: registry.invoke.bind(registry),
                 invoke: registry.invokeAsync.bind(registry),
             });

package/dist/esm/support/transport/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Transport helpers for hosts that own their own HTTP response lifecycle.
+ *
+ * `./sse.js` covers server-sent events (reading, encoding and cancellable writes) and
+ * `./json.js` covers framed JSON scanning. Both are mechanical utilities: the host decides which
+ * traffic, frames and content are acceptable.
+ */
 export * from './sse.js';
 export * from './json.js';

package/dist/esm/support/transport/index.js

@@ -1,2 +1,9 @@
+/**
+ * Transport helpers for hosts that own their own HTTP response lifecycle.
+ *
+ * `./sse.js` covers server-sent events (reading, encoding and cancellable writes) and
+ * `./json.js` covers framed JSON scanning. Both are mechanical utilities: the host decides which
+ * traffic, frames and content are acceptable.
+ */
 export * from './sse.js';
 export * from './json.js';

package/dist/esm/support/transport/json.d.ts

@@ -1,6 +1,33 @@
+/**
+ * JSON transport framing: locate complete JSON objects inside free-form streamed text.
+ *
+ * Framing is purely mechanical. It never repairs, truncates or interprets fields; consumers decide
+ * which surrounding content and which frames they allow. Limits keep malformed or hostile streams
+ * from consuming unbounded memory.
+ *
+ * Main exports: `scanJsonObjectFrames` and `parseJsonFrames`.
+ */
 import type { JsonFrameLimits } from '../../structs/support/transport/json.js';
-/** Extract complete object-shaped spans in surrounding text, without parsing or selecting them. */
+/**
+ * Extract complete object-shaped spans from surrounding text, without parsing or selecting them.
+ *
+ * @param text Streamed text possibly containing JSON objects and unrelated content.
+ * @returns Raw object spans in source order.
+ * @throws {Error} When the text ends inside an unterminated object or string.
+ */
 export declare function scanJsonObjectFrames(text: string): string[];
-/** Scan complete object frames only; never repair, truncate or interpret their fields. */
+/**
+ * Parse complete object frames under explicit count and size limits.
+ *
+ * Only whitespace may appear outside frames; a stray closing brace is tolerated only up to
+ * `maxExtraClosings`, which covers transports that repeat the delimiter after the payload.
+ *
+ * @param text Streamed text to scan.
+ * @param limits Frame count, size and stray-closer allowances; validated before scanning.
+ * @returns Parsed frames in source order.
+ * @throws {TypeError} When a limit is not a safe integer or falls outside its allowed range.
+ * @throws {Error} When a limit is exceeded, content outside a frame is not whitespace, or the
+ *   transport ends before at least one complete frame exists.
+ */
 export declare function parseJsonFrames(text: string, limits: JsonFrameLimits): Record<string, unknown>[];
 export type { JsonFrameLimits } from '../../structs/support/transport/json.js';

package/dist/esm/support/transport/json.js

@@ -30,7 +30,13 @@ function* scan(text) {
     if (depth || quoted)
         throw new Error('Incomplete JSON transport');
 }
-/** Extract complete object-shaped spans in surrounding text, without parsing or selecting them. */
+/**
+ * Extract complete object-shaped spans from surrounding text, without parsing or selecting them.
+ *
+ * @param text Streamed text possibly containing JSON objects and unrelated content.
+ * @returns Raw object spans in source order.
+ * @throws {Error} When the text ends inside an unterminated object or string.
+ */
 export function scanJsonObjectFrames(text) {
     const frames = [];
     for (const part of scan(text))
@@ -38,10 +44,26 @@ export function scanJsonObjectFrames(text) {
             frames.push(part.text);
     return frames;
 }
-/** Scan complete object frames only; never repair, truncate or interpret their fields. */
+/**
+ * Parse complete object frames under explicit count and size limits.
+ *
+ * Only whitespace may appear outside frames; a stray closing brace is tolerated only up to
+ * `maxExtraClosings`, which covers transports that repeat the delimiter after the payload.
+ *
+ * @param text Streamed text to scan.
+ * @param limits Frame count, size and stray-closer allowances; validated before scanning.
+ * @returns Parsed frames in source order.
+ * @throws {TypeError} When a limit is not a safe integer or falls outside its allowed range.
+ * @throws {Error} When a limit is exceeded, content outside a frame is not whitespace, or the
+ *   transport ends before at least one complete frame exists.
+ */
 export function parseJsonFrames(text, limits) {
-    if (!Number.isSafeInteger(limits.maxFrames) || limits.maxFrames < 1
-        || !Number.isSafeInteger(limits.maxExtraClosings) || limits.maxExtraClosings < 0)
+    if (!Number.isSafeInteger(limits.maxFrames) ||
+        limits.maxFrames < 1 ||
+        !Number.isSafeInteger(limits.maxExtraClosings) ||
+        limits.maxExtraClosings < 0 ||
+        (limits.maxFrameChars !== undefined &&
+            (!Number.isSafeInteger(limits.maxFrameChars) || limits.maxFrameChars < 1)))
         throw new TypeError('Invalid JSON frame limits');
     const frames = [];
     let extraClosings = 0;
@@ -49,6 +71,8 @@ export function parseJsonFrames(text, limits) {
         if (part.kind === 'frame') {
             if (frames.length >= limits.maxFrames)
                 throw new Error('JSON frame limit exceeded');
+            if (limits.maxFrameChars !== undefined && part.text.length > limits.maxFrameChars)
+                throw new Error('JSON frame size exceeded');
             frames.push(JSON.parse(part.text));
         }
         else if (part.text === '}') {

package/dist/esm/support/transport/sse.d.ts

@@ -1,10 +1,40 @@
+/**
+ * Server-sent event transport: encode frames, write them with backpressure, and re-export readers.
+ *
+ * The host owns its HTTP response and lifecycle; these helpers only format frames and wait in a
+ * cancellable way. Reading is delegated to the shared streaming package so Core and Support use
+ * one parser.
+ *
+ * Main exports: `encodeSseEvent`, `writeSseFrame`, plus `readSse`, `abortableStream` and their
+ * types.
+ */
 import type { SseWriter, SseOutputEvent } from '../../structs/support/transport/sse.js';
 /** Public transport facade. Applications depend on core; streaming remains an implementation dependency. */
 export { readSse, SseIdleTimeoutError } from '@jangts/streaming/sse';
 export type { SseEvent, SseReadOptions } from '../../structs/support/transport/sse.js';
 export { abortableStream } from '@jangts/streaming/abortable-stream';
+/**
+ * Encode one event in the server-sent events wire format.
+ *
+ * Every line of `data` gets its own `data:` field, because a raw newline would start a new field.
+ *
+ * @param event Event name and payload to encode.
+ * @returns The complete frame, terminated by a blank line.
+ * @throws {TypeError} When the event name contains a newline, which would corrupt the frame.
+ */
 export declare function encodeSseEvent(event: SseOutputEvent): string;
-/** The host owns its HTTP response and lifecycle; this utility handles cancellable backpressure. */
+/**
+ * Write one encoded frame and wait for drain when the writer reports backpressure.
+ *
+ * The signal is re-checked around the write and the drain wait, so cancellation does not leave a
+ * pending write considered successful.
+ *
+ * @param request Writer plus the already encoded frame.
+ * @param context Execution context carrying the abort signal.
+ * @returns Resolves once the frame is accepted or the writer drains.
+ * @throws The signal's abort reason, or {@link TypeError} when `write` does not return a boolean
+ *   synchronously.
+ */
 export declare function writeSseFrame({ writer, frame }: {
     writer: SseWriter;
     frame: string;

package/dist/esm/support/transport/sse.js

@@ -3,12 +3,35 @@ import { booleanResult } from '../../utils/synchronous.js';
 /** Public transport facade. Applications depend on core; streaming remains an implementation dependency. */
 export { readSse, SseIdleTimeoutError } from '@jangts/streaming/sse';
 export { abortableStream } from '@jangts/streaming/abortable-stream';
+/**
+ * Encode one event in the server-sent events wire format.
+ *
+ * Every line of `data` gets its own `data:` field, because a raw newline would start a new field.
+ *
+ * @param event Event name and payload to encode.
+ * @returns The complete frame, terminated by a blank line.
+ * @throws {TypeError} When the event name contains a newline, which would corrupt the frame.
+ */
 export function encodeSseEvent(event) {
     if (/[\r\n]/.test(event.event))
         throw new TypeError('SSE event name cannot contain a newline');
-    return `event: ${event.event}\n${event.data.split(/\r\n|\r|\n/).map(line => `data: ${line}\n`).join('')}\n`;
+    return `event: ${event.event}\n${event.data
+        .split(/\r\n|\r|\n/)
+        .map((line) => `data: ${line}\n`)
+        .join('')}\n`;
 }
-/** The host owns its HTTP response and lifecycle; this utility handles cancellable backpressure. */
+/**
+ * Write one encoded frame and wait for drain when the writer reports backpressure.
+ *
+ * The signal is re-checked around the write and the drain wait, so cancellation does not leave a
+ * pending write considered successful.
+ *
+ * @param request Writer plus the already encoded frame.
+ * @param context Execution context carrying the abort signal.
+ * @returns Resolves once the frame is accepted or the writer drains.
+ * @throws The signal's abort reason, or {@link TypeError} when `write` does not return a boolean
+ *   synchronously.
+ */
 export async function writeSseFrame({ writer, frame }, { signal }) {
     signal.throwIfAborted();
     const ready = booleanResult(writer.write(frame), 'SSE writes must return boolean synchronously');

package/dist/esm/types.d.ts

@@ -1,4 +1,12 @@
-/** Type-only public entry. Runtime values come from Core, Support or individual Kits. */
+/**
+ * Type-only entry (`@jangts/agent-core/types`): every public declaration without runtime
+ * values, suitable for consumers that only need compile-time shapes.
+ *
+ * It mirrors the root surface plus Kit-specific structures, and re-exports `./index.js` as
+ * types so a single import satisfies both usage styles. Because nothing here executes, this
+ * entry cannot be used to reach registries or helpers; those stay on the root entry, the
+ * `Support` namespace, or individual Kit subpaths.
+ */
 export type * from './structs/index.js';
 export type * from './structs/kits/answering/tasks.js';
 export type * from './structs/kits/answering/checks.js';

package/dist/esm/utils/break-observer.d.ts

@@ -1,5 +1,30 @@
+/**
+ * Process-wide diagnostic outlet for `breakWhile` rejections.
+ *
+ * `rules.ts` owns the decision itself; this module only reports the rejection a host
+ * asked to observe. Reporting is optional and strictly fire-and-forget, so a faulty
+ * observer cannot change validation semantics.
+ *
+ * Exports: `configureBreakWhile` (install the observer) and `observeBreak` (notify it).
+ */
 import type { BreakCheck, BreakWhileConfig } from '../structs/utils/rules.js';
-/** Hosts may install a diagnostic observer; no logging or persistence is enabled by default. */
+/**
+ * Install the host-owned break observer.
+ *
+ * No logging or persistence is enabled by default; passing no argument (or an empty
+ * config) removes any previously installed observer.
+ *
+ * @param config - Observation configuration; `onBreak` receives one frozen event per rejection.
+ */
 export declare function configureBreakWhile(config?: BreakWhileConfig): void;
-/** Diagnostic failures must never replace the original interruption. */
+/**
+ * Notify the installed observer about a rejection.
+ *
+ * The original interruption is authoritative: observer failures, and rejections of the
+ * promise an observer returns, are swallowed.
+ *
+ * @param error - The value that is about to be thrown by `breakWhile`.
+ * @param tags - Call-site tags supplied by the caller of `breakWhile`.
+ * @param rule - The failing check, whose own tags are merged into the reported set.
+ */
 export declare function observeBreak(error: unknown, tags: readonly string[], rule: Pick<BreakCheck, 'tags'>): void;