@animalabs/agent-framework 0.33.0 → 0.34.0

package/dist/src/mcpl/modern-connection.d.ts

@@ -20,7 +20,8 @@ export declare class ModernMcpConnection extends EventEmitter {
     readonly id: string;
     readonly family: 'modern';
     readonly transportKind: 'stdio' | 'http';
-    /** The pinned revision, once a connect has established it; null before. */
+    /** The revision the last connect established (over HTTP, the one it
+     *  negotiated); null before any has. */
     protocolVersion: string | null;
     private session;
     /** A connect in flight, owned so `close()` can end it. */
@@ -32,6 +33,10 @@ export declare class ModernMcpConnection extends EventEmitter {
     private readonly reconnectMaxIntervalMs;
     private reconnectTimer;
     private reconnectAttempts;
+    private restarting;
+    private adoptedAt;
+    private youngRestartFree;
+    private stopped;
     /** At most one pending reopen, and only ever for the current generation. */
     private relisten;
     private relistenAttempts;
@@ -54,10 +59,15 @@ export declare class ModernMcpConnection extends EventEmitter {
     /** The per-call deadline: `requestTimeoutMs`, validated positive. */
     get requestTimeoutMs(): number;
     get isConnected(): boolean;
-    /** Whether a lost connection will be re-established in the background. */
+    /** Whether a lost connection will be re-established in the background:
+     *  with `reconnect` set, or while a new session starts in place of one the
+     *  server ended. */
     get willReconnect(): boolean;
     /**
-     * Stop reconnecting, closing nothing, as the legacy engine's does.
+     * Stop reconnecting, as the legacy engine's does, leaving the live session
+     * open. A session the server ends from then on isn't restarted either (see
+     * {@link sessionEnded}), and a reconnect or restart still connecting
+     * doesn't come up: its new session is closed.
      * @internal For the framework's stop(); not a host API.
      */
     stopReconnecting(): void;
@@ -119,10 +129,9 @@ export declare class ModernMcpConnection extends EventEmitter {
     /** Connect one generation's client, and adopt it if it's still current. */
     private establish;
     /**
-     * The server refused the pinned revision (no common one in its
-     * `server/discover` answer, or an unsupported-version error): a
-     * configuration verdict, as for the legacy engine, in the same type, so
-     * every reader treats both engines alike. Retrying can't change it.
+     * This client and the server couldn't negotiate a revision: a configuration
+     * verdict, as for the legacy engine, in the same type, so every reader
+     * treats both engines alike. Retrying can't change it.
      */
     private versionVerdict;
     /**
@@ -138,6 +147,76 @@ export declare class ModernMcpConnection extends EventEmitter {
     private cancelRelisten;
     private scheduleRelisten;
     private reopenSubscription;
+    /**
+     * The HTTP transport's fetch, observed for one session. It observes a
+     * 2025 connection's requests: those carrying a 2025 revision in
+     * `MCP-Protocol-Version`, which the SDK sends on each request after
+     * `initialize`, with a session id or without one (the id is optional). The
+     * handshake's own requests and a 2026-07-28 connection's pass through. The
+     * transport reports these HTTP outcomes only as errors, or not at all:
+     * - A 404 to a request that carried the session's id: the server has ended
+     *   the session. A POST's 404 is also that request's answer: the server
+     *   refused it without running it. That's marked on the leg's record (its
+     *   body's id names the leg) before anything else runs, since ending the
+     *   session closes its client, which can fail the call before the
+     *   transport's own 404 error reaches it.
+     * - The standalone stream's first open, the one GET without
+     *   `Last-Event-ID` before that stream has opened, is the exception. Its
+     *   404 can also mean the server has no GET route at all, which a server
+     *   that routes only POST answers, and reading it as the session's end
+     *   would make such a server unreachable. It ends nothing: the SDK reports
+     *   it as an error and opens no stream, as it does for any refusal of that
+     *   open but a 405, which it takes quietly, and a 401, which its credential
+     *   refresh tries once more. A session that really ended
+     *   meets the 404 on its next POST, such as the framework's relist after
+     *   the connect. The SDK never retries this open, so {@link firstOpen}
+     *   does, on a failure that may pass.
+     * - A 400 carrying the JSON-RPC error -32022 (unsupported protocol
+     *   version), to any request: the server no longer serves this revision,
+     *   as the SDK's 2026 handler answers a 2025 request when it refuses
+     *   legacy traffic (`legacy: 'reject'`). The connection negotiates again,
+     *   and settles on 2026-07-28 when the server offers it. A POST's refusal
+     *   is that request's answer, a JSON-RPC error, as the SDK reads such a 400
+     *   on 2026-07-28: marked on its record as a 404 is.
+     * - A 405 to a GET for one of the session's streams that the server had
+     *   served: the standalone stream opening again after it had opened, or a
+     *   request's stream resumed, which the server gave an event id. The server
+     *   no longer serves this session a stream, as the SDK's 2026 handler
+     *   answers a 2025 session it now serves statelessly, or refuses. The
+     *   connection negotiates again. A first open's 405 says only that the
+     *   server offers no stream, so it changes nothing. Each of these three,
+     *   the 404, the -32022 and the 405, marks the session ended at once
+     *   (`http.ended`), so it gets no DELETE: the server has let it go.
+     * - The standalone stream opening again, after it had opened, without
+     *   `Last-Event-ID`: it couldn't ask for what it missed, whether because
+     *   the server's events carry no ids or because the stream that dropped
+     *   had carried none (the SDK keeps a stream's last id only for that
+     *   stream). See {@link streamReopened}. A GET that carries one resumes a
+     *   stream, the standalone one or a request's, and the server replays
+     *   what that stream missed.
+     * - A standalone resume the server refuses with 400, as one does for an
+     *   event id it no longer holds: retrying the same id can't succeed, and
+     *   the SDK would retry it for the session's life. The stream opens again
+     *   without the id instead, which is a reopen that missed what came between.
+     *   A request stream's resume refused that way is left to the SDK: it is
+     *   retried until its request's answer arrives on it, or its deadline
+     *   cancels it (see ObservedTransport's `aborts`).
+     */
+    private observedFetch;
+    /** The SDK makes the standalone stream's first open once, and never
+     *  retries it. */
+    private firstOpen;
+    /**
+     * The HTTP transport's scheduler for trying a stream again, for both
+     * streams it retries: the standalone stream and a request's stream the
+     * server closed after a priming event (2025-11-25). The server's `retry`
+     * hint is respected, as the spec requires. `hinted` is the server's hint
+     * alone, or 0, since the transport's own backoff is zeroed.
+     */
+    private readonly streamRetry;
+    /** The spec has a client whose session met a 404 start a new one. */
+    private sessionEnded;
+    private streamReopened;
     /** The transport went away (child exit, or a closed HTTP client). */
     private handleLost;
     /** The legacy engine's backoff: doubling from the base interval, capped,
@@ -158,7 +237,8 @@ export declare class ModernMcpConnection extends EventEmitter {
      * Call a tool within the configured deadline. One budget covers the whole
      * logical call: the SDK's per-leg timer and its `maxTotalTimeout` across
      * continuation rounds, and an abort signal around any retry the SDK makes
-     * before dispatch (an auth refresh, or a header-mismatch relist).
+     * before dispatch (an auth refresh, or a header-mismatch relist). That
+     * signal also fires when the call's stream is lost (WireRecord's `cancel`).
      */
     callTool(name: string, args: Record<string, unknown>): Promise<ModernToolCallResult>;
     /** Run one logical request in a wire scope, and classify its failure by
@@ -173,6 +253,16 @@ export declare class ModernMcpConnection extends EventEmitter {
      * framework's unguarded wait on it rely on.
      */
     private static closeSession;
+    /**
+     * End an HTTP session on the server (a DELETE), as the spec asks of a
+     * client that no longer needs it. It runs before the inner transport
+     * closes, since that close would abort it. When a connect fails after its
+     * `initialize` was answered, the SDK closes the transport itself before
+     * the error reaches `establish`. The transport sends nothing for a session
+     * without an id, and the SDK reports a DELETE's failure through the
+     * transport's onerror.
+     */
+    private static endSession;
     /** The close in flight, which later calls wait behind. */
     private closing;
     /** Set when the host closes a live session; cleared, with the one
@@ -215,13 +305,17 @@ export declare class ModernMcpConnection extends EventEmitter {
      *   rounds cap). Nothing is in flight then, so nothing is cancelled. A
      *   result of a type this client doesn't recognize ends the call where it
      *   is;
-     * - an HTTP 401/403 refusal of the current leg: `error-response`, the
-     *   status in `data.httpStatus` (the server answered at the HTTP layer,
-     *   outside the JSON-RPC code space). After an earlier leg
-     *   asked for another round it is `no-response` instead: the server may
-     *   already have acted on the call;
-     * - handed off and unanswered: `no-response`. At the deadline, cancellation
-     *   was requested and the outcome is unknown.
+     * - an HTTP refusal of the current leg: `error-response`, the status in
+     *   `data.httpStatus` (the server answered at the HTTP layer, outside the
+     *   JSON-RPC code space). That's a 401 or 403, or a 404 to a POST from a
+     *   server that had ended the session (`sessionEnded`, read at the HTTP
+     *   layer, whatever error the call then met as its session closed). After
+     *   an earlier leg asked for another round it is `no-response` instead:
+     *   the server may already have acted on the call;
+     * - handed off and unanswered: `no-response`, and the outcome is unknown.
+     *   At the deadline, cancellation was requested, and so it was when the
+     *   stream that would carry the answer ended unresumed (WireRecord's
+     *   `cancel`).
      *
      * The message is the agent's, in the legacy engine's words where it has
      * words for the same outcome (#506), and in their shape where it hasn't:

package/dist/src/mcpl/modern-connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modern-connection.d.ts","sourceRoot":"","sources":["../../../src/mcpl/modern-connection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"modern-connection.d.ts","sourceRoot":"","sources":["../../../src/mcpl/modern-connection.ts"],"names":[],"mappings":"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"}