apcore-mcp 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/LICENSE +190 -0
  2. package/README.md +165 -19
  3. package/dist/acl-builder.d.ts +43 -0
  4. package/dist/acl-builder.d.ts.map +1 -0
  5. package/dist/acl-builder.js +115 -0
  6. package/dist/acl-builder.js.map +1 -0
  7. package/dist/adapters/annotations.d.ts.map +1 -1
  8. package/dist/adapters/annotations.js +37 -2
  9. package/dist/adapters/annotations.js.map +1 -1
  10. package/dist/adapters/errors.d.ts +17 -0
  11. package/dist/adapters/errors.d.ts.map +1 -1
  12. package/dist/adapters/errors.js +192 -2
  13. package/dist/adapters/errors.js.map +1 -1
  14. package/dist/adapters/id-normalizer.d.ts +40 -0
  15. package/dist/adapters/id-normalizer.d.ts.map +1 -0
  16. package/dist/adapters/id-normalizer.js +59 -0
  17. package/dist/adapters/id-normalizer.js.map +1 -0
  18. package/dist/adapters/index.d.ts +2 -2
  19. package/dist/adapters/index.d.ts.map +1 -1
  20. package/dist/adapters/index.js +2 -2
  21. package/dist/adapters/index.js.map +1 -1
  22. package/dist/adapters/{mcpErrorFormatter.d.ts → mcp-error-formatter.d.ts} +5 -7
  23. package/dist/adapters/mcp-error-formatter.d.ts.map +1 -0
  24. package/dist/adapters/mcp-error-formatter.js +30 -0
  25. package/dist/adapters/mcp-error-formatter.js.map +1 -0
  26. package/dist/adapters/schema.d.ts +21 -4
  27. package/dist/adapters/schema.d.ts.map +1 -1
  28. package/dist/adapters/schema.js +147 -13
  29. package/dist/adapters/schema.js.map +1 -1
  30. package/dist/apcore-mcp.d.ts +24 -2
  31. package/dist/apcore-mcp.d.ts.map +1 -1
  32. package/dist/apcore-mcp.js +8 -0
  33. package/dist/apcore-mcp.js.map +1 -1
  34. package/dist/auth/hooks.d.ts +1 -1
  35. package/dist/auth/hooks.d.ts.map +1 -1
  36. package/dist/auth/hooks.js +10 -3
  37. package/dist/auth/hooks.js.map +1 -1
  38. package/dist/auth/jwt.d.ts +1 -2
  39. package/dist/auth/jwt.d.ts.map +1 -1
  40. package/dist/auth/jwt.js +18 -10
  41. package/dist/auth/jwt.js.map +1 -1
  42. package/dist/auth/types.d.ts +6 -3
  43. package/dist/auth/types.d.ts.map +1 -1
  44. package/dist/cli.d.ts.map +1 -1
  45. package/dist/cli.js +23 -1
  46. package/dist/cli.js.map +1 -1
  47. package/dist/config.d.ts.map +1 -1
  48. package/dist/config.js +15 -6
  49. package/dist/config.js.map +1 -1
  50. package/dist/converters/openai.d.ts +10 -0
  51. package/dist/converters/openai.d.ts.map +1 -1
  52. package/dist/converters/openai.js +100 -5
  53. package/dist/converters/openai.js.map +1 -1
  54. package/dist/explorer/index.d.ts +2 -0
  55. package/dist/explorer/index.d.ts.map +1 -0
  56. package/dist/explorer/index.js +2 -0
  57. package/dist/explorer/index.js.map +1 -0
  58. package/dist/index.d.ts +68 -5
  59. package/dist/index.d.ts.map +1 -1
  60. package/dist/index.js +346 -60
  61. package/dist/index.js.map +1 -1
  62. package/dist/inspector/index.d.ts +2 -0
  63. package/dist/inspector/index.d.ts.map +1 -0
  64. package/dist/inspector/index.js +2 -0
  65. package/dist/inspector/index.js.map +1 -0
  66. package/dist/middleware-builder.d.ts +41 -0
  67. package/dist/middleware-builder.d.ts.map +1 -0
  68. package/dist/middleware-builder.js +129 -0
  69. package/dist/middleware-builder.js.map +1 -0
  70. package/dist/server/async-task-bridge.d.ts +190 -0
  71. package/dist/server/async-task-bridge.d.ts.map +1 -0
  72. package/dist/server/async-task-bridge.js +393 -0
  73. package/dist/server/async-task-bridge.js.map +1 -0
  74. package/dist/server/context.d.ts +9 -2
  75. package/dist/server/context.d.ts.map +1 -1
  76. package/dist/server/context.js +14 -6
  77. package/dist/server/context.js.map +1 -1
  78. package/dist/server/factory.d.ts +25 -2
  79. package/dist/server/factory.d.ts.map +1 -1
  80. package/dist/server/factory.js +127 -7
  81. package/dist/server/factory.js.map +1 -1
  82. package/dist/server/listener.d.ts +3 -0
  83. package/dist/server/listener.d.ts.map +1 -1
  84. package/dist/server/listener.js +13 -2
  85. package/dist/server/listener.js.map +1 -1
  86. package/dist/server/observability.d.ts +51 -0
  87. package/dist/server/observability.d.ts.map +1 -0
  88. package/dist/server/observability.js +96 -0
  89. package/dist/server/observability.js.map +1 -0
  90. package/dist/server/router.d.ts +114 -0
  91. package/dist/server/router.d.ts.map +1 -1
  92. package/dist/server/router.js +360 -18
  93. package/dist/server/router.js.map +1 -1
  94. package/dist/server/trace-context.d.ts +40 -0
  95. package/dist/server/trace-context.d.ts.map +1 -0
  96. package/dist/server/trace-context.js +67 -0
  97. package/dist/server/trace-context.js.map +1 -0
  98. package/dist/server/transport.d.ts +39 -0
  99. package/dist/server/transport.d.ts.map +1 -1
  100. package/dist/server/transport.js +134 -4
  101. package/dist/server/transport.js.map +1 -1
  102. package/dist/types.d.ts +18 -4
  103. package/dist/types.d.ts.map +1 -1
  104. package/dist/types.js +11 -0
  105. package/dist/types.js.map +1 -1
  106. package/package.json +12 -6
  107. package/dist/adapters/idNormalizer.d.ts +0 -22
  108. package/dist/adapters/idNormalizer.d.ts.map +0 -1
  109. package/dist/adapters/idNormalizer.js +0 -30
  110. package/dist/adapters/idNormalizer.js.map +0 -1
  111. package/dist/adapters/mcpErrorFormatter.d.ts.map +0 -1
  112. package/dist/adapters/mcpErrorFormatter.js +0 -24
  113. package/dist/adapters/mcpErrorFormatter.js.map +0 -1
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Build apcore middleware instances from Config Bus `mcp.middleware` entries.
3
+ *
4
+ * Config Bus schema (YAML, snake_case — matches Python/Rust bridges):
5
+ *
6
+ * ```yaml
7
+ * mcp:
8
+ * middleware:
9
+ * - type: retry
10
+ * max_retries: 3
11
+ * strategy: exponential
12
+ * base_delay_ms: 100
13
+ * max_delay_ms: 5000
14
+ * jitter: true
15
+ * - type: logging
16
+ * log_inputs: true
17
+ * log_outputs: true
18
+ * log_errors: true
19
+ * - type: error_history
20
+ * max_entries_per_module: 50
21
+ * max_total_entries: 1000
22
+ * ```
23
+ *
24
+ * Config Bus keys are snake_case (cross-language convention). The builder
25
+ * translates them to the camelCase fields the TypeScript apcore-js constructors
26
+ * expect. Mirrors the Python `middleware_builder.build_middleware_from_config`
27
+ * and Rust `middleware_builder::build_middleware_from_config` contracts.
28
+ * Unknown `type` throws so misconfiguration fails loudly at startup.
29
+ */
30
+ export interface MiddlewareConfigEntry {
31
+ type: string;
32
+ [key: string]: unknown;
33
+ }
34
+ /**
35
+ * Construct apcore middleware instances from Config Bus entries.
36
+ *
37
+ * Returns an empty array if `entries` is empty or apcore-js is not installed.
38
+ * Throws on unknown `type` or malformed entry.
39
+ */
40
+ export declare function buildMiddlewareFromConfig(entries: MiddlewareConfigEntry[] | null | undefined): Promise<unknown[]>;
41
+ //# sourceMappingURL=middleware-builder.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"middleware-builder.d.ts","sourceRoot":"","sources":["../src/middleware-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AASD;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,qBAAqB,EAAE,GAAG,IAAI,GAAG,SAAS,GAClD,OAAO,CAAC,OAAO,EAAE,CAAC,CA8GpB"}
@@ -0,0 +1,129 @@
1
+ /**
2
+ * Build apcore middleware instances from Config Bus `mcp.middleware` entries.
3
+ *
4
+ * Config Bus schema (YAML, snake_case — matches Python/Rust bridges):
5
+ *
6
+ * ```yaml
7
+ * mcp:
8
+ * middleware:
9
+ * - type: retry
10
+ * max_retries: 3
11
+ * strategy: exponential
12
+ * base_delay_ms: 100
13
+ * max_delay_ms: 5000
14
+ * jitter: true
15
+ * - type: logging
16
+ * log_inputs: true
17
+ * log_outputs: true
18
+ * log_errors: true
19
+ * - type: error_history
20
+ * max_entries_per_module: 50
21
+ * max_total_entries: 1000
22
+ * ```
23
+ *
24
+ * Config Bus keys are snake_case (cross-language convention). The builder
25
+ * translates them to the camelCase fields the TypeScript apcore-js constructors
26
+ * expect. Mirrors the Python `middleware_builder.build_middleware_from_config`
27
+ * and Rust `middleware_builder::build_middleware_from_config` contracts.
28
+ * Unknown `type` throws so misconfiguration fails loudly at startup.
29
+ */
30
+ /**
31
+ * Convert snake_case → camelCase, preserving single-word keys unchanged.
32
+ */
33
+ function snakeToCamel(key) {
34
+ return key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
35
+ }
36
+ /**
37
+ * Construct apcore middleware instances from Config Bus entries.
38
+ *
39
+ * Returns an empty array if `entries` is empty or apcore-js is not installed.
40
+ * Throws on unknown `type` or malformed entry.
41
+ */
42
+ export async function buildMiddlewareFromConfig(entries) {
43
+ if (!entries || entries.length === 0) {
44
+ return [];
45
+ }
46
+ let apcore;
47
+ try {
48
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
49
+ apcore = (await import("apcore-js"));
50
+ }
51
+ catch (err) {
52
+ throw new Error(`Config Bus 'mcp.middleware' requires apcore-js>=0.18 with middleware support: ${err.message}`);
53
+ }
54
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
55
+ const resolve = (name) => (apcore[name] ?? apcore.default?.[name]);
56
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
57
+ const RetryMiddleware = resolve("RetryMiddleware");
58
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
59
+ const LoggingMiddleware = resolve("LoggingMiddleware");
60
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
61
+ const ErrorHistoryMiddleware = resolve("ErrorHistoryMiddleware");
62
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
63
+ const ErrorHistory = resolve("ErrorHistory");
64
+ const instances = [];
65
+ for (let idx = 0; idx < entries.length; idx += 1) {
66
+ const entry = entries[idx];
67
+ if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
68
+ throw new Error(`mcp.middleware[${idx}] must be an object with a 'type' key`);
69
+ }
70
+ const { type, ...kwargs } = entry;
71
+ if (!type || typeof type !== "string") {
72
+ throw new Error(`mcp.middleware[${idx}] missing required 'type' key`);
73
+ }
74
+ switch (type) {
75
+ case "retry": {
76
+ if (!RetryMiddleware) {
77
+ throw new Error("apcore-js does not export RetryMiddleware");
78
+ }
79
+ // Map snake_case Config Bus keys → camelCase RetryConfig fields.
80
+ const cfg = {};
81
+ for (const [k, v] of Object.entries(kwargs)) {
82
+ cfg[snakeToCamel(k)] = v;
83
+ }
84
+ instances.push(Object.keys(cfg).length
85
+ ? new RetryMiddleware(cfg)
86
+ : new RetryMiddleware());
87
+ break;
88
+ }
89
+ case "logging": {
90
+ if (!LoggingMiddleware) {
91
+ throw new Error("apcore-js does not export LoggingMiddleware");
92
+ }
93
+ const opts = {};
94
+ for (const [k, v] of Object.entries(kwargs)) {
95
+ opts[snakeToCamel(k)] = v;
96
+ }
97
+ instances.push(Object.keys(opts).length
98
+ ? new LoggingMiddleware(opts)
99
+ : new LoggingMiddleware());
100
+ break;
101
+ }
102
+ case "error_history": {
103
+ if (!ErrorHistoryMiddleware || !ErrorHistory) {
104
+ throw new Error("apcore-js does not export ErrorHistoryMiddleware or ErrorHistory");
105
+ }
106
+ const maxPerModule = kwargs["max_entries_per_module"];
107
+ const maxTotal = kwargs["max_total_entries"];
108
+ const allowedKeys = new Set([
109
+ "max_entries_per_module",
110
+ "max_total_entries",
111
+ ]);
112
+ const extra = Object.keys(kwargs).filter((k) => !allowedKeys.has(k));
113
+ if (extra.length) {
114
+ throw new Error(`mcp.middleware[${idx}] (error_history) got unexpected keys: ${extra
115
+ .sort()
116
+ .join(", ")}`);
117
+ }
118
+ const history = new ErrorHistory(maxPerModule ?? 50, maxTotal ?? 1000);
119
+ instances.push(new ErrorHistoryMiddleware(history));
120
+ break;
121
+ }
122
+ default:
123
+ throw new Error(`mcp.middleware[${idx}] unknown type '${type}'. ` +
124
+ "Known built-in types: retry, logging, error_history");
125
+ }
126
+ }
127
+ return instances;
128
+ }
129
+ //# sourceMappingURL=middleware-builder.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"middleware-builder.js","sourceRoot":"","sources":["../src/middleware-builder.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,190 @@
1
+ /**
2
+ * AsyncTaskBridge — MCP ↔ apcore `AsyncTaskManager` adapter.
3
+ *
4
+ * Surfaces apcore's {@link AsyncTaskManager} through the MCP protocol so
5
+ * that long-running modules can be submitted, polled, cancelled, and listed
6
+ * via reserved meta-tools. Async-hinted modules (either
7
+ * `metadata.async === true` OR `annotations.extra["mcp_async"] === "true"`)
8
+ * are routed through `AsyncTaskManager.submit()` instead of the synchronous
9
+ * executor call path; the agent receives a `{task_id, status: "pending"}`
10
+ * envelope it can resolve via the four reserved `__apcore_task_*` meta-tools.
11
+ *
12
+ * Full spec: apcore-mcp/docs/features/async-task-bridge.md (F-043).
13
+ */
14
+ import type { ModuleDescriptor } from "../types.js";
15
+ /** Reserved meta-tool prefix. Module ids starting with this are forbidden. */
16
+ export declare const APCORE_META_TOOL_PREFIX = "__apcore_";
17
+ /** The four reserved meta-tool names. */
18
+ export declare const META_TOOL_NAMES: Readonly<{
19
+ readonly SUBMIT: "__apcore_task_submit";
20
+ readonly STATUS: "__apcore_task_status";
21
+ readonly CANCEL: "__apcore_task_cancel";
22
+ readonly LIST: "__apcore_task_list";
23
+ }>;
24
+ /** Duck-typed TaskInfo projection matching apcore-js `TaskInfo`. */
25
+ export interface TaskInfoProjection {
26
+ task_id: string;
27
+ module_id: string;
28
+ status: string;
29
+ submitted_at: number;
30
+ started_at: number | null;
31
+ completed_at: number | null;
32
+ result?: Record<string, unknown> | null;
33
+ error?: string | null;
34
+ }
35
+ /** Minimal duck-typed `AsyncTaskManager` contract the bridge depends on. */
36
+ export interface AsyncTaskManagerLike {
37
+ submit(moduleId: string, inputs: Record<string, unknown>, context?: unknown | null): Promise<string>;
38
+ getStatus(taskId: string): {
39
+ taskId: string;
40
+ moduleId: string;
41
+ status: string;
42
+ submittedAt: number;
43
+ startedAt: number | null;
44
+ completedAt: number | null;
45
+ result: Record<string, unknown> | null;
46
+ error: string | null;
47
+ } | null;
48
+ getResult(taskId: string): Record<string, unknown>;
49
+ cancel(taskId: string): Promise<boolean>;
50
+ listTasks(status?: string): Array<{
51
+ taskId: string;
52
+ moduleId: string;
53
+ status: string;
54
+ submittedAt: number;
55
+ startedAt: number | null;
56
+ completedAt: number | null;
57
+ result: Record<string, unknown> | null;
58
+ error: string | null;
59
+ }>;
60
+ shutdown?(): Promise<void>;
61
+ }
62
+ /** MCP-facing Tool shape used to advertise meta-tools. */
63
+ export interface AsyncMetaTool {
64
+ name: string;
65
+ description: string;
66
+ inputSchema: Record<string, unknown>;
67
+ }
68
+ /** Options for {@link AsyncTaskBridge}. */
69
+ export interface AsyncTaskBridgeOptions {
70
+ /** When false, `isAsyncModule()` always returns false — meta-tools are disabled. */
71
+ enabled?: boolean;
72
+ /**
73
+ * Optional output-redactor invoked on completed task results before they are
74
+ * returned from `__apcore_task_status`. Signature matches apcore-js's
75
+ * `redactSensitive(result, outputSchema)`.
76
+ */
77
+ redactSensitive?: (result: Record<string, unknown>, outputSchema: Record<string, unknown>) => Record<string, unknown>;
78
+ /** Map of module_id → output_schema used by `redactSensitive`. */
79
+ outputSchemaMap?: Record<string, Record<string, unknown>>;
80
+ /**
81
+ * Look up a module's descriptor by id. Used by `__apcore_task_submit` to
82
+ * enforce the spec rule "non-async module → ASYNC_MODULE_NOT_ASYNC".
83
+ * When omitted, the rule is skipped (preserves backwards-compatible
84
+ * behavior for tests / direct construction without a registry). [A-D-008]
85
+ */
86
+ descriptorLookup?: (moduleId: string) => ModuleDescriptor | null | undefined;
87
+ }
88
+ /**
89
+ * Routes MCP tool calls either to the synchronous Execution Router (default)
90
+ * or to `AsyncTaskManager.submit()` for async-hinted modules.
91
+ */
92
+ export declare class AsyncTaskBridge {
93
+ private readonly _manager;
94
+ private readonly _enabled;
95
+ private readonly _redactSensitive?;
96
+ private readonly _outputSchemaMap;
97
+ private readonly _descriptorLookup?;
98
+ /**
99
+ * Maps task_id → progressToken recorded at submit time so terminal-
100
+ * state notifications can be fanned out via the original token.
101
+ * [A-D-018]
102
+ */
103
+ private readonly _progressTokens;
104
+ /**
105
+ * Maps session/connection key → list of task ids launched from that
106
+ * session so {@link cancelSessionTasks} can cancel them on transport
107
+ * disconnect. Mirrors Rust's `session_tasks` map. [A-D-018]
108
+ */
109
+ private readonly _sessionTasks;
110
+ constructor(manager: AsyncTaskManagerLike, options?: AsyncTaskBridgeOptions);
111
+ /** Whether async routing and meta-tools are enabled. */
112
+ get enabled(): boolean;
113
+ /** Expose the underlying manager (used by server lifecycle for shutdown). */
114
+ get manager(): AsyncTaskManagerLike;
115
+ /**
116
+ * Return true if the descriptor carries an async hint — either
117
+ * `metadata.async === true` OR `annotations.extra["mcp_async"] === "true"`.
118
+ */
119
+ isAsyncModule(descriptor: ModuleDescriptor | null | undefined): boolean;
120
+ /**
121
+ * Submit a module invocation to the AsyncTaskManager. Returns the standard
122
+ * MCP envelope `{task_id, status: "pending"}`.
123
+ */
124
+ submit(moduleId: string, inputs: Record<string, unknown>, context?: unknown | null, options?: {
125
+ /** Optional MCP progress token (recorded for fan-out). [A-D-018] */
126
+ progressToken?: string | number;
127
+ /** Optional session/connection key (recorded for cancelSessionTasks). [A-D-018] */
128
+ sessionKey?: string;
129
+ /**
130
+ * Optional notification sender. When provided together with `progressToken`,
131
+ * a progress sink is installed on the apcore Context so mid-execution progress
132
+ * events from modules are forwarded as `notifications/progress` MCP messages.
133
+ * Mirrors Python's `_install_progress_sink` pattern. [D11-015]
134
+ */
135
+ sendNotification?: (notification: Record<string, unknown>) => Promise<void> | void;
136
+ }): Promise<{
137
+ task_id: string;
138
+ status: "pending";
139
+ }>;
140
+ /**
141
+ * Look up the progress token recorded for a task at submit time.
142
+ *
143
+ * Used by transport / terminal-notification dispatch to route
144
+ * `notifications/progress` to the original caller. Returns undefined
145
+ * when no token was registered. [A-D-018]
146
+ */
147
+ getProgressToken(taskId: string): string | number | undefined;
148
+ /**
149
+ * Cancel every async task currently tracked under `sessionKey`.
150
+ *
151
+ * Used by the transport layer on client disconnect to ensure
152
+ * long-running tasks bound to that session don't keep running after
153
+ * the client has gone. Returns the number of tasks cancelled.
154
+ * Mirrors Rust's `AsyncTaskBridge::cancel_session_tasks`. [A-D-018]
155
+ */
156
+ cancelSessionTasks(sessionKey: string): Promise<number>;
157
+ /**
158
+ * Build the four MCP meta-tool definitions. Caller merges these with
159
+ * the regular tool list returned by `tools/list`.
160
+ */
161
+ buildMetaTools(): AsyncMetaTool[];
162
+ /**
163
+ * Whether `toolName` is one of the reserved meta-tools. Used by the
164
+ * execution router to short-circuit dispatch before touching the executor.
165
+ */
166
+ isMetaTool(toolName: string): boolean;
167
+ /**
168
+ * Dispatch a meta-tool invocation. The caller must have already confirmed
169
+ * `isMetaTool(toolName)` is true.
170
+ */
171
+ handleMetaTool(toolName: string, args: Record<string, unknown>, context?: unknown | null): Promise<Record<string, unknown>>;
172
+ private _projectTaskInfo;
173
+ }
174
+ /**
175
+ * Factory that dynamically imports apcore-js's `AsyncTaskManager` and wraps
176
+ * it in an `AsyncTaskBridge`. Returns null when apcore-js is unavailable.
177
+ */
178
+ export declare function createAsyncTaskBridge(executor: unknown, options?: {
179
+ enabled?: boolean;
180
+ maxConcurrent?: number;
181
+ maxTasks?: number;
182
+ outputSchemaMap?: Record<string, Record<string, unknown>>;
183
+ /**
184
+ * Optional descriptor lookup (typically `(id) => registry.getDefinition(id)`).
185
+ * When provided, `__apcore_task_submit` enforces the spec's
186
+ * ASYNC_MODULE_NOT_ASYNC rule. [A-D-008]
187
+ */
188
+ descriptorLookup?: (moduleId: string) => ModuleDescriptor | null | undefined;
189
+ }): Promise<AsyncTaskBridge | null>;
190
+ //# sourceMappingURL=async-task-bridge.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"async-task-bridge.d.ts","sourceRoot":"","sources":["../../src/server/async-task-bridge.ts"],"names":[],"mappings":"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"}