@n8n/agents 0.1.0

package/dist/sdk/telemetry.js

@@ -0,0 +1,186 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Telemetry = void 0;
+function redactValue(value, redact) {
+    if (Array.isArray(value)) {
+        return value.map((item) => redactValue(item, redact));
+    }
+    if (typeof value === 'object' &&
+        value !== null &&
+        Object.getPrototypeOf(value) === Object.prototype) {
+        const redacted = redact(value);
+        for (const key of Object.keys(redacted)) {
+            redacted[key] = redactValue(redacted[key], redact);
+        }
+        return redacted;
+    }
+    return value;
+}
+function redactEvent(event, redact) {
+    const cloned = { ...event };
+    const redacted = redact(cloned);
+    for (const key of Object.keys(redacted)) {
+        const value = redacted[key];
+        redacted[key] = redactValue(value, redact);
+    }
+    return redacted;
+}
+function wrapIntegrationWithRedaction(integration, redact) {
+    const wrapped = {};
+    if (integration.onStart) {
+        const orig = integration.onStart;
+        wrapped.onStart = (event) => orig(redactEvent(event, redact));
+    }
+    if (integration.onStepStart) {
+        const orig = integration.onStepStart;
+        wrapped.onStepStart = (event) => orig(redactEvent(event, redact));
+    }
+    if (integration.onToolCallStart) {
+        const orig = integration.onToolCallStart;
+        wrapped.onToolCallStart = (event) => orig(redactEvent(event, redact));
+    }
+    if (integration.onToolCallFinish) {
+        const orig = integration.onToolCallFinish;
+        wrapped.onToolCallFinish = (event) => orig(redactEvent(event, redact));
+    }
+    if (integration.onStepFinish) {
+        const orig = integration.onStepFinish;
+        wrapped.onStepFinish = (event) => orig(redactEvent(event, redact));
+    }
+    if (integration.onFinish) {
+        const orig = integration.onFinish;
+        wrapped.onFinish = (event) => orig(redactEvent(event, redact));
+    }
+    return wrapped;
+}
+async function createOtlpTracer(endpoint) {
+    const { NodeTracerProvider } = (await Promise.resolve().then(() => __importStar(require('@opentelemetry/sdk-trace-node'))));
+    const { OTLPTraceExporter } = (await Promise.resolve().then(() => __importStar(require('@opentelemetry/exporter-trace-otlp-http'))));
+    const { SimpleSpanProcessor } = (await Promise.resolve().then(() => __importStar(require('@opentelemetry/sdk-trace-base'))));
+    const exporter = new OTLPTraceExporter({ url: endpoint });
+    const provider = new NodeTracerProvider({
+        spanProcessors: [new SimpleSpanProcessor(exporter)],
+    });
+    const tracer = provider.getTracer('@n8n/agents');
+    return { tracer, provider };
+}
+class Telemetry {
+    constructor() {
+        this.enabledValue = true;
+        this.recordInputsValue = true;
+        this.recordOutputsValue = true;
+        this.integrationsList = [];
+    }
+    credential(name) {
+        this.credentialNameValue = name;
+        return this;
+    }
+    get declaredCredential() {
+        return this.credentialNameValue;
+    }
+    set resolvedApiKey(key) {
+        this.resolvedKey = key;
+    }
+    enabled(value) {
+        this.enabledValue = value;
+        return this;
+    }
+    functionId(value) {
+        this.functionIdValue = value;
+        return this;
+    }
+    metadata(value) {
+        this.metadataValue = value;
+        return this;
+    }
+    recordInputs(value) {
+        this.recordInputsValue = value;
+        return this;
+    }
+    recordOutputs(value) {
+        this.recordOutputsValue = value;
+        return this;
+    }
+    redact(fn) {
+        this.redactFn = fn;
+        return this;
+    }
+    integration(value) {
+        this.integrationsList.push(value);
+        return this;
+    }
+    tracer(value) {
+        this.tracerValue = value;
+        return this;
+    }
+    otlpEndpoint(value) {
+        this.otlpEndpointValue = value;
+        return this;
+    }
+    async build() {
+        if (this.tracerValue !== undefined && this.otlpEndpointValue !== undefined) {
+            throw new Error('Cannot set both .tracer() and .otlpEndpoint() — use one or the other.');
+        }
+        let tracer = this.tracerValue;
+        let provider;
+        if (this.otlpEndpointValue !== undefined) {
+            const otlp = await createOtlpTracer(this.otlpEndpointValue);
+            tracer = otlp.tracer;
+            provider = otlp.provider;
+        }
+        const integrations = this.redactFn
+            ? this.integrationsList.map((i) => wrapIntegrationWithRedaction(i, this.redactFn))
+            : [...this.integrationsList];
+        return {
+            enabled: this.enabledValue,
+            functionId: this.functionIdValue,
+            metadata: this.metadataValue,
+            recordInputs: this.recordInputsValue,
+            recordOutputs: this.recordOutputsValue,
+            integrations,
+            tracer,
+            provider,
+            credentialName: this.credentialNameValue,
+        };
+    }
+    static async shutdown(telemetry) {
+        if (telemetry.provider) {
+            await telemetry.provider.shutdown();
+        }
+    }
+}
+exports.Telemetry = Telemetry;
+//# sourceMappingURL=telemetry.js.map

package/dist/sdk/telemetry.js.map

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

package/dist/sdk/tool.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { BuiltTool, InterruptibleToolContext, ToolContext } from '../types';
+import type { AgentMessage } from '../types/sdk/message';
+import type { JSONObject } from '../types/utils/json';
+export interface ApprovalConfig {
+    requireApproval?: boolean;
+    needsApprovalFn?: (args: unknown) => Promise<boolean> | boolean;
+}
+export declare function wrapToolForApproval(tool: BuiltTool, config: ApprovalConfig): BuiltTool;
+type HandlerContext<S, R> = S extends z.ZodTypeAny ? R extends z.ZodTypeAny ? InterruptibleToolContext<z.infer<S>, z.infer<R>> : ToolContext : ToolContext;
+export declare class Tool<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny, TSuspend extends z.ZodTypeAny | undefined = undefined, TResume extends z.ZodTypeAny | undefined = undefined> {
+    private name;
+    private desc?;
+    private inputSchema?;
+    private outputSchema?;
+    private suspendSchemaValue?;
+    private resumeSchemaValue?;
+    private handlerFn?;
+    private toMessageFn?;
+    private toModelOutputFn?;
+    private providerOptionsValue?;
+    private requireApprovalValue?;
+    private needsApprovalFnValue?;
+    constructor(name: string);
+    description(desc: string): this;
+    input<S extends z.ZodTypeAny>(schema: S): Tool<S, TOutput, TSuspend, TResume>;
+    output<S extends z.ZodTypeAny>(schema: S): Tool<TInput, S, TSuspend, TResume>;
+    suspend<S extends z.ZodTypeAny>(schema: S): Tool<TInput, TOutput, S, TResume>;
+    resume<R extends z.ZodTypeAny>(schema: R): Tool<TInput, TOutput, TSuspend, R>;
+    handler(fn: (input: z.infer<TInput>, ctx: HandlerContext<TSuspend, TResume>) => Promise<z.infer<TOutput>>): this;
+    toMessage(toMessage: (output: z.infer<TOutput>) => AgentMessage): this;
+    toModelOutput(fn: (output: z.infer<TOutput>) => unknown): this;
+    requireApproval(): this;
+    needsApprovalFn(fn: (args: z.infer<TInput>) => Promise<boolean> | boolean): this;
+    providerOptions(options: Record<string, JSONObject>): this;
+    build(): BuiltTool;
+}
+export {};

package/dist/sdk/tool.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tool = void 0;
+exports.wrapToolForApproval = wrapToolForApproval;
+const zod_1 = require("zod");
+const APPROVAL_SUSPEND_SCHEMA = zod_1.z.object({
+    type: zod_1.z.literal('approval'),
+    toolName: zod_1.z.string(),
+    args: zod_1.z.unknown(),
+});
+const APPROVAL_RESUME_SCHEMA = zod_1.z.object({
+    approved: zod_1.z.boolean(),
+});
+function wrapToolForApproval(tool, config) {
+    const originalHandler = tool.handler;
+    return {
+        ...tool,
+        suspendSchema: APPROVAL_SUSPEND_SCHEMA,
+        resumeSchema: APPROVAL_RESUME_SCHEMA,
+        handler: async (input, ctx) => {
+            const interruptCtx = ctx;
+            if (interruptCtx.resumeData === undefined) {
+                let needs = config.requireApproval ?? false;
+                if (!needs && config.needsApprovalFn) {
+                    needs = await config.needsApprovalFn(input);
+                }
+                if (needs) {
+                    return await interruptCtx.suspend({ type: 'approval', toolName: tool.name, args: input });
+                }
+                return await originalHandler(input, {
+                    parentTelemetry: interruptCtx.parentTelemetry,
+                });
+            }
+            const { approved } = interruptCtx.resumeData;
+            if (!approved) {
+                return { declined: true, message: `Tool "${tool.name}" was not approved` };
+            }
+            return await originalHandler(input, {
+                parentTelemetry: interruptCtx.parentTelemetry,
+            });
+        },
+    };
+}
+class Tool {
+    constructor(name) {
+        this.name = name;
+    }
+    description(desc) {
+        this.desc = desc;
+        return this;
+    }
+    input(schema) {
+        const self = this;
+        self.inputSchema = schema;
+        return self;
+    }
+    output(schema) {
+        const self = this;
+        self.outputSchema = schema;
+        return self;
+    }
+    suspend(schema) {
+        const self = this;
+        self.suspendSchemaValue = schema;
+        return self;
+    }
+    resume(schema) {
+        const self = this;
+        self.resumeSchemaValue = schema;
+        return self;
+    }
+    handler(fn) {
+        this.handlerFn = fn;
+        return this;
+    }
+    toMessage(toMessage) {
+        this.toMessageFn = toMessage;
+        return this;
+    }
+    toModelOutput(fn) {
+        this.toModelOutputFn = fn;
+        return this;
+    }
+    requireApproval() {
+        this.requireApprovalValue = true;
+        return this;
+    }
+    needsApprovalFn(fn) {
+        this.needsApprovalFnValue = fn;
+        return this;
+    }
+    providerOptions(options) {
+        this.providerOptionsValue = { ...this.providerOptionsValue, ...options };
+        return this;
+    }
+    build() {
+        if (!this.name) {
+            throw new Error('Tool name is required');
+        }
+        if (!this.desc) {
+            throw new Error(`Tool "${this.name}" requires a description`);
+        }
+        if (!this.inputSchema) {
+            throw new Error(`Tool "${this.name}" requires an input schema`);
+        }
+        if (!this.handlerFn) {
+            throw new Error(`Tool "${this.name}" requires a handler`);
+        }
+        const hasSuspend = this.suspendSchemaValue !== undefined;
+        const hasResume = this.resumeSchemaValue !== undefined;
+        if (hasSuspend && !hasResume) {
+            throw new Error(`Tool "${this.name}" has .suspend() but missing .resume()`);
+        }
+        if (hasResume && !hasSuspend) {
+            throw new Error(`Tool "${this.name}" has .resume() but missing .suspend()`);
+        }
+        const hasApproval = (this.requireApprovalValue ?? false) || this.needsApprovalFnValue !== undefined;
+        if (hasApproval && (hasSuspend || hasResume)) {
+            throw new Error(`Tool "${this.name}" cannot use both approval (.requireApproval/.needsApprovalFn) and suspend/resume (.suspend/.resume)`);
+        }
+        const built = {
+            name: this.name,
+            description: this.desc,
+            suspendSchema: this.suspendSchemaValue,
+            resumeSchema: this.resumeSchemaValue,
+            toMessage: this.toMessageFn,
+            toModelOutput: this.toModelOutputFn,
+            handler: this.handlerFn,
+            inputSchema: this.inputSchema,
+            outputSchema: this.outputSchema,
+            providerOptions: this.providerOptionsValue,
+        };
+        if (this.requireApprovalValue ?? this.needsApprovalFnValue) {
+            return wrapToolForApproval(built, {
+                requireApproval: this.requireApprovalValue,
+                needsApprovalFn: this.needsApprovalFnValue,
+            });
+        }
+        return built;
+    }
+}
+exports.Tool = Tool;
+//# sourceMappingURL=tool.js.map

package/dist/sdk/tool.js.map

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

package/dist/sdk/verify.d.ts

@@ -0,0 +1,5 @@
+export interface VerifyResult {
+    ok: boolean;
+    errors: string[];
+}
+export declare function verify(source: string): VerifyResult;

package/dist/sdk/verify.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verify = verify;
+function verify(source) {
+    const errors = [];
+    if (!source?.trim()) {
+        return { ok: false, errors: ['No source code provided'] };
+    }
+    if (/\.build\s*\(/.test(source)) {
+        errors.push('Do not call .build() — the engine handles this automatically. Remove all .build() calls.');
+    }
+    if (!/export\s+default\b/.test(source)) {
+        errors.push('No default export found. Export an agent as the default: export default agent;');
+    }
+    if (/\bScorer\b/.test(source)) {
+        errors.push("Scorer is deprecated. Use the Eval system instead: new Eval('name').check(...) or evals.correctness()");
+    }
+    if (/process\.env\b/.test(source)) {
+        errors.push('process.env is not available. Use .credential() for API keys, or const variables for configuration.');
+    }
+    {
+        let stripped = source;
+        stripped = stripped.replace(/return\s+(?:await\s+)?(?:ctx\.)?suspend\s*\(/g, '');
+        stripped = stripped.replace(/return\s+[^\n;]+\?\s*(?:await\s+)?(?:ctx\.)?suspend\s*\(/g, '');
+        stripped = stripped.replace(/=>\s*(?:await\s+)?(?:ctx\.)?suspend\s*\(/g, '');
+        stripped = stripped.replace(/\.suspend\s*\(\s*z\./g, '');
+        if (/(?:ctx\.)?suspend\s*\(/.test(stripped)) {
+            errors.push('ctx.suspend() must be returned: use `return await ctx.suspend(...)` or `return ctx.suspend(...)`. ' +
+                'Without return, the handler continues executing after suspension.');
+        }
+    }
+    if (!/\.credential\s*\(/.test(source)) {
+        errors.push("No .credential() found. Every agent must declare a credential (e.g. .credential('anthropic')).");
+    }
+    return { ok: errors.length === 0, errors };
+}
+//# sourceMappingURL=verify.js.map

package/dist/sdk/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/sdk/verify.ts"],"names":[],"mappings":";;AAuBA,wBAgEC;AAhED,SAAgB,MAAM,CAAC,MAAc;IACpC,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;QACrB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,yBAAyB,CAAC,EAAE,CAAC;IAC3D,CAAC;IAED,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CACV,0FAA0F,CAC1F,CAAC;IACH,CAAC;IAED,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACxC,MAAM,CAAC,IAAI,CAAC,gFAAgF,CAAC,CAAC;IAC/F,CAAC;IAED,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,CACV,uGAAuG,CACvG,CAAC;IACH,CAAC;IAED,IAAI,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,IAAI,CACV,qGAAqG,CACrG,CAAC;IACH,CAAC;IAYD,CAAC;QACA,IAAI,QAAQ,GAAG,MAAM,CAAC;QAEtB,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,+CAA+C,EAAE,EAAE,CAAC,CAAC;QAEjF,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,2DAA2D,EAAE,EAAE,CAAC,CAAC;QAE7F,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,2CAA2C,EAAE,EAAE,CAAC,CAAC;QAE7E,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;QACzD,IAAI,wBAAwB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7C,MAAM,CAAC,IAAI,CACV,oGAAoG;gBACnG,mEAAmE,CACpE,CAAC;QACH,CAAC;IACF,CAAC;IAED,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,IAAI,CACV,gGAAgG,CAChG,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;AAC5C,CAAC"}

package/dist/storage/postgres-memory.d.ts

@@ -0,0 +1,79 @@
+import type { ConnectionOptions } from 'tls';
+import type { BuiltMemory, Thread } from '../types/sdk/memory';
+import type { AgentDbMessage, AgentMessage } from '../types/sdk/message';
+export interface PostgresConnectionConfig {
+    host?: string;
+    port?: number;
+    database?: string;
+    user?: string;
+    password?: string | (() => string | Promise<string>);
+}
+export interface PostgresMemoryConfig {
+    connection: string | PostgresConnectionConfig;
+    pool?: {
+        max?: number;
+        min?: number;
+        idleTimeoutMillis?: number;
+        connectionTimeoutMillis?: number;
+        allowExitOnIdle?: boolean;
+    };
+    ssl?: boolean | ConnectionOptions;
+    namespace?: string;
+}
+export declare class PostgresMemory implements BuiltMemory {
+    private initPromise;
+    private embeddingsInitPromise;
+    private readonly config;
+    private readonly ns;
+    constructor(config: PostgresMemoryConfig);
+    private ensureInitialized;
+    private _initialize;
+    getThread(threadId: string): Promise<Thread | null>;
+    saveThread(thread: Omit<Thread, 'createdAt' | 'updatedAt'>): Promise<Thread>;
+    deleteThread(threadId: string): Promise<void>;
+    getMessages(threadId: string, opts?: {
+        limit?: number;
+        before?: Date;
+    }): Promise<AgentDbMessage[]>;
+    saveMessages(args: {
+        threadId: string;
+        resourceId?: string;
+        messages: AgentMessage[];
+    }): Promise<void>;
+    deleteMessages(messageIds: string[]): Promise<void>;
+    getWorkingMemory(params: {
+        threadId: string;
+        resourceId: string;
+        scope: 'resource' | 'thread';
+    }): Promise<string | null>;
+    saveWorkingMemory(params: {
+        threadId: string;
+        resourceId: string;
+        scope: 'resource' | 'thread';
+    }, content: string): Promise<void>;
+    private embeddingDimension;
+    private ensureEmbeddingsTable;
+    private _initializeEmbeddingsTable;
+    saveEmbeddings(opts: {
+        scope?: 'thread' | 'resource';
+        threadId?: string;
+        resourceId?: string;
+        entries: Array<{
+            id: string;
+            vector: number[];
+            text: string;
+            model: string;
+        }>;
+    }): Promise<void>;
+    queryEmbeddings(opts: {
+        scope?: 'thread' | 'resource';
+        threadId?: string;
+        resourceId?: string;
+        vector: number[];
+        topK: number;
+    }): Promise<Array<{
+        id: string;
+        score: number;
+    }>>;
+    close(): Promise<void>;
+}