apcore-mcp 0.12.0 → 0.14.0

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

@@ -0,0 +1,393 @@
+/**
+ * AsyncTaskBridge — MCP ↔ apcore `AsyncTaskManager` adapter.
+ *
+ * Surfaces apcore's {@link AsyncTaskManager} through the MCP protocol so
+ * that long-running modules can be submitted, polled, cancelled, and listed
+ * via reserved meta-tools. Async-hinted modules (either
+ * `metadata.async === true` OR `annotations.extra["mcp_async"] === "true"`)
+ * are routed through `AsyncTaskManager.submit()` instead of the synchronous
+ * executor call path; the agent receives a `{task_id, status: "pending"}`
+ * envelope it can resolve via the four reserved `__apcore_task_*` meta-tools.
+ *
+ * Full spec: apcore-mcp/docs/features/async-task-bridge.md (F-043).
+ */
+/** Reserved meta-tool prefix. Module ids starting with this are forbidden. */
+export const APCORE_META_TOOL_PREFIX = "__apcore_";
+/** The four reserved meta-tool names. */
+export const META_TOOL_NAMES = Object.freeze({
+    SUBMIT: "__apcore_task_submit",
+    STATUS: "__apcore_task_status",
+    CANCEL: "__apcore_task_cancel",
+    LIST: "__apcore_task_list",
+});
+/**
+ * Routes MCP tool calls either to the synchronous Execution Router (default)
+ * or to `AsyncTaskManager.submit()` for async-hinted modules.
+ */
+export class AsyncTaskBridge {
+    _manager;
+    _enabled;
+    _redactSensitive;
+    _outputSchemaMap;
+    _descriptorLookup;
+    /**
+     * Maps task_id → progressToken recorded at submit time so terminal-
+     * state notifications can be fanned out via the original token.
+     * [A-D-018]
+     */
+    _progressTokens = new Map();
+    /**
+     * Maps session/connection key → list of task ids launched from that
+     * session so {@link cancelSessionTasks} can cancel them on transport
+     * disconnect. Mirrors Rust's `session_tasks` map. [A-D-018]
+     */
+    _sessionTasks = new Map();
+    constructor(manager, options) {
+        this._manager = manager;
+        this._enabled = options?.enabled ?? true;
+        this._redactSensitive = options?.redactSensitive;
+        this._outputSchemaMap = options?.outputSchemaMap ?? {};
+        this._descriptorLookup = options?.descriptorLookup;
+    }
+    /** Whether async routing and meta-tools are enabled. */
+    get enabled() {
+        return this._enabled;
+    }
+    /** Expose the underlying manager (used by server lifecycle for shutdown). */
+    get manager() {
+        return this._manager;
+    }
+    /**
+     * Return true if the descriptor carries an async hint — either
+     * `metadata.async === true` OR `annotations.extra["mcp_async"] === "true"`.
+     */
+    isAsyncModule(descriptor) {
+        if (!this._enabled || !descriptor)
+            return false;
+        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]
+        const asyncFlag = meta["async"];
+        if (asyncFlag === true || asyncFlag === "true")
+            return true;
+        const annotations = descriptor.annotations;
+        if (annotations?.extra) {
+            const flag = annotations.extra["mcp_async"];
+            if (flag === true || flag === "true")
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Submit a module invocation to the AsyncTaskManager. Returns the standard
+     * MCP envelope `{task_id, status: "pending"}`.
+     */
+    async submit(moduleId, inputs, context, options) {
+        // [D11-015] Install progress sink on the context BEFORE submitting, so the
+        // module can emit mid-execution progress via context.data[MCP_PROGRESS_KEY].
+        // Mirrors Python's async_task_bridge.py _install_progress_sink() pattern.
+        if (options?.progressToken !== undefined &&
+            options?.sendNotification !== undefined &&
+            context !== null &&
+            context !== undefined &&
+            typeof context === "object") {
+            const progressToken = options.progressToken;
+            const sendNotification = options.sendNotification;
+            const contextData = context.data;
+            if (contextData && typeof contextData === "object") {
+                contextData["_mcp_progress"] = async (progress, total) => {
+                    await sendNotification({
+                        method: "notifications/progress",
+                        params: { progressToken, progress, total },
+                    });
+                };
+            }
+        }
+        const taskId = await this._manager.submit(moduleId, inputs, context ?? null);
+        if (options?.progressToken !== undefined) {
+            this._progressTokens.set(taskId, options.progressToken);
+        }
+        if (options?.sessionKey !== undefined) {
+            const list = this._sessionTasks.get(options.sessionKey) ?? [];
+            list.push(taskId);
+            this._sessionTasks.set(options.sessionKey, list);
+        }
+        return { task_id: taskId, status: "pending" };
+    }
+    /**
+     * Look up the progress token recorded for a task at submit time.
+     *
+     * Used by transport / terminal-notification dispatch to route
+     * `notifications/progress` to the original caller. Returns undefined
+     * when no token was registered. [A-D-018]
+     */
+    getProgressToken(taskId) {
+        return this._progressTokens.get(taskId);
+    }
+    /**
+     * Cancel every async task currently tracked under `sessionKey`.
+     *
+     * Used by the transport layer on client disconnect to ensure
+     * long-running tasks bound to that session don't keep running after
+     * the client has gone. Returns the number of tasks cancelled.
+     * Mirrors Rust's `AsyncTaskBridge::cancel_session_tasks`. [A-D-018]
+     */
+    async cancelSessionTasks(sessionKey) {
+        // [A-D-005] Detach the task list from the map BEFORE iterating cancels.
+        // A concurrent submit() between get() and the post-loop delete() would
+        // otherwise append to the same Array reference and the trailing delete
+        // would drop the newly-tracked task. Mirrors Python's `pop()` and Rust's
+        // `remove()` — both detach before yielding to manager.cancel.
+        const taskIds = this._sessionTasks.get(sessionKey);
+        if (!taskIds || taskIds.length === 0)
+            return 0;
+        this._sessionTasks.delete(sessionKey);
+        let cancelled = 0;
+        for (const taskId of taskIds) {
+            try {
+                const ok = await this._manager.cancel(taskId);
+                if (ok)
+                    cancelled++;
+            }
+            catch {
+                // Cancel may fail if the task has already completed; swallow.
+            }
+            this._progressTokens.delete(taskId);
+        }
+        return cancelled;
+    }
+    /**
+     * Build the four MCP meta-tool definitions. Caller merges these with
+     * the regular tool list returned by `tools/list`.
+     */
+    buildMetaTools() {
+        if (!this._enabled)
+            return [];
+        return [
+            {
+                name: META_TOOL_NAMES.SUBMIT,
+                description: "Submit an async-hinted apcore module for background execution. " +
+                    "Returns `{task_id, status: \"pending\"}`. Use `__apcore_task_status` " +
+                    "to poll until terminal state.",
+                inputSchema: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        module_id: { type: "string" },
+                        arguments: { type: "object", additionalProperties: true, default: {} },
+                        version_hint: { type: "string" },
+                    },
+                    required: ["module_id"],
+                },
+            },
+            {
+                name: META_TOOL_NAMES.STATUS,
+                description: "Return the TaskInfo projection for a previously submitted async " +
+                    "task. When the task is `completed`, the redacted result is inlined.",
+                inputSchema: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: { task_id: { type: "string" } },
+                    required: ["task_id"],
+                },
+            },
+            {
+                name: META_TOOL_NAMES.CANCEL,
+                description: "Cooperatively cancel a pending or running async task. Returns " +
+                    "`{task_id, cancelled: bool}`.",
+                inputSchema: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: { task_id: { type: "string" } },
+                    required: ["task_id"],
+                },
+            },
+            {
+                name: META_TOOL_NAMES.LIST,
+                description: "List tracked async tasks. Optional `status` filter narrows to a " +
+                    "single lifecycle state.",
+                inputSchema: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        status: {
+                            type: "string",
+                            enum: ["pending", "running", "completed", "failed", "cancelled"],
+                        },
+                    },
+                },
+            },
+        ];
+    }
+    /**
+     * Whether `toolName` is one of the reserved meta-tools. Used by the
+     * execution router to short-circuit dispatch before touching the executor.
+     */
+    isMetaTool(toolName) {
+        return (this._enabled &&
+            (toolName === META_TOOL_NAMES.SUBMIT ||
+                toolName === META_TOOL_NAMES.STATUS ||
+                toolName === META_TOOL_NAMES.CANCEL ||
+                toolName === META_TOOL_NAMES.LIST));
+    }
+    /**
+     * Dispatch a meta-tool invocation. The caller must have already confirmed
+     * `isMetaTool(toolName)` is true.
+     */
+    async handleMetaTool(toolName, args, context) {
+        switch (toolName) {
+            case META_TOOL_NAMES.SUBMIT: {
+                const moduleId = args["module_id"];
+                if (typeof moduleId !== "string" || moduleId.length === 0) {
+                    throw new Error("__apcore_task_submit requires module_id (string)");
+                }
+                if (moduleId.startsWith(APCORE_META_TOOL_PREFIX)) {
+                    throw new Error(`Reserved module id: "${moduleId}". Ids prefixed with ` +
+                        `"${APCORE_META_TOOL_PREFIX}" are reserved for apcore-mcp meta-tools.`);
+                }
+                // Spec: __apcore_task_submit on a non-async module returns
+                // ASYNC_MODULE_NOT_ASYNC. Python enforces; TS+Rust were silently
+                // wrapping sync modules as async tasks. The check is only applied
+                // when a descriptor-lookup callback is wired (the normal
+                // production path); direct test construction without a registry
+                // skips this guard to preserve unit-test ergonomics. [A-D-008]
+                if (this._descriptorLookup) {
+                    const descriptor = this._descriptorLookup(moduleId);
+                    if (!descriptor || !this.isAsyncModule(descriptor)) {
+                        const err = new Error(`ASYNC_MODULE_NOT_ASYNC: module "${moduleId}" is not async-hinted; ` +
+                            `use regular tools/call instead of __apcore_task_submit`);
+                        err.code = "ASYNC_MODULE_NOT_ASYNC";
+                        throw err;
+                    }
+                }
+                // [A-D-020] Validate `arguments` is a JSON object (not an array,
+                // string, number, etc.). Python rejects non-objects; pre-fix TS
+                // coerced via `?? {}` and silently passed through arrays/strings.
+                const rawArgs = args["arguments"];
+                if (rawArgs !== undefined &&
+                    rawArgs !== null &&
+                    (typeof rawArgs !== "object" || Array.isArray(rawArgs))) {
+                    throw new Error("__apcore_task_submit requires `arguments` to be a JSON object");
+                }
+                const inputs = rawArgs ?? {};
+                return this.submit(moduleId, inputs, context);
+            }
+            case META_TOOL_NAMES.STATUS: {
+                const taskId = args["task_id"];
+                if (typeof taskId !== "string" || taskId.length === 0) {
+                    throw new Error("__apcore_task_status requires task_id (string)");
+                }
+                const info = this._manager.getStatus(taskId);
+                if (!info) {
+                    const err = new Error(`Task not found: ${taskId}`);
+                    err.code = "ASYNC_TASK_NOT_FOUND";
+                    throw err;
+                }
+                const projection = this._projectTaskInfo(info);
+                // [A-D-025] Inline result on terminal completed status — even
+                // when info.result is null/undefined (Python always inlines;
+                // pre-fix TS only inlined when truthy, silently dropping `null`).
+                // [A-D-026] Wrap redactor in try/catch — a buggy redactor must
+                // not bring down handle_status; fall back to original result.
+                if (info.status === "completed") {
+                    const schema = this._outputSchemaMap[info.moduleId];
+                    let redacted = info.result;
+                    if (this._redactSensitive && schema && info.result) {
+                        try {
+                            redacted = this._redactSensitive(info.result, schema);
+                        }
+                        catch (err) {
+                            console.warn(`task-result redactor raised for ${info.moduleId}; returning unredacted result`, err);
+                            redacted = info.result;
+                        }
+                    }
+                    projection.result = redacted;
+                }
+                else if (info.status === "failed" && info.error) {
+                    projection.error = info.error;
+                }
+                return projection;
+            }
+            case META_TOOL_NAMES.CANCEL: {
+                const taskId = args["task_id"];
+                if (typeof taskId !== "string" || taskId.length === 0) {
+                    throw new Error("__apcore_task_cancel requires task_id (string)");
+                }
+                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
+                // token whose caller has already been told the task is gone. Mirrors
+                // Python's `_progress_bindings.pop(task_id, None)` and Rust's
+                // `progress_tokens.remove(task_id)`.
+                this._progressTokens.delete(taskId);
+                return { task_id: taskId, cancelled };
+            }
+            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
+                // any string verbatim to listTasks(filter).
+                const status = args["status"];
+                let filter;
+                if (status !== undefined && status !== null) {
+                    if (typeof status !== "string") {
+                        throw new Error("__apcore_task_list `status` filter must be a string");
+                    }
+                    const validStatuses = [
+                        "pending",
+                        "running",
+                        "completed",
+                        "failed",
+                        "cancelled",
+                    ];
+                    if (!validStatuses.includes(status)) {
+                        throw new Error(`__apcore_task_list invalid status filter: ${JSON.stringify(status)}; ` +
+                            `must be one of ${validStatuses.join(", ")}`);
+                    }
+                    filter = status;
+                }
+                const tasks = this._manager.listTasks(filter);
+                return { tasks: tasks.map((t) => this._projectTaskInfo(t)) };
+            }
+            default:
+                throw new Error(`Unknown meta-tool: ${toolName}`);
+        }
+    }
+    _projectTaskInfo(info) {
+        return {
+            task_id: info.taskId,
+            module_id: info.moduleId,
+            status: info.status,
+            submitted_at: info.submittedAt,
+            started_at: info.startedAt,
+            completed_at: info.completedAt,
+        };
+    }
+}
+/**
+ * Factory that dynamically imports apcore-js's `AsyncTaskManager` and wraps
+ * it in an `AsyncTaskBridge`. Returns null when apcore-js is unavailable.
+ */
+export async function createAsyncTaskBridge(executor, options) {
+    if (options?.enabled === false)
+        return null;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const apcore = (await import("apcore-js"));
+        const AsyncTaskManager = apcore.AsyncTaskManager ?? apcore.default?.AsyncTaskManager;
+        if (!AsyncTaskManager)
+            return null;
+        const manager = new AsyncTaskManager(executor, options?.maxConcurrent ?? 10, options?.maxTasks ?? 1000);
+        const redactSensitive = apcore.redactSensitive ?? apcore.default?.redactSensitive;
+        return new AsyncTaskBridge(manager, {
+            enabled: true,
+            redactSensitive: typeof redactSensitive === "function" ? redactSensitive : undefined,
+            outputSchemaMap: options?.outputSchemaMap,
+            descriptorLookup: options?.descriptorLookup,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=async-task-bridge.js.map

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

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

package/dist/server/context.d.ts

@@ -11,6 +11,7 @@
  * `data` reference so MCP callbacks remain accessible throughout the call chain.
  */
 import type { Identity } from "../auth/types.js";
+import type { CancelToken } from "./router.js";
 /** Shape of the bridge context object. */
 export interface BridgeContext {
     readonly traceId: string;
@@ -18,7 +19,7 @@ export interface BridgeContext {
     readonly callChain: readonly string[];
     readonly executor: unknown;
     readonly identity: Identity | null;
-    readonly cancelToken: null;
+    readonly cancelToken: CancelToken | null;
     redactedInputs: Record<string, unknown> | null;
     readonly data: Record<string, unknown>;
     child(moduleId: string): BridgeContext;
@@ -28,7 +29,13 @@ export interface BridgeContext {
  *
  * @param data - Shared data dict (MCP callbacks are injected here)
  * @param identity - Authenticated identity, if any
+ * @param traceId - Optional pre-existing traceId (32-hex, W3C format). When
+ *   omitted, a fresh UUID is generated. Used to propagate incoming W3C
+ *   `traceparent` trace_id so the downstream trace chain stays linked.
+ * @param cancelToken - Cooperative cancel token. Threaded into the context so
+ *   modules can read `context.cancelToken?.isCancelled` to react to inbound
+ *   MCP `notifications/cancelled`. [A-D-001]
  * @returns A BridgeContext with a working child() method
  */
-export declare function createBridgeContext(data: Record<string, unknown>, identity?: Identity | null): BridgeContext;
+export declare function createBridgeContext(data: Record<string, unknown>, identity?: Identity | null, traceId?: string, cancelToken?: CancelToken | null): BridgeContext;
 //# sourceMappingURL=context.d.ts.map

package/dist/server/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/server/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAAC;CACxC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,GACzB,aAAa,CAEf"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/server/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAAC;CACxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,EAC1B,OAAO,CAAC,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,GAC/B,aAAa,CASf"}

package/dist/server/context.js

@@ -16,25 +16,33 @@ import { randomUUID } from "node:crypto";
  *
  * @param data - Shared data dict (MCP callbacks are injected here)
  * @param identity - Authenticated identity, if any
+ * @param traceId - Optional pre-existing traceId (32-hex, W3C format). When
+ *   omitted, a fresh UUID is generated. Used to propagate incoming W3C
+ *   `traceparent` trace_id so the downstream trace chain stays linked.
+ * @param cancelToken - Cooperative cancel token. Threaded into the context so
+ *   modules can read `context.cancelToken?.isCancelled` to react to inbound
+ *   MCP `notifications/cancelled`. [A-D-001]
  * @returns A BridgeContext with a working child() method
  */
-export function createBridgeContext(data, identity) {
-    return _buildContext(data, randomUUID(), null, [], identity ?? null);
+export function createBridgeContext(data, identity, traceId, cancelToken) {
+    return _buildContext(data, traceId ?? randomUUID(), null, [], identity ?? null, cancelToken ?? null);
 }
-function _buildContext(data, traceId, callerId, callChain, identity) {
+function _buildContext(data, traceId, callerId, callChain, identity, cancelToken) {
     return {
         traceId,
         callerId,
         callChain,
         executor: null,
         identity,
-        cancelToken: null,
+        cancelToken,
         redactedInputs: null,
         data,
         child(moduleId) {
-            // Match real Context.child(): callerId = last element of current callChain
+            // Match real Context.child(): callerId = last element of current callChain.
+            // child() preserves the cancelToken so cooperative cancel propagates
+            // through the entire executor call chain.
             const newCallerId = callChain.length > 0 ? callChain[callChain.length - 1] : null;
-            return _buildContext(data, traceId, newCallerId, [...callChain, moduleId], identity);
+            return _buildContext(data, traceId, newCallerId, [...callChain, moduleId], identity, cancelToken);
         },
     };
 }

package/dist/server/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/server/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAgBzC;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAA6B,EAC7B,QAA0B;IAE1B,OAAO,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,IAAI,IAAI,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,aAAa,CACpB,IAA6B,EAC7B,OAAe,EACf,QAAuB,EACvB,SAAmB,EACnB,QAAyB;IAEzB,OAAO;QACL,OAAO;QACP,QAAQ;QACR,SAAS;QACT,QAAQ,EAAE,IAAI;QACd,QAAQ;QACR,WAAW,EAAE,IAAI;QACjB,cAAc,EAAE,IAAI;QACpB,IAAI;QACJ,KAAK,CAAC,QAAgB;YACpB,2EAA2E;YAC3E,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAClF,OAAO,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;QACvF,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/server/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiBzC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAA6B,EAC7B,QAA0B,EAC1B,OAAgB,EAChB,WAAgC;IAEhC,OAAO,aAAa,CAClB,IAAI,EACJ,OAAO,IAAI,UAAU,EAAE,EACvB,IAAI,EACJ,EAAE,EACF,QAAQ,IAAI,IAAI,EAChB,WAAW,IAAI,IAAI,CACpB,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CACpB,IAA6B,EAC7B,OAAe,EACf,QAAuB,EACvB,SAAmB,EACnB,QAAyB,EACzB,WAA+B;IAE/B,OAAO;QACL,OAAO;QACP,QAAQ;QACR,SAAS;QACT,QAAQ,EAAE,IAAI;QACd,QAAQ;QACR,WAAW;QACX,cAAc,EAAE,IAAI;QACpB,IAAI;QACJ,KAAK,CAAC,QAAgB;YACpB,4EAA4E;YAC5E,qEAAqE;YACrE,0CAA0C;YAC1C,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAClF,OAAO,aAAa,CAClB,IAAI,EACJ,OAAO,EACP,WAAW,EACX,CAAC,GAAG,SAAS,EAAE,QAAQ,CAAC,EACxB,QAAQ,EACR,WAAW,CACZ,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/server/factory.d.ts

@@ -10,10 +10,18 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { Registry, ModuleDescriptor } from "../types.js";
 import type { ExecutionRouter } from "./router.js";
+import { type AsyncTaskBridge } from "./async-task-bridge.js";
 /** Options for filtering when building tools from a registry. */
 export interface BuildToolsOptions {
     tags?: string[] | null;
     prefix?: string | null;
+    strict?: boolean;
+    registry?: Registry;
+}
+/** Options for building a single MCP tool. */
+export interface BuildToolOptions {
+    strict?: boolean;
+    registry?: Registry;
 }
 export declare class MCPServerFactory {
     private readonly _schemaConverter;
@@ -36,14 +44,23 @@ export declare class MCPServerFactory {
      * - inputSchema = converted via SchemaConverter
      * - annotations = mapped from AnnotationMapper with camelCase keys
      */
-    buildTool(descriptor: ModuleDescriptor): Tool;
+    buildTool(descriptor: ModuleDescriptor, options?: BuildToolOptions): Tool;
     /**
      * Build an array of MCP Tool objects from all modules in a registry.
      *
      * Iterates over registry.list(), gets each definition, and builds tools.
      * Skips modules that return null definitions or throw errors (with console.warn).
+     *
+     * Reserved: module ids starting with `__apcore_` collide with the async
+     * task bridge meta-tool namespace and are rejected with a console.error.
      */
     buildTools(registry: Registry, options?: BuildToolsOptions): Tool[];
+    /**
+     * Merge the four async-task meta-tools onto an existing tool list. Called
+     * after `buildTools()` when an `AsyncTaskBridge` is active so meta-tools
+     * are advertised via `tools/list`.
+     */
+    attachAsyncMetaTools(tools: Tool[], bridge: AsyncTaskBridge | undefined): Tool[];
     /**
      * Register resources/list and resources/read handlers for modules with documentation.
      *
@@ -62,7 +79,13 @@ export declare class MCPServerFactory {
      * @param server - The MCP Server to register handlers on
      * @param tools - Array of MCP Tool objects to serve
      * @param router - ExecutionRouter to handle tool call execution
+     * @param options - Optional extra options; `asyncTaskBridge` adds meta-tools
+     *                  and routes meta-tool calls to the bridge (mirrors Python's
+     *                  `register_handlers(server, tools, router, async_bridge)`).
+     *                  [D11-014]
      */
-    registerHandlers(server: Server, tools: Tool[], router: ExecutionRouter): void;
+    registerHandlers(server: Server, tools: Tool[], router: ExecutionRouter, options?: {
+        asyncTaskBridge?: AsyncTaskBridge;
+    }): void;
 }
 //# sourceMappingURL=factory.d.ts.map

package/dist/server/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/server/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAOnE,OAAO,KAAK,EACV,IAAI,EAIL,MAAM,oCAAoC,CAAC;AAI5C,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAMnD,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkB;IACnD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAmB;;IAOrD;;;;;;OAMG;IACH,YAAY,CACV,IAAI,GAAE,MAAqB,EAC3B,OAAO,GAAE,MAAgB,GACxB,MAAM;IAOT;;;;;;;;OAQG;IACH,SAAS,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI;IA0E7C;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,EAAE;IA2BnE;;;;;;;;;;OAUG;IACH,wBAAwB,CACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,GACjB,IAAI;IAsDP;;;;;;OAMG;IACH,gBAAgB,CACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,IAAI,EAAE,EACb,MAAM,EAAE,eAAe,GACtB,IAAI;CAiDR"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/server/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAOnE,OAAO,KAAK,EACV,IAAI,EAIL,MAAM,oCAAoC,CAAC;AAI5C,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAc,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAKvF,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkB;IACnD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAmB;;IAOrD;;;;;;OAMG;IACH,YAAY,CACV,IAAI,GAAE,MAAqB,EAC3B,OAAO,GAAE,MAAgB,GACxB,MAAM;IAkBT;;;;;;;;OAQG;IACH,SAAS,CAAC,UAAU,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAqGzE;;;;;;;;OAQG;IACH,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,EAAE;IAiCnE;;;;OAIG;IACH,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,EAAE;IAgBhF;;;;;;;;;;OAUG;IACH,wBAAwB,CACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,GACjB,IAAI;IAsDP;;;;;;;;;;OAUG;IACH,gBAAgB,CACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,IAAI,EAAE,EACb,MAAM,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,eAAe,CAAA;KAAE,GAC9C,IAAI;CAuGR"}