@classytic/arc 2.15.3 → 2.16.0

package/dist/integrations/event-gateway.d.mts

@@ -1,5 +1,5 @@
-import { n as DomainEvent } from "../EventTransport-CT_52aWU.mjs";
-import { a as WebSocketMessage, i as WebSocketClient } from "../websocket-ChC2rqe1.mjs";
+import { n as DomainEvent } from "../EventTransport-C-2oAHtw.mjs";
+import { a as WebSocketMessage, i as WebSocketClient } from "../websocket-BkjeGZRn.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 
 //#region src/integrations/event-gateway.d.ts

package/dist/integrations/event-gateway.mjs

@@ -4,7 +4,7 @@ const eventGatewayPluginImpl = async (fastify, opts = {}) => {
 	const { auth = true, orgScoped = false, roomPolicy, maxMessageBytes, maxSubscriptionsPerClient, authenticate } = opts;
 	if (auth && !authenticate && !fastify.hasDecorator("authenticate")) throw new Error("[arc-event-gateway] auth is true but fastify.authenticate is not registered. Register an auth plugin first, provide a custom authenticate function, or set auth: false.");
 	if (opts.sse !== false) {
-		const { default: ssePlugin } = await import("../sse-Bz-5ZeTt.mjs").then((n) => n.r);
+		const { default: ssePlugin } = await import("../sse-BY6sTy4P.mjs").then((n) => n.r);
 		await fastify.register(ssePlugin, {
 			path: opts.sse?.path ?? "/events/stream",
 			requireAuth: auth,

package/dist/integrations/index.d.mts

@@ -1,7 +1,7 @@
-import { a as WebSocketMessage, i as WebSocketClient, o as WebSocketPluginOptions } from "../websocket-ChC2rqe1.mjs";
+import { a as WebSocketMessage, i as WebSocketClient, o as WebSocketPluginOptions } from "../websocket-BkjeGZRn.mjs";
 import { EventGatewayOptions } from "./event-gateway.mjs";
 import { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, QueueStats } from "./jobs.mjs";
-import { c as McpResourceConfig, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler } from "../types-BQsjgQzS.mjs";
+import { c as McpAuthResult, d as PromptDefinition, g as ToolDefinition, h as ToolContext, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpResourceConfig } from "../types-BsJMEQ4D.mjs";
 import { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike } from "./streamline.mjs";
 import { WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription } from "./webhooks.mjs";
 export { type BetterAuthHandler, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type EventGatewayOptions, type JobDefinition, type JobDispatchOptions, type JobDispatcher, type JobMeta, type JobsPluginOptions, type McpAuthResult, type McpPluginOptions, type McpResourceConfig, type PromptDefinition, type QueueStats, type StreamlinePluginOptions, type ToolAnnotations, type ToolContext, type ToolDefinition, type WebSocketClient, type WebSocketMessage, type WebSocketPluginOptions, type WebhookDeliveryRecord, type WebhookManager, type WebhookPluginOptions, type WebhookStore, type WebhookSubscription, type WorkflowLike, type WorkflowRunLike };

package/dist/integrations/jobs.mjs

@@ -68,8 +68,8 @@ const jobsPluginImpl = async (fastify, options) => {
 		const jobTimeout = job.timeout ?? defaults.timeout;
 		const worker = new Worker(queueName, async (bullJob) => {
 			const meta = {
-				jobId: bullJob.id,
-				attemptsMade: bullJob.attemptsMade,
+				jobId: bullJob.id ?? "",
+				attemptsMade: bullJob.attemptsMade ?? 0,
 				timestamp: Date.now()
 			};
 			let result;
@@ -107,7 +107,7 @@ const jobsPluginImpl = async (fastify, options) => {
 		});
 		worker.on("failed", async (bullJob, error) => {
 			const maxAttempts = job.retries ?? defaults.retries ?? 3;
-			if (dlqQueue && bullJob && bullJob.attemptsMade >= maxAttempts) try {
+			if (dlqQueue && bullJob && (bullJob.attemptsMade ?? 0) >= maxAttempts) try {
 				await dlqQueue.add(`${queueName}:dead`, bullJob.data, {
 					jobId: `${bullJob.id}:dlq`,
 					removeOnComplete: false

package/dist/integrations/mcp/index.d.mts

@@ -1,5 +1,8 @@
-import { V as ResourceDefinition } from "../../index-BswOSJCE.mjs";
-import { a as McpAuthResolver, c as McpResourceConfig, d as SessionEntry, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler, u as PromptResult } from "../../types-BQsjgQzS.mjs";
+import { V as ResourceDefinition, bt as IRequestContext, yt as IControllerResponse } from "../../index-CkW0flkU.mjs";
+import { i as RequestScope } from "../../types-DVfpSfx2.mjs";
+import { c as PermissionCheck } from "../../fields-Anj0xdih.mjs";
+import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-BsJMEQ4D.mjs";
+import { ErrorContract } from "@classytic/repo-core/errors";
 import { FastifyPluginAsync } from "fastify";
 import { z } from "zod";
 
@@ -74,6 +77,30 @@ interface McpServerInstance {
   resource: (...args: unknown[]) => void;
 }
 //#endregion
+//#region src/integrations/mcp/crud-tools.d.ts
+/**
+ * Default description for a CRUD tool. Enriches list descriptions with the
+ * configured filter/sort metadata so MCP clients can see what's queryable
+ * without reading the resource source.
+ *
+ * Exposed publicly so authors using the function-form `descriptions`
+ * override can call this from their own override to keep the auto-derived
+ * blurb intact and only append extra context.
+ */
+declare function defaultCrudDescription(op: CrudOperation, displayName: string, softDelete: boolean, queryMeta?: {
+  filterableFields?: readonly string[];
+  allowedOperators?: readonly string[];
+  sortableFields?: readonly string[];
+}): string;
+/**
+ * Resolve a {@link CrudDescriptionOverride} (string or function) into a
+ * concrete description. Centralises the function-form contract so every
+ * call site that consumes an override applies it the same way.
+ *
+ * Falls back to {@link defaultCrudDescription} when no override is set.
+ */
+declare function resolveCrudDescription(override: CrudDescriptionOverride | undefined, meta: CrudDescriptionMeta): string;
+//#endregion
 //#region src/integrations/mcp/definePrompt.d.ts
 /** definePrompt() config */
 interface DefinePromptConfig<TArgs extends Record<string, z.ZodTypeAny>> {
@@ -92,8 +119,15 @@ interface DefinePromptConfig<TArgs extends Record<string, z.ZodTypeAny>> {
 declare function definePrompt<TArgs extends Record<string, z.ZodTypeAny>>(name: string, config: DefinePromptConfig<TArgs>): PromptDefinition;
 //#endregion
 //#region src/integrations/mcp/defineTool.d.ts
-/** defineTool() config — uses flat Zod shapes for SDK compatibility */
-interface DefineToolConfig<TInput extends Record<string, z.ZodTypeAny>> {
+/**
+ * defineTool() config — uses flat Zod shapes for SDK compatibility.
+ *
+ * The `TSession` parameter widens `ctx.session` to a host-specific shape.
+ * Pass an interface that extends `McpAuthResult` (or one that omits it
+ * entirely for custom auth resolvers) to drop the `as any` casts that
+ * pre-2.15.5 handlers needed when reading session fields.
+ */
+interface DefineToolConfig<TInput extends Record<string, z.ZodTypeAny>, TSession = McpAuthResult> {
   description: string;
   title?: string;
   /** Flat Zod shape: `{ name: z.string(), age: z.number() }` */
@@ -101,7 +135,7 @@ interface DefineToolConfig<TInput extends Record<string, z.ZodTypeAny>> {
   /** Flat Zod shape for structured output */
   output?: Record<string, z.ZodTypeAny>;
   annotations?: ToolAnnotations;
-  handler: (input: { [K in keyof TInput]: z.infer<TInput[K]> }, ctx: ToolContext) => Promise<CallToolResult>;
+  handler: (input: { [K in keyof TInput]: z.infer<TInput[K]> }, ctx: ToolContext<TSession>) => Promise<CallToolResult>;
 }
 /**
  * Define a type-safe MCP tool.
@@ -109,7 +143,7 @@ interface DefineToolConfig<TInput extends Record<string, z.ZodTypeAny>> {
  * @param name - Tool name (snake_case recommended)
  * @param config - Tool description, input schema, annotations, handler
  */
-declare function defineTool<TInput extends Record<string, z.ZodTypeAny>>(name: string, config: DefineToolConfig<TInput>): ToolDefinition;
+declare function defineTool<TInput extends Record<string, z.ZodTypeAny>, TSession = McpAuthResult>(name: string, config: DefineToolConfig<TInput, TSession>): ToolDefinition<TSession>;
 //#endregion
 //#region src/integrations/mcp/fieldRulesToZod.d.ts
 interface FieldRulesToZodOptions {
@@ -202,6 +236,121 @@ declare function requireOrgId(orgId: string): McpGuard;
  */
 declare function customGuard(check: (ctx: ToolContext) => boolean | Promise<boolean>, errorMessage: string): McpGuard;
 //#endregion
+//#region src/integrations/mcp/buildRequestContext.d.ts
+type McpOperation = "list" | "get" | "create" | "update" | "delete" | "action";
+/**
+ * Build an IRequestContext from MCP tool input and session auth.
+ *
+ * | Operation | params     | query                | body                |
+ * |-----------|------------|----------------------|---------------------|
+ * | list      | {}         | all input fields     | undefined           |
+ * | get       | { id }     | {}                   | undefined           |
+ * | create    | {}         | {}                   | all input fields    |
+ * | update    | { id }     | {}                   | input minus id      |
+ * | delete    | { id }     | {}                   | undefined           |
+ *
+ * **scopeOverride** — when a permission check (e.g. `requireApiKey()`) returns
+ * `PermissionResult.scope`, the MCP tool handler must install it on the request
+ * context the same way CRUD/action routes do. This parameter follows the exact
+ * same non-downgrade rule as `applyPermissionResult`: it overrides only when
+ * the session-derived scope is `public` (i.e. MCP called with `auth: false`).
+ * An authenticated session scope is never overwritten.
+ */
+declare function buildRequestContext(input: Record<string, unknown>, auth: McpAuthResult | null, operation: McpOperation, policyFilters?: Record<string, unknown>, scopeOverride?: RequestScope): IRequestContext;
+//#endregion
+//#region src/integrations/mcp/invokeController.d.ts
+/**
+ * Options threaded into {@link invokeController}. `session` is required so
+ * permission checks and scope resolution can both honor the caller's
+ * identity; everything else is optional and falls back to sensible defaults.
+ */
+interface InvokeControllerOptions {
+  /** Resolved identity for this invocation — `null` runs as public scope. */
+  readonly session: McpAuthResult | null;
+  /** Resource name surfaced into the permission context (`PermissionContext.resource`). */
+  readonly resourceName: string;
+  /**
+   * Logical action name surfaced into the permission context
+   * (`PermissionContext.action`). Defaults to `op` — pass a distinct name
+   * for custom routes / declarative actions to keep audit logs readable.
+   */
+  readonly actionName?: string;
+  /**
+   * Permission to evaluate before invoking the controller. `undefined` means
+   * "no gate" — same semantics as CRUD without a declared `permissions.<op>`.
+   * Authors that want fail-closed behavior should pass `requireAuth()` or a
+   * concrete role gate; `allowPublic()` documents an intentional opt-out.
+   */
+  readonly permissions?: PermissionCheck;
+  /**
+   * Method name on the controller. Defaults to `op`. Override for custom-route
+   * dispatch where the method name differs from the MCP operation (e.g. an
+   * action handler reached through a `string` route handler).
+   */
+  readonly methodName?: string;
+}
+/**
+ * Invoke a controller method through the MCP synthetic-context path.
+ *
+ * Runs the same chain CRUD MCP tools run:
+ *   1. {@link evaluatePermission} — fails with the canonical
+ *      `arc.unauthorized` / `arc.forbidden` `CallToolResult` shape on denial.
+ *   2. {@link buildRequestContext} — projects MCP input + session into
+ *      `IRequestContext`. Permission `filters` / `scope` thread through
+ *      identically to CRUD/action routes.
+ *   3. `controller[methodName](ctx)` — dispatch. Errors are routed through
+ *      `toCallToolError` so `ArcError` / `HttpError` throws land as the same
+ *      `ErrorContract` shape an HTTP client would see.
+ *
+ * @example Run a controller op from a custom MCP tool.
+ * ```ts
+ * defineTool('promote_post', {
+ *   description: 'Promote a draft to published',
+ *   inputSchema: { id: z.string() },
+ *   handler: (input, ctx) =>
+ *     invokeController(postController, 'update', { ...input, status: 'published' }, {
+ *       session: ctx.session,
+ *       resourceName: 'post',
+ *       permissions: requireRoles(['editor']),
+ *     }),
+ * });
+ * ```
+ *
+ * Workflow / scheduled-job callers pass a synthetic `session` they
+ * constructed from the job's owning identity — the shape is the same
+ * `McpAuthResult` the HTTP MCP plugin produces, so the same permission
+ * checks compose.
+ */
+declare function invokeController(controller: unknown, op: McpOperation, input: Record<string, unknown>, options: InvokeControllerOptions): Promise<CallToolResult>;
+/**
+ * Wrap an async function as a {@link ToolDefinition} handler — handles the
+ * try/catch → canonical-error translation in one place so MCP tools that
+ * compose multiple internal calls don't reimplement the boilerplate.
+ *
+ * The wrapped function may return:
+ *  - A `CallToolResult` — passed through unchanged (use this to short-circuit
+ *    with `permissionDeniedResult` or a custom error shape).
+ *  - An `IControllerResponse` envelope (`{ data, meta?, status?, headers? }`)
+ *    — serialised via `toCallToolResult` so pagination meta etc. survive.
+ *  - Any other value — serialised as JSON via `toCallToolSuccess` semantics.
+ *
+ * Errors raised inside the function are caught and routed through
+ * `toCallToolError`, so `ArcError` / `HttpError` throws collapse to the
+ * canonical `ErrorContract` shape MCP agents see for every other surface.
+ *
+ * @example Compose two controller calls in one tool.
+ * ```ts
+ * defineTool('archive_and_log', {
+ *   description: '...',
+ *   handler: mcpHandlerAdapter(async (input, ctx) => {
+ *     await invokeController(postController, 'update', { ...input, archived: true }, opts);
+ *     return invokeController(auditController, 'create', { event: 'archive', ...input }, opts);
+ *   }),
+ * });
+ * ```
+ */
+declare function mcpHandlerAdapter<TSession = McpAuthResult>(fn: (input: Record<string, unknown>, ctx: ToolContext<TSession>) => Promise<unknown>): ToolDefinition<TSession>["handler"];
+//#endregion
 //#region src/integrations/mcp/sessionCache.d.ts
 declare class McpSessionCache {
   private sessions;
@@ -261,6 +410,37 @@ declare module "fastify" {
     mcp?: McpDecorator;
   }
 }
+interface ResourceFilterInputs {
+  readonly expose?: readonly string[];
+  readonly include?: readonly string[];
+  readonly exclude?: readonly string[];
+}
+/**
+ * Resolve `expose` / `include` / `exclude` into the filtered resource list
+ * `mcpPlugin` should surface. Three mutually exclusive intents:
+ *
+ *  - `expose`: default-deny allowlist (preferred — new resources auto-deny).
+ *  - `include`: legacy alias for `expose`, kept for back-compat.
+ *  - `exclude`: default-allow opt-out (drift-prone — new resources auto-leak).
+ *
+ * Conflicting combinations throw with an actionable message so a host that
+ * accidentally mixed paradigms fails at boot instead of silently leaking or
+ * starving the LLM surface.
+ *
+ * **Local opt-out wins.** Any resource declared with
+ * `defineResource({ mcp: false })` is dropped FIRST, before any of the
+ * plugin-level allowlists/blocklists run. The opt-out is colocated with
+ * the resource definition, so adding a new "never-expose" resource is
+ * a single-file change instead of a host-wide blocklist update that
+ * drifts as the codebase grows.
+ *
+ * Exported so `mcp/testing.ts` and external test harnesses can apply the
+ * same precedence rules without duplicating them.
+ */
+declare function filterResourcesForMcp<T extends {
+  name: string;
+  mcp?: boolean;
+}>(resources: readonly T[], inputs: ResourceFilterInputs): T[];
 declare const mcpPlugin: FastifyPluginAsync<McpPluginOptions>;
 //#endregion
 //#region src/integrations/mcp/resourceToTools.d.ts
@@ -284,4 +464,56 @@ interface ResourceToToolsConfig extends McpResourceConfig {
  */
 declare function resourceToTools(resource: ResourceDefinition, config?: ResourceToToolsConfig): ToolDefinition[];
 //#endregion
-export { type AuthRef, type BetterAuthHandler, type BuildMcpToolsFromBridgesOptions, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type FieldRuleEntry, type FieldRulesToZodOptions, type McpAuthResolver, type McpAuthResult, type McpBridge, type McpGuard, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, bridgeToMcp, buildMcpToolsFromBridges, createMcpServer, customGuard, definePrompt, defineTool, denied, fieldRulesToZod, getOrgId, getUserId, guard, hasOrg, isAuthenticated, isOrg, mcpPlugin, requireAuth, requireOrg, requireOrgId, requireRole, resourceToTools };
+//#region src/integrations/mcp/tool-helpers.d.ts
+/**
+ * Convert a controller response envelope into an MCP `CallToolResult`.
+ * Carries `meta` into the serialized payload so consumers see pagination
+ * totals, stripped-field arrays, etc.
+ *
+ * Errors are not represented here — controllers throw `ArcError` and the
+ * MCP tool wrapper catches them via {@link toCallToolError}.
+ */
+declare function toCallToolResult(result: IControllerResponse): CallToolResult;
+/**
+ * Wrap a raw success payload as an MCP `CallToolResult`. Use when the
+ * tool produced a value directly (action handler return, aggregation
+ * rows, etc.) instead of an `IControllerResponse` envelope.
+ *
+ * Emits the value as JSON with no envelope — same no-envelope contract
+ * the HTTP wire follows. The `isError: true` flag on `CallToolResult`
+ * is the success/error discriminant for MCP, mirroring HTTP status.
+ */
+declare function toCallToolSuccess(value: unknown): CallToolResult;
+/**
+ * Wrap an error as an MCP `CallToolResult` with the canonical
+ * `ErrorContract` shape inside the text payload. Single source of truth
+ * for MCP error serialization — every tool surface (CRUD, action, route,
+ * aggregation) routes through here so the JSON shape an agent sees is
+ * identical to what an HTTP client sees.
+ *
+ * Accepts:
+ *  - An `ArcError` (or any `HttpError`-shaped throw) → routes through
+ *    `toErrorContract()` for the canonical conversion.
+ *  - A partial contract `{code, message, status, details?}` → used as-is.
+ *  - Any other `Error` → falls back to `arc.internal_error` 500.
+ */
+declare function toCallToolError(input: Error | {
+  code: string;
+  message: string;
+  status?: number;
+  details?: ErrorContract["details"];
+}): CallToolResult;
+/**
+ * Build the canonical permission-denied `CallToolResult` for an MCP
+ * tool. Discriminates 401 (no session — "Authentication required") from
+ * 403 (session present, denied — "Permission denied"). Mirrors the
+ * status split the HTTP `errorHandler` plugin uses.
+ */
+declare function permissionDeniedResult(args: {
+  resource: string;
+  operation: string;
+  reason?: string;
+  session: McpAuthResult | null;
+}): CallToolResult;
+//#endregion
+export { type AuthRef, type BetterAuthHandler, type BuildMcpToolsFromBridgesOptions, type CallToolResult, type CreateMcpServerConfig, type CrudDescriptionMeta, type CrudDescriptionOverride, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type FieldRuleEntry, type FieldRulesToZodOptions, type InvokeControllerOptions, type McpAuthResolver, type McpAuthResult, type McpBridge, type McpGuard, type McpOperation, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };