@adonis-agora/agent 0.17.0 → 0.19.0

package/dist/src/mcp/auth.d.ts

@@ -0,0 +1,90 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import type { Actor } from '../types.js';
+/**
+ * Runtime context a {@link McpAuthFactory} thunk receives when the MCP provider builds the configured
+ * auth at boot. Carries the booted application so a driver can resolve a peer's service if it needs to.
+ */
+export interface McpAuthContext {
+    app: ApplicationService;
+}
+/**
+ * OAuth metadata the MCP server advertises at `/.well-known/oauth-protected-resource{path}` (RFC 9728)
+ * so an MCP client can discover how to obtain a token. Omitted → the server exposes no OAuth metadata
+ * endpoint and clients must authenticate another way (e.g. a static API key).
+ */
+export interface McpOAuthMetadata {
+    /** The OAuth 2.0 / OIDC authorization server (the authkit issuer, e.g. `http://localhost:3333/oidc`). */
+    issuer: string;
+    /** Authorization endpoint the MCP client redirects to (e.g. `${issuer}/auth`). */
+    authorizationEndpoint: string;
+    /** Token endpoint the MCP client exchanges the code at (e.g. `${issuer}/token`). */
+    tokenEndpoint: string;
+    /** Scopes supported by the authorization server. */
+    scopesSupported: string[];
+    /** Human label for the protected resource. */
+    resourceName: string;
+}
+/**
+ * A configured MCP auth strategy. `verify` validates a bearer token and resolves the acting {@link Actor}
+ * (attached to `AuthInfo.extra.actor`); it MUST throw when the token is missing/invalid/expired. The
+ * same `AuthInfo` is surfaced to the `tools/list` / `tools/call` handlers as `extra.authInfo`, so the
+ * actor the tool registry gates against is exactly the one the auth strategy resolved.
+ */
+export interface McpAuth {
+    /** OAuth metadata to advertise, resolved lazily (the authkit peer may not be bootable until first use). */
+    oauth?: McpOAuthMetadata | (() => McpOAuthMetadata | Promise<McpOAuthMetadata>);
+    /** Validate `token` and resolve the acting actor. Throws `Error` on rejection. */
+    verify(token: string): Promise<AuthInfo>;
+}
+/**
+ * A configured MCP auth strategy, as a lazy thunk the provider calls at boot. Each factory lazily
+ * imports / resolves its peer inside the thunk, so nothing loads until the strategy is actually selected.
+ */
+export type McpAuthFactory = (ctx: McpAuthContext) => McpAuth | Promise<McpAuth>;
+/**
+ * Resolve a `McpAuth` config value (a ready instance or a lazy factory) at provider boot.
+ */
+export declare function resolveMcpAuth(auth: McpAuth | McpAuthFactory, ctx: McpAuthContext): Promise<McpAuth>;
+/** How `authKitAuth()` maps an access token to the MCP actor. Defaults to the account id. */
+export type AuthKitActorResolver = (info: {
+    accountId: string;
+    scopes: string[];
+    clientId: string | undefined;
+}) => Actor | Promise<Actor>;
+/** Options for {@link authKitAuth}. */
+export interface AuthKitMcpAuthOptions {
+    /** Scopes the authorization server advertises. Defaults to the standard authkit scopes. */
+    scopes?: string[];
+    /** Map a validated access token to the acting {@link Actor}. Defaults to `{ id: accountId }`. */
+    toActor?: AuthKitActorResolver;
+    /** Human label for the protected resource. Defaults to `'Agent MCP Server'`. */
+    resourceName?: string;
+}
+/**
+ * Authenticate MCP clients with `@adonis-agora/authkit-server`: verifies the bearer token against the
+ * authkit OIDC provider's stored access tokens (`provider.AccessToken.find`) and advertises OAuth
+ * metadata derived from the issuer so MCP clients can run the full OAuth login flow.
+ *
+ * The authkit peer is resolved lazily — the `verify`/`oauth` accessors touch the container only when
+ * a request actually arrives (by then the app is fully booted and the authkit keystore/encryption
+ * services are ready). `@adonis-agora/authkit-server` stays an optional dependency. Throws a clear
+ * error at first use if the binding isn't resolvable (authkit not installed / provider not registered).
+ */
+export declare function authKitAuth(options?: AuthKitMcpAuthOptions): McpAuthFactory;
+/** Resolve the MCP actor from a validated API key. Defaults to `{ id: apiKey }`. */
+export type ApiKeyActorResolver = (apiKey: string) => Actor | Promise<Actor>;
+/** Options for {@link apiKeyAuth}. */
+export interface ApiKeyMcpAuthOptions {
+    /** Static API keys clients present in `Authorization: Bearer <key>`. */
+    apiKeys: string[];
+    /** Map a validated API key to the acting {@link Actor}. Defaults to `{ id: apiKey }`. */
+    toActor?: ApiKeyActorResolver;
+}
+/**
+ * Authenticate MCP clients with a static list of API keys (no OAuth metadata). Intended for trusted
+ * gateway / machine-to-machine integrations where the host proxies auth and this server just
+ * checks the key. Keys are compared with a constant-time compare to resist timing attacks.
+ */
+export declare function apiKeyAuth(options: ApiKeyMcpAuthOptions): McpAuthFactory;
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/mcp/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/mcp/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gDAAgD,CAAC;AAC/E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,kBAAkB,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yGAAyG;IACzG,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,2GAA2G;IAC3G,KAAK,CAAC,EAAE,gBAAgB,GAAG,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAChF,kFAAkF;IAClF,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEjF;;GAEG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,OAAO,GAAG,cAAc,EAC9B,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,OAAO,CAAC,CAKlB;AAuBD,6FAA6F;AAC7F,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;AAE7B,uCAAuC;AACvC,MAAM,WAAW,qBAAqB;IACpC,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iGAAiG;IACjG,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAgD/E;AAmBD,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;AAE7E,sCAAsC;AACtC,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yFAAyF;IACzF,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAcxE"}

package/dist/src/mcp/auth.js

@@ -0,0 +1,108 @@
+/**
+ * Resolve a `McpAuth` config value (a ready instance or a lazy factory) at provider boot.
+ */
+export async function resolveMcpAuth(auth, ctx) {
+    if (typeof auth === 'function') {
+        return auth(ctx);
+    }
+    return auth;
+}
+/**
+ * Authenticate MCP clients with `@adonis-agora/authkit-server`: verifies the bearer token against the
+ * authkit OIDC provider's stored access tokens (`provider.AccessToken.find`) and advertises OAuth
+ * metadata derived from the issuer so MCP clients can run the full OAuth login flow.
+ *
+ * The authkit peer is resolved lazily — the `verify`/`oauth` accessors touch the container only when
+ * a request actually arrives (by then the app is fully booted and the authkit keystore/encryption
+ * services are ready). `@adonis-agora/authkit-server` stays an optional dependency. Throws a clear
+ * error at first use if the binding isn't resolvable (authkit not installed / provider not registered).
+ */
+export function authKitAuth(options = {}) {
+    const scopes = options.scopes ?? ['openid', 'profile', 'email', 'offline_access', 'roles'];
+    const toActor = options.toActor ?? (({ accountId }) => ({ id: accountId }));
+    return async ({ app }) => {
+        let servicePromise;
+        const getService = () => {
+            servicePromise ??= resolveAuthKitService(app);
+            return servicePromise;
+        };
+        const oauth = async () => {
+            const service = await getService();
+            const issuer = service.config.issuer;
+            return {
+                issuer,
+                authorizationEndpoint: `${issuer}/auth`,
+                tokenEndpoint: `${issuer}/token`,
+                scopesSupported: scopes,
+                resourceName: options.resourceName ?? 'Agent MCP Server',
+            };
+        };
+        return {
+            oauth,
+            async verify(token) {
+                const service = await getService();
+                const at = await service.provider.AccessToken.find(token);
+                if (!at || at.isExpired) {
+                    throw new Error('invalid or expired access token');
+                }
+                const tokenScopes = (at.scope ?? '').split(' ').filter(Boolean);
+                const actor = await toActor({
+                    accountId: at.accountId,
+                    scopes: tokenScopes,
+                    clientId: at.clientId,
+                });
+                return {
+                    token,
+                    clientId: at.clientId ?? '',
+                    scopes: tokenScopes,
+                    ...(at.exp !== undefined ? { expiresAt: at.exp } : {}),
+                    extra: { actor },
+                };
+            },
+        };
+    };
+}
+/**
+ * Resolve the authkit `OidcService` from the container. `@adonis-agora/authkit-server` augments
+ * `ContainerBindings` with `'authkit.server'`, so `make` is fully typed with no cast.
+ */
+async function resolveAuthKitService(app) {
+    try {
+        return await app.container.make('authkit.server');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`[@adonis-agora/agent] \`authKitAuth()\` could not resolve the authkit server (${message}). Is \`@adonis-agora/authkit-server\` installed and its provider registered in adonisrc.ts?`);
+    }
+}
+/**
+ * Authenticate MCP clients with a static list of API keys (no OAuth metadata). Intended for trusted
+ * gateway / machine-to-machine integrations where the host proxies auth and this server just
+ * checks the key. Keys are compared with a constant-time compare to resist timing attacks.
+ */
+export function apiKeyAuth(options) {
+    const keys = new Set(options.apiKeys);
+    const toActor = options.toActor ?? ((apiKey) => ({ id: apiKey }));
+    return async () => {
+        return {
+            async verify(token) {
+                if (![...keys].some((key) => timingSafeEqual(key, token))) {
+                    throw new Error('invalid API key');
+                }
+                const actor = await toActor(token);
+                return { token, clientId: token, scopes: [], extra: { actor } };
+            },
+        };
+    };
+}
+/** Constant-time string comparison (no `node:crypto` import at module top to keep the browser-safe build). */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return diff === 0;
+}
+//# sourceMappingURL=auth.js.map

package/dist/src/mcp/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/mcp/auth.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp/define_config.d.ts

@@ -0,0 +1,64 @@
+import type { RolesPolicy } from '../spi/roles-policy.js';
+import { apiKeyAuth, authKitAuth } from './auth.js';
+import type { McpAuth, McpAuthFactory } from './auth.js';
+/**
+ * Shape of `config/mcp.ts`. The MCP provider exposes the agent's {@link ToolRegistry} over the Model
+ * Context Protocol (Streamable HTTP): `tools/list` mirrors the tools the acting actor may call
+ * (role-filtered), `tools/call` runs them through the registry (role re-check + schema re-validation).
+ *
+ * ```ts
+ * import { defineMcpConfig, authKitAuth } from '@adonis-agora/agent/mcp'
+ *
+ * export default defineMcpConfig({
+ *   name: 'Lumen Agent',
+ *   version: '1.0.0',
+ *   auth: authKitAuth(),
+ *   path: 'mcp',
+ * })
+ * ```
+ */
+export interface McpConfig {
+    /** Server name reported to MCP clients in the initialize handshake. */
+    name: string;
+    /** Server version reported to MCP clients. */
+    version: string;
+    /**
+     * Route prefix the MCP Streamable HTTP endpoint mounts under. Defaults to `'mcp'` (→ `/mcp`).
+     * OAuth metadata (when `auth.oauth` is set) is served at `/.well-known/oauth-protected-resource{path}`.
+     */
+    path?: string;
+    /**
+     * How MCP clients authenticate. Pass a ready {@link McpAuth} or a lazy {@link McpAuthFactory} thunk
+     * (`authKitAuth()` / `apiKeyAuth()`). Omit → the server is open (no bearer check); the acting actor
+     * falls back to `actor`. Fail-closed: with no `auth` AND no `actor`, requests are rejected.
+     */
+    auth?: McpAuth | McpAuthFactory;
+    /**
+     * The acting actor when `auth` is omitted (dev/open mode). Fail-closed default: omitted → requests
+     * are rejected 401. Set it (e.g. `{ id: 'mcp', roles: ['ADMIN'] }`) to let unauthenticated clients
+     * run tools under that identity.
+     */
+    actor?: {
+        id: string;
+        roles?: string[];
+        tenantRef?: string;
+    };
+    /**
+     * Tool authorization gate. Defaults to `DefaultToolAuthorizer(config.defaultRoles ?? ['ADMIN'])` —
+     * same fail-closed default as the agent provider.
+     */
+    authorizer?: RolesPolicy;
+    /** Roles a tool requires when it declares none. Defaults to `['ADMIN']`. */
+    defaultRoles?: string[];
+    /**
+     * Restrict the exposed tools to this allow-list of names. Omit → all tools the acting actor's roles
+     * permit are exposed.
+     */
+    allowedTools?: string[];
+}
+/** Identity helper giving `config/mcp.ts` full type-checking. */
+export declare function defineMcpConfig(config: McpConfig): McpConfig;
+export { authKitAuth, apiKeyAuth };
+export type { McpAuth, McpAuthFactory, McpAuthContext, McpOAuthMetadata, AuthKitMcpAuthOptions, AuthKitActorResolver, ApiKeyMcpAuthOptions, ApiKeyActorResolver, } from './auth.js';
+export { resolveMcpAuth } from './auth.js';
+//# sourceMappingURL=define_config.d.ts.map

package/dist/src/mcp/define_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/mcp/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IAChC;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D;;;OAGG;IACH,UAAU,CAAC,EAAE,WAAW,CAAC;IACzB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAE5D;AAED,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;AACnC,YAAY,EACV,OAAO,EACP,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/mcp/define_config.js

@@ -0,0 +1,8 @@
+import { apiKeyAuth, authKitAuth } from './auth.js';
+/** Identity helper giving `config/mcp.ts` full type-checking. */
+export function defineMcpConfig(config) {
+    return config;
+}
+export { authKitAuth, apiKeyAuth };
+export { resolveMcpAuth } from './auth.js';
+//# sourceMappingURL=define_config.js.map

package/dist/src/mcp/define_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/mcp/define_config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAuDpD,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;AAWnC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/mcp/index.d.ts

@@ -0,0 +1,7 @@
+export { defineMcpConfig } from './define_config.js';
+export { authKitAuth, apiKeyAuth, resolveMcpAuth } from './auth.js';
+export { createMcpServer } from './server.js';
+export type { McpConfig } from './define_config.js';
+export type { McpAuth, McpAuthFactory, McpAuthContext, McpOAuthMetadata, AuthKitMcpAuthOptions, AuthKitActorResolver, ApiKeyMcpAuthOptions, ApiKeyActorResolver, } from './auth.js';
+export type { CreateMcpServerOptions, McpToolContextOptions } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,OAAO,EACP,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/mcp/index.js

@@ -0,0 +1,4 @@
+export { defineMcpConfig } from './define_config.js';
+export { authKitAuth, apiKeyAuth, resolveMcpAuth } from './auth.js';
+export { createMcpServer } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/src/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,47 @@
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { RolesPolicy } from '../spi/roles-policy.js';
+import { ToolRegistry } from '../tool-registry.js';
+import type { Actor } from '../types.js';
+/**
+ * Runtime context a MCP handler synthesizes for {@link ToolRegistry.invoke}: the acting {@link Actor}
+ * comes from the verified auth, and the run/request ids from the MCP request so tool traces map back
+ * to the MCP session.
+ */
+export interface McpToolContextOptions {
+    /** How the actor is resolved from the transport's verified auth info. */
+    actorFromAuth: (authInfo: AuthInfo | undefined) => Actor;
+    /** How run/thread/request ids are derived. Defaults to the MCP session + request ids. */
+    idsFromRequest?: (sessionId: string | undefined, requestId: string | number | undefined) => {
+        threadId: string;
+        runId: string;
+        requestId: string;
+    };
+}
+/** Options for {@link createMcpServer}. */
+export interface CreateMcpServerOptions extends McpToolContextOptions {
+    /** Server name reported in the initialize handshake. */
+    name: string;
+    /** Server version reported in the initialize handshake. */
+    version: string;
+    /** The agent tool registry to expose. */
+    registry: ToolRegistry;
+    /** Tool authorization gate (role re-check happens per call, defense-in-depth). */
+    policy: RolesPolicy;
+    /** Optional allow-list restricting which tools are exposed. */
+    allowedTools?: string[];
+}
+/**
+ * Build a low-level MCP `Server` that exposes the agent's {@link ToolRegistry} over the wire:
+ *
+ * - `tools/list` → `registry.definitionsFor(actor, policy, allowedTools)` — the tools the acting
+ *   actor's roles permit (fail-closed via the same `RolesPolicy` the agent loop uses), converted to
+ *   MCP `Tool` descriptors with JSON-Schema inputs.
+ * - `tools/call` → `registry.invoke(name, args, ctx, policy)` — role re-check + input re-validation
+ *   before the handler runs (the registry's own defense-in-depth), so a stale tool list can never
+ *   bypass the gate.
+ *
+ * Use this in the MCP provider (one server per session, connected to that session's transport).
+ */
+export declare function createMcpServer(options: CreateMcpServerOptions): Server;
+//# sourceMappingURL=server.d.ts.map

package/dist/src/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gDAAgD,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,aAAa,EAAE,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,KAAK,KAAK,CAAC;IACzD,yFAAyF;IACzF,cAAc,CAAC,EAAE,CACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,KACnC;QACH,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAuB,SAAQ,qBAAqB;IACnE,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,QAAQ,EAAE,YAAY,CAAC;IACvB,kFAAkF;IAClF,MAAM,EAAE,WAAW,CAAC;IACpB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AA4CD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAgDvE"}

package/dist/src/mcp/server.js

@@ -0,0 +1,94 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * True for a Zod schema (tags its Standard Schema props with `vendor: 'zod'`). Narrows to the SDK's
+ * `AnyObjectSchema` so `toJsonSchemaCompat` can consume it without a cast.
+ */
+function isZodSchema(schema) {
+    return schema['~standard'].vendor === 'zod';
+}
+/** True when the schema carries the Standard JSON Schema converter (`~standard.jsonSchema.input`). */
+function hasStandardJsonSchema(schema) {
+    const standard = schema['~standard'];
+    if (!('jsonSchema' in standard)) {
+        return false;
+    }
+    const converter = standard.jsonSchema;
+    return (typeof converter === 'object' &&
+        converter !== null &&
+        'input' in converter &&
+        typeof converter.input === 'function');
+}
+/**
+ * Convert a core `StandardSchemaV1` tool schema into the JSON Schema MCP clients see in `tools/list`.
+ * Zod schemas are converted with the SDK's compat helper (handles both v3 and v4); schemas that expose
+ * the Standard JSON Schema extension (Valibot/ArkType/Zod 4) hand their `input()` schema straight
+ * through. Anything else degrades to a permissive object schema — the loop still validates the real
+ * schema on call via `~standard.validate`.
+ */
+function toJsonSchema(schema) {
+    if (isZodSchema(schema)) {
+        return toJsonSchemaCompat(schema);
+    }
+    if (hasStandardJsonSchema(schema)) {
+        return schema['~standard'].jsonSchema.input();
+    }
+    return { type: 'object', properties: {}, additionalProperties: true };
+}
+/**
+ * Build a low-level MCP `Server` that exposes the agent's {@link ToolRegistry} over the wire:
+ *
+ * - `tools/list` → `registry.definitionsFor(actor, policy, allowedTools)` — the tools the acting
+ *   actor's roles permit (fail-closed via the same `RolesPolicy` the agent loop uses), converted to
+ *   MCP `Tool` descriptors with JSON-Schema inputs.
+ * - `tools/call` → `registry.invoke(name, args, ctx, policy)` — role re-check + input re-validation
+ *   before the handler runs (the registry's own defense-in-depth), so a stale tool list can never
+ *   bypass the gate.
+ *
+ * Use this in the MCP provider (one server per session, connected to that session's transport).
+ */
+export function createMcpServer(options) {
+    const { registry, policy, allowedTools, actorFromAuth, idsFromRequest } = options;
+    const server = new Server({ name: options.name, version: options.version }, { capabilities: { tools: {} } });
+    const buildCtx = (authInfo, sessionId) => {
+        const actor = actorFromAuth(authInfo);
+        const ids = idsFromRequest
+            ? idsFromRequest(sessionId, undefined)
+            : {
+                threadId: `mcp:${sessionId ?? actor.id}`,
+                runId: `mcp:${sessionId ?? 'run'}`,
+                requestId: `mcp:${sessionId ?? 'req'}`,
+            };
+        return { actor, ...ids };
+    };
+    server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+        const actor = actorFromAuth(extra.authInfo);
+        const defs = await registry.definitionsFor(actor, policy, allowedTools);
+        return {
+            tools: defs.map((definition) => ({
+                name: definition.name,
+                description: definition.description,
+                inputSchema: toJsonSchema(definition.inputSchema),
+            })),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const ctx = buildCtx(extra.authInfo, extra.sessionId);
+        const { name, arguments: args } = request.params;
+        try {
+            const output = await registry.invoke(name, args ?? {}, ctx, policy);
+            return {
+                content: [
+                    { type: 'text', text: typeof output === 'string' ? output : JSON.stringify(output) },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: message }], isError: true };
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/src/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/mcp/server.ts"],"names":[],"mappings":"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"}

package/dist/src/rag/chunk.d.ts

@@ -3,12 +3,47 @@ export interface ChunkOptions {
     chunkSize?: number;
     /** Characters of overlap carried from the end of one chunk into the next. Default 100. */
     overlap?: number;
+    /**
+     * The record delimiter, when the text has boundaries that *mean* something. Pass it and the chunker
+     * cuts ONLY on this string — never inside a record.
+     *
+     * Prose has no real boundaries, so the default heuristic (paragraph → sentence → word, in the back
+     * half of the window) is the right guess. Machine-shaped text is the opposite case: a spreadsheet
+     * flattened to one field-labelled record per line, a log, a JSONL export. There the boundaries are
+     * known exactly, and a heuristic cut lands mid-record — stranding the half that carries the row
+     * identifier in a different chunk from the half that carries the value, so neither chunk can answer
+     * a question about that row. `separator: '\n'` says "the lines are the records".
+     *
+     * Two consequences worth knowing before you pass it, both by design:
+     *
+     * 1. **`chunkSize` becomes a target, not a cap.** A single record longer than `chunkSize` is emitted
+     *    whole, as its own over-size chunk. It is NOT split, and it does NOT fall back to the prose
+     *    heuristic — a mid-record cut is the exact failure `separator` exists to prevent, so silently
+     *    performing one to respect a size limit would defeat the feature. An over-size chunk is visible
+     *    (you can see the record, and shorten it or raise `chunkSize`); a mangled record is not. It never
+     *    drags its neighbours over the limit either: it always chunks alone.
+     * 2. **`overlap` is spent on whole records.** It stops being a character count and becomes a
+     *    character *budget*, filled with entire trailing records of the previous chunk — as many as fit,
+     *    never a partial one, and never so many that a chunk fails to advance. Half a record is not
+     *    useful context; it is the same mid-record cut by another name. `overlap: 0` carries nothing,
+     *    which is usually what self-contained records want.
+     *
+     * Empty or whitespace-only records are dropped. An empty string is treated as "not passed" (it would
+     * otherwise split every character), leaving the prose path. Omit it and NOTHING changes: the prose
+     * path below is untouched, byte-for-byte, so no existing corpus is re-chunked (and so none has to be
+     * re-embedded).
+     */
+    separator?: string;
 }
 /**
  * Splits text into overlapping chunks for embedding. Greedy up to `chunkSize`, but prefers to break on
  * a paragraph → sentence → word boundary in the back half of the window (so a chunk rarely cuts
  * mid-sentence), then carries `overlap` characters into the next chunk to preserve context across the
  * seam. Pure and deterministic.
+ *
+ * Pass {@link ChunkOptions.separator} for text whose record boundaries are known rather than guessed;
+ * that path cuts only on the separator, and its two deviations (`chunkSize` becomes a target,
+ * `overlap` is spent on whole records) are documented there.
  */
 export declare function chunkText(text: string, options?: ChunkOptions): string[];
 //# sourceMappingURL=chunk.d.ts.map

package/dist/src/rag/chunk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../../src/rag/chunk.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,EAAE,CAuC5E"}
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../../src/rag/chunk.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,EAAE,CA2C5E"}

package/dist/src/rag/chunk.js

@@ -3,10 +3,18 @@
  * a paragraph → sentence → word boundary in the back half of the window (so a chunk rarely cuts
  * mid-sentence), then carries `overlap` characters into the next chunk to preserve context across the
  * seam. Pure and deterministic.
+ *
+ * Pass {@link ChunkOptions.separator} for text whose record boundaries are known rather than guessed;
+ * that path cuts only on the separator, and its two deviations (`chunkSize` becomes a target,
+ * `overlap` is spent on whole records) are documented there.
  */
 export function chunkText(text, options = {}) {
     const chunkSize = options.chunkSize ?? 800;
     const overlap = options.overlap ?? 100;
+    const separator = options.separator;
+    if (separator !== undefined && separator.length > 0) {
+        return chunkRecords(text, separator, chunkSize, overlap);
+    }
     const normalized = text.trim();
     if (normalized.length === 0) {
         return [];
@@ -39,4 +47,56 @@ export function chunkText(text, options = {}) {
     }
     return chunks;
 }
+/**
+ * The {@link ChunkOptions.separator} path: pack WHOLE records into chunks. Records are the atoms here —
+ * no chunk ever contains a fragment of one — so `chunkSize` is honoured by taking fewer records rather
+ * than by cutting one, and `overlap` is honoured by repeating trailing records rather than by repeating
+ * characters. Pure and deterministic; see {@link ChunkOptions.separator} for the two trades.
+ */
+function chunkRecords(text, separator, chunkSize, overlap) {
+    const records = text
+        .split(separator)
+        .map((record) => record.trim())
+        .filter((record) => record.length > 0);
+    if (records.length === 0) {
+        return [];
+    }
+    const chunks = [];
+    let start = 0;
+    while (start < records.length) {
+        // Pack forward while the joined length fits. The FIRST record is taken unconditionally: that is
+        // what emits an over-long record whole instead of cutting it (trade 1).
+        let end = start;
+        let length = 0;
+        while (end < records.length) {
+            const record = records[end] ?? '';
+            const cost = end === start ? record.length : separator.length + record.length;
+            if (end > start && length + cost > chunkSize) {
+                break;
+            }
+            length += cost;
+            end += 1;
+        }
+        chunks.push(records.slice(start, end).join(separator));
+        if (end >= records.length) {
+            break;
+        }
+        // Overlap as a whole-record budget: walk back over trailing records while they fit in `overlap`.
+        // `back > start + 1` keeps at least one record consumed by this chunk, so `start` strictly
+        // increases — an over-long record (which always chunks alone) is therefore never carried forward,
+        // and no `overlap`, however large, can stall the loop.
+        let back = end;
+        let carried = 0;
+        while (back > start + 1) {
+            const cost = (records[back - 1] ?? '').length + separator.length;
+            if (carried + cost > overlap) {
+                break;
+            }
+            carried += cost;
+            back -= 1;
+        }
+        start = back;
+    }
+    return chunks;
+}
 //# sourceMappingURL=chunk.js.map

package/dist/src/rag/chunk.js.map

@@ -1 +1 @@
-{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../../src/rag/chunk.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,UAAwB,EAAE;IAChE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IAC3C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QACnC,OAAO,CAAC,UAAU,CAAC,CAAC;IACtB,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QAC3D,IAAI,OAAO,GAAG,GAAG,CAAC;QAClB,IAAI,GAAG,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CACvB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,EAC1B,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EACxB,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CACxB,CAAC;YACF,uEAAuE;YACvE,IAAI,QAAQ,GAAG,SAAS,GAAG,CAAC,EAAE,CAAC;gBAC7B,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QACtD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;QACD,IAAI,OAAO,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;YACjC,MAAM;QACR,CAAC;QACD,yFAAyF;QACzF,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../../src/rag/chunk.ts"],"names":[],"mappings":"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"}

package/dist/src/rag/index.d.ts

@@ -1,5 +1,5 @@
 export { chunkText, type ChunkOptions } from './chunk.js';
-export { documentIdOf, type IndexedDocument, type VectorRecord, type VectorSearchOptions, type VectorStore, } from './vector-store.js';
+export { applyMetadataPatch, assertRemovalFilter, documentIdOf, effectivePatchKeys, filterDeniesAll, UnsafeRemovalError, type IndexedDocument, type MetadataPatch, type VectorRecord, type VectorSearchOptions, type VectorStore, } from './vector-store.js';
 export { matchesFilter } from './filter.js';
 export { MemoryVectorStore, cosineSimilarity } from './memory-vector-store.js';
 export { EmbeddingRetriever } from './embedding-retriever.js';

package/dist/src/rag/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}