@n8n/agents 0.26.3 → 0.27.1

package/dist/types/runtime/agent-loop.d.ts

@@ -0,0 +1,73 @@
+import type { LanguageModel, LanguageModelCallOptions, ModelMessage, Output, SystemModelMessage, TelemetryOptions, ToolCallRepairFunction, ToolSet } from 'ai';
+import type { FinishReason, SerializableAgentState, TokenUsage } from '../index';
+import type { ExecutionOptions, RunOptions } from '../sdk/agent';
+import type { AgentMessage } from '../sdk/message';
+import type { JSONObject } from '../utils/json';
+import type { AgentMessageList } from '../../runtime/model/message-list';
+import type { ToolCallBatchResult, ToolCallInput, ToolCallSuspension } from './tool-execution';
+type RunCallOptions = (RunOptions & ExecutionOptions) | undefined;
+export type ModelTurnErrorType = 'prompt_blocked' | 'no_output';
+export interface ModelTurnError {
+    type: ModelTurnErrorType;
+    message: string;
+}
+export interface ModelTurnResult {
+    aiFinishReason: string;
+    finishReason: FinishReason;
+    usage: TokenUsage | undefined;
+    newMessages: AgentMessage[];
+    toolCalls: ToolCallInput[];
+    structuredOutput: unknown;
+    errorReason?: ModelTurnError;
+}
+export interface ModelCallContext {
+    model: LanguageModel;
+    system: SystemModelMessage | SystemModelMessage[];
+    messages: ModelMessage[];
+    abortSignal: AbortSignal;
+    hasTools: boolean;
+    aiTools: ToolSet;
+    reasoning?: LanguageModelCallOptions['reasoning'];
+    providerOptions?: Record<string, JSONObject>;
+    outputSpec?: ReturnType<typeof Output.object>;
+    maxOutputTokens?: number;
+    onInputRejected?: (error: unknown) => Promise<void>;
+    aiSdkOptions: {
+        telemetry?: TelemetryOptions;
+        repairToolCall?: ToolCallRepairFunction<NoInfer<ToolSet>>;
+    };
+}
+export interface SuspendEmission {
+    suspendRunId: string;
+    list: AgentMessageList;
+    usage: TokenUsage | undefined;
+    suspensions: ToolCallSuspension[];
+}
+export interface CompleteEmission {
+    list: AgentMessageList;
+    options: RunCallOptions;
+    finishReason: FinishReason;
+    usage: TokenUsage | undefined;
+    structuredOutput: unknown;
+}
+export interface RunServices {
+    readonly runId: string;
+    readonly modelId: string;
+    applyCost(usage: TokenUsage | undefined): TokenUsage | undefined;
+    saveToMemory(list: AgentMessageList, options: RunCallOptions): Promise<void>;
+    maybeGenerateTitle(list: AgentMessageList, options: RunCallOptions): Promise<void>;
+    flushTelemetry(options: RunCallOptions): Promise<void>;
+    cleanupRun(): Promise<void>;
+    updateState(patch: Partial<SerializableAgentState>): void;
+    emitAgentEnd(messages: AgentMessage[]): void;
+    getState(): SerializableAgentState;
+}
+export interface RunOutputSink<TResult> {
+    callModel(ctx: ModelCallContext): Promise<ModelTurnResult>;
+    reportUsage(usage: TokenUsage | undefined): void;
+    onTurnFolded?(): void;
+    emitToolBatch(batch: ToolCallBatchResult): Promise<void>;
+    finishSuspended(emission: SuspendEmission): Promise<TResult>;
+    finishComplete(emission: CompleteEmission): Promise<TResult>;
+}
+export {};

package/dist/types/runtime/agent-loop.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=agent-loop.js.map

package/dist/types/runtime/agent-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-loop.js","sourceRoot":"","sources":["../../../src/types/runtime/agent-loop.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,51 @@
+import type { ProviderOptions } from '@ai-sdk/provider-utils';
+import type { JSONSchema7 } from 'json-schema';
+import type { z } from 'zod';
+import type { FetchFn } from '../../runtime/model/model-factory';
+import type { ScopedMemoryTaskEvent } from '../../runtime/memory/scoped-memory-task-runner';
+import type { AgentEventBus } from '../../runtime/state/event-bus';
+import type { RunStateManager } from '../../runtime/state/run-state';
+import type { ModelCost } from '../../sdk/catalog';
+import type { RuntimeSkillSource } from '../../skills/types';
+import type { WorkspaceFilesystem } from '../../workspace';
+import type { BuiltFileStore, BuiltMemory, BuiltProviderTool, BuiltTelemetry, BuiltTool, CheckpointStore, EpisodicMemoryConfig, McpConnectionFailedEvent, ObservationalMemoryConfig, ObservationLogMemoryConfig, ReasoningLevel, ThinkingConfig, TitleGenerationConfig } from '../index';
+import type { AgentPersistenceOptions, ModelConfig, PromptCachingConfig } from '../sdk/agent';
+export interface VolatileInstructionsContext {
+    persistence?: AgentPersistenceOptions;
+}
+export type VolatileInstructionsProvider = (context: VolatileInstructionsContext) => Promise<string | undefined>;
+export interface AgentRuntimeConfig {
+    name: string;
+    model: ModelConfig;
+    modelFetch?: FetchFn;
+    instructions: string;
+    skillSource?: RuntimeSkillSource;
+    instructionProviderOptions?: ProviderOptions;
+    tools?: BuiltTool[];
+    deferredTools?: BuiltTool[];
+    workspaceFilesystem?: WorkspaceFilesystem;
+    toolSearch?: {
+        topK?: number;
+    };
+    providerTools?: BuiltProviderTool[];
+    memory?: BuiltMemory;
+    fileStore?: BuiltFileStore;
+    observationLog?: ObservationLogMemoryConfig;
+    observationalMemory?: ObservationalMemoryConfig;
+    episodicMemory?: EpisodicMemoryConfig;
+    structuredOutput?: z.ZodType | JSONSchema7;
+    checkpointStorage?: 'memory' | CheckpointStore;
+    thinking?: ThinkingConfig;
+    reasoning?: ReasoningLevel;
+    promptCaching?: PromptCachingConfig;
+    eventBus?: AgentEventBus;
+    toolCallConcurrency?: number;
+    titleGeneration?: TitleGenerationConfig;
+    telemetry?: BuiltTelemetry;
+    runId?: string;
+    modelCost?: ModelCost;
+    runState?: RunStateManager;
+    onMemoryTaskEvent?: (event: ScopedMemoryTaskEvent) => void;
+    mcpConnectionFailures?: McpConnectionFailedEvent[];
+    volatileInstructionsProvider?: VolatileInstructionsProvider;
+}

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

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=agent-runtime.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runtime.js","sourceRoot":"","sources":["../../../src/types/runtime/agent-runtime.ts"],"names":[],"mappings":""}

package/dist/types/runtime/delegation.d.ts

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+import type { SubAgentTaskPath, SubAgentTaskPathPolicy } from '../../runtime/tools/sub-agent-task-path';
+import type { AgentExecutionCounter, FinishReason, GenerateResult, ModelConfig, StreamChunk, TokenUsage } from '../sdk/agent';
+import type { BuiltProviderTool } from '../sdk/tool';
+import type { BuiltTelemetry } from '../telemetry';
+import type { JSONObject, JSONValue } from '../utils/json';
+export declare const DELEGATE_SUB_AGENT_TOOL_NAME = "delegate_subagent";
+export declare const INLINE_SUB_AGENT_ID = "inline";
+export declare const DELEGATED_CHILD_SUSPEND_UNSUPPORTED_MESSAGE = "agents.chat.delegate.childSuspendUnsupported";
+export declare const INLINE_DELEGATE_SUB_AGENT_TOOL_METADATA_KEY = "inlineDelegateSubAgent";
+export declare const SUB_AGENT_TASK_DIFFICULTIES: readonly ['low', 'medium', 'high'];
+declare const SubAgentTaskDifficultySchema: z.ZodEnum<["low", "medium", "high"]>;
+export type SubAgentTaskDifficulty = z.infer<typeof SubAgentTaskDifficultySchema>;
+export declare const delegateSubAgentInputSchema: z.ZodObject<{
+    subAgentId: z.ZodString;
+    taskName: z.ZodString;
+    goal: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    expectedOutput: z.ZodOptional<z.ZodString>;
+    difficulty: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+}, "strip", z.ZodTypeAny, {
+    subAgentId: string;
+    taskName: string;
+    goal: string;
+    context?: string | undefined;
+    expectedOutput?: string | undefined;
+    difficulty?: "high" | "low" | "medium" | undefined;
+}, {
+    subAgentId: string;
+    taskName: string;
+    goal: string;
+    context?: string | undefined;
+    expectedOutput?: string | undefined;
+    difficulty?: "high" | "low" | "medium" | undefined;
+}>;
+export declare const delegateSubAgentOutputSchema: z.ZodObject<{
+    status: z.ZodEnum<["completed", "failed", "suspended", "cancelled"]>;
+    taskPath: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    threadId: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    answer: z.ZodString;
+    structuredOutput: z.ZodOptional<z.ZodUnknown>;
+    usage: z.ZodOptional<z.ZodObject<{
+        promptTokens: z.ZodOptional<z.ZodNumber>;
+        completionTokens: z.ZodOptional<z.ZodNumber>;
+        totalTokens: z.ZodOptional<z.ZodNumber>;
+        cost: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        promptTokens?: number | undefined;
+        completionTokens?: number | undefined;
+        totalTokens?: number | undefined;
+        cost?: number | undefined;
+    }, {
+        promptTokens?: number | undefined;
+        completionTokens?: number | undefined;
+        totalTokens?: number | undefined;
+        cost?: number | undefined;
+    }>>;
+    finishReason: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    resumeContext: z.ZodOptional<z.ZodType<JSONValue, z.ZodTypeDef, JSONValue>>;
+    pendingSuspend: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        runId: z.ZodString;
+        toolCallId: z.ZodString;
+        toolName: z.ZodString;
+        input: z.ZodUnknown;
+        suspendPayload: z.ZodUnknown;
+        resumeSchema: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        runId: string;
+        toolCallId: string;
+        toolName: string;
+        input?: unknown;
+        suspendPayload?: unknown;
+        resumeSchema?: unknown;
+    }, {
+        runId: string;
+        toolCallId: string;
+        toolName: string;
+        input?: unknown;
+        suspendPayload?: unknown;
+        resumeSchema?: unknown;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    status: "cancelled" | "completed" | "failed" | "suspended";
+    taskPath?: string | undefined;
+    runId?: string | undefined;
+    threadId?: string | undefined;
+    model?: string | undefined;
+    answer: string;
+    structuredOutput?: unknown;
+    usage?: {
+        promptTokens?: number | undefined;
+        completionTokens?: number | undefined;
+        totalTokens?: number | undefined;
+        cost?: number | undefined;
+    } | undefined;
+    finishReason?: string | undefined;
+    error?: string | undefined;
+    resumeContext?: JSONValue | undefined;
+    pendingSuspend?: {
+        runId: string;
+        toolCallId: string;
+        toolName: string;
+        input?: unknown;
+        suspendPayload?: unknown;
+        resumeSchema?: unknown;
+    }[] | undefined;
+}, {
+    status: "cancelled" | "completed" | "failed" | "suspended";
+    taskPath?: string | undefined;
+    runId?: string | undefined;
+    threadId?: string | undefined;
+    model?: string | undefined;
+    answer: string;
+    structuredOutput?: unknown;
+    usage?: {
+        promptTokens?: number | undefined;
+        completionTokens?: number | undefined;
+        totalTokens?: number | undefined;
+        cost?: number | undefined;
+    } | undefined;
+    finishReason?: string | undefined;
+    error?: string | undefined;
+    resumeContext?: JSONValue | undefined;
+    pendingSuspend?: {
+        runId: string;
+        toolCallId: string;
+        toolName: string;
+        input?: unknown;
+        suspendPayload?: unknown;
+        resumeSchema?: unknown;
+    }[] | undefined;
+}>;
+declare const delegateSubAgentContinuationSchema: z.ZodObject<{
+    runId: z.ZodString;
+    toolCallId: z.ZodString;
+    taskPath: z.ZodString;
+    subAgentId: z.ZodString;
+    childCount: z.ZodNumber;
+    threadId: z.ZodOptional<z.ZodString>;
+    resumeContext: z.ZodOptional<z.ZodType<JSONValue, z.ZodTypeDef, JSONValue>>;
+}, "strip", z.ZodTypeAny, {
+    runId: string;
+    toolCallId: string;
+    taskPath: string;
+    subAgentId: string;
+    childCount: number;
+    threadId?: string | undefined;
+    resumeContext?: JSONValue | undefined;
+}, {
+    runId: string;
+    toolCallId: string;
+    taskPath: string;
+    subAgentId: string;
+    childCount: number;
+    threadId?: string | undefined;
+    resumeContext?: JSONValue | undefined;
+}>;
+export declare const delegateSubAgentSuspendSchema: z.ZodUnknown;
+export declare const delegateSubAgentResumeSchema: z.ZodUnknown;
+export type DelegateSubAgentContinuation = z.infer<typeof delegateSubAgentContinuationSchema>;
+export declare function parseDelegateSubAgentContinuation(value: unknown): DelegateSubAgentContinuation | undefined;
+export type DelegateSubAgentInput = z.infer<typeof delegateSubAgentInputSchema>;
+export type DelegateSubAgentPolicy = SubAgentTaskPathPolicy;
+export interface DelegateSubAgentRequest extends DelegateSubAgentInput {
+    taskPath: SubAgentTaskPath;
+    parentRunId?: string;
+    parentThreadId?: string;
+    parentResourceId?: string;
+    parentHostMetadata?: JSONObject;
+    parentToolCallId?: string;
+    parentAbortSignal?: AbortSignal;
+    parentExecutionCounter?: AgentExecutionCounter;
+    parentTelemetry?: BuiltTelemetry;
+    childCount: number;
+    policy?: DelegateSubAgentPolicy;
+}
+export interface DelegateSubAgentToolOutput {
+    status: 'completed' | 'failed' | 'suspended' | 'cancelled';
+    taskPath?: SubAgentTaskPath;
+    runId?: string;
+    threadId?: string;
+    model?: string;
+    answer: string;
+    structuredOutput?: unknown;
+    usage?: Pick<TokenUsage, 'promptTokens' | 'completionTokens' | 'totalTokens' | 'cost'>;
+    finishReason?: FinishReason;
+    error?: string;
+    resumeContext?: JSONValue;
+    pendingSuspend?: GenerateResult['pendingSuspend'];
+}
+export interface DelegateSubAgentRunnerHelpers {
+    runInlineSubAgent: (request: DelegateSubAgentRequest) => Promise<DelegateSubAgentToolOutput>;
+    emitChunk: (chunk: StreamChunk) => void;
+}
+export type InlineSubAgentProviderToolsResolver = (modelConfig: ModelConfig) => BuiltProviderTool[] | Promise<BuiltProviderTool[]>;
+export type DelegateSubAgentRunner = (request: DelegateSubAgentRequest, helpers: DelegateSubAgentRunnerHelpers) => Promise<DelegateSubAgentToolOutput>;
+export interface DelegateSubAgentCheckpointTarget {
+    childRunId: string;
+    childToolCallId: string;
+    childThreadId?: string;
+    resumeContext?: JSONValue;
+}
+export interface DelegateSubAgentResumeRequest extends DelegateSubAgentRequest, DelegateSubAgentCheckpointTarget {
+    resumeData: unknown;
+}
+export type DelegateSubAgentResumeRunner = (request: DelegateSubAgentResumeRequest, helpers: DelegateSubAgentRunnerHelpers) => Promise<DelegateSubAgentToolOutput>;
+export interface DelegateSubAgentCancelRequest extends DelegateSubAgentRequest, DelegateSubAgentCheckpointTarget {
+    reason: string;
+}
+export type DelegateSubAgentCancelRunner = (request: DelegateSubAgentCancelRequest, helpers: DelegateSubAgentRunnerHelpers) => Promise<void>;
+export interface CreateDelegateSubAgentToolOptions {
+    name?: string;
+    description?: string | null;
+    systemInstruction?: string | null;
+    availableSubAgents?: Array<{
+        id: string;
+        name: string;
+        useWhen?: string;
+    }>;
+    policy?: DelegateSubAgentPolicy;
+    inlineSubAgentBlockedTools?: string[];
+    inlineSubAgentModelsByDifficulty?: Partial<Record<SubAgentTaskDifficulty, ModelConfig>>;
+    resolveInlineSubAgentProviderTools?: InlineSubAgentProviderToolsResolver;
+    runSubAgent?: DelegateSubAgentRunner;
+    resumeSubAgent?: DelegateSubAgentResumeRunner;
+    shouldRetrySubAgentResumeError?: (error: unknown) => boolean;
+    cancelSubAgent?: DelegateSubAgentCancelRunner;
+    toModelOutput?: (output: z.infer<typeof delegateSubAgentOutputSchema>) => unknown;
+}
+export type DelegateSubAgentToolMetadata = CreateDelegateSubAgentToolOptions;
+export {};

package/dist/types/runtime/delegation.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delegateSubAgentResumeSchema = exports.delegateSubAgentSuspendSchema = exports.delegateSubAgentOutputSchema = exports.delegateSubAgentInputSchema = exports.SUB_AGENT_TASK_DIFFICULTIES = exports.INLINE_DELEGATE_SUB_AGENT_TOOL_METADATA_KEY = exports.DELEGATED_CHILD_SUSPEND_UNSUPPORTED_MESSAGE = exports.INLINE_SUB_AGENT_ID = exports.DELEGATE_SUB_AGENT_TOOL_NAME = void 0;
+exports.parseDelegateSubAgentContinuation = parseDelegateSubAgentContinuation;
+const zod_1 = require("zod");
+exports.DELEGATE_SUB_AGENT_TOOL_NAME = 'delegate_subagent';
+exports.INLINE_SUB_AGENT_ID = 'inline';
+exports.DELEGATED_CHILD_SUSPEND_UNSUPPORTED_MESSAGE = 'agents.chat.delegate.childSuspendUnsupported';
+exports.INLINE_DELEGATE_SUB_AGENT_TOOL_METADATA_KEY = 'inlineDelegateSubAgent';
+exports.SUB_AGENT_TASK_DIFFICULTIES = ['low', 'medium', 'high'];
+const SubAgentTaskDifficultySchema = zod_1.z.enum(exports.SUB_AGENT_TASK_DIFFICULTIES);
+const jsonValueSchema = zod_1.z.lazy(() => zod_1.z.union([
+    zod_1.z.string(),
+    zod_1.z.number(),
+    zod_1.z.boolean(),
+    zod_1.z.null(),
+    zod_1.z.array(jsonValueSchema),
+    zod_1.z.record(zod_1.z.string(), jsonValueSchema),
+]));
+exports.delegateSubAgentInputSchema = zod_1.z.object({
+    subAgentId: zod_1.z
+        .string()
+        .min(1)
+        .describe('Required. Use "inline" for a one-off inline sub-agent. Use an exact configured sub-agent ID only when one is listed and fits the task.'),
+    taskName: zod_1.z
+        .string()
+        .min(1)
+        .describe('Short human-readable name for this delegated task, e.g. "research_api".'),
+    goal: zod_1.z.string().min(1).describe('The concrete goal the sub-agent should accomplish.'),
+    context: zod_1.z
+        .string()
+        .optional()
+        .describe('All details the child needs, since it sees nothing else: constraints, paths, data, prior decisions, acceptance criteria, and what you have already tried or ruled out.'),
+    expectedOutput: zod_1.z.string().optional().describe('The expected shape or contents of the answer.'),
+    difficulty: SubAgentTaskDifficultySchema.optional().describe('Optional difficulty estimate for this delegated task. Use low for simple bounded work, medium for moderate analysis or implementation, and high for complex research, architecture, or multi-step reasoning.'),
+});
+exports.delegateSubAgentOutputSchema = zod_1.z.object({
+    status: zod_1.z.enum(['completed', 'failed', 'suspended', 'cancelled']),
+    taskPath: zod_1.z.string().optional(),
+    runId: zod_1.z.string().optional(),
+    threadId: zod_1.z.string().optional(),
+    model: zod_1.z.string().optional(),
+    answer: zod_1.z.string(),
+    structuredOutput: zod_1.z.unknown().optional(),
+    usage: zod_1.z
+        .object({
+        promptTokens: zod_1.z.number().optional(),
+        completionTokens: zod_1.z.number().optional(),
+        totalTokens: zod_1.z.number().optional(),
+        cost: zod_1.z.number().optional(),
+    })
+        .optional(),
+    finishReason: zod_1.z.string().optional(),
+    error: zod_1.z.string().optional(),
+    resumeContext: jsonValueSchema.optional(),
+    pendingSuspend: zod_1.z
+        .array(zod_1.z.object({
+        runId: zod_1.z.string(),
+        toolCallId: zod_1.z.string(),
+        toolName: zod_1.z.string(),
+        input: zod_1.z.unknown(),
+        suspendPayload: zod_1.z.unknown(),
+        resumeSchema: zod_1.z.unknown().optional(),
+    }))
+        .optional(),
+});
+const delegateSubAgentContinuationSchema = zod_1.z.object({
+    runId: zod_1.z.string(),
+    toolCallId: zod_1.z.string(),
+    taskPath: zod_1.z.string(),
+    subAgentId: zod_1.z.string(),
+    childCount: zod_1.z.number().int().nonnegative(),
+    threadId: zod_1.z.string().optional(),
+    resumeContext: jsonValueSchema.optional(),
+});
+exports.delegateSubAgentSuspendSchema = zod_1.z.unknown();
+exports.delegateSubAgentResumeSchema = zod_1.z.unknown();
+function parseDelegateSubAgentContinuation(value) {
+    const parsed = delegateSubAgentContinuationSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+//# sourceMappingURL=delegation.js.map

package/dist/types/runtime/delegation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation.js","sourceRoot":"","sources":["../../../src/types/runtime/delegation.ts"],"names":[],"mappings":"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"}

package/dist/types/runtime/tool-execution.d.ts

@@ -0,0 +1,103 @@
+import type { JSONSchema7 } from 'json-schema';
+import type { AgentMessageList } from '../../runtime/model/message-list';
+import type { TokenCounter } from '../../runtime/model/model-token-counter';
+import type { AgentEventBus } from '../../runtime/state/event-bus';
+import type { RuntimeTelemetry } from '../../runtime/telemetry/runtime-telemetry';
+import type { RuntimeSkillLoader } from '../../skills/types';
+import type { WorkspaceFilesystem } from '../../workspace/types';
+import type { AgentExecutionCounter, BuiltTelemetry, BuiltTool, PendingToolCall, ToolSuspendOptions } from '../index';
+import type { AgentPersistenceOptions, ToolResultEntry } from '../sdk/agent';
+import type { AgentMessage } from '../sdk/message';
+import type { JSONValue } from '../utils/json';
+export interface PendingResume {
+    pendingToolCalls: Record<string, PendingToolCall>;
+    resumeToolCallId: string;
+    resumeData: unknown;
+}
+export type ToolCallOutcome = {
+    outcome: 'success';
+    toolEntry: ToolResultEntry;
+    modelOutput: unknown;
+    customMessage?: AgentMessage;
+    mcpServerName?: string;
+} | {
+    outcome: 'suspended';
+    payload: unknown;
+    resumeSchema: JSONSchema7;
+    continuation?: JSONValue;
+} | {
+    outcome: 'cancelled';
+    toolEntry: ToolResultEntry;
+    modelOutput: string;
+    userMessage: string;
+    canceled: true;
+} | {
+    outcome: 'retryable-error';
+} | {
+    outcome: 'error';
+    error: unknown;
+} | {
+    outcome: 'noop';
+};
+export type ToolCallIdentity = Pick<PendingToolCall, 'toolCallId' | 'toolName' | 'input'>;
+export interface ToolCallSuccess extends ToolCallIdentity {
+    toolEntry: ToolResultEntry;
+    modelOutput: unknown;
+    customMessage?: AgentMessage;
+    mcpServerName?: string;
+}
+export interface ToolCallSuspension extends ToolCallIdentity {
+    payload: unknown;
+    resumeSchema: JSONSchema7;
+}
+export interface ToolCallError extends ToolCallIdentity {
+    error: unknown;
+}
+export interface ToolCallBatchResult {
+    results: ToolCallSuccess[];
+    suspensions: ToolCallSuspension[];
+    errors: ToolCallError[];
+    pending: Record<string, PendingToolCall>;
+}
+export interface ToolCallInput {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    providerExecuted?: boolean;
+}
+export interface ToolBatchContext {
+    toolMap: Map<string, BuiltTool>;
+    list: AgentMessageList;
+    runId: string;
+    persistence?: AgentPersistenceOptions;
+    telemetry?: BuiltTelemetry;
+    executionCounter?: AgentExecutionCounter;
+    abortSignal: AbortSignal;
+    isAborted: () => boolean;
+}
+export interface ResumeToolBatchContext extends ToolBatchContext {
+    pendingResume: PendingResume;
+}
+export interface ProcessToolCallParams extends ToolCallIdentity {
+    toolMap: Map<string, BuiltTool>;
+    list: AgentMessageList;
+    runId: string;
+    persistence?: AgentPersistenceOptions;
+    resumeData?: unknown;
+    resolvedTelemetry?: BuiltTelemetry;
+    executionCounter?: AgentExecutionCounter;
+    abortSignal?: AbortSignal;
+    countToolCall?: boolean;
+    suspendPayload?: unknown;
+    continuation?: JSONValue;
+    resumeSchema?: ToolSuspendOptions['resumeSchema'];
+}
+export interface ToolCallExecutorDeps {
+    loadSkill?: RuntimeSkillLoader;
+    telemetry: RuntimeTelemetry;
+    eventBus: AgentEventBus;
+    concurrency: number;
+    onCancelled: () => void;
+    tokenCounter: TokenCounter;
+    workspaceFilesystem?: WorkspaceFilesystem;
+}

package/dist/types/runtime/tool-execution.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=tool-execution.js.map

package/dist/types/runtime/tool-execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-execution.js","sourceRoot":"","sources":["../../../src/types/runtime/tool-execution.ts"],"names":[],"mappings":""}

package/dist/types/sdk/agent-builder.d.ts

@@ -4,7 +4,7 @@ import type { BuiltGuardrail } from './guardrail';
 import type { CheckpointStore } from './memory';
 import type { ReasoningLevel } from './reasoning';
 import type { BuiltProviderTool, BuiltTool } from './tool';
-import type { VolatileInstructionsProvider } from '../../runtime/loop/agent-runtime';
+import type { VolatileInstructionsProvider } from '../runtime/agent-runtime';
 import type { ScopedMemoryTaskEvent } from '../../runtime/memory/scoped-memory-task-runner';
 import type { RuntimeSkill, RuntimeSkillSource } from '../../skills';
 export interface AgentBuilder {

package/dist/types/sdk/memory.d.ts

@@ -31,6 +31,7 @@ export interface BuiltMemory {
         threadId: string;
         resourceId: string;
         messages: AgentDbMessage[];
+        hostMetadata?: JSONObject;
     }): Promise<void>;
     deleteMessages(messageIds: string[]): Promise<void>;
     episodic?: EpisodicMemoryMethods;
@@ -240,6 +241,6 @@ export interface CheckpointStore {
     save(key: string, state: SerializableAgentState): Promise<void>;
     load(key: string): Promise<SerializableAgentState | undefined>;
     claimForResume?(key: string, state: SerializableAgentState): Promise<boolean>;
-    delete(key: string): Promise<void>;
+    delete(key: string, state?: SerializableAgentState): Promise<void>;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n8n/agents",
-  "version": "0.26.3",
+  "version": "0.27.1",
   "description": "AI agent SDK for n8n's code-first execution engine",
   "engines": {
     "node": ">=24.0.0"
@@ -94,9 +94,9 @@
     "@ai-sdk/xai": "^4.0.18",
     "@daytona/sdk": "0.205.1",
     "@modelcontextprotocol/sdk": "1.26.0",
-    "@n8n/ai-utilities": "0.34.3",
+    "@n8n/ai-utilities": "0.35.1",
     "@n8n/sandbox-client": "0.1.1",
-    "@n8n/utils": "1.48.1",
+    "@n8n/utils": "1.49.0",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "@opentelemetry/exporter-trace-otlp-http": ">=0.50.0",
     "@opentelemetry/sdk-trace-base": "2.7.1",
@@ -143,7 +143,7 @@
   },
   "devDependencies": {
     "@n8n/typescript-config": "1.12.0",
-    "@n8n/vitest-config": "1.22.0",
+    "@n8n/vitest-config": "1.23.0",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/context-async-hooks": "^2.7.1",
     "@pinecone-database/pinecone": "^5.0.2",
@@ -151,7 +151,7 @@
     "@supabase/supabase-js": "2.112.3",
     "@types/json-schema": "^7.0.15",
     "@types/pg": "^8.15.6",
-    "@vitest/coverage-v8": "4.1.9",
+    "@vitest/coverage-v8": "5.0.1",
     "dotenv": "17.2.3",
     "cross-env": "^7.0.3",
     "nock": "14.0.14",
@@ -159,7 +159,7 @@
     "tsx": "^4.19.3",
     "typescript": "7.0.2",
     "vite": "^8.0.2",
-    "vitest": "^4.1.9",
+    "vitest": "5.0.1",
     "vitest-mock-extended": "^3.1.0",
     "zod": "3.25.76"
   },