@futdevpro/fsm-dynamo 1.15.17 → 1.15.20

package/src/_modules/ai/_models/ai-llm-request.interface.ts

@@ -1,24 +1,24 @@
-import { DyFM_AI_Message } from './ai-message.interface';
-import { DyFM_AI_CallSettings } from './ai-call-settings.interface';
-
-/**
- * Generic LLM request structure
- * Used by all AI providers for LLM operations
- */
-export interface DyFM_AI_LLM_Request {
-  messages: DyFM_AI_Message[];
-  settings?: DyFM_AI_CallSettings;
-  issuer: string;
-  debugLog?: boolean;
-}
-
-/**
- * Simple LLM request with system and user messages
- */
-export interface DyFM_AI_LLM_Simple_Request {
-  systemMessage: string;
-  userMessage: string;
-  settings?: DyFM_AI_CallSettings;
-  issuer: string;
-  debugLog?: boolean;
-}
+import { DyFM_AI_Message } from './ai-message.interface';
+import { DyFM_AI_CallSettings } from './ai-call-settings.interface';
+
+/**
+ * Generic LLM request structure
+ * Used by all AI providers for LLM operations
+ */
+export interface DyFM_AI_LLM_Request {
+  messages: DyFM_AI_Message[];
+  settings?: DyFM_AI_CallSettings;
+  issuer: string;
+  debugLog?: boolean;
+}
+
+/**
+ * Simple LLM request with system and user messages
+ */
+export interface DyFM_AI_LLM_Simple_Request {
+  systemMessage: string;
+  userMessage: string;
+  settings?: DyFM_AI_CallSettings;
+  issuer: string;
+  debugLog?: boolean;
+}

package/src/_modules/ai/_models/ai-llm-response.interface.ts

@@ -1,30 +1,30 @@
-import { DyFM_AI_Message } from './ai-message.interface';
-import { DyFM_AI_ToolCall } from './ai-tool-call.interface';
-
-/**
- * Generic LLM response structure
- * Used by all AI providers for LLM operations
- */
-export interface DyFM_AI_LLM_Response {
-  content: string;
-  usage?: {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-  };
-  model?: string;
-  finishReason?: string;
-  /** Present when the model requested tool calls (function calling); normalized across providers. */
-  toolCalls?: DyFM_AI_ToolCall[];
-  /** Normalized stop reason (e.g. 'tool_use', 'stop', 'length'). */
-  stopReason?: string;
-  rawResponse?: any; // Provider-specific raw response
-}
-
-/**
- * Raw LLM response with full provider details
- */
-export interface DyFM_AI_LLM_Raw_Response extends DyFM_AI_LLM_Response {
-  messages: DyFM_AI_Message[];
-  rawResponse: any;
-}
+import { DyFM_AI_Message } from './ai-message.interface';
+import { DyFM_AI_ToolCall } from './ai-tool-call.interface';
+
+/**
+ * Generic LLM response structure
+ * Used by all AI providers for LLM operations
+ */
+export interface DyFM_AI_LLM_Response {
+  content: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  model?: string;
+  finishReason?: string;
+  /** Present when the model requested tool calls (function calling); normalized across providers. */
+  toolCalls?: DyFM_AI_ToolCall[];
+  /** Normalized stop reason (e.g. 'tool_use', 'stop', 'length'). */
+  stopReason?: string;
+  rawResponse?: any; // Provider-specific raw response
+}
+
+/**
+ * Raw LLM response with full provider details
+ */
+export interface DyFM_AI_LLM_Raw_Response extends DyFM_AI_LLM_Response {
+  messages: DyFM_AI_Message[];
+  rawResponse: any;
+}

package/src/_modules/ai/_models/ai-message.interface.ts

@@ -1,12 +1,12 @@
-import { DyFM_AI_MessageRole } from '../_enums/ai-message-role.enum';
-import { DyFM_AI_ToolCall } from './ai-tool-call.interface';
-
-export interface DyFM_AI_Message {
-  role: DyFM_AI_MessageRole;
-  content: string;
-  /** Present on an assistant turn that requested tool calls (function calling). */
-  toolCalls?: DyFM_AI_ToolCall[];
-  /** Present on a `tool`-role message — which {@link DyFM_AI_ToolCall.id} this result answers. */
-  toolCallId?: string;
-}
-
+import { DyFM_AI_MessageRole } from '../_enums/ai-message-role.enum';
+import { DyFM_AI_ToolCall } from './ai-tool-call.interface';
+
+export interface DyFM_AI_Message {
+  role: DyFM_AI_MessageRole;
+  content: string;
+  /** Present on an assistant turn that requested tool calls (function calling). */
+  toolCalls?: DyFM_AI_ToolCall[];
+  /** Present on a `tool`-role message — which {@link DyFM_AI_ToolCall.id} this result answers. */
+  toolCallId?: string;
+}
+

package/src/_modules/ai/_models/ai-model-capabilities.interface.ts

@@ -1,27 +1,35 @@
-/**
- * Per-model capability flags.
- *
- * Where {@link DyFM_AI_ProviderCapabilities} describes what a PROVIDER can do
- * in aggregate, this describes what a single concrete MODEL supports. This is
- * the honest source of truth for feature-gating: e.g. an embedding model has
- * functionCalling=false, a reasoning chat model has functionCalling=true, a
- * local generic model may have functionCalling decided at runtime.
- */
-export interface DyFM_AI_ModelCapabilities {
-  /** Native function calling / tool use. The driver for the tool-calling feature. */
-  functionCalling: boolean;
-  /** Image input (vision). */
-  vision: boolean;
-  /** Streaming responses. */
-  streaming: boolean;
-  /** Structured output / JSON mode (OpenAI structured outputs, Gemini responseSchema, etc.). */
-  jsonMode: boolean;
-  /** Audio input (speech-to-text / audio understanding). */
-  audioInput: boolean;
-  /** Audio output (text-to-speech / speech generation). */
-  audioOutput: boolean;
-  /** Image generation (the model produces images). */
-  imageGeneration: boolean;
-  /** Embedding generation (vector output). */
-  embeddings: boolean;
-}
+/**
+ * Per-model capability flags.
+ *
+ * Where {@link DyFM_AI_ProviderCapabilities} describes what a PROVIDER can do
+ * in aggregate, this describes what a single concrete MODEL supports. This is
+ * the honest source of truth for feature-gating: e.g. an embedding model has
+ * functionCalling=false, a reasoning chat model has functionCalling=true, a
+ * local generic model may have functionCalling decided at runtime.
+ */
+export interface DyFM_AI_ModelCapabilities {
+  /** Native function calling / tool use. The driver for the tool-calling feature. */
+  functionCalling: boolean;
+  /** Image input (vision). */
+  vision: boolean;
+  /** Streaming responses. */
+  streaming: boolean;
+  /** Structured output / JSON mode (OpenAI structured outputs, Gemini responseSchema, etc.). */
+  jsonMode: boolean;
+  /** Audio input (speech-to-text / audio understanding). */
+  audioInput: boolean;
+  /** Audio output (text-to-speech / speech generation). */
+  audioOutput: boolean;
+  /** Image generation (the model produces images). */
+  imageGeneration: boolean;
+  /** Embedding generation (vector output). */
+  embeddings: boolean;
+  /**
+   * Can generate adult / uncensored / NSFW content (no content-policy refusal on
+   * mature themes). Mainstream cloud models (OpenAI, Anthropic, Google) are filtered
+   * → false. Uncensored / local models may set true. Used for content-routing and
+   * age-gating (e.g. Adventor mature mode). For generic local models this is
+   * model-dependent — confirm per loaded model rather than assume.
+   */
+  adultContent: boolean;
+}

package/src/_modules/ai/_models/ai-model-info.interface.ts

@@ -1,63 +1,63 @@
-import { DyFM_AI_Provider } from '../_enums/ai-provider.enum';
-import { DyFM_AI_ModelType } from '../_enums/ai-model-type.enum';
-import { DyFM_AI_ModelCapabilities } from './ai-model-capabilities.interface';
-import { DyFM_AI_ModelSettingsSchema } from './ai-model-settings-schema.interface';
-
-/**
- * Lifecycle status of a model in the provider's catalogue.
- *
- * `ga` — generally available, recommended for new work.
- * `preview` — available but pre-GA (API/behaviour may change).
- * `deprecated` — still callable but on a sunset path; prefer {@link DyFM_AI_ModelInfo.successorId}.
- */
-export type DyFM_AI_ModelStatus = 'ga' | 'preview' | 'deprecated';
-
-/**
- * Single-model descriptor for the provider model registry.
- *
- * The provider registries (`DyFM_OAI_Models`, `DyFM_AAI_Models`, …) are arrays
- * of these — an SDK-free, data-only source of truth for which models exist and
- * what each can do. The bare model enums (`DyFM_OAI_Model`, …) remain the typed
- * id keys; a registry entry's `id` references one of those values.
- *
- * Note: model line-ups churn fast (see the 2026-06 research) — keep the registry
- * current and rely on `status`/`successorId` rather than silently breaking on a
- * retired id.
- */
-export interface DyFM_AI_ModelInfo {
-  /** Exact API model string (e.g. 'gpt-5.5', 'claude-opus-4-8', 'gemini-3.5-flash'). */
-  id: string;
-  /** The provider that serves this model. */
-  provider: DyFM_AI_Provider;
-  /** The kind of model (chat / embedding / image / audio). */
-  modelType: DyFM_AI_ModelType;
-  /** What this specific model can DO (feature gates). */
-  capabilities: DyFM_AI_ModelCapabilities;
-  /**
-   * RESERVED (FR-048) — which tuning PARAMETERS this model accepts/rejects.
-   *
-   * Sibling of {@link capabilities}. NOT populated by FR-047 and NOT yet
-   * consumed by any reconciler — reserved space for the future per-model
-   * agnostic settings system. Each model accepts a different settings surface
-   * (e.g. Opus 4.7+ rejects temperature/topP/topK; reasoning models add
-   * reasoningEffort), and that knowledge must be curated continuously like the
-   * model registry itself.
-   *
-   * See: `__agent/feature-requests/FR-048-per-model-agnostic-settings.md`
-   */
-  settingsSchema?: DyFM_AI_ModelSettingsSchema;
-  /** Input context window in tokens, if applicable. */
-  contextWindow?: number;
-  /** Maximum output tokens, if applicable. */
-  maxOutputTokens?: number;
-  /** Lifecycle status; defaults to `ga` when omitted. */
-  status?: DyFM_AI_ModelStatus;
-  /** When `deprecated`/sunsetting, the recommended replacement model id. */
-  successorId?: string;
-  /** When `deprecated`, the earliest known shutdown date (ISO yyyy-mm-dd). */
-  sunsetDate?: string;
-  /** Human-readable name for UI (e.g. 'GPT-5.5', 'Claude Opus 4.8'). */
-  displayName?: string;
-  /** Provider-specific tier label (e.g. 'flagship', 'mini', 'Opus', 'Sonnet', 'Haiku'). */
-  tier?: string;
-}
+import { DyFM_AI_Provider } from '../_enums/ai-provider.enum';
+import { DyFM_AI_ModelType } from '../_enums/ai-model-type.enum';
+import { DyFM_AI_ModelCapabilities } from './ai-model-capabilities.interface';
+import { DyFM_AI_ModelSettingsSchema } from './ai-model-settings-schema.interface';
+
+/**
+ * Lifecycle status of a model in the provider's catalogue.
+ *
+ * `ga` — generally available, recommended for new work.
+ * `preview` — available but pre-GA (API/behaviour may change).
+ * `deprecated` — still callable but on a sunset path; prefer {@link DyFM_AI_ModelInfo.successorId}.
+ */
+export type DyFM_AI_ModelStatus = 'ga' | 'preview' | 'deprecated';
+
+/**
+ * Single-model descriptor for the provider model registry.
+ *
+ * The provider registries (`DyFM_OAI_Models`, `DyFM_AAI_Models`, …) are arrays
+ * of these — an SDK-free, data-only source of truth for which models exist and
+ * what each can do. The bare model enums (`DyFM_OAI_Model`, …) remain the typed
+ * id keys; a registry entry's `id` references one of those values.
+ *
+ * Note: model line-ups churn fast (see the 2026-06 research) — keep the registry
+ * current and rely on `status`/`successorId` rather than silently breaking on a
+ * retired id.
+ */
+export interface DyFM_AI_ModelInfo {
+  /** Exact API model string (e.g. 'gpt-5.5', 'claude-opus-4-8', 'gemini-3.5-flash'). */
+  id: string;
+  /** The provider that serves this model. */
+  provider: DyFM_AI_Provider;
+  /** The kind of model (chat / embedding / image / audio). */
+  modelType: DyFM_AI_ModelType;
+  /** What this specific model can DO (feature gates). */
+  capabilities: DyFM_AI_ModelCapabilities;
+  /**
+   * RESERVED (FR-048) — which tuning PARAMETERS this model accepts/rejects.
+   *
+   * Sibling of {@link capabilities}. NOT populated by FR-047 and NOT yet
+   * consumed by any reconciler — reserved space for the future per-model
+   * agnostic settings system. Each model accepts a different settings surface
+   * (e.g. Opus 4.7+ rejects temperature/topP/topK; reasoning models add
+   * reasoningEffort), and that knowledge must be curated continuously like the
+   * model registry itself.
+   *
+   * See: `__agent/feature-requests/FR-048-per-model-agnostic-settings.md`
+   */
+  settingsSchema?: DyFM_AI_ModelSettingsSchema;
+  /** Input context window in tokens, if applicable. */
+  contextWindow?: number;
+  /** Maximum output tokens, if applicable. */
+  maxOutputTokens?: number;
+  /** Lifecycle status; defaults to `ga` when omitted. */
+  status?: DyFM_AI_ModelStatus;
+  /** When `deprecated`/sunsetting, the recommended replacement model id. */
+  successorId?: string;
+  /** When `deprecated`, the earliest known shutdown date (ISO yyyy-mm-dd). */
+  sunsetDate?: string;
+  /** Human-readable name for UI (e.g. 'GPT-5.5', 'Claude Opus 4.8'). */
+  displayName?: string;
+  /** Provider-specific tier label (e.g. 'flagship', 'mini', 'Opus', 'Sonnet', 'Haiku'). */
+  tier?: string;
+}

package/src/_modules/ai/_models/ai-model-settings-schema.interface.ts

@@ -1,52 +1,52 @@
-/**
- * RESERVED — per-model settings schema (FR-048; NOT implemented by FR-047).
- *
- * Sibling of {@link DyFM_AI_ModelCapabilities}: capabilities describe what a
- * model can DO; this describes which tuning PARAMETERS it accepts, their
- * bounds, and which it REJECTS. A flat {@link DyFM_AI_CallSettings} bag cannot
- * express this, yet sending an unsupported param can hard-fail a call (e.g.
- * Anthropic Opus 4.7+ rejects `temperature`/`top_p`/`top_k` with HTTP 400).
- *
- * This type reserves the architectural space and documents intent. The
- * registry consts do NOT populate `settingsSchema` yet, and no reconciler
- * consumes it yet — both are FR-048 work. The exact shape may evolve when
- * FR-048 is built; treat this as a forward placeholder, not a frozen contract.
- *
- * See: `__agent/feature-requests/FR-048-per-model-agnostic-settings.md`
- *      `documentations/guidelines/development/ai-per-model-settings.md`
- */
-export interface DyFM_AI_ModelSettingsSchema {
-  /** Agnostic setting keys this model ACCEPTS (e.g. 'temperature','topP','maxTokens','reasoningEffort'). */
-  supported?: string[];
-  /**
-   * Agnostic setting keys this model REJECTS — sending them errors.
-   * Example: Opus 4.7+ → ['temperature','topP','topK'] (HTTP 400 on non-default).
-   * The future reconciler drops these (debug-log, never silently).
-   */
-  unsupported?: string[];
-  /** Per-key value constraints (range / enum / default). */
-  constraints?: Record<string, DyFM_AI_SettingConstraint>;
-  /**
-   * Provider/model-specific knobs NOT present on the agnostic CallSettings
-   * (e.g. OpenAI 'reasoningEffort', Gemini 'thinkingConfig'). The provider
-   * translator maps these to the native param.
-   */
-  extraParams?: string[];
-}
-
-/**
- * RESERVED (FR-048) — value constraint for a single tuning parameter.
- * Forward placeholder; shape may evolve when FR-048 is built.
- */
-export interface DyFM_AI_SettingConstraint {
-  /** Minimum numeric value (inclusive), if applicable. */
-  min?: number;
-  /** Maximum numeric value (inclusive), if applicable. */
-  max?: number;
-  /** Default value the provider applies when omitted. */
-  default?: unknown;
-  /** Allowed discrete values (enum-like params, e.g. reasoningEffort). */
-  allowed?: unknown[];
-  /** Free-text note (Hunglish ok) — e.g. provider quirk, version gate. */
-  note?: string;
-}
+/**
+ * RESERVED — per-model settings schema (FR-048; NOT implemented by FR-047).
+ *
+ * Sibling of {@link DyFM_AI_ModelCapabilities}: capabilities describe what a
+ * model can DO; this describes which tuning PARAMETERS it accepts, their
+ * bounds, and which it REJECTS. A flat {@link DyFM_AI_CallSettings} bag cannot
+ * express this, yet sending an unsupported param can hard-fail a call (e.g.
+ * Anthropic Opus 4.7+ rejects `temperature`/`top_p`/`top_k` with HTTP 400).
+ *
+ * This type reserves the architectural space and documents intent. The
+ * registry consts do NOT populate `settingsSchema` yet, and no reconciler
+ * consumes it yet — both are FR-048 work. The exact shape may evolve when
+ * FR-048 is built; treat this as a forward placeholder, not a frozen contract.
+ *
+ * See: `__agent/feature-requests/FR-048-per-model-agnostic-settings.md`
+ *      `documentations/guidelines/development/ai-per-model-settings.md`
+ */
+export interface DyFM_AI_ModelSettingsSchema {
+  /** Agnostic setting keys this model ACCEPTS (e.g. 'temperature','topP','maxTokens','reasoningEffort'). */
+  supported?: string[];
+  /**
+   * Agnostic setting keys this model REJECTS — sending them errors.
+   * Example: Opus 4.7+ → ['temperature','topP','topK'] (HTTP 400 on non-default).
+   * The future reconciler drops these (debug-log, never silently).
+   */
+  unsupported?: string[];
+  /** Per-key value constraints (range / enum / default). */
+  constraints?: Record<string, DyFM_AI_SettingConstraint>;
+  /**
+   * Provider/model-specific knobs NOT present on the agnostic CallSettings
+   * (e.g. OpenAI 'reasoningEffort', Gemini 'thinkingConfig'). The provider
+   * translator maps these to the native param.
+   */
+  extraParams?: string[];
+}
+
+/**
+ * RESERVED (FR-048) — value constraint for a single tuning parameter.
+ * Forward placeholder; shape may evolve when FR-048 is built.
+ */
+export interface DyFM_AI_SettingConstraint {
+  /** Minimum numeric value (inclusive), if applicable. */
+  min?: number;
+  /** Maximum numeric value (inclusive), if applicable. */
+  max?: number;
+  /** Default value the provider applies when omitted. */
+  default?: unknown;
+  /** Allowed discrete values (enum-like params, e.g. reasoningEffort). */
+  allowed?: unknown[];
+  /** Free-text note (Hunglish ok) — e.g. provider quirk, version gate. */
+  note?: string;
+}

package/src/_modules/ai/_models/ai-provider-capabilities.interface.ts

@@ -1,28 +1,28 @@
-/**
- * Defines what capabilities each AI provider supports
- * Used to determine which operations are available for each provider
- */
-export interface DyFM_AI_ProviderCapabilities {
-  /** Can perform text generation/chat operations */
-  chat: boolean;
-  /** Can perform embedding operations */
-  embeddings: boolean;
-  /** Can perform image generation */
-  imageGeneration: boolean;
-  /** Can perform image analysis/vision */
-  vision: boolean;
-  /** Can perform audio generation (TTS) */
-  audioGeneration: boolean;
-  /** Can perform audio analysis (STT) */
-  audioAnalysis: boolean;
-  /** Can perform function calling/tool use */
-  functionCalling: boolean;
-  /** Can perform streaming responses */
-  streaming: boolean;
-  /** Can perform batch operations */
-  batchOperations: boolean;
-  /** Maximum context length in tokens */
-  maxContextLength?: number;
-  /** Supported model types */
-  supportedModelTypes: string[];
-}
+/**
+ * Defines what capabilities each AI provider supports
+ * Used to determine which operations are available for each provider
+ */
+export interface DyFM_AI_ProviderCapabilities {
+  /** Can perform text generation/chat operations */
+  chat: boolean;
+  /** Can perform embedding operations */
+  embeddings: boolean;
+  /** Can perform image generation */
+  imageGeneration: boolean;
+  /** Can perform image analysis/vision */
+  vision: boolean;
+  /** Can perform audio generation (TTS) */
+  audioGeneration: boolean;
+  /** Can perform audio analysis (STT) */
+  audioAnalysis: boolean;
+  /** Can perform function calling/tool use */
+  functionCalling: boolean;
+  /** Can perform streaming responses */
+  streaming: boolean;
+  /** Can perform batch operations */
+  batchOperations: boolean;
+  /** Maximum context length in tokens */
+  maxContextLength?: number;
+  /** Supported model types */
+  supportedModelTypes: string[];
+}

package/src/_modules/ai/_models/ai-settings.interface.ts

@@ -1,17 +1,17 @@
-import { DyFM_AI_CallSettings } from './ai-call-settings.interface';
-import { DyFM_AI_Config } from './ai-config.interface';
-import { DyFM_AI_Provider } from '../_enums/ai-provider.enum';
-
-export class DyFM_AI_Settings {
-  provider?: DyFM_AI_Provider;
-  config?: DyFM_AI_Config;
-  defaultSettings?: DyFM_AI_CallSettings;
-
-  constructor(
-    set?: DyFM_AI_Settings
-  ) {
-    if (set) {
-      Object.assign(this, set);
-    }
-  }
-}
+import { DyFM_AI_CallSettings } from './ai-call-settings.interface';
+import { DyFM_AI_Config } from './ai-config.interface';
+import { DyFM_AI_Provider } from '../_enums/ai-provider.enum';
+
+export class DyFM_AI_Settings {
+  provider?: DyFM_AI_Provider;
+  config?: DyFM_AI_Config;
+  defaultSettings?: DyFM_AI_CallSettings;
+
+  constructor(
+    set?: DyFM_AI_Settings
+  ) {
+    if (set) {
+      Object.assign(this, set);
+    }
+  }
+}

package/src/_modules/ai/_models/ai-tool-call.interface.ts

@@ -1,18 +1,18 @@
-/**
- * A normalized tool invocation requested by the model.
- *
- * Each provider's native shape is normalized into this at the translator boundary:
- *  - OpenAI:    message.tool_calls[] → { id, name, arguments: JSON.parse(function.arguments) }
- *  - Anthropic: content[] { type:'tool_use', id, name, input } → { id, name, arguments: input }
- *  - Gemini:    parts[].functionCall { id, name, args } → { id, name, arguments: args }
- *
- * `arguments` is ALWAYS a parsed object (OpenAI's JSON string is parsed at the boundary).
- */
-export interface DyFM_AI_ToolCall {
-  /** Provider call id — echoed back when returning the result. */
-  id: string;
-  /** The invoked tool's name. */
-  name: string;
-  /** Parsed arguments object. */
-  arguments: Record<string, unknown>;
-}
+/**
+ * A normalized tool invocation requested by the model.
+ *
+ * Each provider's native shape is normalized into this at the translator boundary:
+ *  - OpenAI:    message.tool_calls[] → { id, name, arguments: JSON.parse(function.arguments) }
+ *  - Anthropic: content[] { type:'tool_use', id, name, input } → { id, name, arguments: input }
+ *  - Gemini:    parts[].functionCall { id, name, args } → { id, name, arguments: args }
+ *
+ * `arguments` is ALWAYS a parsed object (OpenAI's JSON string is parsed at the boundary).
+ */
+export interface DyFM_AI_ToolCall {
+  /** Provider call id — echoed back when returning the result. */
+  id: string;
+  /** The invoked tool's name. */
+  name: string;
+  /** Parsed arguments object. */
+  arguments: Record<string, unknown>;
+}

package/src/_modules/ai/_models/ai-tool-handler.type.ts

@@ -1,11 +1,11 @@
-/**
- * Handler for a single function-calling tool — receives the parsed arguments
- * (JSON already parsed) and returns the tool result as a string (which is fed
- * back to the model). Generalized from the proven legacy `FDPNTS_GPT_ToolHandler`.
- */
-export type DyFM_AI_ToolHandler = (args: Record<string, unknown>) => Promise<string> | string;
-
-/**
- * Tool-name → handler registration for the `requestWithTools` agent-loop.
- */
-export type DyFM_AI_ToolHandlers = Record<string, DyFM_AI_ToolHandler>;
+/**
+ * Handler for a single function-calling tool — receives the parsed arguments
+ * (JSON already parsed) and returns the tool result as a string (which is fed
+ * back to the model). Generalized from the proven legacy `FDPNTS_GPT_ToolHandler`.
+ */
+export type DyFM_AI_ToolHandler = (args: Record<string, unknown>) => Promise<string> | string;
+
+/**
+ * Tool-name → handler registration for the `requestWithTools` agent-loop.
+ */
+export type DyFM_AI_ToolHandlers = Record<string, DyFM_AI_ToolHandler>;

package/src/_modules/ai/_models/ai-tool-result.interface.ts

@@ -1,16 +1,16 @@
-/**
- * The result of executing a tool, fed back to the model.
- *
- * Translated per provider:
- *  - OpenAI:    { role:'tool', tool_call_id: toolCallId, content }
- *  - Anthropic: content block { type:'tool_result', tool_use_id: toolCallId, content, is_error: isError }
- *  - Gemini:    part { functionResponse: { id: toolCallId, name, response: { result: content } } }
- */
-export interface DyFM_AI_ToolResult {
-  /** Must echo the originating {@link DyFM_AI_ToolCall.id}. */
-  toolCallId: string;
-  /** The tool's output (or an error message — see {@link isError}). */
-  content: string;
-  /** True when the tool failed; the model is told so it can correct. */
-  isError?: boolean;
-}
+/**
+ * The result of executing a tool, fed back to the model.
+ *
+ * Translated per provider:
+ *  - OpenAI:    { role:'tool', tool_call_id: toolCallId, content }
+ *  - Anthropic: content block { type:'tool_result', tool_use_id: toolCallId, content, is_error: isError }
+ *  - Gemini:    part { functionResponse: { id: toolCallId, name, response: { result: content } } }
+ */
+export interface DyFM_AI_ToolResult {
+  /** Must echo the originating {@link DyFM_AI_ToolCall.id}. */
+  toolCallId: string;
+  /** The tool's output (or an error message — see {@link isError}). */
+  content: string;
+  /** True when the tool failed; the model is told so it can correct. */
+  isError?: boolean;
+}