@jangts/agent-core 0.1.1 → 0.2.1

package/dist/esm/kits/interaction/command.js

@@ -1,37 +1,81 @@
+/**
+ * Interaction Kit: compile a single command protocol from field declarations.
+ *
+ * Place in the package: part of the `interaction` Kit. Parsing is synchronous and never
+ * executes a registered tool; it only validates the shape and applies an optional formatter.
+ *
+ * Exports: `defineCommand`, `compileCommands`, `commandSchema`, and the protocol types.
+ */
 import { pinCommandDefinition } from '../../utils/interaction-definition.js';
 import { assertion, booleanResult, synchronous } from '../../utils/synchronous.js';
 import { freezeSchema } from '../../utils/object.js';
 import { breakWhile } from '../../utils/rules.js';
 import { INTERACTION_CATEGORIES } from '../../structs/kits/interaction.js';
 function reason(error, value, args) {
-    return () => typeof error === 'function' ? error(value, ...args) : error ?? new TypeError('Invalid protocol value');
+    return () => typeof error === 'function'
+        ? error(value, ...args)
+        : (error ?? new TypeError('Invalid protocol value'));
 }
-/** Compile declarations once. Parsing is synchronous and never executes a registered tool. */
+/**
+ * Compile declarations once. Parsing is synchronous and never executes a registered tool.
+ *
+ * Two schemas are produced from one declaration: `modelJsonSchema` marks only fields the model
+ * must fill, while `inputJsonSchema` marks every required field. A discriminator, when present,
+ * is prepended as a required constant field.
+ *
+ * @param definition - Fields, discriminator, checks, tags, error wording and optional
+ *   formatter; predicates and formatters are bound to this object.
+ * @returns A frozen command with `keys`, `assert`, `parse` and the three schemas.
+ * @throws TypeError For an unknown category, a duplicate field or discriminator field, a check
+ *   that still uses the retired `condition`/`conditions` names, or a non-synchronous predicate.
+ */
 export function defineCommand(definition) {
     breakWhile(definition.category !== undefined && !INTERACTION_CATEGORIES.includes(definition.category), 'Invalid interaction category');
-    const fields = Object.fromEntries(Object.entries(fieldDefinitions(definition.fields)).map(([name, field]) => [name, {
+    const fields = Object.fromEntries(Object.entries(fieldDefinitions(definition.fields)).map(([name, field]) => [
+        name,
+        {
             jsonSchema: field.jsonSchema === undefined ? undefined : structuredClone(field.jsonSchema),
-            required: field.required, modelRequired: field.modelRequired, owned: field.owned,
-        }]));
+            required: field.required,
+            modelRequired: field.modelRequired,
+            owned: field.owned,
+        },
+    ]));
     for (const name of definition.ownedFields ?? []) {
         if (!Object.hasOwn(fields, name))
             Object.defineProperty(fields, name, { value: {}, enumerable: true });
     }
-    const discriminator = definition.discriminator && { field: definition.discriminator.field, value: definition.discriminator.value };
+    const discriminator = definition.discriminator && {
+        field: definition.discriminator.field,
+        value: definition.discriminator.value,
+    };
     breakWhile(discriminator && Object.hasOwn(fields, discriminator.field), 'Duplicate protocol discriminator field');
     const entries = [
-        ...(discriminator ? [[discriminator.field, { required: true, jsonSchema: { type: 'string', enum: [discriminator.value] } }]] : []),
+        ...(discriminator
+            ? [
+                [
+                    discriminator.field,
+                    { required: true, jsonSchema: { type: 'string', enum: [discriminator.value] } },
+                ],
+            ]
+            : []),
         ...Object.entries(fields),
     ];
-    const checks = (definition.checks ?? []).map(check => {
+    const checks = (definition.checks ?? []).map((check) => {
         if (!check || check.occur === undefined || 'condition' in check || 'conditions' in check)
             throw new TypeError('Protocol checks require occur');
         const bind = (predicate) => predicate?.bind(check);
-        if (typeof check.occur !== 'function' && (!Array.isArray(check.occur) || check.occur.some(predicate => typeof predicate !== 'function')))
+        if (typeof check.occur !== 'function' &&
+            (!Array.isArray(check.occur) ||
+                check.occur.some((predicate) => typeof predicate !== 'function')))
             throw new TypeError('Protocol occur requires a predicate or predicate array');
-        return Object.freeze({ occur: typeof check.occur === 'function' ? check.occur.bind(check) : Object.freeze(check.occur.map(predicate => predicate.bind(check))),
-            when: bind(check.when), error: typeof check.error === 'function' ? check.error.bind(check) : check.error,
-            tags: Object.freeze([...(check.tags ?? [])]) });
+        return Object.freeze({
+            occur: typeof check.occur === 'function'
+                ? check.occur.bind(check)
+                : Object.freeze(check.occur.map((predicate) => predicate.bind(check))),
+            when: bind(check.when),
+            error: typeof check.error === 'function' ? check.error.bind(check) : check.error,
+            tags: Object.freeze([...(check.tags ?? [])]),
+        });
     });
     const tags = [...(definition.tags ?? [])];
     const additionalProperties = definition.additionalProperties ?? false;
@@ -40,35 +84,57 @@ export function defineCommand(definition) {
     const refine = definition.refine?.bind(definition), format = definition.format?.bind(definition);
     const parameters = Object.fromEntries(Object.entries(fields).map(([name, field]) => [name, field.jsonSchema ?? {}]));
     const schema = {
-        type: 'object', properties: Object.fromEntries(entries.map(([name, field]) => [name, field.jsonSchema ?? {}])),
-        required: entries.filter(([, field]) => field.required && field.modelRequired !== false).map(([name]) => name),
+        type: 'object',
+        properties: Object.fromEntries(entries.map(([name, field]) => [name, field.jsonSchema ?? {}])),
+        required: entries
+            .filter(([, field]) => field.required && field.modelRequired !== false)
+            .map(([name]) => name),
         additionalProperties,
     };
-    const inputJsonSchema = { ...schema, required: entries.filter(([, field]) => field.required).map(([name]) => name) };
+    const inputJsonSchema = {
+        ...schema,
+        required: entries.filter(([, field]) => field.required).map(([name]) => name),
+    };
     freezeSchema(inputJsonSchema);
     freezeSchema(fields);
     freezeSchema(parameters);
     freezeSchema(schema);
-    const keys = (value) => entries.filter(([name, field]) => field.required || (optionalPresence === 'defined' ? value[name] !== undefined : Object.hasOwn(value, name))).map(([name]) => name);
+    const keys = (value) => entries
+        .filter(([name, field]) => field.required ||
+        (optionalPresence === 'defined' ? value[name] !== undefined : Object.hasOwn(value, name)))
+        .map(([name]) => name);
     const validate = (value, ...args) => {
         const fail = reason(error, value, args);
         breakWhile(!value || typeof value !== 'object' || Array.isArray(value), fail, tags);
         const record = value;
         const expected = keys(record);
         breakWhile([
-            { occur: () => expected.some(name => !Object.hasOwn(record, name)), error: fail, tags: ['required-fields'] },
             {
-                occur: () => !additionalProperties && Object.keys(record).some(name => !expected.includes(name)),
-                error: fail, tags: ['unknown-fields'],
+                occur: () => expected.some((name) => !Object.hasOwn(record, name)),
+                error: fail,
+                tags: ['required-fields'],
+            },
+            {
+                occur: () => !additionalProperties && Object.keys(record).some((name) => !expected.includes(name)),
+                error: fail,
+                tags: ['unknown-fields'],
+            },
+            {
+                occur: () => discriminator && record[discriminator.field] !== discriminator.value,
+                error: fail,
+                tags: ['discriminator'],
             },
-            { occur: () => discriminator && record[discriminator.field] !== discriminator.value, error: fail, tags: ['discriminator'] },
-            ...checks.map(check => ({
+            ...checks.map((check) => ({
                 occur: () => {
-                    if (check.when && !booleanResult(check.when(value, ...args), 'Protocol when predicates must return boolean synchronously'))
+                    if (check.when &&
+                        !booleanResult(check.when(value, ...args), 'Protocol when predicates must return boolean synchronously'))
                         return false;
-                    return typeof check.occur === 'function' ? synchronous(check.occur(value, ...args), 'Protocol occur predicates must be synchronous') : check.occur.some(occur => synchronous(occur(value, ...args), 'Protocol occur predicates must be synchronous'));
+                    return typeof check.occur === 'function'
+                        ? synchronous(check.occur(value, ...args), 'Protocol occur predicates must be synchronous')
+                        : check.occur.some((occur) => synchronous(occur(value, ...args), 'Protocol occur predicates must be synchronous'));
                 },
-                error: reason(check.error ?? error, value, args), tags: check.tags,
+                error: reason(check.error ?? error, value, args),
+                tags: check.tags,
             })),
         ], tags);
         assertion(refine?.(value, ...args), 'Protocol refinements must return void synchronously');
@@ -78,14 +144,25 @@ export function defineCommand(definition) {
         ...(definition.version !== undefined ? { version: definition.version } : {}),
         ...(definition.description !== undefined ? { description: definition.description } : {}),
         ...(definition.terminal !== undefined ? { terminal: definition.terminal } : {}),
-        fieldSchemas: parameters, modelJsonSchema: schema, inputJsonSchema, keys, assert: validate,
+        fieldSchemas: parameters,
+        modelJsonSchema: schema,
+        inputJsonSchema,
+        keys,
+        assert: validate,
         modes: definition.modes && Object.freeze([...definition.modes]),
-        ownedFields: Object.freeze([...new Set([
-                ...(definition.ownedFields ?? []), ...Object.entries(fields).filter(([, field]) => field.owned).map(([name]) => name),
-            ])]),
+        ownedFields: Object.freeze([
+            ...new Set([
+                ...(definition.ownedFields ?? []),
+                ...Object.entries(fields)
+                    .filter(([, field]) => field.owned)
+                    .map(([name]) => name),
+            ]),
+        ]),
         parse(value, ...args) {
             validate(value, ...args);
-            return format ? synchronous(format(value, ...args), 'Protocol formatters must be synchronous') : value;
+            return format
+                ? synchronous(format(value, ...args), 'Protocol formatters must be synchronous')
+                : value;
         },
     });
 }
@@ -93,9 +170,20 @@ function fieldDefinitions(fields) {
     if (!Array.isArray(fields))
         return fields;
     breakWhile(new Set(fields).size !== fields.length, 'Duplicate protocol field');
-    return Object.fromEntries(fields.map(name => [name, {}]));
+    return Object.fromEntries(fields.map((name) => [name, {}]));
 }
-/** Install an entire catalog with shared envelope fields; applications declare data and handlers only. */
+/**
+ * Compile a whole catalog with shared envelope fields.
+ *
+ * Applications declare only their own data and handlers. Defaults are merged in this order:
+ * unrelated default keys, then the command's own keys, with `fields`, `checks` and `tags`
+ * concatenated so shared envelope checks always run before per-command checks.
+ *
+ * @param definitions - Commands keyed by their wire id.
+ * @param defaults - Shared envelope definition; its discriminator field is removed per command.
+ * @returns A frozen record from id to compiled command.
+ * @throws TypeError From `defineCommand` for the first invalid declaration.
+ */
 export function compileCommands(definitions, defaults = {}) {
     defaults = pinCommandDefinition(defaults);
     return Object.freeze(Object.fromEntries(Object.entries(definitions).map(([id, value]) => {
@@ -103,20 +191,36 @@ export function compileCommands(definitions, defaults = {}) {
         const envelopeFields = { ...fieldDefinitions(defaults.fields ?? {}) };
         if (definition.discriminator)
             delete envelopeFields[definition.discriminator.field];
-        return [id, defineCommand({
-                ...defaults, ...definition,
+        return [
+            id,
+            defineCommand({
+                ...defaults,
+                ...definition,
                 fields: { ...envelopeFields, ...fieldDefinitions(definition.fields) },
                 checks: [...(defaults.checks ?? []), ...(definition.checks ?? [])],
                 tags: [...(defaults.tags ?? []), ...(definition.tags ?? [])],
-            })];
+            }),
+        ];
     })));
 }
-/** Prefer compiled schemas; retain the existing open-schema contract for dynamic host protocols. */
+/**
+ * Build a JSON schema for one command id.
+ *
+ * Prefer compiled schemas; retain the existing open-schema contract for dynamic host protocols.
+ * A protocol without `fieldSchemas` falls back to an open object that only pins the
+ * discriminator, which keeps legacy hosts working without weakening compiled ones.
+ *
+ * @param id - Command id used as the discriminator value.
+ * @param protocol - Compiled command, or a shape carrying only `fieldSchemas`/`keys`.
+ * @param discriminator - Field name carrying the command id; defaults to `type`.
+ * @returns The compiled model schema, or a generated open schema.
+ */
 export function commandSchema(id, protocol, discriminator = 'type') {
     if (protocol.modelJsonSchema)
         return protocol.modelJsonSchema;
     return {
-        type: 'object', properties: { [discriminator]: { type: 'string', enum: [id] }, ...protocol.fieldSchemas },
+        type: 'object',
+        properties: { [discriminator]: { type: 'string', enum: [id] }, ...protocol.fieldSchemas },
         required: protocol.fieldSchemas ? protocol.keys({ [discriminator]: id }) : [discriminator],
         additionalProperties: !protocol.fieldSchemas,
     };

package/dist/esm/kits/interaction/commands.d.ts

@@ -1,26 +1,90 @@
+/**
+ * Interaction Kit: the sealed command catalog shared by every receiving host.
+ *
+ * Place in the package: part of the `interaction` Kit. It owns mode checks and cross-protocol
+ * field-ownership checks that every host must apply identically; the commands themselves are
+ * compiled elsewhere.
+ *
+ * Exports: `CommandCatalog`, `defineCommandCatalog`, and `CommandCatalogOptions`.
+ */
 import type { Command, CommandDefinition, CommandCatalogOptions, InteractionCategory, InteractionDescriptor } from '../../structs/kits/interaction.js';
 import { ProtocolRegistry } from '../../utils/protocol-registry.js';
 import { compileCommands } from './command.js';
-/** Mode and cross-protocol field ownership checks are shared by all receiving hosts. */
+/**
+ * Mode and cross-protocol field ownership checks are shared by all receiving hosts.
+ *
+ * The catalog seals itself as soon as construction finishes, so a run cannot register a new
+ * command later; `set` remains available only for the superclass installation pass.
+ */
 export declare class CommandCatalog<Value extends object = Record<string, unknown>, Result = Value, Args extends unknown[] = [], Id extends string = string> extends ProtocolRegistry<Command<Value, Result, Args> & {
     readonly id: Id;
 }> {
+    /** Compile and construct a catalog from definitions in one call. */
     static readonly define: typeof defineCommandCatalog;
+    /** Compile a set of definitions with shared envelope fields. */
     static readonly compile: typeof compileCommands;
     private sealed;
     private readonly options;
+    /**
+     * @param definitions - Compiled `[id, command]` pairs, installed in iteration order.
+     * @param options - Mode field, error wording and diagnostic tags used by `parse`.
+     */
     constructor(definitions: Iterable<readonly [Id, Command<Value, Result, Args>]>, options?: CommandCatalogOptions);
+    /**
+     * Install one compiled command during construction.
+     *
+     * @throws Error When the id already exists or construction has finished.
+     */
     set(id: string, command: Command<Value, Result, Args>): this;
+    /**
+     * Removal is not supported.
+     *
+     * @throws Error Always, because the catalog is sealed.
+     */
     delete(_id: string): boolean;
+    /**
+     * Clearing is not supported.
+     *
+     * @throws Error Always, because the catalog is sealed.
+     */
     clear(): void;
+    /** Compiled commands in registration order. */
     get definitions(): readonly Readonly<Command<Value, Result, Args> & {
         id: Id;
     }>[];
     /** Explicit dictionary projection; definitions always remains an ordered array. */
     toRecord(): Readonly<Record<Id, Command<Value, Result, Args>>>;
-    /** The same declarations drive purpose-specific menus, documentation and handler binding. */
+    /**
+     * The same declarations drive purpose-specific menus, documentation and handler binding.
+     *
+     * @param category - Restrict to one interaction category; omit for every command.
+     * @returns Plain descriptors in registration order, without schemas or handlers.
+     */
     manifest(category?: InteractionCategory): readonly InteractionDescriptor[];
+    /**
+     * Validate and parse one payload as the named command.
+     *
+     * Checks run before the command's own parser: the id must exist, the mode (when configured)
+     * must be allowed, and no other command may claim a field that this payload sets. The last
+     * rule prevents one command from silently consuming another command's data.
+     *
+     * @param id - Command id selected by the caller.
+     * @param value - Raw payload.
+     * @param args - Extra arguments forwarded to the command parser.
+     * @returns The parsed result for that command.
+     * @throws A configured error for an unknown command, a disallowed mode or a field owned by
+     *   another command; the command's own error for a shape violation.
+     */
     parse(id: string, value: Value, ...args: Args): Result;
 }
+/**
+ * Compile definitions and wrap them in a sealed catalog.
+ *
+ * @param definitions - Command definitions keyed by wire id.
+ * @param defaults - Shared envelope definition merged into every command.
+ * @param options - Mode field, error wording and diagnostic tags.
+ * @returns A sealed catalog ready for `manifest`, `parse` and handler binding.
+ * @throws TypeError From compilation for the first invalid definition.
+ */
 export declare function defineCommandCatalog<Value extends object, Result = Value, Args extends unknown[] = [], Id extends string = string>(definitions: Readonly<Record<Id, CommandDefinition<Value, Result, Args>>>, defaults?: Partial<CommandDefinition<Value, Result, Args>>, options?: CommandCatalogOptions): CommandCatalog<Value, Result, Args, Id>;
 export type { CommandCatalogOptions } from '../../structs/kits/interaction.js';

package/dist/esm/kits/interaction/commands.js

@@ -1,30 +1,73 @@
 import { breakWhile } from '../../utils/rules.js';
 import { ProtocolRegistry } from '../../utils/protocol-registry.js';
 import { compileCommands } from './command.js';
-/** Mode and cross-protocol field ownership checks are shared by all receiving hosts. */
+/**
+ * Mode and cross-protocol field ownership checks are shared by all receiving hosts.
+ *
+ * The catalog seals itself as soon as construction finishes, so a run cannot register a new
+ * command later; `set` remains available only for the superclass installation pass.
+ */
 export class CommandCatalog extends ProtocolRegistry {
+    /** Compile and construct a catalog from definitions in one call. */
     static define = defineCommandCatalog;
+    /** Compile a set of definitions with shared envelope fields. */
     static compile = compileCommands;
     sealed = false;
     options;
+    /**
+     * @param definitions - Compiled `[id, command]` pairs, installed in iteration order.
+     * @param options - Mode field, error wording and diagnostic tags used by `parse`.
+     */
     constructor(definitions, options = {}) {
         // Map installation calls this class's set, which normalizes each registered identity.
         super(definitions);
         this.options = Object.freeze({ ...options, tags: Object.freeze([...(options.tags ?? [])]) });
         this.sealed = true;
     }
+    /**
+     * Install one compiled command during construction.
+     *
+     * @throws Error When the id already exists or construction has finished.
+     */
     set(id, command) {
         if (this.has(id))
             throw new Error(`Duplicate protocol: ${id}`);
         if (this.sealed)
             throw new Error('Command catalog is sealed');
-        return super.set(id, Object.freeze({ ...command, id: id, fieldSchemas: command.fieldSchemas, modelJsonSchema: command.modelJsonSchema, inputJsonSchema: command.inputJsonSchema,
-            category: command.category, version: command.version, description: command.description, terminal: command.terminal,
-            modes: command.modes && Object.freeze([...command.modes]), ownedFields: Object.freeze([...command.ownedFields]),
-            keys: command.keys.bind(command), assert: command.assert.bind(command), parse: command.parse.bind(command) }));
+        return super.set(id, Object.freeze({
+            ...command,
+            id: id,
+            fieldSchemas: command.fieldSchemas,
+            modelJsonSchema: command.modelJsonSchema,
+            inputJsonSchema: command.inputJsonSchema,
+            category: command.category,
+            version: command.version,
+            description: command.description,
+            terminal: command.terminal,
+            modes: command.modes && Object.freeze([...command.modes]),
+            ownedFields: Object.freeze([...command.ownedFields]),
+            keys: command.keys.bind(command),
+            assert: command.assert.bind(command),
+            parse: command.parse.bind(command),
+        }));
     }
-    delete(_id) { throw new Error('Command catalog is sealed'); }
-    clear() { throw new Error('Command catalog is sealed'); }
+    /**
+     * Removal is not supported.
+     *
+     * @throws Error Always, because the catalog is sealed.
+     */
+    delete(_id) {
+        throw new Error('Command catalog is sealed');
+    }
+    /**
+     * Clearing is not supported.
+     *
+     * @throws Error Always, because the catalog is sealed.
+     */
+    clear() {
+        throw new Error('Command catalog is sealed');
+    }
+    /** Compiled commands in registration order. */
     get definitions() {
         return Object.freeze([...this.values()]);
     }
@@ -32,24 +75,56 @@ export class CommandCatalog extends ProtocolRegistry {
     toRecord() {
         return Object.freeze(Object.fromEntries(this));
     }
-    /** The same declarations drive purpose-specific menus, documentation and handler binding. */
+    /**
+     * The same declarations drive purpose-specific menus, documentation and handler binding.
+     *
+     * @param category - Restrict to one interaction category; omit for every command.
+     * @returns Plain descriptors in registration order, without schemas or handlers.
+     */
     manifest(category) {
-        return Object.freeze([...this].filter(([, command]) => category === undefined || command.category === category)
+        return Object.freeze([...this]
+            .filter(([, command]) => category === undefined || command.category === category)
             .map(([id, { category, description, terminal, modes }]) => Object.freeze({ id, category, description, terminal, modes })));
     }
+    /**
+     * Validate and parse one payload as the named command.
+     *
+     * Checks run before the command's own parser: the id must exist, the mode (when configured)
+     * must be allowed, and no other command may claim a field that this payload sets. The last
+     * rule prevents one command from silently consuming another command's data.
+     *
+     * @param id - Command id selected by the caller.
+     * @param value - Raw payload.
+     * @param args - Extra arguments forwarded to the command parser.
+     * @returns The parsed result for that command.
+     * @throws A configured error for an unknown command, a disallowed mode or a field owned by
+     *   another command; the command's own error for a shape violation.
+     */
     parse(id, value, ...args) {
         const protocol = this.get(id);
-        breakWhile(!protocol, this.options.unknownError ?? 'Unknown command', [...this.options.tags, 'command-selection']);
+        breakWhile(!protocol, this.options.unknownError ?? 'Unknown command', [
+            ...this.options.tags,
+            'command-selection',
+        ]);
         const record = value;
         const modeField = this.options.modeField;
         breakWhile(modeField && !protocol.modes?.includes(record?.[modeField]), this.options.modeError ?? 'Unsupported command mode', [...this.options.tags, 'command-mode']);
         const ownershipTags = [...this.options.tags, 'field-ownership'];
         for (const [owner, other] of this) {
-            breakWhile(owner !== id && other.ownedFields.some(field => record?.[field] !== undefined), this.options.ownershipError ?? 'Field belongs to another command', ownershipTags);
+            breakWhile(owner !== id && other.ownedFields.some((field) => record?.[field] !== undefined), this.options.ownershipError ?? 'Field belongs to another command', ownershipTags);
         }
         return protocol.parse(value, ...args);
     }
 }
+/**
+ * Compile definitions and wrap them in a sealed catalog.
+ *
+ * @param definitions - Command definitions keyed by wire id.
+ * @param defaults - Shared envelope definition merged into every command.
+ * @param options - Mode field, error wording and diagnostic tags.
+ * @returns A sealed catalog ready for `manifest`, `parse` and handler binding.
+ * @throws TypeError From compilation for the first invalid definition.
+ */
 export function defineCommandCatalog(definitions, defaults = {}, options = {}) {
     const compiled = compileCommands(definitions, defaults);
     return new CommandCatalog(Object.entries(compiled), options);

package/dist/esm/kits/interaction/handlers.d.ts

@@ -1,6 +1,23 @@
+/**
+ * Interaction Kit: bind every registered command to a local handler.
+ *
+ * Place in the package: part of the `interaction` Kit. The handler table is App code; this
+ * module checks it is exhaustive, rejects unknown keys and dispatches on the validated wire
+ * value rather than on any formatter output.
+ *
+ * Exports: `bindInteraction`, and the interaction category/descriptor/handler types.
+ */
 import type { InteractionHandlers } from '../../structs/kits/interaction.js';
 import type { InteractionProtocol } from './transfer.js';
-/** Bind every registered transfer command to a local handler. Models cannot add handlers. */
+/**
+ * Bind every registered transfer command to a local handler. Models cannot add handlers.
+ *
+ * @param protocol - Object exposing the command manifest and a `receive` entry point.
+ * @param handlers - One handler per command id, bound to this handlers object.
+ * @returns A frozen `{ catalog, dispatch }`; `dispatch` selects by the validated command id.
+ * @throws A configured error when a handler is missing (including prototype members such as
+ *   `constructor` that were never assigned) or when the table contains an unregistered id.
+ */
 export declare function bindInteraction<Value extends object, Parsed, Args extends unknown[], Id extends string, Context, Output>(protocol: {
     readonly commands: Pick<InteractionProtocol<Value, Parsed, Args, Id>['commands'], 'manifest'>;
     receive(value: Value, ...args: Args): {
@@ -17,5 +34,5 @@ export declare function bindInteraction<Value extends object, Parsed, Args exten
     }>[];
     dispatch(value: Value, context: Context, ...args: Args): Output;
 }>;
-export type { InteractionCategory, InteractionDescriptor, InteractionHandlers } from '../../structs/kits/interaction.js';
+export type { InteractionCategory, InteractionDescriptor, InteractionHandlers, } from '../../structs/kits/interaction.js';
 export { INTERACTION_CATEGORIES } from '../../structs/kits/interaction.js';

package/dist/esm/kits/interaction/handlers.js

@@ -1,22 +1,39 @@
 import { breakWhile } from '../../utils/rules.js';
-/** Bind every registered transfer command to a local handler. Models cannot add handlers. */
+/**
+ * Bind every registered transfer command to a local handler. Models cannot add handlers.
+ *
+ * @param protocol - Object exposing the command manifest and a `receive` entry point.
+ * @param handlers - One handler per command id, bound to this handlers object.
+ * @returns A frozen `{ catalog, dispatch }`; `dispatch` selects by the validated command id.
+ * @throws A configured error when a handler is missing (including prototype members such as
+ *   `constructor` that were never assigned) or when the table contains an unregistered id.
+ */
 export function bindInteraction(protocol, handlers) {
-    const catalog = Object.freeze(protocol.commands.manifest().map(command => Object.freeze({
-        id: command.id, category: command.category, description: command.description, terminal: command.terminal,
+    const catalog = Object.freeze(protocol.commands.manifest().map((command) => Object.freeze({
+        id: command.id,
+        category: command.category,
+        description: command.description,
+        terminal: command.terminal,
         modes: command.modes && Object.freeze([...command.modes]),
     })));
     const receive = protocol.receive.bind(protocol);
-    const ids = new Set(catalog.map(command => command.id));
+    const ids = new Set(catalog.map((command) => command.id));
     breakWhile([
         {
-            occur: () => catalog.some(command => typeof handlers[command.id] !== 'function' || (!Object.hasOwn(handlers, command.id) && (command.id === 'constructor' || handlers[command.id] === Reflect.get(Object.prototype, command.id)))),
-            error: 'Missing interaction handler', tags: ['missing-handler'],
+            occur: () => catalog.some((command) => typeof handlers[command.id] !== 'function' ||
+                (!Object.hasOwn(handlers, command.id) &&
+                    (command.id === 'constructor' ||
+                        handlers[command.id] === Reflect.get(Object.prototype, command.id)))),
+            error: 'Missing interaction handler',
+            tags: ['missing-handler'],
+        },
+        {
+            occur: () => Object.keys(handlers).some((id) => !ids.has(id)),
+            error: 'Unregistered interaction handler',
+            tags: ['unknown-handler'],
         },
-        { occur: () => Object.keys(handlers).some(id => !ids.has(id)), error: 'Unregistered interaction handler', tags: ['unknown-handler'] },
     ], ['agent-core', 'interaction-registration']);
-    const registered = Object.freeze(Object.fromEntries(catalog.map(({ id }) => [id,
-        handlers[id].bind(handlers),
-    ])));
+    const registered = Object.freeze(Object.fromEntries(catalog.map(({ id }) => [id, handlers[id].bind(handlers)])));
     return Object.freeze({
         catalog,
         dispatch(value, context, ...args) {

package/dist/esm/kits/interaction/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Interaction Kit entry: command protocols, their catalog and local handler binding.
+ *
+ * Place in the package: an optional App-side library for the payload family exchanged between
+ * a web or AI client and the App. Framing, transport and the actual command execution stay
+ * outside; this directory validates shapes, routes on a discriminator and binds handlers.
+ *
+ * Exports: everything from `./command.js`, `./commands.js`, `./transfer.js` and
+ * `./handlers.js`, plus `InteractionProtocol` re-exported as `Interaction`.
+ */
 export * from './command.js';
 export * from './commands.js';
 export * from './transfer.js';

package/dist/esm/kits/interaction/index.js

@@ -1,3 +1,13 @@
+/**
+ * Interaction Kit entry: command protocols, their catalog and local handler binding.
+ *
+ * Place in the package: an optional App-side library for the payload family exchanged between
+ * a web or AI client and the App. Framing, transport and the actual command execution stay
+ * outside; this directory validates shapes, routes on a discriminator and binds handlers.
+ *
+ * Exports: everything from `./command.js`, `./commands.js`, `./transfer.js` and
+ * `./handlers.js`, plus `InteractionProtocol` re-exported as `Interaction`.
+ */
 export * from './command.js';
 export * from './commands.js';
 export * from './transfer.js';