nexus-ai-pro 2.2.0 → 2.3.0

package/dist/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/agent/permissions.js

@@ -0,0 +1,180 @@
+import { parseCapability } from './capabilities.js';
+export { capabilitiesOf, isSensitiveCapability, parseCapability } from './capabilities.js';
+const ORDER = { allow: 0, ask: 1, deny: 2 };
+const CHAINING = /[;&|`$<>\n\r]/;
+export function permissionPolicy(rules) {
+    return new PermissionPolicy(rules);
+}
+export 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 = 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';
+            }
+        }
+    }
+}
+function capabilityMatches(pattern, capability, root) {
+    const wanted = 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);
+}
+export 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;
+}

package/dist/agent/sandbox.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The sandbox contract: where an agent's commands and code run, and where its files live.
+ *
+ * The package ships the contract and a conformance suite, not the isolation: a container, a VM, a
+ * remote interpreter, or a hosted sandbox fills the `Sandbox` interface. `processSandbox()` is a
+ * reference for development, which runs commands as ordinary processes; it says so in its
+ * `isolation`, and is never a security boundary.
+ */
+import type { ToolDefinition } from '../types/messages.js';
+/** Options for one command. */
+export interface SandboxExecOptions {
+    /** The working directory, inside the sandbox. Defaults to its root. */
+    cwd?: string;
+    /** Environment variables for the command. The host's own are never passed through. */
+    env?: Record<string, string>;
+    /** Sent to the command's standard input. */
+    stdin?: string;
+    /** Stops the command after this many milliseconds. */
+    timeoutMs?: number;
+    /** Stops the command when aborted. */
+    signal?: AbortSignal;
+}
+/** What a command did. */
+export interface SandboxExecResult {
+    /** Its exit code, or `null` when it was stopped. */
+    exitCode: number | null;
+    /** What it wrote to standard output. */
+    stdout: string;
+    /** What it wrote to standard error. */
+    stderr: string;
+    /** True when it was stopped by its timeout. */
+    timedOut: boolean;
+    /** How long it ran, in milliseconds. */
+    durationMs: number;
+}
+/** What a sandbox claims to isolate. The conformance suite checks the claims it can observe. */
+export interface SandboxIsolation {
+    /** Commands cannot read or write the host's files. */
+    filesystem: boolean;
+    /** Commands cannot reach the network, or only what the sandbox allows. */
+    network: boolean;
+    /** Commands cannot see or signal the host's processes. */
+    processes: boolean;
+}
+/** Where an agent's commands, code, and files go. The application provides one. */
+export interface Sandbox {
+    /** Names the sandbox in reports. */
+    readonly name: string;
+    /** What it isolates. */
+    readonly isolation: SandboxIsolation;
+    /** Runs a command line in the sandbox. */
+    exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>;
+    /** Reads a file, by a path inside the sandbox. */
+    readFile(file: string): Promise<string>;
+    /** Writes a file, creating its directory. */
+    writeFile(file: string, content: string): Promise<void>;
+    /** Lists a directory's entries. */
+    listFiles?(directory?: string): Promise<string[]>;
+    /** Removes a file or directory. */
+    removeFile?(file: string): Promise<void>;
+    /** Releases the sandbox. */
+    dispose?(): Promise<void>;
+}
+/** Raised when a path would leave the sandbox. */
+export declare class SandboxPathError extends Error {
+    /** The path that was refused. */
+    readonly path: string;
+    /** Always `SANDBOX_PATH`. */
+    readonly code = "SANDBOX_PATH";
+    constructor(
+    /** The path that was refused. */
+    path: string);
+}
+/** Options for `processSandbox()`. */
+export interface ProcessSandboxOptions {
+    /** The directory commands run in and files live under. Created when missing. */
+    root: string;
+    /** Environment variables every command gets, on top of a minimal `PATH`. */
+    env?: Record<string, string>;
+    /** Timeout for a command that sets none. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /** Output kept per stream, in bytes. Defaults to 1 MB. */
+    maxOutputBytes?: number;
+}
+/**
+ * A sandbox that runs commands as ordinary processes in a directory, for development and tests only.
+ *
+ * Its file methods refuse any path outside `root`, and commands get only `PATH` and the variables
+ * given, never the host's environment. But a command it runs can read and write anything the user
+ * can, and reach any host: `isolation` says so. Use a container or a VM in production.
+ */
+export declare function processSandbox(options: ProcessSandboxOptions): Sandbox;
+/** Options for `sandboxTools()`. */
+export interface SandboxToolsOptions {
+    /** Offer `run_command`. Defaults to true. */
+    shell?: boolean;
+    /** Offer `read_file`, `write_file`, and `list_files`. Defaults to true. */
+    files?: boolean;
+    /**
+     * The path a permission policy sees the sandbox's files under. Defaults to `/workspace`, so a
+     * policy granting `/workspace/**` grants the sandbox.
+     */
+    mount?: string;
+    /** Timeout for each command. */
+    timeoutMs?: number;
+}
+/**
+ * Tools that act through a sandbox, each declaring exactly what one call does: `run_command`
+ * declares `shell:<the command>`, and the file tools declare `filesystem:read` or
+ * `filesystem:write` with the path under `mount`. A permission policy can therefore grant a
+ * workspace, a few commands, and nothing else.
+ */
+export declare function sandboxTools(sandbox: Sandbox, options?: SandboxToolsOptions): ToolDefinition[];
+/** One conformance check's result. */
+export interface SandboxConformanceCheck {
+    /** What was checked. */
+    name: string;
+    /** Whether it held. */
+    ok: boolean;
+    /** What went wrong, when it did not. */
+    detail?: string;
+}
+/** What `runSandboxConformance()` found. */
+export interface SandboxConformanceReport {
+    /** The sandbox's name. */
+    sandbox: string;
+    /** True when every check held. */
+    passed: boolean;
+    /** Every check, in order. */
+    checks: SandboxConformanceCheck[];
+}
+/** Options for `runSandboxConformance()`. */
+export interface SandboxConformanceOptions {
+    /** The command that runs JavaScript inside the sandbox. Defaults to `node`. */
+    node?: string;
+    /** The timeout the timeout check sets, in milliseconds. Defaults to 300. */
+    timeoutMs?: number;
+}
+/**
+ * Checks a sandbox against the contract, without a test framework, so any sandbox — a container
+ * runner, a VM, a hosted service — can prove itself the same way:
+ *
+ * - commands report their output, errors, and exit code, take standard input and the variables
+ *   given, and never see the host's environment;
+ * - a command past its timeout is stopped and reported as timed out;
+ * - commands run where the files are, and files round-trip;
+ * - a path outside the sandbox is refused.
+ *
+ * Every check runs on a fresh sandbox from `create`, which is disposed afterwards.
+ */
+export declare function runSandboxConformance(create: () => Sandbox | Promise<Sandbox>, options?: SandboxConformanceOptions): Promise<SandboxConformanceReport>;