@zhin.js/command 1.1.11 → 1.1.13

package/README.md

@@ -117,7 +117,7 @@ export default defineCommand({
 后面的内容作为参数。未知/重复选项拒绝。`remind --help` 从同一声明生成帮助，包含
 Endpoint 前缀及显式插件命名空间，不执行命令；同一权限声明仍约束帮助读取。
 
-`dispatch()` 返回 `status`：`unmatched`（继续普通消息处理）、`invalid`（`issues` +
+`dispatch({ input, source, snapshot })` 返回 `status`：`unmatched`（继续普通消息处理）、`invalid`（`issues` +
 `help`）、`denied`（权限拒绝）、`limited`（执行预算拒绝）、`executed`。后四者 `matched: true`，只有 `executed`
 包含业务结果。可靠静态路径匹配后才提示错误；纯动态路由的模糊聊天保持未匹配。
 受限命令没有可鉴权主体时拒绝，Host 可通过 `dispatch` 提供真实 `PermissionSubject`；

package/lib/command-index.d.ts

@@ -25,6 +25,15 @@ export interface CommandDescriptor {
     /** shortcut 触发键列表（不含预填 params）。 */
     readonly shortcut?: readonly string[];
 }
+/** One dispatch reads the caller's exact operation generation and presentation. */
+export interface CommandDispatchRequest {
+    readonly input: CommandMatchInput;
+    readonly source?: unknown;
+    readonly interactionFactory?: UserInteractionFactory;
+    readonly commandPrefix?: string;
+    readonly snapshot?: RuntimeSnapshot;
+    readonly locale?: Locale;
+}
 export interface CommandDispatchResult {
     readonly matched: boolean;
     readonly status: 'unmatched' | 'invalid' | 'denied' | 'limited' | 'executed';
@@ -72,7 +81,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: CommandMatchInput, source?: unknown, interactionFactory?: UserInteractionFactory, commandPrefix?: string, operationSnapshot?: RuntimeSnapshot, localeOverride?: Locale): Promise<CommandDispatchResult>;
+    dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot, locale: localeOverride }: CommandDispatchRequest): Promise<CommandDispatchResult>;
 }
 export declare function isCommandIndex(value: unknown): value is CommandIndex;
 /**

package/lib/command-index.js

@@ -186,18 +186,21 @@ export class CommandIndex {
         if (admission.limit)
             throw new CommandExecutionLimitedError(admission.limit);
         try {
-            return await definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner, textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options, { locale }));
+            return await definition.execute(createCommandContext({ snapshot: operationSnapshot, ownerId: match.command.slot.owner,
+                adapter: definition.adapter, presentation: { locale } }, {
+                args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options,
+            }));
         }
         finally {
             admission.release();
         }
     }
-    async dispatch(input, source = undefined, interactionFactory, commandPrefix, operationSnapshot = this.snapshot, localeOverride) {
+    async dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot = this.snapshot, locale: localeOverride }) {
         const locale = localeOverride ?? commandLocale(source, operationSnapshot);
         const prefix = commandPrefix ?? '';
         if (this.#menu) {
             const keyword = this.#menu.keyword ?? commandMessages(locale, 'menuKeyword');
-            const menuResult = this.#dispatchMenu(input, prefix, operationSnapshot, locale, keyword);
+            const menuResult = this.#dispatchMenu(input, { commandPrefix: prefix, snapshot: operationSnapshot, locale, keyword });
             if (menuResult !== undefined) {
                 return Object.freeze({
                     matched: true,
@@ -244,7 +247,11 @@ 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(operationSnapshot, match.command.slot.owner, textArgs(parsed.remaining), parsed.params, authorSource, parsed.remaining, interactionFactory?.(authorSource), definition.adapter, parsed.options, { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath, source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) }));
+        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 });
     }
     #denied(record) {
@@ -362,12 +369,13 @@ export class CommandIndex {
     // ==========================================================================
     // 内置菜单命令
     // ==========================================================================
-    #dispatchMenu(input, commandPrefix, snapshot, locale, keyword) {
+    #dispatchMenu(input, context) {
+        const { commandPrefix, keyword, locale } = context;
         const text = typeof input === 'string' ? input.trim() : exactMessageText(input);
         if (text === undefined)
             return undefined;
         if (text === keyword)
-            return this.#buildMenu(undefined, commandPrefix, keyword, snapshot, locale);
+            return this.#buildMenu({}, context);
         if (text.startsWith(keyword + ' ')) {
             const key = text.slice(keyword.length + 1).trim();
             const args = key.split(/\s+/u);
@@ -378,15 +386,15 @@ export class CommandIndex {
                     || !Number.isSafeInteger(Number(pageText))) {
                     return { value: commandMessages(locale, 'invalidPage', { command: `${commandPrefix}${keyword}` }) };
                 }
-                return this.#buildMenu(flag === 1 ? args[0] : undefined, commandPrefix, keyword, snapshot, locale, Number(pageText));
+                return this.#buildMenu({ pluginKey: flag === 1 ? args[0] : undefined, page: Number(pageText) }, context);
             }
             if (key)
-                return this.#buildMenu(key, commandPrefix, keyword, snapshot, locale);
-            return this.#buildMenu(undefined, commandPrefix, keyword, snapshot, locale);
+                return this.#buildMenu({ pluginKey: key }, context);
+            return this.#buildMenu({}, context);
         }
         return undefined;
     }
-    #buildMenu(pluginKey, commandPrefix, keyword, snapshot, locale, page = 1) {
+    #buildMenu({ pluginKey, page = 1 }, { commandPrefix, keyword, snapshot, locale }) {
         const root = snapshot.root;
         const targetId = pluginKey
             ? `${root}/${pluginKey.split('.').join('/')}`

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 AdapterClient, type RegisteredAdapterName, type CapabilityContext } from '@zhin.js/feature-kit';
+import { 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';
@@ -233,6 +233,8 @@ export interface CommandContext<TConfig = unknown, TInput extends CommandMessage
     readonly input?: TInput;
     /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
     readonly $client: AdapterClient<TAdapter>;
+    /** Bound by the actual IM operation; direct CommandIndex.execute calls may have no Session. */
+    readonly session: OperationSession<TAdapter> | undefined;
     /**
      * 对话式交互输入。IM 派发时自动注入；无消息来源时为 `undefined`。
      */
@@ -300,13 +302,24 @@ type TypedCommandContext<TConfig, TInput extends CommandMessage, TAdapter extend
     readonly params: keyof P extends never ? Readonly<Record<string, CommandParameterValue>> : InferCommandParams<P>;
     readonly options: InferCommandOptions<O>;
 };
+/** The returned declaration retains its platform, parameter schemas and callback result. */
+type DeclaredCommandAdapter<D> = D extends {
+    readonly adapter: infer A extends string;
+} ? A : D extends {
+    readonly adapter?: infer A extends string | undefined;
+} ? A : undefined;
+export type TypedCommandDefinition<TConfig, TResult, TInput extends CommandMessage, TAdapter extends string | undefined, P extends CommandParams, O extends CommandOptions> = Omit<CommandDefinition<TConfig, TResult, TInput, TAdapter>, 'params' | 'options' | 'execute'> & {
+    readonly params?: P;
+    readonly options?: O;
+    execute(context: TypedCommandContext<TConfig, TInput, TAdapter, P, O>): TResult | Promise<TResult>;
+};
 /**
  * `defineCommand.withConfig<Config>()` 返回的定义函数：config 类型已固定，params / options / 返回值
  * 仍从定义推断。
  * @public
  */
-export type CommandDefiner<TConfig, TInput extends CommandMessage = CommandMessage> = <TResult = unknown, const P extends CommandParams = {}, const O extends CommandOptions = {}>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>) => Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
-export declare function defineCommand<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage, const P extends CommandParams = {}, const O extends CommandOptions = {}>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>): Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
+export type CommandDefiner<TConfig, TInput extends CommandMessage = CommandMessage> = <const TResult = unknown, const P extends CommandParams = {}, const O extends CommandOptions = {}, const D extends CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> = CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> & D) => Readonly<TypedCommandDefinition<TConfig, TResult, TInput, DeclaredCommandAdapter<D>, P, O> & Pick<D, keyof D & 'adapter'>>;
+export declare function defineCommand<TConfig = unknown, const TResult = unknown, TInput extends CommandMessage = CommandMessage, const P extends CommandParams = {}, const O extends CommandOptions = {}, const D extends CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> = CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>>(definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> & D): Readonly<TypedCommandDefinition<TConfig, TResult, TInput, DeclaredCommandAdapter<D>, P, O> & Pick<D, keyof D & 'adapter'>>;
 export declare namespace defineCommand {
     var withConfig: <TConfig = unknown, TInput extends CommandMessage = CommandMessage>() => CommandDefiner<TConfig, TInput>;
 }
@@ -322,11 +335,27 @@ export declare function parseCommandDefinition(value: unknown): CommandDefinitio
  * @internal Command projection helper.
  */
 export declare function resolveDynamicParams(params: Readonly<Record<string, CommandDynamicValue>>, source: unknown): Readonly<Record<string, CommandParameterValue>>;
-/** @internal Command dispatcher assembly helper. */
-export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId: PluginId, args: readonly string[], params?: Readonly<Record<string, CommandParameterValue>>, input?: unknown, segments?: readonly Readonly<CommandSegment>[], interaction?: UserInteraction, adapter?: string, options?: Readonly<Record<string, CommandParameterValue>>, presentation?: Readonly<{
-    locale: Locale;
-    formatCommand?: (localPath: string, owner?: PluginId) => string | undefined;
-}>): CommandContext;
+/** Parsed invocation values, independent of the caller's transport and lifetime. */
+export interface CommandInvocationArguments {
+    readonly args: readonly string[];
+    readonly params?: Readonly<Record<string, CommandParameterValue>>;
+    readonly options?: Readonly<Record<string, CommandParameterValue>>;
+    readonly segments?: readonly Readonly<CommandSegment>[];
+}
+/** Author and lifetime authority captured by the dispatcher for this invocation. */
+export interface CommandInvocationOperation {
+    readonly snapshot: RuntimeSnapshot;
+    readonly ownerId: PluginId;
+    readonly input?: unknown;
+    readonly interaction?: UserInteraction;
+    readonly adapter?: string;
+    readonly presentation?: Readonly<{
+        locale: Locale;
+        formatCommand?: (localPath: string, owner?: PluginId) => string | undefined;
+    }>;
+}
+/** @internal Command dispatcher assembly helper; each value has one owner. */
+export declare function createCommandContext(operation: CommandInvocationOperation, invocation: CommandInvocationArguments): CommandContext;
 /**
  * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。
  * 不依赖 `@zhin.js/core`，按 {@link CommandMessage} 结构鸭式识别。

package/lib/definition.js

@@ -3,7 +3,7 @@
  * @module zhin.js/command
  */
 import { resolveLocale } from '@zhin.js/plugin-runtime';
-import { createCapabilityContext, readOperationClient, readOperationInputSignal, } from '@zhin.js/feature-kit';
+import { createCapabilityContext, readOperationClient, readOperationSession, readOperationInputSignal, } from '@zhin.js/feature-kit';
 import { assertPermitSyntax } from '@zhin.js/permission';
 import { validateArgumentSchemas } from './arguments.js';
 import { normalizeExecutionPolicy } from './execution-policy.js';
@@ -173,8 +173,10 @@ export function resolveDynamicParams(params, source) {
     }
     return Object.freeze(resolved);
 }
-/** @internal Command dispatcher assembly helper. */
-export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([]), interaction, adapter, options = Object.freeze({}), presentation) {
+/** @internal Command dispatcher assembly helper; each value has one owner. */
+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 session = resolveCommandSession(input);
     const parameterValues = { __proto__: null, ...params };
@@ -191,6 +193,10 @@ export function createCommandContext(snapshot, ownerId, args, params = Object.fr
         ...(input !== undefined ? { input: input } : {}),
         ...(interaction !== undefined ? { interaction } : {}),
     };
+    Object.defineProperty(result, 'session', {
+        enumerable: true,
+        get: () => readOperationSession(input, adapter),
+    });
     Object.defineProperty(result, '$client', {
         enumerable: true,
         get: () => readOperationClient(input, adapter),
@@ -203,6 +209,20 @@ export function createCommandContext(snapshot, ownerId, args, params = Object.fr
  * @internal Command dispatcher projection helper.
  */
 export function resolveCommandSession(input) {
+    const operation = readOperationSession(input);
+    if (operation) {
+        const endpoint = input && typeof input === 'object' ? input.endpointId : undefined;
+        const sender = operation.sender;
+        const roles = [...new Set([...sender?.authorizationRoles ?? [], ...sender?.platformRoles ?? []])];
+        return Object.freeze({
+            adapter: operation.scene.endpoint.adapter,
+            ...(typeof endpoint === 'string' && endpoint ? { endpoint } : {}),
+            scene: Object.freeze({ id: operation.scene.id, type: operation.scene.kind,
+                ...(operation.scene.name !== undefined ? { name: operation.scene.name } : {}) }),
+            ...(sender ? { sender: Object.freeze({ id: sender.id, ...(sender.name !== undefined ? { name: sender.name } : {}),
+                    role: Object.freeze(roles.length ? roles : ['user']) }) } : {}),
+        });
+    }
     if (!isCommandMessageLike(input))
         return Object.freeze({});
     const metadata = input.metadata && typeof input.metadata === 'object'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/command",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "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.9",
+    "@zhin.js/feature-kit": "1.1.11",
     "@zhin.js/interaction": "1.1.2",
-    "@zhin.js/permission": "1.1.9",
-    "@zhin.js/plugin-runtime": "1.1.17"
+    "@zhin.js/permission": "1.1.11",
+    "@zhin.js/plugin-runtime": "1.1.19"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/command-index.ts

@@ -58,6 +58,24 @@ export interface CommandDescriptor {
   readonly shortcut?: readonly string[];
 }
 
+/** One dispatch reads the caller's exact operation generation and presentation. */
+export interface CommandDispatchRequest {
+  readonly input: CommandMatchInput;
+  readonly source?: unknown;
+  readonly interactionFactory?: UserInteractionFactory;
+  readonly commandPrefix?: string;
+  readonly snapshot?: RuntimeSnapshot;
+  readonly locale?: Locale;
+}
+/** Presentation and generation shared across one menu lookup/render operation. */
+interface CommandMenuContext {
+  readonly commandPrefix: string;
+  readonly keyword: string;
+  readonly snapshot: RuntimeSnapshot;
+  readonly locale: Locale;
+}
+interface CommandMenuSelection { readonly pluginKey?: string; readonly page?: number }
+
 export interface CommandDispatchResult {
   readonly matched: boolean;
   readonly status: 'unmatched' | 'invalid' | 'denied' | 'limited' | 'executed';
@@ -323,26 +341,22 @@ export class CommandIndex {
     const admission = admitDirectCommandExecution(match.command.slot.id, match.command.execution, operationSnapshot);
     if (admission.limit) throw new CommandExecutionLimitedError(admission.limit);
     try {
-      return await definition.execute(createCommandContext(operationSnapshot, match.command.slot.owner,
-        textArgs(parsed.remaining), parsed.params, undefined, parsed.remaining, undefined, definition.adapter, parsed.options, { locale }));
+      return await definition.execute(createCommandContext({ snapshot: operationSnapshot, ownerId: match.command.slot.owner,
+        adapter: definition.adapter, presentation: { locale } }, {
+        args: textArgs(parsed.remaining), params: parsed.params, segments: parsed.remaining, options: parsed.options,
+      }));
     } finally {
       admission.release();
     }
   }
 
-  async dispatch(
-    input: CommandMatchInput,
-    source: unknown = undefined,
-    interactionFactory?: UserInteractionFactory,
-    commandPrefix?: string,
-    operationSnapshot: RuntimeSnapshot = this.snapshot,
-    localeOverride?: Locale,
-  ): Promise<CommandDispatchResult> {
+  async dispatch({ input, source, interactionFactory, commandPrefix, snapshot: operationSnapshot = this.snapshot,
+    locale: localeOverride }: CommandDispatchRequest): Promise<CommandDispatchResult> {
     const locale = localeOverride ?? commandLocale(source, operationSnapshot);
     const prefix = commandPrefix ?? '';
     if (this.#menu) {
       const keyword = this.#menu.keyword ?? commandMessages(locale, 'menuKeyword');
-      const menuResult = this.#dispatchMenu(input, prefix, operationSnapshot, locale, keyword);
+      const menuResult = this.#dispatchMenu(input, { commandPrefix: prefix, snapshot: operationSnapshot, locale, keyword });
       if (menuResult !== undefined) {
         return Object.freeze({
           matched: true,
@@ -381,10 +395,12 @@ 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(operationSnapshot, match.command.slot.owner,
-      textArgs(parsed.remaining), parsed.params, authorSource, parsed.remaining, interactionFactory?.(authorSource), definition.adapter, parsed.options,
-      { locale, formatCommand: (localPath, owner = match.command.owner) => this.formatCommand(owner, localPath,
-        source && typeof source === 'object' && 'conversation' in source ? commandPrefix : undefined, locale) }));
+    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 });
   }
 
@@ -496,10 +512,11 @@ export class CommandIndex {
   // 内置菜单命令
   // ==========================================================================
 
-  #dispatchMenu(input: CommandMatchInput, commandPrefix: string, snapshot: RuntimeSnapshot, locale: Locale, keyword: string): CommandMenuResult | undefined {
+  #dispatchMenu(input: CommandMatchInput, context: CommandMenuContext): CommandMenuResult | undefined {
+    const { commandPrefix, keyword, locale } = context;
     const text = typeof input === 'string' ? input.trim() : exactMessageText(input);
     if (text === undefined) return undefined;
-    if (text === keyword) return this.#buildMenu(undefined, commandPrefix, keyword, snapshot, locale);
+    if (text === keyword) return this.#buildMenu({}, context);
     if (text.startsWith(keyword + ' ')) {
       const key = text.slice(keyword.length + 1).trim();
       const args = key.split(/\s+/u);
@@ -510,15 +527,15 @@ export class CommandIndex {
           || !Number.isSafeInteger(Number(pageText))) {
           return { value: commandMessages(locale, 'invalidPage', { command: `${commandPrefix}${keyword}` }) };
         }
-        return this.#buildMenu(flag === 1 ? args[0] : undefined, commandPrefix, keyword, snapshot, locale, Number(pageText));
+        return this.#buildMenu({ pluginKey: flag === 1 ? args[0] : undefined, page: Number(pageText) }, context);
       }
-      if (key) return this.#buildMenu(key, commandPrefix, keyword, snapshot, locale);
-      return this.#buildMenu(undefined, commandPrefix, keyword, snapshot, locale);
+      if (key) return this.#buildMenu({ pluginKey: key }, context);
+      return this.#buildMenu({}, context);
     }
     return undefined;
   }
 
-  #buildMenu(pluginKey: string | undefined, commandPrefix: string, keyword: string, snapshot: RuntimeSnapshot, locale: Locale, page = 1): CommandMenuResult {
+  #buildMenu({ pluginKey, page = 1 }: CommandMenuSelection, { commandPrefix, keyword, snapshot, locale }: CommandMenuContext): CommandMenuResult {
     const root = snapshot.root;
     const targetId = pluginKey
       ? `${root}/${pluginKey.split('.').join('/')}` as PluginId

package/src/definition.ts

@@ -6,6 +6,8 @@ import { resolveLocale, type Locale, type PluginId, type RuntimeSnapshot } from
 import {
   createCapabilityContext,
   readOperationClient,
+  readOperationSession,
+  type OperationSession,
   readOperationInputSignal,
   type AdapterClient,
   type RegisteredAdapterName,
@@ -291,6 +293,8 @@ export interface CommandContext<
   readonly input?: TInput;
   /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
   readonly $client: AdapterClient<TAdapter>;
+  /** Bound by the actual IM operation; direct CommandIndex.execute calls may have no Session. */
+  readonly session: OperationSession<TAdapter> | undefined;
   /**
    * 对话式交互输入。IM 派发时自动注入；无消息来源时为 `undefined`。
    */
@@ -378,28 +382,40 @@ type TypedCommandContext<TConfig, TInput extends CommandMessage, TAdapter extend
     readonly options: InferCommandOptions<O>;
   };
 
+/** The returned declaration retains its platform, parameter schemas and callback result. */
+type DeclaredCommandAdapter<D> = D extends { readonly adapter: infer A extends string } ? A
+  : D extends { readonly adapter?: infer A extends string | undefined } ? A : undefined;
+export type TypedCommandDefinition<TConfig, TResult, TInput extends CommandMessage, TAdapter extends string | undefined, P extends CommandParams, O extends CommandOptions> =
+  Omit<CommandDefinition<TConfig, TResult, TInput, TAdapter>, 'params' | 'options' | 'execute'> & {
+    readonly params?: P;
+    readonly options?: O;
+    execute(context: TypedCommandContext<TConfig, TInput, TAdapter, P, O>): TResult | Promise<TResult>;
+  };
+
 /**
  * `defineCommand.withConfig<Config>()` 返回的定义函数：config 类型已固定，params / options / 返回值
  * 仍从定义推断。
  * @public
  */
 export type CommandDefiner<TConfig, TInput extends CommandMessage = CommandMessage> = <
-  TResult = unknown,
+  const TResult = unknown,
   const P extends CommandParams = {},
   const O extends CommandOptions = {},
+  const D extends CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> = CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>,
 >(
-  definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>,
-) => Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>>;
+  definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> & D,
+) => Readonly<TypedCommandDefinition<TConfig, TResult, TInput, DeclaredCommandAdapter<D>, P, O> & Pick<D, keyof D & 'adapter'>>;
 
 export function defineCommand<
   TConfig = unknown,
-  TResult = unknown,
+  const TResult = unknown,
   TInput extends CommandMessage = CommandMessage,
   const P extends CommandParams = {},
   const O extends CommandOptions = {},
+  const D extends CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> = CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>,
 >(
-  definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O>,
-): Readonly<CommandDefinition<TConfig, TResult, TInput, string | undefined>> {
+  definition: CommandAuthoringDefinition<TConfig, TResult, TInput, P, O> & D,
+): Readonly<TypedCommandDefinition<TConfig, TResult, TInput, DeclaredCommandAdapter<D>, P, O> & Pick<D, keyof D & 'adapter'>> {
   if (typeof definition.execute !== 'function') {
     throw new TypeError('Command execute must be a function');
   }
@@ -423,7 +439,7 @@ export function defineCommand<
   validateCommandShortcutShape(definition.shortcut);
   const execution = normalizeExecutionPolicy(definition.execution);
   return Object.freeze({ $feature: commandBrand, ...definition, ...(execution ? { execution } : {}) }) as Readonly<
-    CommandDefinition<TConfig, TResult, TInput, string | undefined>
+    TypedCommandDefinition<TConfig, TResult, TInput, DeclaredCommandAdapter<D>, P, O> & Pick<D, keyof D & 'adapter'>
   >;
 }
 
@@ -570,19 +586,31 @@ export function resolveDynamicParams(
   return Object.freeze(resolved);
 }
 
-/** @internal Command dispatcher assembly helper. */
-export function createCommandContext(
-  snapshot: RuntimeSnapshot,
-  ownerId: PluginId,
-  args: readonly string[],
-  params: Readonly<Record<string, CommandParameterValue>> = Object.freeze({}),
-  input: unknown = undefined,
-  segments: readonly Readonly<CommandSegment>[] = Object.freeze([]),
-  interaction?: UserInteraction,
-  adapter?: string,
-  options: Readonly<Record<string, CommandParameterValue>> = Object.freeze({}),
-  presentation?: Readonly<{ locale: Locale; formatCommand?: (localPath: string, owner?: PluginId) => string | undefined }>,
-): CommandContext {
+/** Parsed invocation values, independent of the caller's transport and lifetime. */
+export interface CommandInvocationArguments {
+  readonly args: readonly string[];
+  readonly params?: Readonly<Record<string, CommandParameterValue>>;
+  readonly options?: Readonly<Record<string, CommandParameterValue>>;
+  readonly segments?: readonly Readonly<CommandSegment>[];
+}
+
+/** Author and lifetime authority captured by the dispatcher for this invocation. */
+export interface CommandInvocationOperation {
+  readonly snapshot: RuntimeSnapshot;
+  readonly ownerId: PluginId;
+  readonly input?: unknown;
+  readonly interaction?: UserInteraction;
+  readonly adapter?: string;
+  readonly presentation?: Readonly<{
+    locale: Locale;
+    formatCommand?: (localPath: string, owner?: PluginId) => string | undefined;
+  }>;
+}
+
+/** @internal Command dispatcher assembly helper; each value has one owner. */
+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 session = resolveCommandSession(input);
   const parameterValues: Record<string, CommandParameterValue> = { __proto__: null, ...params };
@@ -599,6 +627,10 @@ export function createCommandContext(
     ...(input !== undefined ? { input: input as CommandMessage } : {}),
     ...(interaction !== undefined ? { interaction } : {}),
   } as CommandContext;
+  Object.defineProperty(result, 'session', {
+    enumerable: true,
+    get: () => readOperationSession(input, adapter),
+  });
   Object.defineProperty(result, '$client', {
     enumerable: true,
     get: () => readOperationClient(input, adapter),
@@ -612,6 +644,20 @@ export function createCommandContext(
  * @internal Command dispatcher projection helper.
  */
 export function resolveCommandSession(input: unknown): CommandSession {
+  const operation = readOperationSession(input);
+  if (operation) {
+    const endpoint = input && typeof input === 'object' ? (input as { readonly endpointId?: unknown }).endpointId : undefined;
+    const sender = operation.sender;
+    const roles = [...new Set([...sender?.authorizationRoles ?? [], ...sender?.platformRoles ?? []])];
+    return Object.freeze({
+      adapter: operation.scene.endpoint.adapter,
+      ...(typeof endpoint === 'string' && endpoint ? { endpoint } : {}),
+      scene: Object.freeze({ id: operation.scene.id, type: operation.scene.kind,
+        ...(operation.scene.name !== undefined ? { name: operation.scene.name } : {}) }),
+      ...(sender ? { sender: Object.freeze({ id: sender.id, ...(sender.name !== undefined ? { name: sender.name } : {}),
+        role: Object.freeze(roles.length ? roles : ['user']) }) } : {}),
+    });
+  }
   if (!isCommandMessageLike(input)) return Object.freeze({});
 
   const metadata = input.metadata && typeof input.metadata === 'object'