@invect/core 0.0.1

package/dist/types/agent-tool.types.d.cts

@@ -0,0 +1,211 @@
+import { Logger } from "./schemas-fresh/invect-config.cjs";
+import { NodeExecutionContext } from "../types-fresh.cjs";
+
+//#region src/types/agent-tool.types.d.ts
+/**
+ * Tool category for organization in UI
+ */
+type AgentToolCategory = 'data' | 'web' | 'code' | 'utility' | 'custom';
+/**
+ * Base tool definition that can be registered and used by agents
+ */
+interface AgentToolDefinition {
+  /** Unique tool identifier (snake_case recommended) */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Description for the LLM to understand when to use this tool */
+  description: string;
+  /** JSON Schema defining the tool's input parameters */
+  inputSchema: Record<string, unknown>;
+  /** Tool category for organization in UI */
+  category: AgentToolCategory;
+  /** Tags for filtering and organization */
+  tags?: string[];
+  /** Whether this tool is enabled by default */
+  enabledByDefault?: boolean;
+  /** Timeout in milliseconds for this tool (defaults to DEFAULT_TOOL_TIMEOUT_MS) */
+  timeoutMs?: number;
+  /**
+   * If this tool is backed by a node executor, this is the node type.
+   * Used to fetch the node definition for configuration UI.
+   */
+  nodeType?: string;
+  /**
+   * Provider information for grouping and branding in the UI.
+   * Populated from the action's provider when the tool is action-based.
+   */
+  provider?: {
+    id: string;
+    name: string;
+    icon: string; /** Raw SVG markup for custom provider branding. Takes precedence over `icon`. */
+    svgIcon?: string;
+  };
+}
+/**
+ * A configured instance of a tool added to an agent.
+ * Multiple instances of the same tool can exist with different configurations.
+ *
+ * For example, two HTTP Request tools:
+ * - "Fetch Weather" with URL preset to weather API
+ * - "Post to Slack" with URL preset to Slack webhook
+ */
+interface AddedToolInstance {
+  /** Unique instance ID */
+  instanceId: string;
+  /** Reference to the base tool definition ID */
+  toolId: string;
+  /** Custom name for this instance (shown to AI) */
+  name: string;
+  /** Custom description for this instance (shown to AI) */
+  description: string;
+  /**
+   * Tool-specific parameter values.
+   * Contains both static values and `_aiChosenModes` to indicate which params the AI should fill.
+   */
+  params: Record<string, unknown> & {
+    /**
+     * Map of param name to boolean indicating if AI should choose the value.
+     * If true (or not present), AI fills the value at runtime.
+     * If false, the value from `params[fieldName]` is used as a static value.
+     */
+    _aiChosenModes?: Record<string, boolean>;
+  };
+}
+/**
+ * A tool definition customized for a specific instance.
+ * Has filtered inputSchema (only AI-chosen params) and references the instance for static param injection.
+ */
+interface ConfiguredToolDefinition extends AgentToolDefinition {
+  /** The instance this configured tool is derived from */
+  instanceId: string;
+  /** Static parameter values to merge with AI-provided input */
+  staticParams: Record<string, unknown>;
+  /** Original tool ID (before instance customization) */
+  baseToolId: string;
+}
+/**
+ * Tool execution context provided to tool handlers
+ *
+ * Tools are self-contained and should import their own dependencies
+ * (e.g., json-logic-js) rather than relying on context functions.
+ * The nodeContext provides access to cross-cutting concerns like credentials.
+ */
+interface AgentToolExecutionContext {
+  logger: Logger;
+  /** Current agent iteration number */
+  iteration: number;
+  /** Maximum allowed iterations */
+  maxIterations: number;
+  /** Node execution context - provides access to credentials and other cross-cutting concerns */
+  nodeContext: NodeExecutionContext
+  /**
+  * Static parameters configured on the tool instance.
+  * These are set by the user when adding the tool to an agent node,
+  * not provided by the AI at runtime.
+  * Example: credentialId for OAuth2 tools like Gmail
+  */
+;
+  staticParams?: Record<string, unknown>;
+}
+/**
+ * Result from executing a tool
+ */
+interface AgentToolResult {
+  success: boolean;
+  output?: unknown;
+  error?: string;
+}
+/**
+ * Tool executor function type
+ */
+type AgentToolExecutor = (input: Record<string, unknown>, context: AgentToolExecutionContext) => Promise<AgentToolResult>;
+/**
+ * Registered agent tool with definition and executor
+ */
+interface RegisteredAgentTool {
+  definition: AgentToolDefinition;
+  executor: AgentToolExecutor;
+}
+/**
+ * Tool call from an LLM response
+ */
+interface AgentToolCall {
+  id: string;
+  toolId: string;
+  input: Record<string, unknown>;
+}
+/**
+ * Record of a tool execution during an agent run
+ */
+interface ToolExecutionRecord {
+  toolId: string;
+  toolName: string;
+  input: Record<string, unknown>;
+  output?: unknown;
+  error?: string;
+  success: boolean;
+  iteration: number;
+  executionTimeMs: number;
+}
+/**
+ * Message in an agent conversation
+ */
+interface AgentMessage {
+  role: 'user' | 'assistant' | 'tool';
+  content: string;
+  toolCalls?: AgentToolCall[];
+  toolCallId?: string;
+}
+/**
+ * Agent stop conditions
+ */
+type AgentStopCondition = 'tool_result' | 'explicit_stop' | 'max_iterations';
+/**
+ * Agent finish reason
+ */
+type AgentFinishReason = 'completed' | 'max_iterations' | 'tool_result' | 'error';
+/**
+ * Result from agent prompt execution
+ */
+interface AgentPromptResult {
+  type: 'text' | 'tool_use';
+  content: string;
+  /** Tool calls requested by the LLM */
+  toolCalls?: AgentToolCall[];
+}
+/**
+ * Request to run an agent prompt
+ */
+interface AgentPromptRequest {
+  model: string;
+  messages: AgentMessage[];
+  tools: AgentToolDefinition[];
+  systemPrompt?: string;
+  temperature?: number;
+  maxTokens?: number;
+  toolChoice?: 'auto' | 'none' | {
+    type: 'tool';
+    name: string;
+  };
+  /** Whether to allow parallel tool calls (defaults to true) */
+  parallelToolCalls?: boolean;
+}
+/**
+ * Agent execution output structure
+ */
+interface AgentExecutionOutput {
+  finalResponse: string;
+  toolResults: ToolExecutionRecord[];
+  iterations: number;
+  finishReason: AgentFinishReason;
+  conversationHistory: AgentMessage[];
+  /** Token usage statistics */
+  tokenUsage?: {
+    conversationTokensEstimate: number;
+    truncationOccurred: boolean;
+  };
+}
+//#endregion
+export { AddedToolInstance, AgentExecutionOutput, AgentFinishReason, AgentMessage, AgentPromptRequest, AgentPromptResult, AgentStopCondition, AgentToolCall, AgentToolCategory, AgentToolDefinition, AgentToolExecutionContext, AgentToolExecutor, AgentToolResult, ConfiguredToolDefinition, RegisteredAgentTool, ToolExecutionRecord };
+//# sourceMappingURL=agent-tool.types.d.cts.map

package/dist/types/agent-tool.types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool.types.d.cts","names":[],"sources":["../../src/types/agent-tool.types.ts"],"mappings":";;;;;;AAiCA;KArBY,iBAAA;;;;UAqBK,mBAAA;EA+Bb;EA7BF,EAAA;EA6BS;EA3BT,IAAA;EAuCgC;EArChC,WAAA;EAwDyB;EAtDzB,WAAA,EAAa,MAAA;EAuCb;EArCA,QAAA,EAAU,iBAAA;EAyCV;EAvCA,IAAA;EA4CQ;EA1CR,gBAAA;EAgDmB;EA9CnB,SAAA;EA8CyB;AAQ3B;;;EAjDE,QAAA;EAiDgD;;;;EA5ChD,QAAA;IACE,EAAA;IACA,IAAA;IACA,IAAA,UAyDsC;IAvDtC,OAAA;EAAA;AAAA;;;;;;;;;UAYa,iBAAA;EAwDf;EAtDA,UAAA;EAsDqB;EApDrB,MAAA;EA0De;EAxDf,IAAA;;EAEA,WAAA;EAuDA;;;;EAlDA,MAAA,EAAQ,MAAA;IA0DE;;;;;IApDR,cAAA,GAAiB,MAAA;EAAA;AAAA;;;;;UAQJ,wBAAA,SAAiC,mBAAA;EA+C7C;EA7CH,UAAA;EA6C0B;EA3C1B,YAAA,EAAc,MAAA;EAgDC;EA9Cf,UAAA;AAAA;;;;;;;;UAUe,yBAAA;EACf,MAAA,EAAQ,MAAA;;EAER,SAAA;EA0CA;EAxCA,aAAA;EA0CA;EAxCA,WAAA,EAAa;EAwCN;;;AAMT;;;AANS;EAlCP,YAAA,GAAe,MAAA;AAAA;;;;UAMA,eAAA;EACf,OAAA;EACA,MAAA;EACA,KAAA;AAAA;;;AA6CF;KAvCY,iBAAA,IACV,KAAA,EAAO,MAAA,mBACP,OAAA,EAAS,yBAAA,KACN,OAAA,CAAQ,eAAA;;;;UAKI,mBAAA;EACf,UAAA,EAAY,mBAAA;EACZ,QAAA,EAAU,iBAAA;AAAA;;;AAuCZ;UAjCiB,aAAA;EACf,EAAA;EACA,MAAA;EACA,KAAA,EAAO,MAAA;AAAA;;;;UAMQ,mBAAA;EACf,MAAA;EACA,QAAA;EACA,KAAA,EAAO,MAAA;EACP,MAAA;EACA,KAAA;EACA,OAAA;EACA,SAAA;EACA,eAAA;AAAA;;AAoCF;;UA9BiB,YAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA,GAAY,aAAA;EACZ,UAAA;AAAA;;;;KAMU,kBAAA;;;;KAKA,iBAAA;;;AA8BZ;UAzBiB,iBAAA;EACf,IAAA;EACA,OAAA;EA2Bc;EAzBd,SAAA,GAAY,aAAA;AAAA;;;;UAMG,kBAAA;EACf,KAAA;EACA,QAAA,EAAU,YAAA;EACV,KAAA,EAAO,mBAAA;EACP,YAAA;EACA,WAAA;EACA,SAAA;EACA,UAAA;IAAiC,IAAA;IAAc,IAAA;EAAA;;EAE/C,iBAAA;AAAA;;;;UAMe,oBAAA;EACf,aAAA;EACA,WAAA,EAAa,mBAAA;EACb,UAAA;EACA,YAAA,EAAc,iBAAA;EACd,mBAAA,EAAqB,YAAA;;EAErB,UAAA;IACE,0BAAA;IACA,kBAAA;EAAA;AAAA"}

package/dist/types/agent-tool.types.d.ts

@@ -0,0 +1,211 @@
+import { Logger } from "./schemas-fresh/invect-config.js";
+import { NodeExecutionContext } from "../types-fresh.js";
+
+//#region src/types/agent-tool.types.d.ts
+/**
+ * Tool category for organization in UI
+ */
+type AgentToolCategory = 'data' | 'web' | 'code' | 'utility' | 'custom';
+/**
+ * Base tool definition that can be registered and used by agents
+ */
+interface AgentToolDefinition {
+  /** Unique tool identifier (snake_case recommended) */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Description for the LLM to understand when to use this tool */
+  description: string;
+  /** JSON Schema defining the tool's input parameters */
+  inputSchema: Record<string, unknown>;
+  /** Tool category for organization in UI */
+  category: AgentToolCategory;
+  /** Tags for filtering and organization */
+  tags?: string[];
+  /** Whether this tool is enabled by default */
+  enabledByDefault?: boolean;
+  /** Timeout in milliseconds for this tool (defaults to DEFAULT_TOOL_TIMEOUT_MS) */
+  timeoutMs?: number;
+  /**
+   * If this tool is backed by a node executor, this is the node type.
+   * Used to fetch the node definition for configuration UI.
+   */
+  nodeType?: string;
+  /**
+   * Provider information for grouping and branding in the UI.
+   * Populated from the action's provider when the tool is action-based.
+   */
+  provider?: {
+    id: string;
+    name: string;
+    icon: string; /** Raw SVG markup for custom provider branding. Takes precedence over `icon`. */
+    svgIcon?: string;
+  };
+}
+/**
+ * A configured instance of a tool added to an agent.
+ * Multiple instances of the same tool can exist with different configurations.
+ *
+ * For example, two HTTP Request tools:
+ * - "Fetch Weather" with URL preset to weather API
+ * - "Post to Slack" with URL preset to Slack webhook
+ */
+interface AddedToolInstance {
+  /** Unique instance ID */
+  instanceId: string;
+  /** Reference to the base tool definition ID */
+  toolId: string;
+  /** Custom name for this instance (shown to AI) */
+  name: string;
+  /** Custom description for this instance (shown to AI) */
+  description: string;
+  /**
+   * Tool-specific parameter values.
+   * Contains both static values and `_aiChosenModes` to indicate which params the AI should fill.
+   */
+  params: Record<string, unknown> & {
+    /**
+     * Map of param name to boolean indicating if AI should choose the value.
+     * If true (or not present), AI fills the value at runtime.
+     * If false, the value from `params[fieldName]` is used as a static value.
+     */
+    _aiChosenModes?: Record<string, boolean>;
+  };
+}
+/**
+ * A tool definition customized for a specific instance.
+ * Has filtered inputSchema (only AI-chosen params) and references the instance for static param injection.
+ */
+interface ConfiguredToolDefinition extends AgentToolDefinition {
+  /** The instance this configured tool is derived from */
+  instanceId: string;
+  /** Static parameter values to merge with AI-provided input */
+  staticParams: Record<string, unknown>;
+  /** Original tool ID (before instance customization) */
+  baseToolId: string;
+}
+/**
+ * Tool execution context provided to tool handlers
+ *
+ * Tools are self-contained and should import their own dependencies
+ * (e.g., json-logic-js) rather than relying on context functions.
+ * The nodeContext provides access to cross-cutting concerns like credentials.
+ */
+interface AgentToolExecutionContext {
+  logger: Logger;
+  /** Current agent iteration number */
+  iteration: number;
+  /** Maximum allowed iterations */
+  maxIterations: number;
+  /** Node execution context - provides access to credentials and other cross-cutting concerns */
+  nodeContext: NodeExecutionContext
+  /**
+  * Static parameters configured on the tool instance.
+  * These are set by the user when adding the tool to an agent node,
+  * not provided by the AI at runtime.
+  * Example: credentialId for OAuth2 tools like Gmail
+  */
+;
+  staticParams?: Record<string, unknown>;
+}
+/**
+ * Result from executing a tool
+ */
+interface AgentToolResult {
+  success: boolean;
+  output?: unknown;
+  error?: string;
+}
+/**
+ * Tool executor function type
+ */
+type AgentToolExecutor = (input: Record<string, unknown>, context: AgentToolExecutionContext) => Promise<AgentToolResult>;
+/**
+ * Registered agent tool with definition and executor
+ */
+interface RegisteredAgentTool {
+  definition: AgentToolDefinition;
+  executor: AgentToolExecutor;
+}
+/**
+ * Tool call from an LLM response
+ */
+interface AgentToolCall {
+  id: string;
+  toolId: string;
+  input: Record<string, unknown>;
+}
+/**
+ * Record of a tool execution during an agent run
+ */
+interface ToolExecutionRecord {
+  toolId: string;
+  toolName: string;
+  input: Record<string, unknown>;
+  output?: unknown;
+  error?: string;
+  success: boolean;
+  iteration: number;
+  executionTimeMs: number;
+}
+/**
+ * Message in an agent conversation
+ */
+interface AgentMessage {
+  role: 'user' | 'assistant' | 'tool';
+  content: string;
+  toolCalls?: AgentToolCall[];
+  toolCallId?: string;
+}
+/**
+ * Agent stop conditions
+ */
+type AgentStopCondition = 'tool_result' | 'explicit_stop' | 'max_iterations';
+/**
+ * Agent finish reason
+ */
+type AgentFinishReason = 'completed' | 'max_iterations' | 'tool_result' | 'error';
+/**
+ * Result from agent prompt execution
+ */
+interface AgentPromptResult {
+  type: 'text' | 'tool_use';
+  content: string;
+  /** Tool calls requested by the LLM */
+  toolCalls?: AgentToolCall[];
+}
+/**
+ * Request to run an agent prompt
+ */
+interface AgentPromptRequest {
+  model: string;
+  messages: AgentMessage[];
+  tools: AgentToolDefinition[];
+  systemPrompt?: string;
+  temperature?: number;
+  maxTokens?: number;
+  toolChoice?: 'auto' | 'none' | {
+    type: 'tool';
+    name: string;
+  };
+  /** Whether to allow parallel tool calls (defaults to true) */
+  parallelToolCalls?: boolean;
+}
+/**
+ * Agent execution output structure
+ */
+interface AgentExecutionOutput {
+  finalResponse: string;
+  toolResults: ToolExecutionRecord[];
+  iterations: number;
+  finishReason: AgentFinishReason;
+  conversationHistory: AgentMessage[];
+  /** Token usage statistics */
+  tokenUsage?: {
+    conversationTokensEstimate: number;
+    truncationOccurred: boolean;
+  };
+}
+//#endregion
+export { AddedToolInstance, AgentExecutionOutput, AgentFinishReason, AgentMessage, AgentPromptRequest, AgentPromptResult, AgentStopCondition, AgentToolCall, AgentToolCategory, AgentToolDefinition, AgentToolExecutionContext, AgentToolExecutor, AgentToolResult, ConfiguredToolDefinition, RegisteredAgentTool, ToolExecutionRecord };
+//# sourceMappingURL=agent-tool.types.d.ts.map

package/dist/types/agent-tool.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool.types.d.ts","names":[],"sources":["../../src/types/agent-tool.types.ts"],"mappings":";;;;;;;KAYY,iBAAA;;;;UAqBK,mBAAA;EA6Bb;EA3BF,EAAA;EA6BS;EA3BT,IAAA;EAuCe;EArCf,WAAA;;EAEA,WAAA,EAAa,MAAA;EAqCb;EAnCA,QAAA,EAAU,iBAAA;EAuCV;EArCA,IAAA;EA4CA;EA1CA,gBAAA;EAgDE;EA9CF,SAAA;EA8CyB;;AAQ3B;;EAjDE,QAAA;EAiDmE;;;;EA5CnE,QAAA;IACE,EAAA;IACA,IAAA;IACA,IAAA,UAyDa;IAvDb,OAAA;EAAA;AAAA;;;;;;;;;UAYa,iBAAA;EAkDF;EAhDb,UAAA;EAsDe;EApDf,MAAA;EAoDqB;EAlDrB,IAAA;EAwD8B;EAtD9B,WAAA;EAsD8B;;;;EAjD9B,MAAA,EAAQ,MAAA;IAoDH;AAMP;;;;IApDI,cAAA,GAAiB,MAAA;EAAA;AAAA;;;;;UAQJ,wBAAA,SAAiC,mBAAA;EA8ChD;EA5CA,UAAA;EA6CW;EA3CX,YAAA,EAAc,MAAA;EA2CY;EAzC1B,UAAA;AAAA;;;;;;;;UAUe,yBAAA;EACf,MAAA,EAAQ,MAAA;EA2CoB;EAzC5B,SAAA;EA4Ca;EA1Cb,aAAA;EAyCA;EAvCA,WAAA,EAAa;EAwCb;;;;AAMF;;AANE;EAlCA,YAAA,GAAe,MAAA;AAAA;;;;UAMA,eAAA;EACf,OAAA;EACA,MAAA;EACA,KAAA;AAAA;;;;KAMU,iBAAA,IACV,KAAA,EAAO,MAAA,mBACP,OAAA,EAAS,yBAAA,KACN,OAAA,CAAQ,eAAA;;;;UAKI,mBAAA;EACf,UAAA,EAAY,mBAAA;EACZ,QAAA,EAAU,iBAAA;AAAA;;;;UAMK,aAAA;EACf,EAAA;EACA,MAAA;EACA,KAAA,EAAO,MAAA;AAAA;AAmCT;;;AAAA,UA7BiB,mBAAA;EACf,MAAA;EACA,QAAA;EACA,KAAA,EAAO,MAAA;EACP,MAAA;EACA,KAAA;EACA,OAAA;EACA,SAAA;EACA,eAAA;AAAA;;;AAoCF;UA9BiB,YAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA,GAAY,aAAA;EACZ,UAAA;AAAA;;;;KAMU,kBAAA;;;;KAKA,iBAAA;;;;UAKK,iBAAA;EACf,IAAA;EACA,OAAA;EAyBa;EAvBb,SAAA,GAAY,aAAA;AAAA;;;;UAMG,kBAAA;EACf,KAAA;EACA,QAAA,EAAU,YAAA;EACV,KAAA,EAAO,mBAAA;EACP,YAAA;EACA,WAAA;EACA,SAAA;EACA,UAAA;IAAiC,IAAA;IAAc,IAAA;EAAA;EAiB3B;EAfpB,iBAAA;AAAA;;;;UAMe,oBAAA;EACf,aAAA;EACA,WAAA,EAAa,mBAAA;EACb,UAAA;EACA,YAAA,EAAc,iBAAA;EACd,mBAAA,EAAqB,YAAA;;EAErB,UAAA;IACE,0BAAA;IACA,kBAAA;EAAA;AAAA"}

package/dist/types/agent-tool.types.js

@@ -0,0 +1,18 @@
+//#region src/types/agent-tool.types.ts
+/**
+* Default timeout for tool execution (30 seconds)
+*/
+const DEFAULT_TOOL_TIMEOUT_MS = 3e4;
+/**
+* Default max tokens for conversation history (approximate)
+* This is used to estimate when to truncate conversation history
+*/
+const DEFAULT_MAX_CONVERSATION_TOKENS = 1e5;
+/**
+* Approximate tokens per character (for estimation)
+*/
+const APPROX_TOKENS_PER_CHAR = .25;
+//#endregion
+export { APPROX_TOKENS_PER_CHAR, DEFAULT_MAX_CONVERSATION_TOKENS, DEFAULT_TOOL_TIMEOUT_MS };
+
+//# sourceMappingURL=agent-tool.types.js.map

package/dist/types/agent-tool.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool.types.js","names":[],"sources":["../../src/types/agent-tool.types.ts"],"sourcesContent":["/**\n * Agent Tool Types\n *\n * Types for defining tools that AI agents can use during execution.\n */\n\nimport { Logger } from './schemas';\nimport { NodeExecutionContext } from 'src/types-fresh';\n\n/**\n * Tool category for organization in UI\n */\nexport type AgentToolCategory = 'data' | 'web' | 'code' | 'utility' | 'custom';\n\n/**\n * Default timeout for tool execution (30 seconds)\n */\nexport const DEFAULT_TOOL_TIMEOUT_MS = 30000;\n\n/**\n * Default max tokens for conversation history (approximate)\n * This is used to estimate when to truncate conversation history\n */\nexport const DEFAULT_MAX_CONVERSATION_TOKENS = 100000;\n\n/**\n * Approximate tokens per character (for estimation)\n */\nexport const APPROX_TOKENS_PER_CHAR = 0.25;\n\n/**\n * Base tool definition that can be registered and used by agents\n */\nexport interface AgentToolDefinition {\n  /** Unique tool identifier (snake_case recommended) */\n  id: string;\n  /** Human-readable name */\n  name: string;\n  /** Description for the LLM to understand when to use this tool */\n  description: string;\n  /** JSON Schema defining the tool's input parameters */\n  inputSchema: Record<string, unknown>;\n  /** Tool category for organization in UI */\n  category: AgentToolCategory;\n  /** Tags for filtering and organization */\n  tags?: string[];\n  /** Whether this tool is enabled by default */\n  enabledByDefault?: boolean;\n  /** Timeout in milliseconds for this tool (defaults to DEFAULT_TOOL_TIMEOUT_MS) */\n  timeoutMs?: number;\n  /**\n   * If this tool is backed by a node executor, this is the node type.\n   * Used to fetch the node definition for configuration UI.\n   */\n  nodeType?: string;\n  /**\n   * Provider information for grouping and branding in the UI.\n   * Populated from the action's provider when the tool is action-based.\n   */\n  provider?: {\n    id: string;\n    name: string;\n    icon: string;\n    /** Raw SVG markup for custom provider branding. Takes precedence over `icon`. */\n    svgIcon?: string;\n  };\n}\n\n/**\n * A configured instance of a tool added to an agent.\n * Multiple instances of the same tool can exist with different configurations.\n *\n * For example, two HTTP Request tools:\n * - \"Fetch Weather\" with URL preset to weather API\n * - \"Post to Slack\" with URL preset to Slack webhook\n */\nexport interface AddedToolInstance {\n  /** Unique instance ID */\n  instanceId: string;\n  /** Reference to the base tool definition ID */\n  toolId: string;\n  /** Custom name for this instance (shown to AI) */\n  name: string;\n  /** Custom description for this instance (shown to AI) */\n  description: string;\n  /**\n   * Tool-specific parameter values.\n   * Contains both static values and `_aiChosenModes` to indicate which params the AI should fill.\n   */\n  params: Record<string, unknown> & {\n    /**\n     * Map of param name to boolean indicating if AI should choose the value.\n     * If true (or not present), AI fills the value at runtime.\n     * If false, the value from `params[fieldName]` is used as a static value.\n     */\n    _aiChosenModes?: Record<string, boolean>;\n  };\n}\n\n/**\n * A tool definition customized for a specific instance.\n * Has filtered inputSchema (only AI-chosen params) and references the instance for static param injection.\n */\nexport interface ConfiguredToolDefinition extends AgentToolDefinition {\n  /** The instance this configured tool is derived from */\n  instanceId: string;\n  /** Static parameter values to merge with AI-provided input */\n  staticParams: Record<string, unknown>;\n  /** Original tool ID (before instance customization) */\n  baseToolId: string;\n}\n\n/**\n * Tool execution context provided to tool handlers\n *\n * Tools are self-contained and should import their own dependencies\n * (e.g., json-logic-js) rather than relying on context functions.\n * The nodeContext provides access to cross-cutting concerns like credentials.\n */\nexport interface AgentToolExecutionContext {\n  logger: Logger;\n  /** Current agent iteration number */\n  iteration: number;\n  /** Maximum allowed iterations */\n  maxIterations: number;\n  /** Node execution context - provides access to credentials and other cross-cutting concerns */\n  nodeContext: NodeExecutionContext /**\n   * Static parameters configured on the tool instance.\n   * These are set by the user when adding the tool to an agent node,\n   * not provided by the AI at runtime.\n   * Example: credentialId for OAuth2 tools like Gmail\n   */;\n  staticParams?: Record<string, unknown>;\n}\n\n/**\n * Result from executing a tool\n */\nexport interface AgentToolResult {\n  success: boolean;\n  output?: unknown;\n  error?: string;\n}\n\n/**\n * Tool executor function type\n */\nexport type AgentToolExecutor = (\n  input: Record<string, unknown>,\n  context: AgentToolExecutionContext,\n) => Promise<AgentToolResult>;\n\n/**\n * Registered agent tool with definition and executor\n */\nexport interface RegisteredAgentTool {\n  definition: AgentToolDefinition;\n  executor: AgentToolExecutor;\n}\n\n/**\n * Tool call from an LLM response\n */\nexport interface AgentToolCall {\n  id: string;\n  toolId: string;\n  input: Record<string, unknown>;\n}\n\n/**\n * Record of a tool execution during an agent run\n */\nexport interface ToolExecutionRecord {\n  toolId: string;\n  toolName: string;\n  input: Record<string, unknown>;\n  output?: unknown;\n  error?: string;\n  success: boolean;\n  iteration: number;\n  executionTimeMs: number;\n}\n\n/**\n * Message in an agent conversation\n */\nexport interface AgentMessage {\n  role: 'user' | 'assistant' | 'tool';\n  content: string;\n  toolCalls?: AgentToolCall[];\n  toolCallId?: string;\n}\n\n/**\n * Agent stop conditions\n */\nexport type AgentStopCondition = 'tool_result' | 'explicit_stop' | 'max_iterations';\n\n/**\n * Agent finish reason\n */\nexport type AgentFinishReason = 'completed' | 'max_iterations' | 'tool_result' | 'error';\n\n/**\n * Result from agent prompt execution\n */\nexport interface AgentPromptResult {\n  type: 'text' | 'tool_use';\n  content: string;\n  /** Tool calls requested by the LLM */\n  toolCalls?: AgentToolCall[];\n}\n\n/**\n * Request to run an agent prompt\n */\nexport interface AgentPromptRequest {\n  model: string;\n  messages: AgentMessage[];\n  tools: AgentToolDefinition[];\n  systemPrompt?: string;\n  temperature?: number;\n  maxTokens?: number;\n  toolChoice?: 'auto' | 'none' | { type: 'tool'; name: string };\n  /** Whether to allow parallel tool calls (defaults to true) */\n  parallelToolCalls?: boolean;\n}\n\n/**\n * Agent execution output structure\n */\nexport interface AgentExecutionOutput {\n  finalResponse: string;\n  toolResults: ToolExecutionRecord[];\n  iterations: number;\n  finishReason: AgentFinishReason;\n  conversationHistory: AgentMessage[];\n  /** Token usage statistics */\n  tokenUsage?: {\n    conversationTokensEstimate: number;\n    truncationOccurred: boolean;\n  };\n}\n\n/**\n * Agent configuration for advanced settings\n */\nexport interface AgentConfig {\n  /** Tool execution timeout in milliseconds (default: 30000) */\n  toolTimeoutMs?: number;\n  /** Maximum tokens for conversation history before truncation (default: 100000) */\n  maxConversationTokens?: number;\n  /** Whether to enable parallel tool execution (default: true) */\n  enableParallelTools?: boolean;\n  /** Maximum number of parallel tool calls per iteration (default: 5) */\n  maxParallelToolCalls?: number;\n}\n"],"mappings":";;;;AAiBA,MAAa,0BAA0B;;;;;AAMvC,MAAa,kCAAkC;;;;AAK/C,MAAa,yBAAyB"}

package/dist/types/auth.types.cjs

@@ -0,0 +1,76 @@
+//#region src/types/auth.types.ts
+/**
+* Default permission sets for built-in roles.
+*/
+const DEFAULT_ROLE_PERMISSIONS = {
+	admin: ["admin:*"],
+	editor: [
+		"flow:create",
+		"flow:read",
+		"flow:update",
+		"flow:delete",
+		"flow:publish",
+		"flow-version:create",
+		"flow-version:read",
+		"flow-run:create",
+		"flow-run:read",
+		"flow-run:cancel",
+		"credential:create",
+		"credential:read",
+		"credential:update",
+		"credential:delete",
+		"agent-tool:read",
+		"agent-tool:configure",
+		"node:test"
+	],
+	operator: [
+		"flow:read",
+		"flow-version:read",
+		"flow-run:create",
+		"flow-run:read",
+		"flow-run:cancel",
+		"credential:read",
+		"agent-tool:read",
+		"node:test"
+	],
+	viewer: [
+		"flow:read",
+		"flow-version:read",
+		"flow-run:read",
+		"credential:read",
+		"agent-tool:read"
+	]
+};
+/**
+* Map of actions to the permission required.
+* Used for route-level authorization.
+*/
+const ACTION_PERMISSION_MAP = {
+	listFlows: "flow:read",
+	getFlow: "flow:read",
+	createFlow: "flow:create",
+	updateFlow: "flow:update",
+	deleteFlow: "flow:delete",
+	publishFlow: "flow:publish",
+	listFlowVersions: "flow-version:read",
+	getFlowVersion: "flow-version:read",
+	createFlowVersion: "flow-version:create",
+	listFlowRuns: "flow-run:read",
+	getFlowRun: "flow-run:read",
+	startFlowRun: "flow-run:create",
+	cancelFlowRun: "flow-run:cancel",
+	listCredentials: "credential:read",
+	getCredential: "credential:read",
+	createCredential: "credential:create",
+	updateCredential: "credential:update",
+	deleteCredential: "credential:delete",
+	listAgentTools: "agent-tool:read",
+	getAgentTool: "agent-tool:read",
+	testSqlQuery: "node:test",
+	testModel: "node:test"
+};
+//#endregion
+exports.ACTION_PERMISSION_MAP = ACTION_PERMISSION_MAP;
+exports.DEFAULT_ROLE_PERMISSIONS = DEFAULT_ROLE_PERMISSIONS;
+
+//# sourceMappingURL=auth.types.cjs.map

package/dist/types/auth.types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.types.cjs","names":[],"sources":["../../src/types/auth.types.ts"],"sourcesContent":["/**\n * Invect Authentication & Authorization Types\n *\n * Authentication is handled by the auth plugin (better-auth).\n * Invect handles authorization based on the identity resolved by the plugin's onRequest hook.\n */\n\n// =============================================================================\n// Identity Types\n// =============================================================================\n\n/**\n * Identity resolved from the host app's authentication system.\n * Invect doesn't care HOW you authenticated - just WHO you are.\n */\nexport interface InvectIdentity {\n  /** Unique user identifier from host app (e.g., user ID, email, API key ID) */\n  id: string;\n\n  /** Optional display name for UI and audit logs */\n  name?: string;\n\n  /**\n   * Role within Invect (maps to permissions).\n   * Host app can either:\n   * 1. Provide a Invect role directly (if they store it)\n   * 2. Use roleMapper in config to map their roles → Invect roles\n   */\n  role?: InvectRole;\n\n  /**\n   * Team IDs this user belongs to (from host app).\n   * Used for team-level flow access when useFlowAccessTable is enabled.\n   */\n  teamIds?: string[];\n\n  /**\n   * Optional: Direct permission overrides (advanced use case).\n   * These are checked IN ADDITION to role-based permissions.\n   */\n  permissions?: InvectPermission[];\n\n  /**\n   * Optional: Resource-level access control.\n   * Restricts access to specific resources by ID.\n   * E.g., user can only access specific flows they created.\n   *\n   * Use '*' to allow access to all resources of that type.\n   * Omit the key entirely to use role-based access (no resource restriction).\n   *\n   * Note: If useFlowAccessTable is enabled, flow access is looked up from\n   * the database instead of this field.\n   */\n  resourceAccess?: InvectResourceAccess;\n\n  /** Any additional metadata from host app (for audit logs, etc.) */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Resource-level access control configuration.\n * Each property is either:\n * - An array of resource IDs the user can access\n * - '*' to allow access to all resources\n * - undefined to not restrict (use role permissions only)\n */\nexport interface InvectResourceAccess {\n  /** Flow IDs the user can access */\n  flows?: string[] | '*';\n  /** Credential IDs the user can access */\n  credentials?: string[] | '*';\n}\n\n// =============================================================================\n// Role & Permission Types\n// =============================================================================\n\n/**\n * Built-in roles with predefined permission sets.\n * Custom roles can be defined via config.customRoles.\n */\nexport type InvectBuiltInRole = 'admin' | 'editor' | 'operator' | 'viewer';\n\n/**\n * Invect role - either a built-in role or a custom role string.\n */\nexport type InvectRole = InvectBuiltInRole | string;\n\n/**\n * Granular permissions for Invect resources.\n */\nexport type InvectPermission =\n  // Flow permissions\n  | 'flow:create'\n  | 'flow:read'\n  | 'flow:update'\n  | 'flow:delete'\n  | 'flow:publish' // Set live version\n  // Flow version permissions\n  | 'flow-version:create'\n  | 'flow-version:read'\n  // Execution permissions\n  | 'flow-run:create' // Start executions\n  | 'flow-run:read'\n  | 'flow-run:cancel'\n  // Credential permissions\n  | 'credential:create'\n  | 'credential:read'\n  | 'credential:update'\n  | 'credential:delete'\n  // Agent/tool permissions\n  | 'agent-tool:read'\n  | 'agent-tool:configure'\n  // Node testing\n  | 'node:test' // Test individual nodes (SQL, model, etc.)\n  // Admin permissions\n  | 'admin:*'; // Wildcard - all permissions\n\n/**\n * Resource types that can be protected by authorization.\n */\nexport type InvectResourceType =\n  | 'flow'\n  | 'flow-version'\n  | 'flow-run'\n  | 'node-execution'\n  | 'credential'\n  | 'agent-tool';\n\n// =============================================================================\n// Authorization Context & Results\n// =============================================================================\n\n/**\n * Context provided to authorization checks.\n */\nexport interface AuthorizationContext {\n  /** The identity making the request (null if unauthenticated) */\n  identity: InvectIdentity | null;\n\n  /** The permission being checked */\n  action: InvectPermission;\n\n  /** The resource being accessed (if applicable) */\n  resource?: {\n    type: InvectResourceType;\n    id?: string;\n  };\n}\n\n/**\n * Result of an authorization check.\n */\nexport interface AuthorizationResult {\n  /** Whether the action is allowed */\n  allowed: boolean;\n  /** Reason for denial (if not allowed) */\n  reason?: string;\n}\n\n// =============================================================================\n// Auth Events (for host app audit logging)\n// =============================================================================\n\n/**\n * Base event data for all auth events.\n */\nexport interface AuthEventBase {\n  /** Timestamp of the event */\n  timestamp: Date;\n  /** Identity that triggered the event (null if unauthenticated) */\n  identity: InvectIdentity | null;\n  /** The permission that was checked */\n  action: InvectPermission;\n  /** The resource involved (if applicable) */\n  resource?: {\n    type: InvectResourceType;\n    id?: string;\n  };\n}\n\n/**\n * Event emitted when authorization succeeds.\n */\nexport interface AuthAuthorizedEvent extends AuthEventBase {\n  type: 'auth:authorized';\n  allowed: true;\n}\n\n/**\n * Event emitted when authorization fails.\n */\nexport interface AuthForbiddenEvent extends AuthEventBase {\n  type: 'auth:forbidden';\n  allowed: false;\n  reason: string;\n}\n\n/**\n * Event emitted when authentication fails (no valid identity).\n */\nexport interface AuthUnauthenticatedEvent {\n  type: 'auth:unauthenticated';\n  timestamp: Date;\n  /** The permission that was attempted */\n  action: InvectPermission;\n  /** The resource involved (if applicable) */\n  resource?: {\n    type: InvectResourceType;\n    id?: string;\n  };\n}\n\n/**\n * Union of all auth events.\n */\nexport type AuthEvent = AuthAuthorizedEvent | AuthForbiddenEvent | AuthUnauthenticatedEvent;\n\n// =============================================================================\n// Configuration Types\n// =============================================================================\n\n/**\n * Callback for custom authorization logic.\n * Called after standard RBAC checks.\n *\n * @returns\n * - true: Allow the action\n * - false: Deny the action\n * - undefined: Use default RBAC result\n */\nexport type CustomAuthorizeFn = (\n  context: AuthorizationContext,\n) => Promise<boolean | undefined> | boolean | undefined;\n\n/**\n * Authentication/Authorization configuration for Invect.\n */\nexport interface InvectAuthConfig {\n  /**\n   * Enable RBAC (Role-Based Access Control).\n   * When false, all requests are allowed without authentication checks.\n   * @default false\n   */\n  enabled?: boolean;\n\n  /**\n   * Map host app roles to Invect roles.\n   * Useful when host app has different role names.\n   *\n   * @example { 'super_admin': 'admin', 'content_editor': 'editor' }\n   */\n  roleMapper?: Record<string, InvectRole>;\n\n  /**\n   * Define custom roles with specific permissions.\n   * Extends built-in roles (admin, editor, operator, viewer).\n   *\n   * @example { 'qa_tester': ['flow:read', 'flow-run:create', 'flow-run:read'] }\n   */\n  customRoles?: Record<string, InvectPermission[]>;\n\n  /**\n   * Callback for custom authorization logic.\n   * Called after standard RBAC checks.\n   * Return true to allow, false to deny, undefined to use default.\n   */\n  customAuthorize?: CustomAuthorizeFn;\n\n  /**\n   * Routes that don't require authentication.\n   * Matched against the request path.\n   *\n   * @example ['/health', '/metrics', '/webhooks/*']\n   */\n  publicRoutes?: string[];\n\n  /**\n   * Default role for authenticated users without an explicit role.\n   * @default 'viewer'\n   */\n  defaultRole?: InvectRole;\n\n  /**\n   * Behavior when auth fails.\n   * - 'throw': Throw an error (401/403)\n   * - 'log': Log warning and continue (allow access)\n   * - 'deny': Silently deny access\n   * @default 'throw'\n   */\n  onAuthFailure?: 'throw' | 'log' | 'deny';\n\n  /**\n   * Use the flow_access database table to manage flow-level permissions.\n   * When enabled:\n   * - Invect stores flow access records in its own database\n   * - Flow access is looked up from the database\n   *\n   * When disabled (default):\n   * - Flow access is determined by resourceAccess.flows from the identity\n   *\n   * @default false\n   */\n  useFlowAccessTable?: boolean;\n}\n\n// =============================================================================\n// Default Role Permissions\n// =============================================================================\n\n/**\n * Default permission sets for built-in roles.\n */\nexport const DEFAULT_ROLE_PERMISSIONS: Record<InvectBuiltInRole, InvectPermission[]> = {\n  admin: ['admin:*'],\n\n  editor: [\n    'flow:create',\n    'flow:read',\n    'flow:update',\n    'flow:delete',\n    'flow:publish',\n    'flow-version:create',\n    'flow-version:read',\n    'flow-run:create',\n    'flow-run:read',\n    'flow-run:cancel',\n    'credential:create',\n    'credential:read',\n    'credential:update',\n    'credential:delete',\n    'agent-tool:read',\n    'agent-tool:configure',\n    'node:test',\n  ],\n\n  operator: [\n    'flow:read',\n    'flow-version:read',\n    'flow-run:create',\n    'flow-run:read',\n    'flow-run:cancel',\n    'credential:read',\n    'agent-tool:read',\n    'node:test',\n  ],\n\n  viewer: ['flow:read', 'flow-version:read', 'flow-run:read', 'credential:read', 'agent-tool:read'],\n};\n\n/**\n * Map of actions to the permission required.\n * Used for route-level authorization.\n */\nexport const ACTION_PERMISSION_MAP: Record<string, InvectPermission> = {\n  // Flows\n  listFlows: 'flow:read',\n  getFlow: 'flow:read',\n  createFlow: 'flow:create',\n  updateFlow: 'flow:update',\n  deleteFlow: 'flow:delete',\n  publishFlow: 'flow:publish',\n\n  // Flow versions\n  listFlowVersions: 'flow-version:read',\n  getFlowVersion: 'flow-version:read',\n  createFlowVersion: 'flow-version:create',\n\n  // Flow runs\n  listFlowRuns: 'flow-run:read',\n  getFlowRun: 'flow-run:read',\n  startFlowRun: 'flow-run:create',\n  cancelFlowRun: 'flow-run:cancel',\n\n  // Credentials\n  listCredentials: 'credential:read',\n  getCredential: 'credential:read',\n  createCredential: 'credential:create',\n  updateCredential: 'credential:update',\n  deleteCredential: 'credential:delete',\n\n  // Agent tools\n  listAgentTools: 'agent-tool:read',\n  getAgentTool: 'agent-tool:read',\n\n  // Node testing\n  testSqlQuery: 'node:test',\n  testModel: 'node:test',\n};\n"],"mappings":";;;;AAyTA,MAAa,2BAA0E;CACrF,OAAO,CAAC,UAAU;CAElB,QAAQ;EACN;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD;CAED,UAAU;EACR;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD;CAED,QAAQ;EAAC;EAAa;EAAqB;EAAiB;EAAmB;EAAkB;CAClG;;;;;AAMD,MAAa,wBAA0D;CAErE,WAAW;CACX,SAAS;CACT,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,aAAa;CAGb,kBAAkB;CAClB,gBAAgB;CAChB,mBAAmB;CAGnB,cAAc;CACd,YAAY;CACZ,cAAc;CACd,eAAe;CAGf,iBAAiB;CACjB,eAAe;CACf,kBAAkB;CAClB,kBAAkB;CAClB,kBAAkB;CAGlB,gBAAgB;CAChB,cAAc;CAGd,cAAc;CACd,WAAW;CACZ"}