@zhin.js/command 1.1.7 → 1.1.8

package/src/definition.ts

@@ -6,6 +6,7 @@ import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import {
   createCapabilityContext,
   readOperationClient,
+  readOperationInputSignal,
   type AdapterClient,
   type RegisteredAdapterName,
   type CapabilityContext,
@@ -13,6 +14,8 @@ import {
 import { assertPermitSyntax } from '@zhin.js/permission';
 import { validateArgumentSchemas } from './arguments.js';
 import type { UserInteraction } from '@zhin.js/interaction';
+import { normalizeExecutionPolicy, type CommandExecutionPolicy } from './execution-policy.js';
+export type { CommandExecutionPolicy, CommandExecutionLimit } from './execution-policy.js';
 
 const commandBrand = 'zhin.command/1' as const;
 
@@ -309,6 +312,8 @@ export interface CommandDefinition<
    * 例：`adapter(icqq)`、`role(master)`、`group(123,456)`。
    */
   readonly permit?: readonly string[];
+  /** Optional full-operation cooldown, concurrency and one-shot progress feedback. */
+  readonly execution?: Readonly<CommandExecutionPolicy>;
   /**
    * 全局整句快捷方式：触发串（trim 后全文相等）→ 预填 params。
    * 与普通路由一样是全局用户输入，冲突会在 generation 构建时拒绝。
@@ -383,7 +388,8 @@ export function defineCommand<
   validateCommandAlias(definition.alias);
   validateCommandPermit(definition.permit);
   validateCommandShortcutShape(definition.shortcut);
-  return Object.freeze({ $feature: commandBrand, ...definition }) as Readonly<
+  const execution = normalizeExecutionPolicy(definition.execution);
+  return Object.freeze({ $feature: commandBrand, ...definition, ...(execution ? { execution } : {}) }) as Readonly<
     CommandDefinition<TConfig, TResult, TInput, string | undefined>
   >;
 }
@@ -464,6 +470,7 @@ export function parseCommandDefinition(value: unknown): CommandDefinition {
     throw new TypeError('Command module must default-export defineCommand(...)');
   }
   validateAdapterName(definition.adapter);
+  normalizeExecutionPolicy(definition.execution);
   return definition as CommandDefinition;
 }
 
@@ -496,7 +503,7 @@ export function createCommandContext(
   adapter?: string,
   options: Readonly<Record<string, CommandParameterValue>> = Object.freeze({}),
 ): CommandContext {
-  const context = createCapabilityContext(snapshot, ownerId);
+  const context = createCapabilityContext(snapshot, ownerId, undefined, readOperationInputSignal(input));
   const session = resolveCommandSession(input);
   const parameterValues: Record<string, CommandParameterValue> = { __proto__: null, ...params };
   const optionValues: Record<string, CommandParameterValue> = { __proto__: null, ...options };
@@ -534,7 +541,7 @@ export function resolveCommandSession(input: unknown): CommandSession {
     || (typeof metadata?.endpoint === 'string' && metadata.endpoint ? metadata.endpoint : undefined);
 
   const scene = resolveScene(input, metadata);
-  const sender = resolveSender(input, metadata);
+  const sender = resolveCommandSender(input, metadata);
 
   return Object.freeze({
     ...(adapter ? { adapter } : {}),
@@ -583,8 +590,12 @@ function resolveScene(
   });
 }
 
-function resolveSender(
-  input: CommandMessage,
+/**
+ * Pure canonical sender projection shared with read-only command condition simulation.
+ * @internal Command dispatcher projection helper.
+ */
+export function resolveCommandSender(
+  input: Pick<CommandMessage, 'sender'>,
   metadata: Readonly<Record<string, unknown>> | undefined,
 ): CommandSender | undefined {
   const structured = (input as { readonly from?: unknown }).from;
@@ -606,7 +617,7 @@ function resolveSender(
 }
 
 function resolveRoles(
-  input: CommandMessage,
+  input: Pick<CommandMessage, 'sender'>,
   metadata: Readonly<Record<string, unknown>> | undefined,
 ): readonly string[] {
   if (input.sender?.roles?.length) {

package/src/execution-policy.ts

@@ -0,0 +1,39 @@
+/** Optional per-capability budget, isolated by sender and the complete conversation identity. */
+export interface CommandExecutionPolicy {
+  readonly cooldownMs?: number;
+  readonly maxConcurrent?: number;
+  /** One best-effort progress message while business logic is waiting; disabled by default. */
+  readonly progressAfterMs?: number;
+}
+
+export interface CommandExecutionLimit {
+  readonly reason: 'cooldown' | 'busy' | 'capacity' | 'operation_unavailable' | 'identity_unavailable' | 'service_unavailable';
+  /** Exact remaining cooldown; a busy operation has no predictable completion time. */
+  readonly retryAfterMs?: number;
+}
+
+export class CommandExecutionLimitedError extends Error {
+  readonly limit: CommandExecutionLimit;
+  constructor(limit: CommandExecutionLimit) {
+    super(`Command execution limited: ${limit.reason}`);
+    this.name = 'CommandExecutionLimitedError';
+    this.limit = limit;
+  }
+}
+
+/** @internal Validate at declaration and projection, without coercion or silent clamping. */
+export function normalizeExecutionPolicy(value: unknown): Readonly<CommandExecutionPolicy> | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('Command execution must be an object');
+  const limits = { cooldownMs: 86_400_000, maxConcurrent: 1000, progressAfterMs: 3_600_000 };
+  const result: Record<string, number> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (!Object.hasOwn(limits, key) || !Number.isSafeInteger(item) || (item as number) <= 0
+      || (item as number) > limits[key as keyof typeof limits]) {
+      throw new TypeError(`Command execution.${key} must be a positive bounded integer`);
+    }
+    result[key] = item as number;
+  }
+  if (Object.keys(result).length === 0) throw new TypeError('Command execution requires at least one policy');
+  return Object.freeze(result);
+}

package/src/execution-runtime.ts

@@ -0,0 +1,165 @@
+/** Internal composition contract. Not part of the command authoring facade. */
+import { createToken, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { CommandExecutionLimit, CommandExecutionPolicy } from './execution-policy.js';
+
+interface ConversationIdentity {
+  readonly endpoint: { readonly adapter: string; readonly id: string };
+  readonly kind: string;
+  readonly id: string;
+  readonly parent?: { readonly kind: string; readonly id: string };
+  readonly threadId?: string;
+}
+
+interface AdmissionReader {
+  admit(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined;
+}
+
+/** @internal Admission-only Root resource; no bind or finish authority is published. */
+export const commandExecutionAdmissionToken = createToken<AdmissionReader>('zhin.command.execution-admission');
+
+/** @internal Held only by Core's actual leased operation. */
+export interface CommandOperationController {
+  bind(view: object, owner: PluginId): void;
+  /** Core registers actual started delivery promises, never a caller-supplied completion callback. */
+  trackSend(send: Promise<unknown>): void;
+  /** Stop pending feedback and drain already-started feedback before the final reply. */
+  stopProgress(): Promise<void>;
+  /** Called only by the real outer operation's finally, after all final sends settle. */
+  finish(): Promise<void>;
+}
+
+interface Entry { active: number; cooldownUntil: number }
+interface Operation {
+  snapshot?: RuntimeSnapshot;
+  key?: readonly string[];
+  active: boolean;
+  progressStopped: boolean;
+  admitted: boolean;
+  signal: AbortSignal;
+  reply?: (owner: PluginId, text: string) => Promise<unknown>;
+  readonly releases: (() => void)[];
+  readonly timers: Set<ReturnType<typeof setTimeout>>;
+  readonly feedback: Promise<void>[];
+  readonly accepted: Set<string>;
+  readonly sends: Set<Promise<void>>;
+}
+
+/** @internal Root-instance-owned state shared by projections and draining retired generations. */
+export class CommandExecutionBudget {
+  readonly #entries = new Map<string, Entry>();
+  readonly #views = new WeakMap<object, { operation: Operation; owner: PluginId }>();
+  readonly #clock: () => number;
+  readonly #capacity: number;
+  readonly admission: AdmissionReader;
+
+  constructor(options: { readonly clock?: () => number; readonly capacity?: number } = {}) {
+    this.#clock = options.clock ?? (() => performance.now());
+    this.#capacity = options.capacity ?? 10_000;
+    if (!Number.isSafeInteger(this.#capacity) || this.#capacity < 1) throw new TypeError('Invalid command budget capacity');
+    this.admission = Object.freeze<AdmissionReader>({ admit: (source, capability, owner, policy, snapshot) => this.#admit(source, capability, owner, policy, snapshot) });
+  }
+
+  openOperation(input: {
+    readonly snapshot: RuntimeSnapshot;
+    readonly conversation: ConversationIdentity;
+    readonly senderId?: string;
+    readonly retirementSignal: AbortSignal;
+    readonly reply: (owner: PluginId, text: string) => Promise<unknown>;
+  }): CommandOperationController {
+    const c = input.conversation;
+    const values = [c.endpoint.adapter, c.endpoint.id, c.kind, c.id, c.parent?.kind ?? '', c.parent?.id ?? '', c.threadId ?? '', input.senderId ?? ''];
+    const valid = values.slice(0, 4).every(nonempty) && ['private', 'group', 'channel'].includes(c.kind) && nonempty(input.senderId)
+      && (c.parent === undefined || (nonempty(c.parent.kind) && nonempty(c.parent.id)))
+      && (c.threadId === undefined || nonempty(c.threadId)) && values.every(value => value.length <= 1024);
+    const operation: Operation = {
+      snapshot: input.snapshot, key: valid ? Object.freeze(values) : undefined,
+      active: true, progressStopped: false, admitted: false, signal: input.retirementSignal,
+      reply: input.reply, releases: [], timers: new Set(), feedback: [], accepted: new Set(), sends: new Set(),
+    };
+    const stop = () => {
+      operation.progressStopped = true;
+      for (const timer of operation.timers) clearTimeout(timer);
+      operation.timers.clear();
+    };
+    input.retirementSignal.addEventListener('abort', stop, { once: true });
+    return Object.freeze({
+      bind: (view: object, owner: PluginId) => { if (operation.active) this.#views.set(view, { operation, owner }); },
+      trackSend: (send: Promise<unknown>) => {
+        if (!operation.active) return;
+        const settled = send.then(() => { operation.sends.delete(settled); }, () => { operation.sends.delete(settled); });
+        operation.sends.add(settled);
+      },
+      stopProgress: async () => { stop(); await Promise.all(operation.feedback); },
+      finish: async () => {
+        stop();
+        await Promise.all(operation.feedback);
+        // New sends may start while an earlier send is draining. Do not release from an initial snapshot alone.
+        if (operation.admitted) while (operation.sends.size > 0) await Promise.all(operation.sends);
+        if (!operation.active) return;
+        operation.active = false;
+        operation.signal.removeEventListener('abort', stop);
+        for (const release of operation.releases) release();
+        operation.releases.length = 0;
+        operation.feedback.length = 0;
+        operation.accepted.clear();
+        operation.sends.clear();
+        operation.reply = undefined;
+        operation.snapshot = undefined;
+        operation.key = undefined;
+      },
+    });
+  }
+
+  #admit(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined {
+    const binding = source !== null && typeof source === 'object' ? this.#views.get(source) : undefined;
+    const operation = binding?.operation;
+    if (!operation?.active || operation.snapshot !== snapshot || binding?.owner !== owner || operation.signal.aborted) return limited('operation_unavailable');
+    if (!operation.key) return limited('identity_unavailable');
+    const key = JSON.stringify([capability, ...operation.key]);
+    // Re-entering the same capability is a second attempt, rather than a second free execution.
+    const now = this.#clock();
+    let entry = this.#entries.get(key);
+    if (entry && policy.maxConcurrent !== undefined && entry.active >= policy.maxConcurrent) return limited('busy');
+    if (entry && entry.cooldownUntil > now) return Object.freeze({ reason: 'cooldown', retryAfterMs: Math.ceil(entry.cooldownUntil - now) });
+    if (!entry) {
+      if (this.#entries.size >= this.#capacity) {
+        for (const [oldKey, old] of this.#entries) if (old.active === 0 && old.cooldownUntil <= now) this.#entries.delete(oldKey);
+        if (this.#entries.size >= this.#capacity) return limited('capacity');
+      }
+      entry = { active: 0, cooldownUntil: 0 };
+      this.#entries.set(key, entry);
+    }
+    entry.active++;
+    operation.admitted = true;
+    entry.cooldownUntil = now + (policy.cooldownMs ?? 0);
+    const acceptedEntry = entry;
+    operation.releases.push(() => {
+      acceptedEntry.active--;
+      if (acceptedEntry.active === 0 && acceptedEntry.cooldownUntil <= this.#clock()) this.#entries.delete(key);
+    });
+    if (policy.progressAfterMs !== undefined && !operation.progressStopped && !operation.accepted.has(capability)) {
+      const timer = setTimeout(() => {
+        operation.timers.delete(timer);
+        if (!operation.active || operation.progressStopped || operation.signal.aborted || !operation.reply) return;
+        // Observe failure once. Never retry uncertain delivery and never expose the exception.
+        let send: Promise<void>;
+        try { send = Promise.resolve(operation.reply(owner, '正在处理中，请稍候。')).then(() => {}, () => {}); }
+        catch { send = Promise.resolve(); }
+        operation.feedback.push(send);
+      }, policy.progressAfterMs);
+      operation.timers.add(timer);
+    }
+    operation.accepted.add(capability);
+    return undefined;
+  }
+}
+
+function nonempty(value: unknown): value is string { return typeof value === 'string' && value.length > 0; }
+function limited(reason: CommandExecutionLimit['reason']): CommandExecutionLimit { return Object.freeze({ reason }); }
+
+/** @internal Projection reads the Root resource; ordinary authoring values cannot bind an operation. */
+export function admitCommandExecution(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy | undefined, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined {
+  if (!policy) return undefined;
+  const reader = snapshot.resources.get(snapshot.root)?.get(commandExecutionAdmissionToken.id) as AdmissionReader | undefined;
+  return reader ? reader.admit(source, capability, owner, policy, snapshot) : limited('service_unavailable');
+}

package/src/index.ts

@@ -6,6 +6,7 @@
 export * from './command-index.js';
 /** @public Command authoring contract and `defineCommand`. */
 export * from './definition.js';
+export * from './permission-explanation.js';
 export {
   assertBuiltinPermits,
   checkBuiltinPermit,

package/src/permission-explanation.ts

@@ -0,0 +1,58 @@
+import { operationClientAdapter } from '@zhin.js/feature-kit';
+import { explainPermitRules, toPermissionSubject, type PermissionSubject, type PermissionConditionExplanation } from '@zhin.js/permission';
+import { resolveCommandSender, resolveCommandSession, type CommandMessage } from './definition.js';
+import type { CommandDescriptor } from './command-index.js';
+
+/** The exact subject projection used by the real command permit gate. No factories or checkers run. */
+export function toCommandPermissionSubject(source: unknown): PermissionSubject {
+  const projected = toPermissionSubject(source);
+  const session = resolveCommandSession(source);
+  return { ...projected, ...session, ...(session.sender ? { sender: { ...projected.sender, ...session.sender } } : {}) };
+}
+
+/** Exact authoring adapter restriction, distinct from builtin adapter(...) matching. */
+export function commandAdapterMatches(command: Readonly<{ adapter?: string }>, source: unknown): boolean {
+  return !command.adapter || operationClientAdapter(source) === command.adapter;
+}
+
+export type CommandPermissionHostStatus = 'present' | 'missing' | 'unverified';
+
+/** Read-only hypothetical conditions. A match is not permission to execute the command. */
+export function explainCommandPermissions(
+  command: Pick<CommandDescriptor, 'adapter' | 'permit'>,
+  options: Readonly<{ source?: unknown; rolesKnown?: boolean; permissionHost: CommandPermissionHostStatus }>,
+) {
+  const projected = toCommandPermissionSubject(options.source);
+  const inputSender = options.source && typeof options.source === 'object'
+    ? (options.source as Pick<CommandMessage, 'sender'>).sender : undefined;
+  const structuredRoles = inputSender && typeof inputSender === 'object'
+    && Array.isArray((inputSender as { readonly role?: unknown }).role);
+  // A sender-only assumption has no synthetic conversation. Apply the real canonical
+  // sender defaults without inventing an Endpoint or treating unknown roles as known.
+  const senderOnly = options.source && typeof options.source === 'object' && !('conversation' in options.source) && !structuredRoles
+    ? resolveCommandSender(options.source as Pick<CommandMessage, 'sender'>, undefined) : undefined;
+  const subject = senderOnly ? { ...projected, sender: senderOnly } : projected;
+  const defaultedRoles = options.rolesKnown && Array.isArray(inputSender?.roles) && inputSender.roles.length === 0
+    && subject.sender?.role.length === 1 && subject.sender.role[0] === 'user';
+  const actualAdapter = operationClientAdapter(options.source);
+  const adapter: PermissionConditionExplanation = !command.adapter
+    ? { outcome: 'not_evaluated', reason: '命令未声明 adapter 约束' }
+    : !actualAdapter ? { outcome: 'unknown', reason: '未选择当前 Endpoint，无法判断命令的精确 adapter 约束' }
+      : { outcome: commandAdapterMatches(command, options.source) ? 'match' : 'mismatch', reason: '命令 adapter 与当前 Endpoint 声明的原生适配器精确比较；未探测在线状态' };
+  const rules = explainPermitRules(command.permit ?? [], subject, { rolesKnown: options.rolesKnown });
+  const conditions = [...(command.adapter ? [adapter] : []), ...rules];
+  let summary: PermissionConditionExplanation;
+  if (conditions.some(item => item.outcome === 'mismatch')) summary = { outcome: 'mismatch', reason: '至少一个声明条件与假设输入不符；这不是实际准入检查' };
+  else if ((rules.length > 0 && options.permissionHost !== 'present') || conditions.some(item => item.outcome === 'unknown')) {
+    summary = { outcome: 'unknown', reason: rules.length > 0 && options.permissionHost !== 'present'
+      ? 'PermissionHost 缺失或无法确认；不能推断命令可执行' : '存在缺少依据的条件，不能推断命令可执行' };
+  } else if (rules.length === 0) summary = { outcome: 'not_evaluated', reason: '命令未声明 permit 限制；这不表示已获得执行权限' };
+  else if (conditions.some(item => item.outcome === 'not_evaluated')) summary = { outcome: 'not_evaluated', reason: '存在未执行的平台或自定义条件，不能推断命令可执行' };
+  else summary = { outcome: 'match', reason: '已解释的 builtin 条件与假设输入匹配；不代表真实授权或命令可执行' };
+  return Object.freeze({ permissionHost: options.permissionHost, adapter: Object.freeze(adapter), rules, summary: Object.freeze(summary),
+    unconstrained: Object.freeze(['已解释的 builtin 规则不检查具体 Endpoint、parent 或 thread；保留完整目标不等于这些维度受规则限制']),
+    assumptions: Object.freeze(['身份与角色仅用于模拟，未向平台核实', '未执行命令、动态默认值、平台或自定义 checker',
+      ...(defaultedRoles
+        ? ['canonical 输入未附角色时按命令运行时默认 user 解释；这不是已核验的平台角色'] : [])]),
+  });
+}