@open-mercato/ai-assistant 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3045.b4b3320cc2

package/src/modules/ai_assistant/lib/types.ts

@@ -16,6 +16,14 @@ export interface McpToolContext {
   apiKeySecret?: string
   /** Session token for memory layer (deduplication of search/GET calls) */
   sessionId?: string
+  /**
+   * Back-reference to the tool definition the handler is executing. Populated
+   * by the runtime (`tool-executor`, `pending-action-executor`, the agent-tools
+   * dispatcher, and the test runner) so handlers can construct an
+   * `AiToolExecutionContext` for `createAiApiOperationRunner` without losing
+   * `requiredFeatures` coverage at the route gate.
+   */
+  tool?: AiToolDefinition
 }
 
 /**
@@ -35,7 +43,37 @@ export interface McpToolDefinition<TInput = unknown, TOutput = unknown> {
 }
 
 /**
- * Alias for McpToolDefinition - use in ai-tools.ts files.
+ * Per-record batch-diff descriptor returned by `loadBeforeRecords` on a bulk
+ * mutation tool (Step 5.6 `prepareMutation`). Shape is a strict prefix of the
+ * stored `AiPendingActionRecordDiff` — `prepareMutation` fills in the per-field
+ * diff itself after matching the patch payload from `toolCallArgs.records[]`.
+ */
+export interface AiToolLoadBeforeRecord {
+  recordId: string
+  entityType: string
+  label: string
+  recordVersion: string | null
+  before: Record<string, unknown>
+}
+
+/**
+ * Single-record before-snapshot returned by `loadBeforeRecord` on a mutation
+ * tool. Used by `prepareMutation` to compute a per-field diff against the
+ * proposed patch in `toolCallArgs`. Tools that do not declare this resolver
+ * fall back to `fieldDiff: []` with a `sideEffectsSummary` warning.
+ */
+export interface AiToolLoadBeforeSingleRecord {
+  recordId: string
+  entityType: string
+  recordVersion: string | null
+  before: Record<string, unknown>
+}
+
+/**
+ * Public MCP-compatible tool definition consumed by `ai-tools.ts` files and
+ * `defineAiTool()`. Extends `McpToolDefinition` with optional focused-agent
+ * metadata. All additive fields are optional so existing plain-object
+ * definitions remain valid and backward compatible.
  *
  * @example
  * ```typescript
@@ -44,7 +82,72 @@ export interface McpToolDefinition<TInput = unknown, TOutput = unknown> {
  * export const aiTools: AiToolDefinition[] = [...]
  * ```
  */
-export type AiToolDefinition<TInput = unknown, TOutput = unknown> = McpToolDefinition<TInput, TOutput>
+export interface AiToolDefinition<TInput = unknown, TOutput = unknown>
+  extends McpToolDefinition<TInput, TOutput> {
+  /** Human-friendly label for UI surfaces (falls back to `name`). */
+  displayName?: string
+  /** Free-form tags used by routing/search layers (e.g. `['read', 'catalog']`). */
+  tags?: string[]
+  /**
+   * True when the tool performs a mutation. Defaults to false.
+   * Mutation-capable tools are not automatically allowed in v1 focused agents
+   * and must be explicitly whitelisted via the agent's `allowedTools`.
+   */
+  isMutation?: boolean
+  /**
+   * True when the tool acts on multiple records in a single call. Routes the
+   * `prepareMutation` wrapper into the batch code path (Step 5.6) — the tool
+   * MUST carry `loadBeforeRecords` and emit a `records[]` array in its input.
+   * Defaults to `false`.
+   */
+  isBulk?: boolean
+  /**
+   * Marks a mutation as destructive. Honored by the agent's
+   * `mutationPolicy` gate:
+   *
+   *   - `read-only`               → tool blocked (regardless of this flag).
+   *   - `confirm-required`        → every mutation requires approval (this
+   *                                 flag is ignored — every write gates).
+   *   - `destructive-confirm-required` → tools require approval ONLY when
+   *                                 this flag resolves to `true`. Other
+   *                                 mutations execute directly.
+   *
+   * Accepts either:
+   *   - a static `boolean` (whole tool is destructive or not), OR
+   *   - a predicate `(input) => boolean` evaluated at every call so a
+   *     multi-operation tool (e.g. `customers.manage_deal_comment` with
+   *     `operation: 'create' | 'update' | 'delete'`) can gate ONLY the
+   *     destructive branches without splitting into multiple tools.
+   *
+   * Default `false`. Tool authors that delete data, change ownership, or
+   * trigger irreversible side-effects MUST set this — boolean `true` for
+   * single-operation tools, predicate for multi-operation tools.
+   */
+  isDestructive?: boolean | ((input: TInput) => boolean)
+  /**
+   * Optional single-record before-snapshot resolver used by `prepareMutation`
+   * to compute a `fieldDiff[]` against the proposed patch in `toolCallArgs`.
+   * When absent, the preview card ships with `fieldDiff: []` and a
+   * `sideEffectsSummary` fallback message (spec Phase 3 WS-C §9).
+   */
+  loadBeforeRecord?: (
+    input: TInput,
+    context: McpToolContext,
+  ) => Promise<AiToolLoadBeforeSingleRecord | null>
+  /**
+   * Optional batch before-snapshot resolver used by `prepareMutation` when
+   * `isBulk === true`. Returns one entry per record being touched; each entry
+   * is diffed against the matching patch shape inside `toolCallArgs.records[]`.
+   */
+  loadBeforeRecords?: (
+    input: TInput,
+    context: McpToolContext,
+  ) => Promise<AiToolLoadBeforeRecord[]>
+  /** Optional per-turn call budget enforced by the focused-agent runtime. */
+  maxCallsPerTurn?: number
+  /** Declares the tool can receive resolved attachment parts at runtime. */
+  supportsAttachments?: boolean
+}
 
 /**
  * Options for tool registration.