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.
- package/LICENSE +190 -0
- package/README.md +165 -19
- package/dist/acl-builder.d.ts +43 -0
- package/dist/acl-builder.d.ts.map +1 -0
- package/dist/acl-builder.js +115 -0
- package/dist/acl-builder.js.map +1 -0
- package/dist/adapters/annotations.d.ts.map +1 -1
- package/dist/adapters/annotations.js +37 -2
- package/dist/adapters/annotations.js.map +1 -1
- package/dist/adapters/errors.d.ts +17 -0
- package/dist/adapters/errors.d.ts.map +1 -1
- package/dist/adapters/errors.js +192 -2
- package/dist/adapters/errors.js.map +1 -1
- package/dist/adapters/id-normalizer.d.ts +40 -0
- package/dist/adapters/id-normalizer.d.ts.map +1 -0
- package/dist/adapters/id-normalizer.js +59 -0
- package/dist/adapters/id-normalizer.js.map +1 -0
- package/dist/adapters/index.d.ts +2 -2
- package/dist/adapters/index.d.ts.map +1 -1
- package/dist/adapters/index.js +2 -2
- package/dist/adapters/index.js.map +1 -1
- package/dist/adapters/{mcpErrorFormatter.d.ts → mcp-error-formatter.d.ts} +5 -7
- package/dist/adapters/mcp-error-formatter.d.ts.map +1 -0
- package/dist/adapters/mcp-error-formatter.js +30 -0
- package/dist/adapters/mcp-error-formatter.js.map +1 -0
- package/dist/adapters/schema.d.ts +21 -4
- package/dist/adapters/schema.d.ts.map +1 -1
- package/dist/adapters/schema.js +147 -13
- package/dist/adapters/schema.js.map +1 -1
- package/dist/apcore-mcp.d.ts +24 -2
- package/dist/apcore-mcp.d.ts.map +1 -1
- package/dist/apcore-mcp.js +8 -0
- package/dist/apcore-mcp.js.map +1 -1
- package/dist/auth/hooks.d.ts +1 -1
- package/dist/auth/hooks.d.ts.map +1 -1
- package/dist/auth/hooks.js +10 -3
- package/dist/auth/hooks.js.map +1 -1
- package/dist/auth/jwt.d.ts +1 -2
- package/dist/auth/jwt.d.ts.map +1 -1
- package/dist/auth/jwt.js +18 -10
- package/dist/auth/jwt.js.map +1 -1
- package/dist/auth/types.d.ts +6 -3
- package/dist/auth/types.d.ts.map +1 -1
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +23 -1
- package/dist/cli.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +15 -6
- package/dist/config.js.map +1 -1
- package/dist/converters/openai.d.ts +10 -0
- package/dist/converters/openai.d.ts.map +1 -1
- package/dist/converters/openai.js +100 -5
- package/dist/converters/openai.js.map +1 -1
- package/dist/explorer/index.d.ts +2 -0
- package/dist/explorer/index.d.ts.map +1 -0
- package/dist/explorer/index.js +2 -0
- package/dist/explorer/index.js.map +1 -0
- package/dist/index.d.ts +68 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +346 -60
- package/dist/index.js.map +1 -1
- package/dist/inspector/index.d.ts +2 -0
- package/dist/inspector/index.d.ts.map +1 -0
- package/dist/inspector/index.js +2 -0
- package/dist/inspector/index.js.map +1 -0
- package/dist/middleware-builder.d.ts +41 -0
- package/dist/middleware-builder.d.ts.map +1 -0
- package/dist/middleware-builder.js +129 -0
- package/dist/middleware-builder.js.map +1 -0
- package/dist/server/async-task-bridge.d.ts +190 -0
- package/dist/server/async-task-bridge.d.ts.map +1 -0
- package/dist/server/async-task-bridge.js +393 -0
- package/dist/server/async-task-bridge.js.map +1 -0
- package/dist/server/context.d.ts +9 -2
- package/dist/server/context.d.ts.map +1 -1
- package/dist/server/context.js +14 -6
- package/dist/server/context.js.map +1 -1
- package/dist/server/factory.d.ts +25 -2
- package/dist/server/factory.d.ts.map +1 -1
- package/dist/server/factory.js +127 -7
- package/dist/server/factory.js.map +1 -1
- package/dist/server/listener.d.ts +3 -0
- package/dist/server/listener.d.ts.map +1 -1
- package/dist/server/listener.js +13 -2
- package/dist/server/listener.js.map +1 -1
- package/dist/server/observability.d.ts +51 -0
- package/dist/server/observability.d.ts.map +1 -0
- package/dist/server/observability.js +96 -0
- package/dist/server/observability.js.map +1 -0
- package/dist/server/router.d.ts +114 -0
- package/dist/server/router.d.ts.map +1 -1
- package/dist/server/router.js +360 -18
- package/dist/server/router.js.map +1 -1
- package/dist/server/trace-context.d.ts +40 -0
- package/dist/server/trace-context.d.ts.map +1 -0
- package/dist/server/trace-context.js +67 -0
- package/dist/server/trace-context.js.map +1 -0
- package/dist/server/transport.d.ts +39 -0
- package/dist/server/transport.d.ts.map +1 -1
- package/dist/server/transport.js +134 -4
- package/dist/server/transport.js.map +1 -1
- package/dist/types.d.ts +18 -4
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +11 -0
- package/dist/types.js.map +1 -1
- package/package.json +12 -6
- package/dist/adapters/idNormalizer.d.ts +0 -22
- package/dist/adapters/idNormalizer.d.ts.map +0 -1
- package/dist/adapters/idNormalizer.js +0 -30
- package/dist/adapters/idNormalizer.js.map +0 -1
- package/dist/adapters/mcpErrorFormatter.d.ts.map +0 -1
- package/dist/adapters/mcpErrorFormatter.js +0 -24
- 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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"}
|