@n8n/agents 0.10.1 → 0.12.0

package/dist/runtime/write-todos-tool.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WRITE_TODOS_TOOL_NAME = void 0;
+exports.createWriteTodosTool = createWriteTodosTool;
+const zod_1 = require("zod");
+const delegate_sub_agent_tool_1 = require("./delegate-sub-agent-tool");
+const sdk_owned_tool_1 = require("./sdk-owned-tool");
+const tool_1 = require("../sdk/tool");
+exports.WRITE_TODOS_TOOL_NAME = 'write_todos';
+const todoStatusSchema = zod_1.z.enum(['pending', 'in_progress', 'completed', 'blocked', 'cancelled']);
+const todoDifficultySchema = zod_1.z.enum(delegate_sub_agent_tool_1.SUB_AGENT_TASK_DIFFICULTIES);
+const todoDelegateHintSchema = zod_1.z
+    .object({
+    subAgentId: zod_1.z
+        .string()
+        .optional()
+        .describe('Optional sub-agent id when this task is a delegate_subagent candidate. Use "inline" for one-off inline sub-agents.'),
+    expectedOutput: zod_1.z
+        .string()
+        .optional()
+        .describe('Optional expected output shape when delegating this task.'),
+})
+    .optional();
+const todoItemSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1).describe('Stable identifier for this task within the current plan.'),
+    content: zod_1.z.string().min(1).describe('Concrete, self-contained task description.'),
+    status: todoStatusSchema,
+    difficulty: todoDifficultySchema.describe('Task difficulty: "low", "medium", or "high". Use the same value when delegating this task with delegate_subagent.'),
+    delegateHint: todoDelegateHintSchema,
+});
+const writeTodosInputSchema = zod_1.z
+    .object({
+    todos: zod_1.z
+        .array(todoItemSchema)
+        .describe('Full task list for the current run. Replaces any previous list.'),
+})
+    .superRefine((value, ctx) => {
+    const seen = new Set();
+    for (const [index, todo] of value.todos.entries()) {
+        if (seen.has(todo.id)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Duplicate todo id "${todo.id}". Each task must have a unique id.`,
+                path: ['todos', index, 'id'],
+            });
+        }
+        seen.add(todo.id);
+    }
+});
+const writeTodosOutputSchema = zod_1.z.object({
+    status: zod_1.z.literal('ok'),
+    todoCount: zod_1.z.number(),
+    todos: zod_1.z.array(todoItemSchema),
+});
+const WRITE_TODOS_DESCRIPTION = 'Create or update a structured task list for complex agent work. Use it to decompose a larger request into concrete workstreams, track progress, and identify which tasks should be handled separately with delegate_subagent. Do not use it for trivial work, single-step tasks, or purely conversational answers. This tool only updates the task list; it does not run sub-agents or answer the user.';
+const WRITE_TODOS_SYSTEM_INSTRUCTION = [
+    'write_todos helps you plan and track complex objectives before and during execution. It updates the current task list only; it does not complete tasks, run sub-agents, or answer the user.',
+    'WHEN TO USE write_todos:',
+    '- The user request has 3+ meaningful steps or multiple deliverables.',
+    '- The request decomposes into 2+ independent workstreams.',
+    '- Some workstreams are good candidates for delegate_subagent.',
+    '- You need to track progress, revise the plan, or avoid losing context.',
+    'WHEN NOT TO USE write_todos:',
+    '- The request is trivial, conversational, or informational.',
+    '- The task can be completed directly in one or two simple steps.',
+    "- You would only create a todo list to restate the user's request.",
+    'HOW TO USE write_todos:',
+    '- Write concrete, self-contained tasks, not vague phases.',
+    '- Assign difficulty to every task: low for simple mechanical or localized work, medium for normal implementation or review requiring judgment, high for complex, broad, ambiguous, or high-risk work.',
+    '- Mark the first active task, or independent active tasks, as in_progress immediately.',
+    '- For sub-agent-worthy work, create one todo per bounded workstream, then call delegate_subagent separately for that task; pass the same difficulty on the delegate call.',
+    '- Do not delegate the entire user request as one task.',
+    '- Update task status as soon as work completes; do not batch completions at the end.',
+    '- Revise the list when new information changes the plan.',
+    '- Do not call write_todos multiple times in parallel; send one full list update at a time.',
+    '- After all work is done, send the final answer as normal assistant text after the last write_todos call.',
+].join('\n');
+function createWriteTodosTool() {
+    const tool = new tool_1.Tool(exports.WRITE_TODOS_TOOL_NAME)
+        .description(WRITE_TODOS_DESCRIPTION)
+        .systemInstruction(WRITE_TODOS_SYSTEM_INSTRUCTION)
+        .input(writeTodosInputSchema)
+        .output(writeTodosOutputSchema)
+        .handler(async (input) => {
+        const todos = [...input.todos];
+        return await Promise.resolve({
+            status: 'ok',
+            todoCount: todos.length,
+            todos,
+        });
+    })
+        .build();
+    return (0, sdk_owned_tool_1.withSdkOwnedBuiltInMetadata)(tool);
+}
+//# sourceMappingURL=write-todos-tool.js.map

package/dist/runtime/write-todos-tool.js.map

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

package/dist/sdk/agent.d.ts

@@ -1,12 +1,13 @@
 import type { ProviderOptions } from '@ai-sdk/provider-utils';
-import { z } from 'zod';
+import type { JSONSchema7 } from 'json-schema';
+import type { z } from 'zod';
 import type { Eval } from './eval';
 import type { McpClient } from './mcp-client';
 import { Memory } from './memory';
 import { Telemetry } from './telemetry';
-import { AgentRuntime } from '../runtime/agent-runtime';
+import { type AgentRuntimeConfig } from '../runtime/agent-runtime';
 import type { RuntimeSkill, RuntimeSkillSource } from '../skills';
-import type { AgentEventHandler, AgentMiddleware, BuiltAgent, BuiltEval, BuiltGuardrail, BuiltMemory, BuiltProviderTool, BuiltTool, BuiltTelemetry, CheckpointStore, ExecutionOptions, GenerateResult, MemoryConfig, ModelConfig, Provider, RunOptions, SerializableAgentState, StreamResult, ThinkingConfig, ThinkingConfigFor, ResumeOptions } from '../types';
+import type { AgentEventHandler, AgentMiddleware, BuiltAgent, BuiltEval, BuiltGuardrail, BuiltMemory, BuiltProviderTool, BuiltTool, BuiltTelemetry, CheckpointStore, ExecutionOptions, GenerateResult, MemoryConfig, ModelConfig, Provider, RunOptions, StreamResult, ThinkingConfig, ThinkingConfigFor, ResumeOptions } from '../types';
 import type { AgentEvent } from '../types/runtime/event';
 import type { AgentBuilder } from '../types/sdk/agent-builder';
 import type { AgentMessage } from '../types/sdk/message';
@@ -35,7 +36,6 @@ export interface AgentSnapshot {
     hasEpisodicMemory: boolean;
     thinking: ThinkingConfig | null;
     toolCallConcurrency: number | null;
-    requireToolApproval: boolean;
 }
 export declare class Agent implements BuiltAgent, AgentBuilder {
     readonly name: string;
@@ -55,16 +55,15 @@ export declare class Agent implements BuiltAgent, AgentBuilder {
     private outputSchema?;
     private checkpointStore?;
     private thinkingConfig?;
-    private runtime?;
     private concurrencyValue?;
     private telemetryBuilder?;
     private telemetryConfig?;
     private middlewares;
-    private requireToolApprovalValue;
     private mcpClients;
     private defaultExecutionOptions?;
     private buildPromise;
-    private eventBus;
+    private agentHandlers;
+    private activeRuntimes;
     private workspaceInstance?;
     constructor(name: string);
     hasCheckpointStorage(): boolean;
@@ -90,21 +89,18 @@ export declare class Agent implements BuiltAgent, AgentBuilder {
         ensureBuilt(): BuiltEval;
     }): this;
     checkpoint(storage: 'memory' | CheckpointStore): this;
-    structuredOutput(schema: z.ZodType): this;
+    structuredOutput(schema: z.ZodType | JSONSchema7): this;
     thinking<P extends Provider>(_provider: P, config?: ThinkingConfigFor<P>): this;
     telemetry(t: Telemetry | BuiltTelemetry): this;
     protected get declaredTelemetry(): Telemetry | undefined;
     toolCallConcurrency(n: number): this;
-    requireToolApproval(): this;
     workspace(ws: Workspace): this;
     mcp(client: McpClient): this;
     configuration(options: ExecutionOptions): this;
     get evaluations(): BuiltEval[];
     on(event: AgentEvent, handler: AgentEventHandler): void;
     off(event: AgentEvent, handler: AgentEventHandler): void;
-    asTool(description: string): BuiltTool;
     get snapshot(): AgentSnapshot;
-    getState(): SerializableAgentState;
     abort(): void;
     close(): Promise<void>;
     generate(input: AgentMessage[] | string, options?: RunOptions & ExecutionOptions): Promise<GenerateResult>;
@@ -117,9 +113,20 @@ export declare class Agent implements BuiltAgent, AgentBuilder {
     deny(method: 'stream', options: ResumeOptions & ExecutionOptions): Promise<StreamResult>;
     private mergeWithDefaults;
     private ensureBuilt;
+    private createRuntime;
+    private trackStreamRuntime;
+    private cleanupRuntime;
     private toMessages;
-    protected build(): Promise<AgentRuntime>;
+    protected build(): Promise<AgentRuntimeConfig>;
+    private completeInlineDelegateTools;
+    private createInlineSubAgentRunner;
+    private assertToolRegistrationAllowed;
     private assertToolNameAvailable;
+    private assertReservedSdkBuiltInToolName;
     private removeRuntimeSkillTools;
 }
+export declare function buildInlineSubAgentBlockedToolNames(hostBlockedTools?: string[]): Set<string>;
+export declare function filterInlineSubAgentTools<T extends {
+    readonly name: string;
+}>(tools: T[], hostBlockedTools?: string[]): T[];
 export {};