nexus-ai-pro 2.2.0 → 2.3.0

package/dist-cjs/agent/middleware/shared.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.turnOf = turnOf;
+exports.modelCallsInTurn = modelCallsInTurn;
+exports.callPosition = callPosition;
+exports.textOf = textOf;
+exports.backoffDelay = backoffDelay;
+exports.sleep = sleep;
+exports.isCancellation = isCancellation;
+exports.shortHash = shortHash;
+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;
+}
+function modelCallsInTurn(messages) {
+    return turnOf(messages).filter((message) => message.role === 'assistant').length;
+}
+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;
+}
+function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    return content
+        .filter((part) => part.type === 'text')
+        .map((part) => part.text)
+        .join('\n');
+}
+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);
+}
+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 });
+    });
+}
+function isCancellation(error, signal) {
+    if (signal?.aborted)
+        return true;
+    const name = error?.name;
+    return name === 'AbortError';
+}
+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-cjs/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-cjs/agent/middleware/tool-selector.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolSelector = toolSelector;
+const shared_js_1 = require("./shared.js");
+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 (0, shared_js_1.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 (0, shared_js_1.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;
+}

package/dist-cjs/agent/permissions.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Permission policies: what an agent's tools may do, decided per call from what each call declares.
+ *
+ * Danger belongs to what a tool does, not to its name. A tool declares capabilities — a path it
+ * writes, a host it calls, a command it runs — and a policy grants filesystem paths, network hosts,
+ * and shell commands, and decides every call: allow it, deny it, or ask a person first. A call is
+ * denied when any of its capabilities is, asked about when any needs approval, and allowed only when
+ * every one is granted.
+ */
+import type { Principal } from '../types/principal.js';
+export { capabilitiesOf, isSensitiveCapability, type ParsedCapability, parseCapability } from './capabilities.js';
+/** What a policy decides for one call: run it, refuse it, or interrupt for a person's approval. */
+export type PermissionDecision = 'allow' | 'ask' | 'deny';
+/** One tool call, as a policy sees it. */
+export interface PermissionRequest {
+    /** The tool's name. */
+    tool: string;
+    /** The call's arguments. */
+    args: Record<string, unknown>;
+    /** What the call declares it does, or `undefined` when the tool declares nothing. */
+    capabilities: readonly string[] | undefined;
+    /** Who the run is for, when it has a principal, so a policy of your own can decide by role or scope. */
+    principal?: Readonly<Principal>;
+}
+/** A policy's decision, with the reason a person or a model reads. */
+export interface PermissionVerdict {
+    /** The decision. */
+    decision: PermissionDecision;
+    /** Why, naming the capability that decided it. */
+    reason: string;
+    /** The capability that decided it, when one did. */
+    capability?: string;
+}
+/** Anything that decides tool calls. `createAgent({ permissions })` takes one. */
+export interface PermissionPolicyLike {
+    /** Decides one call. */
+    decide(request: PermissionRequest): PermissionVerdict | Promise<PermissionVerdict>;
+}
+/** What a policy grants. Anything not granted is denied unless `ungranted` says otherwise. */
+export interface PermissionRules {
+    /**
+     * Paths a tool may read and write, as globs: `*` within one path segment, `**` across segments, so
+     * `/workspace/**` is the workspace and everything in it. A write grant also allows reading.
+     */
+    filesystem?: {
+        read?: readonly string[];
+        write?: readonly string[];
+    };
+    /** Hosts a tool may reach: `api.github.com`, `*.openai.com` for its subdomains, or `*` for any. */
+    network?: {
+        allow?: readonly string[];
+    };
+    /**
+     * Commands a tool may run, each the start of a command line: `git` allows every git command, and
+     * `npm test` only that. A command line that chains, pipes, redirects, or substitutes is never
+     * granted by these, only by `*`.
+     */
+    shell?: {
+        allow?: readonly string[];
+    };
+    /** Running code a tool was given. Defaults to `deny`; a sandboxed interpreter is the place for `ask` or `allow`. */
+    code?: PermissionDecision;
+    /** Decisions for the application's own capabilities, by kind or by full capability: `{ payments: 'ask' }`. */
+    custom?: Readonly<Record<string, PermissionDecision>>;
+    /**
+     * Capabilities that need a person's approval even when granted, as patterns: `shell`,
+     * `filesystem:write`, `network:*.stripe.com`, `payments`.
+     */
+    ask?: readonly string[];
+    /** A tool that declares no capabilities. Defaults to `deny`: a policy cannot judge what it cannot see. */
+    undeclared?: PermissionDecision;
+    /** A capability no grant covers. Defaults to `deny`. */
+    ungranted?: 'ask' | 'deny';
+    /** Decisions per tool name, applied before anything else. */
+    tools?: Readonly<Record<string, PermissionDecision>>;
+    /** What a relative path is resolved against. Defaults to `/`. */
+    root?: string;
+}
+/**
+ * Builds a policy from what it grants.
+ *
+ * ```ts
+ * const permissions = permissionPolicy({
+ *   filesystem: { read: ['/workspace/**'], write: ['/workspace/output/**'] },
+ *   network: { allow: ['api.github.com', '*.openai.com'] },
+ *   shell: { allow: ['git', 'npm test'] },
+ *   ask: ['shell', 'filesystem:write'],
+ * });
+ * const agent = createAgent({ client, tools, permissions, checkpointer });
+ * ```
+ */
+export declare function permissionPolicy(rules: PermissionRules): PermissionPolicy;
+/** A policy built from `PermissionRules`. Deterministic: the same call always gets the same decision. */
+export declare class PermissionPolicy implements PermissionPolicyLike {
+    /** What the policy grants. */
+    readonly rules: PermissionRules;
+    constructor(
+    /** What the policy grants. */
+    rules: PermissionRules);
+    /** Decides one call from its declared capabilities. */
+    decide(request: PermissionRequest): PermissionVerdict;
+    /** Decides one capability: granted or not, then whether it needs approval. */
+    decideOne(capability: string): PermissionVerdict;
+    private shown;
+    private root;
+    private granted;
+}
+/**
+ * A path made absolute and normalized, with `.` and `..` resolved, so `/workspace/../etc` is
+ * `/etc` before any grant sees it. Backslashes count as separators. `null` for a path that could
+ * never be safe to judge, such as one holding a NUL.
+ */
+export declare function normalizePath(path: string, root?: string): string | null;

package/dist-cjs/agent/permissions.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionPolicy = exports.parseCapability = exports.isSensitiveCapability = exports.capabilitiesOf = void 0;
+exports.permissionPolicy = permissionPolicy;
+exports.normalizePath = normalizePath;
+const capabilities_js_1 = require("./capabilities.js");
+var capabilities_js_2 = require("./capabilities.js");
+Object.defineProperty(exports, "capabilitiesOf", { enumerable: true, get: function () { return capabilities_js_2.capabilitiesOf; } });
+Object.defineProperty(exports, "isSensitiveCapability", { enumerable: true, get: function () { return capabilities_js_2.isSensitiveCapability; } });
+Object.defineProperty(exports, "parseCapability", { enumerable: true, get: function () { return capabilities_js_2.parseCapability; } });
+const ORDER = { allow: 0, ask: 1, deny: 2 };
+const CHAINING = /[;&|`$<>\n\r]/;
+function permissionPolicy(rules) {
+    return new PermissionPolicy(rules);
+}
+class PermissionPolicy {
+    rules;
+    constructor(rules) {
+        this.rules = rules;
+    }
+    decide(request) {
+        const forced = this.rules.tools?.[request.tool];
+        if (forced)
+            return { decision: forced, reason: `"${request.tool}" is set to ${forced} by name` };
+        if (request.capabilities === undefined) {
+            const decision = this.rules.undeclared ?? 'deny';
+            return {
+                decision,
+                reason: `"${request.tool}" declares no capabilities, so the policy cannot see what it does`,
+            };
+        }
+        let verdict = { decision: 'allow', reason: `every capability of "${request.tool}" is granted` };
+        for (const capability of request.capabilities) {
+            const next = this.decideOne(capability);
+            if (ORDER[next.decision] > ORDER[verdict.decision])
+                verdict = next;
+            if (verdict.decision === 'deny')
+                break;
+        }
+        return verdict;
+    }
+    decideOne(capability) {
+        const parsed = (0, capabilities_js_1.parseCapability)(capability);
+        const shown = this.shown(capability, parsed);
+        const granted = this.granted(parsed);
+        if (granted === 'deny') {
+            return { decision: this.rules.ungranted ?? 'deny', reason: `${shown} is not granted`, capability };
+        }
+        if (granted === 'ask' ||
+            (this.rules.ask ?? []).some((pattern) => capabilityMatches(pattern, parsed, this.root()))) {
+            return { decision: 'ask', reason: `${shown} needs approval`, capability };
+        }
+        return { decision: 'allow', reason: `${shown} is granted`, capability };
+    }
+    shown(capability, parsed) {
+        if (parsed.kind !== 'filesystem' || parsed.target === undefined)
+            return capability;
+        const resolved = normalizePath(parsed.target, this.root());
+        return resolved === null ? capability : `filesystem:${parsed.access ?? 'write'}:${resolved}`;
+    }
+    root() {
+        return this.rules.root ?? '/';
+    }
+    granted(parsed) {
+        switch (parsed.kind) {
+            case 'filesystem': {
+                const path = parsed.target === undefined ? undefined : normalizePath(parsed.target, this.root());
+                if (path === null)
+                    return 'deny';
+                const writes = this.rules.filesystem?.write ?? [];
+                const reads = [...(this.rules.filesystem?.read ?? []), ...writes];
+                const globs = parsed.access === 'read' ? reads : writes;
+                const matches = (glob) => path === undefined
+                    ? glob === '**' || glob === '/**'
+                    : globToRegExp(normalizePath(glob, this.root()) ?? '').test(path);
+                return globs.some(matches) ? 'allow' : 'deny';
+            }
+            case 'network': {
+                const host = parsed.target === undefined ? undefined : hostOf(parsed.target);
+                const allowed = this.rules.network?.allow ?? [];
+                return allowed.some((pattern) => hostMatches(pattern, host)) ? 'allow' : 'deny';
+            }
+            case 'shell': {
+                const allowed = this.rules.shell?.allow ?? [];
+                if (allowed.includes('*'))
+                    return 'allow';
+                const command = parsed.target?.trim();
+                if (!command || CHAINING.test(command))
+                    return 'deny';
+                const tokens = command.split(/\s+/);
+                return allowed.some((entry) => {
+                    const prefix = entry.trim().split(/\s+/);
+                    return prefix.every((token, index) => tokens[index] === token);
+                })
+                    ? 'allow'
+                    : 'deny';
+            }
+            case 'code':
+                return this.rules.code ?? 'deny';
+            default: {
+                const custom = this.rules.custom ?? {};
+                const full = parsed.target === undefined ? parsed.kind : `${parsed.kind}:${parsed.target}`;
+                return custom[full] ?? custom[parsed.kind] ?? 'deny';
+            }
+        }
+    }
+}
+exports.PermissionPolicy = PermissionPolicy;
+function capabilityMatches(pattern, capability, root) {
+    const wanted = (0, capabilities_js_1.parseCapability)(pattern);
+    if (wanted.kind !== capability.kind)
+        return false;
+    if (wanted.access && wanted.access !== capability.access)
+        return false;
+    if (wanted.target === undefined)
+        return true;
+    if (capability.target === undefined)
+        return false;
+    if (capability.kind === 'network')
+        return hostMatches(wanted.target, hostOf(capability.target));
+    if (capability.kind === 'filesystem') {
+        const path = normalizePath(capability.target, root);
+        return path !== null && globToRegExp(normalizePath(wanted.target, root) ?? '').test(path);
+    }
+    return globToRegExp(wanted.target).test(capability.target);
+}
+function normalizePath(path, root = '/') {
+    if (path.includes('\0'))
+        return null;
+    const unified = path.replace(/\\/g, '/');
+    const absolute = /^([A-Za-z]:)?\//.test(unified)
+        ? unified
+        : `${root.replace(/\\/g, '/').replace(/\/+$/, '')}/${unified}`;
+    const drive = /^[A-Za-z]:/.exec(absolute)?.[0]?.toLowerCase() ?? '';
+    const parts = [];
+    for (const segment of absolute.slice(drive.length).split('/')) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..')
+            parts.pop();
+        else
+            parts.push(segment);
+    }
+    return `${drive}/${parts.join('/')}`;
+}
+function globToRegExp(glob) {
+    let source = '';
+    for (let index = 0; index < glob.length; index += 1) {
+        const char = glob[index];
+        if (char === '*' && glob[index + 1] === '*') {
+            const atEnd = index + 2 === glob.length;
+            if (atEnd && source.endsWith('/')) {
+                source = `${source.slice(0, -1)}(?:/.*)?`;
+            }
+            else {
+                source += '.*';
+            }
+            index += 1;
+        }
+        else if (char === '*') {
+            source += '[^/]*';
+        }
+        else if (char === '?') {
+            source += '[^/]';
+        }
+        else {
+            source += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp(`^${source}$`, 'i');
+}
+function hostOf(target) {
+    try {
+        return new URL(target.includes('://') ? target : `https://${target}`).hostname.toLowerCase();
+    }
+    catch {
+        return target.toLowerCase();
+    }
+}
+function hostMatches(pattern, host) {
+    const wanted = pattern.trim().toLowerCase();
+    if (wanted === '*')
+        return true;
+    if (host === undefined)
+        return false;
+    if (wanted.startsWith('*.'))
+        return host.endsWith(wanted.slice(1)) && host.length > wanted.length - 1;
+    return host === wanted;
+}