@qilin-agent/commands 0.0.0-stage → 3.1.3

package/lib/typert.remote-client.d.ts

@@ -0,0 +1,29 @@
+/* Generated by @qilin-agent/typert-generator from the Host FaceModel — do not edit. */
+import type {
+  RemoteResult,
+  TypertRemoteContribution,
+} from '@qilin-agent/typert-protocol'
+import type { CommandDescriptor, CommandExecution, CommandSubmitAttachment } from '@qilin-agent/commands/types'
+import type { SessionId } from '@qilin-agent/session/types'
+
+declare module '@qilin-agent/typert-protocol' {
+  interface TypertRemoteNamespace$636f6d6d616e6473 {
+    execute: (agentId: SessionId, line: string, submittedAttachments: readonly CommandSubmitAttachment[], signal?: AbortSignal) => Promise<RemoteResult<CommandExecution | undefined>>
+    list: (agentId: SessionId) => Promise<RemoteResult<readonly CommandDescriptor[]>>
+  }
+  interface TypertRemoteMap {
+    'commands/execute': (agentId: SessionId, line: string, submittedAttachments: readonly CommandSubmitAttachment[], signal?: AbortSignal) => Promise<RemoteResult<CommandExecution | undefined>>
+    'commands/list': (agentId: SessionId) => Promise<RemoteResult<readonly CommandDescriptor[]>>
+  }
+  interface TypertRemoteNamespaceMap {
+    'commands': TypertRemoteNamespace$636f6d6d616e6473
+  }
+  interface TypertRemoteScopeMap {
+    'agent:commands/execute': (line: string, submittedAttachments: readonly CommandSubmitAttachment[], signal?: AbortSignal) => Promise<RemoteResult<CommandExecution | undefined>>
+    'agent:commands/list': () => Promise<RemoteResult<readonly CommandDescriptor[]>>
+  }
+}
+
+export declare const TYPERT_REMOTE: TypertRemoteContribution
+export default TYPERT_REMOTE
+//# sourceMappingURL=typert.remote-client.d.ts.map

package/lib/typert.remote-client.js

@@ -0,0 +1,131 @@
+/* Generated by @qilin-agent/typert-generator from the Host FaceModel — do not edit. */
+import { z } from 'zod'
+
+let _qilin_agent_commands_commands_execute_parameter_0$schema$value
+const _qilin_agent_commands_commands_execute_parameter_0$schema = () => (_qilin_agent_commands_commands_execute_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+let _qilin_agent_commands_commands_execute_parameter_1$schema$value
+const _qilin_agent_commands_commands_execute_parameter_1$schema = () => (_qilin_agent_commands_commands_execute_parameter_1$schema$value ??= z.string())
+let _qilin_agent_commands_commands_execute_parameter_2$schema$value
+const _qilin_agent_commands_commands_execute_parameter_2$schema = () => (_qilin_agent_commands_commands_execute_parameter_2$schema$value ??= z.array(z.union([z.intersection(z.object({
+  'type': z.literal("image").readonly(),
+}), z.object({
+  'mediaType': z.union([z.literal("image/png"), z.literal("image/jpeg"), z.literal("image/webp"), z.literal("image/gif")]),
+  'data': z.string(),
+  'name': z.string().optional(),
+})), z.object({
+  'type': z.literal("file").readonly(),
+  'receiptId': z.string().readonly(),
+})])))
+let _qilin_agent_commands_commands_execute_result$schema$value
+const _qilin_agent_commands_commands_execute_result$schema = () => (_qilin_agent_commands_commands_execute_result$schema$value ??= z.union([z.undefined(), z.object({
+  'commandId': z.intersection(z.string(), z.unknown()).readonly(),
+  'result': z.union([z.object({
+  'kind': z.literal("success").readonly(),
+  'text': z.string().readonly().optional(),
+  'sourceEventSeq': z.intersection(z.number(), z.unknown()).readonly().optional(),
+}), z.object({
+  'kind': z.literal("error").readonly(),
+  'text': z.string().readonly(),
+})]).readonly(),
+})]))
+let _qilin_agent_commands_commands_list_parameter_0$schema$value
+const _qilin_agent_commands_commands_list_parameter_0$schema = () => (_qilin_agent_commands_commands_list_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+let _qilin_agent_commands_commands_list_result$schema$value
+const _qilin_agent_commands_commands_list_result$schema = () => (_qilin_agent_commands_commands_list_result$schema$value ??= z.array(z.object({
+  'definitionId': z.intersection(z.string(), z.unknown()).readonly().optional(),
+  'name': z.string().readonly(),
+  'description': z.string().readonly(),
+  'input': z.object({
+  'hint': z.string().readonly(),
+  'attachments': z.boolean().readonly().optional(),
+}).readonly().optional(),
+})))
+
+export const TYPERT_REMOTE = {
+  package: '@qilin-agent/commands',
+  descriptors: [
+    {
+      id: '@qilin-agent/commands#commands/execute',
+      service: 'commands',
+      namespace: 'commands',
+      method: 'execute',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qilin-agent/session/types#SessionId',
+            create: _qilin_agent_commands_commands_execute_parameter_0$schema,
+          },
+        },
+        {
+          name: 'line',
+          wire: 'line',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qilin-agent/commands#commands/execute:line',
+            create: _qilin_agent_commands_commands_execute_parameter_1$schema,
+          },
+        },
+        {
+          name: 'submittedAttachments',
+          wire: 'submittedAttachments',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qilin-agent/commands#commands/execute:submittedAttachments',
+            create: _qilin_agent_commands_commands_execute_parameter_2$schema,
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@qilin-agent/commands#commands/execute:result',
+        create: _qilin_agent_commands_commands_execute_result$schema,
+      },
+      sourceLocation: {"file":"packages/interaction/commands/src/index.ts","line":361,"column":9},
+    },
+    {
+      id: '@qilin-agent/commands#commands/list',
+      service: 'commands',
+      namespace: 'commands',
+      method: 'list',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qilin-agent/session/types#SessionId',
+            create: _qilin_agent_commands_commands_list_parameter_0$schema,
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@qilin-agent/commands#commands/list:result',
+        create: _qilin_agent_commands_commands_list_result$schema,
+      },
+      sourceLocation: {"file":"packages/interaction/commands/src/index.ts","line":315,"column":3},
+    },
+  ],
+}
+
+export default TYPERT_REMOTE

package/lib/types/brand.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Command definition identities and execution ids for discovery and lifecycle pairing.
+ *
+ * The `Branded<B>` primitive lives in `@qilin-agent/brand`; this module
+ * is a pure type/constructor outlet (no cordis imports, no module
+ * augmentation) so wire and client programs can name the brand without
+ * loading the host plugin's Context merges — the `qilin-llm/brand` shape.
+ *
+ * @module @qilin-agent/commands/brand
+ */
+import type { Branded } from '@qilin-agent/brand';
+/** Stable, plugin-owned identity of a command definition, independent of its name and copy. */
+export type CommandDefinitionId = Branded<'CommandDefinitionId'>;
+/**
+ * Brand a plugin-namespaced command definition identity.
+ * @param id - stable identity chosen by the registering plugin.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function CommandDefinitionId(id: string): CommandDefinitionId;
+/**
+ * Pairs one command execution's `command/run`/`command/done` lifecycle
+ * records with each other and with the `command.execute` admission response.
+ * Minted by the executor, monotonic per service instance.
+ */
+export type CommandId = Branded<'CommandId'>;
+/**
+ * Brand a string as a {@link CommandId}.
+ * @param id - the executor-minted pairing id.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function CommandId(id: string): CommandId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -0,0 +1,27 @@
+/**
+ * Command definition identities and execution ids for discovery and lifecycle pairing.
+ *
+ * The `Branded<B>` primitive lives in `@qilin-agent/brand`; this module
+ * is a pure type/constructor outlet (no cordis imports, no module
+ * augmentation) so wire and client programs can name the brand without
+ * loading the host plugin's Context merges — the `qilin-llm/brand` shape.
+ *
+ * @module @qilin-agent/commands/brand
+ */
+/**
+ * Brand a plugin-namespaced command definition identity.
+ * @param id - stable identity chosen by the registering plugin.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function CommandDefinitionId(id) {
+    return id;
+}
+/**
+ * Brand a string as a {@link CommandId}.
+ * @param id - the executor-minted pairing id.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function CommandId(id) {
+    return id;
+}
+//# sourceMappingURL=brand.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Plugin-owned human-command registry shared by interactive UI adapters.
+ * @module @qilin-agent/commands
+ */
+import { Context } from '@qilin-agent/kylin';
+import type { Agent } from '@qilin-agent/agent';
+import type { FileAttachmentRef } from '@qilin-agent/attachment/types';
+import type { FileBlock, ImageBlock } from '@qilin-agent/llm';
+import { TypertRemoteService } from '@qilin-agent/typert-protocol';
+import { CommandId } from './brand.ts';
+import type { CommandDefinitionId } from './brand.ts';
+import type { CommandDescriptor, CommandExecution, CommandInputDescriptor, CommandResult, CommandSubmitAttachment } from './types.ts';
+export { CommandDefinitionId, CommandId } from './brand.ts';
+export type * from './types.ts';
+export declare const name = "commands";
+/** Host resolver for Session-scoped staged file-upload receipts. */
+export type CommandFileReceiptResolver = (agent: Agent, receiptId: string) => FileAttachmentRef | undefined;
+/** Invocation passed to one registered command handler. */
+export interface CommandInvocation {
+    /** Pairing id already written to this invocation's `command/run` event. */
+    readonly commandId: CommandId;
+    /** Exact agent whose UI received the command. */
+    readonly agent: Agent;
+    /** Exact text following the registered command name, including separator whitespace. */
+    readonly rawInput: string;
+    /**
+     * Durably admitted image and file blocks accompanying this invocation, in submission
+     * order; empty unless the definition declares `input.attachments`. The handler
+     * owns their model-visible use — the registry never schedules them itself —
+     * and a handler whose grammar cannot use them in this invocation returns an
+     * error so the dispatching composer retains the originals.
+     */
+    readonly attachments: readonly (ImageBlock | FileBlock)[];
+    /** Cancellation signal owned by the dispatching UI request. */
+    readonly signal: AbortSignal;
+}
+/** Plugin-owned command registration. */
+export interface CommandDefinition {
+    /** 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;
+    /**
+     * Whether `command/run` records `rawInput`. Defaults to true. A command
+     * whose domain event owns the payload sets this false to avoid duplicating
+     * that payload in the session log.
+     */
+    readonly recordInput?: boolean;
+    /** Execute against the receiving agent without sending the command to the model. */
+    readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>;
+}
+/** Syntactically valid slash command before registry resolution. */
+export interface ParsedCommand {
+    /** Lowercase command name without the leading slash. */
+    readonly name: string;
+    /** Exact text following the command name. */
+    readonly rawInput: string;
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        commands: CommandRuntime;
+    }
+}
+/**
+ * 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 declare function parseCommand(line: string): ParsedCommand | undefined;
+/**
+ * Human-command registry. Plain-context definitions are global; definitions
+ * registered through a command-injected child of an agent context shadow
+ * globals for that agent.
+ */
+export declare class CommandRuntime extends TypertRemoteService {
+    private readonly layers;
+    /** Monotonic per-instance counter behind {@link mintCommandId}. */
+    private commandSeq;
+    /** Instance token keeping minted ids unique across process restarts over one resumed log. */
+    private readonly instanceToken;
+    /** Optional provider installed by the Session upload owner. */
+    private readonly fileReceipts;
+    constructor(ctx: Context);
+    /**
+     * 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: CommandDefinition): () => void;
+    /**
+     * 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: CommandFileReceiptResolver): () => void;
+    /**
+     * 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: Agent): readonly CommandDescriptor[];
+    /**
+     * 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: Agent, name: string): CommandDefinition | undefined;
+    /**
+     * 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.
+     */
+    execute(agent: Agent, line: string, submittedAttachments: readonly CommandSubmitAttachment[], signal: AbortSignal): Promise<CommandExecution | undefined>;
+    /** Contained `command/done` error append for a thrown handler or admission failure. */
+    private settleThrown;
+    /** Mint the next pairing id (monotonic; instance-token-prefixed so a resumed log never repeats one). */
+    private mintCommandId;
+    /**
+     * 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.
+     */
+    private appendLifecycle;
+    /** Resolve global definitions followed by exact scoped shadows. */
+    private view;
+    /** Notify every registry observer without making UI refresh load-bearing. */
+    private notifyChange;
+}
+export default CommandRuntime;
+//# sourceMappingURL=index.d.ts.map