@qilin-agent/commands 0.0.0-stage → 3.1.3

package/lib/types/index.js

@@ -0,0 +1,462 @@
+/**
+ * Plugin-owned human-command registry shared by interactive UI adapters.
+ * @module @qilin-agent/commands
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { randomUUID } from '@qilin-agent/util-crypto';
+import { AttachmentError, admitEncodedImages } from '@qilin-agent/attachment';
+import { NamedEntries, ScopedLayers } from '@qilin-agent/scope';
+import { SessionSeq } from '@qilin-agent/session';
+import { TypertRemoteService, Remote } from '@qilin-agent/typert-protocol';
+import { CommandId } from "./brand.js";
+export { CommandDefinitionId, CommandId } from "./brand.js";
+export const name = 'commands';
+const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/u;
+/** Shared frozen attachments value for attachment-free invocations. */
+const NO_ATTACHMENTS = Object.freeze([]);
+/** All command registrations owned by one global or scoped layer. */
+class CommandLayer {
+    commands;
+    /**
+     * Create one command layer with diagnostics specific to its ownership scope.
+     * @param scope - the scoped owner, or `undefined` for global registrations.
+     */
+    constructor(scope) {
+        this.commands = new NamedEntries(name => new Error(scope === undefined
+            ? `command "${name}" is already registered (for a per-agent variant, mount a command-injected plugin under that agent's \`agent.ctx\`)`
+            : `command "${name}" is already registered in this scope`));
+    }
+    /** @returns whether this layer owns no command registrations. */
+    isEmpty() {
+        return this.commands.isEmpty();
+    }
+}
+/**
+ * Parse an exact slash command without normalizing its trailing input.
+ *
+ * @param line - Complete candidate command line.
+ * @returns The parsed command, or `undefined` when the line is not a command.
+ */
+export function parseCommand(line) {
+    const match = /^\/([a-z][a-z0-9_-]*)(?=$|[\t\n\r ])/u.exec(line);
+    if (match === null)
+        return undefined;
+    const name = match[1];
+    /* v8 ignore next -- the first capture is required whenever the regular expression matches */
+    if (name === undefined)
+        return undefined;
+    return Object.freeze({ name, rawInput: line.slice(match[0].length) });
+}
+/** Convert arbitrary abort reasons to one stable rejected Error. */
+function abortError(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    return new Error(typeof signal.reason === 'string' ? signal.reason : 'command aborted');
+}
+/** The signal's normalized abort error when it is already aborted. */
+function cancellationOf(signal) {
+    return signal.aborted ? abortError(signal) : undefined;
+}
+/** Render arbitrary thrown values without trusting their string coercion. */
+function renderThrown(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return '<unrenderable thrown value>';
+    }
+}
+/** Stop awaiting an uncooperative handler once its owning UI request aborts. */
+function withAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(abortError(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            signal.removeEventListener('abort', onAbort);
+            reject(abortError(signal));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error instanceof Error
+                ? error
+                : new Error(`command handler rejected with a non-Error value: ${renderThrown(error)}`, { cause: error }));
+        });
+    });
+}
+/** Reject invalid command metadata before it can reach a UI protocol. */
+function normalizeDefinition(definition) {
+    if (!COMMAND_NAME.test(definition.name)) {
+        throw new TypeError(`command name "${definition.name}" must match ${String(COMMAND_NAME)}`);
+    }
+    if (typeof definition.description !== 'string') {
+        throw new TypeError(`command "${definition.name}" description must be a string`);
+    }
+    if (definition.description.trim().length === 0) {
+        throw new TypeError(`command "${definition.name}" description must not be empty`);
+    }
+    if (typeof definition.handler !== 'function') {
+        throw new TypeError(`command "${definition.name}" handler must be a function`);
+    }
+    const rawInput = definition.input;
+    let input;
+    if (rawInput !== undefined) {
+        if (typeof rawInput !== 'object' || rawInput === null || !('hint' in rawInput)
+            || typeof rawInput.hint !== 'string') {
+            throw new TypeError(`command "${definition.name}" input hint must be a string`);
+        }
+        if (rawInput.hint.trim().length === 0) {
+            throw new TypeError(`command "${definition.name}" input hint must not be empty`);
+        }
+        if ('attachments' in rawInput && rawInput.attachments !== undefined && typeof rawInput.attachments !== 'boolean') {
+            throw new TypeError(`command "${definition.name}" input attachments flag must be a boolean`);
+        }
+        input = Object.freeze({
+            hint: rawInput.hint,
+            ...('attachments' in rawInput && rawInput.attachments === true) ? { attachments: true } : {},
+        });
+    }
+    const normalized = Object.freeze({
+        ...definition.definitionId === undefined ? {} : { definitionId: definition.definitionId },
+        name: definition.name,
+        description: definition.description,
+        ...input === undefined ? {} : { input },
+        ...definition.recordInput === undefined ? {} : { recordInput: definition.recordInput },
+        handler: definition.handler,
+    });
+    const descriptor = Object.freeze({
+        ...normalized.definitionId === undefined ? {} : { definitionId: normalized.definitionId },
+        name: normalized.name,
+        description: normalized.description,
+        ...normalized.input === undefined ? {} : { input: normalized.input },
+    });
+    return { definition: normalized, descriptor };
+}
+/** Validate and detach an untrusted handler result at the registry boundary. */
+function normalizeResult(command, value) {
+    if (typeof value !== 'object' || value === null || !('kind' in value)) {
+        throw new TypeError(`command "${command}" handler must return a CommandResult`);
+    }
+    const result = value;
+    if (result.kind === 'success') {
+        if (result.text !== undefined && typeof result.text !== 'string') {
+            throw new TypeError(`command "${command}" success text must be a string when supplied`);
+        }
+        if (result.sourceEventSeq !== undefined
+            && (!Number.isSafeInteger(result.sourceEventSeq)
+                || result.sourceEventSeq < 0
+                || Object.is(result.sourceEventSeq, -0))) {
+            throw new TypeError(`command "${command}" success sourceEventSeq must be a non-negative safe integer when supplied`);
+        }
+        return Object.freeze({
+            kind: 'success',
+            ...result.text === undefined ? {} : { text: result.text },
+            ...result.sourceEventSeq === undefined ? {} : { sourceEventSeq: SessionSeq(result.sourceEventSeq) },
+        });
+    }
+    if (result.kind === 'error') {
+        if (typeof result.text !== 'string' || result.text.trim().length === 0) {
+            throw new TypeError(`command "${command}" error text must be a non-empty string`);
+        }
+        return Object.freeze({ kind: 'error', text: result.text });
+    }
+    throw new TypeError(`command "${command}" returned unknown result kind "${String(result.kind)}"`);
+}
+/**
+ * Human-command registry. Plain-context definitions are global; definitions
+ * registered through a command-injected child of an agent context shadow
+ * globals for that agent.
+ */
+let CommandRuntime = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _list_decorators;
+    let _execute_decorators;
+    return class CommandRuntime extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _list_decorators = [Remote];
+            _execute_decorators = [Remote];
+            __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _execute_decorators, { kind: "method", name: "execute", static: false, private: false, access: { has: obj => "execute" in obj, get: obj => obj.execute }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        layers = (__runInitializers(this, _instanceExtraInitializers), new ScopedLayers(scope => new CommandLayer(scope), () => { this.notifyChange(); }));
+        /** Monotonic per-instance counter behind {@link mintCommandId}. */
+        commandSeq = 0;
+        /** Instance token keeping minted ids unique across process restarts over one resumed log. */
+        instanceToken = randomUUID().slice(0, 8);
+        /** Optional provider installed by the Session upload owner. */
+        fileReceipts = { resolver: undefined };
+        constructor(ctx) {
+            super(ctx, 'commands');
+        }
+        /**
+         * Register a global or calling-agent-scoped command.
+         * @param definition - discovery metadata and direct UI handler.
+         * @returns the exact effect disposer that unregisters this definition.
+         */
+        register(definition) {
+            const registered = normalizeDefinition(definition);
+            return this.layers.effect(this.ctx, layer => layer.commands.insert(registered.definition.name, registered), { label: 'commands.register()' });
+        }
+        /**
+         * Register the sole authority that resolves staged file receipts for command submissions.
+         * @param resolver - Session-aware receipt resolver.
+         * @returns disposer that removes this exact resolver.
+         */
+        registerFileReceiptResolver(resolver) {
+            if (this.fileReceipts.resolver !== undefined) {
+                throw new Error('commands: a file receipt resolver is already registered');
+            }
+            this.fileReceipts.resolver = resolver;
+            return () => {
+                if (this.fileReceipts.resolver === resolver)
+                    this.fileReceipts.resolver = undefined;
+            };
+        }
+        /**
+         * List the effective immutable command descriptors for one agent.
+         * @param agent - exact receiving agent and scoped-layer key.
+         * @returns name-sorted descriptors after scoped shadowing.
+         */
+        list(agent) {
+            return Object.freeze([...this.view(agent).values()]
+                .map(command => command.descriptor)
+                // Names are unique in the effective view, so equality is impossible.
+                .sort((left, right) => left.name < right.name ? -1 : 1));
+        }
+        /**
+         * Resolve one effective command definition.
+         * @param agent - exact receiving agent and scoped-layer key.
+         * @param name - command name without a slash.
+         * @returns the scoped shadow or global definition.
+         */
+        find(agent, name) {
+            return this.view(agent).get(name)?.definition;
+        }
+        /**
+         * Parse and execute a known command without sending it to the model.
+         *
+         * A resolved command's lifecycle is logged: `command/run` is appended
+         * before the handler is invoked and `command/done` after settlement (a
+         * thrown or aborted handler settles as `kind: 'error'`). Both are direct
+         * log-only appends — no turn wraps them, and persistence drains them at
+         * ordinary checkpoints. Admission misses (syntax or unknown name) log
+         * nothing — they never entered a handler. A `command/run` append failure
+         * fails the execution loud; a `command/done` append failure on the
+         * handler-failure path is contained so the handler's own error stays the
+         * reported failure.
+         *
+         * Attachment admission is enforced here, not in the composer: attachments sent to a
+         * command that does not declare `input.attachments`, an absent attachment store,
+         * and an exceeded image limit each settle as an error result before
+         * the handler runs. Validation rejection starts no attachment writes;
+         * a storage failure can leave only unreachable content-addressed objects
+         * for deferred collection.
+         *
+         * @param agent - exact receiving agent.
+         * @param line - complete slash-command line.
+         * @param submittedAttachments - encoded images and staged file receipts accompanying the line,
+         *   in submission order; empty for a plain invocation.
+         * @param signal - cancellation signal owned by the UI request.
+         * @returns the settled execution (result + lifecycle pairing id), or
+         *   `undefined` when syntax or name does not resolve.
+         */
+        async execute(agent, line, submittedAttachments, signal) {
+            const parsed = parseCommand(line);
+            if (parsed === undefined)
+                return undefined;
+            const command = this.view(agent).get(parsed.name);
+            if (command === undefined)
+                return undefined;
+            if (signal.aborted)
+                throw abortError(signal);
+            const commandId = this.mintCommandId();
+            this.appendLifecycle(agent.session, 'command/run', {
+                commandId,
+                name: parsed.name,
+                ...command.definition.recordInput === false ? {} : { args: parsed.rawInput },
+                source: { kind: 'user' },
+            });
+            const settle = (result) => {
+                this.appendLifecycle(agent.session, 'command/done', {
+                    commandId, kind: result.kind,
+                    ...result.text === undefined ? {} : { text: result.text },
+                    ...result.kind === 'success' && result.sourceEventSeq !== undefined
+                        ? { sourceEventSeq: result.sourceEventSeq }
+                        : {},
+                });
+                return Object.freeze({ commandId, result: Object.freeze(result) });
+            };
+            let attachments = NO_ATTACHMENTS;
+            if (submittedAttachments.length > 0) {
+                if (command.definition.input?.attachments !== true) {
+                    return settle({ kind: 'error', text: `/${parsed.name} does not accept attachments` });
+                }
+                const store = this.ctx.get('attachments');
+                if (store === undefined) {
+                    return settle({ kind: 'error', text: `/${parsed.name}: attachments are unavailable because no attachment store is composed` });
+                }
+                try {
+                    attachments = await admitCommandAttachments(store, submittedAttachments, receiptId => this.fileReceipts.resolver?.(agent, receiptId));
+                }
+                catch (error) {
+                    if (error instanceof AttachmentError) {
+                        return settle({ kind: 'error', text: error.message });
+                    }
+                    this.settleThrown(agent.session, parsed.name, commandId, error);
+                    throw error;
+                }
+                // Cancellation must be honored BEFORE the handler runs: admission may
+                // await slow storage, and a handler entered after the caller cancelled
+                // would mutate state the retrying caller then duplicates. (The committed
+                // image objects stay unreferenced and are deferred-GC territory.)
+                const cancelledDuringAdmission = cancellationOf(signal);
+                if (cancelledDuringAdmission !== undefined) {
+                    this.settleThrown(agent.session, parsed.name, commandId, cancelledDuringAdmission);
+                    throw cancelledDuringAdmission;
+                }
+            }
+            const invocation = Object.freeze({ commandId, agent, rawInput: parsed.rawInput, attachments, signal });
+            let result;
+            try {
+                const output = command.definition.handler(invocation);
+                result = normalizeResult(parsed.name, await withAbort(Promise.resolve(output), signal));
+            }
+            catch (error) {
+                this.settleThrown(agent.session, parsed.name, commandId, error);
+                throw error;
+            }
+            return settle(result);
+        }
+        /** Contained `command/done` error append for a thrown handler or admission failure. */
+        settleThrown(session, command, commandId, error) {
+            try {
+                this.appendLifecycle(session, 'command/done', {
+                    commandId, kind: 'error',
+                    text: error instanceof Error ? error.message : renderThrown(error),
+                });
+            }
+            catch (appendError) {
+                this.ctx.logger.warn(`command "${command}": command/done append failed: ${renderThrown(appendError)}`);
+            }
+        }
+        /** Mint the next pairing id (monotonic; instance-token-prefixed so a resumed log never repeats one). */
+        mintCommandId() {
+            this.commandSeq += 1;
+            return CommandId(`cmd-${this.instanceToken}-${this.commandSeq}`);
+        }
+        /**
+         * Append one log-only lifecycle event directly: no turn is opened for it and
+         * no flush is forced — persistence observes the eager `session/event` path
+         * and drains at ordinary checkpoints and teardown, like every other
+         * standalone plugin event.
+         */
+        appendLifecycle(session, type, data) {
+            // Both admitted types are log-only (non-surface), but TypeScript does not
+            // reduce Session.append's conditional rest parameter through a generic
+            // type parameter. Preserve the proven two-argument call shape.
+            const appendLogOnly = session.append.bind(session);
+            return appendLogOnly(type, data);
+        }
+        /** Resolve global definitions followed by exact scoped shadows. */
+        view(agent) {
+            return this.layers.merge(agent, layer => layer.commands);
+        }
+        /** Notify every registry observer without making UI refresh load-bearing. */
+        notifyChange() {
+            // Cordis emit uses Array.map: one synchronous throw starves later listeners,
+            // and returned promises are discarded. Registry notifications are
+            // non-vetoing, so contain each callback independently.
+            for (const callback of this.ctx.events.dispatch('emit', ['commands/change'])) {
+                try {
+                    const returned = callback();
+                    void Promise.resolve(returned).catch((error) => {
+                        this.ctx.logger.warn(`commands/change listener rejected: ${renderThrown(error)}`);
+                    });
+                }
+                catch (error) {
+                    this.ctx.logger.warn(`commands/change listener threw: ${renderThrown(error)}`);
+                }
+            }
+        }
+    };
+})();
+export { CommandRuntime };
+/** Admit a mixed command batch and restore its original image/file order. */
+async function admitCommandAttachments(store, attachments, resolveFileReceipt) {
+    const files = new Map();
+    for (const attachment of attachments) {
+        if (attachment.type !== 'file' || files.has(attachment.receiptId))
+            continue;
+        const file = resolveFileReceipt(attachment.receiptId);
+        if (file === undefined) {
+            throw new AttachmentError('File upload receipt is unknown for this session.', 'ATTACHMENT_NOT_FOUND');
+        }
+        files.set(attachment.receiptId, file);
+    }
+    const images = [];
+    for (const attachment of attachments) {
+        if (attachment.type !== 'image')
+            continue;
+        images.push({
+            mediaType: attachment.mediaType,
+            data: attachment.data,
+            ...(attachment.name === undefined ? {} : { name: attachment.name }),
+        });
+    }
+    const imageRefs = images.length === 0 ? [] : await admitEncodedImages(store, images);
+    let imageIndex = 0;
+    const blocks = [];
+    for (const attachment of attachments) {
+        if (attachment.type === 'image') {
+            const ref = imageRefs[imageIndex];
+            imageIndex += 1;
+            blocks.push(Object.freeze({ type: 'image', attachment: ref }));
+            continue;
+        }
+        blocks.push(Object.freeze({
+            type: 'file', attachment: files.get(attachment.receiptId),
+        }));
+    }
+    return Object.freeze(blocks);
+}
+export default CommandRuntime;
+//# sourceMappingURL=index.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Durable command event vocabulary and the registry's Cordis event
+ * declaration, shared with type-only consumers. Client-safe: nothing here
+ * reaches a Host-only symbol, so a Client compilation face reads the same
+ * `commands/change` signature the Host emits.
+ *
+ * @module @qilin-agent/commands/types
+ */
+import type { SessionSeq } from '@qilin-agent/session/types';
+import type { CommandDefinitionId, CommandId } from './brand.ts';
+import type { EncodedImageAttachment } from '@qilin-agent/attachment/types';
+/** One browser-submitted command attachment: encoded image input or a staged file receipt. */
+export type CommandSubmitAttachment = ({
+    readonly type: 'image';
+} & EncodedImageAttachment) | {
+    readonly type: 'file';
+    readonly receiptId: string;
+};
+/** Immutable metadata for a command's optional unstructured input. */
+export interface CommandInputDescriptor {
+    /** Placeholder shown before the user supplies free-form input. */
+    readonly hint: string;
+    /**
+     * Whether composer attachments may accompany an invocation. Absent or
+     * false = the executor rejects an invocation carrying attachments and capable
+     * composers refuse the submission before dispatch. A declaring command's
+     * handler receives the admitted durable blocks and owns every further
+     * grammar decision, including rejecting sub-commands that cannot use them.
+     */
+    readonly attachments?: boolean;
+}
+/** Expected command outcome rendered directly by the dispatching UI. */
+export type CommandResult = {
+    readonly kind: 'success';
+    readonly text?: string;
+    /** Earlier authoritative domain event that owns a richer presentation. */
+    readonly sourceEventSeq?: SessionSeq;
+} | {
+    readonly kind: 'error';
+    readonly text: string;
+};
+/**
+ * One settled command execution: the handler's normalized result plus the
+ * lifecycle pairing id minted for its `command/run`/`command/done` records,
+ * so a dispatching surface can correlate the Remote acknowledgment with the
+ * flow node those events produce.
+ */
+export interface CommandExecution {
+    /** Pairing id carried by this execution's lifecycle events. */
+    readonly commandId: CommandId;
+    /** The handler's normalized outcome. */
+    readonly result: CommandResult;
+}
+/** Handler-free immutable command view returned to UI adapters. */
+export interface CommandDescriptor {
+    /** Stable plugin-owned identity; absent for definitions without identity-based client behavior. */
+    readonly definitionId?: CommandDefinitionId;
+    /** Lowercase command name without the leading slash. */
+    readonly name: string;
+    /** Human-readable summary used in discovery UI. */
+    readonly description: string;
+    /** Optional free-form input hint advertised to capable clients. */
+    readonly input?: CommandInputDescriptor;
+}
+/**
+ * Producer record for one command invocation (the `command/run` event's
+ * source slot). Merge-extensible sum type mirroring `MessageSourceMap`'s
+ * shape; minimal because every executor caller is a human-facing UI
+ * surface dispatching a human-typed line, so the sole variant is `user`.
+ */
+export interface CommandSourceMap {
+    user: {
+        kind: 'user';
+    };
+}
+/** The union over {@link CommandSourceMap} — who issued a command line. */
+export type CommandSource = CommandSourceMap[keyof CommandSourceMap];
+declare module '@qilin-agent/kylin' {
+    interface Events {
+        /**
+         * A command was registered or unregistered. This is an unfiltered registry
+         * notification because a global or scoped change may affect any UI view.
+         * Observer failures are contained and cannot veto the registry mutation.
+         * @mode emit
+         */
+        'commands/change'(): void;
+    }
+}
+declare module '@qilin-agent/session/types' {
+    interface SessionEventMap {
+        /**
+         * A resolved slash command entered its handler. Log-only (never model
+         * surface); paired with `command/done` by `commandId`, mirroring the
+         * `tool/call`↔`tool/result` pairing. The payload is structured — `name`
+         * and `args` are `parseCommand`'s own split (name and verbatim rawInput,
+         * separator whitespace included), so a consumer (a projection unit
+         * folding its own command records, a rich command card) never re-parses
+         * a line. `args` is absent when the definition sets `recordInput: false`
+         * because an authoritative domain event owns the input payload.
+         */
+        'command/run': {
+            commandId: CommandId;
+            name: string;
+            args?: string;
+            source: CommandSource;
+        };
+        /**
+         * The paired command settled. `kind`/`text` carry the handler's verbatim
+         * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
+         * rendered failure). A successful command may identify the earlier
+         * authoritative domain event for a richer client-computed presentation.
+         */
+        'command/done': {
+            commandId: CommandId;
+            kind: 'success' | 'error';
+            text?: string;
+            sourceEventSeq?: import('@qilin-agent/session/types').SessionSeq;
+        };
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,10 @@
+/**
+ * Durable command event vocabulary and the registry's Cordis event
+ * declaration, shared with type-only consumers. Client-safe: nothing here
+ * reaches a Host-only symbol, so a Client compilation face reads the same
+ * `commands/change` signature the Host emits.
+ *
+ * @module @qilin-agent/commands/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@qilin-agent/commands",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Plugin-owned human command registry for QiLin UIs",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/interaction/commands"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.host.d.ts",
+    "lib/typert.remote-client.js",
+    "lib/typert.remote-client.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/attachment": "3.1.3",
+    "@qilin-agent/brand": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/scope": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/typert-protocol": "3.1.3"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@qilin-agent/util-crypto": "3.1.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/brand": "3.1.3",
+    "@qilin-agent/attachment": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/scope": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/typert-protocol": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }