@zackbart/connecta 0.37.1 → 0.39.0

package/dist/routes/credentials.js

@@ -1,7 +1,10 @@
 import { failureRecord, logFailure } from "../operator-record.js";
 import { Effect } from "effect";
-import { claimConnectorScopeCleanup, closeConnectorScope } from "../connector-scope.js";
+import { claimConnectorScopeCleanup } from "../connector-scope.js";
 import { credentialTestRule, describeCredentialTestMismatch, storedCredentialShape } from "../credential-rules.js";
+import { credentialFailureClass, credentialTestOutcome, writeVerification, } from "../credential-verification.js";
+import { closeScope } from "../runtime/connector-scope.js";
+import { withDeadlineEffect } from "../runtime/run.js";
 import { authorizedPerson, refuse, serveOperator, managementRegistry } from "./operator.js";
 import { boundedText, mayManageConnector, isSameOrigin, msg, privateJson } from "./shared.js";
 /** The longest body, in characters, a credential write accepts. */
@@ -51,9 +54,19 @@ function readCredentialInput(request, config) {
         // `null` parses, but a credential cannot be read from it.
         if (body === null)
             return yield* refuse("invalid JSON body", 400);
-        return yield* credentialInput(body, config);
+        if (body.verify !== undefined && body.verify !== "test" && body.verify !== "skip") {
+            return yield* refuse('verify must be "test" or "skip"', 400);
+        }
+        const input = yield* credentialInput(body, config);
+        return { input, verify: body.verify ?? "skip" };
     });
 }
+/** The test hook's refusal when the declared shape picks none, in the page's words. */
+function untestable(mismatch) {
+    return refuse(mismatch
+        ? "this connector cannot test its credential: " + describeCredentialTestMismatch(mismatch)
+        : "this connector does not support credential testing", 400);
+}
 function credentialRequest(context, connectorId, action) {
     const { request, baseUrl, opts } = context;
     return Effect.gen(function* () {
@@ -79,6 +92,64 @@ function credentialRequest(context, connectorId, action) {
         const updatedBy = authz.identity.principal
             ? `${authz.identity.principal.namespace}:${authz.identity.principal.id}`
             : (authz.actor.id ?? authz.actor.kind);
+        /**
+         * Run the connector's test hook on `values` — the stored credential or an
+         * unsaved candidate, which stays in this request's memory — under the
+         * deployment's probe deadline. Settles to an outcome class and never
+         * fails: whatever goes wrong is the test's result, not the route's. Each
+         * run gets its own context and request scope, so concurrent tests share
+         * no connection.
+         *
+         * Only the class leaves. A hook's message, and anything it throws, can
+         * quote the downstream's reply, and that reply can quote the credential
+         * it just rejected — so neither the page nor the log repeats it (INV-6):
+         * the page says fixed copy for the class, and the log records a
+         * failure's class.
+         */
+        const runTest = (mode, values) => {
+            const timeoutError = new Error("credential test timed out");
+            return withDeadlineEffect((signal) => {
+                const ctx = registry.contextFor(connectorId, baseUrl, {}, { signal });
+                const releaseCleanup = claimConnectorScopeCleanup(ctx, connectorId);
+                return Effect.tryPromise({
+                    try: async () => {
+                        const result = mode === "multiple"
+                            ? await connector.testCredentials(values, ctx)
+                            : // The single-value shape guarantees this key.
+                                await connector.testCredential(values.value, ctx);
+                        // A hook that turned the deadline's abort into a result still ran out of time.
+                        return signal.reason === timeoutError ? "timeout" : credentialTestOutcome(result);
+                    },
+                    catch: (error) => (signal.reason === timeoutError ? timeoutError : error),
+                }).pipe(
+                // The scope closes here, once, however the test ends: a hook that
+                // never settles is interrupted by the deadline, and a cleanup in
+                // its Promise would never run (INV-7).
+                Effect.ensuring(Effect.suspend(() => {
+                    releaseCleanup();
+                    return closeScope(connector, ctx, context.defer);
+                })));
+            }, { timeoutMs: opts.config.discovery.probeTimeoutMs, timeoutError }).pipe(Effect.catch((error) => {
+                if (error === timeoutError)
+                    return Effect.succeed("timeout");
+                logFailure(opts.config.logger, "credential test threw", failureRecord({ connector: connectorId }, error));
+                return Effect.succeed(credentialFailureClass(error));
+            }), Effect.map((outcome) => {
+                if (outcome !== "ok")
+                    logFailure(opts.config.logger, "credential test failed", failureRecord({ connector: connectorId }));
+                return outcome;
+            }));
+        };
+        /**
+         * Record what was observed about the save with `revision`, or (`null`)
+         * forget it, in the connector's own owner-partitioned storage. A save
+         * without a revision (a vault that keeps none) is never recorded. Best
+         * effort: a lost record only leaves status saying the credential is not
+         * verified, so it never fails the request.
+         */
+        const record = (outcome, revision) => Effect.promise(async () => outcome && !revision
+            ? undefined
+            : writeVerification(registry.contextFor(connectorId, baseUrl).storage, outcome, revision).catch((error) => void logFailure(opts.config.logger, "credential verification record failed", failureRecord({ connector: connectorId }, error))));
         if (action === "test") {
             if (request.method !== "POST")
                 return yield* refuse("method not allowed", 405);
@@ -86,79 +157,74 @@ function credentialRequest(context, connectorId, action) {
             // Credentials page asks for its Test affordance, so a shown button reaches
             // that reads the shape the credential was stored in.
             const { mode, mismatch } = credentialTestRule(connector);
-            if (!mode) {
-                return yield* refuse(mismatch
-                    ? "this connector cannot test its credential: " + describeCredentialTestMismatch(mismatch)
-                    : "this connector does not support credential testing", 400);
-            }
-            // Whatever goes wrong past this point is the test's result, not the
-            // route's: the page shows it beside the Test button. Only `ok` leaves
-            // the host. A hook's message, and anything it throws, can quote the
-            // downstream's reply, and that reply can quote the credential it just
-            // rejected — so neither the page nor the log repeats it (INV-6): the
-            // page says a fixed sentence for the outcome, and the log records a
-            // failure's class.
-            return yield* Effect.tryPromise({
-                try: async () => {
-                    const values = await vault.getAll(connectorId, owner);
-                    const shape = storedCredentialShape(credential, values);
-                    // Both refusals are the route's own words, and each carries the
-                    // problem kind the page keys its copy and fix prompt off.
-                    if (shape.state === "missing") {
-                        return privateJson({
-                            error: mode === "multiple"
-                                ? "configure the credentials before testing them"
-                                : "configure the credential before testing it",
-                            problem: "credential_required",
-                        }, { status: 409 });
-                    }
-                    if (shape.state === "mismatch") {
-                        return privateJson({ error: shape.message, problem: "credential_mismatch" }, { status: 409 });
-                    }
-                    const storedValues = values;
-                    const ctx = registry.contextFor(connectorId, baseUrl);
-                    const releaseCleanup = claimConnectorScopeCleanup(ctx, connectorId);
-                    try {
-                        const result = mode === "multiple"
-                            ? await connector.testCredentials(storedValues, ctx)
-                            : await connector.testCredential(
-                            // The single-value shape check above guarantees this key.
-                            storedValues.value, ctx);
-                        const ok = result?.ok === true;
-                        if (!ok)
-                            logFailure(opts.config.logger, "credential test failed", failureRecord({ connector: connectorId }, undefined));
-                        return privateJson({ ok });
-                    }
-                    finally {
-                        releaseCleanup();
-                        await closeConnectorScope(connector, ctx, context.defer);
-                    }
-                },
+            if (!mode)
+                return yield* untestable(mismatch);
+            // One envelope read gives both the values tested and the revision of
+            // the save they came from, so the record can never vouch for another
+            // save. A vault without snapshots is tested but never recorded.
+            const stored = yield* Effect.tryPromise({
+                try: async () => vault.snapshot
+                    ? ((await vault.snapshot(connectorId, owner)) ?? { values: null })
+                    : { values: await vault.getAll(connectorId, owner) },
                 catch: (error) => error,
             }).pipe(Effect.catch((error) => {
                 logFailure(opts.config.logger, "credential test threw", failureRecord({ connector: connectorId }, error));
-                return Effect.succeed(privateJson({ ok: false }));
+                return Effect.succeed(undefined);
             }));
+            if (!stored)
+                return privateJson({ ok: false, failure: "failed" });
+            const shape = storedCredentialShape(credential, stored.values);
+            // Both refusals are the route's own words, and each carries the
+            // problem kind the page keys its copy and fix prompt off.
+            if (shape.state === "missing") {
+                return privateJson({
+                    error: mode === "multiple"
+                        ? "configure the credentials before testing them"
+                        : "configure the credential before testing it",
+                    problem: "credential_required",
+                }, { status: 409 });
+            }
+            if (shape.state === "mismatch") {
+                return privateJson({ error: shape.message, problem: "credential_mismatch" }, { status: 409 });
+            }
+            const outcome = yield* runTest(mode, stored.values);
+            if ("metadata" in stored)
+                yield* record(outcome, stored.metadata.revision);
+            return privateJson(outcome === "ok" ? { ok: true } : { ok: false, failure: outcome });
         }
         if (action)
             return yield* refuse("not found", 404);
         if (request.method === "PUT") {
-            const input = yield* readCredentialInput(request, credential);
-            return yield* Effect.tryPromise({
-                try: async () => {
-                    const metadata = input.kind === "single"
-                        ? await vault.set(connectorId, input.value, updatedBy, owner)
-                        : await vault.setAll(connectorId, input.values, updatedBy, owner);
-                    await registry.invalidateStored(connectorId);
-                    return privateJson({ credential: metadata });
-                },
+            const { input, verify } = yield* readCredentialInput(request, credential);
+            const values = input.kind === "single" ? { value: input.value } : input.values;
+            if (verify === "test") {
+                // Test then save: the candidate is tested in memory and stored only
+                // if the test passes. A failure stores nothing and names its class;
+                // the operator may still save it unverified with `verify: "skip"`,
+                // so an outage at the vendor never blocks a replacement.
+                const { mode, mismatch } = credentialTestRule(connector);
+                if (!mode)
+                    return yield* untestable(mismatch);
+                const outcome = yield* runTest(mode, values);
+                if (outcome !== "ok")
+                    return privateJson({ saved: false, failure: outcome });
+            }
+            const metadata = yield* Effect.tryPromise({
+                try: () => input.kind === "single"
+                    ? vault.set(connectorId, input.value, updatedBy, owner)
+                    : vault.setAll(connectorId, input.values, updatedBy, owner),
                 catch: (error) => error,
             }).pipe(Effect.catch((error) => refuse(msg(error), 400)));
+            // The write's own revision: a concurrent save cannot lend it one.
+            const { revision, ...saved } = metadata;
+            const verification = yield* record(verify === "test" ? "ok" : "unverified", revision);
+            yield* Effect.promise(() => registry.invalidateStored(connectorId));
+            return privateJson({ saved: true, credential: saved, ...(verification ? { verification } : {}) });
         }
         if (request.method === "DELETE") {
             // Clearing nothing is refused, as testing nothing is, so the route
             // agrees with the operator contract, which offers `clear` only once a
-            // value is stored in the caller's partition (#837). A value that cannot
+            // value is stored in the caller's partition. A value that cannot
             // be read may still be cleared: removing it is how one recovers.
             const stored = yield* Effect.tryPromise({
                 try: () => vault.metadata(connectorId, owner),
@@ -168,6 +234,9 @@ function credentialRequest(context, connectorId, action) {
                 return privateJson({ error: "no credential is stored to clear", problem: "credential_required" }, { status: 409 });
             }
             yield* Effect.promise(() => vault.delete(connectorId, owner));
+            // A record about a value no longer stored would match nothing anyway;
+            // removing it keeps the partition clean.
+            yield* record(null);
             yield* Effect.promise(() => registry.invalidateStored(connectorId));
             return new Response(null, {
                 status: 204,

package/dist/routes/dispatch.js

@@ -28,7 +28,11 @@ export function createRouteDispatcher(mcp, metadata, health) {
     });
     const afterUi = (program) => (context) => Effect.gen(function* () {
         const ui = context.opts.config.ui;
-        const response = ui ? yield* Effect.promise(() => ui.handle(context)) : null;
+        // The operator surface is a Promise edge that owns the request's
+        // signal: when the caller leaves, its routes stop on their own. Wait
+        // for it to settle rather than abandoning it, so writes it has
+        // already started end inside this request (INV-7).
+        const response = ui ? yield* Effect.uninterruptible(Effect.promise(() => ui.handle(context))) : null;
         if (response?.status === 401) {
             const authorizationHeader = authorizationCredential(context.request).kind;
             logFailure(context.opts.config.logger, "operator_refused", failureRecord({

package/dist/routes/mcp.js

@@ -1,4 +1,6 @@
+import { routeNames } from "../agent-routes.js";
 import { upwardStep } from "../upward.js";
+import { bindDiscoveryEndpoint } from "../discovery-health.js";
 import { authCall, authInvoke, authFlow, authMethod } from "../auth/native.js";
 import { registryProgram } from "../runtime/registry.js";
 import { requestOwner, RequestScope } from "../runtime/request-scope.js";
@@ -20,7 +22,7 @@ import { failureRecord, logFailure } from "../operator-record.js";
 import { redactAgentOutput, sentSecretsForRequest } from "../sent-secrets.js";
 import { detach } from "../runtime/run.js";
 import { agentEndpointPool, isAgentPath } from "./agent-path.js";
-import { admitsMaintainer, agentPool, authorize, authorizeAgent, mayManageConnector, memberPool, } from "./shared.js";
+import { admitsMaintainer, agentPool, authorize, authorizeAgent, mayManageConnector, memberPool, personPools, } from "./shared.js";
 /**
  * Core checks admission.requests.maxBodyBytes after authentication and endpoint
  * admission, before any SDK/body-hint reader. The SDK's separate 4 MiB default
@@ -32,7 +34,7 @@ const deadlineResponses = new WeakSet();
 /**
  * The most a `subscriptions/listen` classification reads. A listen is a small
  * JSON-RPC request; this read happens before request admission, so it is
- * bounded by this fixed cap rather than by the host's body limit (#857).
+ * bounded by this fixed cap rather than by the host's body limit.
  */
 export const MAX_LISTEN_CLASSIFICATION_BYTES = 64 * 1024;
 /**
@@ -286,7 +288,7 @@ function admitted(controller, signal) {
     }), (lease) => Effect.sync(() => lease.release()), { interruptible: true });
 }
 /**
- * 404 for any `?toolkit=` value, kept after the feature's retirement (#178).
+ * 404 for any `?toolkit=` value, kept after the feature's retirement.
  *
  * Toolkits are gone, but the URLs that named them are not: clients were handed
  * MCP endpoint URLs with `?toolkit=` baked in, and nothing about upgrading the
@@ -396,8 +398,11 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
             ...(runtimeContext?.waitUntil ? { defer: runtimeContext.waitUntil.bind(runtimeContext) } : {}),
         });
         const diagnostics = native ? { ...native, catalogErrors: [] } : undefined;
+        // A native pool's text uses the native contract's wording.
+        const routes = native ? routeNames(native.executeCode ? "native-code" : "native") : opts.routes;
         const nativeRoute = registerMetaTools(server, registry, {
             native: diagnostics,
+            routes,
             authElicitation,
             client,
             baseUrl,
@@ -409,6 +414,7 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
             credentialHandoffUrl: opts.config.ui?.credentialHandoffUrl(baseUrl),
             ...(activity ? { activity } : {}),
             defaultToolTimeoutMs: opts.config.calls.defaultTimeoutMs ?? opts.config.execute.hostCallTimeoutMs,
+            maxProgramResultChars: opts.config.execute.maxResultChars,
             probeTimeoutMs: opts.config.discovery.probeTimeoutMs,
             discoveryConcurrency: opts.config.discovery.concurrency,
             requestSignal,
@@ -429,6 +435,7 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
                 ...executeLimits(opts.config),
                 readOnly,
                 native: native !== undefined,
+                routes,
             });
         }
         if (native && nativeRoute && hint) {
@@ -596,6 +603,9 @@ export function createMcpRoute(opts) {
         const requestScope = {};
         const sentSecrets = sentSecretsForRequest(requestScope, sentSecretsForRequest(request));
         const poolName = endpoint.kind === "pool" || endpoint.kind === "agent" ? endpoint.pool : undefined;
+        // Discovery health is kept per admitted endpoint: the same person and
+        // pool at `/mcp` and `/mcp/<pool>` keep separate records.
+        bindDiscoveryEndpoint(requestScope, JSON.stringify([endpoint.kind, poolName ?? null]));
         const agentEndpoint = endpoint.kind === "agent";
         // Access attaches `ctx.access` even to a path it bypasses; an agent
         // endpoint never reads it, so nothing past this point receives it.
@@ -638,7 +648,7 @@ export function createMcpRoute(opts) {
             }));
             // A request naming `subscriptions/listen` defers its permit: nothing of
             // its body is read until auth and endpoint admission pass, and then at
-            // most MAX_LISTEN_CLASSIFICATION_BYTES (#857). Only a body-confirmed
+            // most MAX_LISTEN_CLASSIFICATION_BYTES. Only a body-confirmed
             // modern listen goes without a permit; trusting the header alone would
             // let a legacy tools/call bypass the pool, so anything else takes one
             // after classification. Every other request takes its permit here,
@@ -718,13 +728,17 @@ export function createMcpRoute(opts) {
                     false,
                     opts.config.logger,
                 ]));
-            // Plain /mcp admits maintainers and serves the whole catalog; a pool
+            // Plain /mcp serves maintainers the whole catalog and other people their unique pool; a pool
             // admits its members, people at /mcp/<pool> and agents at
             // /agent/<pool>, and serves exactly its tools (INV-4).
             const scopeFor = (admitted) => {
                 if (poolName === undefined) {
-                    return admitsMaintainer(opts, admitted)
-                        ? { access: { connectorIds: "all" }, readOnly: opts.config.readOnly }
+                    if (admitsMaintainer(opts, admitted))
+                        return { access: { connectorIds: "all" }, readOnly: opts.config.readOnly };
+                    // Exactly one membership routes; none or several fail closed.
+                    const [match, ...more] = personPools(opts, admitted.identity);
+                    return match && !more.length
+                        ? { pool: match[0], access: match[1].access, readOnly: match[1].readOnly }
                         : undefined;
                 }
                 const pool = agentEndpoint
@@ -734,6 +748,7 @@ export function createMcpRoute(opts) {
                 // same caller facts (#837 P5: agents act as the pool owner).
                 return pool
                     ? {
+                        pool: poolName,
                         access: pool.access,
                         readOnly: pool.readOnly,
                         ...(pool.owner !== undefined ? { poolOwner: pool.owner } : {}),
@@ -779,14 +794,16 @@ export function createMcpRoute(opts) {
                             ? "MCP agent endpoint request denied"
                             : "MCP pool request denied", failureRecord({
                         reason: poolName === undefined
-                            ? "not_maintainer"
+                            ? personPools(opts, authz.identity).length > 1
+                                ? "ambiguous_pool"
+                                : "not_maintainer"
                             : opts.pools.has(poolName)
                                 ? "not_pool_member"
                                 : "pool_not_declared",
                     }));
                     return notFound();
                 }
-                const { access, readOnly, poolOwner } = scope;
+                const { access, readOnly } = scope;
                 // Admission, not completed-call activity. This fact carries no live
                 // identity or credential and never changes the admission verdict.
                 if (agentEndpoint && authz.identity.agent && opts.config.agents.includes(authz.identity.agent)) {
@@ -811,15 +828,15 @@ export function createMcpRoute(opts) {
                 }
                 // The caller rides on the view, and the paging recheck builds the
                 // same one: an agent's Workspace visibility depends on the owner.
-                const callerFor = (identity, owner) => ({
+                const callerFor = (identity, admittedScope) => ({
                     identity,
                     // `authorize` admits an open deployment's every request as the
                     // anonymous actor; only a provider's `ok` is an authentication.
                     authenticated: opts.config.auth.length > 0,
                     // Both pool endpoints build the caller here from the same
                     // admitted scope, so an agent at /agent/<pool> carries the owner.
-                    ...(poolName !== undefined ? { pool: poolName } : {}),
-                    ...(owner !== undefined ? { poolOwner: owner } : {}),
+                    ...(admittedScope.pool !== undefined ? { pool: admittedScope.pool } : {}),
+                    ...(admittedScope.poolOwner !== undefined ? { poolOwner: admittedScope.poolOwner } : {}),
                 });
                 let scopedRegistry;
                 try {
@@ -843,14 +860,14 @@ export function createMcpRoute(opts) {
                                 return false;
                             // Paging re-admits the caller at this endpoint, as a new request would.
                             const currentScope = scopeFor(current);
-                            if (!currentScope)
+                            if (!currentScope || currentScope.pool !== scope.pool)
                                 return false;
-                            const { access: currentAccess, readOnly: currentReadOnly, poolOwner: currentOwner } = currentScope;
+                            const { access: currentAccess, readOnly: currentReadOnly } = currentScope;
                             const view = opts.registry.scoped({
                                 ...currentAccess,
                                 ...(current.subjectKey ? { subjectKey: current.subjectKey } : {}),
                                 ...(current.principalKey ? { principalKey: current.principalKey } : {}),
-                                caller: callerFor(current.identity, currentOwner),
+                                caller: callerFor(current.identity, currentScope),
                             });
                             if (classification === "write" && currentReadOnly)
                                 return false;
@@ -897,7 +914,7 @@ export function createMcpRoute(opts) {
                                 }
                             }
                         })),
-                        caller: callerFor(authz.identity, poolOwner),
+                        caller: callerFor(authz.identity, scope),
                     });
                 }
                 catch {
@@ -909,7 +926,7 @@ export function createMcpRoute(opts) {
                 return cors(yield* serveMcp(localRequest, localAbort.signal, requestScope, opts, baseUrl, authz.actor, scopedRegistry, (id) => {
                     const connector = scopedRegistry.getConnector(id);
                     return Boolean(connector && mayManageConnector(opts, authz, connector));
-                }, authz.principalKey, runtimeContext, readOnly, poolName, authz.identity.principal
+                }, authz.principalKey, runtimeContext, readOnly, scope.pool, authz.identity.principal
                     ? {
                         kind: authz.actor.kind,
                         id: authz.identity.principal.id,

package/dist/routes/oauth-management.js

@@ -23,7 +23,7 @@ function oauthManagementRequest(context, connectorId) {
         const registry = yield* managementRegistry(context, authz);
         const connector = registry.getConnector(connectorId);
         const disconnectAuth = connector?.disconnectAuth?.bind(connector);
-        // Each verb needs only its own hooks (#837): connecting needs the whole
+        // Each verb needs only its own hooks: connecting needs the whole
         // flow, through the callback's state check; disconnecting needs only
         // disconnectAuth, so a grant provisioned out of band can still be dropped.
         const connects = Boolean(connector?.startAuth && connector.finishAuth && connector.verifyState);

package/dist/routes/operator.js

@@ -1,3 +1,4 @@
+import { bytesToHex } from "../bytes.js";
 // The Effect plumbing the operator and activity data routes share.
 //
 // Each JSON route under /ui/* is one Effect program, run at its Promise edge
@@ -84,7 +85,7 @@ export function operatorViewerKey(context, authz) {
         ]));
         const signingKey = key;
         const digest = yield* attempt(() => crypto.subtle.sign("HMAC", signingKey, identity));
-        return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        return bytesToHex(new Uint8Array(digest));
     }), {
         timeoutMs: 500,
         signal: context.request.signal,
@@ -92,16 +93,16 @@ export function operatorViewerKey(context, authz) {
     }).pipe(Effect.catch(() => refuse("operator identity could not be read", 503)));
 }
 /** The partition an identity carries into a registry view of the given connectors. */
-export function scopeFor(authz, authenticated, connectorIds = "all") {
+export function scopeFor(authz, authenticated, connectorIds = "all", pool) {
     return {
         connectorIds,
         ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
         ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
-        operatorCaller: { identity: authz.identity, authenticated },
+        operatorCaller: { identity: authz.identity, authenticated, ...(pool !== undefined ? { pool } : {}) },
     };
 }
 /**
- * The whole registry, for a maintainer only (#837). Everyone else gets the
+ * The whole registry, for a maintainer only. Everyone else gets the
  * private 404 plain `/mcp` gives them.
  */
 export function visibleRegistry({ opts }, authz) {
@@ -111,7 +112,7 @@ export function visibleRegistry({ opts }, authz) {
     return Effect.succeed(opts.registry.scoped(scopeFor(authz, opts.config.auth.length > 0)));
 }
 /**
- * The connectors a connector-auth route may resolve (#837): every connector
+ * The connectors a connector-auth route may resolve: every connector
  * for a maintainer, the connectors of their pools for a pool member, and the
  * private 404 for anyone else. mayManageConnector still decides each action.
  */

package/dist/routes/shared.d.ts

@@ -1,3 +1,4 @@
+import type { AgentRouteNames } from "../types.js";
 import type { ActivityActor } from "../activity.js";
 import type { DeferredWork } from "../connector-scope.js";
 import type { AdmissionController } from "../executor-admission.js";
@@ -28,6 +29,8 @@ export interface ServerOptions {
     executorName?: string | undefined;
     /** Global FIFO boundary for all non-preflight `/mcp` requests. */
     requestAdmission: AdmissionController;
+    /** Route names agent text uses outside native pools: meta, or program form for the eval code arm only. */
+    routes: AgentRouteNames;
 }
 export interface RuntimeExecutionContext extends InboundAuthRuntimeContext {
     waitUntil(promise: Promise<unknown>): void;
@@ -78,7 +81,7 @@ export declare function authorize(request: Request, baseUrl: string, auth: reado
     response: Response;
 }>;
 /**
- * Admission at an agent endpoint, `/agent/<pool>` (#837). Only the built-in
+ * Admission at an agent endpoint, `/agent/<pool>`. Only the built-in
  * agent credential adapters are consulted: Clerk and Access never run, cookies and Clerk
  * handshake parameters are stripped, and the runtime context, which carries
  * Access's `ctx.access` even on a bypassed path, is never passed. Anything but
@@ -88,31 +91,33 @@ export declare function authorizeAgent(request: Request, baseUrl: string, auth:
 /** Human routes reject machine credentials before any verification or storage I/O. */
 export declare function authorizeUiIdentity(request: Request, baseUrl: string, auth: readonly InboundAuth[], purpose: string, runtimeContext?: RuntimeExecutionContext, logger?: Logger): Promise<Awaited<ReturnType<typeof authorize>>>;
 export declare function isSameOrigin(request: Request, baseUrl: string): boolean;
-export declare function withSecurityHeaders(response: Response, requestUrl: URL, _path: string): Response;
+export declare function withSecurityHeaders(response: Response, requestUrl: URL): Response;
 type AuthorizedIdentity = Extract<Awaited<ReturnType<typeof authorize>>, {
     ok: true;
 }>;
 /**
- * Plain `/mcp` and every operator route admit a maintainer (#837). An open
+ * Every operator route admits a maintainer. An open
  * deployment has no inbound auth and so no maintainers: its one anonymous
  * caller keeps the whole default endpoint, as the startup warning says.
  */
 export declare function admitsMaintainer(opts: ServerOptions, authz: AuthorizedIdentity): boolean;
 /**
  * The declared pool `/mcp/<name>` serves to this person, or undefined for the
- * same 404. An agent is never admitted here, even when listed (#837).
+ * same 404. An agent is never admitted here, even when listed.
  */
 export declare function memberPool(opts: ServerOptions, name: string, identity: Readonly<AuthenticatedIdentity>): ResolvedPool | undefined;
+/** Human memberships, matched only against the resolved namespaced principal. */
+export declare function personPools(opts: ServerOptions, identity: Readonly<AuthenticatedIdentity>): Array<[string, ResolvedPool]>;
 /** The declared pool `/agent/<name>` serves to this agent, or undefined for the same 404. */
 export declare function agentPool(opts: ServerOptions, name: string, identity: Readonly<AuthenticatedIdentity>): ResolvedPool | undefined;
 /**
- * The connectors of every pool this identity is a member of (#837): what a
+ * The connectors of every pool this identity is a member of: what a
  * pool member may ever manage, and only their personal ones among these.
  */
 export declare function memberConnectors(opts: ServerOptions, identity: Readonly<AuthenticatedIdentity>): "all" | ReadonlySet<string>;
 /**
  * Whether this identity may start, finish, or remove a connector's auth
- * (#837). Only an interactive person ever may; an agent or any other machine
+ * Only an interactive person ever may; an agent or any other machine
  * credential manages nothing. Shared auth is deployment-wide, so it takes a
  * maintainer. A personal connector takes a stable principal that is a
  * maintainer, whose plain `/mcp` includes it, or a member of a pool that
@@ -124,10 +129,10 @@ export declare function mayManageConnector(opts: ServerOptions, authz: Authorize
     id: string;
     authScope?: "shared" | "personal";
 }): boolean;
-/** Agent token list, issue, rotate, and revoke: an interactive maintainer only (#837). */
+/** Agent token list, issue, rotate, and revoke: an interactive maintainer only. */
 export declare function managesAgentTokens(opts: ServerOptions, authz: AuthorizedIdentity): boolean;
 /**
- * Activity reads: a maintainer principal, interactive or not (#837). Members
+ * Activity reads: a maintainer principal, interactive or not. Members
  * and agents read none, and an open deployment has no maintainer.
  */
 export declare function readsActivity(opts: ServerOptions, authz: AuthorizedIdentity): boolean;