@jangts/agent-core 0.1.1 → 0.2.1

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

@@ -3,40 +3,84 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineCommand = defineCommand;
 exports.compileCommands = compileCommands;
 exports.commandSchema = commandSchema;
+/**
+ * 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.
+ */
 const interaction_definition_js_1 = require("../../utils/interaction-definition.js");
 const synchronous_js_1 = require("../../utils/synchronous.js");
 const object_js_1 = require("../../utils/object.js");
 const rules_js_1 = require("../../utils/rules.js");
 const interaction_js_1 = require("../../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.
+ */
 function defineCommand(definition) {
     (0, rules_js_1.breakWhile)(definition.category !== undefined && !interaction_js_1.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,
+    };
     (0, rules_js_1.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;
@@ -45,35 +89,57 @@ 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),
+    };
     (0, object_js_1.freezeSchema)(inputJsonSchema);
     (0, object_js_1.freezeSchema)(fields);
     (0, object_js_1.freezeSchema)(parameters);
     (0, object_js_1.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);
         (0, rules_js_1.breakWhile)(!value || typeof value !== 'object' || Array.isArray(value), fail, tags);
         const record = value;
         const expected = keys(record);
         (0, rules_js_1.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 && !(0, synchronous_js_1.booleanResult)(check.when(value, ...args), 'Protocol when predicates must return boolean synchronously'))
+                    if (check.when &&
+                        !(0, synchronous_js_1.booleanResult)(check.when(value, ...args), 'Protocol when predicates must return boolean synchronously'))
                         return false;
-                    return typeof check.occur === 'function' ? (0, synchronous_js_1.synchronous)(check.occur(value, ...args), 'Protocol occur predicates must be synchronous') : check.occur.some(occur => (0, synchronous_js_1.synchronous)(occur(value, ...args), 'Protocol occur predicates must be synchronous'));
+                    return typeof check.occur === 'function'
+                        ? (0, synchronous_js_1.synchronous)(check.occur(value, ...args), 'Protocol occur predicates must be synchronous')
+                        : check.occur.some((occur) => (0, synchronous_js_1.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);
         (0, synchronous_js_1.assertion)(refine?.(value, ...args), 'Protocol refinements must return void synchronously');
@@ -83,14 +149,25 @@ 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 ? (0, synchronous_js_1.synchronous)(format(value, ...args), 'Protocol formatters must be synchronous') : value;
+            return format
+                ? (0, synchronous_js_1.synchronous)(format(value, ...args), 'Protocol formatters must be synchronous')
+                : value;
         },
     });
 }
@@ -98,9 +175,20 @@ function fieldDefinitions(fields) {
     if (!Array.isArray(fields))
         return fields;
     (0, rules_js_1.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.
+ */
 function compileCommands(definitions, defaults = {}) {
     defaults = (0, interaction_definition_js_1.pinCommandDefinition)(defaults);
     return Object.freeze(Object.fromEntries(Object.entries(definitions).map(([id, value]) => {
@@ -108,20 +196,36 @@ 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.
+ */
 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/cjs/kits/interaction/commands.js

@@ -5,30 +5,73 @@ exports.defineCommandCatalog = defineCommandCatalog;
 const rules_js_1 = require("../../utils/rules.js");
 const protocol_registry_js_1 = require("../../utils/protocol-registry.js");
 const command_js_1 = require("./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.
+ */
 class CommandCatalog extends protocol_registry_js_1.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 = command_js_1.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()]);
     }
@@ -36,25 +79,57 @@ class CommandCatalog extends protocol_registry_js_1.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);
-        (0, rules_js_1.breakWhile)(!protocol, this.options.unknownError ?? 'Unknown command', [...this.options.tags, 'command-selection']);
+        (0, rules_js_1.breakWhile)(!protocol, this.options.unknownError ?? 'Unknown command', [
+            ...this.options.tags,
+            'command-selection',
+        ]);
         const record = value;
         const modeField = this.options.modeField;
         (0, rules_js_1.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) {
-            (0, rules_js_1.breakWhile)(owner !== id && other.ownedFields.some(field => record?.[field] !== undefined), this.options.ownershipError ?? 'Field belongs to another command', ownershipTags);
+            (0, rules_js_1.breakWhile)(owner !== id && other.ownedFields.some((field) => record?.[field] !== undefined), this.options.ownershipError ?? 'Field belongs to another command', ownershipTags);
         }
         return protocol.parse(value, ...args);
     }
 }
 exports.CommandCatalog = CommandCatalog;
+/**
+ * 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.
+ */
 function defineCommandCatalog(definitions, defaults = {}, options = {}) {
     const compiled = (0, command_js_1.compileCommands)(definitions, defaults);
     return new CommandCatalog(Object.entries(compiled), options);

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

@@ -3,24 +3,41 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.INTERACTION_CATEGORIES = void 0;
 exports.bindInteraction = bindInteraction;
 const rules_js_1 = require("../../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.
+ */
 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));
     (0, rules_js_1.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/cjs/kits/interaction/index.js

@@ -15,6 +15,16 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Interaction = void 0;
+/**
+ * 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`.
+ */
 __exportStar(require("./command.js"), exports);
 __exportStar(require("./commands.js"), exports);
 __exportStar(require("./transfer.js"), exports);

package/dist/cjs/kits/interaction/transfer.js

@@ -2,13 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InteractionProtocol = void 0;
 exports.defineInteractionProtocol = defineInteractionProtocol;
+/**
+ * Interaction Kit: the web/AI payload family with selector normalization.
+ *
+ * Place in the package: part of the `interaction` Kit and its main entry. HTTP/SSE framing and
+ * the actual command execution remain separate ports; this class only validates the envelope,
+ * accepts selector aliases and delegates parsing to the sealed command catalog.
+ *
+ * Exports: `InteractionProtocol`, `defineInteractionProtocol`, and its definition type.
+ */
 const interaction_definition_js_1 = require("../../utils/interaction-definition.js");
 const rules_js_1 = require("../../utils/rules.js");
 const commands_js_1 = require("./commands.js");
 const command_js_1 = require("./command.js");
 const handlers_js_1 = require("./handlers.js");
 const interaction_js_1 = require("../../structs/kits/interaction.js");
-/** Web/AI payload family. HTTP/SSE framing and actual command execution remain separate ports. */
+/**
+ * Web/AI payload family. HTTP/SSE framing and actual command execution remain separate ports.
+ *
+ * Every command registered here gets the envelope's discriminator forced to its own id, so a
+ * payload cannot claim one command while carrying another command's data.
+ */
 class InteractionProtocol {
     static define = defineInteractionProtocol;
     static Commands = commands_js_1.CommandCatalog;
@@ -16,39 +30,79 @@ class InteractionProtocol {
     static commandSchema = command_js_1.commandSchema;
     static bind = handlers_js_1.bindInteraction;
     static categories = interaction_js_1.INTERACTION_CATEGORIES;
+    /** Field carrying the command id in a payload. */
     commandField;
+    /** Accepted selector names: the command field first, then any declared aliases. */
     commandSelectors;
+    /** Sealed catalog of the compiled commands. */
     commands;
     selectionError;
+    /**
+     * @param definition - Command definitions plus envelope, selector aliases and error wording.
+     * @throws An error for a blank or duplicate selector, a conflicting per-command discriminator
+     *   (it must match the envelope field and the command's own id).
+     */
     constructor(definition) {
-        const { commands, commandField, commandAliases, modeField, unknownError, modeError, ownershipError } = definition;
+        const { commands, commandField, commandAliases, modeField, unknownError, modeError, ownershipError, } = definition;
         const { discriminator: _discriminator, modes: _modes, ownedFields: _ownedFields, ...envelope } = (0, interaction_definition_js_1.pinCommandDefinition)(definition);
-        const selectionError = typeof definition.selectionError === 'function' ? definition.selectionError.bind(definition) : definition.selectionError;
+        const selectionError = typeof definition.selectionError === 'function'
+            ? definition.selectionError.bind(definition)
+            : definition.selectionError;
         (0, rules_js_1.breakWhile)(!commandField.trim(), 'Missing transfer command field');
         this.commandField = commandField;
         this.commandSelectors = Object.freeze([commandField, ...(commandAliases ?? [])]);
         (0, rules_js_1.breakWhile)([
-            { occur: () => this.commandSelectors.some(field => !field.trim()), error: 'Missing transfer selector' },
-            { occur: () => new Set(this.commandSelectors).size !== this.commandSelectors.length, error: 'Duplicate transfer selector' },
+            {
+                occur: () => this.commandSelectors.some((field) => !field.trim()),
+                error: 'Missing transfer selector',
+            },
+            {
+                occur: () => new Set(this.commandSelectors).size !== this.commandSelectors.length,
+                error: 'Duplicate transfer selector',
+            },
         ]);
         this.selectionError = selectionError;
         const registered = Object.fromEntries(Object.entries(commands).map(([id, value]) => {
             const command = (0, interaction_definition_js_1.pinCommandDefinition)(value);
-            (0, rules_js_1.breakWhile)(command.discriminator && (command.discriminator.field !== commandField || command.discriminator.value !== id), 'Conflicting transfer command discriminator');
+            (0, rules_js_1.breakWhile)(command.discriminator &&
+                (command.discriminator.field !== commandField || command.discriminator.value !== id), 'Conflicting transfer command discriminator');
             return [id, { ...command, discriminator: { field: commandField, value: id } }];
         }));
         this.commands = (0, commands_js_1.defineCommandCatalog)(registered, envelope, {
-            modeField, unknownError, modeError, ownershipError, tags: envelope.tags,
+            modeField,
+            unknownError,
+            modeError,
+            ownershipError,
+            tags: envelope.tags,
         });
     }
+    /** JSON schema for the model, expressed as a union of the per-command schemas. */
     get modelJsonSchema() {
-        return { anyOf: [...this.commands.values()].map(command => command.modelJsonSchema) };
+        return { anyOf: [...this.commands.values()].map((command) => command.modelJsonSchema) };
     }
-    get inputJsonSchema() { return { anyOf: [...this.commands.values()].map(command => command.inputJsonSchema) }; }
+    /** Strict JSON schema for transport input, expressed as a union of per-command schemas. */
+    get inputJsonSchema() {
+        return { anyOf: [...this.commands.values()].map((command) => command.inputJsonSchema) };
+    }
+    /**
+     * Parse a payload and return only the result.
+     *
+     * @param value - Raw payload.
+     * @param args - Extra arguments forwarded to the command parser.
+     * @throws The same errors as `receive`.
+     */
     parse(value, ...args) {
         return this.receive(value, ...args).result;
     }
-    /** Retain the selected command separately from a formatter's output. */
+    /**
+     * Retain the selected command id separately from a formatter's output.
+     *
+     * @param value - Raw payload; aliases are normalized when more than one selector is allowed.
+     * @param args - Extra arguments forwarded to the command parser.
+     * @returns The selected command id and its parsed result.
+     * @throws A configured error for a malformed or ambiguous selector, or the catalog's
+     *   command/mode/ownership errors.
+     */
     receive(value, ...args) {
         const normalized = this.normalizeSelector(value, args);
         const id = normalized[this.commandField];
@@ -58,14 +112,19 @@ class InteractionProtocol {
         // Preserve the original no-alias parsing path; alias handling is an explicit host choice.
         if (this.commandSelectors.length === 1)
             return value;
-        const fail = () => typeof this.selectionError === 'function' ? this.selectionError(value, ...args)
-            : this.selectionError ?? new TypeError('Invalid transfer selector');
+        const fail = () => typeof this.selectionError === 'function'
+            ? this.selectionError(value, ...args)
+            : (this.selectionError ?? new TypeError('Invalid transfer selector'));
         (0, rules_js_1.breakWhile)(!value || typeof value !== 'object' || Array.isArray(value), fail);
         const record = value;
-        const selectors = this.commandSelectors.filter(field => Object.hasOwn(record, field));
+        const selectors = this.commandSelectors.filter((field) => Object.hasOwn(record, field));
         (0, rules_js_1.breakWhile)([
             { occur: () => selectors.length !== 1, error: fail, tags: ['selector-count'] },
-            { occur: () => typeof record[selectors[0]] !== 'string', error: fail, tags: ['selector-value'] },
+            {
+                occur: () => typeof record[selectors[0]] !== 'string',
+                error: fail,
+                tags: ['selector-value'],
+            },
         ]);
         const normalized = { ...record, [this.commandField]: record[selectors[0]] };
         if (selectors[0] !== this.commandField)
@@ -74,6 +133,13 @@ class InteractionProtocol {
     }
 }
 exports.InteractionProtocol = InteractionProtocol;
+/**
+ * Construct a protocol from one definition.
+ *
+ * @param definition - Commands, envelope and selector configuration.
+ * @returns A new protocol instance.
+ * @throws The same errors as the constructor.
+ */
 function defineInteractionProtocol(definition) {
     return new InteractionProtocol(definition);
 }