nexus-ai-pro 2.2.0 → 2.4.0

package/dist/server/deployments.d.ts

@@ -1,4 +1,5 @@
 import { type Regression, type RegressionMetric, type RunSample } from '../insights/regressions.js';
+import type { EvaluationScore, Evaluator } from '../types/evaluate.js';
 import type { DeploymentChange, DeploymentChangeRecord, DeploymentRecord, ReplicaReport, RevisionChoice, RevisionRequest, ServerAssistant, ServerDeployments, ServerStateStore } from '../types/server.js';
 export type { DeploymentChange, DeploymentChangeRecord, DeploymentRecord, ReplicaReport, RevisionChoice, RevisionReason, RevisionRequest, RunRevision, } from '../types/server.js';
 /** Options for `Deployments`. */
@@ -58,6 +59,30 @@ export interface RevisionStats {
     /** Mean recorded cost of finished runs, in US dollars. */
     meanCost?: number;
 }
+/** Options for `Deployments.evaluate()`. */
+export interface RunEvaluationOptions {
+    /** What each run is scored by: evaluators from `nexus-ai-pro/evaluate`, such as an LLM judge. */
+    evaluators: ReadonlyArray<Evaluator>;
+    /** Only runs created from this time, such as the start of a canary. */
+    since?: string;
+    /** Only this revision's runs. Defaults to every revision's. */
+    revision?: string;
+    /** The share of runs scored, from 0 to 1, chosen by run id so every replica picks the same ones. Defaults to 1. */
+    sampleRate?: number;
+    /** How many recent runs are read. Defaults to 2,000. */
+    limit?: number;
+    /** Recorded as each score's source; a run already scored by this source is skipped. Defaults to `online-evaluation`. */
+    source?: string;
+}
+/** What `Deployments.evaluate()` did. */
+export interface RunEvaluationReport {
+    /** Runs scored. */
+    evaluated: number;
+    /** Runs passed over because this source had already scored them. */
+    skipped: number;
+    /** Every score given. */
+    scores: EvaluationScore[];
+}
 /**
  * Revisions, traffic splits, and replica health for the agent server, recorded in a shared store.
  *
@@ -75,6 +100,8 @@ export interface RevisionStats {
 export declare class Deployments implements ServerDeployments {
     private readonly options;
     private readonly state;
+    /** The change in progress per deployment, which the next one waits for. */
+    private readonly changing;
     private readonly now;
     private readonly registrations;
     private readonly cache;
@@ -108,10 +135,16 @@ export declare class Deployments implements ServerDeployments {
      * `expectedVersion` applies a change only to the version it was decided on, and throws
      * `DEPLOYMENT_CONFLICT` otherwise, so two people — or a person and a canary guard — cannot undo each
      * other without noticing.
+     *
+     * Changes to one deployment through this object apply one at a time, so two made at once on one
+     * replica both land, in order. The state store has no atomic compare-and-set, so two replicas
+     * changing one deployment in the same instant can still lose one change: make changes from one
+     * place, or pass `expectedVersion` and retry a conflict.
      */
     change(assistant: string, change: DeploymentChange & {
         expectedVersion?: number;
     }, by?: string): Promise<DeploymentRecord>;
+    private applyChange;
     /** Sets each revision's share of new runs. */
     split(assistant: string, traffic: Record<string, number>, options?: {
         by?: string;
@@ -159,6 +192,17 @@ export declare class Deployments implements ServerDeployments {
      * expired run is an error, a cancelled one is left out.
      */
     samples(assistant: string, revision: string, since?: string, limit?: number): Promise<RunSample[]>;
+    /**
+     * Online evaluation of the server's own runs: scores each finished run's output with evaluators
+     * from `nexus-ai-pro/evaluate`, and records the scores as the run's feedback. A canary guard given
+     * those keys in `feedback` then compares quality between revisions, beside errors, latency, and
+     * cost.
+     *
+     * A run is scored once per `source`, so calling this on a schedule never counts a run twice.
+     * Sampling is stable: the same run is always in or out of a sample, on every replica. Evaluators
+     * judge a run by its output, since a run record does not keep its input.
+     */
+    evaluate(assistant: string, options: RunEvaluationOptions): Promise<RunEvaluationReport>;
     /** The deployment the router uses, reusing a recent read. */
     private current;
     /** The deployment of a registered assistant before anything is recorded: its live revision, all traffic. */
@@ -201,8 +245,26 @@ export interface CanaryGuardOptions {
         revision: string;
         since: string;
     }) => Promise<RunSample[]>;
-    /** Feedback keys whose mean score is compared, when `samples` supplies feedback. */
+    /**
+     * Feedback keys whose mean score is compared: the scores `Deployments.evaluate()` records from
+     * online evaluation, or any a person left through the feedback route. A canary that is worse on one
+     * is rolled back like one that fails more.
+     */
     feedback?: readonly string[];
+    /**
+     * Judges each metric as an evaluation comparison does, at this confidence, such as 0.95. A bootstrap
+     * interval must not reach zero, and the change must be at least the metric's minimum effect:
+     * `minErrorRateIncrease`, `latencyIncrease` with `minLatencyChangeMs`, `costIncrease`, and
+     * `minFeedbackDrop`. A real regression rolls back, and noise or a trivial change does not. Without
+     * it, the error rate uses a z-test at 95%, and latency and cost use their margins alone.
+     */
+    confidence?: number;
+    /** The smallest rise in the error rate, absolute, that counts under `confidence`. Defaults to 0.02. */
+    minErrorRateIncrease?: number;
+    /** The smallest fall in a feedback score's mean, absolute, that counts under `confidence`. Defaults to 0.05. */
+    minFeedbackDrop?: number;
+    /** Bootstrap resamples under `confidence`. Defaults to 1,000. */
+    resamples?: number;
     /** Recorded as who made a change. Defaults to `guard`. */
     by?: string;
     /** Hears every decision, including holds. */

package/dist/server/deployments.js

@@ -7,6 +7,7 @@ const EPSILON = 1e-9;
 export class Deployments {
     options;
     state;
+    changing = new Map();
     now;
     registrations = new Map();
     cache = new Map();
@@ -81,6 +82,18 @@ export class Deployments {
         return (await this.get(assistant))?.history ?? [];
     }
     async change(assistant, change, by) {
+        const previous = this.changing.get(assistant) ?? Promise.resolve();
+        const next = previous.catch(() => undefined).then(() => this.applyChange(assistant, change, by));
+        this.changing.set(assistant, next);
+        try {
+            return await next;
+        }
+        finally {
+            if (this.changing.get(assistant) === next)
+                this.changing.delete(assistant);
+        }
+    }
+    async applyChange(assistant, change, by) {
         const current = await this.get(assistant);
         if (!current) {
             throw new BadRequestError(`Assistant "${assistant}" has no deployment yet: serve it through Deployments.assistant() first`, 'UNKNOWN_DEPLOYMENT');
@@ -228,15 +241,67 @@ export class Deployments {
         return (await this.runs(assistant, { since, limit }))
             .filter((run) => (run.revision?.id ?? '') === revision)
             .flatMap((run) => {
+            const feedback = run.feedback?.length ? { feedback: run.feedback } : {};
             if (run.status === 'failed' || run.status === 'expired') {
-                return [{ status: 'error', latencyMs: run.durationMs, cost: run.cost }];
+                return [{ status: 'error', latencyMs: run.durationMs, cost: run.cost, ...feedback }];
             }
             if (run.status === 'succeeded' || run.status === 'awaiting_input') {
-                return [{ status: 'success', latencyMs: run.durationMs, cost: run.cost }];
+                return [{ status: 'success', latencyMs: run.durationMs, cost: run.cost, ...feedback }];
             }
             return [];
         });
     }
+    async evaluate(assistant, options) {
+        const source = options.source ?? 'online-evaluation';
+        const rate = options.sampleRate ?? 1;
+        const report = { evaluated: 0, skipped: 0, scores: [] };
+        for (const run of await this.runs(assistant, options)) {
+            if (run.status !== 'succeeded')
+                continue;
+            if (options.revision !== undefined && (run.revision?.id ?? '') !== options.revision)
+                continue;
+            if (rate < 1 && bucket(`evaluate:${run.id}`) >= rate)
+                continue;
+            if (run.feedback?.some((item) => item.source === source)) {
+                report.skipped += 1;
+                continue;
+            }
+            const scores = [];
+            for (const evaluator of options.evaluators) {
+                const value = await evaluator({
+                    example: { id: run.id, inputs: undefined, ...(run.metadata ? { metadata: run.metadata } : {}) },
+                    output: run.output,
+                    latencyMs: run.durationMs ?? 0,
+                    ...(run.cost === undefined ? {} : { cost: run.cost }),
+                    run: 0,
+                });
+                if (typeof value === 'number')
+                    scores.push({ key: 'score', score: value });
+                else if (typeof value === 'boolean')
+                    scores.push({ key: 'score', score: value ? 1 : 0, passed: value });
+                else
+                    scores.push(...(Array.isArray(value) ? value : [value]));
+            }
+            const at = new Date().toISOString();
+            const latest = (await this.state.get(RUNS_NAMESPACE, run.id)) ?? run;
+            await this.state.put(RUNS_NAMESPACE, run.id, {
+                ...latest,
+                feedback: [
+                    ...(latest.feedback ?? []),
+                    ...scores.map((score) => ({
+                        key: score.key,
+                        score: score.score,
+                        ...(score.comment ? { comment: score.comment } : {}),
+                        source,
+                        createdAt: at,
+                    })),
+                ].slice(-100),
+            });
+            report.evaluated += 1;
+            report.scores.push(...scores);
+        }
+        return report;
+    }
     async current(assistant) {
         const cached = this.cache.get(assistant);
         if (cached && Date.now() - cached.at < (this.options.cacheMs ?? 2_000))
@@ -305,6 +370,14 @@ export function watchCanaries(options) {
             latencyIncrease: options.latencyIncrease,
             minLatencyChangeMs: options.minLatencyChangeMs ?? 50,
             costIncrease: options.costIncrease,
+            ...(options.confidence === undefined
+                ? {}
+                : {
+                    confidence: options.confidence,
+                    minErrorRateIncrease: options.minErrorRateIncrease,
+                    minFeedbackDrop: options.minFeedbackDrop,
+                    resamples: options.resamples,
+                }),
         });
         if (regressions.length > 0) {
             await deployments.change(deployment.assistant, {

package/dist/server/runs.d.ts

@@ -1,4 +1,5 @@
 import type { OperationRunnerConfig } from '../types/operations.js';
+import type { RunFeedback } from '../types/tracing.js';
 import type { Principal, ReplicaReport, RunEventLog, RunRecord, ScalingSnapshot, ServerAssistant, ServerStateStore, TenantGate, ThreadBusyPolicy, ThreadRecord } from '../types/server.js';
 import { ServerMetrics } from './metrics.js';
 /** What a run needs to start. */
@@ -161,6 +162,14 @@ export declare class RunManager {
     start(options: StartRunOptions): Promise<RunRecord>;
     /** The rest of `start()`, once the thread, if any, is this run's. */
     private startClaimed;
+    /**
+     * Leaves feedback on a run: a person's rating, or an online evaluator's score. A canary guard
+     * compares it between revisions as their quality. Another tenant's run is not found, and a run
+     * keeps its latest 100 pieces of feedback.
+     */
+    addFeedback(runId: string, feedback: Omit<RunFeedback, 'createdAt'> & {
+        createdAt?: string;
+    }, principal?: Principal): Promise<RunRecord>;
     /** Cancels a run, including one another replica is executing. */
     cancel(runId: string, principal?: Principal, reason?: string): Promise<RunRecord>;
     /**

package/dist/server/runs.js

@@ -177,6 +177,26 @@ export class RunManager {
             throw error;
         }
     }
+    async addFeedback(runId, feedback, principal) {
+        const run = await this.run(runId, principal);
+        if (typeof feedback.key !== 'string' || !feedback.key.trim())
+            throw new BadRequestError('Feedback needs a key');
+        if (feedback.score !== undefined && !(typeof feedback.score === 'number' && Number.isFinite(feedback.score))) {
+            throw new BadRequestError('A feedback score is a finite number');
+        }
+        const at = this.now().toISOString();
+        const entry = {
+            key: feedback.key,
+            ...(feedback.score === undefined ? {} : { score: feedback.score }),
+            ...(feedback.value === undefined ? {} : { value: feedback.value }),
+            ...(typeof feedback.comment === 'string' ? { comment: feedback.comment } : {}),
+            ...(typeof feedback.source === 'string' ? { source: feedback.source } : {}),
+            createdAt: feedback.createdAt ?? at,
+        };
+        const next = { ...run, feedback: [...(run.feedback ?? []), entry].slice(-100), updatedAt: at };
+        await this.state.put(RUNS, runId, next);
+        return next;
+    }
     async cancel(runId, principal, reason) {
         const run = await this.run(runId, principal);
         this.local.get(runId)?.cancel(reason);

package/dist/server/server.js

@@ -137,6 +137,11 @@ export function createAgentServer(options) {
         const body = await readJson(request);
         return json(await runs.cancel(params.runId, principal, body.reason));
     });
+    write('POST', '/runs/:runId/feedback', async ({ request, params, principal }) => {
+        const body = await readJson(request);
+        const run = await runs.addFeedback(params.runId, { ...body, source: body.source ?? principal?.userId ?? 'api' }, principal);
+        return json({ runId: run.id, feedback: run.feedback?.at(-1) }, 201);
+    });
     read('GET', '/runs/:runId/events', async ({ request, params, principal, url }) => {
         await runs.run(params.runId, principal);
         const header = request.headers.get('last-event-id') ?? url.searchParams.get('lastEventId');

package/dist/store/memory.d.ts

@@ -20,6 +20,10 @@ export declare class MemoryStore implements Store {
     private readonly options;
     private readonly items;
     private readonly maxItems;
+    /** Whether any item was ever given a time to live; until one is, there is nothing to sweep. */
+    private expiring;
+    /** When expired items were last swept, in milliseconds. */
+    private sweptAt;
     private readonly now;
     constructor(options?: MemoryStoreOptions);
     /** Stores an item, keeping its original `createdAt` when it replaces one. */
@@ -42,5 +46,11 @@ export declare class MemoryStore implements Store {
     size(): number;
     private embed;
     private expired;
+    /**
+     * Drops expired items. Reads already skip them, so this only reclaims memory: it runs once any item
+     * has a time to live, and at most once a second, so a write stays constant-time however many items
+     * there are. A store that is full sweeps before it evicts, so a live item never makes way for an
+     * expired one.
+     */
     private sweep;
 }

package/dist/store/memory.js

@@ -4,6 +4,8 @@ export class MemoryStore {
     options;
     items = new Map();
     maxItems;
+    expiring = false;
+    sweptAt = Number.NEGATIVE_INFINITY;
     now;
     constructor(options = {}) {
         this.options = options;
@@ -18,6 +20,8 @@ export class MemoryStore {
         const timestamp = this.now().toISOString();
         const existing = this.items.get(id);
         const vector = await this.embed(value, options.index);
+        if (options.ttlMs !== undefined)
+            this.expiring = true;
         this.items.delete(id);
         this.items.set(id, {
             namespace: [...namespace],
@@ -99,6 +103,12 @@ export class MemoryStore {
         return item.expiresAt !== undefined && Date.parse(item.expiresAt) <= this.now().getTime();
     }
     sweep() {
+        if (!this.expiring)
+            return;
+        const now = this.now().getTime();
+        if (now - this.sweptAt < 1_000 && this.items.size <= this.maxItems)
+            return;
+        this.sweptAt = now;
         for (const [id, item] of this.items)
             if (this.expired(item))
                 this.items.delete(id);

package/dist/testing/record.js

@@ -1,4 +1,4 @@
-import { createHash } from 'node:crypto';
+import { sha256Hex } from '../utils/sha256.js';
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 export class FixtureMissingError extends Error {
@@ -148,7 +148,7 @@ function defaultKey(input, ignoreBodyFields = []) {
     }
     catch {
     }
-    return createHash('sha256').update(`${input.method}\n${input.url}\n${body}`).digest('hex').slice(0, 16);
+    return sha256Hex(`${input.method}\n${input.url}\n${body}`).slice(0, 16);
 }
 function canonical(value) {
     if (Array.isArray(value))

package/dist/tracing/stores.js

@@ -1,3 +1,4 @@
+import { utf8Length } from '../utils/ids.js';
 import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { applyQuery, assembleTree } from './query.js';
@@ -132,7 +133,7 @@ export class JsonlTraceStore {
         catch {
             return;
         }
-        if (Buffer.byteLength(content, 'utf8') <= this.maxBytes)
+        if (utf8Length(content) <= this.maxBytes)
             return;
         const lines = content.split('\n').filter(Boolean);
         await writeFile(this.file, `${lines.slice(Math.floor(lines.length / 2)).join('\n')}\n`, 'utf8');

package/dist/tracing/tracer.js

@@ -1,5 +1,5 @@
+import { randomHex } from '../utils/ids.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { randomBytes } from 'node:crypto';
 export class Tracer {
     options;
     context = new AsyncLocalStorage();
@@ -194,7 +194,7 @@ export class Tracer {
     }
 }
 function id(prefix) {
-    return `${prefix}-${randomBytes(8).toString('hex')}`;
+    return `${prefix}-${randomHex(8)}`;
 }
 export function w3cTraceId(traceId) {
     if (/^[0-9a-f]{32}$/.test(traceId))

package/dist/types/config.d.ts

@@ -25,6 +25,11 @@ export interface OpenAIProviderConfig {
     apiKey: string;
     /** API base URL. Point it at an OpenAI-compatible server to use that instead. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
     /** OpenAI organization to bill. */
     organization?: string;
     /** Headers added to every request. */
@@ -59,6 +64,11 @@ export interface AnthropicProviderConfig {
     apiKey: string;
     /** API base URL. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
     /** Name this provider registers under. */
     providerName?: string;
     /** Model-name prefixes this provider answers for. */
@@ -75,6 +85,11 @@ export interface GoogleProviderConfig {
     apiKey: string;
     /** API base URL. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
 }
 /** Configuration for a local Ollama server. */
 export interface OllamaProviderConfig {
@@ -101,6 +116,11 @@ export interface CohereProviderConfig {
     apiKey: string;
     /** API base URL. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
 }
 export interface OpenRouterProviderConfig {
     apiKey: string;

package/dist/types/graph.d.ts

@@ -8,6 +8,7 @@ import type { OperationLifecycleLike } from './lifecycle.js';
  * is, so a different process can pick it up.
  */
 import type { CacheAdapter } from '../cache/adapters.js';
+import type { Principal } from './principal.js';
 import type { Store } from './store.js';
 /** Entry sentinel. An edge from `START` names the first node. */
 export declare const START = "__start__";
@@ -243,6 +244,14 @@ export interface NodeOptions<S extends ChannelSchema = ChannelSchema> {
      * that are not.
      */
     idempotent?: boolean;
+    /**
+     * What the node does to the world, as capabilities: `payments:charge`, `network:api.stripe.com`,
+     * `filesystem:write`. Declared for the linter, which reports a node with effects that also
+     * interrupts, since the node runs again from the top when the answer comes.
+     */
+    effects?: readonly string[];
+    /** True when the node may call `context.interrupt()`. Declared for the linter. */
+    interrupts?: boolean;
     /**
      * Nodes this one may reach through `Send` or a `Command`. Declaring them keeps compile-time
      * reachability checks and diagrams exact, so a node reached only that way is not reported as
@@ -374,6 +383,8 @@ export interface NodeContext<S extends ChannelSchema> {
     readonly threadId: string;
     /** The tenant the run is for, when it has one. */
     readonly tenantId?: string;
+    /** Who the run is for, when it was started with a principal: the caller the server authenticated. */
+    readonly principal?: Readonly<Principal>;
     /** Identifies this task. Equal to `node` unless the task came from a `Send`. */
     readonly taskId: string;
     /** Input carried by a `Send`. Undefined for a node reached through an ordinary edge. */
@@ -577,6 +588,14 @@ export interface GraphRunOptions {
      * `tenantId` is refused before anything runs. A run without one carries on the thread's tenant.
      */
     tenantId?: string;
+    /**
+     * Who the run is for, such as the caller the server authenticated. Nodes read it as
+     * `context.principal`, and an agent hands it to every tool and middleware. Its `tenantId` is the
+     * run's tenant when `tenantId` is not given, and a run whose two tenants differ is refused. Its
+     * `userId` is recorded on every checkpoint as `metadata.userId`; the rest is never stored, so a
+     * resumed run carries the principal of whoever resumed it.
+     */
+    principal?: Principal;
     /** Overrides the compiled `maxConcurrency` for this run. */
     maxConcurrency?: number;
     /** Breakpoints for this run only, replacing the compiled ones. */
@@ -853,6 +872,10 @@ export interface GraphDescription {
         idempotent?: boolean;
         /** True when the node reuses results through `cache`. */
         cache?: boolean;
+        /** The capabilities its work uses, when it declares them. */
+        effects?: string[];
+        /** True when it declares that it may interrupt. */
+        interrupts?: boolean;
         /** The graph this node runs, when it is a compiled graph used through `asNode()`. */
         subgraph?: GraphDescription;
     }>;
@@ -876,6 +899,19 @@ export interface GraphDescription {
     checkpointer?: 'memory' | 'custom' | 'none';
     /** Tasks a superstep runs at once. */
     maxConcurrency?: number;
+    /** The tools the graph's nodes call, when it was compiled with them, as an agent is. */
+    tools?: GraphToolDescription[];
+}
+/** A tool a graph calls, as the linter reads it. */
+export interface GraphToolDescription {
+    /** The tool's name. */
+    name: string;
+    /** Its capabilities, when it declares a fixed list. */
+    capabilities?: string[];
+    /** True when it computes its capabilities from each call's arguments. */
+    dynamic?: boolean;
+    /** How its calls are approved: an interrupt for each, a permission policy, or not at all. */
+    approval: 'interrupt' | 'policy' | 'none';
 }
 /**
  * Options applied when a graph is compiled: stores, breakpoints, concurrency, retries, and failure
@@ -898,6 +934,8 @@ export interface CompileOptions {
     maxConcurrency?: number;
     /** Default retry policy for every node. A node's own policy wins. */
     retry?: RetryPolicy;
+    /** The tools the graph's nodes call, for `describe()` and the linter. `createAgent()` fills it. */
+    tools?: GraphToolDescription[];
     /**
      * Defaults for every node: a retry policy, timeouts, and an `onError`. A node's own options win,
      * field by field. `retry` here is the same as `compile({ retry })`, and wins over it.

package/dist/types/messages.d.ts

@@ -1,5 +1,7 @@
 import type { CacheTtl, ReasoningEffort } from './providers.js';
 import type { AssetInput } from './images.js';
+import type { Principal } from './principal.js';
+import type { Store } from './store.js';
 declare global {
     namespace NodeJS {
         /**
@@ -128,8 +130,19 @@ export interface ToolDefinition {
     description: string;
     /** JSON Schema for the arguments. */
     parameters: Record<string, unknown>;
-    /** Runs the tool, for the agent loop and executors that call tools automatically. */
-    execute?: (args: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Runs the tool, for the agent loop and executors that call tools automatically. An agent passes
+     * a `ToolContext` too: who the run is for, its thread and tenant, its signal, and its store.
+     */
+    execute?: (args: Record<string, unknown>, context?: ToolContext) => Promise<unknown>;
+    /**
+     * What the tool does to the world, as capabilities a permission policy decides on:
+     * `filesystem:read` or `filesystem:write` with an optional path, `network` with an optional host,
+     * `shell` with an optional command, `code`, or a name of the application's own such as `payments`.
+     * A function computes them from each call's arguments, so a policy sees the path, host, or command
+     * the call actually uses. Never sent to a model.
+     */
+    capabilities?: readonly string[] | ((args: Record<string, unknown>) => readonly string[]);
     /**
      * Ends a cacheable prefix after this tool. Only honored when the request sets
      * `cache.mode: 'explicit'` and the provider accepts caller-placed breakpoints.
@@ -145,6 +158,27 @@ export interface ToolDefinition {
 export type ToolChoice = 'auto' | 'none' | 'required' | {
     name: string;
 };
+/**
+ * What a tool receives besides its arguments when an agent runs it. Every field is optional: a tool
+ * run outside an agent, or by an executor given nothing, sees none of them.
+ */
+export interface ToolContext {
+    /** The model's id for this call. */
+    toolCallId?: string;
+    /** The thread the run belongs to. */
+    threadId?: string;
+    /** The tenant the run is for. */
+    tenantId?: string;
+    /**
+     * Who the run is for: the caller the server authenticated, with their roles and scopes, so a
+     * tool can act as that user and nobody else.
+     */
+    principal?: Readonly<Principal>;
+    /** Aborted when the run is cancelled or the step times out. A tool that waits should stop with it. */
+    signal?: AbortSignal;
+    /** Long-term memory. In a tenant's run, the tenant's view of it. */
+    store?: Store;
+}
 /** What a tool returned, correlated with the call that asked for it. */
 export interface ToolCallResult {
     /** The id of the call this answers. */

package/dist/types/principal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Who a request, a run, or a tool call is for.
+ *
+ * One shape everywhere: the server's authentication hook returns it, a run carries it, graph nodes
+ * and workflow steps read it, tools and middleware receive it, and a permission policy can decide on
+ * it. Its tenant scopes threads, runs, budgets, and the store.
+ */
+export interface Principal {
+    /** Isolates threads, runs, and cron jobs. Requests only ever see their own tenant's resources. */
+    tenantId?: string;
+    /** Who the caller is: a token's subject, a key's owner. Recorded on what they create. */
+    userId?: string;
+    /** What the caller may do. A route that names a scope refuses a principal without it. */
+    scopes?: readonly string[];
+    /** The caller's roles, for policies and tools that decide by role rather than by scope. */
+    roles?: readonly string[];
+    /** How the caller was authenticated: `jwt`, `api-key`, `proxy`, or a name of your own. */
+    method?: string;
+    /** The verified claims or attributes the principal was built from, for anything the fields above leave out. */
+    claims?: Readonly<Record<string, unknown>>;
+}

package/dist/types/principal.js

@@ -0,0 +1 @@
+export {};

package/dist/types/server.d.ts

@@ -6,15 +6,9 @@
  * graph thread, so state, interrupts, and history come from the checkpointer; and an assistant is
  * anything that can stream events for an input, which a compiled graph already does.
  */
-/** Who is making a request, as the server's authentication hook reports them. */
-export interface Principal {
-    /** Isolates threads, runs, and cron jobs. Requests only ever see their own tenant's resources. */
-    tenantId?: string;
-    /** Who the caller is, recorded on what they create. */
-    userId?: string;
-    /** What the caller may do. A route that names a scope refuses a principal without it. */
-    scopes?: readonly string[];
-}
+import type { Principal } from './principal.js';
+import type { RunFeedback } from './tracing.js';
+export type { Principal };
 /** Where a run stands, as the server reports it. */
 export type RunStatus = 'queued' | 'running' | 'awaiting_input' | 'succeeded' | 'failed' | 'cancelled' | 'expired';
 /** What happens when a run is requested for a thread that is already running one. */
@@ -82,6 +76,11 @@ export interface RunRecord {
     worker?: string;
     /** Its latest attempt, starting at 1. */
     attempt?: number;
+    /**
+     * Scores left on the run by people or by online evaluation, through `POST /runs/:runId/feedback`
+     * or `Deployments.evaluate()`. A canary guard compares them between revisions as its quality signal.
+     */
+    feedback?: RunFeedback[];
 }
 /** Why a run got the revision it did. */
 export type RevisionReason = 'split' | 'thread' | 'requested';

package/dist/utils/base64.d.ts

@@ -0,0 +1,4 @@
+/** Base64 text as bytes, in a buffer of their own, so typed-array views of it are aligned. */
+export declare function decodeBase64(data: string): Uint8Array;
+/** Bytes as base64 text. */
+export declare function encodeBase64(bytes: Uint8Array): string;

package/dist/utils/base64.js

@@ -0,0 +1,21 @@
+const host = () => globalThis.Buffer;
+export function decodeBase64(data) {
+    const buffer = host();
+    if (buffer)
+        return new Uint8Array(buffer.from(data, 'base64'));
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+export function encodeBase64(bytes) {
+    const buffer = host();
+    if (buffer)
+        return buffer.from(bytes).toString('base64');
+    let binary = '';
+    for (let index = 0; index < bytes.length; index += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000));
+    }
+    return btoa(binary);
+}