@zhin.js/command 1.1.13 → 1.1.14

package/lib/command-index.d.ts

@@ -1,5 +1,6 @@
 import { type CapabilityId, type CapabilitySlot, type PluginId, type RuntimeSnapshot, type Locale } from '@zhin.js/plugin-runtime';
 import type { UserInteractionFactory } from '@zhin.js/interaction';
+import { type CapabilityOperationFactory } from '@zhin.js/feature-kit';
 import { type CommandValidationIssue } from './arguments.js';
 import { type CommandMenuEntry, type CommandMenuAppearance } from './command-menu.js';
 export type { CommandMenuEntry, CommandMenuAppearance } from './command-menu.js';
@@ -32,6 +33,7 @@ export interface CommandDispatchRequest {
     readonly interactionFactory?: UserInteractionFactory;
     readonly commandPrefix?: string;
     readonly snapshot?: RuntimeSnapshot;
+    readonly operation?: CapabilityOperationFactory;
     readonly locale?: Locale;
 }
 export interface CommandDispatchResult {
@@ -81,7 +83,7 @@ export declare class CommandIndex {
     formatMenu(prefix: string | undefined, locale: Locale): string | undefined;
     has(name: string): boolean;
     execute(name: string, args?: readonly string[], operationSnapshot?: RuntimeSnapshot): Promise<unknown>;
-    dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot, locale: localeOverride }: CommandDispatchRequest): Promise<CommandDispatchResult>;
+    dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot, locale: localeOverride, operation: operationFactory }: CommandDispatchRequest): Promise<CommandDispatchResult>;
 }
 export declare function isCommandIndex(value: unknown): value is CommandIndex;
 /**

package/lib/command-index.js

@@ -195,7 +195,7 @@ export class CommandIndex {
             admission.release();
         }
     }
-    async dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot = this.snapshot, locale: localeOverride }) {
+    async dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot = this.snapshot, locale: localeOverride, operation: operationFactory }) {
         const locale = localeOverride ?? commandLocale(source, operationSnapshot);
         const prefix = commandPrefix ?? '';
         if (this.#menu) {
@@ -247,12 +247,22 @@ export class CommandIndex {
         const limit = admitCommandExecution(authorSource, match.command.slot.id, match.command.slot.owner, match.command.execution, operationSnapshot);
         if (limit)
             return Object.freeze({ matched: true, status: 'limited', command: match.command.name, owner: match.command.slot.owner, limit });
-        const value = await definition.execute(createCommandContext({
-            snapshot: operationSnapshot, ownerId: match.command.slot.owner, input: authorSource,
-            interaction: interactionFactory?.(authorSource), adapter: definition.adapter,
-            presentation: { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath, source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) },
-        }, { args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options }));
-        return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
+        const operation = operationFactory?.create({ owner: match.command.slot.owner, signal: operationFactory.signal });
+        try {
+            const value = await definition.execute(createCommandContext({
+                snapshot: operationSnapshot, ownerId: match.command.slot.owner, input: authorSource,
+                operation,
+                interaction: interactionFactory?.(authorSource), adapter: definition.adapter,
+                presentation: { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath, source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) },
+            }, { args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options }));
+            return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
+        }
+        finally {
+            try {
+                await operation?.resources?.close();
+            }
+            catch { /* Cleanup never replaces the command's actual outcome. */ }
+        }
     }
     #denied(record) {
         return Object.freeze({ matched: true, status: 'denied', command: record.name, owner: record.slot.owner });

package/lib/definition.d.ts

@@ -3,7 +3,7 @@
  * @module zhin.js/command
  */
 import { type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import { type OperationSession, type AdapterClient, type RegisteredAdapterName, type CapabilityContext } from '@zhin.js/feature-kit';
+import { type CapabilityOperation, type OperationSession, type AdapterClient, type RegisteredAdapterName, type CapabilityContext } from '@zhin.js/feature-kit';
 import type { UserInteraction } from '@zhin.js/interaction';
 import { type CommandExecutionPolicy } from './execution-policy.js';
 export type { CommandExecutionPolicy, CommandExecutionLimit } from './execution-policy.js';
@@ -346,6 +346,7 @@ export interface CommandInvocationArguments {
 export interface CommandInvocationOperation {
     readonly snapshot: RuntimeSnapshot;
     readonly ownerId: PluginId;
+    readonly operation?: CapabilityOperation;
     readonly input?: unknown;
     readonly interaction?: UserInteraction;
     readonly adapter?: string;

package/lib/definition.js

@@ -177,7 +177,7 @@ export function resolveDynamicParams(params, source) {
 export function createCommandContext(operation, invocation) {
     const { snapshot, ownerId, input, interaction, adapter, presentation } = operation;
     const { args, params = {}, options = {}, segments = [] } = invocation;
-    const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
+    const context = createCapabilityContext({ snapshot, ownerId, signal: readOperationInputSignal(input), operation: operation.operation });
     const session = resolveCommandSession(input);
     const parameterValues = { __proto__: null, ...params };
     const optionValues = { __proto__: null, ...options };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.1.13",
+  "version": "1.1.14",
   "description": "Convention-based Command Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -21,10 +21,10 @@
   ],
   "dependencies": {
     "segment-matcher": "^1.0.5",
-    "@zhin.js/feature-kit": "1.1.11",
+    "@zhin.js/feature-kit": "1.1.12",
     "@zhin.js/interaction": "1.1.2",
-    "@zhin.js/permission": "1.1.11",
-    "@zhin.js/plugin-runtime": "1.1.19"
+    "@zhin.js/permission": "1.1.12",
+    "@zhin.js/plugin-runtime": "1.1.20"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/command-index.ts

@@ -13,7 +13,7 @@ import {
   type Locale,
 } from '@zhin.js/plugin-runtime';
 import type { UserInteractionFactory } from '@zhin.js/interaction';
-import { bindOperationInput } from '@zhin.js/feature-kit';
+import { bindOperationInput, type CapabilityOperationFactory } from '@zhin.js/feature-kit';
 import {
   permissionHostToken,
   type PermissionHost,
@@ -65,6 +65,7 @@ export interface CommandDispatchRequest {
   readonly interactionFactory?: UserInteractionFactory;
   readonly commandPrefix?: string;
   readonly snapshot?: RuntimeSnapshot;
+  readonly operation?: CapabilityOperationFactory;
   readonly locale?: Locale;
 }
 /** Presentation and generation shared across one menu lookup/render operation. */
@@ -351,7 +352,7 @@ export class CommandIndex {
   }
 
   async dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot = this.snapshot,
-    locale: localeOverride }: CommandDispatchRequest): Promise<CommandDispatchResult> {
+    locale: localeOverride, operation: operationFactory }: CommandDispatchRequest): Promise<CommandDispatchResult> {
     const locale = localeOverride ?? commandLocale(source, operationSnapshot);
     const prefix = commandPrefix ?? '';
     if (this.#menu) {
@@ -395,13 +396,19 @@ export class CommandIndex {
       owner: match.command.slot.owner, issues: parsed.issues, help });
     const limit = admitCommandExecution(authorSource, match.command.slot.id, match.command.slot.owner, match.command.execution, operationSnapshot);
     if (limit) return Object.freeze({ matched: true, status: 'limited', command: match.command.name, owner: match.command.slot.owner, limit });
-    const value = await definition.execute(createCommandContext({
-      snapshot: operationSnapshot, ownerId: match.command.slot.owner, input: authorSource,
-      interaction: interactionFactory?.(authorSource), adapter: definition.adapter,
-      presentation: { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath,
-        source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) },
-    }, { args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options }));
-    return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
+    const operation = operationFactory?.create({ owner: match.command.slot.owner, signal: operationFactory.signal });
+    try {
+      const value = await definition.execute(createCommandContext({
+        snapshot: operationSnapshot, ownerId: match.command.slot.owner, input: authorSource,
+        operation,
+        interaction: interactionFactory?.(authorSource), adapter: definition.adapter,
+        presentation: { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath,
+          source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) },
+      }, { args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options }));
+      return Object.freeze({ matched: true, status: 'executed', command: match.command.name, owner: match.command.slot.owner, value });
+    } finally {
+      try { await operation?.resources?.close(); } catch { /* Cleanup never replaces the command's actual outcome. */ }
+    }
   }
 
   #denied(record: CommandRecord): CommandDispatchResult {

package/src/definition.ts

@@ -5,6 +5,7 @@
 import { resolveLocale, type Locale, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import {
   createCapabilityContext,
+  type CapabilityOperation,
   readOperationClient,
   readOperationSession,
   type OperationSession,
@@ -598,6 +599,7 @@ export interface CommandInvocationArguments {
 export interface CommandInvocationOperation {
   readonly snapshot: RuntimeSnapshot;
   readonly ownerId: PluginId;
+  readonly operation?: CapabilityOperation;
   readonly input?: unknown;
   readonly interaction?: UserInteraction;
   readonly adapter?: string;
@@ -611,7 +613,7 @@ export interface CommandInvocationOperation {
 export function createCommandContext(operation: CommandInvocationOperation, invocation: CommandInvocationArguments): CommandContext {
   const { snapshot, ownerId, input, interaction, adapter, presentation } = operation;
   const { args, params = {}, options = {}, segments = [] } = invocation;
-  const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
+  const context = createCapabilityContext({ snapshot, ownerId, signal: readOperationInputSignal(input), operation: operation.operation });
   const session = resolveCommandSession(input);
   const parameterValues: Record<string, CommandParameterValue> = { __proto__: null, ...params };
   const optionValues: Record<string, CommandParameterValue> = { __proto__: null, ...options };