@zackbart/connecta 0.24.3 → 0.25.0

package/dist/routes/operator.js

@@ -0,0 +1,82 @@
+// The Effect plumbing the operator and activity data routes share.
+//
+// Each JSON route under /ui/* is one Effect program, run at its Promise edge
+// by serveOperator. A route that settles its answer early — a refusal, or an
+// auth provider's own challenge — fails with an Answer carrying that exact
+// Response, and the edge serves it. That is the whole error model: every
+// status, body, and header is still built by privateJson or by the provider,
+// so the wire format cannot drift from what these routes have always sent.
+// Anything else that goes wrong is a defect and rejects the edge, as a throw
+// from the async handlers did.
+//
+// Effect's HttpApi was measured for this and not used (P1-S18). Declaring
+// these seven endpoints added about 101 KB gzip to ./ui and 131 KB to
+// ./activity, most of it Schema, and matching the wire format would have
+// meant opting out of nearly everything it does: unowned paths fall through
+// to the next module rather than 404, a wrong method is a JSON 405, the
+// Content-Type and size checks run before a body is read, and a credential
+// field error names the field in words the page already shows. Plain routing
+// over one error channel keeps the behavior and costs nothing, because ./ui
+// already carries Effect through its deadlines.
+//
+// Imported by the /ui and /activity graphs only; never from the root entry.
+import { Effect } from "effect";
+import { runEdge } from "../runtime/run.js";
+import { authorize, authorizeUiIdentity, msg, privateJson, validateAuthPermissions, } from "./shared.js";
+/** A response the route has already decided on. */
+export class Answer {
+    response;
+    _tag = "Answer";
+    constructor(response) {
+        this.response = response;
+    }
+}
+/** End the route with a private JSON error, as every route here does. */
+export function refuse(error, status) {
+    return Effect.fail(new Answer(privateJson({ error }, { status })));
+}
+function admitted(result) {
+    return Effect.flatMap(Effect.promise(() => result), (authz) => authz.ok ? Effect.succeed(authz) : Effect.fail(new Answer(authz.response)));
+}
+/** Any configured caller. The gate's refusal, challenge headers and all, is the answer. */
+export function authorized({ request, baseUrl, opts, runtimeContext }, partitionIdentity = true) {
+    return Effect.suspend(() => admitted(authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity, partitionIdentity)));
+}
+/** A signed-in person, for a route that changes how a connector authenticates. */
+export function authorizedPerson({ request, baseUrl, opts, runtimeContext }, purpose) {
+    return Effect.suspend(() => admitted(authorizeUiIdentity(request, baseUrl, opts.auth, purpose, runtimeContext, opts.identity)));
+}
+/** The partition and tool grants an identity carries into a registry view. */
+export function scopeFor(authz, connectorIds = authz.connectorIds) {
+    return {
+        connectorIds,
+        ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}),
+        ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
+        ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
+    };
+}
+/**
+ * The registry as this identity may see it. A configured permission naming a
+ * connector that does not exist refuses the whole view, management rights
+ * included, rather than quietly granting what remains.
+ */
+export function visibleRegistry({ opts }, authz) {
+    return Effect.try({
+        try: () => {
+            validateAuthPermissions(authz, opts.registry);
+            return opts.registry.scoped(scopeFor(authz));
+        },
+        catch: (error) => new Answer(privateJson({ error: msg(error) }, { status: 403 })),
+    });
+}
+/**
+ * Run one route program to its Response.
+ *
+ * A read passes the request's signal, so a caller who leaves stops whatever
+ * the read was waiting on. A mutation passes none: once a vault write or an
+ * OAuth disconnect has started, the cache invalidation that follows it must
+ * run too, whether or not anyone is still waiting for the answer.
+ */
+export function serveOperator(program, signal) {
+    return runEdge(Effect.catch(program, (answer) => Effect.succeed(answer.response)), signal ? { signal } : undefined);
+}

package/dist/routes/shared.d.ts

@@ -37,6 +37,8 @@ export interface ServerOptions {
     maxHostCalls?: number | undefined;
     /** Deadline per execute_code host call. Default 15_000. */
     hostCallTimeoutMs?: number | undefined;
+    /** Hard ceiling on one execute_code run, outside the sandbox. Default 120_000. */
+    watchdogMs?: number | undefined;
     /** Required sandbox backing the execute_code meta-tool. */
     executor: Executor;
     /** Sanitized identity of the configured sandbox, when it has one. */

package/dist/routes/ui-data.js

@@ -0,0 +1,210 @@
+// The Effect core of the operator payload: `buildUiData` in src/ui.ts is its
+// Promise face, and the `/ui/connectors/<id>` route yields it directly.
+//
+// Every visible connector is one slot of a bounded fan-out: its probe runs
+// under a deadline, any failure becomes that connector's error row rather
+// than the payload's, and its connector scope closes as the slot ends,
+// however it ends.
+import { Effect } from "effect";
+import { resolveDiscoveryConcurrency } from "../concurrency.js";
+import { credentialTestRule, describeUndeclaredCredentialFields, storedCredentialShape, } from "../credential-rules.js";
+import { closeScope } from "../runtime/connector-scope.js";
+import { withDeadlineEffect } from "../runtime/run.js";
+import { uiProblemFor, uiToolSafety } from "../ui.js";
+import { CONNECTA_VERSION } from "../version.js";
+const DETAIL_TIMEOUT_MS = 30_000;
+const DETAIL_TIMED_OUT = "Connection details timed out. Retry this connection.";
+function attempt(operation) {
+    return Effect.tryPromise({ try: operation, catch: (error) => error });
+}
+export function uiData(registry, baseUrl, options) {
+    return Effect.suspend(() => {
+        const requestScope = {};
+        const vault = options.credentialVault;
+        const owner = options.personalCredentialOwner;
+        /**
+         * A connector's status message stops here. It can quote a downstream error
+         * body — and a downstream error body can quote the secret it just rejected —
+         * so the payload carries only the classified `problem` and the raw text goes
+         * to the deployment's log, where an operator debugging the failure already
+         * looks. An `ok` status's message is informational and simply dropped.
+         */
+        const logStatus = (id, state, message) => {
+            if (!message || state === "ok")
+                return;
+            const logger = registry.contextFor(id, baseUrl, requestScope).logger;
+            const line = `[connecta] connector "${id}" operator status ${state}: ${message}`;
+            if (state === "auth_required")
+                logger.info(line);
+            else
+                logger.warn(line);
+        };
+        // Status first, then the catalog only when status is ok. A failed status
+        // read is an error status, not a failed row: the row still reports the
+        // connector's credential.
+        const observe = (c, drift, signal) => {
+            if (drift) {
+                return Effect.succeed({
+                    status: { state: "auth_required", message: drift },
+                    tools: [],
+                    catalogFailed: false,
+                });
+            }
+            return Effect.gen(function* () {
+                const status = yield* attempt(() => registry.statusFor(c.id, baseUrl, requestScope, { signal }));
+                if (status.state !== "ok" || signal.aborted) {
+                    return { status, tools: [], catalogFailed: false };
+                }
+                return yield* attempt(async () => (await registry.getTools(c.id, baseUrl, requestScope, { signal })).map((t) => ({
+                    name: t.name,
+                    address: `${c.id}.${t.name}`,
+                    ...(t.description ? { description: t.description } : {}),
+                    safety: uiToolSafety(t),
+                }))).pipe(Effect.map((tools) => ({ status, tools, catalogFailed: false })), 
+                // The registry owns the failed catalog observation; the page only
+                // needs to know there was one.
+                Effect.catch(() => Effect.succeed({ status, tools: [], catalogFailed: !signal.aborted })));
+            }).pipe(Effect.catch((error) => Effect.succeed({
+                status: {
+                    state: "error",
+                    message: error instanceof Error
+                        ? error.message
+                        : "Connection details unavailable",
+                },
+                tools: [],
+                catalogFailed: false,
+            })));
+        };
+        // The credential card, for someone who may manage this connector's auth.
+        // Never fails: a vault that cannot be read is the card's own error.
+        const credentialFor = (c) => {
+            const mayManageAuth = options.mayManage?.(c.id) ??
+                (c.authScope === "personal" ? Boolean(owner) : options.oauthManagement);
+            const declared = c.credential;
+            if (!declared || !vault || !mayManageAuth)
+                return Effect.succeed(undefined);
+            // One rule, shared with the test route: only the hook matching the
+            // declared credential shape can run, so the button is offered only
+            // where a click can succeed (src/credentials.ts).
+            const testRule = credentialTestRule(c);
+            const credentialFields = (metadata) => declared.fields?.map((field) => {
+                const fieldMetadata = metadata?.fields?.[field.name];
+                return {
+                    name: field.name,
+                    label: field.label,
+                    ...(field.description ? { description: field.description } : {}),
+                    ...(field.placeholder ? { placeholder: field.placeholder } : {}),
+                    inputType: field.inputType ?? "password",
+                    configured: Boolean(fieldMetadata),
+                    ...(fieldMetadata
+                        ? {
+                            lastFour: fieldMetadata.lastFour,
+                            updatedAt: fieldMetadata.updatedAt,
+                        }
+                        : {}),
+                };
+            });
+            const card = {
+                label: declared.label,
+                ...(declared.description ? { description: declared.description } : {}),
+                ...(declared.placeholder ? { placeholder: declared.placeholder } : {}),
+            };
+            return attempt(async () => {
+                const metadata = await vault.metadata(c.id, c.authScope === "personal" ? owner : undefined);
+                const fields = credentialFields(metadata);
+                const shape = storedCredentialShape(declared, metadata?.fields ?? null);
+                return {
+                    ...card,
+                    ...(fields?.length ? { fields } : {}),
+                    configured: shape.state === "valid",
+                    removable: Boolean(metadata),
+                    ...(metadata
+                        ? { lastFour: metadata.lastFour, updatedAt: metadata.updatedAt }
+                        : {}),
+                    testable: testRule.mode !== null && shape.state !== "mismatch",
+                    ...(shape.state === "mismatch"
+                        ? { error: shape.message, problem: "credential_mismatch" }
+                        : {}),
+                    // A dropped field leaves its secret in the vault, and the field
+                    // list below only renders fields the connector still declares —
+                    // so without this line there is nowhere an operator could see it.
+                    ...(shape.state === "valid" && shape.undeclared.length
+                        ? { notice: describeUndeclaredCredentialFields(shape.undeclared) }
+                        : {}),
+                };
+            }).pipe(Effect.catch(() => {
+                const fields = credentialFields();
+                return Effect.succeed({
+                    ...card,
+                    ...(fields?.length ? { fields } : {}),
+                    configured: false,
+                    removable: true,
+                    testable: testRule.mode !== null,
+                    error: "Stored credential could not be read.",
+                    problem: "credential_unreadable",
+                });
+            }));
+        };
+        const detail = (c, signal) => Effect.gen(function* () {
+            const drift = yield* attempt(() => registry.credentialDriftFor(c.id));
+            // One deadline covers the whole row. The status and catalog reads once
+            // had a second one of the same length inside it, which could only fire
+            // after this one had already ended the row.
+            const { status, tools, catalogFailed } = yield* observe(c, drift, signal);
+            const credential = yield* credentialFor(c);
+            logStatus(c.id, status.state, status.message);
+            const problem = uiProblemFor(c, status.state, {
+                credentialDrift: Boolean(drift),
+                catalogFailed,
+            });
+            return {
+                id: c.id,
+                authScope: c.authScope ?? "shared",
+                ...(c.title ? { title: c.title } : {}),
+                ...(c.description !== undefined ? { description: c.description } : {}),
+                status: status.state,
+                ...(problem ? { problem } : {}),
+                toolCount: tools.length,
+                tools,
+                // Counts only, and only when a refresh in this runtime produced them.
+                // `Registry.statusFor` already rebuilt the report through
+                // `boundedCatalogDrift`, so what lands here cannot carry a name or a
+                // schema even if the plugin seam returned one.
+                ...(status.catalogDrift ? { catalogDrift: status.catalogDrift } : {}),
+                ...(status.catalogAccess ? { catalogAccess: status.catalogAccess } : {}),
+                oauth: Boolean(c.startAuth && c.disconnectAuth),
+                ...(credential ? { credential } : {}),
+            };
+        });
+        const unavailable = (c, error) => Effect.sync(() => {
+            logStatus(c.id, "failed", error instanceof Error ? error.message : String(error));
+            return {
+                id: c.id,
+                ...(c.title ? { title: c.title } : {}),
+                authScope: c.authScope ?? "shared",
+                status: "error",
+                problem: "connector_unavailable",
+                oauth: Boolean(c.startAuth && c.disconnectAuth),
+                toolCount: 0,
+                tools: [],
+            };
+        });
+        const row = (c) => withDeadlineEffect((signal) => detail(c, signal), {
+            timeoutMs: options.timeoutMs ?? DETAIL_TIMEOUT_MS,
+            ...(options.signal ? { signal: options.signal } : {}),
+            timeoutError: new Error(DETAIL_TIMED_OUT),
+        }).pipe(
+        // A hook that throws where it should reject fails its own row too.
+        Effect.catchDefect((defect) => Effect.fail(defect)), Effect.catch((error) => unavailable(c, error)), Effect.ensuring(Effect.suspend(() => closeScope(c, registry.contextFor(c.id, baseUrl, requestScope), options.defer))));
+        return Effect.forEach(registry.listConnectors(), row, {
+            concurrency: resolveDiscoveryConcurrency(options.discoveryConcurrency),
+        }).pipe(Effect.map((connectors) => ({
+            serverInfo: options.serverInfo,
+            connectaVersion: CONNECTA_VERSION,
+            connectors,
+            activityEnabled: options.activityEnabled,
+            credentialManagement: options.credentialManagement,
+            oauthManagement: options.oauthManagement || Boolean(owner),
+        })));
+    });
+}

package/dist/routes/ui.js

@@ -1,7 +1,10 @@
+import { Effect } from "effect";
 import { CONNECTA_VERSION } from "../version.js";
 import { CONNECTA_FAVICON_ICO } from "../favicon.js";
-import { buildUiData, CONNECTA_FAVICON_SVG, operatorPageForPath, renderUiHtml, } from "../ui.js";
-import { authorize, mayManageConnector, validateAuthPermissions, msg, privateJson, } from "./shared.js";
+import { CONNECTA_FAVICON_SVG, operatorPageForPath, renderUiHtml, } from "../ui.js";
+import { authorized, refuse, scopeFor, serveOperator, visibleRegistry, } from "./operator.js";
+import { mayManageConnector, privateJson, } from "./shared.js";
+import { uiData } from "./ui-data.js";
 /**
  * Headers that make an operator-supplied favicon body inert on this origin.
  * The SVG route is the sharp one: `image/svg+xml` is an *active* content type,
@@ -38,7 +41,7 @@ function uiScriptNonce() {
     return btoa(binary);
 }
 export async function routeUi(context) {
-    const { request, url, path, baseUrl, opts, defer, runtimeContext } = context;
+    const { request, url, path, baseUrl, opts, runtimeContext } = context;
     if (request.method === "GET" && path === "/favicon.svg") {
         return new Response(opts.branding?.favicon?.svg ?? CONNECTA_FAVICON_SVG, {
             headers: {
@@ -103,22 +106,11 @@ export async function routeUi(context) {
         return null;
     if (request.method !== "GET")
         return privateJson({ error: "method not allowed" }, { status: 405 });
-    const authz = await authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity);
-    if (!authz.ok)
-        return authz.response;
-    let registry;
-    try {
-        validateAuthPermissions(authz, opts.registry);
-        registry = opts.registry.scoped({
-            connectorIds: authz.connectorIds,
-            ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}),
-            ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
-            ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
-        });
-    }
-    catch (error) {
-        return privateJson({ error: msg(error) }, { status: 403 });
-    }
+    // Reads: a caller who leaves stops whatever the payload was waiting on.
+    return serveOperator(detail ? connectorDetail(context, detail[1]) : summary(context), request.signal);
+}
+/** What this identity may see and do, for the summary and a detail alike. */
+function operatorView({ opts }, authz, registry) {
     const visible = registry.listConnectors();
     const mayManage = (id) => { const connector = registry.getConnector(id); return Boolean(connector && mayManageConnector(authz, connector)); };
     const permissions = (connector) => ({
@@ -130,20 +122,60 @@ export async function routeUi(context) {
     const credentialManagement = visible.some(c => c.credential && mayManage(c.id))
         ? opts.credentialVault ? "available" : "vault_not_configured"
         : authz.identity.interactive && !visible.some(c => c.credential) ? "no_slots" : "requires_operator";
-    if (detail) {
-        const connector = registry.getConnector(detail[1]);
+    return { visible, mayManage, permissions, activityEnabled, credentialManagement };
+}
+/** One connector's probed row, the page's second request per card. */
+function connectorDetail(context, id) {
+    const { request, baseUrl, opts, defer } = context;
+    return Effect.gen(function* () {
+        const authz = yield* authorized(context);
+        const registry = yield* visibleRegistry(context, authz);
+        const { mayManage, permissions, activityEnabled, credentialManagement } = operatorView(context, authz, registry);
+        const connector = registry.getConnector(id);
         if (!connector)
-            return privateJson({ error: "unknown connector" }, { status: 404 });
-        const one = opts.registry.scoped({ connectorIds: [connector.id], ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}), ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}), ...(authz.principalKey ? { principalKey: authz.principalKey } : {}) });
-        const data = await buildUiData(one, baseUrl, opts.serverInfo, opts.credentialVault, activityEnabled, credentialManagement, defer, false, 1, authz.principalKey, { mayManage, timeoutMs: opts.probeTimeoutMs ?? 30_000, signal: request.signal });
+            return yield* refuse("unknown connector", 404);
+        const data = yield* uiData(opts.registry.scoped(scopeFor(authz, [connector.id])), baseUrl, {
+            serverInfo: opts.serverInfo,
+            credentialVault: opts.credentialVault,
+            activityEnabled,
+            credentialManagement,
+            defer,
+            oauthManagement: false,
+            discoveryConcurrency: 1,
+            personalCredentialOwner: authz.principalKey,
+            mayManage,
+            timeoutMs: opts.probeTimeoutMs ?? 30_000,
+            signal: request.signal,
+        });
         return privateJson({ ...data.connectors[0], permissions: permissions(connector) });
-    }
-    return privateJson({
-        serverInfo: opts.serverInfo,
-        connectaVersion: CONNECTA_VERSION,
-        activityEnabled,
-        credentialManagement,
-        oauthManagement: visible.some(c => mayManage(c.id)),
-        connectors: visible.map(c => ({ id: c.id, ...(c.title ? { title: c.title } : {}), ...(c.description ? { description: c.description } : {}), authScope: c.authScope ?? "shared", status: "loading", toolCount: 0, tools: [], oauth: Boolean(c.startAuth && c.disconnectAuth), permissions: permissions(c) })),
+    });
+}
+/** The summary: every visible connector as "loading", with no probe at all. */
+function summary(context) {
+    const { opts } = context;
+    return Effect.gen(function* () {
+        const authz = yield* authorized(context);
+        const registry = yield* visibleRegistry(context, authz);
+        const { visible, mayManage, permissions, activityEnabled, credentialManagement } = operatorView(context, authz, registry);
+        // Setup commands are offered per pool, but only for pools this identity's
+        // grant admits: `/mcp/<name>` answers every other name with one flat 404 so
+        // a credential cannot enumerate them, and the page must not undo that.
+        const pools = [];
+        for (const [name, pool] of opts.pools ?? []) {
+            const granted = yield* Effect.tryPromise(async () => (await pool.grant(authz.identity)) === true).pipe(
+            // A throwing grant is a refusal at the endpoint, and so a refusal here.
+            Effect.orElseSucceed(() => false));
+            if (granted)
+                pools.push(name);
+        }
+        return privateJson({
+            ...(pools.length ? { pools } : {}),
+            serverInfo: opts.serverInfo,
+            connectaVersion: CONNECTA_VERSION,
+            activityEnabled,
+            credentialManagement,
+            oauthManagement: visible.some(c => mayManage(c.id)),
+            connectors: visible.map(c => ({ id: c.id, ...(c.title ? { title: c.title } : {}), ...(c.description ? { description: c.description } : {}), authScope: c.authScope ?? "shared", status: "loading", toolCount: 0, tools: [], oauth: Boolean(c.startAuth && c.disconnectAuth), permissions: permissions(c) })),
+        });
     });
 }

package/dist/runtime/admission.js

@@ -0,0 +1,43 @@
+// The Effect face of bounded admission (src/executor-admission.ts).
+//
+// AdmissionController is a published class, and its declaration — private
+// member names included — is part of what ships, so its Effect program cannot
+// hang off a new field or method. The class hands that program here from a
+// static block instead: the one place outside its instance methods that may
+// read its private bookkeeping, and one that emits nothing into the `.d.ts`.
+// Promise callers keep `acquire()`, which runs the same program through
+// runEdge; Effect callers come through this module and never see a Promise.
+import { Effect } from "effect";
+let program;
+/**
+ * Install the controller's admission program. Called once, by
+ * AdmissionController's static block, when that module evaluates — which any
+ * importer of this module's value exports has already caused, since they need
+ * a controller to pass in.
+ */
+export function provideAdmissionProgram(admit) {
+    program = admit;
+}
+/**
+ * Admit one unit of work, as `controller.acquire()` does, without a Promise.
+ *
+ * Fails with the same ExecutorAdmissionError objects, bumps the same counters,
+ * and honours the same queue bound and timeout. Interrupting the fiber while
+ * it is queued withdraws it (counted as cancelled); interrupting it after a
+ * slot was handed over releases that slot rather than stranding it.
+ */
+export function admit(controller, options = {}) {
+    if (!program) {
+        throw new Error("AdmissionController's admission program was never installed.");
+    }
+    return program(controller, options.signal);
+}
+/**
+ * A lease owned by the enclosing Scope: released when the scope closes, on
+ * success, failure, or interruption alike. The wait itself stays
+ * interruptible — a queued request whose caller left must not hold its place
+ * in line until the queue timeout.
+ */
+export function acquireScoped(controller, options = {}) {
+    return Effect.acquireRelease(admit(controller, options), (lease) => Effect.sync(() => lease.release()), { interruptible: true });
+}

package/dist/runtime/call-admission.js

@@ -0,0 +1,67 @@
+// The Effect face of downstream call admission (src/call-admission.ts).
+//
+// ConnectorCallAdmissionController is a published class whose declaration —
+// private member names included — ships, so its Effect program cannot hang
+// off a new field or method. As with AdmissionController (see
+// src/runtime/admission.ts), the class hands that program here from a static
+// block: the one place outside its instance methods that may read its private
+// bookkeeping, and one that emits nothing into the `.d.ts`.
+//
+// The two controllers stay separate on purpose (#453): request admission
+// bounds executor work, this bounds calls to one downstream connector, and a
+// shared queue between them was refused.
+import { Effect } from "effect";
+let program;
+// What the live Clock reads, looked up on every call rather than bound once,
+// so a Date faked after a caller queued (vitest's setSystemTime) still counts.
+const liveNow = () => Date.now();
+/**
+ * Install the controller's admission program. Called once, by
+ * ConnectorCallAdmissionController's static block, when that module
+ * evaluates — which any caller has already caused, since it needs a
+ * controller to pass in.
+ */
+export function provideCallAdmissionProgram(admit) {
+    program = admit;
+}
+function installed() {
+    if (!program) {
+        throw new Error("ConnectorCallAdmissionController's admission program was never installed.");
+    }
+    return program;
+}
+/**
+ * The Promise shell's entry: decide now, on `Date.now()` — the value the live
+ * Clock reads — and return only the wait.
+ *
+ * Deciding eagerly is what keeps the limiter payload-free. The returned
+ * effect closes over the partition key, never the request, so a queued call
+ * does not retain its tool arguments for as long as it waits.
+ */
+export function startCallAdmission(controller, request) {
+    return installed()(controller, request, liveNow);
+}
+/**
+ * Admit one downstream call, as `controller.acquire()` does, without a
+ * Promise.
+ *
+ * Fails with the same CallAdmissionError objects and bumps the same counters.
+ * The rolling window and queue-wait times read the fiber's Clock. Nothing
+ * happens until the effect runs, and each run is a fresh admission.
+ * Interrupting the fiber while it is queued withdraws it (counted as
+ * cancelled); interrupting it after a slot was handed over releases that slot
+ * rather than stranding it.
+ */
+export function admitCall(controller, request) {
+    const admit = installed();
+    return Effect.clockWith((clock) => admit(controller, request, () => clock.currentTimeMillisUnsafe()));
+}
+/**
+ * A permit owned by the enclosing Scope: released when the scope closes, on
+ * success, failure, or interruption alike. The queued wait stays
+ * interruptible, so a caller that left does not hold its place in line until
+ * the queue timeout.
+ */
+export function acquireCallScoped(controller, request) {
+    return Effect.acquireRelease(admitCall(controller, request), (permit) => Effect.sync(() => permit.release()), { interruptible: true });
+}

package/dist/runtime/connector-scope.js

@@ -0,0 +1,72 @@
+// The Effect face of connector scope teardown (src/connector-scope.ts).
+//
+// closeConnectorScope() is the Promise shell over closeScope() below. An
+// Effect caller that owns a Scope registers the close as that scope's
+// finalizer instead, so teardown runs however the work inside it ends.
+import { Duration, Effect } from "effect";
+import { detach } from "./run.js";
+/** Enough for local transport abort/close without letting cleanup own latency. */
+const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
+/**
+ * Bound on cleanup continued after the caller-facing window expires.
+ *
+ * `remoteMcp` spends at most one second asking the downstream to terminate its
+ * session, leaving another second for the local close. Custom hooks still get a
+ * finite background window: handing a never-settling promise to a Worker's
+ * `waitUntil` would otherwise keep the invocation alive until the platform cap.
+ */
+const CONNECTOR_SCOPE_DEFER_BUDGET_MS = 2_000;
+/**
+ * Succeed when `work` settles or `budgetMs` expires, whichever is first; never
+ * fail. The loser is interrupted, so a close that finishes early leaves no
+ * timer behind. Interrupting the wait leaves `work` running: nothing here can
+ * cancel a connector's close, only stop waiting for it.
+ */
+function waitAtMost(work, budgetMs) {
+    return Effect.raceAllFirst([
+        Effect.promise(() => work),
+        Effect.sleep(Duration.millis(budgetMs)),
+    ]);
+}
+/**
+ * Tell a connector that a scope owned by the core has ended, with the contract
+ * closeConnectorScope() documents: best-effort, never failing, waited on for a
+ * small fixed window, with a bounded tail handed to `defer` when the runtime
+ * has one. The hook is called when the effect runs, not when it is built.
+ */
+export function closeScope(connector, ctx, defer) {
+    return Effect.suspend(() => {
+        let settled;
+        try {
+            const closing = connector.closeScope?.(ctx);
+            if (!closing)
+                return Effect.void;
+            // Attach both handlers before either timer can win, so a late rejection
+            // is consumed rather than becoming an unhandled rejection.
+            settled = closing.then(() => { }, () => { });
+        }
+        catch {
+            // The scope is over whether or not the connector managed to clean it up.
+            return Effect.void;
+        }
+        if (defer) {
+            try {
+                detach(waitAtMost(settled, CONNECTOR_SCOPE_DEFER_BUDGET_MS), {
+                    waitUntil: defer,
+                });
+            }
+            catch {
+                // A runtime hook is best-effort too; the caller cap still applies.
+            }
+        }
+        return waitAtMost(settled, CONNECTOR_SCOPE_CLOSE_BUDGET_MS);
+    });
+}
+/**
+ * Close the connector scope when the enclosing Scope closes — on success,
+ * failure, or interruption alike. Callers still own the at-most-once
+ * guarantee: register the finalizer once per connector scope.
+ */
+export function closeScopeOnExit(connector, ctx, defer) {
+    return Effect.addFinalizer(() => closeScope(connector, ctx, defer));
+}