agentfootprint 12.1.0 → 12.2.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/AGENTS.md +1 -1
- package/CAPABILITIES.md +3 -1
- package/ai-instructions/claude-code/SKILL.md +1 -1
- package/dist/adapters/mcp/agentcoreRuntime/invoke.js +113 -7
- package/dist/adapters/mcp/agentcoreRuntime/invoke.js.map +1 -1
- package/dist/adapters/mcp/agentcoreRuntime/session.js +21 -21
- package/dist/adapters/mcp/agentcoreRuntime/session.js.map +1 -1
- package/dist/adapters/mcp/agentcoreRuntime/transport.js +79 -5
- package/dist/adapters/mcp/agentcoreRuntime/transport.js.map +1 -1
- package/dist/core/Agent.js +6 -0
- package/dist/core/Agent.js.map +1 -1
- package/dist/core/agent/stages/toolCalls.js +4 -0
- package/dist/core/agent/stages/toolCalls.js.map +1 -1
- package/dist/core/slots/buildToolsSlot.js +8 -0
- package/dist/core/slots/buildToolsSlot.js.map +1 -1
- package/dist/esm/adapters/mcp/agentcoreRuntime/invoke.d.ts +23 -4
- package/dist/esm/adapters/mcp/agentcoreRuntime/invoke.js +112 -6
- package/dist/esm/adapters/mcp/agentcoreRuntime/invoke.js.map +1 -1
- package/dist/esm/adapters/mcp/agentcoreRuntime/session.d.ts +20 -6
- package/dist/esm/adapters/mcp/agentcoreRuntime/session.js +21 -21
- package/dist/esm/adapters/mcp/agentcoreRuntime/session.js.map +1 -1
- package/dist/esm/adapters/mcp/agentcoreRuntime/transport.js +81 -7
- package/dist/esm/adapters/mcp/agentcoreRuntime/transport.js.map +1 -1
- package/dist/esm/core/Agent.js +6 -0
- package/dist/esm/core/Agent.js.map +1 -1
- package/dist/esm/core/agent/stages/toolCalls.js +4 -0
- package/dist/esm/core/agent/stages/toolCalls.js.map +1 -1
- package/dist/esm/core/slots/buildToolsSlot.d.ts +12 -0
- package/dist/esm/core/slots/buildToolsSlot.js +8 -0
- package/dist/esm/core/slots/buildToolsSlot.js.map +1 -1
- package/dist/esm/events/payloads.d.ts +41 -0
- package/dist/esm/events/registry.d.ts +3 -1
- package/dist/esm/events/registry.js +2 -0
- package/dist/esm/events/registry.js.map +1 -1
- package/dist/esm/identity/types.d.ts +7 -3
- package/dist/esm/identity/types.js.map +1 -1
- package/dist/esm/index.d.ts +1 -1
- package/dist/esm/index.js +4 -1
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/lib/boundedJson.d.ts +14 -7
- package/dist/esm/lib/boundedJson.js +14 -7
- package/dist/esm/lib/boundedJson.js.map +1 -1
- package/dist/esm/mcp/callLifetime.js +5 -2
- package/dist/esm/mcp/callLifetime.js.map +1 -1
- package/dist/esm/mcp/clientPort.d.ts +78 -0
- package/dist/esm/mcp/clientPort.js +33 -0
- package/dist/esm/mcp/clientPort.js.map +1 -0
- package/dist/esm/mcp/gatewayTransport.js +13 -3
- package/dist/esm/mcp/gatewayTransport.js.map +1 -1
- package/dist/esm/mcp/index.d.ts +9 -1
- package/dist/esm/mcp/index.js +8 -0
- package/dist/esm/mcp/index.js.map +1 -1
- package/dist/esm/mcp/mcpClient.d.ts +18 -1
- package/dist/esm/mcp/mcpClient.js +203 -43
- package/dist/esm/mcp/mcpClient.js.map +1 -1
- package/dist/esm/mcp/mockMcpClient.js +13 -0
- package/dist/esm/mcp/mockMcpClient.js.map +1 -1
- package/dist/esm/mcp/pool/boundTool.d.ts +58 -0
- package/dist/esm/mcp/pool/boundTool.js +218 -0
- package/dist/esm/mcp/pool/boundTool.js.map +1 -0
- package/dist/esm/mcp/pool/clientSet.d.ts +73 -0
- package/dist/esm/mcp/pool/clientSet.js +152 -0
- package/dist/esm/mcp/pool/clientSet.js.map +1 -0
- package/dist/esm/mcp/pool/definitions.d.ts +103 -0
- package/dist/esm/mcp/pool/definitions.js +168 -0
- package/dist/esm/mcp/pool/definitions.js.map +1 -0
- package/dist/esm/mcp/pool/errors.d.ts +76 -0
- package/dist/esm/mcp/pool/errors.js +91 -0
- package/dist/esm/mcp/pool/errors.js.map +1 -0
- package/dist/esm/mcp/pool/identityKey.d.ts +57 -0
- package/dist/esm/mcp/pool/identityKey.js +94 -0
- package/dist/esm/mcp/pool/identityKey.js.map +1 -0
- package/dist/esm/mcp/pool/lease.d.ts +36 -0
- package/dist/esm/mcp/pool/lease.js +51 -0
- package/dist/esm/mcp/pool/lease.js.map +1 -0
- package/dist/esm/mcp/pool/listTools.d.ts +33 -0
- package/dist/esm/mcp/pool/listTools.js +146 -0
- package/dist/esm/mcp/pool/listTools.js.map +1 -0
- package/dist/esm/mcp/pool/mcpClientPool.d.ts +121 -0
- package/dist/esm/mcp/pool/mcpClientPool.js +151 -0
- package/dist/esm/mcp/pool/mcpClientPool.js.map +1 -0
- package/dist/esm/mcp/pool/options.d.ts +183 -0
- package/dist/esm/mcp/pool/options.js +119 -0
- package/dist/esm/mcp/pool/options.js.map +1 -0
- package/dist/esm/mcp/pool/plan.d.ts +77 -0
- package/dist/esm/mcp/pool/plan.js +134 -0
- package/dist/esm/mcp/pool/plan.js.map +1 -0
- package/dist/esm/mcp/pool/pool.d.ts +307 -0
- package/dist/esm/mcp/pool/pool.js +1071 -0
- package/dist/esm/mcp/pool/pool.js.map +1 -0
- package/dist/esm/mcp/pool/pooledClient.d.ts +93 -0
- package/dist/esm/mcp/pool/pooledClient.js +90 -0
- package/dist/esm/mcp/pool/pooledClient.js.map +1 -0
- package/dist/esm/mcp/pool/record.d.ts +80 -0
- package/dist/esm/mcp/pool/record.js +75 -0
- package/dist/esm/mcp/pool/record.js.map +1 -0
- package/dist/esm/mcp/pool/sessionEnded.d.ts +24 -0
- package/dist/esm/mcp/pool/sessionEnded.js +31 -0
- package/dist/esm/mcp/pool/sessionEnded.js.map +1 -0
- package/dist/esm/mcp/pool/work.d.ts +116 -0
- package/dist/esm/mcp/pool/work.js +213 -0
- package/dist/esm/mcp/pool/work.js.map +1 -0
- package/dist/esm/mcp/requestGuard.d.ts +70 -0
- package/dist/esm/mcp/requestGuard.js +98 -0
- package/dist/esm/mcp/requestGuard.js.map +1 -0
- package/dist/esm/mcp/requestLedger.d.ts +35 -1
- package/dist/esm/mcp/requestLedger.js +76 -3
- package/dist/esm/mcp/requestLedger.js.map +1 -1
- package/dist/esm/mcp/seriesEvidence.d.ts +10 -6
- package/dist/esm/mcp/seriesEvidence.js +16 -7
- package/dist/esm/mcp/seriesEvidence.js.map +1 -1
- package/dist/esm/mcp/terminate.d.ts +94 -0
- package/dist/esm/mcp/terminate.js +184 -0
- package/dist/esm/mcp/terminate.js.map +1 -0
- package/dist/esm/mcp/throttleRetry.js +71 -7
- package/dist/esm/mcp/throttleRetry.js.map +1 -1
- package/dist/esm/mcp/types.d.ts +85 -7
- package/dist/esm/redaction/knownStrings.js +34 -0
- package/dist/esm/redaction/knownStrings.js.map +1 -1
- package/dist/esm/tool-providers/index.d.ts +2 -2
- package/dist/esm/tool-providers/index.js +7 -1
- package/dist/esm/tool-providers/index.js.map +1 -1
- package/dist/esm/tools/mcpClientUse.d.ts +59 -0
- package/dist/esm/tools/mcpClientUse.js +216 -0
- package/dist/esm/tools/mcpClientUse.js.map +1 -0
- package/dist/esm/tools/toolProvider.d.ts +16 -0
- package/dist/esm/tools/toolSessions.d.ts +41 -0
- package/dist/esm/tools/toolSessions.js +41 -1
- package/dist/esm/tools/toolSessions.js.map +1 -1
- package/dist/events/registry.js +2 -0
- package/dist/events/registry.js.map +1 -1
- package/dist/identity/types.js.map +1 -1
- package/dist/index.js +6 -3
- package/dist/index.js.map +1 -1
- package/dist/lib/boundedJson.js +14 -7
- package/dist/lib/boundedJson.js.map +1 -1
- package/dist/mcp/callLifetime.js +5 -2
- package/dist/mcp/callLifetime.js.map +1 -1
- package/dist/mcp/clientPort.js +38 -0
- package/dist/mcp/clientPort.js.map +1 -0
- package/dist/mcp/gatewayTransport.js +13 -3
- package/dist/mcp/gatewayTransport.js.map +1 -1
- package/dist/mcp/index.js +16 -1
- package/dist/mcp/index.js.map +1 -1
- package/dist/mcp/mcpClient.js +207 -45
- package/dist/mcp/mcpClient.js.map +1 -1
- package/dist/mcp/mockMcpClient.js +13 -0
- package/dist/mcp/mockMcpClient.js.map +1 -1
- package/dist/mcp/pool/boundTool.js +223 -0
- package/dist/mcp/pool/boundTool.js.map +1 -0
- package/dist/mcp/pool/clientSet.js +157 -0
- package/dist/mcp/pool/clientSet.js.map +1 -0
- package/dist/mcp/pool/definitions.js +174 -0
- package/dist/mcp/pool/definitions.js.map +1 -0
- package/dist/mcp/pool/errors.js +96 -0
- package/dist/mcp/pool/errors.js.map +1 -0
- package/dist/mcp/pool/identityKey.js +99 -0
- package/dist/mcp/pool/identityKey.js.map +1 -0
- package/dist/mcp/pool/lease.js +55 -0
- package/dist/mcp/pool/lease.js.map +1 -0
- package/dist/mcp/pool/listTools.js +150 -0
- package/dist/mcp/pool/listTools.js.map +1 -0
- package/dist/mcp/pool/mcpClientPool.js +155 -0
- package/dist/mcp/pool/mcpClientPool.js.map +1 -0
- package/dist/mcp/pool/options.js +123 -0
- package/dist/mcp/pool/options.js.map +1 -0
- package/dist/mcp/pool/plan.js +140 -0
- package/dist/mcp/pool/plan.js.map +1 -0
- package/dist/mcp/pool/pool.js +1075 -0
- package/dist/mcp/pool/pool.js.map +1 -0
- package/dist/mcp/pool/pooledClient.js +94 -0
- package/dist/mcp/pool/pooledClient.js.map +1 -0
- package/dist/mcp/pool/record.js +80 -0
- package/dist/mcp/pool/record.js.map +1 -0
- package/dist/mcp/pool/sessionEnded.js +35 -0
- package/dist/mcp/pool/sessionEnded.js.map +1 -0
- package/dist/mcp/pool/work.js +219 -0
- package/dist/mcp/pool/work.js.map +1 -0
- package/dist/mcp/requestGuard.js +106 -0
- package/dist/mcp/requestGuard.js.map +1 -0
- package/dist/mcp/requestLedger.js +76 -3
- package/dist/mcp/requestLedger.js.map +1 -1
- package/dist/mcp/seriesEvidence.js +16 -7
- package/dist/mcp/seriesEvidence.js.map +1 -1
- package/dist/mcp/terminate.js +193 -0
- package/dist/mcp/terminate.js.map +1 -0
- package/dist/mcp/throttleRetry.js +71 -7
- package/dist/mcp/throttleRetry.js.map +1 -1
- package/dist/redaction/knownStrings.js +34 -0
- package/dist/redaction/knownStrings.js.map +1 -1
- package/dist/tool-providers/index.js +12 -1
- package/dist/tool-providers/index.js.map +1 -1
- package/dist/tools/mcpClientUse.js +225 -0
- package/dist/tools/mcpClientUse.js.map +1 -0
- package/dist/tools/toolSessions.js +44 -1
- package/dist/tools/toolSessions.js.map +1 -1
- package/dist/types/adapters/mcp/agentcoreRuntime/invoke.d.ts +23 -4
- package/dist/types/adapters/mcp/agentcoreRuntime/invoke.d.ts.map +1 -1
- package/dist/types/adapters/mcp/agentcoreRuntime/session.d.ts +20 -6
- package/dist/types/adapters/mcp/agentcoreRuntime/session.d.ts.map +1 -1
- package/dist/types/adapters/mcp/agentcoreRuntime/transport.d.ts.map +1 -1
- package/dist/types/core/Agent.d.ts.map +1 -1
- package/dist/types/core/agent/stages/toolCalls.d.ts.map +1 -1
- package/dist/types/core/slots/buildToolsSlot.d.ts +12 -0
- package/dist/types/core/slots/buildToolsSlot.d.ts.map +1 -1
- package/dist/types/events/payloads.d.ts +41 -0
- package/dist/types/events/payloads.d.ts.map +1 -1
- package/dist/types/events/registry.d.ts +3 -1
- package/dist/types/events/registry.d.ts.map +1 -1
- package/dist/types/identity/types.d.ts +7 -3
- package/dist/types/identity/types.d.ts.map +1 -1
- package/dist/types/index.d.ts +1 -1
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/lib/boundedJson.d.ts +14 -7
- package/dist/types/lib/boundedJson.d.ts.map +1 -1
- package/dist/types/mcp/callLifetime.d.ts.map +1 -1
- package/dist/types/mcp/clientPort.d.ts +79 -0
- package/dist/types/mcp/clientPort.d.ts.map +1 -0
- package/dist/types/mcp/gatewayTransport.d.ts.map +1 -1
- package/dist/types/mcp/index.d.ts +9 -1
- package/dist/types/mcp/index.d.ts.map +1 -1
- package/dist/types/mcp/mcpClient.d.ts +18 -1
- package/dist/types/mcp/mcpClient.d.ts.map +1 -1
- package/dist/types/mcp/mockMcpClient.d.ts.map +1 -1
- package/dist/types/mcp/pool/boundTool.d.ts +59 -0
- package/dist/types/mcp/pool/boundTool.d.ts.map +1 -0
- package/dist/types/mcp/pool/clientSet.d.ts +74 -0
- package/dist/types/mcp/pool/clientSet.d.ts.map +1 -0
- package/dist/types/mcp/pool/definitions.d.ts +104 -0
- package/dist/types/mcp/pool/definitions.d.ts.map +1 -0
- package/dist/types/mcp/pool/errors.d.ts +77 -0
- package/dist/types/mcp/pool/errors.d.ts.map +1 -0
- package/dist/types/mcp/pool/identityKey.d.ts +58 -0
- package/dist/types/mcp/pool/identityKey.d.ts.map +1 -0
- package/dist/types/mcp/pool/lease.d.ts +37 -0
- package/dist/types/mcp/pool/lease.d.ts.map +1 -0
- package/dist/types/mcp/pool/listTools.d.ts +34 -0
- package/dist/types/mcp/pool/listTools.d.ts.map +1 -0
- package/dist/types/mcp/pool/mcpClientPool.d.ts +122 -0
- package/dist/types/mcp/pool/mcpClientPool.d.ts.map +1 -0
- package/dist/types/mcp/pool/options.d.ts +184 -0
- package/dist/types/mcp/pool/options.d.ts.map +1 -0
- package/dist/types/mcp/pool/plan.d.ts +78 -0
- package/dist/types/mcp/pool/plan.d.ts.map +1 -0
- package/dist/types/mcp/pool/pool.d.ts +308 -0
- package/dist/types/mcp/pool/pool.d.ts.map +1 -0
- package/dist/types/mcp/pool/pooledClient.d.ts +94 -0
- package/dist/types/mcp/pool/pooledClient.d.ts.map +1 -0
- package/dist/types/mcp/pool/record.d.ts +81 -0
- package/dist/types/mcp/pool/record.d.ts.map +1 -0
- package/dist/types/mcp/pool/sessionEnded.d.ts +25 -0
- package/dist/types/mcp/pool/sessionEnded.d.ts.map +1 -0
- package/dist/types/mcp/pool/work.d.ts +117 -0
- package/dist/types/mcp/pool/work.d.ts.map +1 -0
- package/dist/types/mcp/requestGuard.d.ts +71 -0
- package/dist/types/mcp/requestGuard.d.ts.map +1 -0
- package/dist/types/mcp/requestLedger.d.ts +35 -1
- package/dist/types/mcp/requestLedger.d.ts.map +1 -1
- package/dist/types/mcp/seriesEvidence.d.ts +10 -6
- package/dist/types/mcp/seriesEvidence.d.ts.map +1 -1
- package/dist/types/mcp/terminate.d.ts +95 -0
- package/dist/types/mcp/terminate.d.ts.map +1 -0
- package/dist/types/mcp/throttleRetry.d.ts.map +1 -1
- package/dist/types/mcp/types.d.ts +85 -7
- package/dist/types/mcp/types.d.ts.map +1 -1
- package/dist/types/redaction/knownStrings.d.ts.map +1 -1
- package/dist/types/tool-providers/index.d.ts +2 -2
- package/dist/types/tool-providers/index.d.ts.map +1 -1
- package/dist/types/tools/mcpClientUse.d.ts +60 -0
- package/dist/types/tools/mcpClientUse.d.ts.map +1 -0
- package/dist/types/tools/toolProvider.d.ts +16 -0
- package/dist/types/tools/toolProvider.d.ts.map +1 -1
- package/dist/types/tools/toolSessions.d.ts +41 -0
- package/dist/types/tools/toolSessions.d.ts.map +1 -1
- package/package.json +3 -3
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* pool — the state behind `mcpClientPool`: who holds which client, what is
|
|
3
|
+
* charged, and what ends when.
|
|
4
|
+
*
|
|
5
|
+
* Pattern: one state machine, mutated only between awaits.
|
|
6
|
+
* Role: §§ 5–7 of the design. Every mutation of the sets and the budget runs
|
|
7
|
+
* synchronously — a check and the move it allows are never split by
|
|
8
|
+
* an await — so two callers cannot both take the last slot.
|
|
9
|
+
*
|
|
10
|
+
* - ADMISSION: every listing, call, acquire and ending is admitted against
|
|
11
|
+
* `maxOperations` before anything is sent. At each interaction the lazy
|
|
12
|
+
* sweep (revoked leases, idle ends, deferred ends) runs FIRST, so it
|
|
13
|
+
* reserves its endings before the new operation is admitted.
|
|
14
|
+
* - ONE OPEN PER KEY, from a plan resolved at that moment, under the pool's own
|
|
15
|
+
* signal and `initTimeoutMs`, never a caller's. A caller that gives up
|
|
16
|
+
* detaches alone; the operation that started the open keeps its charge until
|
|
17
|
+
* the open's work settles. Past the deadline every waiter is refused at once
|
|
18
|
+
* (`init-timeout`), and until the open's work settles the key cannot open
|
|
19
|
+
* again. A failure reaches every current waiter and is not cached.
|
|
20
|
+
* - THE HANDOFF: every operation waiting for an open holds a RESERVATION on
|
|
21
|
+
* the client until it takes its lease, so between the open settling and
|
|
22
|
+
* that lease the client is busy — nobody can evict, idle-end or end it. The
|
|
23
|
+
* client's state is checked again after every wait, and the lease taken in
|
|
24
|
+
* the same step: a lease is never handed out on a client that is ending.
|
|
25
|
+
* - MAKING ROOM: the principal's, then the pool's, least recently used IDLE
|
|
26
|
+
* client moves to the ending set — or `PoolFullError` at once.
|
|
27
|
+
* - ENDING reserves an ending slot and an operation slot FIRST; when either is
|
|
28
|
+
* full the client stays in the open set, counted, reported deferred, and is
|
|
29
|
+
* ended when slots free. Every end goes through `terminate()` — but a client
|
|
30
|
+
* whose handle this process lost: nothing can be sent for it, so its ending
|
|
31
|
+
* is its local close alone, charged the same way until it settles.
|
|
32
|
+
* - SETTLEMENT, never an abort, returns a slot (`work.ts`).
|
|
33
|
+
* - NOTHING UNCHECKED: on a pooled client every request carries a guard — its
|
|
34
|
+
* call's, or the client's open, listing or ending — and a request with none
|
|
35
|
+
* is refused before it is sent (`request-unmatched`), at the watched `send`
|
|
36
|
+
* and at the pool's own fetch alike.
|
|
37
|
+
*/
|
|
38
|
+
import type { Tool } from '../../tools/tools.js';
|
|
39
|
+
import type { McpTerminateOutcome } from '../types.js';
|
|
40
|
+
import { ClientSet, type PreviousEnd } from './clientSet.js';
|
|
41
|
+
import { SharedDefinitions, type Definition, type DefinitionList } from './definitions.js';
|
|
42
|
+
import { McpPoolRefusedError, PoolFullError, type McpPoolLimit } from './errors.js';
|
|
43
|
+
import { type PoolKey } from './identityKey.js';
|
|
44
|
+
import { type PoolSettings } from './options.js';
|
|
45
|
+
import { type ClientPlan } from './plan.js';
|
|
46
|
+
import { PooledClient, type EndReason } from './pooledClient.js';
|
|
47
|
+
import { Reporter, type UseFacts } from './record.js';
|
|
48
|
+
import { OperationBudget, Work, type Operation, type OperationKind, type WorkKind } from './work.js';
|
|
49
|
+
/** An app lease, as the pool tracks it for `maxLeaseMs`. */
|
|
50
|
+
export interface HeldLease {
|
|
51
|
+
readonly client: PooledClient;
|
|
52
|
+
readonly takenAt: number;
|
|
53
|
+
/** Revoked: its next use throws `lease-expired`. */
|
|
54
|
+
revoked: boolean;
|
|
55
|
+
/** Released: idempotent. */
|
|
56
|
+
released: boolean;
|
|
57
|
+
}
|
|
58
|
+
/** Where a list's definitions live: a client's own, or a shared entry. */
|
|
59
|
+
export interface ServedList {
|
|
60
|
+
readonly list: DefinitionList;
|
|
61
|
+
readonly shared: boolean;
|
|
62
|
+
/** The definitions context: `pc:` or `sh:`. */
|
|
63
|
+
readonly context: string;
|
|
64
|
+
}
|
|
65
|
+
/** What `stats()` returns: counts, never keys. */
|
|
66
|
+
export interface McpPoolStats {
|
|
67
|
+
/** Clients in the open set: opening, busy or idle. */
|
|
68
|
+
readonly open: number;
|
|
69
|
+
readonly busy: number;
|
|
70
|
+
readonly idle: number;
|
|
71
|
+
readonly opening: number;
|
|
72
|
+
/** Clients being ended, until each ending's work has settled. */
|
|
73
|
+
readonly ending: number;
|
|
74
|
+
/** Operations charged. */
|
|
75
|
+
readonly operations: number;
|
|
76
|
+
/** Shared definition entries kept. */
|
|
77
|
+
readonly entries: number;
|
|
78
|
+
/** Charged work past its deadline that has not settled, by what it is doing. */
|
|
79
|
+
readonly unsettled: Readonly<Record<WorkKind, number>>;
|
|
80
|
+
/** Endings whose remote outcome was not confirmed. */
|
|
81
|
+
readonly unresolvedEndings: number;
|
|
82
|
+
}
|
|
83
|
+
export declare class Pool {
|
|
84
|
+
readonly settings: PoolSettings;
|
|
85
|
+
readonly clients: ClientSet;
|
|
86
|
+
readonly budget: OperationBudget;
|
|
87
|
+
readonly shared: SharedDefinitions;
|
|
88
|
+
readonly reporter: Reporter;
|
|
89
|
+
/** The pool's own signal: what every open, listing and call runs under; aborted at `close()`. */
|
|
90
|
+
private readonly lifetime;
|
|
91
|
+
private readonly leases;
|
|
92
|
+
private readonly settleWaiters;
|
|
93
|
+
/** Waiting for some client to become idle (`terminate`, `close`). */
|
|
94
|
+
private readonly idleWaiters;
|
|
95
|
+
closed: boolean;
|
|
96
|
+
unresolvedEndings: number;
|
|
97
|
+
constructor(settings: PoolSettings);
|
|
98
|
+
now(): number;
|
|
99
|
+
get signal(): AbortSignal;
|
|
100
|
+
/**
|
|
101
|
+
* The lazy sweep, run at the start of every interaction: leases past
|
|
102
|
+
* `maxLeaseMs` revoked, idle clients ended, deferred endings retried — all of
|
|
103
|
+
* it before a new operation is admitted.
|
|
104
|
+
*/
|
|
105
|
+
interact(): void;
|
|
106
|
+
/**
|
|
107
|
+
* Admit one operation, or refuse at once: `closed`, or `PoolFullError`
|
|
108
|
+
* (`limit: 'operations'`) — before anything is sent.
|
|
109
|
+
*/
|
|
110
|
+
admit(kind: OperationKind, phase: WorkKind, callerSignal: AbortSignal | undefined): Operation;
|
|
111
|
+
refused(reason: McpPoolRefusedError['reason'], cause?: unknown): McpPoolRefusedError;
|
|
112
|
+
full(limit: McpPoolLimit): PoolFullError;
|
|
113
|
+
/**
|
|
114
|
+
* A library lease on `key`'s client for `operation`, opening one when the key
|
|
115
|
+
* has none (inside the operation's slot). `plan` is the plan resolved for a
|
|
116
|
+
* new client; a key that already has one keeps its own. The lease is
|
|
117
|
+
* released when the operation SETTLES.
|
|
118
|
+
*/
|
|
119
|
+
leaseClient(key: PoolKey, operation: Operation, facts: UseFacts, plan?: ClientPlan): Promise<PooledClient>;
|
|
120
|
+
/**
|
|
121
|
+
* Wait for `client`'s open inside `operation`, holding a reservation on it
|
|
122
|
+
* all the while — between the open settling and this lease the client is
|
|
123
|
+
* busy, so nobody can evict, idle-end or end it — then check it again and
|
|
124
|
+
* lease it in the same step, with no wait between. `undefined` when it no
|
|
125
|
+
* longer serves: the caller's next round finds the key's next client.
|
|
126
|
+
*/
|
|
127
|
+
private leaseOnceOpen;
|
|
128
|
+
/** `client` may have just become idle: a deferred ending may run, and a waiter for idleness may go on. */
|
|
129
|
+
private becameIdle;
|
|
130
|
+
private takeLease;
|
|
131
|
+
/** One lease ended: the client may now be idle, and a deferred ending may run. */
|
|
132
|
+
releaseLease(client: PooledClient): void;
|
|
133
|
+
private notifyIdle;
|
|
134
|
+
/** An app lease: a hold on a client for as long as the app keeps it, at most `maxLeaseMs`. */
|
|
135
|
+
holdLease(client: PooledClient): HeldLease;
|
|
136
|
+
/** End an app lease — at most once, whether released or revoked. */
|
|
137
|
+
endLease(lease: HeldLease): void;
|
|
138
|
+
private revokeExpiredLeases;
|
|
139
|
+
/** Every app lease is revoked: the pool is closing. */
|
|
140
|
+
revokeAllLeases(): void;
|
|
141
|
+
/**
|
|
142
|
+
* Open a client for `key`: make room, resolve its plan, admit it to the open
|
|
143
|
+
* set, and start the one open. The operation that started it tracks the open's
|
|
144
|
+
* settlement, so its charge stays until the open's work has settled.
|
|
145
|
+
*/
|
|
146
|
+
private openFor;
|
|
147
|
+
/** The one open of `client`, under the pool's own signal and `initTimeoutMs`. */
|
|
148
|
+
private startOpen;
|
|
149
|
+
private dropFailedOpen;
|
|
150
|
+
/** Wait for `client`'s open inside `operation`: the caller's signal detaches the caller only. */
|
|
151
|
+
private waitOpen;
|
|
152
|
+
/** What `mcpClient` is opened with: the connection-shaping options, the pool's signal. */
|
|
153
|
+
private clientOptions;
|
|
154
|
+
/** What only a pool asks of the client it opens (`clientPort.ts`). */
|
|
155
|
+
private seamFor;
|
|
156
|
+
/**
|
|
157
|
+
* The guard for a message on `client` that carries none of its own: a tool
|
|
158
|
+
* call always brings its call's guard, so one without it is refused; any
|
|
159
|
+
* other request runs under the client's open, listing or ending — and with
|
|
160
|
+
* none under way, it is refused too. Nothing pooled is sent unchecked.
|
|
161
|
+
*/
|
|
162
|
+
private guardOf;
|
|
163
|
+
/** The guard of a request nothing covers: it refuses, so the request is never sent. */
|
|
164
|
+
private readonly unmatched;
|
|
165
|
+
/**
|
|
166
|
+
* The pool's own fetch, outermost on every pooled transport: a request is
|
|
167
|
+
* checked against its guard (the pooled call's, else the client's phase) and
|
|
168
|
+
* counted under it; the guard's signal is linked in; and the answer is read
|
|
169
|
+
* for the two pieces of evidence the pool classifies on — a 404 the MCP server
|
|
170
|
+
* itself sent to a request that carried its session id, and a handle this
|
|
171
|
+
* process lost. The client's own standalone stream (a GET), a notification and
|
|
172
|
+
* an answer to the server's own request are the client's, not an operation's:
|
|
173
|
+
* they pass untouched. Any other request with no guard is refused unsent.
|
|
174
|
+
*/
|
|
175
|
+
private pooledFetch;
|
|
176
|
+
/**
|
|
177
|
+
* Make room for a new client of `key`: the principal's least recently used
|
|
178
|
+
* idle client, then the pool's, moves to the ending set — or `PoolFullError`
|
|
179
|
+
* at once, naming the budget. There is no queue.
|
|
180
|
+
*/
|
|
181
|
+
private makeRoom;
|
|
182
|
+
/**
|
|
183
|
+
* Move `victim` to the ending set to make room. When the slots cannot be
|
|
184
|
+
* reserved, the arrival is refused at once, and the victim stays in the open
|
|
185
|
+
* set, counted, reported deferred — ended once slots free.
|
|
186
|
+
*/
|
|
187
|
+
private evict;
|
|
188
|
+
/** An ending slot and an operation slot, both, or which one is full. */
|
|
189
|
+
private reserveEnding;
|
|
190
|
+
/**
|
|
191
|
+
* End `client` for `reason` — when it is idle and both slots can be reserved.
|
|
192
|
+
* Otherwise it stays in the open set, still counted, and is reported deferred
|
|
193
|
+
* (once); it is ended when its last lease ends or slots free.
|
|
194
|
+
*/
|
|
195
|
+
endClient(client: PooledClient, reason: EndReason): void;
|
|
196
|
+
private defer;
|
|
197
|
+
/**
|
|
198
|
+
* Move `client` into the ending set under `operation`, and end it through
|
|
199
|
+
* `terminate()` — or, for a lost handle, through its local close alone.
|
|
200
|
+
*/
|
|
201
|
+
private startEnding;
|
|
202
|
+
private noteEnded;
|
|
203
|
+
/**
|
|
204
|
+
* A client whose handle this process lost: nothing can be sent for it, so it
|
|
205
|
+
* leaves its key at once — the next use opens the key's next client — and is
|
|
206
|
+
* ended under the ending rule like any other: its ending is its LOCAL close,
|
|
207
|
+
* charged an ending slot and an operation slot until that close settles, its
|
|
208
|
+
* remote outcome recorded unresolved. Busy, or with no slots free, it waits —
|
|
209
|
+
* still counted in the open set, reported deferred.
|
|
210
|
+
*/
|
|
211
|
+
lostHandle(client: PooledClient): void;
|
|
212
|
+
/** A client whose session the server ended: no new lease; ended (through `terminate()`) when idle. */
|
|
213
|
+
expired(client: PooledClient): void;
|
|
214
|
+
private sweepIdle;
|
|
215
|
+
/** Retry every deferred ending whose client is now idle. */
|
|
216
|
+
retryDeferred(): void;
|
|
217
|
+
/** Where `client`'s definitions are served from: its shared entry, or its own list. */
|
|
218
|
+
servedListOf(client: PooledClient): ServedList;
|
|
219
|
+
/**
|
|
220
|
+
* The definitions context `client` serves under NOW: the app's `share` asked
|
|
221
|
+
* again over the client's own configuration. A changed answer moves the
|
|
222
|
+
* client to the new context and stops serving its own list, so every tool
|
|
223
|
+
* bound under the old one is refused before it is sent.
|
|
224
|
+
*
|
|
225
|
+
* @throws `binding-changed`, `share`'s error as its cause, when the answer
|
|
226
|
+
* cannot be had — never the old context
|
|
227
|
+
*/
|
|
228
|
+
refreshContext(client: PooledClient): PooledClient['definitions'];
|
|
229
|
+
/** Does `context` still name the definitions context `client` serves under? False when it cannot be had. */
|
|
230
|
+
contextHolds(client: PooledClient, context: string): boolean;
|
|
231
|
+
/**
|
|
232
|
+
* The list `client` serves under NOW, listed again on it when it cannot be
|
|
233
|
+
* served as it stands — one listing at a time per list; a second caller joins
|
|
234
|
+
* it inside its own slot. Every attempt asks the app's names again
|
|
235
|
+
* (`refreshContext`), so a listing that a moved context discarded or refused
|
|
236
|
+
* at its send is listed once more under the context of now, never written
|
|
237
|
+
* into the one it began under. A listing raced by an invalidation is
|
|
238
|
+
* discarded too. Refused (`stale-tools`) when three attempts serve nothing.
|
|
239
|
+
* What it returns was checked against the context with no wait since.
|
|
240
|
+
*/
|
|
241
|
+
ensureListed(client: PooledClient, operation: Operation): Promise<ServedList>;
|
|
242
|
+
/**
|
|
243
|
+
* What `client` can serve under the context of now — asked of the app's names
|
|
244
|
+
* here — or, when nothing can, the list it should list. Too long to share:
|
|
245
|
+
* the conversation's own client keeps that list, under the same context.
|
|
246
|
+
*/
|
|
247
|
+
private servableNow;
|
|
248
|
+
/**
|
|
249
|
+
* One listing on `client` for `served`'s context. Its requests are sent only
|
|
250
|
+
* while that context holds — asked at every boundary they cross — and its
|
|
251
|
+
* answer is written only if the context still holds when it arrives and the
|
|
252
|
+
* list's generation held: an answer the app's names moved under belongs to
|
|
253
|
+
* no context, and is dropped.
|
|
254
|
+
*/
|
|
255
|
+
private startListing;
|
|
256
|
+
/**
|
|
257
|
+
* A request failed: when the pool's fetch read the server's own 404 for the
|
|
258
|
+
* session, or this process lost the handle, the client leaves its key — the
|
|
259
|
+
* next use opens the next client under the SAME key — and the error says so.
|
|
260
|
+
*/
|
|
261
|
+
classifyFailure(client: PooledClient, work: Work, error: unknown): RequestEvidenceOutcome;
|
|
262
|
+
/** The server said a client's tool list changed: that client's list and its shared entry. */
|
|
263
|
+
private toolsChangedOn;
|
|
264
|
+
/** The app's permission signal: every list in the scope. */
|
|
265
|
+
permissionsChanged(scope: {
|
|
266
|
+
readonly tenant?: string;
|
|
267
|
+
readonly principal?: string;
|
|
268
|
+
}): void;
|
|
269
|
+
/** The server changed: every list. */
|
|
270
|
+
toolsChanged(): void;
|
|
271
|
+
/**
|
|
272
|
+
* Stop new leases on every client `scope` names, at once; wait for their
|
|
273
|
+
* in-flight work up to `waitMs`; then end each one whose slots can be
|
|
274
|
+
* reserved. The rest are reported deferred and ended when they can be.
|
|
275
|
+
*/
|
|
276
|
+
terminate(matches: (key: PoolKey) => boolean, reason: EndReason, waitMs: number): Promise<readonly McpTerminateOutcome[]>;
|
|
277
|
+
/** End each of `clients` whose slots can be reserved; the outcomes of those that started. */
|
|
278
|
+
private endNow;
|
|
279
|
+
/** Wait until every client in `clients` is idle, or `waitMs` passed. */
|
|
280
|
+
private waitIdle;
|
|
281
|
+
/**
|
|
282
|
+
* Close: refuse new work, revoke app leases, abort in-flight work through the
|
|
283
|
+
* pool's own signal, then end every client as slots can be reserved — at most
|
|
284
|
+
* `maxEnding` at a time — in rounds, each bounded by `waitMs` (and each
|
|
285
|
+
* ending's answer by its own deadline). What could not be ended yet is
|
|
286
|
+
* reported deferred and ended when slots free; work still unsettled stays
|
|
287
|
+
* charged until it settles.
|
|
288
|
+
*/
|
|
289
|
+
closeAll(waitMs: number): Promise<readonly McpTerminateOutcome[]>;
|
|
290
|
+
/** Wait until an ending slot and an operation slot are free, or `waitMs` passed. */
|
|
291
|
+
private waitSlots;
|
|
292
|
+
/** Refuse new work, revoke app leases, abort in-flight work through the pool's signal. */
|
|
293
|
+
shutDown(): void;
|
|
294
|
+
/** Resolve once every charged operation and every ending has settled. */
|
|
295
|
+
settled(): Promise<void>;
|
|
296
|
+
private quiet;
|
|
297
|
+
private notifySettled;
|
|
298
|
+
stats(): McpPoolStats;
|
|
299
|
+
/** The bound shape of every definition in `served`, for a client of `key`. */
|
|
300
|
+
definitionsOf(served: ServedList): readonly Definition[];
|
|
301
|
+
/** The tools a list's client-own entries carry, by name (per-client lists only). */
|
|
302
|
+
ownTool(served: ServedList, name: string): Tool | undefined;
|
|
303
|
+
}
|
|
304
|
+
/** What a failed request proved about its client, if anything. */
|
|
305
|
+
export type RequestEvidenceOutcome = 'expired' | 'handle-lost' | undefined;
|
|
306
|
+
/** Re-exported for the bound tool: which end reasons name a previous client. */
|
|
307
|
+
export type { PreviousEnd };
|