nexus-ai-pro 1.18.0 → 1.19.0

package/API_STABILITY.md

@@ -442,6 +442,19 @@ 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.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,73 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [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 +1008,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.18.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.19.0...HEAD
+[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 |

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/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/security/index.js

@@ -63,9 +63,9 @@ export class SecurityPipeline {
             findings.push(...piiFindings);
             guardrailsApplied.push('pii-detection');
             const action = piiConfig.action || (level === 'strict' || level === 'paranoid' ? 'mask' : 'flag');
-            if (piiFindings.length > 0 && action === 'mask') {
-                safeRequest = this.piiDetector.mask(safeRequest, piiConfig);
-                guardrailsApplied.push('pii-masking');
+            if (piiFindings.length > 0 && (action === 'mask' || action === 'remove')) {
+                safeRequest = this.piiDetector.mask(safeRequest, { ...piiConfig, action });
+                guardrailsApplied.push(action === 'remove' ? 'pii-removal' : 'pii-masking');
             }
         }
         const blockingFindings = this.getBlockingFindings(findings, level, normalized);

package/dist/security/input-guard.js

@@ -103,8 +103,13 @@ export class InputGuard {
             });
             return output;
         };
-        if (action !== 'mask')
+        if (action !== 'mask') {
+            request.messages.forEach((message, index) => {
+                for (const text of this.extractText(message))
+                    maskText(text, `messages.${index}.content`);
+            });
             return request;
+        }
         return {
             ...request,
             messages: request.messages.map((message, index) => ({

package/dist/security/pii-detector.d.ts

@@ -4,7 +4,7 @@ import type { PIIConfig, SecurityFinding } from '../types/security.js';
 export declare class PIIDetector {
     /** Finds personal data in a request's messages. */
     detect(request: CompletionRequest, config?: PIIConfig): SecurityFinding[];
-    /** Returns the request with personal data masked. */
+    /** Returns the request with personal data masked, or removed when the action is `remove`. */
     mask(request: CompletionRequest, config?: PIIConfig): CompletionRequest;
     private maskText;
     private extractText;

package/dist/security/pii-detector.js

@@ -35,22 +35,28 @@ export class PIIDetector {
     mask(request, config = {}) {
         const enabledTypes = config.detect || ['email', 'phone', 'credit-card', 'ip-address', 'aws-key', 'private-key'];
         const maskChar = config.maskChar || '█';
+        const remove = config.action === 'remove';
         return {
             ...request,
             messages: request.messages.map((message) => ({
                 ...message,
                 content: typeof message.content === 'string'
-                    ? this.maskText(message.content, enabledTypes, maskChar, config.preserveFormat !== false)
+                    ? this.maskText(message.content, enabledTypes, maskChar, config.preserveFormat !== false, remove)
                     : message.content.map((part) => part.type === 'text'
-                        ? { ...part, text: this.maskText(part.text, enabledTypes, maskChar, config.preserveFormat !== false) }
+                        ? {
+                            ...part,
+                            text: this.maskText(part.text, enabledTypes, maskChar, config.preserveFormat !== false, remove),
+                        }
                         : part),
             })),
         };
     }
-    maskText(text, types, maskChar, preserveFormat) {
+    maskText(text, types, maskChar, preserveFormat, remove = false) {
         let masked = text;
         for (const type of types) {
             masked = masked.replace(PII_PATTERNS[type], (value) => {
+                if (remove)
+                    return '';
                 if (!preserveFormat)
                     return maskChar.repeat(Math.min(value.length, 12));
                 return value.replace(/[A-Za-z0-9]/g, maskChar);

package/dist/security/prompt-hardening.d.ts

@@ -1,6 +1,9 @@
 import type { CompletionRequest } from '../types/messages.js';
+/** Options for `hardenPrompt()`. */
 export interface PromptHardeningOptions {
+    /** What user text is wrapped in. Defaults to `"""`. */
     delimiter?: string;
+    /** The system message placed first, telling the model to treat delimited text as data. */
     systemInstruction?: string;
 }
 /**

package/dist/security/semantic-injection-classifier.d.ts

@@ -1,10 +1,15 @@
 import type { CompletionRequest } from '../types/messages.js';
 import type { SecurityFinding } from '../types/security.js';
 import { type EmbeddingProvider } from '../hallucination/retrieval.js';
+/** Options for `SemanticInjectionClassifier`. */
 export interface SemanticInjectionClassifierOptions {
+    /** `false` turns `detect()` off. */
     enabled?: boolean;
+    /** Similarity at which a prompt is flagged, from 0 to 1. Defaults to 0.78; above 0.88 is critical. */
     threshold?: number;
+    /** Embeds text for `detect()`. Defaults to hashed term vectors; `detectSync()` always uses those. */
     embed?: EmbeddingProvider;
+    /** Example attacks to compare against, instead of the built-in ones. */
     examples?: string[];
 }
 /**
@@ -16,6 +21,7 @@ export declare class SemanticInjectionClassifier {
     private examples;
     private embed;
     private exampleEmbeddings?;
+    private hashedExamples?;
     constructor(options?: SemanticInjectionClassifierOptions);
     /** Finds injection attempts, using the configured embedding function. */
     detect(request: CompletionRequest): Promise<SecurityFinding[]>;

package/dist/security/semantic-injection-classifier.js

@@ -12,6 +12,7 @@ export class SemanticInjectionClassifier {
     examples;
     embed;
     exampleEmbeddings;
+    hashedExamples;
     constructor(options = {}) {
         this.options = options;
         this.examples = options.examples || DEFAULT_ATTACK_EXAMPLES;
@@ -43,7 +44,8 @@ export class SemanticInjectionClassifier {
     detectSync(request) {
         const findings = [];
         const threshold = this.options.threshold ?? 0.78;
-        const exampleEmbeddings = createHashEmbeddings(this.examples);
+        this.hashedExamples ??= createHashEmbeddings(this.examples);
+        const exampleEmbeddings = this.hashedExamples;
         for (const [index, message] of request.messages.entries()) {
             for (const text of extractText(message)) {
                 const [embedding] = createHashEmbeddings([text]);

package/dist/tracing/instrument.js

@@ -105,6 +105,8 @@ export function traceModelClient(client, tracer, options = {}) {
                         }
                         : {}),
                     ...(response.meta?.cost?.amount === undefined ? {} : { cost: response.meta.cost.amount }),
+                    ...(response.meta?.modelUsed ? { model: response.meta.modelUsed } : {}),
+                    ...(response.meta?.providerUsed ? { provider: response.meta.providerUsed } : {}),
                     metadata: {
                         provider: response.meta?.providerUsed,
                         model: response.meta?.modelUsed,

package/dist/tracing/tracer.d.ts

@@ -49,6 +49,10 @@ export interface FinishRunOptions {
     cost?: number;
     /** Metadata merged into the run's. */
     metadata?: Record<string, unknown>;
+    /** The model that actually ran, replacing the one the run started with, such as `auto` after routing. */
+    model?: string;
+    /** The provider that actually ran. */
+    provider?: string;
 }
 /** A run in progress. Finishing it writes it to the store. */
 export interface RunHandle {

package/dist/tracing/tracer.js

@@ -78,6 +78,8 @@ export class Tracer {
                 ...(options.error ? { error: describeError(options.error) } : {}),
                 ...(options.usage ? { usage: options.usage } : {}),
                 ...(options.cost === undefined ? {} : { cost: options.cost }),
+                ...(options.model ? { model: options.model } : {}),
+                ...(options.provider ? { provider: options.provider } : {}),
                 metadata: { ...run.metadata, ...options.metadata },
             };
             await this.close(finished, sampled);

package/dist/types/graph.d.ts

@@ -360,6 +360,8 @@ export interface GraphCheckpointer {
     history(threadId: string, limit?: number): Promise<GraphCheckpoint[]> | GraphCheckpoint[];
     /** Deletes every checkpoint of a thread. */
     delete?(threadId: string): Promise<void> | void;
+    /** Every thread with a checkpoint, for tools that browse threads, such as the studio. */
+    threadIds?(): Promise<string[]> | string[];
 }
 /** Options for one run of a compiled graph. */
 export interface GraphRunOptions {

package/dist/types/security.d.ts

@@ -1,5 +1,11 @@
 /** How much protection a client applies, from none to maximal. */
 export type SecurityLevel = 'off' | 'basic' | 'standard' | 'strict' | 'paranoid';
+/**
+ * A preset tuned for a kind of deployment. `developer` is the `standard` level; `startup` is `strict`
+ * with output redaction; `enterprise` adds blocking injection detection and PII masking; `healthcare`
+ * and `finance` are `paranoid`, blocking or masking PII respectively. Your own settings are merged
+ * over the preset.
+ */
 export type SecurityPreset = 'developer' | 'startup' | 'enterprise' | 'healthcare' | 'finance';
 /**
  * What a guardrail does with a match: let it through, block the request, mask the match, or record
@@ -12,16 +18,27 @@ export type PIIType = 'email' | 'phone' | 'credit-card' | 'ip-address' | 'aws-ke
 export interface InjectionDetectionConfig {
     /** Turns detection on. */
     enabled?: boolean;
-    /** How eagerly patterns match, from 0 to 1. */
+    /**
+     * Ignored: the patterns match or they do not.
+     *
+     * @deprecated Has never been read. It will be removed in 2.0.
+     */
     sensitivity?: number;
     /** What a detection does: block the request, record it, or neutralize the text. */
     onDetection?: 'block' | 'flag' | 'transform';
     /** Extra patterns to treat as injection. */
     customPatterns?: RegExp[];
-    /** Similarity-based detection against example attacks, through an embedder. */
+    /**
+     * Similarity to example attacks, which catches rephrasings a pattern misses. In the pipeline it
+     * compares hashed term vectors, so it needs no provider; for a real embedding model, use
+     * `SemanticInjectionClassifier` with `embed` directly.
+     */
     semantic?: {
+        /** Turns the semantic check on. Off by default. */
         enabled?: boolean;
+        /** Similarity at which a prompt is flagged, from 0 to 1. Defaults to 0.78. */
         threshold?: number;
+        /** Example attacks to compare against, instead of the built-in ones. */
         examples?: string[];
     };
 }
@@ -31,42 +48,82 @@ export interface PIIConfig {
     enabled?: boolean;
     /** Kinds of data to detect. */
     detect?: PIIType[];
-    /** What a match does: mask it, remove it, block the request, or record it. */
+    /**
+     * What a match does: mask it, remove it, block the request, or record it. Defaults to `mask` at the
+     * `strict` and `paranoid` levels and `flag` below them; `paranoid` also blocks.
+     */
     action?: 'mask' | 'remove' | 'block' | 'flag';
-    /** Character used for masking. */
+    /** Character used for masking. Defaults to `█`. */
     maskChar?: string;
-    /** Keeps the data's shape when masking, such as the last four digits. */
+    /**
+     * Keeps the data's shape when masking: letters and digits are replaced one for one and punctuation
+     * stays. On by default; `false` replaces each match with a run of the mask character instead.
+     */
     preserveFormat?: boolean;
 }
+/** Detection of credentials in input: private keys, cloud and payment keys, tokens, and secret assignments. */
 export interface SecretDetectionConfig {
+    /** Turns detection on. On by default at every level but `off`. */
     enabled?: boolean;
+    /** What a match does: block the request, mask the secret, or record it. Defaults to `block`. */
     action?: 'block' | 'mask' | 'flag';
 }
+/**
+ * Detection of risky URLs in input: loopback and cloud-metadata addresses, onion services, and URLs
+ * carrying secret-like query parameters.
+ */
 export interface UrlRiskConfig {
+    /** Turns detection on. On by default at every level but `off`. */
     enabled?: boolean;
+    /** What a match does: block the request, or record it. Defaults to `flag`. */
     action?: 'block' | 'flag';
 }
+/** Which tools a request may offer the model. */
 export interface ToolPolicyConfig {
+    /** The only tool names a request may carry; any other tool blocks it. Unset or empty allows every tool. */
     allowedNames?: string[];
+    /**
+     * Ignored: approval before a tool runs belongs to the agent loop.
+     *
+     * @deprecated Has never been read. It will be removed in 2.0.
+     */
     requiresApproval?: string[];
 }
+/** Terms a response must not contain. */
 export interface ModerationConfig {
+    /** Turns moderation on. Off by default. */
     enabled?: boolean;
+    /** Terms matched literally, ignoring case. */
     forbiddenTerms?: string[];
+    /** What a match does: block the response, record it, or redact the term. Defaults to recording it. */
     onViolation?: 'block' | 'flag' | 'redact';
 }
+/** Data-loss prevention on output. */
 export interface DLPConfig {
+    /** Turns the checks on. On by default. */
     enabled?: boolean;
+    /** Terms that must not leave, such as project code names. A match is recorded as a high finding. */
     proprietaryTerms?: string[];
+    /** Redacts database connection strings. On by default. */
     connectionStrings?: boolean;
 }
+/** Topics a response must stay out of, matched as text, ignoring case. */
 export interface TopicGuardrailConfig {
+    /** The topics. */
     forbiddenTopics?: string[];
+    /** What a match does: block the response, or record it. Defaults to recording it. */
     onViolation?: 'block' | 'flag';
 }
+/**
+ * A cheap grounding check on output: the share of the response's longer words that also appear in
+ * the context. A low share is recorded as a medium finding; it never blocks.
+ */
 export interface GroundingConfig {
+    /** Turns the check on. Off by default. */
     enabled?: boolean;
+    /** The context the response should draw from. */
     context?: string[];
+    /** Smallest acceptable share, from 0 to 1. Defaults to 0.1. */
     minOverlapRatio?: number;
 }
 /** Guardrails for input and output, from a preset, a level, or detailed settings. */
@@ -77,20 +134,32 @@ export interface SecurityConfig {
     level?: SecurityLevel;
     /** Input guardrails: length, injection, PII, secrets, URLs, and tool policy. */
     input?: {
+        /** Longest the request's text may be, in characters; longer blocks it. */
         maxContentLength?: number;
+        /** Prompt-injection detection, from the `standard` level up. */
         injectionDetection?: InjectionDetectionConfig;
+        /** Personal data detection, from the `standard` level up. */
         pii?: PIIConfig;
+        /** Credential detection. */
         secrets?: SecretDetectionConfig;
+        /** Risky URL detection. */
         urls?: UrlRiskConfig;
+        /** Which tools a request may carry. */
         tools?: ToolPolicyConfig;
     };
     /** Output guardrails: length, PII redaction, moderation, DLP, topics, and grounding. */
     output?: {
+        /** Longest the response may be, in characters; longer is cut, and the cut recorded. */
         maxContentLength?: number;
+        /** Redacts secrets and personal data from the response and its tool-call arguments. On by default. */
         piiRedaction?: boolean;
+        /** Forbidden terms. */
         moderation?: ModerationConfig;
+        /** Connection strings and proprietary terms. */
         dlp?: DLPConfig;
+        /** Forbidden topics. */
         topics?: TopicGuardrailConfig;
+        /** Word overlap with a context. */
         grounding?: GroundingConfig;
     };
 }

package/dist/workflow/chains.d.ts

@@ -32,7 +32,7 @@ export interface SummarizeVerifyFormatOptions {
     model: string;
     /** The content to summarize. */
     input: string;
-    /** Sources to check the summary against. Without them, verification is skipped. */
+    /** Sources to check the summary against. Without them, the verify step is skipped. */
     verifyContext?: string[];
     /** Format of the final answer, such as a JSON schema. */
     responseFormat?: ResponseFormatConfig;
@@ -86,8 +86,8 @@ export interface CompareOptions {
     criteria?: string[];
 }
 /**
- * Summarizes content, verifies the summary against sources when given, then formats it: three
- * completions, each step returned.
+ * Summarizes content, verifies the summary against sources when given, then formats it: two
+ * completions, or three to four with verification, each step returned.
  */
 export declare function summarizeVerifyFormat(client: WorkflowClient, options: SummarizeVerifyFormatOptions): Promise<WorkflowResult>;
 /**

package/dist/workflow/chains.js

@@ -13,17 +13,28 @@ export async function summarizeVerifyFormat(client, options) {
         ],
     }, { chainOfThought: 'private' }));
     steps.push({ step: 'summarize', response: summary });
-    const verified = options.verifyContext?.length
-        ? await completeVerified(client, {
+    let verified = summary;
+    if (options.verifyContext?.length) {
+        verified = await completeVerified(client, {
             model: options.model,
-            messages: [{ role: 'user', content: summary.content }],
-            responseFormat: toRequestResponseFormat(options.responseFormat),
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        'Restate this summary, keeping only what the sources support.',
+                        'Sources:',
+                        ...options.verifyContext.map((item, index) => `[source-${index + 1}] ${item}`),
+                        'Summary:',
+                        summary.content,
+                    ].join('\n'),
+                },
+            ],
         }, {
             context: options.verifyContext,
             repair: true,
-        })
-        : summary;
-    steps.push({ step: 'verify', response: verified });
+        });
+        steps.push({ step: 'verify', response: verified });
+    }
     const formatted = await client.complete({
         model: options.model,
         messages: [

package/dist-cjs/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-cjs/graph/checkpointer.js

@@ -90,6 +90,15 @@ 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-cjs/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-cjs/mcp/client.js

@@ -43,6 +43,7 @@ class McpClient {
     pending = new Map();
     nextId = 1;
     initialized = false;
+    connecting;
     serverInfo = {};
     constructor(transport, options = {}) {
         this.transport = transport;
@@ -53,6 +54,12 @@ 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: protocol_js_1.MCP_PROTOCOL_VERSION,

package/dist-cjs/mcp/server.js

@@ -39,7 +39,7 @@ class McpServer {
                 jsonrpc: '2.0',
                 id: message.id,
                 error: {
-                    code: protocol_js_1.JSON_RPC_ERRORS.internal,
+                    code: error instanceof protocol_js_1.McpError ? error.code : protocol_js_1.JSON_RPC_ERRORS.internal,
                     message: error instanceof Error ? error.message : String(error),
                 },
             });
@@ -93,7 +93,7 @@ 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 protocol_js_1.McpError(`Unknown resource "${uri}"`, protocol_js_1.JSON_RPC_ERRORS.invalidParams);
                 const value = await resource.read();
                 return {
                     contents: [
@@ -106,7 +106,7 @@ class McpServer {
                 };
             }
             default:
-                throw new Error(`Unknown method "${request.method}"`);
+                throw new protocol_js_1.McpError(`Unknown method "${request.method}"`, protocol_js_1.JSON_RPC_ERRORS.methodNotFound);
         }
     }
 }

package/dist-cjs/security/index.js

@@ -67,9 +67,9 @@ class SecurityPipeline {
             findings.push(...piiFindings);
             guardrailsApplied.push('pii-detection');
             const action = piiConfig.action || (level === 'strict' || level === 'paranoid' ? 'mask' : 'flag');
-            if (piiFindings.length > 0 && action === 'mask') {
-                safeRequest = this.piiDetector.mask(safeRequest, piiConfig);
-                guardrailsApplied.push('pii-masking');
+            if (piiFindings.length > 0 && (action === 'mask' || action === 'remove')) {
+                safeRequest = this.piiDetector.mask(safeRequest, { ...piiConfig, action });
+                guardrailsApplied.push(action === 'remove' ? 'pii-removal' : 'pii-masking');
             }
         }
         const blockingFindings = this.getBlockingFindings(findings, level, normalized);

package/dist-cjs/security/input-guard.js

@@ -106,8 +106,13 @@ class InputGuard {
             });
             return output;
         };
-        if (action !== 'mask')
+        if (action !== 'mask') {
+            request.messages.forEach((message, index) => {
+                for (const text of this.extractText(message))
+                    maskText(text, `messages.${index}.content`);
+            });
             return request;
+        }
         return {
             ...request,
             messages: request.messages.map((message, index) => ({

package/dist-cjs/security/pii-detector.d.ts

@@ -4,7 +4,7 @@ import type { PIIConfig, SecurityFinding } from '../types/security.js';
 export declare class PIIDetector {
     /** Finds personal data in a request's messages. */
     detect(request: CompletionRequest, config?: PIIConfig): SecurityFinding[];
-    /** Returns the request with personal data masked. */
+    /** Returns the request with personal data masked, or removed when the action is `remove`. */
     mask(request: CompletionRequest, config?: PIIConfig): CompletionRequest;
     private maskText;
     private extractText;

package/dist-cjs/security/pii-detector.js

@@ -38,22 +38,28 @@ class PIIDetector {
     mask(request, config = {}) {
         const enabledTypes = config.detect || ['email', 'phone', 'credit-card', 'ip-address', 'aws-key', 'private-key'];
         const maskChar = config.maskChar || '█';
+        const remove = config.action === 'remove';
         return {
             ...request,
             messages: request.messages.map((message) => ({
                 ...message,
                 content: typeof message.content === 'string'
-                    ? this.maskText(message.content, enabledTypes, maskChar, config.preserveFormat !== false)
+                    ? this.maskText(message.content, enabledTypes, maskChar, config.preserveFormat !== false, remove)
                     : message.content.map((part) => part.type === 'text'
-                        ? { ...part, text: this.maskText(part.text, enabledTypes, maskChar, config.preserveFormat !== false) }
+                        ? {
+                            ...part,
+                            text: this.maskText(part.text, enabledTypes, maskChar, config.preserveFormat !== false, remove),
+                        }
                         : part),
             })),
         };
     }
-    maskText(text, types, maskChar, preserveFormat) {
+    maskText(text, types, maskChar, preserveFormat, remove = false) {
         let masked = text;
         for (const type of types) {
             masked = masked.replace(PII_PATTERNS[type], (value) => {
+                if (remove)
+                    return '';
                 if (!preserveFormat)
                     return maskChar.repeat(Math.min(value.length, 12));
                 return value.replace(/[A-Za-z0-9]/g, maskChar);

package/dist-cjs/security/prompt-hardening.d.ts

@@ -1,6 +1,9 @@
 import type { CompletionRequest } from '../types/messages.js';
+/** Options for `hardenPrompt()`. */
 export interface PromptHardeningOptions {
+    /** What user text is wrapped in. Defaults to `"""`. */
     delimiter?: string;
+    /** The system message placed first, telling the model to treat delimited text as data. */
     systemInstruction?: string;
 }
 /**

package/dist-cjs/security/semantic-injection-classifier.d.ts

@@ -1,10 +1,15 @@
 import type { CompletionRequest } from '../types/messages.js';
 import type { SecurityFinding } from '../types/security.js';
 import { type EmbeddingProvider } from '../hallucination/retrieval.js';
+/** Options for `SemanticInjectionClassifier`. */
 export interface SemanticInjectionClassifierOptions {
+    /** `false` turns `detect()` off. */
     enabled?: boolean;
+    /** Similarity at which a prompt is flagged, from 0 to 1. Defaults to 0.78; above 0.88 is critical. */
     threshold?: number;
+    /** Embeds text for `detect()`. Defaults to hashed term vectors; `detectSync()` always uses those. */
     embed?: EmbeddingProvider;
+    /** Example attacks to compare against, instead of the built-in ones. */
     examples?: string[];
 }
 /**
@@ -16,6 +21,7 @@ export declare class SemanticInjectionClassifier {
     private examples;
     private embed;
     private exampleEmbeddings?;
+    private hashedExamples?;
     constructor(options?: SemanticInjectionClassifierOptions);
     /** Finds injection attempts, using the configured embedding function. */
     detect(request: CompletionRequest): Promise<SecurityFinding[]>;

package/dist-cjs/security/semantic-injection-classifier.js

@@ -15,6 +15,7 @@ class SemanticInjectionClassifier {
     examples;
     embed;
     exampleEmbeddings;
+    hashedExamples;
     constructor(options = {}) {
         this.options = options;
         this.examples = options.examples || DEFAULT_ATTACK_EXAMPLES;
@@ -46,7 +47,8 @@ class SemanticInjectionClassifier {
     detectSync(request) {
         const findings = [];
         const threshold = this.options.threshold ?? 0.78;
-        const exampleEmbeddings = (0, retrieval_js_1.createHashEmbeddings)(this.examples);
+        this.hashedExamples ??= (0, retrieval_js_1.createHashEmbeddings)(this.examples);
+        const exampleEmbeddings = this.hashedExamples;
         for (const [index, message] of request.messages.entries()) {
             for (const text of extractText(message)) {
                 const [embedding] = (0, retrieval_js_1.createHashEmbeddings)([text]);

package/dist-cjs/tracing/instrument.js

@@ -109,6 +109,8 @@ function traceModelClient(client, tracer, options = {}) {
                         }
                         : {}),
                     ...(response.meta?.cost?.amount === undefined ? {} : { cost: response.meta.cost.amount }),
+                    ...(response.meta?.modelUsed ? { model: response.meta.modelUsed } : {}),
+                    ...(response.meta?.providerUsed ? { provider: response.meta.providerUsed } : {}),
                     metadata: {
                         provider: response.meta?.providerUsed,
                         model: response.meta?.modelUsed,

package/dist-cjs/tracing/tracer.d.ts

@@ -49,6 +49,10 @@ export interface FinishRunOptions {
     cost?: number;
     /** Metadata merged into the run's. */
     metadata?: Record<string, unknown>;
+    /** The model that actually ran, replacing the one the run started with, such as `auto` after routing. */
+    model?: string;
+    /** The provider that actually ran. */
+    provider?: string;
 }
 /** A run in progress. Finishing it writes it to the store. */
 export interface RunHandle {

package/dist-cjs/tracing/tracer.js

@@ -82,6 +82,8 @@ class Tracer {
                 ...(options.error ? { error: describeError(options.error) } : {}),
                 ...(options.usage ? { usage: options.usage } : {}),
                 ...(options.cost === undefined ? {} : { cost: options.cost }),
+                ...(options.model ? { model: options.model } : {}),
+                ...(options.provider ? { provider: options.provider } : {}),
                 metadata: { ...run.metadata, ...options.metadata },
             };
             await this.close(finished, sampled);

package/dist-cjs/types/graph.d.ts

@@ -360,6 +360,8 @@ export interface GraphCheckpointer {
     history(threadId: string, limit?: number): Promise<GraphCheckpoint[]> | GraphCheckpoint[];
     /** Deletes every checkpoint of a thread. */
     delete?(threadId: string): Promise<void> | void;
+    /** Every thread with a checkpoint, for tools that browse threads, such as the studio. */
+    threadIds?(): Promise<string[]> | string[];
 }
 /** Options for one run of a compiled graph. */
 export interface GraphRunOptions {

package/dist-cjs/types/security.d.ts

@@ -1,5 +1,11 @@
 /** How much protection a client applies, from none to maximal. */
 export type SecurityLevel = 'off' | 'basic' | 'standard' | 'strict' | 'paranoid';
+/**
+ * A preset tuned for a kind of deployment. `developer` is the `standard` level; `startup` is `strict`
+ * with output redaction; `enterprise` adds blocking injection detection and PII masking; `healthcare`
+ * and `finance` are `paranoid`, blocking or masking PII respectively. Your own settings are merged
+ * over the preset.
+ */
 export type SecurityPreset = 'developer' | 'startup' | 'enterprise' | 'healthcare' | 'finance';
 /**
  * What a guardrail does with a match: let it through, block the request, mask the match, or record
@@ -12,16 +18,27 @@ export type PIIType = 'email' | 'phone' | 'credit-card' | 'ip-address' | 'aws-ke
 export interface InjectionDetectionConfig {
     /** Turns detection on. */
     enabled?: boolean;
-    /** How eagerly patterns match, from 0 to 1. */
+    /**
+     * Ignored: the patterns match or they do not.
+     *
+     * @deprecated Has never been read. It will be removed in 2.0.
+     */
     sensitivity?: number;
     /** What a detection does: block the request, record it, or neutralize the text. */
     onDetection?: 'block' | 'flag' | 'transform';
     /** Extra patterns to treat as injection. */
     customPatterns?: RegExp[];
-    /** Similarity-based detection against example attacks, through an embedder. */
+    /**
+     * Similarity to example attacks, which catches rephrasings a pattern misses. In the pipeline it
+     * compares hashed term vectors, so it needs no provider; for a real embedding model, use
+     * `SemanticInjectionClassifier` with `embed` directly.
+     */
     semantic?: {
+        /** Turns the semantic check on. Off by default. */
         enabled?: boolean;
+        /** Similarity at which a prompt is flagged, from 0 to 1. Defaults to 0.78. */
         threshold?: number;
+        /** Example attacks to compare against, instead of the built-in ones. */
         examples?: string[];
     };
 }
@@ -31,42 +48,82 @@ export interface PIIConfig {
     enabled?: boolean;
     /** Kinds of data to detect. */
     detect?: PIIType[];
-    /** What a match does: mask it, remove it, block the request, or record it. */
+    /**
+     * What a match does: mask it, remove it, block the request, or record it. Defaults to `mask` at the
+     * `strict` and `paranoid` levels and `flag` below them; `paranoid` also blocks.
+     */
     action?: 'mask' | 'remove' | 'block' | 'flag';
-    /** Character used for masking. */
+    /** Character used for masking. Defaults to `█`. */
     maskChar?: string;
-    /** Keeps the data's shape when masking, such as the last four digits. */
+    /**
+     * Keeps the data's shape when masking: letters and digits are replaced one for one and punctuation
+     * stays. On by default; `false` replaces each match with a run of the mask character instead.
+     */
     preserveFormat?: boolean;
 }
+/** Detection of credentials in input: private keys, cloud and payment keys, tokens, and secret assignments. */
 export interface SecretDetectionConfig {
+    /** Turns detection on. On by default at every level but `off`. */
     enabled?: boolean;
+    /** What a match does: block the request, mask the secret, or record it. Defaults to `block`. */
     action?: 'block' | 'mask' | 'flag';
 }
+/**
+ * Detection of risky URLs in input: loopback and cloud-metadata addresses, onion services, and URLs
+ * carrying secret-like query parameters.
+ */
 export interface UrlRiskConfig {
+    /** Turns detection on. On by default at every level but `off`. */
     enabled?: boolean;
+    /** What a match does: block the request, or record it. Defaults to `flag`. */
     action?: 'block' | 'flag';
 }
+/** Which tools a request may offer the model. */
 export interface ToolPolicyConfig {
+    /** The only tool names a request may carry; any other tool blocks it. Unset or empty allows every tool. */
     allowedNames?: string[];
+    /**
+     * Ignored: approval before a tool runs belongs to the agent loop.
+     *
+     * @deprecated Has never been read. It will be removed in 2.0.
+     */
     requiresApproval?: string[];
 }
+/** Terms a response must not contain. */
 export interface ModerationConfig {
+    /** Turns moderation on. Off by default. */
     enabled?: boolean;
+    /** Terms matched literally, ignoring case. */
     forbiddenTerms?: string[];
+    /** What a match does: block the response, record it, or redact the term. Defaults to recording it. */
     onViolation?: 'block' | 'flag' | 'redact';
 }
+/** Data-loss prevention on output. */
 export interface DLPConfig {
+    /** Turns the checks on. On by default. */
     enabled?: boolean;
+    /** Terms that must not leave, such as project code names. A match is recorded as a high finding. */
     proprietaryTerms?: string[];
+    /** Redacts database connection strings. On by default. */
     connectionStrings?: boolean;
 }
+/** Topics a response must stay out of, matched as text, ignoring case. */
 export interface TopicGuardrailConfig {
+    /** The topics. */
     forbiddenTopics?: string[];
+    /** What a match does: block the response, or record it. Defaults to recording it. */
     onViolation?: 'block' | 'flag';
 }
+/**
+ * A cheap grounding check on output: the share of the response's longer words that also appear in
+ * the context. A low share is recorded as a medium finding; it never blocks.
+ */
 export interface GroundingConfig {
+    /** Turns the check on. Off by default. */
     enabled?: boolean;
+    /** The context the response should draw from. */
     context?: string[];
+    /** Smallest acceptable share, from 0 to 1. Defaults to 0.1. */
     minOverlapRatio?: number;
 }
 /** Guardrails for input and output, from a preset, a level, or detailed settings. */
@@ -77,20 +134,32 @@ export interface SecurityConfig {
     level?: SecurityLevel;
     /** Input guardrails: length, injection, PII, secrets, URLs, and tool policy. */
     input?: {
+        /** Longest the request's text may be, in characters; longer blocks it. */
         maxContentLength?: number;
+        /** Prompt-injection detection, from the `standard` level up. */
         injectionDetection?: InjectionDetectionConfig;
+        /** Personal data detection, from the `standard` level up. */
         pii?: PIIConfig;
+        /** Credential detection. */
         secrets?: SecretDetectionConfig;
+        /** Risky URL detection. */
         urls?: UrlRiskConfig;
+        /** Which tools a request may carry. */
         tools?: ToolPolicyConfig;
     };
     /** Output guardrails: length, PII redaction, moderation, DLP, topics, and grounding. */
     output?: {
+        /** Longest the response may be, in characters; longer is cut, and the cut recorded. */
         maxContentLength?: number;
+        /** Redacts secrets and personal data from the response and its tool-call arguments. On by default. */
         piiRedaction?: boolean;
+        /** Forbidden terms. */
         moderation?: ModerationConfig;
+        /** Connection strings and proprietary terms. */
         dlp?: DLPConfig;
+        /** Forbidden topics. */
         topics?: TopicGuardrailConfig;
+        /** Word overlap with a context. */
         grounding?: GroundingConfig;
     };
 }

package/dist-cjs/workflow/chains.d.ts

@@ -32,7 +32,7 @@ export interface SummarizeVerifyFormatOptions {
     model: string;
     /** The content to summarize. */
     input: string;
-    /** Sources to check the summary against. Without them, verification is skipped. */
+    /** Sources to check the summary against. Without them, the verify step is skipped. */
     verifyContext?: string[];
     /** Format of the final answer, such as a JSON schema. */
     responseFormat?: ResponseFormatConfig;
@@ -86,8 +86,8 @@ export interface CompareOptions {
     criteria?: string[];
 }
 /**
- * Summarizes content, verifies the summary against sources when given, then formats it: three
- * completions, each step returned.
+ * Summarizes content, verifies the summary against sources when given, then formats it: two
+ * completions, or three to four with verification, each step returned.
  */
 export declare function summarizeVerifyFormat(client: WorkflowClient, options: SummarizeVerifyFormatOptions): Promise<WorkflowResult>;
 /**

package/dist-cjs/workflow/chains.js

@@ -20,17 +20,28 @@ async function summarizeVerifyFormat(client, options) {
         ],
     }, { chainOfThought: 'private' }));
     steps.push({ step: 'summarize', response: summary });
-    const verified = options.verifyContext?.length
-        ? await (0, verification_js_1.completeVerified)(client, {
+    let verified = summary;
+    if (options.verifyContext?.length) {
+        verified = await (0, verification_js_1.completeVerified)(client, {
             model: options.model,
-            messages: [{ role: 'user', content: summary.content }],
-            responseFormat: toRequestResponseFormat(options.responseFormat),
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        'Restate this summary, keeping only what the sources support.',
+                        'Sources:',
+                        ...options.verifyContext.map((item, index) => `[source-${index + 1}] ${item}`),
+                        'Summary:',
+                        summary.content,
+                    ].join('\n'),
+                },
+            ],
         }, {
             context: options.verifyContext,
             repair: true,
-        })
-        : summary;
-    steps.push({ step: 'verify', response: verified });
+        });
+        steps.push({ step: 'verify', response: verified });
+    }
     const formatted = await client.complete({
         model: options.model,
         messages: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-ai-pro",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Typed AI framework for TypeScript: provider routing and failover, parallel agent graphs with checkpoints, durable operations, guardrails, and cost control",
   "type": "module",
   "main": "dist-cjs/index.js",
@@ -1017,7 +1017,12 @@
     "example:agent": "tsx examples/agent.ts",
     "example:realtime": "tsx examples/realtime-scheduling.ts",
     "size:check": "node scripts/check-subpath-sizes.mjs",
-    "docs:check": "node scripts/check-doc-coverage.mjs",
+    "docs:check": "node scripts/check-doc-coverage.mjs && node scripts/check-doc-coverage.mjs --package studio",
+    "studio:build": "node studio/scripts/build.mjs",
+    "studio:typecheck": "tsc -p studio/tsconfig.json",
+    "studio:demo": "node studio/scripts/run.mjs studio/example/start.ts",
+    "test:studio": "node studio/scripts/run.mjs test",
+    "test:studio-install": "node studio/scripts/install-smoke.mjs",
     "docs:guides": "node scripts/check-guide-coverage.mjs",
     "docs:update": "node scripts/check-guide-coverage.mjs --update",
     "size:update": "node scripts/check-subpath-sizes.mjs --update",
@@ -1030,7 +1035,7 @@
     "typecheck:tests": "tsc -p tsconfig.tests.json --noEmit",
     "typecheck:examples": "tsc -p tsconfig.examples.json --noEmit",
     "typecheck:examples:browser": "tsc -p tsconfig.examples.browser.json --noEmit",
-    "test": "npm run build && npm run test:unit && npm run test:conformance:mock && npm run test:conformance:images && npm run size:check && npm run docs:check && npm run docs:guides && npm run test:smoke && npm run test:api && npm run test:types",
+    "test": "npm run build && npm run test:unit && npm run test:conformance:mock && npm run test:conformance:images && npm run size:check && npm run docs:check && npm run docs:guides && npm run test:studio && npm run test:smoke && npm run test:api && npm run test:types",
     "test:unit": "node --import tsx --test tests/unit.ts tests/*.test.ts",
     "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-include=src/**/*.ts --test-coverage-lines=82 --test-coverage-branches=67 --test-coverage-functions=73 tests/unit.ts tests/*.test.ts",
     "test:smoke": "node tests/package-smoke.mjs",
@@ -1041,8 +1046,8 @@
     "test:conformance:real": "tsx tests/conformance.real.ts",
     "bench:graph": "node scripts/bench-graph.mjs",
     "pack:dry-run": "npm pack --dry-run --cache .tmp-nexus-ai-tests/npm-cache",
-    "check": "npm run format:check && npm run registry:check && npm run lint && npm test && npm run typecheck:tests && npm run typecheck:examples && npm run typecheck:examples:browser && npm run test:coverage",
-    "check:release": "npm run check && npm run bench:graph && npm run pack:dry-run && npm run test:clean-install",
+    "check": "npm run format:check && npm run registry:check && npm run lint && npm test && npm run typecheck:tests && npm run studio:typecheck && npm run typecheck:examples && npm run typecheck:examples:browser && npm run test:coverage",
+    "check:release": "npm run check && npm run bench:graph && npm run pack:dry-run && npm run test:clean-install && npm run test:studio-install",
     "prepack": "npm run build",
     "prepublishOnly": "npm run check:release",
     "build:esm": "tsc --removeComments --declaration false && tsc --emitDeclarationOnly",