@codemation/core-nodes 0.0.13 → 0.0.15

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { HumanMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
+import { AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
 import { DynamicStructuredTool } from "@langchain/core/tools";
 import { ReadableStream } from "node:stream/web";
 import { DependencyContainer as Container, InjectionToken as TypeToken } from "tsyringe";
@@ -321,6 +321,7 @@ interface TriggerNodeConfig<TOutputJson$1 = unknown, TSetupState$1 extends JsonV
   readonly [triggerNodeOutputType]?: TOutputJson$1;
   readonly [triggerNodeSetupStateType]?: TSetupState$1;
 }
+type RunnableNodeInputJson<TConfig extends RunnableNodeConfig<any, any>> = TConfig extends RunnableNodeConfig<infer TInputJson, any> ? TInputJson : never;
 type RunnableNodeOutputJson<TConfig extends RunnableNodeConfig<any, any>> = TConfig extends RunnableNodeConfig<any, infer TOutputJson> ? TOutputJson : never;
 type TriggerNodeOutputJson<TConfig extends TriggerNodeConfig<any, any>> = TConfig extends TriggerNodeConfig<infer TOutputJson, any> ? TOutputJson : never;
 type TriggerNodeSetupState<TConfig extends TriggerNodeConfig<any, any>> = TConfig extends TriggerNodeConfig<any, infer TSetupState> ? TSetupState : never;
@@ -508,6 +509,28 @@ declare class WorkflowBuilder {
   build(): WorkflowDefinition;
 }
 //#endregion
+//#region ../core/src/ai/NodeBackedToolConfig.d.ts
+declare class NodeBackedToolConfig<TNodeConfig extends RunnableNodeConfig<any, any>, TInputSchema extends ZodSchemaAny, TOutputSchema extends ZodSchemaAny> implements ToolConfig {
+  readonly name: string;
+  readonly node: TNodeConfig;
+  readonly type: TypeToken<unknown>;
+  readonly toolKind: "nodeBacked";
+  readonly description?: string;
+  readonly presentation?: AgentCanvasPresentation;
+  private readonly inputSchemaValue;
+  private readonly outputSchemaValue;
+  private readonly mapInputValue?;
+  private readonly mapOutputValue?;
+  constructor(name: string, node: TNodeConfig, options: NodeBackedToolConfigOptions<TNodeConfig, TInputSchema, TOutputSchema>);
+  getCredentialRequirements(): ReadonlyArray<CredentialRequirement>;
+  getInputSchema(): TInputSchema;
+  getOutputSchema(): TOutputSchema;
+  toNodeItem(args: NodeBackedToolInputMapperArgs<TNodeConfig, input<TInputSchema>>): Item<RunnableNodeInputJson<TNodeConfig>>;
+  toToolOutput(args: NodeBackedToolOutputMapperArgs<TNodeConfig, input<TInputSchema>>): output<TOutputSchema>;
+  private readDefaultToolOutput;
+  private isItem;
+}
+//#endregion
 //#region ../core/src/ai/AiHost.d.ts
 interface AgentCanvasPresentation<TIcon extends string = string> {
   readonly label?: string;
@@ -515,7 +538,7 @@ interface AgentCanvasPresentation<TIcon extends string = string> {
 }
 type ZodSchemaAny = ZodType<any, any, any>;
 interface ToolConfig {
-  readonly type: TypeToken<Tool<ToolConfig, ZodSchemaAny, ZodSchemaAny>>;
+  readonly type: TypeToken<unknown>;
   readonly name: string;
   readonly description?: string;
   readonly presentation?: AgentCanvasPresentation;
@@ -529,11 +552,41 @@ type ToolExecuteArgs<TConfig extends ToolConfig = ToolConfig, TInput = unknown>
   itemIndex: number;
   items: Items;
 }>;
-interface Tool<TConfig extends ToolConfig = ToolConfig, TInputSchema extends ZodSchemaAny = ZodSchemaAny, TOutputSchema extends ZodSchemaAny = ZodSchemaAny> {
-  readonly defaultDescription: string;
-  readonly inputSchema: TInputSchema;
-  readonly outputSchema: TOutputSchema;
-  execute(args: ToolExecuteArgs<TConfig, input<TInputSchema>>): Promise<output<TOutputSchema>> | output<TOutputSchema>;
+type AgentMessageRole = "system" | "user" | "assistant";
+type AgentMessageBuildArgs<TInputJson$1 = unknown> = Readonly<{
+  item: Item<TInputJson$1>;
+  itemIndex: number;
+  items: Items<TInputJson$1>;
+  ctx: NodeExecutionContext<any>;
+}>;
+interface AgentMessageDto {
+  readonly role: AgentMessageRole;
+  readonly content: string;
+}
+type AgentMessageTemplateContent<TInputJson$1 = unknown> = string | ((args: AgentMessageBuildArgs<TInputJson$1>) => string);
+interface AgentMessageTemplate<TInputJson$1 = unknown> {
+  readonly role: AgentMessageRole;
+  readonly content: AgentMessageTemplateContent<TInputJson$1>;
+}
+/** A single prompt line: fixed DTO or template with optional function `content`. */
+type AgentMessageLine<TInputJson$1 = unknown> = AgentMessageDto | AgentMessageTemplate<TInputJson$1>;
+/**
+ * Message list for an agent. Prefer a **plain array** of `{ role, content }` (optionally with function `content` for templates).
+ * Use the object form only when you need `buildMessages` to append messages after optional `prompt` lines.
+ */
+type AgentMessageConfig<TInputJson$1 = unknown> = ReadonlyArray<AgentMessageLine<TInputJson$1>> | {
+  readonly prompt?: ReadonlyArray<AgentMessageLine<TInputJson$1>>;
+  readonly buildMessages?: (args: AgentMessageBuildArgs<TInputJson$1>) => ReadonlyArray<AgentMessageDto>;
+};
+type AgentTurnLimitBehavior = "error" | "respondWithLastMessage";
+interface AgentModelInvocationOptions {
+  readonly maxTokens?: number;
+  readonly providerOptions?: Readonly<Record<string, JsonValue>>;
+}
+interface AgentGuardrailConfig {
+  readonly maxTurns?: number;
+  readonly onTurnLimitReached?: AgentTurnLimitBehavior;
+  readonly modelInvocationOptions?: AgentModelInvocationOptions;
 }
 type AgentToolCall = Readonly<{
   id?: string;
@@ -556,11 +609,38 @@ interface ChatModelFactory<TConfig extends ChatModelConfig = ChatModelConfig> {
     ctx: NodeExecutionContext<any>;
   }>): Promise<LangChainChatModelLike> | LangChainChatModelLike;
 }
+type NodeBackedToolInputMapperArgs<TNodeConfig extends RunnableNodeConfig<any, any>, TToolInput = unknown> = Readonly<{
+  input: TToolInput;
+  item: Item;
+  itemIndex: number;
+  items: Items;
+  ctx: NodeExecutionContext<any>;
+  node: TNodeConfig;
+}>;
+type NodeBackedToolOutputMapperArgs<TNodeConfig extends RunnableNodeConfig<any, any>, TToolInput = unknown> = Readonly<{
+  input: TToolInput;
+  item: Item;
+  itemIndex: number;
+  items: Items;
+  ctx: NodeExecutionContext<any>;
+  node: TNodeConfig;
+  outputs: NodeOutputs;
+}>;
+type NodeBackedToolInputMapper<TNodeConfig extends RunnableNodeConfig<any, any>, TToolInput = unknown> = (args: NodeBackedToolInputMapperArgs<TNodeConfig, TToolInput>) => Item<RunnableNodeInputJson<TNodeConfig>> | RunnableNodeInputJson<TNodeConfig>;
+type NodeBackedToolOutputMapper<TNodeConfig extends RunnableNodeConfig<any, any>, TToolInput = unknown, TToolOutput = unknown> = (args: NodeBackedToolOutputMapperArgs<TNodeConfig, TToolInput>) => TToolOutput;
+type NodeBackedToolConfigOptions<TNodeConfig extends RunnableNodeConfig<any, any>, TInputSchema extends ZodSchemaAny, TOutputSchema extends ZodSchemaAny> = Readonly<{
+  description?: string;
+  presentation?: AgentCanvasPresentation;
+  inputSchema: TInputSchema;
+  outputSchema: TOutputSchema;
+  mapInput?: NodeBackedToolInputMapper<TNodeConfig, input<TInputSchema>>;
+  mapOutput?: NodeBackedToolOutputMapper<TNodeConfig, input<TInputSchema>, output<TOutputSchema>>;
+}>;
 interface AgentNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> extends RunnableNodeConfig<TInputJson$1, TOutputJson$1> {
-  readonly systemMessage: string;
-  readonly userMessageFormatter: (item: Item<TInputJson$1>, index: number, items: Items<TInputJson$1>, ctx: NodeExecutionContext<any>) => string;
+  readonly messages: AgentMessageConfig<TInputJson$1>;
   readonly chatModel: ChatModelConfig;
   readonly tools?: ReadonlyArray<ToolConfig>;
+  readonly guardrails?: AgentGuardrailConfig;
 }
 //#endregion
 //#region src/chatModels/openAiChatModelConfig.d.ts
@@ -610,12 +690,15 @@ declare const openAiChatModelPresets: OpenAiChatModelPresets;
 //#endregion
 //#region src/nodes/AgentMessageFactory.d.ts
 declare class AgentMessageFactory {
+  static createPromptMessages(messages: ReadonlyArray<AgentMessageDto>): ReadonlyArray<BaseMessage>;
   static createSystemPrompt(systemMessage: string): SystemMessage;
   static createUserPrompt(prompt: string): HumanMessage;
+  static createAssistantPrompt(prompt: string): AIMessage;
   static createToolMessage(toolCallId: string, content: string): ToolMessage;
   static extractContent(message: unknown): string;
   static extractToolCalls(message: unknown): ReadonlyArray<AgentToolCall>;
   private static isRecord;
+  private static createPromptMessage;
 }
 //#endregion
 //#region src/nodes/AgentOutputFactory.d.ts
@@ -631,46 +714,49 @@ declare class AgentToolCallPortMap {
 }
 //#endregion
 //#region src/nodes/AIAgentConfig.d.ts
+interface AIAgentOptions<TInputJson$1 = unknown, _TOutputJson = unknown> {
+  readonly name: string;
+  readonly messages: AgentMessageConfig<TInputJson$1>;
+  readonly chatModel: ChatModelConfig;
+  readonly tools?: ReadonlyArray<ToolConfig>;
+  readonly id?: string;
+  readonly retryPolicy?: RetryPolicySpec;
+  readonly guardrails?: AgentGuardrailConfig;
+}
 /**
  * AI agent: credential bindings are keyed to connection-owned LLM/tool node ids (ConnectionNodeIdFactory),
  * not to the agent workflow node id.
  */
 declare class AIAgent<TInputJson$1 = unknown, TOutputJson$1 = unknown> implements RunnableNodeConfig<TInputJson$1, TOutputJson$1>, AgentNodeConfig<TInputJson$1, TOutputJson$1> {
-  readonly name: string;
-  readonly systemMessage: string;
-  readonly userMessageFormatter: (item: Item<TInputJson$1>, index: number, items: Items<TInputJson$1>, ctx: NodeExecutionContext<AIAgent<TInputJson$1, TOutputJson$1>>) => string;
-  readonly chatModel: ChatModelConfig;
-  readonly tools: ReadonlyArray<ToolConfig>;
-  readonly id?: string | undefined;
-  readonly retryPolicy: RetryPolicySpec;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
   readonly execution: {
     readonly hint: "local";
   };
   readonly icon: "lucide:bot";
-  constructor(name: string, systemMessage: string, userMessageFormatter: (item: Item<TInputJson$1>, index: number, items: Items<TInputJson$1>, ctx: NodeExecutionContext<AIAgent<TInputJson$1, TOutputJson$1>>) => string, chatModel: ChatModelConfig, tools?: ReadonlyArray<ToolConfig>, id?: string | undefined, retryPolicy?: RetryPolicySpec);
+  readonly name: string;
+  readonly messages: AgentMessageConfig<TInputJson$1>;
+  readonly chatModel: ChatModelConfig;
+  readonly tools: ReadonlyArray<ToolConfig>;
+  readonly id?: string;
+  readonly retryPolicy: RetryPolicySpec;
+  readonly guardrails?: AgentGuardrailConfig;
+  constructor(options: AIAgentOptions<TInputJson$1, TOutputJson$1>);
 }
 //#endregion
-//#region src/nodes/AIAgentNodeFactory.d.ts
-declare class AIAgentNode implements Node<AIAgent<any, any>> {
-  private readonly nodeResolver;
-  kind: "node";
-  outputPorts: readonly ["main"];
-  private readonly connectionCredentialExecutionContextFactory;
-  constructor(nodeResolver: NodeResolver, credentialSessions: CredentialSessionService);
-  execute(items: Items, ctx: NodeExecutionContext<AIAgent<any, any>>): Promise<NodeOutputs>;
-  private resolveTools;
-  private createItemScopedTools;
-  private invokeModel;
-  private markQueuedTools;
-  private executeToolCalls;
-  private planToolCalls;
-  private parseToolOutput;
-  private failTrackedNodeInvocation;
-  private summarizeLlmMessages;
-  private toolCallInputToJson;
-  private resultToJsonValue;
+//#region src/nodes/ConnectionCredentialExecutionContextFactory.d.ts
+/**
+ * Builds a {@link NodeExecutionContext} whose identity for credential binding and `getCredential`
+ * is a **connection-owned** workflow node id (`ConnectionNodeIdFactory` in `@codemation/core`),
+ * not the executing parent node. Use for LLM slots, tool slots, or any connection-scoped owner.
+ */
+declare class ConnectionCredentialExecutionContextFactory {
+  private readonly credentialResolverFactory;
+  constructor(credentialSessions: CredentialSessionService);
+  forConnectionNode<TConfig extends NodeConfigBase>(ctx: NodeExecutionContext<TConfig>, args: Readonly<{
+    connectionNodeId: NodeId;
+    getCredentialRequirements: () => ReadonlyArray<CredentialRequirement>;
+  }>): NodeExecutionContext<TConfig>;
 }
 //#endregion
 //#region src/nodes/aiAgentSupport.types.d.ts
@@ -679,7 +765,11 @@ declare class AgentItemPortMap {
 }
 type ResolvedTool = Readonly<{
   config: ToolConfig;
-  tool: Tool<ToolConfig, ZodSchemaAny, ZodSchemaAny>;
+  runtime: Readonly<{
+    defaultDescription: string;
+    inputSchema: ZodSchemaAny;
+    execute(args: ToolExecuteArgs<ToolConfig, unknown>): Promise<unknown>;
+  }>;
 }>;
 type ItemScopedToolBinding = Readonly<{
   config: ToolConfig;
@@ -698,6 +788,69 @@ type ExecutedToolCall = Readonly<{
   serialized: string;
 }>;
 //#endregion
+//#region src/nodes/AIAgentExecutionHelpersFactory.d.ts
+/**
+ * LangChain adapters and credential context wiring for {@link AIAgentNode}.
+ * Lives in a `*Factory.ts` composition-root module so construction stays explicit and testable.
+ */
+declare class AIAgentExecutionHelpersFactory {
+  createConnectionCredentialExecutionContextFactory(credentialSessions: CredentialSessionService): ConnectionCredentialExecutionContextFactory;
+  createDynamicStructuredTool(entry: ResolvedTool, toolCredentialContext: NodeExecutionContext<any>, item: Item, itemIndex: number, items: Items): DynamicStructuredTool;
+}
+//#endregion
+//#region src/nodes/NodeBackedToolRuntime.d.ts
+declare class NodeBackedToolRuntime {
+  private readonly nodeResolver;
+  constructor(nodeResolver: NodeResolver);
+  execute(config: NodeBackedToolConfig<any, ZodSchemaAny, ZodSchemaAny>, args: ToolExecuteArgs): Promise<unknown>;
+  private executeResolvedNode;
+  private isNode;
+  private isMultiInputNode;
+}
+//#endregion
+//#region src/nodes/AIAgentNode.d.ts
+declare class AIAgentNode implements Node<AIAgent<any, any>> {
+  private readonly nodeResolver;
+  private readonly nodeBackedToolRuntime;
+  private readonly executionHelpers;
+  kind: "node";
+  outputPorts: readonly ["main"];
+  private readonly connectionCredentialExecutionContextFactory;
+  constructor(nodeResolver: NodeResolver, credentialSessions: CredentialSessionService, nodeBackedToolRuntime: NodeBackedToolRuntime, executionHelpers: AIAgentExecutionHelpersFactory);
+  execute(items: Items, ctx: NodeExecutionContext<AIAgent<any, any>>): Promise<NodeOutputs>;
+  /**
+   * Resolves the chat model and tools once, then returns shared state for every item in the batch.
+   */
+  private prepareExecution;
+  /**
+   * One item: build prompts, optionally bind tools, run the multi-turn loop, map the final model message to workflow JSON.
+   */
+  private runAgentForItem;
+  /**
+   * Repeatedly invokes the model until it returns without tool calls, or guardrails end the loop.
+   */
+  private runTurnLoopUntilFinalAnswer;
+  private cannotExecuteAnotherToolRound;
+  private finishOrThrowWhenTurnCapHitWithToolCalls;
+  private appendAssistantAndToolMessages;
+  private buildOutputItem;
+  private bindToolsToModel;
+  private resolveTools;
+  private createItemScopedTools;
+  private invokeModel;
+  private markQueuedTools;
+  private executeToolCalls;
+  private planToolCalls;
+  private parseToolOutput;
+  private failTrackedNodeInvocation;
+  private summarizeLlmMessages;
+  private toolCallInputToJson;
+  private resultToJsonValue;
+  private createPromptMessages;
+  private resolveToolRuntime;
+  private resolveGuardrails;
+}
+//#endregion
 //#region src/nodes/CallbackNode.d.ts
 declare class CallbackNode implements Node<Callback<any, any>> {
   kind: "node";
@@ -1072,20 +1225,5 @@ declare class AIAgentConnectionWorkflowExpander {
   private assertNoIdCollision;
 }
 //#endregion
-//#region src/nodes/ConnectionCredentialExecutionContextFactory.d.ts
-/**
- * Builds a {@link NodeExecutionContext} whose identity for credential binding and `getCredential`
- * is a **connection-owned** workflow node id (`ConnectionNodeIdFactory` in `@codemation/core`),
- * not the executing parent node. Use for LLM slots, tool slots, or any connection-scoped owner.
- */
-declare class ConnectionCredentialExecutionContextFactory {
-  private readonly credentialResolverFactory;
-  constructor(credentialSessions: CredentialSessionService);
-  forConnectionNode<TConfig extends NodeConfigBase>(ctx: NodeExecutionContext<TConfig>, args: Readonly<{
-    connectionNodeId: NodeId;
-    getCredentialRequirements: () => ReadonlyArray<CredentialRequirement>;
-  }>): NodeExecutionContext<TConfig>;
-}
-//#endregion
-export { AIAgent, AIAgentConnectionWorkflowExpander, AIAgentNode, AgentItemPortMap, AgentMessageFactory, AgentOutputFactory, AgentToolCallPortMap, Callback, CallbackHandler, CallbackNode, CallbackResultNormalizer, CanvasIconName, ConnectionCredentialExecutionContextFactory, ConnectionCredentialNode, ConnectionCredentialNodeConfig, ConnectionCredentialNodeConfigFactory, type ExecutedToolCall, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, If, IfNode, type ItemScopedToolBinding, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, type PlannedToolCall, type ResolvedTool, SubWorkflow, SubWorkflowNode, Wait, WaitDuration, WaitNode, WebhookRespondNowAndContinueError, WebhookRespondNowError, WebhookTrigger, WebhookTriggerNode, createWorkflowBuilder, openAiChatModelPresets, registerCoreNodes };
+export { AIAgent, AIAgentConnectionWorkflowExpander, AIAgentExecutionHelpersFactory, AIAgentNode, AgentItemPortMap, AgentMessageFactory, AgentOutputFactory, AgentToolCallPortMap, Callback, CallbackHandler, CallbackNode, CallbackResultNormalizer, CanvasIconName, ConnectionCredentialExecutionContextFactory, ConnectionCredentialNode, ConnectionCredentialNodeConfig, ConnectionCredentialNodeConfigFactory, type ExecutedToolCall, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, If, IfNode, type ItemScopedToolBinding, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, type PlannedToolCall, type ResolvedTool, SubWorkflow, SubWorkflowNode, Wait, WaitDuration, WaitNode, WebhookRespondNowAndContinueError, WebhookRespondNowError, WebhookTrigger, WebhookTriggerNode, createWorkflowBuilder, openAiChatModelPresets, registerCoreNodes };
 //# sourceMappingURL=index.d.ts.map