apcore-mcp 0.14.0 → 0.16.0

package/dist/markdown.js

@@ -0,0 +1,125 @@
+/**
+ * Markdown rendering for apcore modules via apcore-toolkit.
+ *
+ * LLMs read MCP/OpenAI tool `description` strings as their primary
+ * signal for tool selection — the richer the description, the better
+ * the agent picks the right tool. apcore-toolkit's
+ * `formatModule({ style: "markdown" })` emits a canonical, cross-SDK
+ * byte-equivalent rendering with title, description, parameters list,
+ * returns list, behavior table, tags, and examples.
+ *
+ * This module bridges apcore's `ModuleDescriptor` (the runtime type
+ * flowing through apcore-mcp) to apcore-toolkit's `ScannedModule`
+ * (the input format `formatModule` expects), then delegates.
+ *
+ * apcore-toolkit is an OPTIONAL peer dependency in package.json (it
+ * appears under `optionalDependencies`). Callers must check
+ * {@link isMarkdownAvailable} before invoking
+ * {@link renderModuleMarkdown}.
+ */
+let _toolkit;
+let _toolkitLoaded = false;
+async function loadToolkit() {
+    if (_toolkitLoaded)
+        return _toolkit ?? null;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod = (await import("apcore-toolkit"));
+        const formatModule = mod.formatModule ?? mod.default?.formatModule;
+        if (typeof formatModule === "function") {
+            _toolkit = { formatModule };
+        }
+        else {
+            _toolkit = null;
+        }
+    }
+    catch {
+        _toolkit = null;
+    }
+    _toolkitLoaded = true;
+    return _toolkit ?? null;
+}
+/**
+ * Synchronous availability check using a side-effect-free flag set by
+ * {@link primeMarkdownToolkit}. Returns false until the toolkit has been
+ * primed; callers that need to check before the first async render should
+ * `await primeMarkdownToolkit()` at startup.
+ */
+export function isMarkdownAvailable() {
+    return _toolkitLoaded && _toolkit !== null;
+}
+/**
+ * Eagerly load apcore-toolkit so subsequent {@link isMarkdownAvailable}
+ * checks return synchronously. Safe to call multiple times — the import
+ * resolves to the same cached module.
+ */
+export async function primeMarkdownToolkit() {
+    await loadToolkit();
+    return isMarkdownAvailable();
+}
+/**
+ * Adapt an apcore `ModuleDescriptor` to a toolkit `ScannedModule`-shaped
+ * object. The two types are near-supersets — overlapping fields are
+ * copied verbatim, toolkit-only fields (`target`, `documentation`,
+ * `suggestedAlias`, `warnings`) get sensible defaults.
+ *
+ * Note: apcore-mcp's `ModuleDescriptor` uses snake_case
+ * (`module_id`, `input_schema`); apcore-toolkit's `ScannedModule` uses
+ * camelCase (`moduleId`, `inputSchema`). We rename here.
+ */
+function descriptorToScannedModule(descriptor) {
+    // The TS `ModuleDescriptor` type doesn't declare a `display` field
+    // (apcore-mcp-typescript predates apcore 0.19.0's display overlay)
+    // but real instances coming from apcore-js may carry one — read it
+    // through an index lookup so we don't lose the overlay when present.
+    const display = descriptor.display ?? null;
+    return {
+        moduleId: descriptor.moduleId,
+        description: descriptor.description ?? "",
+        inputSchema: descriptor.inputSchema ?? {},
+        outputSchema: descriptor.outputSchema ?? {},
+        tags: [...(descriptor.tags ?? [])],
+        target: "",
+        version: descriptor.version ?? "1.0.0",
+        annotations: descriptor.annotations ?? null,
+        documentation: descriptor.documentation ?? null,
+        suggestedAlias: null,
+        examples: [...(descriptor.examples ?? [])],
+        metadata: { ...(descriptor.metadata ?? {}) },
+        display,
+        warnings: [],
+    };
+}
+/**
+ * Render a `ModuleDescriptor` as canonical apcore-toolkit Markdown.
+ *
+ * Returns `null` when the toolkit hasn't been primed yet — callers that want
+ * Markdown rendering inside synchronous code paths (like
+ * `MCPServerFactory.buildTool`) MUST `await primeMarkdownToolkit()` during
+ * their async startup so the cached reference is populated.
+ *
+ * Once primed, this function is a thin sync wrapper around `formatModule`
+ * (which is itself synchronous in apcore-toolkit-js). Returns the Markdown
+ * body — title, description, parameters list, returns list, behavior table
+ * (toolkit 0.6.x emits only fields that differ from defaults), tags, and
+ * examples.
+ *
+ * Returns `null` (not an error) when apcore-toolkit is not installed, so
+ * callers can fall back to plain `descriptor.description`.
+ */
+export function renderModuleMarkdownSync(descriptor, options = {}) {
+    if (!_toolkitLoaded || !_toolkit)
+        return null;
+    const scanned = descriptorToScannedModule(descriptor);
+    try {
+        const rendered = _toolkit.formatModule(scanned, {
+            style: "markdown",
+            display: options.display ?? true,
+        });
+        return typeof rendered === "string" ? rendered : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=markdown.js.map

package/dist/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkBH,IAAI,QAA0C,CAAC;AAC/C,IAAI,cAAc,GAAG,KAAK,CAAC;AAE3B,KAAK,UAAU,WAAW;IACxB,IAAI,cAAc;QAAE,OAAO,QAAQ,IAAI,IAAI,CAAC;IAC5C,IAAI,CAAC;QACH,8DAA8D;QAC9D,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAQ,CAAC;QACpD,MAAM,YAAY,GAAG,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC;QACnE,IAAI,OAAO,YAAY,KAAK,UAAU,EAAE,CAAC;YACvC,QAAQ,GAAG,EAAE,YAAY,EAAE,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IACD,cAAc,GAAG,IAAI,CAAC;IACtB,OAAO,QAAQ,IAAI,IAAI,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,cAAc,IAAI,QAAQ,KAAK,IAAI,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,WAAW,EAAE,CAAC;IACpB,OAAO,mBAAmB,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,yBAAyB,CAChC,UAA4B;IAE5B,mEAAmE;IACnE,mEAAmE;IACnE,mEAAmE;IACnE,qEAAqE;IACrE,MAAM,OAAO,GACV,UAAsE,CAAC,OAAO,IAAI,IAAI,CAAC;IAC1F,OAAO;QACL,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,EAAE;QACzC,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,EAAE;QACzC,YAAY,EAAE,UAAU,CAAC,YAAY,IAAI,EAAE;QAC3C,IAAI,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAClC,MAAM,EAAE,EAAE;QACV,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,OAAO;QACtC,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,IAAI;QAC3C,aAAa,EAAE,UAAU,CAAC,aAAa,IAAI,IAAI;QAC/C,cAAc,EAAE,IAAI;QACpB,QAAQ,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;QAC1C,QAAQ,EAAE,EAAE,GAAG,CAAC,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE;QAC5C,OAAO;QACP,QAAQ,EAAE,EAAE;KACb,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAA4B,EAC5B,UAAiC,EAAE;IAEnC,IAAI,CAAC,cAAc,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,OAAO,GAAG,yBAAyB,CAAC,UAAU,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,OAAO,EAAE;YAC9C,KAAK,EAAE,UAAU;YACjB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI;SACjC,CAAC,CAAC;QACH,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/server/approval-bridge.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ApprovalBridge: exposes __apcore_approval_check as an MCP meta-tool.
+ *
+ * Symmetric with AsyncTaskBridge. Registered in MCPServerFactory.registerHandlers()
+ * alongside asyncBridge.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const APPROVAL_META_TOOL_NAMES: readonly ["__apcore_approval_check"];
+export type ApprovalMetaToolName = (typeof APPROVAL_META_TOOL_NAMES)[number];
+export declare class ApprovalBridge {
+    private readonly handler;
+    constructor(handler: {
+        checkApproval(approvalId: string): Promise<{
+            status: string;
+            reason?: string;
+            approvalId?: string;
+        }>;
+    });
+    static isMetaTool(name: string): name is ApprovalMetaToolName;
+    buildMetaTools(): Tool[];
+    handleMetaTool(name: string, arguments_: Record<string, unknown>): Promise<[Array<{
+        type: string;
+        text: string;
+    }>, boolean, string | null]>;
+    private handleCheck;
+}
+//# sourceMappingURL=approval-bridge.d.ts.map

package/dist/server/approval-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-bridge.d.ts","sourceRoot":"","sources":["../../src/server/approval-bridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAE/D,eAAO,MAAM,wBAAwB,sCAAuC,CAAC;AAE7E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,qBAAa,cAAc;IAEb,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE;QACpC,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACtG;IAED,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,oBAAoB;IAI7D,cAAc,IAAI,IAAI,EAAE;IAyBlB,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;YAW7D,WAAW;CAiC1B"}

package/dist/server/approval-bridge.js

@@ -0,0 +1,77 @@
+export const APPROVAL_META_TOOL_NAMES = ["__apcore_approval_check"];
+export class ApprovalBridge {
+    handler;
+    // handler is StorageBackedApprovalHandler but typed loosely for cross-SDK compat
+    constructor(handler) {
+        this.handler = handler;
+    }
+    static isMetaTool(name) {
+        return APPROVAL_META_TOOL_NAMES.includes(name);
+    }
+    buildMetaTools() {
+        return [
+            {
+                name: "__apcore_approval_check",
+                description: "Poll the status of a pending approval request. " +
+                    "Returns {approval_id, status, reason}. " +
+                    "status is 'pending', 'approved', or 'rejected'. " +
+                    "When 'approved', retry the original tool call with " +
+                    "_meta.approvalId set to this approval_id.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        approval_id: {
+                            type: "string",
+                            description: "The approval_id from the APPROVAL_PENDING response",
+                        },
+                    },
+                    required: ["approval_id"],
+                    additionalProperties: false,
+                },
+            },
+        ];
+    }
+    async handleMetaTool(name, arguments_) {
+        if (name === "__apcore_approval_check") {
+            return this.handleCheck(arguments_);
+        }
+        return [
+            [{ type: "text", text: `Unknown approval meta-tool: ${name}` }],
+            true,
+            null,
+        ];
+    }
+    async handleCheck(args) {
+        const approvalId = args["approval_id"];
+        if (typeof approvalId !== "string" || !approvalId) {
+            return [
+                [{ type: "text", text: "approval_id is required" }],
+                true,
+                null,
+            ];
+        }
+        try {
+            const result = await this.handler.checkApproval(approvalId);
+            const payload = {
+                approval_id: approvalId,
+                status: result.status,
+            };
+            if (result.reason !== undefined) {
+                payload["reason"] = result.reason;
+            }
+            return [
+                [{ type: "text", text: JSON.stringify(payload) }],
+                false,
+                null,
+            ];
+        }
+        catch (err) {
+            return [
+                [{ type: "text", text: `Approval check failed: ${String(err)}` }],
+                true,
+                null,
+            ];
+        }
+    }
+}
+//# sourceMappingURL=approval-bridge.js.map

package/dist/server/approval-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-bridge.js","sourceRoot":"","sources":["../../src/server/approval-bridge.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,yBAAyB,CAAU,CAAC;AAI7E,MAAM,OAAO,cAAc;IAEI;IAD7B,iFAAiF;IACjF,YAA6B,OAE5B;QAF4B,YAAO,GAAP,OAAO,CAEnC;IAAG,CAAC;IAEL,MAAM,CAAC,UAAU,CAAC,IAAY;QAC5B,OAAQ,wBAA8C,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxE,CAAC;IAED,cAAc;QACZ,OAAO;YACL;gBACE,IAAI,EAAE,yBAAyB;gBAC/B,WAAW,EACT,iDAAiD;oBACjD,yCAAyC;oBACzC,kDAAkD;oBAClD,qDAAqD;oBACrD,2CAA2C;gBAC7C,WAAW,EAAE;oBACX,IAAI,EAAE,QAAiB;oBACvB,UAAU,EAAE;wBACV,WAAW,EAAE;4BACX,IAAI,EAAE,QAAQ;4BACd,WAAW,EAAE,oDAAoD;yBAClE;qBACF;oBACD,QAAQ,EAAE,CAAC,aAAa,CAAC;oBACzB,oBAAoB,EAAE,KAAK;iBAC5B;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,IAAY,EACZ,UAAmC;QAEnC,IAAI,IAAI,KAAK,yBAAyB,EAAE,CAAC;YACvC,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;QACtC,CAAC;QACD,OAAO;YACL,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,+BAA+B,IAAI,EAAE,EAAE,CAAC;YAC/D,IAAI;YACJ,IAAI;SACL,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,WAAW,CACvB,IAA6B;QAE7B,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;QACvC,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,CAAC,UAAU,EAAE,CAAC;YAClD,OAAO;gBACL,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,EAAE,CAAC;gBACnD,IAAI;gBACJ,IAAI;aACL,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;YAC5D,MAAM,OAAO,GAA4B;gBACvC,WAAW,EAAE,UAAU;gBACvB,MAAM,EAAE,MAAM,CAAC,MAAM;aACtB,CAAC;YACF,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;YACpC,CAAC;YACD,OAAO;gBACL,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;gBACjD,KAAK;gBACL,IAAI;aACL,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACjE,IAAI;gBACJ,IAAI;aACL,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/server/async-task-bridge.d.ts

@@ -14,12 +14,18 @@
 import type { ModuleDescriptor } from "../types.js";
 /** Reserved meta-tool prefix. Module ids starting with this are forbidden. */
 export declare const APCORE_META_TOOL_PREFIX = "__apcore_";
-/** The four reserved meta-tool names. */
+/**
+ * Reserved meta-tool names.
+ *
+ * Four task-management tools (submit/status/cancel/list) plus one
+ * preflight tool (`__apcore_module_preview`, apcore 0.21 PROTOCOL_SPEC §5.6).
+ */
 export declare const META_TOOL_NAMES: Readonly<{
     readonly SUBMIT: "__apcore_task_submit";
     readonly STATUS: "__apcore_task_status";
     readonly CANCEL: "__apcore_task_cancel";
     readonly LIST: "__apcore_task_list";
+    readonly PREVIEW: "__apcore_module_preview";
 }>;
 /** Duck-typed TaskInfo projection matching apcore-js `TaskInfo`. */
 export interface TaskInfoProjection {
@@ -59,6 +65,30 @@ export interface AsyncTaskManagerLike {
     }>;
     shutdown?(): Promise<void>;
 }
+/**
+ * Minimal duck-typed `Executor` contract used by `__apcore_module_preview`.
+ *
+ * `validate(moduleId, inputs, context)` is the dry-run preflight entry
+ * point in apcore 0.20+; it never throws on input-shape errors —
+ * malformed inputs are surfaced as a failed `PreflightCheckResult` in
+ * the returned `PreflightResult`. apcore 0.21 added
+ * `predicted_changes` populated from `Module.preview()`.
+ */
+export interface ExecutorLike {
+    validate(moduleId: string, inputs?: Record<string, unknown> | null, context?: unknown | null): Promise<{
+        valid: boolean;
+        requiresApproval?: boolean;
+        requires_approval?: boolean;
+        predictedChanges?: unknown[];
+        predicted_changes?: unknown[];
+        checks?: Array<{
+            check: string;
+            passed: boolean;
+            error?: unknown;
+            warnings?: string[];
+        }>;
+    }>;
+}
 /** MCP-facing Tool shape used to advertise meta-tools. */
 export interface AsyncMetaTool {
     name: string;
@@ -84,6 +114,13 @@ export interface AsyncTaskBridgeOptions {
      * behavior for tests / direct construction without a registry). [A-D-008]
      */
     descriptorLookup?: (moduleId: string) => ModuleDescriptor | null | undefined;
+    /**
+     * Optional executor reference used by `__apcore_module_preview` to drive
+     * the cross-language `executor.validate()` preflight (apcore PROTOCOL_SPEC
+     * §5.6). When omitted, the preview meta-tool returns
+     * `PREVIEW_UNAVAILABLE`.
+     */
+    executor?: ExecutorLike;
 }
 /**
  * Routes MCP tool calls either to the synchronous Execution Router (default)
@@ -95,6 +132,7 @@ export declare class AsyncTaskBridge {
     private readonly _redactSensitive?;
     private readonly _outputSchemaMap;
     private readonly _descriptorLookup?;
+    private readonly _executor?;
     /**
      * Maps task_id → progressToken recorded at submit time so terminal-
      * state notifications can be fanned out via the original token.

package/dist/server/async-task-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async-task-bridge.d.ts","sourceRoot":"","sources":["../../src/server/async-task-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAEnD,yCAAyC;AACzC,eAAO,MAAM,eAAe;;;;;EAKjB,CAAC;AAEZ,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACvC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;KACtB,GAAG,IAAI,CAAC;IACT,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;QAChC,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACvC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;KACtB,CAAC,CAAC;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,oFAAoF;IACpF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAAC;CAC9E;AAED;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAA4C;IAC9E,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA0C;IAC3E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAA6C;IAChF;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsC;IACtE;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;gBAEjD,OAAO,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,sBAAsB;IAQ3E,wDAAwD;IACxD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,6EAA6E;IAC7E,IAAI,OAAO,IAAI,oBAAoB,CAElC;IAED;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;IAgBvE;;;OAGG;IACG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,EACxB,OAAO,CAAC,EAAE;QACR,oEAAoE;QACpE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAChC,mFAAmF;QACnF,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB;;;;;WAKG;QACH,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;KACpF,GACA,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC;IAuClD;;;;;;OAMG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7D;;;;;;;OAOG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsB7D;;;OAGG;IACH,cAAc,IAAI,aAAa,EAAE;IA+DjC;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAUrC;;;OAGG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAoInC,OAAO,CAAC,gBAAgB;CAmBzB;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,OAAO,EACjB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAAC;CAC9E,GACA,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAsBjC"}
+{"version":3,"file":"async-task-bridge.d.ts","sourceRoot":"","sources":["../../src/server/async-task-bridge.ts"],"names":[],"mappings":"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"}

package/dist/server/async-task-bridge.js

@@ -11,14 +11,64 @@
  *
  * Full spec: apcore-mcp/docs/features/async-task-bridge.md (F-043).
  */
+import { ErrorCodes } from "../types.js";
+/**
+ * Lazy snapshot of apcore-js's TaskLimitExceededError class for `instanceof`
+ * dispatch in handleMetaTool. Mirrors the lazy-load pattern used by
+ * adapters/errors.ts so callers don't pay an import-time tax.
+ */
+let _taskLimitExceededClass;
+async function _loadTaskLimitExceededClass() {
+    if (_taskLimitExceededClass !== undefined) {
+        return _taskLimitExceededClass ?? null;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const apcore = (await import("apcore-js"));
+        _taskLimitExceededClass = apcore.TaskLimitExceededError ?? null;
+    }
+    catch {
+        _taskLimitExceededClass = null;
+    }
+    return _taskLimitExceededClass ?? null;
+}
+// Eager fire-and-forget load so the cache is warm by the time handleMetaTool
+// fires under typical flows. The synchronous code path below tolerates a cold
+// cache by also duck-typing on `error.code`.
+void _loadTaskLimitExceededClass();
+/**
+ * Detect a task-capacity-exceeded error from apcore-js. Prefers `instanceof`
+ * dispatch when the class has been resolved; falls back to duck-typing on
+ * `error.code === "TASK_LIMIT_EXCEEDED"` so cold-cache or
+ * apcore-js-unavailable scenarios still classify correctly.
+ */
+function _isTaskLimitExceeded(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const cls = _taskLimitExceededClass;
+    if (cls && err instanceof cls)
+        return true;
+    const obj = err;
+    if (obj.code === ErrorCodes.TASK_LIMIT_EXCEEDED)
+        return true;
+    if (obj.name === "TaskLimitExceededError")
+        return true;
+    return false;
+}
 /** Reserved meta-tool prefix. Module ids starting with this are forbidden. */
 export const APCORE_META_TOOL_PREFIX = "__apcore_";
-/** The four reserved meta-tool names. */
+/**
+ * Reserved meta-tool names.
+ *
+ * Four task-management tools (submit/status/cancel/list) plus one
+ * preflight tool (`__apcore_module_preview`, apcore 0.21 PROTOCOL_SPEC §5.6).
+ */
 export const META_TOOL_NAMES = Object.freeze({
     SUBMIT: "__apcore_task_submit",
     STATUS: "__apcore_task_status",
     CANCEL: "__apcore_task_cancel",
     LIST: "__apcore_task_list",
+    PREVIEW: "__apcore_module_preview",
 });
 /**
  * Routes MCP tool calls either to the synchronous Execution Router (default)
@@ -30,6 +80,7 @@ export class AsyncTaskBridge {
     _redactSensitive;
     _outputSchemaMap;
     _descriptorLookup;
+    _executor;
     /**
      * Maps task_id → progressToken recorded at submit time so terminal-
      * state notifications can be fanned out via the original token.
@@ -48,6 +99,7 @@ export class AsyncTaskBridge {
         this._redactSensitive = options?.redactSensitive;
         this._outputSchemaMap = options?.outputSchemaMap ?? {};
         this._descriptorLookup = options?.descriptorLookup;
+        this._executor = options?.executor;
     }
     /** Whether async routing and meta-tools are enabled. */
     get enabled() {
@@ -67,14 +119,17 @@ export class AsyncTaskBridge {
         const meta = descriptor.metadata ?? {};
         // Accept both boolean true AND the string "true" — Python and Rust
         // both accept the string form (registries that store annotations as
-        // YAML produce string booleans). [A-D-021]
+        // YAML produce string booleans). Match Python's case-insensitive
+        // semantics so that `"True"` / `"TRUE"` round-tripped through YAML
+        // dispatchers agree across SDKs. [A-D-021 / A-003 cross-lang fix]
+        const isTruthyAsyncString = (v) => typeof v === "string" && v.toLowerCase() === "true";
         const asyncFlag = meta["async"];
-        if (asyncFlag === true || asyncFlag === "true")
+        if (asyncFlag === true || isTruthyAsyncString(asyncFlag))
             return true;
         const annotations = descriptor.annotations;
         if (annotations?.extra) {
             const flag = annotations.extra["mcp_async"];
-            if (flag === true || flag === "true")
+            if (flag === true || isTruthyAsyncString(flag))
                 return true;
         }
         return false;
@@ -218,6 +273,24 @@ export class AsyncTaskBridge {
                     },
                 },
             },
+            {
+                name: META_TOOL_NAMES.PREVIEW,
+                description: "Preview a module call: predict state changes, validate inputs, " +
+                    "and check approval requirements WITHOUT executing the module. " +
+                    "Returns `{valid, requires_approval, predicted_changes, checks}`. " +
+                    "Use this before invoking destructive or stateful modules to let " +
+                    "the AI orchestrator answer 'what would change in the world if I " +
+                    "called this?' (apcore PROTOCOL_SPEC §5.6).",
+                inputSchema: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        module_id: { type: "string" },
+                        arguments: { type: "object", additionalProperties: true, default: {} },
+                    },
+                    required: ["module_id"],
+                },
+            },
         ];
     }
     /**
@@ -229,7 +302,8 @@ export class AsyncTaskBridge {
             (toolName === META_TOOL_NAMES.SUBMIT ||
                 toolName === META_TOOL_NAMES.STATUS ||
                 toolName === META_TOOL_NAMES.CANCEL ||
-                toolName === META_TOOL_NAMES.LIST));
+                toolName === META_TOOL_NAMES.LIST ||
+                toolName === META_TOOL_NAMES.PREVIEW));
     }
     /**
      * Dispatch a meta-tool invocation. The caller must have already confirmed
@@ -271,7 +345,30 @@ export class AsyncTaskBridge {
                     throw new Error("__apcore_task_submit requires `arguments` to be a JSON object");
                 }
                 const inputs = rawArgs ?? {};
-                return this.submit(moduleId, inputs, context);
+                // [A-D-222] Catch TaskLimitExceededError from manager.submit() and
+                // surface it as a structured TASK_LIMIT_EXCEEDED envelope with
+                // retryable=true. Mirrors Python's
+                // `apcore_mcp/server/async_task_bridge.py:375-376` which explicitly
+                // catches TaskLimitExceededError. Pre-fix TS let the bare error
+                // bubble — it would still get mapped by the router's ErrorMapper,
+                // but bridges that call handleMetaTool directly (toolkit/library
+                // use) saw a raw Error without errorType or retryable hints.
+                try {
+                    return (await this.submit(moduleId, inputs, context));
+                }
+                catch (err) {
+                    if (_isTaskLimitExceeded(err)) {
+                        const e = err;
+                        return {
+                            isError: true,
+                            errorType: ErrorCodes.TASK_LIMIT_EXCEEDED,
+                            message: e.message,
+                            details: e.details ?? null,
+                            retryable: true,
+                        };
+                    }
+                    throw err;
+                }
             }
             case META_TOOL_NAMES.STATUS: {
                 const taskId = args["task_id"];
@@ -280,9 +377,14 @@ export class AsyncTaskBridge {
                 }
                 const info = this._manager.getStatus(taskId);
                 if (!info) {
-                    const err = new Error(`Task not found: ${taskId}`);
-                    err.code = "ASYNC_TASK_NOT_FOUND";
-                    throw err;
+                    // [D10-003] Return envelope (matching Python's `(content, is_error=True, None)`
+                    // and Rust's `Ok(envelope)`). Throwing here would force the caller's catch path
+                    // to diverge from Python+Rust, breaking cross-SDK error handling.
+                    return {
+                        error: "ASYNC_TASK_NOT_FOUND",
+                        task_id: taskId,
+                        isError: true,
+                    };
                 }
                 const projection = this._projectTaskInfo(info);
                 // [A-D-025] Inline result on terminal completed status — even
@@ -314,6 +416,18 @@ export class AsyncTaskBridge {
                 if (typeof taskId !== "string" || taskId.length === 0) {
                     throw new Error("__apcore_task_cancel requires task_id (string)");
                 }
+                // [D10-004] Pre-check existence (matching Python `_handle_cancel_tool`).
+                // Without this, unknown task_ids silently return `{cancelled: false}` —
+                // callers can't distinguish "task existed and is uncancellable" from
+                // "task never existed".
+                if (!this._manager.getStatus(taskId)) {
+                    this._progressTokens.delete(taskId);
+                    return {
+                        error: "ASYNC_TASK_NOT_FOUND",
+                        task_id: taskId,
+                        isError: true,
+                    };
+                }
                 const cancelled = await this._manager.cancel(taskId);
                 // [A-D-009] Drop the progress-token binding after a single-task cancel
                 // so notifications/progress for cancelled tasks don't fan out to a
@@ -323,6 +437,72 @@ export class AsyncTaskBridge {
                 this._progressTokens.delete(taskId);
                 return { task_id: taskId, cancelled };
             }
+            case META_TOOL_NAMES.PREVIEW: {
+                const moduleId = args["module_id"];
+                if (typeof moduleId !== "string" || moduleId.length === 0) {
+                    throw new Error("__apcore_module_preview requires module_id (string)");
+                }
+                // Reject reserved-prefix module ids the same way the submit branch
+                // does at line 474 — the preview meta-tool must not introspect the
+                // bridge's own meta-tools (apcore PROTOCOL_SPEC §5.6 contract).
+                // Cross-SDK parity: Python and Rust apply the same guard.
+                if (moduleId.startsWith(APCORE_META_TOOL_PREFIX)) {
+                    throw new Error(`Reserved module id: "${moduleId}". Names starting with ` +
+                        `"${APCORE_META_TOOL_PREFIX}" are reserved for apcore-mcp ` +
+                        "meta-tools and cannot be previewed via this handler.");
+                }
+                if (!this._executor) {
+                    // Bridge was constructed without an executor reference — preview
+                    // is a runtime no-op rather than an error so the meta-tool stays
+                    // discoverable across heterogenous deployments.
+                    return {
+                        error: "PREVIEW_UNAVAILABLE",
+                        message: "Module preview requires an Executor reference; bridge was built without one.",
+                    };
+                }
+                // Preserve `arguments: null` verbatim (forwarded as null to
+                // executor.validate). The calling business decides whether
+                // null is acceptable for the target module. Reject only
+                // structurally-impossible shapes — arrays and scalars can
+                // never represent a JSON object.
+                const rawArgs = args["arguments"];
+                if (rawArgs !== undefined &&
+                    rawArgs !== null &&
+                    (typeof rawArgs !== "object" || Array.isArray(rawArgs))) {
+                    throw new Error("__apcore_module_preview requires `arguments` to be a JSON object or null");
+                }
+                // null → null, undefined → null (no caller intent to pass inputs),
+                // {x:1} → {x:1}. Distinguishing missing from explicit null is not
+                // observable downstream — both represent "no inputs supplied".
+                const inputs = rawArgs === undefined
+                    ? null
+                    : rawArgs;
+                const preflight = await this._executor.validate(moduleId, inputs, context ?? null);
+                // PreflightResult fields land in either snake_case or camelCase
+                // depending on the apcore-js minor; normalize to the canonical
+                // wire shape (snake_case) Python and Rust emit.
+                const requiresApproval = preflight.requires_approval ??
+                    preflight.requiresApproval ??
+                    false;
+                const predictedChanges = preflight.predicted_changes ?? preflight.predictedChanges ?? [];
+                const checks = (preflight.checks ?? []).map((c) => {
+                    const out = {
+                        check: c.check,
+                        passed: c.passed,
+                    };
+                    if (c.error !== undefined && c.error !== null)
+                        out["error"] = c.error;
+                    if (c.warnings && c.warnings.length > 0)
+                        out["warnings"] = c.warnings;
+                    return out;
+                });
+                return {
+                    valid: preflight.valid,
+                    requires_approval: requiresApproval,
+                    predicted_changes: predictedChanges,
+                    checks,
+                };
+            }
             case META_TOOL_NAMES.LIST: {
                 // [A-D-024] Validate status filter against the spec enum;
                 // Python+Rust both reject unknown values. Pre-fix TS forwarded
@@ -379,11 +559,17 @@ export async function createAsyncTaskBridge(executor, options) {
             return null;
         const manager = new AsyncTaskManager(executor, options?.maxConcurrent ?? 10, options?.maxTasks ?? 1000);
         const redactSensitive = apcore.redactSensitive ?? apcore.default?.redactSensitive;
+        // Pass the executor through so `__apcore_module_preview` can drive
+        // `executor.validate()` (apcore PROTOCOL_SPEC §5.6).
+        const executorLike = typeof executor?.validate === "function"
+            ? executor
+            : undefined;
         return new AsyncTaskBridge(manager, {
             enabled: true,
             redactSensitive: typeof redactSensitive === "function" ? redactSensitive : undefined,
             outputSchemaMap: options?.outputSchemaMap,
             descriptorLookup: options?.descriptorLookup,
+            executor: executorLike,
         });
     }
     catch {