nexus-ai-pro 2.1.0 → 2.2.0

package/dist/sqlite/store.js

@@ -21,6 +21,16 @@ export function sqliteStoreMigration(options = {}) {
         `CREATE INDEX IF NOT EXISTS "${name}_expiry" ON ${table} (expires_at) WHERE expires_at IS NOT NULL`,
     ];
 }
+export function sqliteStoreMigrations(options = {}) {
+    return [
+        {
+            component: `store:${options.table ?? DEFAULT_TABLE}`,
+            version: 1,
+            name: 'create the store table',
+            statements: sqliteStoreMigration(options),
+        },
+    ];
+}
 export class SqliteStore {
     options;
     client;
@@ -32,9 +42,9 @@ export class SqliteStore {
         this.table = quoteSqliteTable(options.table ?? DEFAULT_TABLE);
         this.now = options.now ?? (() => new Date());
     }
-    async migrate() {
-        for (const statement of sqliteStoreMigration(this.options))
-            await this.client.exec(statement);
+    async migrate(options = {}) {
+        const { applySqliteMigrations } = await import('./migrations.js');
+        return applySqliteMigrations(this.client, sqliteStoreMigrations(this.options), options);
     }
     async put(namespace, key, value, options = {}) {
         if (!key.trim())

package/dist/sqlite/vectors.d.ts

@@ -1,5 +1,7 @@
 import { type EmbeddingProvider, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, type VectorStore } from '../hallucination/retrieval.js';
+import type { MigrationResult, SchemaMigration } from '../utils/schema-migrations.js';
 import { type SqliteDatabaseLike, type SqliteLikeClient } from './client.js';
+import type { SqliteMigrateOptions } from './migrations.js';
 /** Options for the SQLite vector store. */
 export interface SqliteVectorStoreOptions {
     /** Width of every vector. Must match the embedding function's output. */
@@ -20,6 +22,10 @@ export interface SqliteVectorStoreOptions {
 export declare function sqliteVectorStoreMigration(options?: {
     table?: string;
 }): string;
+/** The versioned schema, which `migrate()` applies. Version 1 is the 2.0 table. */
+export declare function sqliteVectorStoreMigrations(options?: {
+    table?: string;
+}): SchemaMigration[];
 /**
  * Retrieval chunks in SQLite: one file, no server, the same contract as every other store.
  *
@@ -34,8 +40,11 @@ export declare class SqliteVectorStore implements VectorStore {
     private readonly table;
     private readonly embed;
     constructor(database: SqliteLikeClient | SqliteDatabaseLike, options: SqliteVectorStoreOptions);
-    /** Creates the table unless it exists. Never runs implicitly. */
-    migrate(): Promise<void>;
+    /**
+     * Applies this store's pending migrations, recorded in `nexus_schema_migrations`, each inside
+     * `BEGIN IMMEDIATE`. Never runs implicitly. Safe on a file an older release created.
+     */
+    migrate(options?: SqliteMigrateOptions): Promise<MigrationResult>;
     /** Adds chunks, or replaces those whose id exists, embedding those without a vector in one batch. */
     add(documents: VectorDocument[]): Promise<void>;
     /** The chunks most similar to a query, best first. */

package/dist/sqlite/vectors.js

@@ -5,6 +5,16 @@ export function sqliteVectorStoreMigration(options = {}) {
     const table = quoteSqliteTable(options.table ?? 'nexus_vectors');
     return `CREATE TABLE IF NOT EXISTS ${table} (id TEXT PRIMARY KEY, content TEXT NOT NULL, source TEXT, metadata TEXT, embedding BLOB NOT NULL)`;
 }
+export function sqliteVectorStoreMigrations(options = {}) {
+    return [
+        {
+            component: `vectors:${options.table ?? 'nexus_vectors'}`,
+            version: 1,
+            name: 'create the vectors table',
+            statements: [sqliteVectorStoreMigration(options)],
+        },
+    ];
+}
 export class SqliteVectorStore {
     options;
     client;
@@ -17,8 +27,9 @@ export class SqliteVectorStore {
         this.table = quoteSqliteTable(options.table ?? 'nexus_vectors');
         this.embed = options.embed ?? ((texts) => createHashEmbeddings(texts, options.dimensions));
     }
-    async migrate() {
-        await this.client.exec(sqliteVectorStoreMigration(this.options));
+    async migrate(options = {}) {
+        const { applySqliteMigrations } = await import('./migrations.js');
+        return applySqliteMigrations(this.client, sqliteVectorStoreMigrations(this.options), options);
     }
     async add(documents) {
         if (documents.length === 0)

package/dist/store/tenant.d.ts

@@ -0,0 +1,12 @@
+import type { Store } from '../types/store.js';
+/** The first namespace part under which every tenant's items live, so they never meet an application's own. */
+export declare const TENANT_NAMESPACE = "nexus:tenant";
+/**
+ * One tenant's view of a long-term store: every namespace it reads or writes is placed under
+ * `['nexus:tenant', tenantId]`, and every item it returns has that prefix taken off again. A search
+ * or a namespace listing cannot reach past it, so another tenant's items are not merely filtered out
+ * but never read. Works over any store — memory, Redis, Postgres, SQLite — with no schema change.
+ *
+ * A graph run given a `tenantId` sees its store through this view as `context.store`.
+ */
+export declare function tenantStore(store: Store, tenantId: string): Store;

package/dist/store/tenant.js

@@ -0,0 +1,29 @@
+import { assertTenantId } from '../utils/tenant.js';
+export const TENANT_NAMESPACE = 'nexus:tenant';
+export function tenantStore(store, tenantId) {
+    const root = [TENANT_NAMESPACE, assertTenantId(tenantId)];
+    const scope = (namespace) => [...root, ...namespace];
+    const unscope = (item) => ({ ...item, namespace: item.namespace.slice(root.length) });
+    return {
+        put(namespace, key, value, options) {
+            return store.put(scope(namespace), key, value, options);
+        },
+        async get(namespace, key) {
+            const item = await store.get(scope(namespace), key);
+            return item ? unscope(item) : undefined;
+        },
+        delete(namespace, key) {
+            return store.delete(scope(namespace), key);
+        },
+        async search(namespacePrefix, options) {
+            return (await store.search(scope(namespacePrefix), options)).map(unscope);
+        },
+        async listNamespaces(options = {}) {
+            const namespaces = await store.listNamespaces({
+                prefix: scope(options.prefix ?? []),
+                ...(options.limit === undefined ? {} : { limit: options.limit }),
+            });
+            return namespaces.map((namespace) => namespace.slice(root.length)).filter((namespace) => namespace.length > 0);
+        },
+    };
+}

package/dist/tenancy/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * One tenant model for every store.
+ *
+ * Each function returns one tenant's view of a shared store, implementing the same contract as the
+ * store itself, so a tenant's code takes a `TraceStore`, a `PromptStore`, or a `VectorStore` as it
+ * always did and cannot reach past its tenant. Names and keys are placed under the tenant's prefix
+ * (`tenant/<id>/`) and records carry `tenantId`, so the views work over the memory, Redis, Postgres,
+ * SQLite, and file stores alike, with no schema change. A tenant id is letters, digits, `_`, and `-`,
+ * so no tenant's prefix is the start of another's.
+ */
+import type { CacheAdapter } from '../cache/adapters.js';
+import type { VectorStore } from '../hallucination/retrieval.js';
+import type { AssetPutOptions, AssetSignOptions, AssetStore } from '../images/asset-support.js';
+import type { RollupStore } from '../tracing/rollups.js';
+import type { DatasetStore, ExperimentStore } from '../types/evaluate.js';
+import type { OperationStore } from '../types/operations.js';
+import type { PromptStore } from '../types/prompts.js';
+import type { Store } from '../types/store.js';
+import type { TraceStore } from '../types/tracing.js';
+export { TENANT_NAMESPACE, tenantStore } from '../store/tenant.js';
+export { assertTenantId, TenantIdError } from '../utils/tenant.js';
+/**
+ * One tenant's traces. Every run saved through it is stamped `metadata.tenantId`, the field rollups,
+ * the studio, and the Postgres tenant index read; `get()`, `query()`, and `tree()` return only runs so
+ * stamped, and feedback reaches only the tenant's own runs. `prune()` is left out, since it would
+ * remove every tenant's old runs.
+ */
+export declare function tenantTraceStore(store: TraceStore, tenantId: string): TraceStore;
+/**
+ * One tenant's operations. Records it creates carry `tenantId`, and their idempotency keys are
+ * placed under the tenant's prefix, so two tenants using the same key never collide. Reads, updates,
+ * deletes, recovery, and queue listings see only the tenant's records; `listQueued()` and `stats()`
+ * pass the tenant to the store as a filter, which Postgres and SQLite answer from an index.
+ */
+export declare function tenantOperationStore<TResult = unknown>(store: OperationStore<TResult>, tenantId: string): OperationStore<TResult>;
+/**
+ * One tenant's prompts. Every prompt name is placed under the tenant's prefix on the way in and
+ * taken off on the way out, so the tenant sees its own names and `listNames()` lists only them. A
+ * `ContextHub` given this store keeps the tenant's context bundles apart the same way.
+ */
+export declare function tenantPromptStore(store: PromptStore, tenantId: string): PromptStore;
+/** One tenant's datasets: names placed under the tenant's prefix, and `list()` showing only its own. */
+export declare function tenantDatasetStore(store: DatasetStore, tenantId: string): DatasetStore;
+/**
+ * One tenant's experiments. Ids, names, and dataset names are placed under the tenant's prefix, so
+ * `get()` of another tenant's experiment id finds nothing and `list()` returns only the tenant's.
+ */
+export declare function tenantExperimentStore(store: ExperimentStore, tenantId: string): ExperimentStore;
+/**
+ * One tenant's retrieval chunks. Each chunk's id is placed under the tenant's prefix and its metadata
+ * stamped `tenantId`, and every search adds `tenantId` to its filter, which every vector store applies
+ * natively. A search never ranks another tenant's chunks, and `delete()` reaches only the tenant's.
+ */
+export declare function tenantVectorStore(store: VectorStore, tenantId: string): VectorStore;
+/**
+ * One tenant's cache: every key placed under the tenant's prefix, so a tenant can never read what
+ * another cached. `clear()` is left out, since it would clear every tenant's entries.
+ */
+export declare function tenantCache<T = unknown>(cache: CacheAdapter<T>, tenantId: string): CacheAdapter<T>;
+/** An asset store with the tenant bound, so no call can name another. Returned by `tenantAssetStore()`. */
+export interface TenantAssetStore {
+    /** The tenant every call acts for. */
+    readonly tenantId: string;
+    /** Stores an asset for the tenant. */
+    put(input: Parameters<AssetStore['put']>[0], options: Omit<AssetPutOptions, 'tenantId'>): ReturnType<AssetStore['put']>;
+    /** Reads one of the tenant's assets with its bytes. */
+    get(assetId: string): ReturnType<AssetStore['get']>;
+    /** Describes one of the tenant's assets. */
+    stat(assetId: string): ReturnType<AssetStore['stat']>;
+    /** Deletes one of the tenant's assets. */
+    delete(assetId: string): ReturnType<AssetStore['delete']>;
+    /** Signs a URL for one of the tenant's assets. */
+    sign(assetId: string, options?: AssetSignOptions): ReturnType<AssetStore['sign']>;
+}
+/**
+ * One tenant's assets. Asset stores already treat another tenant's asset as missing; this binds the
+ * tenant once, so code handed the view cannot pass a different one.
+ */
+export declare function tenantAssetStore(store: AssetStore, tenantId: string): TenantAssetStore;
+/** One tenant's rollups: rows it adds are counted for the tenant, and queries read only the tenant's rows. */
+export declare function tenantRollupStore(store: RollupStore, tenantId: string): RollupStore;
+/** The stores `tenantScope()` can scope. Each is optional. */
+export interface TenantStores {
+    /** Long-term memory. */
+    store?: Store;
+    /** Traces. */
+    traces?: TraceStore;
+    /** Operation records. */
+    operations?: OperationStore<unknown>;
+    /** Prompt versions and labels, and the context hub's bundles. */
+    prompts?: PromptStore;
+    /** Datasets. */
+    datasets?: DatasetStore;
+    /** Experiments. */
+    experiments?: ExperimentStore;
+    /** Retrieval chunks. */
+    vectors?: VectorStore;
+    /** A cache. */
+    cache?: CacheAdapter<unknown>;
+    /** Dashboard rollups. */
+    rollups?: RollupStore;
+}
+/**
+ * Scopes every given store to one tenant at once, keeping each one's type, so a request handler
+ * builds its tenant's view in one line.
+ *
+ * ```ts
+ * const scoped = tenantScope(principal.tenantId, { store, traces, prompts, vectors });
+ * ```
+ */
+export declare function tenantScope<T extends TenantStores>(tenantId: string, stores: T): T & {
+    readonly tenantId: string;
+};

package/dist/tenancy/index.js

@@ -0,0 +1,233 @@
+import { tenantPrefix } from '../utils/tenant.js';
+import { tenantStore } from '../store/tenant.js';
+export { TENANT_NAMESPACE, tenantStore } from '../store/tenant.js';
+export { assertTenantId, TenantIdError } from '../utils/tenant.js';
+function names(tenantId) {
+    const prefix = tenantPrefix(tenantId);
+    return {
+        prefix,
+        in: (name) => `${prefix}${name}`,
+        owns: (name) => name.startsWith(prefix),
+        out: (name) => name.slice(prefix.length),
+    };
+}
+function stamped(metadata, tenantId) {
+    return metadata?.tenantId === tenantId;
+}
+export function tenantTraceStore(store, tenantId) {
+    tenantPrefix(tenantId);
+    const own = (run) => (run && stamped(run.metadata, tenantId) ? run : undefined);
+    const prune = (tree) => ({
+        ...tree,
+        children: tree.children.filter((child) => stamped(child.metadata, tenantId)).map(prune),
+    });
+    return {
+        save: (run) => store.save({ ...run, metadata: { ...run.metadata, tenantId } }),
+        get: async (runId) => own(await store.get(runId)),
+        query: (query = {}) => store.query({ ...query, metadata: { ...query.metadata, tenantId } }),
+        async tree(traceId) {
+            const tree = await store.tree(traceId);
+            return tree && stamped(tree.metadata, tenantId) ? prune(tree) : undefined;
+        },
+        async addFeedback(runId, feedback) {
+            const run = own(await store.get(runId));
+            if (!run)
+                return;
+            if (store.addFeedback)
+                await store.addFeedback(runId, feedback);
+            else
+                await store.save({ ...run, feedback: [...(run.feedback ?? []), feedback] });
+        },
+    };
+}
+export function tenantOperationStore(store, tenantId) {
+    const keys = names(tenantId);
+    const inward = (record) => ({
+        ...record,
+        tenantId,
+        ...(record.idempotencyKey ? { idempotencyKey: keys.in(record.idempotencyKey) } : {}),
+    });
+    const outward = (record) => {
+        if (!record || record.tenantId !== tenantId)
+            return undefined;
+        return record.idempotencyKey && keys.owns(record.idempotencyKey)
+            ? { ...record, idempotencyKey: keys.out(record.idempotencyKey) }
+            : record;
+    };
+    const own = (records) => records.map(outward).filter((record) => record !== undefined);
+    const filtered = (filter) => ({ ...filter, tenantId });
+    const view = {
+        create: (record) => store.create(inward(record)),
+        read: async (id) => outward(await store.read(id)),
+        async update(record, expectedSequence) {
+            if (record.tenantId !== undefined && record.tenantId !== tenantId)
+                return false;
+            if (!outward(await store.read(record.id)))
+                return false;
+            return store.update(inward(record), expectedSequence);
+        },
+    };
+    if (store.delete) {
+        const remove = store.delete.bind(store);
+        view.delete = async (id) => (outward(await store.read(id)) ? remove(id) : false);
+    }
+    if (store.claimExpired) {
+        const claim = store.claimExpired.bind(store);
+        view.claimExpired = async (now, limit) => own(await claim(now, limit));
+    }
+    if (store.findByIdempotencyKey) {
+        const find = store.findByIdempotencyKey.bind(store);
+        view.findByIdempotencyKey = async (key) => outward(await find(keys.in(key)));
+    }
+    if (store.list) {
+        const list = store.list.bind(store);
+        view.list = async () => own(await list());
+    }
+    if (store.listQueued) {
+        const listQueued = store.listQueued.bind(store);
+        view.listQueued = async (limit, filter) => own(await listQueued(limit, filtered(filter)));
+    }
+    if (store.stats) {
+        const stats = store.stats.bind(store);
+        view.stats = (now, filter) => stats(now, filtered(filter));
+    }
+    return view;
+}
+export function tenantPromptStore(store, tenantId) {
+    const scoped = names(tenantId);
+    const named = (value) => ({ ...value, name: scoped.in(value.name) });
+    const unnamed = (value) => value && scoped.owns(value.name) ? { ...value, name: scoped.out(value.name) } : undefined;
+    const all = (values) => values.map(unnamed).filter((value) => value !== undefined);
+    return {
+        saveVersion: (version) => store.saveVersion(named(version)),
+        getVersion: async (name, version) => unnamed(await store.getVersion(scoped.in(name), version)),
+        listVersions: async (name, options) => all(await store.listVersions(scoped.in(name), options)),
+        getLabel: async (name, label) => unnamed(await store.getLabel(scoped.in(name), label)),
+        listLabels: async (name) => all(await store.listLabels(scoped.in(name))),
+        setLabel: (label, expected) => store.setLabel(named(label), expected),
+        deleteLabel: (name, label) => store.deleteLabel(scoped.in(name), label),
+        appendHistory: (entry) => store.appendHistory(named(entry)),
+        listHistory: async (name, options) => all(await store.listHistory(scoped.in(name), options)),
+        listNames: async () => (await store.listNames()).filter(scoped.owns).map(scoped.out).sort(),
+    };
+}
+export function tenantDatasetStore(store, tenantId) {
+    const scoped = names(tenantId);
+    return {
+        save: (dataset) => store.save({ ...dataset, name: scoped.in(dataset.name) }),
+        async get(name, version) {
+            const dataset = await store.get(scoped.in(name), version);
+            return dataset ? { ...dataset, name: name } : undefined;
+        },
+        async list() {
+            return (await store.list())
+                .filter((entry) => scoped.owns(entry.name))
+                .map((entry) => ({ ...entry, name: scoped.out(entry.name) }));
+        },
+    };
+}
+export function tenantExperimentStore(store, tenantId) {
+    const scoped = names(tenantId);
+    const inward = (experiment) => ({
+        ...experiment,
+        id: scoped.in(experiment.id),
+        name: scoped.in(experiment.name),
+        dataset: { ...experiment.dataset, name: scoped.in(experiment.dataset.name) },
+    });
+    const outward = (experiment) => experiment && scoped.owns(experiment.id)
+        ? {
+            ...experiment,
+            id: scoped.out(experiment.id),
+            name: scoped.out(experiment.name),
+            dataset: { ...experiment.dataset, name: scoped.out(experiment.dataset.name) },
+        }
+        : undefined;
+    return {
+        save: (experiment) => store.save(inward(experiment)),
+        get: async (id) => outward(await store.get(scoped.in(id))),
+        async list(filter = {}) {
+            const experiments = await store.list({
+                ...filter,
+                ...(filter.name === undefined ? {} : { name: scoped.in(filter.name) }),
+                ...(filter.dataset === undefined ? {} : { dataset: scoped.in(filter.dataset) }),
+            });
+            return experiments.map(outward).filter((experiment) => experiment !== undefined);
+        },
+    };
+}
+export function tenantVectorStore(store, tenantId) {
+    const scoped = names(tenantId);
+    const outward = (results) => results
+        .filter((result) => scoped.owns(result.id) && stamped(result.metadata, tenantId))
+        .map((result) => {
+        const { tenantId: _owner, ...metadata } = result.metadata ?? {};
+        return { ...result, id: scoped.out(result.id), metadata };
+    });
+    const filtered = (options = {}) => ({
+        ...options,
+        filter: { ...options.filter, tenantId },
+    });
+    return {
+        add: (documents) => store.add(documents.map((document) => ({
+            ...document,
+            id: scoped.in(document.id),
+            metadata: { ...document.metadata, tenantId },
+        }))),
+        search: async (query, options) => outward(await store.search(query, filtered(options))),
+        searchVector: async (vector, options) => outward(await store.searchVector(vector, filtered(options))),
+        delete: (ids) => store.delete(ids.map(scoped.in)),
+    };
+}
+export function tenantCache(cache, tenantId) {
+    const scoped = names(tenantId);
+    const view = {
+        get: (key) => cache.get(scoped.in(key)),
+        set: (key, value, ttlSeconds) => cache.set(scoped.in(key), value, ttlSeconds),
+    };
+    if (cache.delete) {
+        const remove = cache.delete.bind(cache);
+        view.delete = (key) => remove(scoped.in(key));
+    }
+    return view;
+}
+export function tenantAssetStore(store, tenantId) {
+    tenantPrefix(tenantId);
+    return {
+        tenantId,
+        put: (input, options) => store.put(input, { ...options, tenantId }),
+        get: (assetId) => store.get(assetId, tenantId),
+        stat: (assetId) => store.stat(assetId, tenantId),
+        delete: (assetId) => store.delete(assetId, tenantId),
+        sign: (assetId, options) => store.sign(assetId, tenantId, options),
+    };
+}
+export function tenantRollupStore(store, tenantId) {
+    tenantPrefix(tenantId);
+    return {
+        add: (key, totals) => store.add({ ...key, tenant: tenantId }, totals),
+        query: (query = {}) => store.query({ ...query, tenant: tenantId }),
+    };
+}
+export function tenantScope(tenantId, stores) {
+    tenantPrefix(tenantId);
+    const scoped = {};
+    if (stores.store)
+        scoped.store = tenantStore(stores.store, tenantId);
+    if (stores.traces)
+        scoped.traces = tenantTraceStore(stores.traces, tenantId);
+    if (stores.operations)
+        scoped.operations = tenantOperationStore(stores.operations, tenantId);
+    if (stores.prompts)
+        scoped.prompts = tenantPromptStore(stores.prompts, tenantId);
+    if (stores.datasets)
+        scoped.datasets = tenantDatasetStore(stores.datasets, tenantId);
+    if (stores.experiments)
+        scoped.experiments = tenantExperimentStore(stores.experiments, tenantId);
+    if (stores.vectors)
+        scoped.vectors = tenantVectorStore(stores.vectors, tenantId);
+    if (stores.cache)
+        scoped.cache = tenantCache(stores.cache, tenantId);
+    if (stores.rollups)
+        scoped.rollups = tenantRollupStore(stores.rollups, tenantId);
+    return { ...stores, ...scoped, tenantId };
+}

package/dist/tracing/instrument.js

@@ -140,6 +140,8 @@ export function traceModelClient(client, tracer, options = {}) {
                         model: response.meta?.modelUsed,
                         finishReason: response.finishReason,
                         ...(request.metadata?.prompt === undefined ? {} : { prompt: request.metadata.prompt }),
+                        ...(response.meta?.cache ? { cache: response.meta.cache } : {}),
+                        ...(request.tenantId ? { tenantId: request.tenantId } : {}),
                     },
                 });
                 return response;

package/dist/types/config.d.ts

@@ -8,6 +8,7 @@ import type { TelephonyConfig } from './telephony.js';
 import type { AliasMetadata, InputModality, ModelCapabilities, ModelStatus, OutputModality, RoutingModelPreference } from './providers.js';
 import type { CapabilityConfig } from './capabilities.js';
 import type { LifecycleConfig, OperationFamily } from './lifecycle.js';
+import type { CompletionRequest } from './messages.js';
 import type { PipelineConfig } from '../pipeline/types.js';
 import type { CacheAdapter } from '../cache/adapters.js';
 import type { SemanticCacheOptions } from '../cache/semantic-cache.js';
@@ -228,6 +229,24 @@ export interface CacheConfig {
     strategy?: 'exact' | 'semantic' | 'hybrid';
     adapter?: CacheAdapter;
     semantic?: SemanticCacheOptions;
+    /**
+     * What cached responses are kept apart by, fixed or per request. A response is reused only within
+     * its namespace, so a new model revision or context version starts from an empty cache, and no
+     * tenant is answered from another's. The tenant defaults to the request's `tenantId`. Without it,
+     * exact-cache keys are what they were before 2.2; semantic matches are always kept to one tenant.
+     */
+    namespace?: CacheNamespace | ((request: CompletionRequest) => CacheNamespace);
+}
+/** What a cached response is kept apart by. Each field narrows the namespace. */
+export interface CacheNamespace {
+    /** The tenant. Defaults to the request's `tenantId`. */
+    tenant?: string;
+    /** The deployment environment, such as `staging`. */
+    environment?: string;
+    /** A revision of the model or its prompts; changing it retires every earlier entry. */
+    modelRevision?: string;
+    /** The version of the context an answer depends on, such as a context hub bundle's. */
+    contextVersion?: string;
 }
 /** A response format applied to every request that does not set its own. */
 export interface ResponseFormatConfig {
@@ -244,8 +263,11 @@ export interface RateLimitConfig {
     maxRequests: number;
     /** Window length in milliseconds. */
     windowMs: number;
-    /** What a budget is counted per: each user, each model, or everything together. */
-    key?: 'userId' | 'model' | 'global';
+    /**
+     * What a budget is counted per: each user, each model, each tenant (the request's `tenantId`), or
+     * everything together. Per tenant, one tenant cannot spend another's share of a shared client.
+     */
+    key?: 'userId' | 'model' | 'tenantId' | 'global';
     /**
      * How calls are counted. `fixed-window` (the default) counts per window, so a burst at the end of
      * one window and another at the start of the next can pass twice the limit in a moment. `gcra` is

package/dist/types/graph.d.ts

@@ -372,6 +372,8 @@ export interface NodeContext<S extends ChannelSchema> {
     readonly step: number;
     /** The thread this run belongs to. */
     readonly threadId: string;
+    /** The tenant the run is for, when it has one. */
+    readonly tenantId?: string;
     /** 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. */
@@ -395,7 +397,8 @@ export interface NodeContext<S extends ChannelSchema> {
      * Long-term memory, present when the graph was compiled with a store.
      *
      * State is this thread's; the store is everything else the application remembers — across threads,
-     * users, and runs.
+     * users, and runs. In a run with a `tenantId`, it is that tenant's view of the store, and nothing
+     * another tenant stored can be read through it.
      */
     readonly store?: Store;
     /** Reports progress without writing to state. Refreshes an idle timeout. */
@@ -567,6 +570,13 @@ export interface GraphRunOptions {
     signal?: AbortSignal;
     /** Application data recorded on every checkpoint of the run. */
     metadata?: Record<string, unknown>;
+    /**
+     * The tenant the run is for. It is recorded on every checkpoint as `metadata.tenantId`, nodes read
+     * it as `context.tenantId`, and `context.store` becomes the tenant's own view of the store. A thread
+     * another tenant owns is not found: resuming, continuing, forking, or editing it with a different
+     * `tenantId` is refused before anything runs. A run without one carries on the thread's tenant.
+     */
+    tenantId?: string;
     /** Overrides the compiled `maxConcurrency` for this run. */
     maxConcurrency?: number;
     /** Breakpoints for this run only, replacing the compiled ones. */

package/dist/types/messages.d.ts

@@ -257,6 +257,11 @@ export interface CompletionRequest {
     reasoning?: ReasoningConfig;
     /** Provider-side prompt caching controls. */
     cache?: PromptCacheConfig;
+    /**
+     * Skips this client's response cache for this request: `bypass` neither reads nor writes it, and
+     * `refresh` skips the read and stores the fresh answer. Either is recorded as a `bypass` outcome.
+     */
+    responseCache?: 'bypass' | 'refresh';
     /**
      * Overrides the configured capability policy for this request. `'strict'` fails on an option the
      * model cannot honor, `'warn'` drops it and records a warning, and `'off'` sends the request

package/dist/types/operations.d.ts

@@ -173,6 +173,8 @@ export interface OperationRecord<TResult = unknown> {
     idempotencyKey?: string;
     /** Family and operation, such as `image.generate`, for filtering and metrics. */
     kind?: string;
+    /** The tenant it belongs to. A tenant-scoped store reads and lists only its own. */
+    tenantId?: string;
     /** Trace propagation headers, carried to the worker that runs it. */
     traceContext?: Record<string, string>;
     /** Application data. Must be serializable. */
@@ -217,6 +219,8 @@ export interface OperationStore<TResult = unknown> {
 export interface OperationStoreFilter {
     /** Only records whose `kind` starts with this, such as `assistant:` for the agent server's runs. */
     kindPrefix?: string;
+    /** Only records of this tenant. Postgres and SQLite read it through an index on queued work. */
+    tenantId?: string;
 }
 /** What an operation store holds, counted: the numbers a queue dashboard and an autoscaler read. */
 export interface OperationStoreStats {
@@ -305,6 +309,8 @@ export interface OperationSubmitOptions {
     id?: string;
     /** Family and operation, such as `image.generate`. */
     kind?: string;
+    /** The tenant it belongs to, recorded on the operation. */
+    tenantId?: string;
     /** Replays the operation already accepted under this key instead of starting another. */
     idempotencyKey?: string;
     /** Overrides the runner's attempt budget for this operation. */

package/dist/types/response.d.ts

@@ -72,6 +72,8 @@ export interface ResponseMeta {
     capabilityWarnings?: CapabilityWarning[];
     /** True when the response came from the response cache and no provider was called. */
     cacheHit: boolean;
+    /** What the response cache did for this request, and why. Present when the cache is enabled. */
+    cache?: CacheOutcome;
     /** Guardrails and techniques applied, such as redaction, trimming, or a retry. */
     guardrailsApplied: string[];
     /** Why the router chose the provider, and how many fallbacks were available. */
@@ -164,3 +166,21 @@ export interface NexusStream extends AsyncIterable<StreamChunk> {
     /** Stops the stream and the provider request behind it. */
     abort(): void;
 }
+/**
+ * What the response cache did for one request: `hit` (answered from it), `miss` (looked, found
+ * nothing), `stale` (found an entry that had expired), `bypass` (the request skipped the lookup), or
+ * `error` (the cache failed, and the request went to the provider as on a miss). Recorded on
+ * `response.meta.cache` and on the request's trace.
+ */
+export interface CacheOutcome {
+    /** What happened. */
+    outcome: 'hit' | 'miss' | 'stale' | 'bypass' | 'error';
+    /** Which layer answered or was asked last: the exact cache or the semantic one. */
+    layer?: 'exact' | 'semantic';
+    /** Why, in a few words, such as `no entry for this request` or the cache's error message. */
+    reason: string;
+    /** The namespace the lookup ran in, when one applies. */
+    namespace?: string;
+    /** Set when storing the response failed; the response was still returned. */
+    writeError?: string;
+}