@futdevpro/fsm-dynamo 1.16.4 → 1.16.7

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;
+}

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

@@ -1,16 +1,16 @@
-/**
- * Provider-neutral tool (function) definition for native function calling.
- *
- * One agnostic shape, translated per provider by the execution layer:
- *  - OpenAI-wire: → { type:'function', function:{ name, description, parameters } }
- *  - Anthropic:   → { name, description, input_schema: parameters }
- *  - Gemini:      → tools:[{ functionDeclarations:[{ name, description, parameters }] }]
- */
-export interface DyFM_AI_Tool {
-  /** Function name. No spaces / special chars (Gemini constraint). */
-  name: string;
-  /** What the tool does — the model uses this to decide when to call it. */
-  description: string;
-  /** JSON Schema (object schema) describing the arguments. Translated to each provider's param shape. */
-  parameters: object;
-}
+/**
+ * Provider-neutral tool (function) definition for native function calling.
+ *
+ * One agnostic shape, translated per provider by the execution layer:
+ *  - OpenAI-wire: → { type:'function', function:{ name, description, parameters } }
+ *  - Anthropic:   → { name, description, input_schema: parameters }
+ *  - Gemini:      → tools:[{ functionDeclarations:[{ name, description, parameters }] }]
+ */
+export interface DyFM_AI_Tool {
+  /** Function name. No spaces / special chars (Gemini constraint). */
+  name: string;
+  /** What the tool does — the model uses this to decide when to call it. */
+  description: string;
+  /** JSON Schema (object schema) describing the arguments. Translated to each provider's param shape. */
+  parameters: object;
+}

package/src/_modules/ai/_models/ai-user-provider-config.control-model.ts

@@ -1,29 +1,29 @@
-import { DyFM_AI_Provider } from '../_enums/ai-provider.enum';
-
-/**
- * User szintu AI provider konfiguracio base class
- *
- * Tartalmazz a provider API kulcs titkositott valtozatat, annak suffix-et a megjeleníteshez,
- * es az alap beallitasokat. Provider-specifikus leszarmazottak bovitik sajat mezoikkel.
- */
-export class DyFM_AI_UserProviderConfig {
-  provider?: DyFM_AI_Provider;
-  /** titkositott API kulcs (csak szerver oldalon tarolva, kliensre sosem kerul) */
-  encryptedApiKey?: string;
-  /** az API kulcs utolso ~4 karaktere megjeleníteshez (pl. "...xR7q") */
-  keySuffix?: string;
-  isActive?: boolean;
-  label?: string;
-  lastTestedAt?: Date;
-  lastUsedAt?: Date;
-  /** a user altal kivalasztott modellek (providerrol lekerdezett listabol) */
-  selectedModels?: string[];
-
-  constructor(
-    set?: DyFM_AI_UserProviderConfig
-  ) {
-    if (set) {
-      Object.assign(this, set);
-    }
-  }
-}
+import { DyFM_AI_Provider } from '../_enums/ai-provider.enum';
+
+/**
+ * User szintu AI provider konfiguracio base class
+ *
+ * Tartalmazz a provider API kulcs titkositott valtozatat, annak suffix-et a megjeleníteshez,
+ * es az alap beallitasokat. Provider-specifikus leszarmazottak bovitik sajat mezoikkel.
+ */
+export class DyFM_AI_UserProviderConfig {
+  provider?: DyFM_AI_Provider;
+  /** titkositott API kulcs (csak szerver oldalon tarolva, kliensre sosem kerul) */
+  encryptedApiKey?: string;
+  /** az API kulcs utolso ~4 karaktere megjeleníteshez (pl. "...xR7q") */
+  keySuffix?: string;
+  isActive?: boolean;
+  label?: string;
+  lastTestedAt?: Date;
+  lastUsedAt?: Date;
+  /** a user altal kivalasztott modellek (providerrol lekerdezett listabol) */
+  selectedModels?: string[];
+
+  constructor(
+    set?: DyFM_AI_UserProviderConfig
+  ) {
+    if (set) {
+      Object.assign(this, set);
+    }
+  }
+}