nexus-ai-pro 2.2.0 → 2.3.0

package/dist/agent/middleware/pii.js

@@ -0,0 +1,173 @@
+import { shortHash } from './shared.js';
+export class PiiBlockedError extends Error {
+    kind;
+    where;
+    code = 'PII_BLOCKED';
+    constructor(kind, where) {
+        super(`The ${where === 'input' ? 'request' : 'response'} contains ${kind}, which is blocked`);
+        this.kind = kind;
+        this.where = where;
+        this.name = 'PiiBlockedError';
+    }
+}
+const DETECTORS = {
+    secret: {
+        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----|\b(?:sk-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{36,}|xox[abprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{35})\b/g,
+    },
+    email: { pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+    'credit-card': { pattern: /\b\d(?:[ -]?\d){12,18}\b/g, valid: luhn },
+    iban: { pattern: /\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{4}){2,7}(?: ?[A-Z0-9]{1,4})?\b/g, valid: ibanChecksum },
+    ssn: { pattern: /\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g },
+    'ip-address': { pattern: /\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b/g },
+    phone: {
+        pattern: /(?<![\w+])\+?(?:\(\d{1,4}\)|\d{1,4})(?:[ .-]?(?:\(\d{1,4}\)|\d{2,4})){2,4}(?!\w)/g,
+        valid: (match) => {
+            const digits = match.replace(/\D/g, '').length;
+            return digits >= 10 && digits <= 15 && (/^\+/.test(match) || /[ .()-]/.test(match));
+        },
+    },
+};
+const ORDER = ['secret', 'email', 'credit-card', 'iban', 'ssn', 'ip-address', 'phone'];
+export function piiMiddleware(options = {}) {
+    const kinds = new Set(options.kinds ?? ORDER);
+    const detectors = [
+        ...ORDER.filter((kind) => kinds.has(kind)).map((kind) => [kind, DETECTORS[kind]]),
+        ...Object.entries(options.patterns ?? {}).map(([kind, pattern]) => [
+            kind,
+            { pattern: pattern.flags.includes('g') ? pattern : new RegExp(pattern.source, `${pattern.flags}g`) },
+        ]),
+    ];
+    const apply = { input: true, output: false, toolResults: true, ...options.apply };
+    const strategyOf = (kind) => typeof options.strategy === 'string' ? options.strategy : (options.strategy?.[kind] ?? 'redact');
+    const clean = (text, where) => {
+        let current = text;
+        for (const [kind, detector] of detectors) {
+            const strategy = strategyOf(kind);
+            let blocked = false;
+            current = current.replace(detector.pattern, (match) => {
+                if (detector.valid && !detector.valid(match))
+                    return match;
+                options.onDetect?.({ kind, where, strategy });
+                if (strategy === 'block')
+                    blocked = true;
+                return replace(match, kind, strategy);
+            });
+            if (blocked)
+                return { blocked: kind };
+        }
+        return { text: current };
+    };
+    const cleanMessage = (message, where) => {
+        if (typeof message.content === 'string') {
+            const result = clean(message.content, where);
+            if ('blocked' in result)
+                throw new PiiBlockedError(result.blocked, where);
+            return result.text === message.content ? message : { ...message, content: result.text };
+        }
+        let changed = false;
+        const content = message.content.map((part) => {
+            if (part.type !== 'text')
+                return part;
+            const result = clean(part.text, where);
+            if ('blocked' in result)
+                throw new PiiBlockedError(result.blocked, where);
+            if (result.text === part.text)
+                return part;
+            changed = true;
+            return { ...part, text: result.text };
+        });
+        return changed ? { ...message, content } : message;
+    };
+    return {
+        name: 'pii',
+        beforeModel({ request }) {
+            if (!apply.input)
+                return;
+            return {
+                ...request,
+                messages: request.messages.map((message) => message.role === 'system' ? message : cleanMessage(message, 'input')),
+            };
+        },
+        afterModel({ response }) {
+            if (!apply.output || !response.content)
+                return;
+            const result = clean(response.content, 'output');
+            if ('blocked' in result)
+                throw new PiiBlockedError(result.blocked, 'output');
+            return result.text === response.content ? undefined : { ...response, content: result.text };
+        },
+        async wrapToolCall(_call, next) {
+            const result = await next();
+            if (!apply.toolResults || !result.ok)
+                return result;
+            let blocked;
+            const walk = (value) => {
+                if (blocked)
+                    return value;
+                if (typeof value === 'string') {
+                    const cleaned = clean(value, 'tool');
+                    if ('blocked' in cleaned) {
+                        blocked = cleaned.blocked;
+                        return value;
+                    }
+                    return cleaned.text;
+                }
+                if (Array.isArray(value))
+                    return value.map(walk);
+                if (isToolOutput(value)) {
+                    const content = value.content.map((part) => part.type === 'text' ? { ...part, text: walk(part.text) } : part);
+                    return { ...value, content };
+                }
+                if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+                    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, walk(entry)]));
+                }
+                return value;
+            };
+            const cleaned = walk(result.result);
+            if (blocked)
+                return { ok: false, error: `The tool's result was withheld: it contains ${blocked}` };
+            return { ...result, result: cleaned };
+        },
+    };
+}
+function replace(match, kind, strategy) {
+    if (strategy === 'mask') {
+        const visible = match.replace(/[^A-Za-z0-9]/g, '').slice(-4);
+        return `${'*'.repeat(Math.max(4, match.length - visible.length))}${visible}`;
+    }
+    if (strategy === 'hash')
+        return `[${kind}:${shortHash(match)}]`;
+    return `[${kind}]`;
+}
+function isToolOutput(value) {
+    return value?.type === 'tool_output' && Array.isArray(value.content);
+}
+function luhn(match) {
+    const digits = match.replace(/\D/g, '');
+    if (digits.length < 13 || digits.length > 19)
+        return false;
+    let sum = 0;
+    for (let index = 0; index < digits.length; index += 1) {
+        let digit = Number(digits[digits.length - 1 - index]);
+        if (index % 2 === 1) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+    }
+    return sum % 10 === 0;
+}
+function ibanChecksum(match) {
+    const iban = match.replace(/ /g, '');
+    if (iban.length < 15 || iban.length > 34)
+        return false;
+    const rearranged = `${iban.slice(4)}${iban.slice(0, 4)}`;
+    let remainder = 0;
+    for (const char of rearranged) {
+        const value = /\d/.test(char) ? char : String(char.charCodeAt(0) - 55);
+        for (const digit of value)
+            remainder = (remainder * 10 + Number(digit)) % 97;
+    }
+    return remainder === 1;
+}

package/dist/agent/middleware/retry.d.ts

@@ -0,0 +1,66 @@
+import type { NexusResponse } from '../../types/response.js';
+import type { AgentMiddleware, AgentToolCall, AgentToolResult } from '../create-agent.js';
+import { type RetryBackoff } from './shared.js';
+/** One retry about to happen. */
+export interface RetryEvent {
+    /** The attempt that failed, from 1. */
+    attempt: number;
+    /** How long until the next attempt, in milliseconds. */
+    delayMs: number;
+    /** The error a model call threw, when it threw. */
+    error?: unknown;
+    /** The failed tool call's result, for a tool retry. */
+    result?: AgentToolResult;
+    /** The tool's name, for a tool retry. */
+    tool?: string;
+}
+/** Options for `modelRetry()`. */
+export interface ModelRetryOptions {
+    /** Attempts in all, the first included. Defaults to 3. */
+    attempts?: number;
+    /** How long to wait between attempts. */
+    backoff?: RetryBackoff;
+    /**
+     * Whether an error is worth another attempt. Defaults to every error not marked
+     * `retryable: false`, such as a provider's authentication error, and never a cancellation.
+     */
+    retryOn?: (error: unknown, attempt: number) => boolean;
+    /** Whether a response that did arrive is tried again, such as an empty one. Defaults to never. */
+    retryResponse?: (response: NexusResponse, attempt: number) => boolean;
+    /** Called before each new attempt, for logs and metrics. */
+    onRetry?: (event: RetryEvent) => void;
+}
+/**
+ * Tries a failed model call again, with exponential backoff.
+ *
+ * The client already retries one provider request; this retries the agent's step as a whole, after
+ * the client gave up, and can retry a response that arrived but is unusable. A streamed call that
+ * fails halfway streams again from the start. Waits stop when the run is cancelled.
+ */
+export declare function modelRetry(options?: ModelRetryOptions): AgentMiddleware;
+/** Options for `toolRetry()`. */
+export interface ToolRetryOptions {
+    /** Attempts in all, the first included. Defaults to 3. */
+    attempts?: number;
+    /** How long to wait between attempts. */
+    backoff?: RetryBackoff;
+    /**
+     * Which calls may run again: tool names, `'all'`, or a function of the call. Defaults to calls
+     * that are safe to repeat, whose tool declares capabilities and none of them writes, runs a
+     * command or code, reaches the network, or is the application's own. A call that may already have
+     * changed something is retried only when you say so.
+     */
+    tools?: readonly string[] | 'all' | ((call: AgentToolCall) => boolean);
+    /** Whether a result is a failure worth another attempt. Defaults to any result with `ok: false`. */
+    retryOn?: (result: AgentToolResult, call: AgentToolCall, attempt: number) => boolean;
+    /** Called before each new attempt, for logs and metrics. */
+    onRetry?: (event: RetryEvent) => void;
+}
+/**
+ * Runs a failed tool call again, with exponential backoff.
+ *
+ * By default only a call that cannot have changed anything is repeated: retrying a payment or a
+ * write that timed out after it landed would do it twice. Name the tools that are idempotent to
+ * retry those too.
+ */
+export declare function toolRetry(options?: ToolRetryOptions): AgentMiddleware;

package/dist/agent/middleware/retry.js

@@ -0,0 +1,59 @@
+import { isSensitiveCapability } from '../capabilities.js';
+import { backoffDelay, isCancellation, sleep } from './shared.js';
+export function modelRetry(options = {}) {
+    const attempts = Math.max(1, options.attempts ?? 3);
+    const retryOn = options.retryOn ?? ((error) => error?.retryable !== false);
+    return {
+        name: 'model-retry',
+        async wrapModelCall(request, next, context) {
+            for (let attempt = 1;; attempt += 1) {
+                try {
+                    const response = await next(request);
+                    if (attempt < attempts && options.retryResponse?.(response, attempt)) {
+                        const delayMs = backoffDelay(attempt, options.backoff);
+                        options.onRetry?.({ attempt, delayMs });
+                        await sleep(delayMs, context.signal);
+                        continue;
+                    }
+                    return response;
+                }
+                catch (error) {
+                    if (attempt >= attempts || isCancellation(error, context.signal) || !retryOn(error, attempt))
+                        throw error;
+                    const delayMs = backoffDelay(attempt, options.backoff);
+                    options.onRetry?.({ attempt, delayMs, error });
+                    await sleep(delayMs, context.signal);
+                }
+            }
+        },
+    };
+}
+export function toolRetry(options = {}) {
+    const attempts = Math.max(1, options.attempts ?? 3);
+    const retryOn = options.retryOn ?? ((result) => !result.ok);
+    const eligible = (call) => {
+        const tools = options.tools;
+        if (tools === 'all')
+            return true;
+        if (typeof tools === 'function')
+            return tools(call);
+        if (tools)
+            return tools.includes(call.name);
+        return call.capabilities !== undefined && !call.capabilities.some(isSensitiveCapability);
+    };
+    return {
+        name: 'tool-retry',
+        async wrapToolCall(call, next, context) {
+            if (!eligible(call))
+                return next();
+            for (let attempt = 1;; attempt += 1) {
+                const result = await next();
+                if (attempt >= attempts || context.signal.aborted || !retryOn(result, call, attempt))
+                    return result;
+                const delayMs = backoffDelay(attempt, options.backoff);
+                options.onRetry?.({ attempt, delayMs, result, tool: call.name });
+                await sleep(delayMs, context.signal);
+            }
+        },
+    };
+}

package/dist/agent/middleware/shared.d.ts

@@ -0,0 +1,41 @@
+import type { Message } from '../../types/messages.js';
+import type { AgentToolCall } from '../create-agent.js';
+/**
+ * What the middleware share. Every count here is read from the transcript rather than kept in
+ * memory, so it survives a restart, a resumed approval, and a second process, and two threads never
+ * share one.
+ */
+/**
+ * The current turn: every message after the latest user message. One `invoke()` is one turn; a run
+ * that resumes after an approval is the same turn.
+ */
+export declare function turnOf(messages: readonly Message[]): readonly Message[];
+/** Model calls made in the current turn: its assistant messages. */
+export declare function modelCallsInTurn(messages: readonly Message[]): number;
+/**
+ * Where a call sits among the current turn's calls to the same tool, from 1. Calls the model made in
+ * parallel are ordered as the model listed them, so the position never depends on which finished
+ * first.
+ */
+export declare function callPosition(messages: readonly Message[], call: Pick<AgentToolCall, 'id' | 'name'>): number;
+/** A message's text: the string, or its text parts joined. */
+export declare function textOf(content: Message['content']): string;
+/** How long to wait between attempts. */
+export interface RetryBackoff {
+    /** The wait before the second attempt, in milliseconds. Defaults to 500. */
+    initialMs?: number;
+    /** The longest wait, in milliseconds. Defaults to 10,000. */
+    maxMs?: number;
+    /** What each wait is multiplied by. Defaults to 2. */
+    factor?: number;
+    /** Spreads each wait between half and all of it, so runs that failed together retry apart. Defaults to true. */
+    jitter?: boolean;
+}
+/** The wait before attempt `attempt + 1`, after `attempt` failed. */
+export declare function backoffDelay(attempt: number, backoff?: RetryBackoff): number;
+/** Waits, or rejects with the signal's reason as soon as it aborts. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/** True for a cancellation: never worth retrying or falling back from. */
+export declare function isCancellation(error: unknown, signal?: AbortSignal): boolean;
+/** A short, stable hash of a text: cyrb53 as 8 hex digits. Not a security boundary. */
+export declare function shortHash(text: string): string;

package/dist/agent/middleware/shared.js

@@ -0,0 +1,73 @@
+export function turnOf(messages) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        if (messages[index]?.role === 'user')
+            return messages.slice(index + 1);
+    }
+    return messages;
+}
+export function modelCallsInTurn(messages) {
+    return turnOf(messages).filter((message) => message.role === 'assistant').length;
+}
+export function callPosition(messages, call) {
+    let position = 0;
+    for (const message of turnOf(messages)) {
+        for (const made of message.toolCalls ?? []) {
+            if (made.function.name !== call.name)
+                continue;
+            position += 1;
+            if (made.id === call.id)
+                return position;
+        }
+    }
+    return position + 1;
+}
+export function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    return content
+        .filter((part) => part.type === 'text')
+        .map((part) => part.text)
+        .join('\n');
+}
+export function backoffDelay(attempt, backoff = {}) {
+    const initial = backoff.initialMs ?? 500;
+    const delay = Math.min(backoff.maxMs ?? 10_000, initial * (backoff.factor ?? 2) ** Math.max(0, attempt - 1));
+    return backoff.jitter === false ? delay : delay / 2 + Math.random() * (delay / 2);
+}
+export function sleep(ms, signal) {
+    if (ms <= 0)
+        return signal?.aborted ? Promise.reject(signal.reason) : Promise.resolve();
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+export function isCancellation(error, signal) {
+    if (signal?.aborted)
+        return true;
+    const name = error?.name;
+    return name === 'AbortError';
+}
+export function shortHash(text) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        h1 = Math.imul(h1 ^ code, 2654435761);
+        h2 = Math.imul(h2 ^ code, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(16).padStart(14, '0').slice(-8);
+}

package/dist/agent/middleware/tool-selector.d.ts

@@ -0,0 +1,64 @@
+import type { CompletionRequest, ToolDefinition } from '../../types/messages.js';
+import type { AgentMiddleware, AgentMiddlewareContext } from '../create-agent.js';
+/** What a rule chooses tools from. */
+export interface ToolSelectionContext extends AgentMiddlewareContext {
+    /** The request about to be sent. */
+    request: CompletionRequest;
+    /** Every tool the request offers. */
+    tools: readonly ToolDefinition[];
+    /** What the turn is about: the text `query` returned. */
+    query: string;
+}
+/** Options for `toolSelector()`. Give it `select`, `embed`, or both. */
+export interface ToolSelectorOptions {
+    /**
+     * A rule: the names of the tools to send. With `embed` too, the rule narrows the candidates and
+     * similarity ranks what is left.
+     */
+    select?: (context: ToolSelectionContext) => readonly string[] | Promise<readonly string[]>;
+    /**
+     * Embeds texts, for choosing by similarity: any embedding function, such as one from
+     * `toEmbeddingFunction()`. Each tool is embedded once, from `describe`; the query once per turn.
+     */
+    embed?: (texts: string[]) => Promise<readonly (readonly number[])[]> | readonly (readonly number[])[];
+    /** The most tools sent, `always` included. Defaults to 12. */
+    maxTools?: number;
+    /** The lowest similarity a tool needs to be sent, from -1 to 1. Defaults to none. */
+    minScore?: number;
+    /** Tools sent on every call, whatever the turn is about. */
+    always?: readonly string[];
+    /**
+     * Keeps every tool the model already called this turn, so a tool it is halfway through using
+     * never disappears from under it. Defaults to true.
+     */
+    keepUsed?: boolean;
+    /** What the turn is about. Defaults to the latest user message. */
+    query?: (context: AgentMiddlewareContext & {
+        request: CompletionRequest;
+    }) => string;
+    /** The text a tool is embedded from. Defaults to its name and description. */
+    describe?: (tool: ToolDefinition) => string;
+    /** Called with each selection, for logs and for measuring what the selector saves. */
+    onSelect?: (selection: ToolSelection) => void;
+}
+/** What `toolSelector()` sent for one call. */
+export interface ToolSelection {
+    /** The query the tools were chosen for. */
+    query: string;
+    /** The names of the tools sent. */
+    selected: string[];
+    /** How many tools the request offered. */
+    offered: number;
+    /** Each ranked tool's similarity to the query, when tools were chosen by similarity. */
+    scores?: Record<string, number>;
+}
+/**
+ * Sends a model only the tools relevant to the turn.
+ *
+ * An agent with 150 tools otherwise sends 150 schemas on every call: the tokens are paid each time,
+ * the call is slower, and a model choosing among that many picks worse. A rule, embedding
+ * similarity, or both choose a dozen; tools named in `always`, the tool a `toolChoice` forces, and
+ * the tools the model already used this turn are always kept. The agent can still run every tool —
+ * only what the model is offered changes.
+ */
+export declare function toolSelector(options: ToolSelectorOptions): AgentMiddleware;

package/dist/agent/middleware/tool-selector.js

@@ -0,0 +1,106 @@
+import { textOf, turnOf } from './shared.js';
+export function toolSelector(options) {
+    if (!options.select && !options.embed) {
+        throw new TypeError('toolSelector() needs a select rule, an embed function, or both');
+    }
+    const maxTools = Math.max(1, options.maxTools ?? 12);
+    const describe = options.describe ?? ((tool) => `${tool.name}: ${tool.description}`);
+    const vectors = new Map();
+    let lastQuery;
+    const embedTools = async (tools) => {
+        const missing = [...new Set(tools.map(describe).filter((text) => !vectors.has(text)))];
+        if (missing.length === 0 || !options.embed)
+            return;
+        const embedded = await options.embed(missing);
+        missing.forEach((text, index) => {
+            const vector = embedded[index];
+            if (vector)
+                vectors.set(text, normalize(vector));
+        });
+    };
+    const embedQuery = async (text) => {
+        if (!options.embed || !text.trim())
+            return undefined;
+        if (lastQuery?.text === text)
+            return lastQuery.vector;
+        const [vector] = await options.embed([text]);
+        if (!vector)
+            return undefined;
+        lastQuery = { text, vector: normalize(vector) };
+        return lastQuery.vector;
+    };
+    return {
+        name: 'tool-selector',
+        async beforeModel(context) {
+            const { request } = context;
+            const offered = request.tools ?? [];
+            if (offered.length === 0 || (!options.select && offered.length <= maxTools))
+                return;
+            const query = options.query?.(context) ?? latestUserText(context.state.messages);
+            const kept = new Set(options.always ?? []);
+            if (request.toolChoice && typeof request.toolChoice === 'object')
+                kept.add(request.toolChoice.name);
+            if (options.keepUsed !== false) {
+                for (const message of turnOf(context.state.messages)) {
+                    for (const call of message.toolCalls ?? [])
+                        kept.add(call.function.name);
+                }
+            }
+            let candidates = offered.filter((tool) => !kept.has(tool.name));
+            if (options.select) {
+                const chosen = new Set(await options.select({ ...context, tools: offered, query }));
+                candidates = candidates.filter((tool) => chosen.has(tool.name));
+            }
+            let scores;
+            const room = Math.max(0, maxTools - kept.size);
+            if (options.embed) {
+                const vector = await embedQuery(query);
+                if (vector) {
+                    await embedTools(candidates);
+                    scores = {};
+                    const ranked = candidates
+                        .map((tool) => ({ tool, score: dot(vector, vectors.get(describe(tool)) ?? []) }))
+                        .filter((entry) => options.minScore === undefined || entry.score >= options.minScore)
+                        .sort((left, right) => right.score - left.score);
+                    for (const entry of ranked)
+                        scores[entry.tool.name] = round(entry.score);
+                    candidates = ranked.map((entry) => entry.tool);
+                }
+            }
+            const names = new Set([...kept, ...candidates.slice(0, room).map((tool) => tool.name)]);
+            const tools = offered.filter((tool) => names.has(tool.name));
+            options.onSelect?.({
+                query,
+                selected: tools.map((tool) => tool.name),
+                offered: offered.length,
+                ...(scores ? { scores } : {}),
+            });
+            return { ...request, tools };
+        },
+    };
+}
+function latestUserText(messages) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message?.role === 'user')
+            return textOf(message.content);
+    }
+    return '';
+}
+function normalize(vector) {
+    let norm = 0;
+    for (const value of vector)
+        norm += value * value;
+    norm = Math.sqrt(norm);
+    return norm === 0 ? vector : vector.map((value) => value / norm);
+}
+function dot(left, right) {
+    let total = 0;
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1)
+        total += left[index] * right[index];
+    return total;
+}
+function round(value) {
+    return Math.round(value * 1000) / 1000;
+}