@codemation/core 0.11.0 → 0.12.0

package/dist/ItemsInputNormalizer-C09a7iFP.d.ts

@@ -0,0 +1,321 @@
+import { Aa as TelemetrySpanScope, Fi as NodeExecutionContext, Mr as RunnableNodeConfig, Nr as RunnableNodeInputJson, On as TypeToken, Rt as ConnectionInvocationId, Sr as NodeOutputs, To as NodeId, fr as NodeConfigBase, gt as Expr, ir as Items, lo as CredentialRequirement, lr as JsonValue, nr as Item, q as McpServerDeclaration, wo as NodeConnectionName } from "./index-CSKKuK60.js";
+import { ZodType, input, output } from "zod";
+
+//#region 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 src/ai/CallableToolConfig.d.ts
+type CallableToolExecuteHandler<TInputSchema extends ZodSchemaAny, TOutputSchema extends ZodSchemaAny> = (args: ToolExecuteArgs<CallableToolConfig<TInputSchema, TOutputSchema>, input<TInputSchema>>) => Promise<output<TOutputSchema>> | output<TOutputSchema>;
+type CallableToolConfigOptions<TInputSchema extends ZodSchemaAny, TOutputSchema extends ZodSchemaAny> = Readonly<{
+  name: string;
+  description?: string;
+  presentation?: AgentCanvasPresentation;
+  inputSchema: TInputSchema;
+  outputSchema: TOutputSchema;
+  /**
+   * Optional credential slots for this tool (same contract as other {@link ToolConfig} shapes).
+   */
+  credentialRequirements?: ReadonlyArray<CredentialRequirement>;
+  execute: CallableToolExecuteHandler<TInputSchema, TOutputSchema>;
+}>;
+/**
+ * Inline callable agent tool: DSL sugar over {@link ToolConfig} without a separate {@link NodeResolver}-registered {@link Tool} class.
+ */
+declare class CallableToolConfig<TInputSchema extends ZodSchemaAny, TOutputSchema extends ZodSchemaAny> implements ToolConfig {
+  readonly name: string;
+  readonly type: TypeToken<unknown>;
+  readonly toolKind: "callable";
+  readonly description?: string;
+  readonly presentation?: AgentCanvasPresentation;
+  private readonly inputSchemaValue;
+  private readonly outputSchemaValue;
+  private readonly credentialRequirementsValue?;
+  private readonly executeHandler;
+  constructor(name: string, options: CallableToolConfigOptions<TInputSchema, TOutputSchema>);
+  getCredentialRequirements(): ReadonlyArray<CredentialRequirement>;
+  getInputSchema(): TInputSchema;
+  getOutputSchema(): TOutputSchema;
+  /**
+   * Parses tool input and output with the configured Zod schemas.
+   */
+  executeTool(args: ToolExecuteArgs<CallableToolConfig<TInputSchema, TOutputSchema>, input<TInputSchema>>): Promise<output<TOutputSchema>>;
+  private parseInput;
+  private parseOutput;
+  private decorateValidationError;
+}
+//#endregion
+//#region src/ai/CallableToolFactory.d.ts
+declare class CallableToolFactoryImpl {
+  callableTool<TInputSchema extends ZodSchemaAny, TOutputSchema extends ZodSchemaAny>(options: CallableToolConfigOptions<TInputSchema, TOutputSchema>): CallableToolConfig<TInputSchema, TOutputSchema>;
+}
+declare const CallableToolFactory: CallableToolFactoryImpl;
+//#endregion
+//#region src/ai/CallableToolKindToken.d.ts
+/**
+ * Shared {@link import("../di").TypeToken} marker for {@link CallableToolConfig}.
+ * Callable tools are not registered in {@link NodeResolver}; this class only satisfies {@link ToolConfig#type}.
+ */
+declare class CallableToolKindToken {}
+//#endregion
+//#region src/ai/AgentToolFactory.d.ts
+declare class AgentToolFactoryImpl {
+  asTool<TNodeConfig extends RunnableNodeConfig<any, any>, TInputSchema extends ZodSchemaAny, TOutputSchema extends ZodSchemaAny>(node: TNodeConfig, options: Readonly<{
+    name?: string;
+  } & NodeBackedToolConfigOptions<TNodeConfig, TInputSchema, TOutputSchema>>): NodeBackedToolConfig<TNodeConfig, TInputSchema, TOutputSchema>;
+  private withDefaultAgentInputMapper;
+  private mergeAgentToolInputWithCurrentItem;
+  private isMergeableRecord;
+}
+declare const AgentToolFactory: AgentToolFactoryImpl;
+//#endregion
+//#region src/ai/AgentMessageConfigNormalizerFactory.d.ts
+declare class AgentMessageConfigNormalizer {
+  /**
+   * Prefer {@code input.messages} when present (ItemNode / engine-mapped payloads); otherwise resolve from
+   * {@link AgentNodeConfig.messages} templates.
+   */
+  static resolveFromInputOrConfig<TInputJson, TOutputJson>(input: unknown, config: AgentNodeConfig<TInputJson, TOutputJson>, args: AgentMessageBuildArgs<TInputJson>): ReadonlyArray<AgentMessageDto>;
+  static normalize<TInputJson, TOutputJson>(config: AgentNodeConfig<TInputJson, TOutputJson>, args: AgentMessageBuildArgs<TInputJson>): ReadonlyArray<AgentMessageDto>;
+  private static tryMessagesFromStructuredInput;
+  private static normalizeRichMessages;
+  private static lineToDto;
+}
+//#endregion
+//#region src/ai/AgentConfigInspectorFactory.d.ts
+declare class AgentConfigInspector {
+  static isAgentNodeConfig(config: NodeConfigBase | undefined): config is AgentNodeConfig<any, any>;
+  private static hasCompatibleMessageConfiguration;
+}
+//#endregion
+//#region src/ai/AiHost.d.ts
+interface AgentCanvasPresentation<TIcon extends string = string> {
+  readonly label?: string;
+  readonly icon?: TIcon;
+}
+type ZodSchemaAny = ZodType<any, any, any>;
+interface ToolConfig {
+  readonly type: TypeToken<unknown>;
+  readonly name: string;
+  readonly description?: string;
+  readonly presentation?: AgentCanvasPresentation;
+  getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+}
+type ToolExecuteArgs<TConfig extends ToolConfig = ToolConfig, TInput = unknown> = Readonly<{
+  config: TConfig;
+  input: TInput;
+  ctx: NodeExecutionContext<any>;
+  item: Item;
+  itemIndex: number;
+  items: Items;
+  /**
+   * Optional sub-agent boundary hooks: when present, the live `agent.tool.call` span and the
+   * planned tool-call invocationId are forwarded so node-backed runtimes can re-root their child
+   * execution scope. Plain function tools may safely ignore these hooks.
+   */
+  hooks?: Readonly<{
+    parentSpan?: TelemetrySpanScope;
+    parentInvocationId?: ConnectionInvocationId;
+  }>;
+}>;
+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 AgentTool<TInputSchema extends ZodSchemaAny = ZodSchemaAny, TOutputSchema extends ZodSchemaAny = ZodSchemaAny> = Tool<ToolConfig, TInputSchema, TOutputSchema>;
+type AgentToolExecuteArgs<TInput = unknown> = ToolExecuteArgs<ToolConfig, TInput>;
+type AgentToolToken = TypeToken<Tool<ToolConfig, ZodSchemaAny, ZodSchemaAny>>;
+type AgentMessageRole = "system" | "user" | "assistant";
+type AgentMessageBuildArgs<TInputJson = unknown> = Readonly<{
+  item: Item<TInputJson>;
+  itemIndex: number;
+  items: Items<TInputJson>;
+  ctx: NodeExecutionContext<any>;
+}>;
+interface AgentMessageDto {
+  readonly role: AgentMessageRole;
+  readonly content: string;
+}
+type AgentMessageTemplateContent<TInputJson = unknown> = string | ((args: AgentMessageBuildArgs<TInputJson>) => string);
+interface AgentMessageTemplate<TInputJson = unknown> {
+  readonly role: AgentMessageRole;
+  readonly content: AgentMessageTemplateContent<TInputJson>;
+}
+/** A single prompt line: fixed DTO or template with optional function `content`. */
+type AgentMessageLine<TInputJson = unknown> = AgentMessageDto | AgentMessageTemplate<TInputJson>;
+/**
+ * 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 = unknown> = Expr<ReadonlyArray<AgentMessageLine<TInputJson>>, TInputJson> | ReadonlyArray<AgentMessageLine<TInputJson>> | {
+  readonly prompt?: ReadonlyArray<AgentMessageLine<TInputJson>>;
+  readonly buildMessages?: (args: AgentMessageBuildArgs<TInputJson>) => 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;
+}
+/** Defaults aligned with common tool-agent iteration limits (many products use ~10 max rounds). */
+declare const AgentGuardrailDefaults: {
+  readonly maxTurns: 10;
+  readonly onTurnLimitReached: AgentTurnLimitBehavior;
+};
+interface AgentToolDefinition {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: ZodSchemaAny;
+}
+type AgentToolCall = Readonly<{
+  id?: string;
+  name: string;
+  input: unknown;
+}>;
+type AgentToolCallPlanner<_TNodeConfig = unknown> = (item: Item, index: number, items: Items, ctx: NodeExecutionContext<any>) => ReadonlyArray<AgentToolCall>;
+interface ChatModelConfig {
+  readonly type: TypeToken<ChatModelFactory<ChatModelConfig>>;
+  readonly name: string;
+  readonly provider?: string;
+  readonly modelName?: string;
+  readonly presentation?: AgentCanvasPresentation;
+  getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+}
+/**
+ * Provider-neutral chat language model wrapper returned by a {@link ChatModelFactory}.
+ *
+ * Thin adapter around an AI SDK `LanguageModelV2` (from `@ai-sdk/provider`) plus the call-site
+ * defaults Codemation needs at every generate/stream: the provider label, the model name used for
+ * pricing / telemetry, and the default invocation options (max output tokens, temperature,
+ * provider-specific overrides).
+ *
+ * The consumer (AIAgentNode / AgentStructuredOutputRunner) passes `languageModel` directly into
+ * `generateText({ model, ... })` from the `ai` package.
+ */
+interface ChatLanguageModel {
+  /** AI SDK `LanguageModelV2` instance (kept `unknown` to avoid leaking the SDK type into `@codemation/core`). */
+  readonly languageModel: unknown;
+  /** Stable pricing/telemetry key — e.g. `"gpt-4.1-nano"`. */
+  readonly modelName: string;
+  /** Provider label — e.g. `"openai"`. Used for cost tracking. */
+  readonly provider?: string;
+  /** Defaults merged into every call. Consumers may override per-invocation. */
+  readonly defaultCallOptions?: ChatLanguageModelCallOptions;
+}
+interface ChatLanguageModelCallOptions {
+  readonly maxOutputTokens?: number;
+  readonly temperature?: number;
+  readonly providerOptions?: Readonly<Record<string, Readonly<Record<string, JsonValue>>>>;
+}
+/**
+ * Options for a structured-output generate call. Mirrors
+ * `generateText({ output: Output.object(...) })` from the `ai` package.
+ */
+interface StructuredOutputOptions {
+  /** Optional schema name — used by some providers as the JSON schema name attribute. */
+  readonly schemaName?: string;
+  /** When `true`, the consumer should pass a strict-mode-compatible JSON Schema record. */
+  readonly strict?: boolean;
+}
+interface ChatModelFactory<TConfig extends ChatModelConfig = ChatModelConfig> {
+  create(args: Readonly<{
+    config: TConfig;
+    ctx: NodeExecutionContext<any>;
+  }>): Promise<ChatLanguageModel> | ChatLanguageModel;
+}
+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 = unknown, TOutputJson = unknown> extends RunnableNodeConfig<TInputJson, TOutputJson> {
+  readonly messages: AgentMessageConfig<TInputJson>;
+  readonly chatModel: ChatModelConfig;
+  readonly tools?: ReadonlyArray<ToolConfig>;
+  readonly guardrails?: AgentGuardrailConfig;
+  readonly outputSchema?: ZodType<TOutputJson>;
+}
+type AgentAttachmentRole = "languageModel" | "tool" | "nestedAgent";
+//#endregion
+//#region src/ai/AgentConnectionNodeCollector.d.ts
+type AgentConnectionNodeRole = "languageModel" | "tool" | "nestedAgent";
+type AgentConnectionCredentialSource = Readonly<{
+  getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+}>;
+type AgentConnectionNodeDescriptor = Readonly<{
+  nodeId: NodeId;
+  parentNodeId: NodeId;
+  connectionName: NodeConnectionName;
+  role: AgentConnectionNodeRole;
+  name: string;
+  typeName: string;
+  icon?: string;
+  credentialSource: AgentConnectionCredentialSource;
+}>;
+type McpServerResolver = (id: string) => McpServerDeclaration | undefined;
+type AgentConnectionNodeCollectorApi = Readonly<{
+  collect(parentNodeId: NodeId, agentConfig: AgentNodeConfig<any, any>, mcpServerResolver?: McpServerResolver): ReadonlyArray<AgentConnectionNodeDescriptor>;
+}>;
+declare const AgentConnectionNodeCollector: AgentConnectionNodeCollectorApi;
+//#endregion
+//#region src/serialization/ItemsInputNormalizer.d.ts
+/**
+ * Normalizes external inputs into the engine's canonical `Items` shape.
+ * Used at host and builder boundaries where callers may provide either a raw value,
+ * a single item-like object, or an array of item-like values.
+ */
+declare class ItemsInputNormalizer {
+  normalize(raw: unknown): Items;
+  private normalizeItem;
+  private isItem;
+}
+//#endregion
+export { ChatModelFactory as A, ZodSchemaAny as B, AgentToolDefinition as C, ChatLanguageModel as D, AgentTurnLimitBehavior as E, NodeBackedToolOutputMapperArgs as F, CallableToolFactory as G, AgentMessageConfigNormalizer as H, StructuredOutputOptions as I, CallableToolExecuteHandler as J, CallableToolConfig as K, Tool as L, NodeBackedToolInputMapper as M, NodeBackedToolInputMapperArgs as N, ChatLanguageModelCallOptions as O, NodeBackedToolOutputMapper as P, ToolConfig as R, AgentToolCallPlanner as S, AgentToolToken as T, AgentToolFactory as U, AgentConfigInspector as V, CallableToolKindToken as W, NodeBackedToolConfig as Y, AgentMessageTemplateContent as _, AgentConnectionNodeRole as a, AgentTool as b, AgentCanvasPresentation as c, AgentMessageBuildArgs as d, AgentMessageConfig as f, AgentMessageTemplate as g, AgentMessageRole as h, AgentConnectionNodeDescriptor as i, NodeBackedToolConfigOptions as j, ChatModelConfig as k, AgentGuardrailConfig as l, AgentMessageLine as m, AgentConnectionCredentialSource as n, McpServerResolver as o, AgentMessageDto as p, CallableToolConfigOptions as q, AgentConnectionNodeCollector as r, AgentAttachmentRole as s, ItemsInputNormalizer as t, AgentGuardrailDefaults as u, AgentModelInvocationOptions as v, AgentToolExecuteArgs as w, AgentToolCall as x, AgentNodeConfig as y, ToolExecuteArgs as z };
+//# sourceMappingURL=ItemsInputNormalizer-C09a7iFP.d.ts.map