@reclaimprotocol/agent 0.1.34 → 0.1.36

package/lib/mcp/start.js

@@ -11,7 +11,7 @@ import { ReclaimSdkClient } from "../old/sdk-client.js";
 import { buildOldBackendTools } from "../old/tools/build.js";
 import { NAME, VERSION } from "../pkg.js";
 import { registerTools } from "./api/tools.js";
-import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, disposeAgentState, readSession, } from "./tools/index.js";
+import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, disposeAgentState, readSession, releaseAllListeners, stopAllForwarders, } from "./tools/index.js";
 import { BUILDER_MODE_INSTRUCTIONS } from "./instructions.js";
 import { registerToolList } from "./server.js";
 export async function startMcpServer() {
@@ -94,7 +94,7 @@ export async function startMcpServer() {
     // the session can end without a single tool call: the developer closes their
     // agent, the client kills the server, stdin drops. Nothing ran here before,
     // which left a container up after the session that made it was gone.
-    if (agentToolsEnabled) {
+    if (agentToolsEnabled || !oldMode) {
         installShutdownHooks(() => agentState);
     }
     const transport = new StdioServerTransport();
@@ -117,10 +117,7 @@ function installShutdownHooks(state) {
         }
         shuttingDown = true;
         const current = state();
-        if (!current) {
-            process.exit(0);
-        }
-        LOGGER.info({ reason }, 'releasing the browser before exit');
+        LOGGER.info({ reason }, 'releasing resources before exit');
         // Bounded: a wedged `docker stop` must not keep the process alive, but
         // nor should we skip cleanup that would have finished in a second.
         const timer = setTimeout(() => {
@@ -128,7 +125,11 @@ function installShutdownHooks(state) {
             process.exit(0);
         }, SHUTDOWN_GRACE_MS);
         timer.unref();
-        void disposeAgentState(current)
+        void Promise.all([
+            stopAllForwarders(),
+            releaseAllListeners(),
+            current && disposeAgentState(current),
+        ])
             .catch((err) => {
             LOGGER.warn({ err }, 'teardown failed');
         })

package/lib/mcp/tools/agent/build.js

@@ -14,6 +14,7 @@ import { ensureAttestorCrypto } from "../../../proof/proof-core.js";
 import { analyzeTool } from "./analyze.js";
 import { attachTool } from "./attach.js";
 import { captureTools, resetCaptures } from "./capture.js";
+import { checkAttestorTool } from "./check-attestor.js";
 import { listTabsTool } from "./eval.js";
 import { howItWorksTool } from "./how-it-works.js";
 import { liveViewTools } from "./live-view.js";
@@ -65,6 +66,7 @@ export function buildAgentTools(client, builderClient = client, externalState) {
         tools.push(t);
     }
     tools.push(analyzeTool(state.captures));
+    tools.push(checkAttestorTool());
     // navigate / eval_in_page / wait_for_page / get_cookies / list_requests /
     // find_requests_containing / propose_provider / replay_request / run_proof —
     // shared with the cloud loop, bound to each capture's local backend.

package/lib/mcp/tools/agent/check-attestor.d.ts

@@ -0,0 +1,5 @@
+import { checkAttestor, type CheckAttestorOptions } from '../../../proof/check-attestor.ts';
+import { type RegisteredTool } from '../../server.ts';
+/** `check_attestor`: proves a public request to show whether the attestor
+ *  works from this machine. `check` is injectable so tests need no network. */
+export declare function checkAttestorTool(check?: (opts: CheckAttestorOptions) => ReturnType<typeof checkAttestor>): RegisteredTool;

package/lib/mcp/tools/agent/check-attestor.js

@@ -0,0 +1,37 @@
+import { checkAttestor, } from "../../../proof/check-attestor.js";
+import { defineTool } from "../../server.js";
+/** `check_attestor`: proves a public request to show whether the attestor
+ *  works from this machine. `check` is injectable so tests need no network. */
+export function checkAttestorTool(check = checkAttestor) {
+    return defineTool({
+        name: 'check_attestor',
+        description: 'Checks that the Reclaim attestor works from this machine by proving '
+            + 'a public CoinGecko price request with a throwaway key. It uses no '
+            + 'credential, provider, or logged-in site, and takes up to 45 '
+            + 'seconds (about 8 when healthy). Call it once when you set up a '
+            + 'new provider build, and after `run_proof` fails with a network '
+            + 'error. Returns `{ ok, attestorUrl, durationMs, '
+            + 'extractedParameters, error, errorKind }`. If `ok` is true, the '
+            + 'attestor is fine and a failing proof points to the target site. '
+            + 'If `errorKind` is `attestor-unreachable`, this machine cannot '
+            + 'reach the attestor (network, VPN, firewall, or proxy): tell the '
+            + 'developer. If it is `setup-failed`, the ZK file download failed '
+            + 'before the attestor was contacted: tell the developer to check '
+            + 'network access to the circuit download. If it is '
+            + '`attestor-error`, the attestor rejected the claim: report '
+            + '`error`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                attestorUrl: {
+                    type: 'string',
+                    description: 'Attestor websocket URL. Set it only if the developer '
+                        + 'supplied one; the default is the public attestor.',
+                },
+            },
+        },
+        annotations: { openWorldHint: true, readOnlyHint: true },
+    }, async ({ attestorUrl }) => {
+        return check(attestorUrl ? { attestorUrl } : {});
+    });
+}

package/lib/mcp/tools/agent/live-view.js

@@ -3,9 +3,10 @@
  * attached container browser's built-in viewer behind a public URL, so someone
  * who is not at this machine can watch it and optionally drive it.
  *
- * The server never runs, downloads or resolves cloudflared: the agent runs it
- * itself and passes the resulting `trycloudflare.com` URL back to get the link
- * to hand out.
+ * The server never runs, downloads or resolves cloudflared. The developer
+ * chooses who runs it: they run it themselves (recommended) or approve the
+ * agent running it. Either way the `trycloudflare.com` URL it prints comes
+ * back as `publicUrl` to get the link to hand out.
  *
  * Scoped to `container` mode on purpose. A `builder`-mode browser already has
  * a hosted live view at `attach_browser`'s `liveViewUrl`.
@@ -24,9 +25,13 @@ export function liveViewTools(attachRef) {
             description: 'Returns a link that lets someone who is not at this machine watch '
                 + 'and drive the attached `container` browser, for example to sign '
                 + 'in. This server opens no tunnel itself. Step 1: call with no '
-                + 'arguments to get the local viewer URL and the `cloudflared` '
-                + 'command for the developer to run. Step 2: after cloudflared '
-                + 'prints its `https://*.trycloudflare.com` URL, call again with it '
+                + 'arguments. It returns the local viewer URL, the `cloudflared` '
+                + 'command, and two `choices`. Ask the developer to pick one before '
+                + 'any tunnel runs: (a, recommended) they run `! cloudflared tunnel '
+                + '--url http://localhost:<port>` themselves and paste the printed '
+                + '`https://*.trycloudflare.com` URL; (b) they explicitly approve '
+                + 'you running the command in the background. Never install '
+                + '`cloudflared` without approval. Step 2: call again with the URL '
                 + 'as `publicUrl` to get the link to relay. The link grants access '
                 + 'to that browser session only, so share it only with the person '
                 + 'who needs it. For `builder`, use the `liveViewUrl` from '
@@ -75,27 +80,46 @@ export function liveViewTools(attachRef) {
                             + 'separate window is visible too.',
                         'Opening it on a phone lays the page out for that phone, with '
                             + 'touch, pinch-zoom and the soft keyboard.',
-                        'When they are done, stop the cloudflared process you started. '
-                            + 'The browser keeps running until `dispose_browser`.',
+                        'When they are done, stop the cloudflared process: yourself if '
+                            + 'you started it, otherwise ask the developer. The browser '
+                            + 'keeps running until `dispose_browser`.',
                     ],
                 };
             }
             const localUrl = `http://localhost:${viewerPort}`;
+            const command = `cloudflared tunnel --url ${localUrl}`;
             return {
                 localViewerUrl: ensureLiveViewUrl(localUrl),
                 port: viewerPort,
-                command: `cloudflared tunnel --url ${localUrl}`,
+                command,
+                choices: [
+                    {
+                        id: 'developer-runs',
+                        recommended: true,
+                        action: `Run \`! ${command}\` in the prompt, then paste the `
+                            + 'https://*.trycloudflare.com URL it prints.',
+                    },
+                    {
+                        id: 'agent-runs',
+                        recommended: false,
+                        action: 'Approve the agent to run the command in the '
+                            + 'background and read the URL from its output.',
+                    },
+                ],
                 _notes: [
-                    'Run `command` yourself in a background process. If `cloudflared` '
-                        + 'is not installed, tell the developer and ask them to install '
-                        + 'it (https://developers.cloudflare.com/cloudflare-one/'
-                        + 'connections/connect-networks/downloads/) — do not install it '
+                    'Ask the developer to choose before any tunnel runs. Do not run '
+                        + '`command` until they pick `agent-runs`.',
+                    'If they pick `developer-runs`, wait for the pasted URL. If they '
+                        + 'pick `agent-runs`, run `command` in a background process and '
+                        + 'read its output for a line containing '
+                        + '`https://<words>.trycloudflare.com`.',
+                    'If `cloudflared` is not installed, tell the developer and ask '
+                        + 'them to install it '
+                        + '(https://developers.cloudflare.com/cloudflare-one/'
+                        + 'connections/connect-networks/downloads/). Never install it '
                         + 'without their approval.',
-                    'Read its output for a line containing '
-                        + '`https://<words>.trycloudflare.com`. That is the public URL.',
-                    'Call share_browser_view again with that value as `publicUrl` '
-                        + 'to get the link to relay. Never guess or reconstruct the '
-                        + 'hostname.',
+                    'Call share_browser_view again with the URL as `publicUrl` to get '
+                        + 'the link to relay. Never guess or reconstruct the hostname.',
                     'Expose only this port. Never tunnel the browser\'s CDP port.',
                 ],
             };

package/lib/mcp/tools/agent/proof.d.ts

@@ -1,4 +1,5 @@
 import { type ProofResult } from '../../../proof/attestor.ts';
+import { type AttestorCheckResult, type CheckAttestorOptions } from '../../../proof/check-attestor.ts';
 /**
  * The MCP's rich `run_proof` view: persist the full claim to disk, return
  * identifier + extractedParameters + a prettified claim (request dropped, byte
@@ -11,3 +12,14 @@ export declare function shapeRichProofResult(result: ProofResult, opts: {
     hasSecrets: boolean;
     attestorUrl?: string;
 }): Record<string, unknown>;
+export interface ProofDiagnosis {
+    attestor: AttestorCheckResult;
+    likelyCause: string;
+    next: string;
+}
+/**
+ * When an unverified proof failed with a network-like error, runs the
+ * attestor check once and says whether the attestor or the target site is the
+ * likely cause. Returns `undefined` for verified proofs and other errors.
+ */
+export declare function diagnoseNetworkFailure(result: Pick<ProofResult, 'verified' | 'error' | 'errorKind'>, check: (opts: CheckAttestorOptions) => Promise<AttestorCheckResult>, attestorUrl?: string): Promise<ProofDiagnosis | undefined>;

package/lib/mcp/tools/agent/proof.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { agentTraceEnabled } from "../../../consts.js";
 import { reclaimHomeDirPath } from "../../../paths.js";
 import { tailLogs, warnsAndErrors, } from "../../../proof/attestor.js";
+import { isNetworkError, } from "../../../proof/check-attestor.js";
 function claimsDir() {
     return join(reclaimHomeDirPath(), 'claims');
 }
@@ -157,3 +158,34 @@ export function shapeRichProofResult(result, opts) {
     }
     return out;
 }
+/**
+ * When an unverified proof failed with a network-like error, runs the
+ * attestor check once and says whether the attestor or the target site is the
+ * likely cause. Returns `undefined` for verified proofs and other errors.
+ */
+export async function diagnoseNetworkFailure(result, check, attestorUrl) {
+    if (result.verified
+        || result.errorKind !== undefined
+        || !isNetworkError(result.error)) {
+        return undefined;
+    }
+    const attestor = await check(attestorUrl ? { attestorUrl } : {});
+    if (attestor.ok) {
+        return {
+            attestor,
+            likelyCause: 'The attestor works from this machine, so the target site likely '
+                + 'blocks or drops the attestor\'s network (geo or IP restriction).',
+            next: 'If the browser attach mode is "builder", call `run_proof_via_pod`. '
+                + 'Otherwise tell the developer and suggest asking the Reclaim team. '
+                + 'Do not retry the same proof.',
+        };
+    }
+    return {
+        attestor,
+        likelyCause: 'The attestor check also failed, so this machine cannot reach the '
+            + 'attestor (network, VPN, firewall, or proxy).',
+        next: 'Tell the developer. To see the connection details, suggest '
+            + 'restarting the MCP server with `RECLAIM_AGENT_TRACE=1`. Do not '
+            + 'retry the same proof.',
+    };
+}

package/lib/mcp/tools/agent/shared.d.ts

@@ -1,3 +1,4 @@
+import { checkAttestor } from '../../../proof/check-attestor.ts';
 import type { RegisteredTool } from '../../server.ts';
 import type { CaptureStore } from './capture.ts';
 /** The shared authoring tools mapped to the MCP's shape: resolve each call's
@@ -5,4 +6,4 @@ import type { CaptureStore } from './capture.ts';
  *  takes `captureId`; `run_proof` also gets the credential-aware contract. The
  *  tools are authored plain in `../../../authoring`; this only wraps them with
  *  `extendTool` (handlers untouched — loose arg parse keeps `captureId`). */
-export declare function sharedAuthoringTools(captures: CaptureStore): RegisteredTool[];
+export declare function sharedAuthoringTools(captures: CaptureStore, check?: typeof checkAttestor): RegisteredTool[];

package/lib/mcp/tools/agent/shared.js

@@ -1,7 +1,8 @@
 import { authoringTools, extendTool, } from "../../../authoring/index.js";
 import { runAttestorProof } from "../../../proof/attestor.js";
+import { checkAttestor } from "../../../proof/check-attestor.js";
 import { replayProviderInPage } from "../../../proof/page-replay.js";
-import { shapeRichProofResult } from "./proof.js";
+import { diagnoseNetworkFailure, shapeRichProofResult } from "./proof.js";
 /**
  * OPRF mode this LOCAL (non-TEE) attestor can actually run. Recipes carry
  * `oprf-mpc` — the canonical/publish mode a TEE expects — but the local dev
@@ -32,7 +33,7 @@ function withLocalOprfMode(provider) {
 /** The local backend for one capture: drive its tab over CDP, read its
  *  captured requests, prove via the in-process attestor, replay by re-fetching
  *  FROM INSIDE the tab (real cookies/session — see proof/page-replay.ts). */
-function localBackend(entry, kept) {
+function localBackend(entry, kept, check) {
     const { tabClient, session, drafts } = entry;
     const sendCdp = (method, params) => {
         return tabClient.send(method, params ?? {});
@@ -76,11 +77,13 @@ function localBackend(entry, kept) {
                 ...(opts?.ownerAddress ? { ownerAddress: opts.ownerAddress } : {}),
                 ...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
             });
-            return shapeRichProofResult(result, {
+            const shaped = shapeRichProofResult(result, {
                 provider: draft.provider,
                 hasSecrets: Object.keys(draft.secrets).length > 0,
                 ...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
             });
+            const diagnosis = await diagnoseNetworkFailure(result, check, opts?.attestorUrl);
+            return diagnosis ? { ...shaped, diagnosis } : shaped;
         },
     };
 }
@@ -88,25 +91,26 @@ function localBackend(entry, kept) {
  *  tool by the host below (the cloud's TEE signs in-enclave, so it needs none
  *  of this). */
 const RUN_PROOF_EXTRAS = {
-    description: 'Run a full zkTLS proof of the drafted recipe through the Reclaim '
-        + 'attestor SDK. Use only after replay_request looks right — attestor '
-        + 'calls are expensive. Writes the full claim to '
-        + '~/.reclaim/claims/<timestamp>.json and returns identifier + '
-        + 'extractedParameters + claimPath + a prettified `claim` (request '
-        + 'dropped, byte arrays as base64). With RECLAIM_AGENT_TRACE=1, also '
-        + 'writes a per-call diagnostic dump (input provider, sentParams, full '
-        + 'attestor log stream, result) and returns it as `runLogPath`. '
-        + '`attestorUrl` overrides the default only when the dev supplies a '
-        + 'specific alternative — do NOT invent backup URLs. `ownerAddress` '
-        + '(the credential to sign with) is REQUIRED — call resolve_owner_key '
-        + 'first. errorKind="missing-owner-key" means that address has no known '
-        + 'private key; re-run resolve_owner_key or issue/import a credential. '
-        + 'NOTE: unlike replay_request (which re-issues from inside the live '
-        + 'attached browser tab), the ATTESTOR calls the target from its OWN '
-        + 'network/IP, separate from the browser\'s. A request that replayed '
-        + 'fine can still fail here for geo/IP-bound content (country-locked '
-        + "pages, IP-allowlisted APIs) — if that happens, it's a property of "
-        + 'the site, not a bug in the draft.',
+    description: 'Proves the drafted recipe with a full zkTLS proof through the attestor '
+        + 'SDK. Call it after `replay_request` looks right; attestor calls are '
+        + 'expensive. Call `resolve_owner_key` first and pass its address as '
+        + '`ownerAddress`. Writes the full claim to '
+        + '`~/.reclaim/claims/<timestamp>.json`. Returns `identifier`, '
+        + '`extractedParameters`, `claimPath`, and a readable `claim` (request '
+        + 'removed, byte arrays as base64). Set `RECLAIM_AGENT_TRACE=1` to also '
+        + 'get `runLogPath`, a diagnostic dump with the attestor log stream. '
+        + 'Set `attestorUrl` only if the developer supplied one; never invent '
+        + 'backup URLs. If `errorKind` is `missing-owner-key`, the address has '
+        + 'no known private key: run `resolve_owner_key` again, or issue or '
+        + 'import a credential. Unlike `replay_request`, which re-sends from '
+        + 'inside the attached browser tab, the attestor calls the target from '
+        + 'its own network and IP. A request that replayed can still fail here '
+        + 'for geo- or IP-bound content, such as country-locked pages or '
+        + 'IP-allowlisted APIs. That is a property of the site, not a draft '
+        + 'bug. After a network-like failure ("connection closed", '
+        + '`ERROR_NETWORK_ERROR`, timeout), the result includes `diagnosis` '
+        + 'with `attestor` (a `check_attestor` result), `likelyCause`, and '
+        + '`next`. Follow `next`; do not retry the same proof.',
     properties: {
         ownerAddress: {
             type: 'string',
@@ -124,7 +128,7 @@ const RUN_PROOF_EXTRAS = {
  *  takes `captureId`; `run_proof` also gets the credential-aware contract. The
  *  tools are authored plain in `../../../authoring`; this only wraps them with
  *  `extendTool` (handlers untouched — loose arg parse keeps `captureId`). */
-export function sharedAuthoringTools(captures) {
+export function sharedAuthoringTools(captures, check = checkAttestor) {
     const resolveBackend = (args) => {
         const captureId = String(args.captureId);
         const entry = captures.sessions.get(captureId);
@@ -132,7 +136,7 @@ export function sharedAuthoringTools(captures) {
             throw new Error(`no capture ${captureId} — call start_capture first `
                 + '(it has been reset or never started).');
         }
-        return localBackend(entry, captures);
+        return localBackend(entry, captures, check);
     };
     return authoringTools(resolveBackend).map((tool) => {
         if (tool.definition.name === 'run_proof') {

package/lib/mcp/tools/agent/start-integration.js

@@ -10,10 +10,11 @@ export function startIntegrationTool() {
     return defineTool({
         name: 'start_integration',
         description: 'Returns a step-by-step plan for adding Reclaim verification to the '
-            + 'current codebase: sign in, build or choose a provider, then add the '
-            + 'session route, callback, and Verify button. Call it first when a '
-            + 'developer wants their users to prove something, and follow the '
-            + 'plan to the end. Changes nothing itself.',
+            + 'current codebase: sign in, set up the app (session route, callback, '
+            + 'Verify button, local event proxy) in parallel with building or '
+            + 'choosing the provider, then wire the provider and test. Call it '
+            + 'first when a developer wants their users to prove something, and '
+            + 'follow the plan to the end. Changes nothing itself.',
         inputSchema: {
             type: 'object',
             required: ['goal'],

package/lib/mcp/tools/verification/build.d.ts

@@ -4,7 +4,9 @@ import type { RegisteredTool } from '../../server.ts';
  * generated API surface. `get_verification_result` authenticates with the org
  * token, checks status, pulls the stored payload, and decrypts it locally with
  * the optional eth key — a flow the generated raw-API tools can't express
- * (the decryption key never leaves the consumer). Diagnosis is left to the
+ * (the decryption key never leaves the consumer). `read_callback_events` and
+ * `proxy_callback_events` read and forward the org's pull-listener events.
+ * Diagnosis is left to the
  * agent over the generated tools (`get_verification_session`,
  * `list_verification_events`, `list_verification_deliveries`), whose
  * descriptions carry the lifecycle and delivery semantics.

package/lib/mcp/tools/verification/build.js

@@ -1,14 +1,22 @@
+import { proxyCallbackEventsTool } from "./proxy-callback-events.js";
+import { readCallbackEventsTool } from "./read-callback-events.js";
 import { verificationResultTool } from "./result.js";
 /**
  * Builder-mode verification tools: higher-level orchestrations over the
  * generated API surface. `get_verification_result` authenticates with the org
  * token, checks status, pulls the stored payload, and decrypts it locally with
  * the optional eth key — a flow the generated raw-API tools can't express
- * (the decryption key never leaves the consumer). Diagnosis is left to the
+ * (the decryption key never leaves the consumer). `read_callback_events` and
+ * `proxy_callback_events` read and forward the org's pull-listener events.
+ * Diagnosis is left to the
  * agent over the generated tools (`get_verification_session`,
  * `list_verification_events`, `list_verification_deliveries`), whose
  * descriptions carry the lifecycle and delivery semantics.
  */
 export function buildVerificationTools() {
-    return [verificationResultTool()];
+    return [
+        verificationResultTool(),
+        readCallbackEventsTool(),
+        proxyCallbackEventsTool(),
+    ];
 }

package/lib/mcp/tools/verification/callback-listener.d.ts

@@ -0,0 +1,51 @@
+import { ReclaimClient } from '@reclaimprotocol/client/api';
+import type { IOperationResponse } from '@reclaimprotocol/client/openapi';
+/** Runtime seams. Production passes none; tests pass a stub `fetch`. */
+export interface CallbackDeps {
+    fetch?: typeof globalThis.fetch;
+    /** Waits between heartbeats and polls. Resolves, without error, on abort. */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    keeper?: ListenerKeeper;
+}
+/**
+ * Events the org's pull listener subscribes to: the five session-ending
+ * events (the first four carry the signed result; `session_expired` has no
+ * result) plus the lifecycle milestones an app developer checks while testing.
+ * High-volume diagnostics (`network_request_observed`, `provider_script_log`,
+ * `user_interaction_*`) are left out, so a forwarded session sends the app at
+ * most 11 requests instead of dozens.
+ */
+export declare const LISTENER_EVENTS: readonly ["verification_success", "verification_rejected", "verification_error", "verification_cancelled", "session_expired", "session_pending", "verification_client_opened", "authenticated", "verification_proofs_completed", "verification_result_submitting", "verification_result_submission_failed"];
+export type ListenerInfo = {
+    subscriptionId: string;
+    created: boolean;
+    /** When the lease lapses unless the heartbeat renews it. */
+    expiresAt: string;
+};
+export type CallbackEvent = IOperationResponse<'ListCallbackEvents'>['items'][number];
+/**
+ * A client that presents the organization's API key. With a `signal`, every
+ * request aborts when it does.
+ */
+export declare function orgClient(secret: string, deps?: CallbackDeps, signal?: AbortSignal): ReclaimClient;
+/**
+ * Keeps each org's pull listener alive while this MCP process runs. Creating
+ * the subscription is the heartbeat: it renews a lease, and the listener
+ * stops receiving events when the lease lapses. {@link release} ends the
+ * lease at shutdown.
+ */
+export declare class ListenerKeeper {
+    #private;
+    /** Creates or renews the listener and starts its heartbeat (once). */
+    ensure(secret: string, deps?: CallbackDeps): Promise<ListenerInfo>;
+    /** Ends every lease and stops the heartbeats, within a short timeout. */
+    release(): Promise<void>;
+}
+/** Releases every listener this process keeps alive. Runs at MCP shutdown. */
+export declare function releaseAllListeners(): Promise<void>;
+/**
+ * Create the org's pull listener and keep it alive until shutdown. An org has
+ * one, so a second call returns the existing subscription (HTTP 200).
+ */
+export declare function ensureListener(secret: string, deps?: CallbackDeps): Promise<ListenerInfo>;
+export declare function sleepFor(ms: number, signal: AbortSignal): Promise<void>;