nexus-ai-pro 1.22.0 → 1.23.0

package/API_STABILITY.md

@@ -456,6 +456,18 @@ with nexus-ai-pro and declares the core versions it works with as a peer depende
 - The access rules are a guarantee: loopback binding by default, a token on every request, the token
   in a header for every change, and loopback hosts only unless others are allowed.
 
+## Team platform stage (1.23.0)
+
+The context hub (`nexus-ai-pro/context-hub`), insights (`nexus-ai-pro/insights`), and the studio's
+accounts are experimental in production readiness. Their contracts follow the 1.x rules.
+
+- A bundle's content version covers its name, description, prompts, instructions, tools, skills, and
+  config, and is stable across 1.x, so the same content is the same version in every release.
+- The export format is `nexus-context-bundle`, format version 1; a later release reads it.
+- A cached evaluation output is keyed by the fingerprint, the example's id and inputs, and the
+  repetition. The key's derivation is stable across 1.x, so a cache survives an upgrade.
+- The studio's roles keep their order and meaning; new actions are assigned to an existing role.
+
 ## Retrieval breadth stage (1.22.0)
 
 The loaders (`nexus-ai-pro/loaders/*`), the Redis, Pinecone, Weaviate, Chroma, and SQLite vector

package/CHANGELOG.md

@@ -4,6 +4,40 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.23.0] - 2026-09-30
+
+The team engineering platform. The studio becomes something a team shares, and it starts finding
+problems on its own.
+
+### Added
+
+- **A shared studio.** Accounts through an authenticator — personal links, identity headers from a
+  signing-in proxy, or bearer tokens verified by your function, such as OIDC — with four roles
+  (viewer, reviewer, editor, admin), an audit log of every change and every refused attempt, comments
+  on runs, review items, proposals, threads, and bundles, per-person page tokens for changes, and
+  `Secure` cookies behind HTTPS. Local, token-only use stays the default. The CLI gains `--users` and
+  `--journal`, and a config module may export `options`.
+- **The context hub** on `nexus-ai-pro/context-hub`: prompts, instructions, tool sets, skills, and
+  settings versioned together as bundles, committed by content, labelled, promoted through evaluation
+  gates, diffed, rolled back, and exported with their prompts to move between projects. Bundles live in
+  any prompt store. The studio shows them.
+- **Insights** on `nexus-ai-pro/insights`: failing and slow runs clustered by error, trajectory, or
+  meaning; regressions between two time windows; and, opt-in, a proposed fix — a candidate prompt or
+  bundle version — evaluated against the dataset before it waits in the studio's inbox for a person
+  to promote, with an optional pull request through an injected client.
+- **Evaluation caching**: `evaluate()` reuses a target's outputs when the example and the target's
+  fingerprint are unchanged, so a comparison re-runs only what changed; evaluators always run again.
+  `MemoryEvaluationCache`, `FileEvaluationCache`, and `fingerprintOf()` on `nexus-ai-pro/evaluate`;
+  `evaluatePrompt()` fingerprints the prompt version itself.
+
+### Changed
+
+- The guides are rewritten for readability: each says what its feature is for before its options,
+  options and fields are in tables, and long sentences are split. Every export is still explained.
+- `nexus-ai-pro-studio` requires nexus-ai-pro 1.23 or newer.
+- The studio's development type paths map each entry point to the file it publishes, so studio tests
+  exercise what the package ships.
+
 ## [1.22.0] - 2026-09-29
 
 Retrieval and integration breadth. Getting documents in, finding the right ones, and reaching the
@@ -1118,7 +1152,8 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.22.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.23.0...HEAD
+[1.23.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.22.0...v1.23.0
 [1.22.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.21.0...v1.22.0
 [1.21.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.20.0...v1.21.0
 [1.20.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.19.0...v1.20.0

package/README.md

@@ -1,8 +1,9 @@
 # nexus-ai-pro
 
-The typed AI framework for TypeScript. One API for provider routing and failover, agent graphs that
-run branches in parallel and survive a restart, durable background operations, guardrails, cost
-control, images, voice, and evals.
+The typed AI framework for TypeScript. One API for provider routing and failover, agent graphs and
+workflows that run branches in parallel and survive a restart, retrieval over any vector store, MCP,
+durable background operations, guardrails, cost control, images, voice, and evals — with a studio a
+team can share.
 
 Import the whole runtime, or one piece: every capability has its own entry point with a size budget
 CI enforces, and [the packaging guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md) publishes what each one costs. A graph-only application loads 49 KB
@@ -90,6 +91,14 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
 - embed text through the same routing, caching, batching, budget, retry, and metrics as a completion
 - run long operations that survive a restart, with leases, retries, dead-lettering, and signed webhooks
 - build stateful graphs with cycles, fan-out, subgraphs, human approval, and resumable checkpoints
+- make ordinary async functions durable step by step, and recover a crashed run at the step it died on
+- load files, web pages, sitemaps, and Git repositories into retrieval, over memory, Postgres, SQLite,
+  Redis, Qdrant, Pinecone, Weaviate, or Chroma
+- retrieve with hybrid keyword and vector search, reranking, and diversity, and measure it with evals
+- reach tools from many MCP servers under one configuration, with allowlists and credentials from the
+  environment
+- version prompts, instructions, tools, and skills together, and promote them through evaluation gates
+- find failing and slow runs, detect regressions, and review evaluated fix proposals in a shared studio
 - trip routing away from a failing provider, and share one rate-limit budget across workers
 - reach the providers' half-price asynchronous batch tier behind one operation handle
 - persist generated media to disk or S3 with tenant isolation, retention, and checksums
@@ -112,6 +121,8 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [MCP](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/mcp.md) | Borrowing tools from MCP servers, a registry of many, and serving your own |
 | [Traces](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/tracing.md) | Run trees, queries, feedback, comparison, and alerts |
 | [Evaluation](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/evaluation.md) | Datasets, evaluators, experiments, comparisons with a verdict, review queues, LLM judges |
+| [Context hub](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/context-hub.md) | Prompts, instructions, tools, and skills versioned together, promoted through gates, and moved between projects |
+| [Insights](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/insights.md) | Failing and slow runs clustered, regressions between time windows, and evaluated fix proposals |
 | [Prompts](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/prompts.md) | Typed templates, content versions, gated promotion, rollback, A/B splits, serving through outages |
 | [Postgres](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/postgres.md) | One adapter family for operations, memory, traces, evaluation, circuits, and prompts |
 | [SQLite](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/sqlite.md) | Durable operations, checkpoints, and memory on one machine, over any SQLite driver |
@@ -179,10 +190,11 @@ interface, or enum, has no doc comment, and `npm run docs:guides` fails when a g
 every export of the entry points it covers, or its generated reference is stale. Both hold at 100%;
 `--list` names what is missing, and `npm run docs:update` regenerates the references.
 
-Real provider conformance is opt-in:
+Real provider conformance, and the vector store contract against real servers, are opt-in:
 
 ```bash
 npm run test:conformance:real
+npm run test:vectors:live
 ```
 
 ## Roadmap
@@ -201,11 +213,16 @@ Shipped so far:
 - record and replay of provider traffic;
 - prompt versioning: typed templates, content versions, gated promotion, and serving through outages;
 - a self-hosted agent server, and a local studio as a separate package;
-- per-entry-point size budgets.
-
-Next: durable functional workflows and step-level recovery, then retrieval and integration breadth,
-a shared team studio, and self-managed deployment at scale, before 2.0.0 consolidates. The image
-family leaves experimental once recorded live conformance passes on all three backends.
+- per-entry-point size budgets;
+- vector stores behind one contract, and deprecation warnings at run time;
+- durable functional workflows, step-level recovery in the server, SQLite persistence, and diagrams
+  as images;
+- document loaders, five more vector stores, hybrid retrieval with reranking, and an MCP registry;
+- a shared studio with accounts, roles, an audit log, and comments; a context hub; insights with
+  evaluated fix proposals; and evaluation caching.
+
+Next: self-managed deployment at scale, before 2.0.0 consolidates. The image family leaves experimental once recorded live
+conformance passes on all three backends.
 
 ## Before Production
 

package/dist/context-hub/diff.d.ts

@@ -0,0 +1,32 @@
+import { type PromptLineChange } from '../prompts/diff.js';
+import type { ContextBundle } from './hub.js';
+/** One entry that differs between two bundle versions. */
+export interface ContextChange {
+    /** The part of the bundle. */
+    section: 'description' | 'prompts' | 'instructions' | 'tools' | 'skills' | 'config';
+    /** The entry within it: a prompt role, an instruction or skill name, a tool name, or a config key. */
+    key: string;
+    /** Whether the entry was added, removed, or changed. */
+    change: 'added' | 'removed' | 'changed';
+    /** Line by line, for text: an instruction, a skill's instructions, or the description. */
+    lines?: PromptLineChange[];
+    /** The entry before, for anything that is not text. */
+    before?: unknown;
+    /** The entry after, for anything that is not text. */
+    after?: unknown;
+}
+/** What changed between two versions of a bundle. */
+export interface ContextDiff {
+    /** The bundle. */
+    name: string;
+    /** The earlier version. */
+    from: string;
+    /** The later version. */
+    to: string;
+    /** Every entry that differs, section by section. */
+    changes: ContextChange[];
+}
+/** Compares two versions of a bundle, entry by entry, with line diffs for text. */
+export declare function diffContexts(from: ContextBundle, to: ContextBundle): ContextDiff;
+/** A diff as text, one line per change and `+`/`-` lines for text, for a terminal or a pull request. */
+export declare function formatContextDiff(diff: ContextDiff): string;

package/dist/context-hub/diff.js

@@ -0,0 +1,64 @@
+import { diffLines } from '../prompts/diff.js';
+import { canonicalJson } from '../prompts/version.js';
+export function diffContexts(from, to) {
+    const changes = [];
+    if ((from.description ?? '') !== (to.description ?? '')) {
+        changes.push({
+            section: 'description',
+            key: 'description',
+            change: from.description === undefined ? 'added' : to.description === undefined ? 'removed' : 'changed',
+            lines: diffLines(from.description ?? '', to.description ?? ''),
+        });
+    }
+    compare(changes, 'prompts', from.prompts, to.prompts);
+    compare(changes, 'instructions', from.instructions, to.instructions, (value) => value);
+    compare(changes, 'tools', Object.fromEntries((from.tools ?? []).map((tool) => [tool.name, tool])), Object.fromEntries((to.tools ?? []).map((tool) => [tool.name, tool])));
+    compare(changes, 'skills', from.skills, to.skills, (value) => {
+        const skill = value;
+        return `${skill.description}\n\n${skill.instructions}${Object.entries(skill.resources ?? {})
+            .map(([name, text]) => `\n\n[${name}]\n${text}`)
+            .join('')}`;
+    });
+    compare(changes, 'config', from.config, to.config);
+    return { name: to.name, from: from.version, to: to.version, changes };
+}
+export function formatContextDiff(diff) {
+    const lines = [`${diff.name}: ${diff.from} -> ${diff.to}`];
+    if (diff.changes.length === 0)
+        lines.push('  no changes');
+    for (const change of diff.changes) {
+        lines.push(`  ${change.change} ${change.section}.${change.key}`);
+        for (const line of change.lines ?? []) {
+            if (line.op !== '=')
+                lines.push(`    ${line.op} ${line.text}`);
+        }
+        if (!change.lines && change.change === 'changed') {
+            lines.push(`    - ${canonicalJson(change.before)}`, `    + ${canonicalJson(change.after)}`);
+        }
+    }
+    return lines.join('\n');
+}
+function compare(changes, section, before, after, asText) {
+    const keys = [...new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})])].sort();
+    for (const key of keys) {
+        const was = before?.[key];
+        const is = after?.[key];
+        if (was !== undefined && is !== undefined && canonicalJson(was) === canonicalJson(is))
+            continue;
+        const change = was === undefined ? 'added' : is === undefined ? 'removed' : 'changed';
+        changes.push(asText
+            ? {
+                section,
+                key,
+                change,
+                lines: diffLines(was === undefined ? '' : asText(was), is === undefined ? '' : asText(is)),
+            }
+            : {
+                section,
+                key,
+                change,
+                ...(was === undefined ? {} : { before: was }),
+                ...(is === undefined ? {} : { after: is }),
+            });
+    }
+}

package/dist/context-hub/hub.d.ts

@@ -0,0 +1,268 @@
+import type { GateResult } from '../prompts/errors.js';
+import type { PromptRegistry } from '../prompts/registry.js';
+import type { PromptHistoryEntry, PromptLabel, PromptStore, PromptVersion, RenderedPrompt, RenderOptions } from '../types/prompts.js';
+import { type ContextDiff } from './diff.js';
+/** A prompt a bundle uses, pinned to one content version of the prompt registry. */
+export interface ContextPromptPin {
+    /** The prompt's name in the registry. */
+    name: string;
+    /** Its content version, such as `p3f9a1c02b7de`. */
+    version: string;
+}
+/** A tool a bundle offers: its name, description, and argument schema. The implementation stays in code. */
+export interface ContextTool {
+    /** The tool's name, as the model sees it. */
+    name: string;
+    /** What the tool does, for the model. */
+    description?: string;
+    /** JSON Schema for its arguments. */
+    parameters?: Record<string, unknown>;
+}
+/** A skill: instructions for one kind of task, with the reference material it needs. */
+export interface ContextSkill {
+    /** When the skill applies, so an agent or a router can choose it. */
+    description: string;
+    /** How to do the task. */
+    instructions: string;
+    /** Reference material by name, such as a style guide or a schema. */
+    resources?: Record<string, string>;
+}
+/**
+ * Everything an agent runs with, versioned together: pinned prompts, named instructions, tool
+ * definitions, skills, and configuration. A change to any part is a new version of the whole.
+ */
+export interface ContextBundleDefinition {
+    /** The bundle's name, such as `support-agent`. */
+    name: string;
+    /** What the bundle is for. */
+    description?: string;
+    /** Prompts by role, such as `{ answer: { name: 'support-answer', version: 'p…' } }`. */
+    prompts?: Record<string, ContextPromptPin>;
+    /** Named instructions, such as a system policy or a tone guide. */
+    instructions?: Record<string, string>;
+    /** The tools the agent is offered. */
+    tools?: ContextTool[];
+    /** Skills by name. */
+    skills?: Record<string, ContextSkill>;
+    /** Settings the application reads, such as a model or a temperature. */
+    config?: Record<string, unknown>;
+    /** Application data. Not part of the version, so describing a bundle differently does not change it. */
+    metadata?: Record<string, unknown>;
+}
+/** A committed bundle version. */
+export interface ContextBundle extends ContextBundleDefinition {
+    /** Its content version: `c` and 12 hex digits of a SHA-256 over everything but `metadata`. */
+    version: string;
+    /** ISO-8601 time it was committed. */
+    createdAt: string;
+    /** Why it changed, from the commit. */
+    message?: string;
+    /** Who committed it. */
+    author?: string;
+    /** The version that was newest before it. */
+    parent?: string;
+}
+/** Which bundle version is being used, as experiments and traces record it. */
+export interface ContextReference {
+    /** The bundle's name. */
+    name: string;
+    /** Its content version. */
+    version: string;
+    /** The label it was resolved through, when it was. */
+    label?: string;
+}
+/** A label pointing at a bundle version. The same shape as a prompt label. */
+export type ContextLabel = PromptLabel;
+/** One recorded change to a bundle. The same shape as a prompt history entry. */
+export type ContextHistoryEntry = PromptHistoryEntry;
+/** What a context promotion gate is asked to judge. */
+export interface ContextPromotionContext {
+    /** The bundle. */
+    name: string;
+    /** The version being promoted. */
+    bundle: ContextBundle;
+    /** The label it is being promoted to. */
+    to: string;
+    /** The label it is being promoted from, when the promotion names one. */
+    from?: string;
+    /** The version `to` serves now, if any. */
+    current?: ContextBundle;
+    /** The hub, for gates that look things up. */
+    hub: ContextHub;
+}
+/** Decides whether a bundle version may be promoted to a label. */
+export type ContextPromotionGate = (context: ContextPromotionContext) => Promise<GateResult> | GateResult;
+/** The outcome of a promotion. */
+export interface ContextPromotionResult {
+    /** The label after the promotion. */
+    label: ContextLabel;
+    /** Every gate's verdict. */
+    results: GateResult[];
+    /** False when the label already served the version, so nothing moved. */
+    changed: boolean;
+}
+/** A bundle with the prompts it pins, as one document that moves between projects. */
+export interface ContextBundleExport {
+    /** Always `nexus-context-bundle`. */
+    format: 'nexus-context-bundle';
+    /** The export format's version. */
+    formatVersion: 1;
+    /** The bundle version. */
+    bundle: ContextBundle;
+    /** Every pinned prompt version, when the hub has a prompt registry. */
+    prompts: PromptVersion[];
+}
+/** Options for a `ContextHub`. */
+export interface ContextHubOptions {
+    /**
+     * Where bundle versions, labels, and history live: any prompt store — memory, files, Redis, or
+     * Postgres — given to the hub alone. Defaults to a `MemoryPromptStore`.
+     */
+    store?: PromptStore;
+    /** The prompt registry pinned prompts come from. Commits check each pin exists; exports carry them. */
+    prompts?: PromptRegistry;
+    /** Gates run before a promotion, by the label promoted to. */
+    gates?: Record<string, readonly ContextPromotionGate[]>;
+    /** Called after every recorded change. */
+    onChange?: (entry: ContextHistoryEntry) => void | Promise<void>;
+    /** Replaces the system clock, for tests. */
+    now?: () => Date;
+}
+/** Base class for context hub errors, each with a stable `code`. */
+export declare class ContextHubError extends Error {
+    /** Stable code, such as `CONTEXT_NOT_FOUND`. */
+    readonly code: string;
+    constructor(message: string, 
+    /** Stable code, such as `CONTEXT_NOT_FOUND`. */
+    code: string);
+}
+/** Raised for a bundle, version, or label that does not exist. */
+export declare class ContextNotFoundError extends ContextHubError {
+    /** The bundle. */
+    readonly bundle: string;
+    /** The version or label asked for. */
+    readonly ref: string;
+    constructor(
+    /** The bundle. */
+    bundle: string, 
+    /** The version or label asked for. */
+    ref: string);
+}
+/** Raised when a label moved while it was being changed. */
+export declare class ContextConflictError extends ContextHubError {
+    constructor(bundle: string, label: string);
+}
+/** Raised when a gate refuses a promotion. `results` holds every gate's verdict. */
+export declare class ContextPromotionError extends ContextHubError {
+    /** Every gate's verdict. */
+    readonly results: GateResult[];
+    constructor(bundle: string, to: string, 
+    /** Every gate's verdict. */
+    results: GateResult[]);
+}
+/** Raised when a bundle definition, a pin, or an import is invalid. */
+export declare class ContextDefinitionError extends ContextHubError {
+    constructor(message: string);
+}
+/**
+ * The content version of a bundle: `c` and the first 12 hex digits of a SHA-256 over its name,
+ * description, prompts, instructions, tools, skills, and configuration. Metadata is left out.
+ */
+export declare function contextVersion(definition: ContextBundleDefinition): Promise<string>;
+/**
+ * Versioned context bundles: prompts, instructions, tool sets, and skills versioned together,
+ * labelled, promoted through gates, diffed, rolled back, and exported to move between projects.
+ *
+ * It works as the prompt registry does — `commit()` stores content under its version, so committing
+ * unchanged content is a no-op; labels point at versions; every change is recorded — and it keeps its
+ * state in a prompt store, so every adapter the prompt family has serves bundles too.
+ */
+export declare class ContextHub {
+    private readonly options;
+    /** Where versions, labels, and history live. */
+    readonly store: PromptStore;
+    private readonly now;
+    constructor(options?: ContextHubOptions);
+    /**
+     * Commits a bundle and returns its version. Unchanged content returns the existing version and
+     * records nothing; `label` points labels at the version either way. With a prompt registry, every
+     * pinned prompt version must exist in it.
+     */
+    commit(definition: ContextBundleDefinition, options?: {
+        message?: string;
+        author?: string;
+        label?: string | readonly string[];
+    }): Promise<ContextBundle>;
+    /** A version by content version, label, or `latest`, the default. Throws `ContextNotFoundError` when there is none. */
+    get(name: string, ref?: string): Promise<ContextBundle>;
+    /** A version with the reference experiments and traces record for it. */
+    resolve(name: string, ref?: string): Promise<{
+        bundle: ContextBundle;
+        reference: ContextReference;
+    }>;
+    /**
+     * Renders the prompt a bundle pins for a role, through the prompt registry, recording the bundle in
+     * the request's `metadata.context` beside the prompt's own reference.
+     */
+    renderPrompt(bundle: ContextBundle, role: string, variables?: Record<string, unknown>, options?: RenderOptions): Promise<RenderedPrompt>;
+    /** Points a label at a version, without gates. Throws `ContextConflictError` if the label moved meanwhile. */
+    label(name: string, label: string, ref: string, options?: {
+        by?: string;
+        note?: string;
+    }): Promise<ContextLabel>;
+    /** Removes a label. Resolves false when there was none. */
+    unlabel(name: string, label: string, options?: {
+        by?: string;
+        note?: string;
+    }): Promise<boolean>;
+    /**
+     * Moves `to` to a version — named directly, or whatever `from` serves — once every gate for `to`
+     * allows it. Throws `ContextPromotionError` when a gate refuses, unless `force` is set, in which case
+     * the refusals are still reported and recorded in the note.
+     */
+    promote(name: string, options: {
+        to: string;
+        from?: string;
+        version?: string;
+        by?: string;
+        note?: string;
+        force?: boolean;
+    }): Promise<ContextPromotionResult>;
+    /** Moves a label back to where it pointed before its last change. */
+    rollback(name: string, label: string, options?: {
+        by?: string;
+        note?: string;
+    }): Promise<ContextLabel>;
+    /** A bundle's changes, newest first, optionally for one label. */
+    history(name: string, options?: {
+        label?: string;
+        limit?: number;
+    }): Promise<ContextHistoryEntry[]>;
+    /** A bundle's versions, newest first. */
+    versions(name: string, options?: {
+        limit?: number;
+    }): Promise<ContextBundle[]>;
+    /** A bundle's labels. */
+    labels(name: string): Promise<ContextLabel[]>;
+    /** Every bundle's name, sorted. */
+    names(): Promise<string[]>;
+    /** What changed between two versions or labels of a bundle. */
+    diff(name: string, from: string, to: string): Promise<ContextDiff>;
+    /**
+     * A bundle version as one document, with every prompt version it pins when the hub has a prompt
+     * registry, so importing it elsewhere needs nothing else.
+     */
+    export(name: string, ref?: string): Promise<ContextBundleExport>;
+    /**
+     * Commits an exported bundle, and the prompts it carries into the hub's registry. Each prompt must
+     * still have the version it was exported with, and the bundle its version, so an export edited by
+     * hand is refused rather than imported under a version that no longer describes it.
+     */
+    import(exported: ContextBundleExport, options?: {
+        label?: string | readonly string[];
+        by?: string;
+    }): Promise<ContextBundle>;
+    private read;
+    private pointer;
+    private record;
+}