nexus-ai-pro 1.18.0 → 1.20.0

package/API_STABILITY.md

@@ -442,6 +442,30 @@ from the root.
 - Recovery re-runs a whole run rather than the step it died on, so an assistant with side effects
   should be idempotent or be left at a single attempt.
 
+## Studio stage (1.19.0)
+
+`nexus-ai-pro-studio` is a separate package, experimental in production readiness. It is versioned
+with nexus-ai-pro and declares the core versions it works with as a peer dependency.
+
+- The `nexus-studio` command, its flags, and the shape of the config module's default export follow
+  the 1.x rules. A minor release may add sources and flags.
+- `createStudio()`, `startStudio()`, and the exported types follow the 1.x rules.
+- The JSON routes behind the page are for the page and may change in any release; build on the
+  stores themselves rather than on the studio's routes.
+- 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.
+
+## Retrieval stores stage (1.20.0)
+
+`PostgresVectorStore` (`nexus-ai-pro/postgres/vectors`) and `QdrantVectorStore` (`nexus-ai-pro/rag/qdrant`)
+are experimental in production readiness. The `VectorStore` contract they share with
+`MemoryVectorStore` follows the 1.x rules: a minor release may add optional methods and options, not
+remove or reshape these.
+
+- The pgvector table layout may gain columns in a minor release; `migrate()` adds what is missing.
+- A Qdrant point id is derived from the chunk id and is stable across releases, so a collection
+  written by one version is read by the next.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,108 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.20.0] - 2026-09-28
+
+Retrieval that scales past one process. Deprecated options now say so at run time, and every guide
+explains every export it lists.
+
+### Added
+
+- **Vector stores for retrieval.** `VectorStore` is a shared contract — `add()`, which replaces a chunk
+  whose id already exists, `search()`, `searchVector()` for a vector computed elsewhere, `delete()`,
+  and an exact-match metadata `filter` — with three implementations checked by one contract test:
+  - `PostgresVectorStore` on `nexus-ai-pro/postgres/vectors`, ranking with pgvector in the database,
+    with an HNSW index by default or an exact scan. `vectorStoreMigration()` gives its schema, and
+    `postgresMigration()` and `nexus db sql` include it when `vectors` is named.
+  - `QdrantVectorStore` on `nexus-ai-pro/rag/qdrant`, through Qdrant's REST API with `fetch` and Web
+    Crypto, so no Qdrant client is a dependency and it runs on edge runtimes. `migrate()` creates the
+    collection and indexes filter fields; failures raise `QdrantError`.
+  - `MemoryVectorStore`, which gains `searchVector()`, `delete()`, and the filter.
+- Retrieval is reachable from `nexus-ai-pro/rag` — `MemoryVectorStore`, `createHashEmbeddings()`,
+  `cosineSimilarity()`, `normalizeVector()`, `matchesMetadata()`, and the types — so an application
+  that ingests and searches no longer loads the root import.
+- **Deprecated options warn once per process** through Node's `DeprecationWarning` channel, with a
+  `NEXUS_DEP_*` code each, so `--no-deprecation` silences them and `--throw-deprecation` fails a CI
+  job on them: `GoogleProviderConfig.projectId`, `OllamaProviderConfig.timeout`,
+  `MetricsConfig.prometheus`, `HealthConfig.latencyHalfLife`, `DensificationConfig.preserveMarkdown`,
+  `InjectionDetectionConfig.sensitivity`, and `ToolPolicyConfig.requiresApproval`.
+
+### Changed
+
+- `MemoryVectorStore.add()` replaces a chunk whose id already exists instead of storing a second
+  copy, so re-ingesting a document no longer duplicates its passages in search results.
+- The guide check enforces that every export is explained in a guide's own text, not only named in
+  its generated reference; the five remaining guides — operations, embeddings, evaluation, images,
+  and realtime — now are. The README's limitations and production notes moved into the guides they
+  belong to.
+
+## [1.19.0] - 2026-09-28
+
+A studio to look at it all. `nexus-ai-pro-studio` is a separate package — so the core install never
+carries a UI — that shows what an application records, from its own stores, on the developer's
+machine, with no hosted service.
+
+### Added
+
+- **`nexus-ai-pro-studio`**, experimental, with the `nexus-studio` command. Given a config module
+  whose default export lists the application's stores, it serves eight views:
+  - **Traces**: filtered run lists, run trees with inputs, outputs, cost, and latency, trace
+    comparison, and feedback on a run.
+  - **Threads**: each graph's diagram with the next nodes highlighted, state at any step, and fork,
+    edit, and resume.
+  - **Inbox**: every thread waiting for a human and every review item waiting for a grade.
+  - **Experiments**: experiment and dataset lists, and comparisons with per-metric intervals and a
+    verdict.
+  - **Prompts**: versions, labels, history, diffs, gated promotion, rollback, and a playground.
+  - **Costs**: cost per day and per model, the most expensive runs, and budgets.
+  - **Health**: provider health, local and shared circuit state, metrics, and cache statistics.
+  - **Operations**: the operation queue by status, and asset store totals.
+- **Locked down for a local tool.** It binds `127.0.0.1`, requires a token that moves from the URL
+  into an HTTP-only same-site cookie, requires the token in a header for every change, refuses
+  non-loopback `Host` headers against DNS rebinding, and serves every page under a strict content
+  security policy with every value inserted as text.
+- `startStudio()` and `createStudio()` start it from code or mount it in an existing server.
+- `npm run studio:demo` starts it on a demo application with something in every view.
+- The operation-store checkpointer — the one behind Redis and Postgres — lists its threads through
+  `threadIds()`, as the in-memory one already did, and `GraphCheckpointer` declares it as optional.
+
+### Fixed
+
+- **Secret detection on input now detects under every action.** It only scanned when the action
+  was `mask`. Under the default action, `block`, and under `flag`, a request carrying a private
+  key, a cloud or payment key, a token, or a secret assignment went out with no finding. Such a
+  request is now blocked by default, at every level but `off`. Set `input.secrets.action` to `flag`
+  to record secrets without blocking.
+- The PII action `remove` deletes the matched data. It was accepted but behaved like `flag`, so the
+  data stayed in the request.
+- The semantic injection check no longer re-embeds its example attacks on every request.
+- `McpServer` answers an unknown method with the JSON-RPC method-not-found code, and an unknown
+  resource with invalid-params, instead of an internal error, so a client can tell an unsupported
+  feature from a failure.
+- `McpClient` requests made together before the handshake finished each sent `initialize`; they now
+  share one handshake.
+- `summarizeVerifyFormat()`'s verify step sent the summary to the model with no instruction, so the
+  model answered the summary instead of restating it, and that reply was what got checked against
+  the sources. It now asks for a restatement against the sources. The final format is applied only in
+  the last step, and a verify step that was skipped is no longer recorded in `steps`.
+- `traceModelClient()` records the model and provider that answered on the run itself. It recorded
+  the model the request asked for — often `auto` — and left `provider` empty, so a `provider` query
+  never matched a model run and per-model views showed `auto`. `FinishRunOptions` gains `model` and
+  `provider` for the same purpose in your own instrumentation.
+
+### Deprecated
+
+- `InjectionDetectionConfig.sensitivity` and `ToolPolicyConfig.requiresApproval` have never been
+  read. Both will be removed in 2.0; approval before a tool runs belongs to the agent loop.
+
+### Changed
+
+- Nineteen guides under `docs/` — agents, batch, caching, core, graphs, grounding, MCP, memory,
+  Postgres, prompts, providers, resilience, security, server, telephony, testing, tracing, voice, and
+  workflows — now explain each export they list in their text, not only in the generated reference.
+  The security configuration's nested settings have doc comments.
+- The documentation coverage check also covers the studio package's exports.
+
 ## [1.18.0] - 2026-09-25
 
 A server you can host. Assistants get an HTTP surface — threads, background runs, resumable event
@@ -941,7 +1043,9 @@ 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.18.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.20.0...HEAD
+[1.20.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.19.0...v1.20.0
+[1.19.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.18.0...v1.19.0
 [1.18.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.17.0...v1.18.0
 [1.17.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.16.0...v1.17.0
 [1.16.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.15.0...v1.16.0

package/README.md

@@ -125,6 +125,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Realtime voice](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/realtime.md) | Browser and server realtime sessions with barge-in, tools, and exports |
 | [Telephony](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/telephony.md) | Calls, webhooks, phone numbers, and phone agents on realtime sessions |
 | [Testing](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/testing.md) | Recording and replaying provider traffic, and conformance suites |
+| [Studio](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/studio.md) | A local UI for traces, threads, approvals, experiments, prompts, costs, and health, as a separate package |
 | [Agent server](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/server.md) | Self-hosted HTTP server for assistants: threads, durable runs, resumable streams, cron |
 | [Workflows](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/workflows.md) | Ready-made chains and domain workflows |
 | [Command line](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/cli.md) | The `nexus` command |
@@ -196,37 +197,22 @@ Shipped so far:
 - queryable traces, an evaluation platform, and a CI gate on top of it;
 - 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 is a self-hosted agent server. The image family leaves experimental once recorded live
-conformance passes on all three backends.
-
-## Known Limitations
-
-- Voice, telephony, images, local models, and custom providers are optional layers; enable only what
-  you use.
-- Audio and video preprocessing is limited, and provider modality support differs.
-- Bundled model metadata is a routing and estimation convenience, not a pricing contract.
-- Process-memory cache, queues, and asset storage are not enough for a distributed deployment; use
-  the Redis, BullMQ, filesystem, or S3 adapters instead.
-- Default hash embeddings suit tests and demos, not strong semantic search. Register a real
-  embedding provider for production retrieval.
-- NLI verification is an interface; bring a specialized verifier for high-confidence entailment.
-- Guardrails reduce risk but do not replace application authorization, provider-side moderation, or
-  human review of high-impact actions.
-- Realtime sessions are not yet routed through the metrics, audit, and rate-limit path that every
-  other family uses.
-- The image adapters are verified against documented wire shapes; recorded live conformance for all
-  three backends is still to come, which is why the family is experimental.
-
-## Production Notes
-
-- Use direct or rules-based routing when model choice is already known.
-- Keep semantic cache, semantic security, and custom hooks off latency-sensitive routes unless needed.
-- Disable response traces with `pipeline.includeTraceInResponse = false`.
-- Use shared adapters for distributed apps instead of process memory.
-- Treat bundled model pricing and context metadata as defaults, not financial truth.
-- Keep server-side authorization and provider moderation around high-risk workflows.
+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.
+
+## Before Production
+
+Each guide ends with its limitations. The ones worth reading first: the
+[client guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/core.md#in-production) on latency, traces,
+and shared adapters; the [security guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/security.md#limitations)
+on what guardrails do not replace; and the
+[grounding guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/grounding.md#limitations) on embeddings
+and verification. Voice, telephony, images, realtime, local models, and custom providers are optional
+layers; enable only what you use.
 
 ## Donations
 

package/dist/cli/db.js

@@ -1,6 +1,14 @@
 import { postgresMigration } from '../postgres/index.js';
 import { CliUsageError, listFlag, numberFlag } from './args.js';
-const ADAPTERS = ['operations', 'store', 'traces', 'evaluation', 'circuits', 'prompts'];
+const ADAPTERS = [
+    'operations',
+    'store',
+    'traces',
+    'evaluation',
+    'circuits',
+    'prompts',
+    'vectors',
+];
 export async function runDbCommand(subcommand, { flags }) {
     if (subcommand !== 'sql')
         throw new CliUsageError(`Unknown db command "${subcommand ?? ''}". Use sql.`);
@@ -10,6 +18,9 @@ export async function runDbCommand(subcommand, { flags }) {
         throw new CliUsageError(`Unknown adapter ${unknown.join(', ')}. Choose from ${ADAPTERS.join(', ')}.`);
     }
     const vectorDimensions = numberFlag(flags, 'vector-dimensions');
+    if (adapters?.includes('vectors') && vectorDimensions === undefined) {
+        throw new CliUsageError('The vectors adapter needs --vector-dimensions.');
+    }
     process.stdout.write(postgresMigration({
         ...(adapters ? { adapters } : {}),
         ...(vectorDimensions === undefined ? {} : { vectorDimensions }),

package/dist/graph/checkpointer.d.ts

@@ -66,6 +66,11 @@ export declare class OperationStoreCheckpointer implements GraphCheckpointer {
     history(threadId: string, limit?: number): Promise<GraphCheckpoint[]>;
     /** Deletes a thread's checkpoints and its head. */
     delete(threadId: string): Promise<void>;
+    /**
+     * Every thread with a checkpoint, read from the head records. Empty when the store cannot list,
+     * since finding heads any other way would mean scanning every key.
+     */
+    threadIds(): Promise<string[]>;
     private readHead;
     /**
      * Writes one record, creating it when absent and otherwise updating in place.

package/dist/graph/checkpointer.js

@@ -86,6 +86,15 @@ export class OperationStoreCheckpointer {
             await this.store.delete?.(stepId(threadId, step));
         await this.store.delete?.(threadId);
     }
+    async threadIds() {
+        if (!this.store.list)
+            return [];
+        const records = await this.store.list();
+        return records
+            .filter((record) => record.result !== undefined && isHead(record.result))
+            .map((record) => record.id)
+            .sort();
+    }
     async readHead(threadId) {
         const record = await this.store.read(threadId);
         return record?.result && isHead(record.result) ? record.result : undefined;

package/dist/hallucination/retrieval.d.ts

@@ -17,24 +17,52 @@ export interface VectorSearchOptions {
     topK?: number;
     /** Lowest similarity returned. Defaults to 0. */
     minScore?: number;
+    /**
+     * Exact matches on top-level `metadata` fields, such as `{ tenant: 'acme' }`. Every field must
+     * match. Values are strings, numbers, or booleans, which every adapter can filter on natively.
+     */
+    filter?: Record<string, string | number | boolean>;
+}
+/**
+ * Where retrieval chunks live and how they are searched. `MemoryVectorStore`, `PostgresVectorStore`,
+ * and `QdrantVectorStore` implement it, and pass the same contract tests.
+ *
+ * Adding a chunk whose id already exists replaces it, so re-ingesting a document never duplicates
+ * its passages.
+ */
+export interface VectorStore {
+    /** Adds chunks, or replaces the ones whose id already exists, embedding those without a vector. */
+    add(documents: VectorDocument[]): Promise<void>;
+    /** The chunks most similar to a query text, best first. */
+    search(query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** The chunks most similar to a vector computed elsewhere, best first. */
+    searchVector(vector: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** Removes chunks by id. An id that is not stored is ignored. */
+    delete(ids: readonly string[]): Promise<void>;
 }
 /**
  * Chunks and their vectors in process memory, searched by cosine similarity. Defaults to hashed
  * term vectors, which need no provider.
  */
-export declare class MemoryVectorStore {
+export declare class MemoryVectorStore implements VectorStore {
     private documents;
     private embed;
     constructor(embed?: EmbeddingProvider);
-    /** Adds chunks, embedding those without a vector in one batch. */
+    /** 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. */
     search(query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** The chunks most similar to a vector, best first. */
+    searchVector(vector: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** Removes chunks by id. */
+    delete(ids: readonly string[]): Promise<void>;
     /** Removes every chunk. */
     clear(): void;
     /** Chunks held. */
     size(): number;
 }
+/** Whether a chunk's metadata satisfies an exact-match filter. Every adapter filters the same way. */
+export declare function matchesMetadata(metadata: Record<string, unknown> | undefined, filter: VectorSearchOptions['filter']): boolean;
 /**
  * Hashed term-count vectors, normalized to unit length. Deterministic and free, for tests and a
  * store without a provider.
@@ -42,4 +70,5 @@ export declare class MemoryVectorStore {
 export declare function createHashEmbeddings(texts: string[], dimensions?: number): number[][];
 /** Cosine similarity of two unit-length vectors, as their dot product. */
 export declare function cosineSimilarity(a: number[], b: number[]): number;
+/** Scales a vector to unit length, so a dot product is its cosine similarity. A zero vector stays zero. */
 export declare function normalizeVector(vector: number[]): number[];

package/dist/hallucination/retrieval.js

@@ -1,5 +1,5 @@
 export class MemoryVectorStore {
-    documents = [];
+    documents = new Map();
     embed;
     constructor(embed = createHashEmbeddings) {
         this.embed = embed;
@@ -10,29 +10,46 @@ export class MemoryVectorStore {
         let generatedIndex = 0;
         for (const doc of documents) {
             const embedding = doc.embedding || generated[generatedIndex++];
-            this.documents.push({ ...doc, embedding: normalizeVector(embedding) });
+            this.documents.set(doc.id, { ...doc, embedding: normalizeVector(embedding) });
         }
     }
     async search(query, options = {}) {
+        const [queryEmbedding] = await this.embed([query]);
+        return this.searchVector(queryEmbedding, options);
+    }
+    async searchVector(vector, options = {}) {
         const topK = options.topK || 5;
         const minScore = options.minScore ?? 0;
-        const [queryEmbedding] = await this.embed([query]);
-        const normalizedQuery = normalizeVector(queryEmbedding);
-        return this.documents
-            .map(({ embedding, ...doc }) => ({
-            ...doc,
-            score: cosineSimilarity(normalizedQuery, embedding),
-        }))
-            .filter((doc) => doc.score >= minScore)
-            .sort((a, b) => b.score - a.score)
-            .slice(0, topK);
+        const normalizedQuery = normalizeVector(vector);
+        const results = [];
+        for (const { embedding, ...doc } of this.documents.values()) {
+            if (!matchesMetadata(doc.metadata, options.filter))
+                continue;
+            const score = cosineSimilarity(normalizedQuery, embedding);
+            if (score >= minScore)
+                results.push({ ...doc, score });
+        }
+        return results.sort((a, b) => b.score - a.score).slice(0, topK);
+    }
+    async delete(ids) {
+        for (const id of ids)
+            this.documents.delete(id);
     }
     clear() {
-        this.documents = [];
+        this.documents.clear();
     }
     size() {
-        return this.documents.length;
+        return this.documents.size;
+    }
+}
+export function matchesMetadata(metadata, filter) {
+    if (!filter)
+        return true;
+    for (const [key, expected] of Object.entries(filter)) {
+        if (metadata?.[key] !== expected)
+            return false;
     }
+    return true;
 }
 export function createHashEmbeddings(texts, dimensions = 384) {
     return texts.map((text) => {

package/dist/index.d.ts

@@ -38,7 +38,7 @@ export { PipelineRunner, createPipelineContext, } from './pipeline/pipeline.js';
 export type { PipelineConfig, PipelineContext, PipelineHookName, PipelineHooksConfig, PipelineMiddleware, PipelineStep, PipelineStepName, PipelineTrace, PipelineTraceStep, } from './pipeline/types.js';
 export { withFactualDefaults, asJsonOnly, type FactualOptions, } from './hallucination/factual.js';
 export { withRagContext, extractCitations, validateCitations, type RagChunk, type RagOptions, } from './hallucination/rag.js';
-export { MemoryVectorStore, createHashEmbeddings, cosineSimilarity, type EmbeddingProvider, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, } from './hallucination/retrieval.js';
+export { MemoryVectorStore, createHashEmbeddings, cosineSimilarity, matchesMetadata, normalizeVector, type EmbeddingProvider, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, type VectorStore, } from './hallucination/retrieval.js';
 export { withKnowledgeGraphContext, selectGraphFacts, type KnowledgeGraph, type KnowledgeGraphEdge, type KnowledgeGraphNode, type KnowledgeGraphOptions, } from './hallucination/knowledge-graph.js';
 export { completeVerified, verifyAgainstContext, extractFacts, lexicalEntailment, type NliVerifier, type VerificationClient, type VerificationFact, type VerificationOptions, type VerificationReport, } from './hallucination/verification.js';
 export { completeWithSelfConsistency, selectMostConsistent, textSimilarity, type ConsistencyClient, type SelfConsistencyOptions, } from './hallucination/consistency.js';

package/dist/index.js

@@ -37,7 +37,7 @@ export { MemoryRateLimitStore, RedisRateLimitStore, } from './ops/rate-limit-ada
 export { PipelineRunner, createPipelineContext, } from './pipeline/pipeline.js';
 export { withFactualDefaults, asJsonOnly, } from './hallucination/factual.js';
 export { withRagContext, extractCitations, validateCitations, } from './hallucination/rag.js';
-export { MemoryVectorStore, createHashEmbeddings, cosineSimilarity, } from './hallucination/retrieval.js';
+export { MemoryVectorStore, createHashEmbeddings, cosineSimilarity, matchesMetadata, normalizeVector, } from './hallucination/retrieval.js';
 export { withKnowledgeGraphContext, selectGraphFacts, } from './hallucination/knowledge-graph.js';
 export { completeVerified, verifyAgainstContext, extractFacts, lexicalEntailment, } from './hallucination/verification.js';
 export { completeWithSelfConsistency, selectMostConsistent, textSimilarity, } from './hallucination/consistency.js';

package/dist/mcp/client.d.ts

@@ -62,13 +62,18 @@ export declare class McpClient {
     private readonly pending;
     private nextId;
     private initialized;
+    private connecting;
     private serverInfo;
     constructor(transport: McpTransport, options?: McpClientOptions);
-    /** Performs the handshake. Called automatically by the first request that needs it. */
+    /**
+     * Performs the handshake and returns the server's name and version. Called automatically by the
+     * first request that needs it; requests made together share one handshake.
+     */
     connect(): Promise<{
         name?: string;
         version?: string;
     }>;
+    private handshake;
     /** Lists the server's tools. */
     listTools(): Promise<McpToolDescriptor[]>;
     /**

package/dist/mcp/client.js

@@ -5,6 +5,7 @@ export class McpClient {
     pending = new Map();
     nextId = 1;
     initialized = false;
+    connecting;
     serverInfo = {};
     constructor(transport, options = {}) {
         this.transport = transport;
@@ -15,6 +16,12 @@ export class McpClient {
     async connect() {
         if (this.initialized)
             return this.serverInfo;
+        this.connecting ??= this.handshake().finally(() => {
+            this.connecting = undefined;
+        });
+        return this.connecting;
+    }
+    async handshake() {
         await this.transport.start?.();
         const result = (await this.request('initialize', {
             protocolVersion: MCP_PROTOCOL_VERSION,

package/dist/mcp/server.js

@@ -1,4 +1,4 @@
-import { isNotification, isRequest, JSON_RPC_ERRORS, LineDecoder, MCP_PROTOCOL_VERSION, textContent, } from './protocol.js';
+import { isNotification, isRequest, JSON_RPC_ERRORS, LineDecoder, MCP_PROTOCOL_VERSION, McpError, textContent, } from './protocol.js';
 export class McpServer {
     options;
     tools = new Map();
@@ -35,7 +35,7 @@ export class McpServer {
                 jsonrpc: '2.0',
                 id: message.id,
                 error: {
-                    code: JSON_RPC_ERRORS.internal,
+                    code: error instanceof McpError ? error.code : JSON_RPC_ERRORS.internal,
                     message: error instanceof Error ? error.message : String(error),
                 },
             });
@@ -89,7 +89,7 @@ export class McpServer {
                 const uri = String(params.uri ?? '');
                 const resource = this.options.resources?.find((item) => item.uri === uri);
                 if (!resource)
-                    throw new Error(`Unknown resource "${uri}"`);
+                    throw new McpError(`Unknown resource "${uri}"`, JSON_RPC_ERRORS.invalidParams);
                 const value = await resource.read();
                 return {
                     contents: [
@@ -102,7 +102,7 @@ export class McpServer {
                 };
             }
             default:
-                throw new Error(`Unknown method "${request.method}"`);
+                throw new McpError(`Unknown method "${request.method}"`, JSON_RPC_ERRORS.methodNotFound);
         }
     }
 }

package/dist/ops/health.js

@@ -1,8 +1,10 @@
+import { warnUnreadOption } from '../utils/deprecation.js';
 export class ProviderHealthMonitor {
     config;
     states = new Map();
     constructor(config = {}) {
         this.config = config;
+        warnUnreadOption(config.latencyHalfLife !== undefined, 'NEXUS_DEP_HEALTH_LATENCY_HALF_LIFE', 'HealthConfig.latencyHalfLife');
     }
     recordSuccess(providerName, latencyMs) {
         if (!this.config.enabled)

package/dist/ops/metrics.js

@@ -1,3 +1,4 @@
+import { warnUnreadOption } from '../utils/deprecation.js';
 export class InMemoryMetrics {
     counters = new Map();
     histograms = new Map();
@@ -86,6 +87,7 @@ export class MetricsCollector {
         this.config = config;
         this.sink = config.sink || this.memory;
         this.prefix = config.prefix || 'nexus_ai';
+        warnUnreadOption(config.prometheus !== undefined, 'NEXUS_DEP_METRICS_PROMETHEUS', 'MetricsConfig.prometheus');
     }
     async recordRequest(labels) {
         if (!this.config.enabled)

package/dist/optimizer/index.js

@@ -1,6 +1,7 @@
 import { Tokenizer } from '../utils/tokenizer.js';
 import { PromptDensifier } from './densifier.js';
 import { BudgetEnforcer } from './budget.js';
+import { warnUnreadOption } from '../utils/deprecation.js';
 export class TokenOptimizer {
     config;
     tokenizer = new Tokenizer();
@@ -8,6 +9,7 @@ export class TokenOptimizer {
     budget = new BudgetEnforcer(this.tokenizer);
     constructor(config = {}) {
         this.config = config;
+        warnUnreadOption(config.densification?.preserveMarkdown !== undefined, 'NEXUS_DEP_DENSIFICATION_PRESERVE_MARKDOWN', 'DensificationConfig.preserveMarkdown');
     }
     optimize(request) {
         if (this.config.enabled === false) {

package/dist/postgres/index.d.ts

@@ -5,13 +5,17 @@ export { operationStoreMigration, PostgresOperationStore, type PostgresOperation
 export { PostgresPromptStore, type PostgresPromptStoreOptions, promptStoreMigration } from './prompts.js';
 export { PostgresStore, type PostgresStoreOptions, storeMigration } from './store.js';
 export { PostgresTraceStore, type PostgresTraceStoreOptions, traceStoreMigration } from './traces.js';
+export { PostgresVectorStore, type PostgresVectorStoreOptions, vectorStoreMigration } from './vectors.js';
 /** The Postgres adapters a migration can include. */
-export type PostgresAdapter = 'operations' | 'store' | 'traces' | 'evaluation' | 'circuits' | 'prompts';
+export type PostgresAdapter = 'operations' | 'store' | 'traces' | 'evaluation' | 'circuits' | 'prompts' | 'vectors';
 /** Options for `postgresMigration()`. */
 export interface PostgresMigrationOptions {
-    /** Adapters to include. Defaults to all of them. */
+    /**
+     * Adapters to include. Defaults to every one but `vectors`, which needs pgvector and
+     * `vectorDimensions`, so it is included only when named.
+     */
     adapters?: readonly PostgresAdapter[];
-    /** Enables pgvector for the long-term store. */
+    /** Enables pgvector for the long-term store, and sets the width of the `vectors` table. */
     vectorDimensions?: number;
 }
 /**

package/dist/postgres/index.js

@@ -4,6 +4,7 @@ import { operationStoreMigration } from './operations.js';
 import { promptStoreMigration } from './prompts.js';
 import { storeMigration } from './store.js';
 import { traceStoreMigration } from './traces.js';
+import { vectorStoreMigration } from './vectors.js';
 export { circuitStoreMigration, PostgresCircuitStateStore, } from './circuits.js';
 export { fromPostgresJs } from './client.js';
 export { evaluationStoreMigration, PostgresDatasetStore, PostgresExperimentStore, } from './evaluate.js';
@@ -11,6 +12,7 @@ export { operationStoreMigration, PostgresOperationStore } from './operations.js
 export { PostgresPromptStore, promptStoreMigration } from './prompts.js';
 export { PostgresStore, storeMigration } from './store.js';
 export { PostgresTraceStore, traceStoreMigration } from './traces.js';
+export { PostgresVectorStore, vectorStoreMigration } from './vectors.js';
 export function postgresMigration(options = {}) {
     const adapters = new Set(options.adapters ?? ['operations', 'store', 'traces', 'evaluation', 'circuits', 'prompts']);
     const statements = [
@@ -22,6 +24,12 @@ export function postgresMigration(options = {}) {
         ...(adapters.has('evaluation') ? evaluationStoreMigration() : []),
         ...(adapters.has('circuits') ? circuitStoreMigration() : []),
         ...(adapters.has('prompts') ? promptStoreMigration() : []),
+        ...(adapters.has('vectors') ? vectorMigrationFor(options.vectorDimensions) : []),
     ];
     return `${statements.join(';\n\n')};\n`;
 }
+function vectorMigrationFor(dimensions) {
+    if (dimensions === undefined)
+        throw new RangeError('The vectors adapter needs vectorDimensions');
+    return vectorStoreMigration({ dimensions });
+}

package/dist/postgres/vectors.d.ts

@@ -0,0 +1,46 @@
+import { type EmbeddingProvider, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, type VectorStore } from '../hallucination/retrieval.js';
+import { type PostgresLikeClient } from './client.js';
+/** Options for the pgvector store. */
+export interface PostgresVectorStoreOptions {
+    /** Width of every vector. Must match the embedding function's output. */
+    dimensions: number;
+    /** Embeds chunks that arrive without a vector, and search queries. Defaults to hashed term vectors. */
+    embed?: EmbeddingProvider;
+    /** Table name, optionally schema-qualified. Defaults to `nexus_vectors`. */
+    table?: string;
+    /**
+     * The approximate index created by `migrate()`. `hnsw` (the default) answers a search without
+     * scanning every row, at the cost of slower writes; `none` scans exactly, which suits a few
+     * thousand chunks.
+     */
+    index?: 'hnsw' | 'none';
+}
+/** The schema, as statements: the pgvector extension, the table, and its index. */
+export declare function vectorStoreMigration(options: Omit<PostgresVectorStoreOptions, 'embed'>): string[];
+/**
+ * Retrieval chunks in Postgres with pgvector, ranked by cosine similarity in the database.
+ *
+ * The same contract as `MemoryVectorStore`, checked by the same tests. Only the nearest chunks leave
+ * the database, so a search costs the same whether the table holds a thousand chunks or ten million.
+ * Adding a chunk whose id exists replaces it, and a metadata filter runs in SQL.
+ */
+export declare class PostgresVectorStore implements VectorStore {
+    private readonly client;
+    private readonly options;
+    private readonly table;
+    private readonly embed;
+    constructor(client: PostgresLikeClient, options: PostgresVectorStoreOptions);
+    /** Creates the extension, table, and index. Never runs implicitly. */
+    migrate(): Promise<void>;
+    /** 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. */
+    search(query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** The chunks most similar to a vector, best first. */
+    searchVector(vector: number[], options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+    /** Removes chunks by id. */
+    delete(ids: readonly string[]): Promise<void>;
+    /** Chunks stored. */
+    size(): Promise<number>;
+    private assertWidth;
+}