nexus-ai-pro 2.2.0 → 2.4.0

package/dist-cjs/adapter-kit/errors.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdapterError = void 0;
+exports.classifyAdapterError = classifyAdapterError;
+class AdapterError extends Error {
+    adapter;
+    operation;
+    code;
+    retryable;
+    status;
+    constructor(adapter, operation, failure, cause) {
+        super(`${adapter} ${operation} failed (${failure.code}): ${cause instanceof Error ? cause.message : String(cause)}`, {
+            cause,
+        });
+        this.adapter = adapter;
+        this.operation = operation;
+        this.name = 'AdapterError';
+        this.code = failure.code;
+        this.retryable = failure.retryable;
+        if (failure.status !== undefined)
+            this.status = failure.status;
+    }
+}
+exports.AdapterError = AdapterError;
+const RETRYABLE = new Set(['RATE_LIMIT', 'TIMEOUT', 'UNAVAILABLE']);
+function classifyAdapterError(error) {
+    const value = error;
+    const raw = value?.status ?? value?.statusCode ?? value?.response?.status;
+    const status = typeof raw === 'number' ? raw : undefined;
+    const code = (() => {
+        if (value?.name === 'AbortError')
+            return 'CANCELLED';
+        if (value?.name === 'TimeoutError' || value?.code === 'ETIMEDOUT')
+            return 'TIMEOUT';
+        if (status !== undefined) {
+            if (status === 401 || status === 403)
+                return 'AUTH';
+            if (status === 404)
+                return 'NOT_FOUND';
+            if (status === 408)
+                return 'TIMEOUT';
+            if (status === 409 || status === 412)
+                return 'CONFLICT';
+            if (status === 429)
+                return 'RATE_LIMIT';
+            if (status >= 500)
+                return 'UNAVAILABLE';
+            if (status >= 400)
+                return 'INVALID';
+        }
+        if (typeof value?.code === 'string' && /^(ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|EPIPE)$/.test(value.code)) {
+            return 'UNAVAILABLE';
+        }
+        return 'UNKNOWN';
+    })();
+    return { code, retryable: RETRYABLE.has(code), ...(status === undefined ? {} : { status }) };
+}

package/dist-cjs/adapter-kit/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The adapter kit: how a package outside this repository builds an adapter — a provider, an
+ * embeddings backend, a vector store, a retriever, or a long-term store — and proves it works.
+ *
+ * Each `define*()` takes what the adapter is, the releases of `nexus-ai-pro` it supports, what it
+ * can do, and how to create it, and returns an adapter whose instances normalize every failure into
+ * an `AdapterError` and report every call for telemetry. Its `verify()` runs the same contract suite
+ * this package runs on its own adapters, skipping only what the adapter declares it cannot do, with a
+ * small benchmark held to the budgets it declares.
+ */
+import type { EmbeddingProvider, VectorStore } from '../hallucination/retrieval.js';
+import type { BaseProvider } from '../providers/base.js';
+import type { Retriever } from '../rag/retrievers.js';
+import { type EmbeddingProviderConformanceOptions } from '../testing/embedding-provider-conformance.js';
+import { type ProviderConformanceOptions } from '../testing/provider-conformance.js';
+import type { EmbeddingsProvider } from '../types/embeddings.js';
+import type { Store } from '../types/store.js';
+import { type AdapterCheck, type RetrieverCapabilities, type RetrieverContractOptions, type StoreCapabilities, type VectorStoreCapabilities } from './contracts.js';
+import { type AdapterErrorClass } from './errors.js';
+export { ADAPTER_FIXTURE_PASSAGES, type AdapterCheck, type RetrieverCapabilities, type RetrieverContractOptions, runRetrieverContract, runStoreContract, runVectorStoreContract, type StoreCapabilities, type VectorStoreCapabilities, type VectorStoreContractOptions, } from './contracts.js';
+export { AdapterError, type AdapterErrorClass, type AdapterErrorCode, classifyAdapterError } from './errors.js';
+export { parseVersion, satisfiesRange } from './semver.js';
+/** The kinds of adapter the kit builds. */
+export type AdapterKind = 'provider' | 'embeddings' | 'vector-store' | 'retriever' | 'store';
+/** What every adapter declares about itself. */
+export interface AdapterDefinition<Config, Instance, Capabilities> {
+    /** Its name, usually its package name, such as `@acme/nexus-milvus`. */
+    name: string;
+    /** Its own version. */
+    version: string;
+    /** The releases of `nexus-ai-pro` it works with, as a range: `>=2.4.0 <3`. */
+    nexus: string;
+    /** What it can do. The contract skips what it declares it cannot, and fails what it claims and cannot. */
+    capabilities: Capabilities;
+    /** Creates an instance from its configuration. */
+    create(config: Config): Instance | Promise<Instance>;
+    /**
+     * Classifies a failure from the service behind the adapter, when the kit's own reading of statuses
+     * and network codes is not enough. Returning nothing falls back to that reading.
+     */
+    normalizeError?(error: unknown, operation: string): AdapterErrorClass | undefined;
+    /** The p95 latency each operation must stay within in `verify()`'s benchmark, in milliseconds. */
+    budgets?: Readonly<Record<string, number>>;
+}
+/** One call through an adapter, for telemetry. */
+export interface AdapterCallEvent {
+    /** The adapter. */
+    adapter: string;
+    /** Its kind. */
+    kind: AdapterKind;
+    /** The method called, such as `search`. */
+    operation: string;
+    /** How long the call took, in milliseconds. */
+    durationMs: number;
+    /** Whether it succeeded. */
+    ok: boolean;
+    /** How it failed, when it did. */
+    error?: AdapterErrorClass;
+}
+/** Options for an adapter's `create()`. */
+export interface AdapterCreateOptions {
+    /** Receives every call: the hook a tracer, a metrics exporter, or a log subscribes with. */
+    onCall?: (event: AdapterCallEvent) => void;
+}
+/** What `verify()` measured for one operation over the contract's calls. */
+export interface AdapterBenchmarkEntry {
+    /** Successful calls measured. */
+    calls: number;
+    /** Median latency, in milliseconds. */
+    p50Ms: number;
+    /** 95th-percentile latency, in milliseconds. */
+    p95Ms: number;
+}
+/** What `verify()` found. */
+export interface AdapterReport {
+    /** The adapter. */
+    adapter: string;
+    /** Its version. */
+    version: string;
+    /** Its kind. */
+    kind: AdapterKind;
+    /** The `nexus-ai-pro` release it was verified against. */
+    nexusVersion: string;
+    /** Whether that release is inside the adapter's declared range. */
+    compatible: boolean;
+    /** True when it is compatible and every check that ran held. */
+    passed: boolean;
+    /** Every check, in order, with skipped ones marked. */
+    checks: AdapterCheck[];
+    /** Latency per operation over the contract's calls. */
+    benchmark: Record<string, AdapterBenchmarkEntry>;
+}
+/** An adapter built with the kit. */
+export interface Adapter<Config, Instance, Capabilities, VerifyOptions> extends Readonly<Omit<AdapterDefinition<Config, Instance, Capabilities>, 'create'>> {
+    /** Its kind. */
+    readonly kind: AdapterKind;
+    /** Creates an instance whose every call normalizes its failures and reports itself. */
+    create(config: Config, options?: AdapterCreateOptions): Promise<Instance>;
+    /** Whether a release of `nexus-ai-pro` is inside the declared range. Defaults to the installed one. */
+    compatible(nexusVersion?: string): boolean;
+    /** Runs the contract suite for its kind against a fresh instance, with a benchmark. */
+    verify(config: Config, options: VerifyOptions): Promise<AdapterReport>;
+}
+/** What a chat provider supports, which decides the conformance cases it runs. */
+export interface ProviderAdapterCapabilities {
+    /** `stream()`. */
+    streaming: boolean;
+    /** JSON output through `responseFormat`. */
+    json: boolean;
+    /** Tool calls. */
+    tools: boolean;
+    /** `healthCheck()`. */
+    health: boolean;
+}
+/** Options for a provider adapter's `verify()`: the model and, if you like, cases of your own. */
+export type ProviderVerifyOptions = Pick<ProviderConformanceOptions, 'model' | 'fixtures'>;
+/** Builds a chat-provider adapter, verified by the provider conformance suite. */
+export declare function defineProviderAdapter<Config, Instance extends BaseProvider>(definition: AdapterDefinition<Config, Instance, ProviderAdapterCapabilities>): Adapter<Config, Instance, ProviderAdapterCapabilities, ProviderVerifyOptions>;
+/** What an embeddings backend supports. */
+export interface EmbeddingsAdapterCapabilities {
+    /** Stops an embedding call when its signal aborts. */
+    abort: boolean;
+    /** Returns the same vectors for the same input. */
+    deterministic: boolean;
+}
+/** Options for an embeddings adapter's `verify()`. */
+export type EmbeddingsVerifyOptions = Pick<EmbeddingProviderConformanceOptions, 'model' | 'fixtures'>;
+/** Builds an embeddings adapter, verified by the embeddings conformance suite. */
+export declare function defineEmbeddingsAdapter<Config, Instance extends EmbeddingsProvider>(definition: AdapterDefinition<Config, Instance, EmbeddingsAdapterCapabilities>): Adapter<Config, Instance, EmbeddingsAdapterCapabilities, EmbeddingsVerifyOptions>;
+/** Options for a vector-store adapter's `verify()`. */
+export interface VectorStoreVerifyOptions {
+    /** The embedding function the store embeds with, to compute a query vector. */
+    embed: EmbeddingProvider;
+    /** Waits for writes to become searchable, for an eventually consistent index. */
+    settle?: () => Promise<void>;
+}
+/** Builds a vector-store adapter, verified by the `VectorStore` contract. */
+export declare function defineVectorStoreAdapter<Config, Instance extends VectorStore>(definition: AdapterDefinition<Config, Instance, VectorStoreCapabilities>): Adapter<Config, Instance, VectorStoreCapabilities, VectorStoreVerifyOptions>;
+/** Options for a retriever adapter's `verify()`. */
+export type RetrieverVerifyOptions = Omit<RetrieverContractOptions, 'capabilities'>;
+/** Builds a retriever adapter, verified by the `Retriever` contract, and the `SparseRetriever` one when it takes writes. */
+export declare function defineRetrieverAdapter<Config, Instance extends Retriever>(definition: AdapterDefinition<Config, Instance, RetrieverCapabilities>): Adapter<Config, Instance, RetrieverCapabilities, RetrieverVerifyOptions>;
+/** Builds a long-term store adapter, verified by the `Store` contract. */
+export declare function defineStoreAdapter<Config, Instance extends Store>(definition: AdapterDefinition<Config, Instance, StoreCapabilities>): Adapter<Config, Instance, StoreCapabilities, Record<string, never>>;

package/dist-cjs/adapter-kit/index.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.satisfiesRange = exports.parseVersion = exports.classifyAdapterError = exports.AdapterError = exports.runVectorStoreContract = exports.runStoreContract = exports.runRetrieverContract = exports.ADAPTER_FIXTURE_PASSAGES = void 0;
+exports.defineProviderAdapter = defineProviderAdapter;
+exports.defineEmbeddingsAdapter = defineEmbeddingsAdapter;
+exports.defineVectorStoreAdapter = defineVectorStoreAdapter;
+exports.defineRetrieverAdapter = defineRetrieverAdapter;
+exports.defineStoreAdapter = defineStoreAdapter;
+const embedding_provider_conformance_js_1 = require("../testing/embedding-provider-conformance.js");
+const provider_conformance_js_1 = require("../testing/provider-conformance.js");
+const version_js_1 = require("../version.js");
+const contracts_js_1 = require("./contracts.js");
+const errors_js_1 = require("./errors.js");
+const semver_js_1 = require("./semver.js");
+var contracts_js_2 = require("./contracts.js");
+Object.defineProperty(exports, "ADAPTER_FIXTURE_PASSAGES", { enumerable: true, get: function () { return contracts_js_2.ADAPTER_FIXTURE_PASSAGES; } });
+Object.defineProperty(exports, "runRetrieverContract", { enumerable: true, get: function () { return contracts_js_2.runRetrieverContract; } });
+Object.defineProperty(exports, "runStoreContract", { enumerable: true, get: function () { return contracts_js_2.runStoreContract; } });
+Object.defineProperty(exports, "runVectorStoreContract", { enumerable: true, get: function () { return contracts_js_2.runVectorStoreContract; } });
+var errors_js_2 = require("./errors.js");
+Object.defineProperty(exports, "AdapterError", { enumerable: true, get: function () { return errors_js_2.AdapterError; } });
+Object.defineProperty(exports, "classifyAdapterError", { enumerable: true, get: function () { return errors_js_2.classifyAdapterError; } });
+var semver_js_2 = require("./semver.js");
+Object.defineProperty(exports, "parseVersion", { enumerable: true, get: function () { return semver_js_2.parseVersion; } });
+Object.defineProperty(exports, "satisfiesRange", { enumerable: true, get: function () { return semver_js_2.satisfiesRange; } });
+const OPERATIONS = {
+    provider: ['complete', 'healthCheck'],
+    embeddings: ['embed'],
+    'vector-store': ['add', 'search', 'searchVector', 'delete'],
+    retriever: ['retrieve', 'add', 'delete'],
+    store: ['put', 'get', 'delete', 'search', 'listNamespaces'],
+};
+function build(kind, definition, contract) {
+    for (const field of ['name', 'version', 'nexus']) {
+        if (typeof definition[field] !== 'string' || !definition[field])
+            throw new TypeError(`An adapter needs a ${field}`);
+    }
+    (0, semver_js_1.satisfiesRange)(version_js_1.NEXUS_VERSION, definition.nexus);
+    const create = async (config, options = {}) => instrument(kind, definition, await definition.create(config), options);
+    return {
+        kind,
+        name: definition.name,
+        version: definition.version,
+        nexus: definition.nexus,
+        capabilities: definition.capabilities,
+        ...(definition.normalizeError ? { normalizeError: definition.normalizeError } : {}),
+        ...(definition.budgets ? { budgets: definition.budgets } : {}),
+        create,
+        compatible: (nexusVersion = version_js_1.NEXUS_VERSION) => (0, semver_js_1.satisfiesRange)(nexusVersion, definition.nexus),
+        async verify(config, options) {
+            const durations = new Map();
+            const instance = await create(config, {
+                onCall: (event) => {
+                    if (event.ok)
+                        durations.set(event.operation, [...(durations.get(event.operation) ?? []), event.durationMs]);
+                },
+            });
+            const compatible = (0, semver_js_1.satisfiesRange)(version_js_1.NEXUS_VERSION, definition.nexus);
+            const checks = [
+                {
+                    name: `declares support for nexus-ai-pro ${version_js_1.NEXUS_VERSION}`,
+                    ok: compatible,
+                    ...(compatible ? {} : { detail: `the declared range is ${definition.nexus}` }),
+                },
+                ...(await contract(instance, options, definition.capabilities)),
+            ];
+            const benchmark = {};
+            for (const [operation, values] of durations) {
+                const sorted = [...values].sort((a, b) => a - b);
+                const at = (q) => round(sorted[Math.min(sorted.length - 1, Math.ceil(q * sorted.length) - 1)] ?? 0);
+                benchmark[operation] = { calls: sorted.length, p50Ms: at(0.5), p95Ms: at(0.95) };
+            }
+            for (const [operation, budget] of Object.entries(definition.budgets ?? {})) {
+                const measured = benchmark[operation]?.p95Ms;
+                checks.push(measured === undefined
+                    ? {
+                        name: `${operation} stays within ${budget} ms at p95`,
+                        ok: true,
+                        skipped: true,
+                        detail: 'not called by the contract',
+                    }
+                    : {
+                        name: `${operation} stays within ${budget} ms at p95`,
+                        ok: measured <= budget,
+                        ...(measured <= budget ? {} : { detail: `measured ${measured} ms` }),
+                    });
+            }
+            return {
+                adapter: definition.name,
+                version: definition.version,
+                kind,
+                nexusVersion: version_js_1.NEXUS_VERSION,
+                compatible,
+                passed: checks.every((check) => check.ok),
+                checks,
+                benchmark,
+            };
+        },
+    };
+}
+function instrument(kind, definition, instance, options) {
+    const operations = new Set(OPERATIONS[kind]);
+    return new Proxy(instance, {
+        get(target, property, receiver) {
+            const value = Reflect.get(target, property, receiver);
+            if (typeof property !== 'string' || !operations.has(property) || typeof value !== 'function') {
+                return typeof value === 'function' ? value.bind(target) : value;
+            }
+            return async (...args) => {
+                const started = performance.now();
+                try {
+                    const result = await value.apply(target, args);
+                    options.onCall?.({
+                        adapter: definition.name,
+                        kind,
+                        operation: property,
+                        durationMs: performance.now() - started,
+                        ok: true,
+                    });
+                    return result;
+                }
+                catch (error) {
+                    const failure = error instanceof errors_js_1.AdapterError
+                        ? {
+                            code: error.code,
+                            retryable: error.retryable,
+                            ...(error.status === undefined ? {} : { status: error.status }),
+                        }
+                        : (definition.normalizeError?.(error, property) ?? (0, errors_js_1.classifyAdapterError)(error));
+                    options.onCall?.({
+                        adapter: definition.name,
+                        kind,
+                        operation: property,
+                        durationMs: performance.now() - started,
+                        ok: false,
+                        error: failure,
+                    });
+                    throw error instanceof errors_js_1.AdapterError ? error : new errors_js_1.AdapterError(definition.name, property, failure, error);
+                }
+            };
+        },
+    });
+}
+function defineProviderAdapter(definition) {
+    return build('provider', definition, async (provider, options, capabilities) => {
+        const results = await (0, provider_conformance_js_1.runProviderConformance)(definition.name, provider, {
+            ...options,
+            testStream: capabilities.streaming,
+            testJson: capabilities.json,
+            testTools: capabilities.tools,
+            testHealth: capabilities.health,
+        });
+        return results.flatMap((result) => [
+            {
+                name: `completes the ${result.caseName} case`,
+                ok: result.completeOk,
+                ...(result.completeOk ? {} : { detail: result.error ?? 'the response was not accepted' }),
+            },
+            ...(result.streamOk === undefined ? [] : [{ name: `streams the ${result.caseName} case`, ok: result.streamOk }]),
+            ...(result.healthOk === undefined ? [] : [{ name: 'answers its health check', ok: result.healthOk }]),
+        ]);
+    });
+}
+function defineEmbeddingsAdapter(definition) {
+    return build('embeddings', definition, async (provider, options, capabilities) => {
+        const results = await (0, embedding_provider_conformance_js_1.runEmbeddingProviderConformance)(definition.name, provider, {
+            ...options,
+            testAbort: capabilities.abort,
+            testDeterminism: capabilities.deterministic,
+        });
+        return results.flatMap((result) => [
+            {
+                name: `embeds the ${result.caseName} case`,
+                ok: result.ok,
+                ...(result.ok ? {} : { detail: result.error ?? 'not accepted' }),
+            },
+            ...(result.abortOk === undefined
+                ? []
+                : [{ name: `stops the ${result.caseName} case when aborted`, ok: result.abortOk }]),
+        ]);
+    });
+}
+function defineVectorStoreAdapter(definition) {
+    return build('vector-store', definition, (store, options, capabilities) => (0, contracts_js_1.runVectorStoreContract)(store, { ...options, capabilities }));
+}
+function defineRetrieverAdapter(definition) {
+    return build('retriever', definition, (retriever, options, capabilities) => (0, contracts_js_1.runRetrieverContract)(retriever, { ...options, capabilities }));
+}
+function defineStoreAdapter(definition) {
+    return build('store', definition, (store, _options, capabilities) => (0, contracts_js_1.runStoreContract)(store, { capabilities }));
+}
+function round(value) {
+    return Math.round(value * 100) / 100;
+}

package/dist-cjs/adapter-kit/semver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Version ranges, as an adapter declares the releases of `nexus-ai-pro` it works with. A small,
+ * dependency-free subset of npm's ranges: comparators joined by spaces must all hold, alternatives
+ * joined by `||` need one to hold, and `>=`, `>`, `<=`, `<`, `=`, `^`, `~`, `x`, and `*` mean what
+ * they mean in npm.
+ */
+type Version = [number, number, number];
+/** A version as three numbers. A prerelease or build tag is ignored. `undefined` for anything else. */
+export declare function parseVersion(version: string): Version | undefined;
+/** Whether `version` satisfies `range`, such as `>=2.4.0 <3` or `^2.4.0 || ^3.0.0`. */
+export declare function satisfiesRange(version: string, range: string): boolean;
+export {};

package/dist-cjs/adapter-kit/semver.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseVersion = parseVersion;
+exports.satisfiesRange = satisfiesRange;
+function parseVersion(version) {
+    const match = /^\s*v?(\d+)\.(\d+)\.(\d+)/.exec(version);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : undefined;
+}
+function satisfiesRange(version, range) {
+    const parsed = parseVersion(version);
+    if (!parsed)
+        return false;
+    return range.split('||').some((alternative) => {
+        const comparators = alternative.trim().split(/\s+/).filter(Boolean);
+        return comparators.length === 0 || comparators.every((comparator) => holds(parsed, comparator));
+    });
+}
+function holds(version, comparator) {
+    const match = /^(>=|<=|>|<|=|\^|~)?v?(\d+|x|X|\*)(?:\.(\d+|x|X|\*))?(?:\.(\d+|x|X|\*))?/.exec(comparator);
+    if (!match)
+        throw new RangeError(`"${comparator}" is not a version range`);
+    const operator = match[1] ?? '';
+    const parts = [match[2], match[3], match[4]];
+    const fixed = parts.findIndex((part) => part === undefined || /^[xX*]$/.test(part));
+    const known = fixed === -1 ? 3 : fixed;
+    const base = parts.map((part, index) => (index < known ? Number(part) : 0));
+    if (known === 0)
+        return operator === '' || operator === '=' || operator === '>=' || operator === '<=';
+    switch (operator) {
+        case '>=':
+            return compare(version, base) >= 0;
+        case '>':
+            return known === 3 ? compare(version, base) > 0 : compare(version, bump(base, known - 1)) >= 0;
+        case '<=':
+            return known === 3 ? compare(version, base) <= 0 : compare(version, bump(base, known - 1)) < 0;
+        case '<':
+            return compare(version, base) < 0;
+        case '^': {
+            const pinned = base[0] > 0 || known === 1 ? 0 : base[1] > 0 || known === 2 ? 1 : 2;
+            return compare(version, base) >= 0 && compare(version, bump(base, pinned)) < 0;
+        }
+        case '~':
+            return compare(version, base) >= 0 && compare(version, bump(base, known >= 2 ? 1 : 0)) < 0;
+        default:
+            return known === 3
+                ? compare(version, base) === 0
+                : compare(version, base) >= 0 && compare(version, bump(base, known - 1)) < 0;
+    }
+}
+function bump(version, part) {
+    return version.map((value, index) => (index < part ? value : index === part ? value + 1 : 0));
+}
+function compare(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        if (left[index] !== right[index])
+            return left[index] - right[index];
+    }
+    return 0;
+}

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

@@ -0,0 +1,39 @@
+import type { ToolDefinition } from '../types/messages.js';
+/**
+ * Capabilities: what a tool does to the world, written as strings a policy can decide on.
+ *
+ * | Capability | Means |
+ * | --- | --- |
+ * | `filesystem:read`, `filesystem:read:<path>` | Reads files, or one path |
+ * | `filesystem:write`, `filesystem:write:<path>` | Writes, creates, or deletes files |
+ * | `network`, `network:<host or URL>` | Opens a network connection, to a host when given |
+ * | `shell`, `shell:<command line>` | Runs a shell command |
+ * | `code` | Runs code it was given, as an interpreter does |
+ * | `<name>`, `<name>:<detail>` | Anything the application names, such as `payments:refund` |
+ *
+ * A tool that declares `capabilities: []` does nothing to the world; one that declares none at all
+ * is undeclared, and a policy decides on it as such.
+ */
+/** One capability, split into its parts. */
+export interface ParsedCapability {
+    /** `filesystem`, `network`, `shell`, `code`, or the application's own name. */
+    kind: string;
+    /** `read` or `write`, for the filesystem. */
+    access?: 'read' | 'write';
+    /** The path, host, command, or detail, when the capability names one. */
+    target?: string;
+}
+/** Splits a capability string into its kind, access, and target. */
+export declare function parseCapability(capability: string): ParsedCapability;
+/**
+ * The capabilities one call of a tool declares: its static list, or what its function computes from
+ * the call's arguments. `undefined` means undeclared — no list, or a function that threw — which is
+ * not the same as `[]`, a tool that declares it does nothing to the world.
+ */
+export declare function capabilitiesOf(tool: Pick<ToolDefinition, 'capabilities'> | undefined, args: Record<string, unknown>): string[] | undefined;
+/**
+ * Whether a capability is sensitive: anything but reading files. A pure tool declares
+ * `capabilities: []`; whatever it does declare, a write, a command, code, the network, or an
+ * effect of the application's own such as `payments`, changes the world or leaves the process.
+ */
+export declare function isSensitiveCapability(capability: string): boolean;

package/dist-cjs/agent/capabilities.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCapability = parseCapability;
+exports.capabilitiesOf = capabilitiesOf;
+exports.isSensitiveCapability = isSensitiveCapability;
+function parseCapability(capability) {
+    const text = capability.trim();
+    const colon = text.indexOf(':');
+    const kind = (colon < 0 ? text : text.slice(0, colon)).toLowerCase();
+    const rest = colon < 0 ? undefined : text.slice(colon + 1);
+    if (kind === 'filesystem') {
+        if (!rest)
+            return { kind };
+        const [access, ...path] = rest.split(':');
+        const parsed = { kind };
+        if (access === 'read' || access === 'write')
+            parsed.access = access;
+        const target = parsed.access ? path.join(':') : rest;
+        if (target)
+            parsed.target = target;
+        return parsed;
+    }
+    return rest === undefined || rest === '' ? { kind } : { kind, target: rest };
+}
+function capabilitiesOf(tool, args) {
+    const declared = tool?.capabilities;
+    if (!declared)
+        return undefined;
+    if (typeof declared !== 'function')
+        return [...declared];
+    try {
+        return [...declared(args)];
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSensitiveCapability(capability) {
+    const parsed = parseCapability(capability);
+    return !(parsed.kind === 'filesystem' && parsed.access === 'read');
+}