@codemation/core-nodes 0.0.13 → 0.0.15

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ReadableStream } from "node:stream/web";
 import { DependencyContainer as Container, InjectionToken as TypeToken } from "tsyringe";
 import { ZodType, input, output } from "zod";
-import { HumanMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
+import { AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
 import { DynamicStructuredTool } from "@langchain/core/tools";
 
 //#region src/canvasIconName.d.ts
@@ -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, ExecutedToolCall, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, If, IfNode, ItemScopedToolBinding, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, PlannedToolCall, 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, ExecutedToolCall, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, If, IfNode, ItemScopedToolBinding, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, PlannedToolCall, ResolvedTool, SubWorkflow, SubWorkflowNode, Wait, WaitDuration, WaitNode, WebhookRespondNowAndContinueError, WebhookRespondNowError, WebhookTrigger, WebhookTriggerNode, createWorkflowBuilder, openAiChatModelPresets, registerCoreNodes };
 //# sourceMappingURL=index.d.cts.map