@zackbart/connecta 0.31.0 → 0.33.0

package/dist/describe-config.d.ts

@@ -1,6 +1,7 @@
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import type { ConnectaConfig, ResolvedConfig } from "./config.js";
-import type { ConnectorAuthDescription, ConnectorDescription, ConnectorToolDescription, DescribedEndpoint } from "./types.js";
+import type { ResolvedPool } from "./membership.js";
+import type { ConnectorAuthDescription, ConnectorDescription, ConnectorToolDescription, DescribedEndpoint, IdentityReference } from "./types.js";
 /** Where a limit's value came from. */
 export type ConfigValueSource = "default" | "config";
 /** One limit and where its value came from. `null` means unset (no bound). */
@@ -8,6 +9,15 @@ export interface DescribedLimit<T = number> {
     value: T | null;
     source: ConfigValueSource;
 }
+/** A resolved pool member: a principal, or a declared agent by name. */
+export type DescribedMember = {
+    kind: "human";
+    namespace: string;
+    id: string;
+} | {
+    kind: "agent";
+    name: string;
+};
 /** One connector as `describeConfig()` reports it. */
 export interface DescribedConnector {
     id: string;
@@ -86,8 +96,13 @@ export interface ConnectaConfigDescription {
         execute: Record<keyof typeof CONFIG_DEFAULTS.execute, DescribedLimit>;
         requests: Record<keyof typeof CONFIG_DEFAULTS.admission.requests, DescribedLimit>;
     };
-    /** Trust and exact classification overrides from deployment code. */
-    trust: "trusted" | "read-only";
+    /** Whether the default /mcp endpoint refuses every write, and exact classification overrides from deployment code. */
+    readOnly: boolean;
+    /** The principals plain `/mcp` admits, resolved, in declaration order. Empty on an open deployment. */
+    maintainers: Array<{
+        namespace: string;
+        id: string;
+    }>;
     classification: Record<string, Record<string, "read" | "write">>;
     /** Inbound auth providers in the order they are tried. */
     auth: Array<{
@@ -95,13 +110,20 @@ export interface ConnectaConfigDescription {
         interactive: boolean;
         ui?: string;
     }>;
-    identity: Record<"connectorAccess" | "activityAccess" | "credentialAdministration" | "accessTokenManagement" | "personalConnection", "default" | "custom">;
+    /** Agents declared in code, by name, in declaration order. Never token state. */
+    agents: string[];
+    /**
+     * `readOnly` is resolved: the pool's own value, else the deployment's.
+     * `members` are resolved references in declaration order. `owner` is the
+     * Workspace address agents act as, or null.
+     */
     pools: Array<{
         name: string;
         path: string;
         tools: string[];
-        hasGrant: boolean;
-        trust: "trusted" | "read-only";
+        members: DescribedMember[];
+        readOnly: boolean;
+        owner: string | null;
     }>;
     modules: {
         ui: {
@@ -122,7 +144,6 @@ export interface ConnectaConfigDescription {
         };
         accessTokens: {
             enabled: boolean;
-            maxActive?: number;
         };
     };
     /** Every accepted store implements `list` and `compareAndSet`, so only its kind is told. */
@@ -154,6 +175,10 @@ export interface DescribeConfigInput {
     registry: import("./registry.js").Registry;
     raw: ConnectaConfig;
     config: ResolvedConfig;
+    /** Resolved `maintainers`. */
+    maintainers: readonly IdentityReference[];
+    /** Resolved pools; members are read from here, never from raw references. */
+    pools: ReadonlyMap<string, ResolvedPool>;
     executorName: string | undefined;
     /** True when the executor owns admission, so `admission.code` is unused. */
     executorAdmits: boolean;

package/dist/describe-config.js

@@ -183,13 +183,6 @@ function describeConnector(connector, deploymentCap, registry) {
         ...(connector.staticTools ? { tools: describedTools(registry.describeStaticTools(connector.id) ?? []) } : {}),
     };
 }
-const IDENTITY_KEYS = [
-    "connectorAccess",
-    "activityAccess",
-    "credentialAdministration",
-    "accessTokenManagement",
-    "personalConnection",
-];
 const STORE_KINDS = new Set(["memory", "d1", "sqlite"]);
 const storeKind = (described) => typeof described?.kind === "string" && STORE_KINDS.has(described.kind)
     ? described.kind
@@ -198,7 +191,6 @@ const storeKind = (described) => typeof described?.kind === "string" && STORE_KI
 export function describeConfig(input) {
     const { raw, config } = input;
     const brand = resolveBranding(config.ui?.branding);
-    const accessTokens = config.accessTokens?.describe?.();
     const storage = config.storage;
     const activityStore = config.activity?.store.describe?.();
     const D = CONFIG_DEFAULTS;
@@ -240,20 +232,24 @@ export function describeConfig(input) {
             execute: limitGroup(config.execute, ownValue(raw, "execute"), Object.keys(D.execute)),
             requests: limitGroup(config.admission.requests, ownValue(ownValue(raw, "admission"), "requests"), Object.keys(D.admission.requests)),
         },
-        trust: config.trust,
+        readOnly: config.readOnly,
+        maintainers: input.maintainers.map(({ namespace, id }) => ({ namespace: String(namespace), id: String(id) })),
         classification: structuredClone(config.classification ?? {}),
         auth: config.auth.map((provider) => ({
             kind: String(provider.kind),
             interactive: provider.interactiveOperator === true,
             ...(str(provider.uiAuth?.kind) !== undefined ? { ui: provider.uiAuth.kind } : {}),
         })),
-        identity: Object.fromEntries(IDENTITY_KEYS.map((key) => [key, typeof config.identity[key] === "function" ? "custom" : "default"])),
+        agents: [...config.agents],
         pools: Object.entries(config.pools ?? {}).map(([name, pool]) => ({
-            trust: pool.trust,
+            readOnly: pool.readOnly ?? config.readOnly,
             name,
             path: `/mcp/${name}`,
             tools: pool.tools.map(String),
-            hasGrant: typeof pool.grant === "function",
+            members: (input.pools.get(name)?.members ?? []).map((member) => member.kind === "agent"
+                ? { kind: "agent", name: member.name }
+                : { kind: "human", namespace: member.namespace, id: member.id }),
+            owner: input.pools.get(name)?.owner ?? null,
         })),
         modules: {
             ui: { enabled: config.ui !== undefined },
@@ -276,12 +272,7 @@ export function describeConfig(input) {
                     },
                 }
                 : { enabled: false },
-            accessTokens: config.accessTokens
-                ? {
-                    enabled: true,
-                    ...(num(accessTokens?.maxActive) !== undefined ? { maxActive: accessTokens.maxActive } : {}),
-                }
-                : { enabled: false },
+            accessTokens: { enabled: config.accessTokens !== undefined },
         },
         storage: {
             configured: raw.storage !== undefined,

package/dist/errors.d.ts

@@ -33,7 +33,7 @@ export type ConnectorCallErrorCode = "timeout" | "auth_required" | "downstream_o
  * Adding a member fails typecheck until {@link CLASSIFICATION_CODE_TABLE}
  * lists it.
  */
-export type ClassificationCode = ConnectorCallErrorCode | ExecutorAdmissionErrorCode | "cancelled" | "unknown_address" | "unknown_tool" | "ambiguous_tool_alias" | "catalog_lookup_failed" | "result_too_large" | "destructive_tool_requires_approval" | "auth_replay_refused" | "write_outcome_unknown" | "result_processing_failed" | "budget_exceeded" | "executor_failed" | "program_error";
+export type ClassificationCode = ConnectorCallErrorCode | ExecutorAdmissionErrorCode | "cancelled" | "unknown_address" | "unknown_tool" | "ambiguous_tool_alias" | "catalog_lookup_failed" | "result_too_large" | "destructive_tool_requires_approval" | "read_only_endpoint" | "auth_replay_refused" | "write_outcome_unknown" | "result_processing_failed" | "budget_exceeded" | "executor_failed" | "program_error";
 /** `value` when it is a code connecta assigns, else undefined. */
 export declare function classificationCode(value: unknown): ClassificationCode | undefined;
 /** One bounded, payload-free explanation of an input-schema mismatch. */

package/dist/errors.js

@@ -28,6 +28,7 @@ const CLASSIFICATION_CODE_TABLE = {
     catalog_lookup_failed: true,
     result_too_large: true,
     destructive_tool_requires_approval: true,
+    read_only_endpoint: true,
     auth_replay_refused: true,
     write_outcome_unknown: true,
     result_processing_failed: true,

package/dist/execute.js

@@ -412,6 +412,8 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
     const catalog = new CatalogService(registry, baseUrl, {
         requestScope,
         requestSignal: hostAccessSignal,
+        // connecta.search and connecta.describe never show a read-only endpoint's writes.
+        readOnly: limits.readOnly,
         // A program that just missed an address cannot call search_tools.
         searchRoute: "connecta.search",
         concurrency: limits.discoveryConcurrency,
@@ -455,7 +457,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
         }
         return value;
     };
-    /** Budget and account for writes admitted by the pool trust decision. */
+    /** Budget and account for writes a writable endpoint admits. */
     const invocationContext = (sending, timeoutMs) => ({
         source: "execute_code",
         sentSecrets,
@@ -463,9 +465,9 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
         ...(signal !== undefined ? { requestSignal: signal } : {}),
         ...(limits.dispatchController ? { dispatchSignal: limits.dispatchController.signal } : {}),
         unwrapResult: true,
-        trust: limits.trust,
+        readOnly: limits.readOnly,
         processResult: async (value, resolved, secrets, format, raw) => {
-            const page = (data, valueFormat, wireBytes) => pageProgramResult(registry, baseUrl, resolved, data, valueFormat, secrets, limits.trust, requestScope, wireBytes);
+            const page = (data, valueFormat, wireBytes) => pageProgramResult(registry, baseUrl, resolved, data, valueFormat, secrets, requestScope, wireBytes);
             const envelope = resolved.connector.kind === "mcp" && raw !== null && typeof raw === "object"
                 ? raw
                 : undefined;
@@ -605,7 +607,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
             normalizeTimeoutMs(limits.defaultToolTimeoutMs) ??
             hostCallTimeoutMs;
         const timeoutMs = Math.min(requestedMs, Math.max(1, (limits.programDeadlineAt ?? Infinity) - Date.now()));
-        // A trusted-pool write settles here — unknown if the call never returned an
+        // A program write settles here — unknown if the call never returned an
         // outcome. Credentials are filtered from arguments; submitted private values are not.
         const sending = {};
         const outcome = yield* invocation
@@ -656,7 +658,7 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 : Effect.raceAllFirst([reading, fromSignal(hostAccessSignal).pipe(Effect.mapError(cancelled))])).pipe(Effect.onExit((exit) => Effect.sync(() => diagnostics?.recordCatalog(operation, Date.now() - started, Exit.isSuccess(exit), Exit.isSuccess(exit) ? exit.value : undefined))));
     });
     const meta = createMetaTools(registry, baseUrl, {
-        trust: limits.trust,
+        readOnly: limits.readOnly,
         requestScope,
         onResultRead: (dependencies) => limits.resultDependencies?.push(...dependencies),
     });
@@ -1077,7 +1079,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 defaultToolTimeoutMs: config.defaultToolTimeoutMs,
                 programDeadlineAt: Date.now() + watchdog.ms,
                 defer: config.defer,
-                trust: config.trust,
+                readOnly: config.readOnly,
                 maxWrites: config.maxWrites,
                 programWrites,
                 resultDependencies,
@@ -1087,7 +1089,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
                 return yield* Effect.fail(new ExecutorAdmissionError("executor_cancelled", "Execution was cancelled during sandbox setup."));
             }
             const admitted = lease;
-            // A trusted-pool write may still be on the wire when the program settles:
+            // A program write may still be on the wire when the program settles:
             // close, so a write gated after this is not sent, then let the ones
             // already dispatched finish before the scope aborts them — an
             // abandoned write would be one whose outcome nobody knows.
@@ -1114,7 +1116,7 @@ export function createExecuteTool(registry, baseUrl, executor, logger, activity,
             emitted,
             diagnostics,
             program,
-            guardResult: (value, maxChars) => guardProgramReturn(value, registry, baseUrl, [...new Map(resultDependencies.map((dependency) => [JSON.stringify(dependency), dependency])).values()], sentSecrets, config.trust, logger, maxChars, programWrites.hasSucceeded),
+            guardResult: (value, maxChars) => guardProgramReturn(value, registry, baseUrl, [...new Map(resultDependencies.map((dependency) => [JSON.stringify(dependency), dependency])).values()], sentSecrets, logger, maxChars, programWrites.hasSucceeded),
         };
         const exited = Effect.exit(Effect.scoped(run)).pipe(Effect.flatMap((exit) => 
         // Releasing a QuickJS lease ends its child and rejects execute() with
@@ -1336,7 +1338,7 @@ function connectorInventory(connectors) {
         return `${prefix}${shown.join(", ")}.`;
     return `${prefix}${shown.join(", ")}${shown.length > 0 ? "; " : ""}+${omitted} more.`;
 }
-const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors, maxWrites, trust) => `One known read: call_tool. One known write: call_destructive_tool. Everything else: execute_code. ${trust === "trusted" ? "Trusted pool: programs may read and write; the host approves the program as a write." : "Read-only pool: programs read; writes use call_destructive_tool."} Limits: ${hostLimits.maxHostCalls} host calls, ${maxWrites} writes, ${hostLimits.hostCallTimeoutMs / 1_000}s/host call.
+const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors, maxWrites, readOnly) => `${readOnly ? "One known read: call_tool. Everything else: execute_code. Read-only endpoint: search and describe omit write tools, and every write call is refused." : "One known read: call_tool. One known write: call_destructive_tool. Everything else: execute_code. Writable endpoint: programs may read and write; the client approves."} Limits: ${hostLimits.maxHostCalls} host calls, ${readOnly ? "" : `${maxWrites} writes, `}${hostLimits.hostCallTimeoutMs / 1_000}s/host call.
 ${connectorInventory(connectors)}
 
 Use async () => { ... }, no arguments. No portable ambient capabilities. API:
@@ -1383,7 +1385,7 @@ export function registerExecuteTool(server, registry, ctx) {
         hostCallTimeoutMs: hostLimits.hostCallTimeoutMs,
         watchdogMs: ctx.watchdogMs,
         defer: ctx.defer,
-        trust: ctx.trust,
+        readOnly: ctx.readOnly,
         maxWrites,
         requestScope: ctx.requestScope,
     });
@@ -1391,13 +1393,13 @@ export function registerExecuteTool(server, registry, ctx) {
         description: executeDescription(emitBudgets, {
             ...hostLimits,
             hostCallTimeoutMs: normalizeTimeoutMs(ctx.defaultToolTimeoutMs) ?? hostLimits.hostCallTimeoutMs,
-        }, hasConnectorGuides(connectors), connectors, maxWrites, ctx.trust ?? "read-only"),
+        }, hasConnectorGuides(connectors), connectors, maxWrites, ctx.readOnly === true),
         inputSchema: EXECUTE_INPUT,
         outputSchema: EXECUTE_OUTPUT,
-        // The host sees execute_code as a write only on a trusted endpoint.
+        // The client sees execute_code as a write exactly when the endpoint writes.
         annotations: {
-            readOnlyHint: ctx.trust !== "trusted",
-            destructiveHint: ctx.trust === "trusted",
+            readOnlyHint: ctx.readOnly === true,
+            destructiveHint: ctx.readOnly !== true,
             openWorldHint: true,
         },
     }, (args, extra) => {

package/dist/index.d.ts

@@ -5,8 +5,9 @@ export { customExecutor, type CustomExecutorOptions } from "./executor-contract.
 export type { AccessTokensModule, ActivityModule, OperatorSurface } from "./module-contracts.js";
 export type { CredentialVault, CredentialMetadata } from "./credential-contract.js";
 export { defineConfig } from "./config.js";
-export type { AdmissionPoolConfig, ConnectaAdmissionConfig, ConnectaCallsConfig, ConnectaConfig, ConnectaDiscoveryConfig, ConnectaExecuteConfig, ConnectaIdentityConfig, ConnectaPoolConfig, ConnectaResultsConfig, ConnectorPermission, RequestAdmissionConfig, } from "./config.js";
-export type { ConfigValueSource, ConnectaConfigDescription, DescribedConnector, DescribedLimit, } from "./describe-config.js";
+export type { AdmissionPoolConfig, ConnectaAdmissionConfig, ConnectaCallsConfig, ConnectaConfig, ConnectaDiscoveryConfig, ConnectaExecuteConfig, ConnectaPoolConfig, ConnectaResultsConfig, RequestAdmissionConfig, } from "./config.js";
+export type { MemberRef } from "./membership.js";
+export type { ConfigValueSource, ConnectaConfigDescription, DescribedConnector, DescribedMember, DescribedLimit, } from "./describe-config.js";
 export interface Connecta {
     /** Web-standard fetch handler. Usable as `export default { fetch: connecta.fetch }`. */
     fetch: (request: Request, env?: unknown, ctx?: unknown) => Promise<Response>;
@@ -14,7 +15,7 @@ export interface Connecta {
     /**
      * A secret-free snapshot of the configuration this deployment runs with,
      * built once at construction: limits and where each came from, auth
-     * providers, identity rules, pools, modules, and every connector's source,
+     * providers, maintainers, agents, pools, modules, and every connector's source,
      * endpoint, auth mode, and static tools. Header values, keys, client
      * secrets, credentials, and functions never appear. The same object is
      * returned on every call.

package/dist/index.js

@@ -2,6 +2,9 @@ import { describeConfigSources } from "./config-value-sources.js";
 import { credentialTestRule, describeCredentialTestMismatch } from "./credential-rules.js";
 import { Registry } from "./registry.js";
 import { parseConnectorAccess, POOL_NAME_RE } from "./connector-access.js";
+import { assertsAgents } from "./agent-identity.js";
+import { ConfigError } from "./config-schema.js";
+import { memberContext, resolveMaintainers, resolveMembers, } from "./membership.js";
 import { createFetchHandler } from "./server.js";
 import { droppedBrandingUrls, droppedThemeTokens, droppedUiAuthUrls } from "./branding.js";
 import { readConfig } from "./config.js";
@@ -10,19 +13,21 @@ export { customExecutor } from "./executor-contract.js";
 import { AdmissionController, executorName, isAdmittingExecutor, withExecutorAdmission } from "./executor-admission.js";
 export { defineConfig } from "./config.js";
 /**
- * Validate declared pools against the connector set. Everything checkable at
- * construction throws here: a malformed name, an unparseable grant, an
- * unknown connector id, a tool address on an `api()` connector whose static
- * catalog lacks it. Remote catalogs load lazily, so their addresses are
- * checked at catalog load instead and stay unreachable until they match.
+ * Validate declared pools against the connector set and the members against
+ * auth and agents. Everything checkable at construction throws here: a
+ * malformed name, an unparseable grant, an unknown connector id, a tool
+ * address on an `api()` connector whose static catalog lacks it, and an empty,
+ * ambiguous, unknown, or repeated member. Remote catalogs load lazily, so
+ * their addresses are checked at catalog load instead and stay unreachable
+ * until they match.
  */
-function resolvePools(pools, registry) {
+function resolvePools(pools, readOnly, registry, members) {
     const resolved = new Map();
     if (!pools)
         return resolved;
     // The schema has already refused a pool that is not an object, a missing or
-    // non-array `tools`, a non-function `grant`, and a misspelled key — a
-    // misspelled `grant` would otherwise boot as a deny-all pool.
+    // non-array `tools` or `members`, and a misspelled key; the retired `grant`
+    // is refused there with its replacement named.
     for (const [name, pool] of Object.entries(pools)) {
         if (!POOL_NAME_RE.test(name)) {
             throw new Error(`ConnectaConfig.pools: pool name "${name}" must match [a-z0-9_-]+`);
@@ -52,7 +57,17 @@ function resolvePools(pools, registry) {
                 }
             }
         }
-        resolved.set(name, { access, trust: pool.trust, grant: pool.grant ?? (() => false) });
+        const path = `ConnectaConfig.pools.${name}.members`;
+        if (pool.members.length === 0) {
+            throw new ConfigError(`${path} is empty; a pool serves only its members, so list at least one.`);
+        }
+        // A pool inherits the deployment value unless it sets its own, either way.
+        resolved.set(name, Object.freeze({
+            access,
+            readOnly: pool.readOnly ?? readOnly,
+            members: Object.freeze(resolveMembers(pool.members, path, members)),
+            ...(pool.owner !== undefined ? { owner: pool.owner.trim() } : {}),
+        }));
     }
     return resolved;
 }
@@ -190,7 +205,9 @@ export function createConnecta(config) {
         results: resolved.results,
         classification: resolved.classification,
     });
-    const pools = resolvePools(resolved.pools, registry);
+    const members = memberContext(resolved.auth, resolved.agents);
+    const maintainers = resolveMaintainers(input.maintainers, resolved.auth.some((provider) => !assertsAgents(provider)), members);
+    const pools = resolvePools(resolved.pools, resolved.readOnly, registry, members);
     warnInsecureConfig(resolved);
     const requestAdmission = new AdmissionController(resolved.admission.requests);
     let codeAdmission;
@@ -213,6 +230,8 @@ export function createConnecta(config) {
         registry,
         raw: input,
         config: resolved,
+        maintainers,
+        pools,
         executorName: configuredExecutorName,
         executorAdmits,
     });
@@ -221,6 +240,7 @@ export function createConnecta(config) {
         configDescription: description,
         configValueSources: describeConfigSources(description, input),
         registry,
+        maintainers,
         pools,
         executor,
         executorName: configuredExecutorName,

package/dist/invocation.js

@@ -1,8 +1,9 @@
 import { withAuthorizationHandoff } from "./authorization-handoff.js";
 import { hasControlCharacters } from "./tool-name.js";
-import { surfaceAllowsTool } from "./tool-safety.js";
+import { writeRefusal } from "./tool-safety.js";
 import { Cause, Effect, Exit } from "effect";
 import { isCallAdmissionError } from "./call-admission.js";
+import { attachCallAdmission } from "./call-admission-context.js";
 import { boundedEchoText, classificationCode, classifyCallError, ConnectorCallError, echoedCallArgs, framingError, } from "./errors.js";
 import { downstreamValue } from "./mcp-result.js";
 import { carryFailureFacts, classifiedFailure, failureRecord, logFailure, recordedToolName, } from "./operator-record.js";
@@ -389,7 +390,7 @@ export class InvocationService {
                 // Activity rows and this log line are both payload-free by
                 // construction: the line is the failure's typed record, never its
                 // message, which may be the downstream's own words (INV-6).
-                if (target && details.code !== "destructive_tool_requires_approval") {
+                if (target && details.code !== "destructive_tool_requires_approval" && details.code !== "read_only_endpoint") {
                     logFailure(this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope).logger, "call failed", failureRecord({
                         connector: target.connector.id,
                         // Named only when the catalog listed it (src/operator-record.ts).
@@ -463,8 +464,11 @@ export class InvocationService {
                         reconciliationRequired: true,
                     };
                 }
-                if (!surfaceAllowsTool(target.definition.classification, context.source, context.trust)) {
-                    const canonicalAddress = `${target.connector.id}.${target.toolName}`;
+                const refusal = writeRefusal(target.definition.classification, context.source, context.readOnly);
+                if (refusal === "read_only_endpoint") {
+                    return framingError("read_only_endpoint", `Tool "${canonicalAddress}" is a write, and this endpoint is read-only. Nothing here can send it.`);
+                }
+                if (refusal === "destructive_tool_requires_approval") {
                     return framingError("destructive_tool_requires_approval", `Tool "${canonicalAddress}" is a write. Invoke it through call_destructive_tool so the MCP host can request approval.`);
                 }
                 // Remote MCP tools advertise their input schema in the catalog. Validate
@@ -491,8 +495,9 @@ export class InvocationService {
                 if (callSignal?.aborted)
                     return yield* Effect.fail(callSignal.reason);
                 attempts = 1;
-                const call = async () => {
+                const call = async (permit) => {
                     const connectorContext = this.registry.contextFor(target.connector.id, this.catalog.baseUrl, this.catalog.requestScope, defined({ signal: callSignal, timeoutMs: context.timeoutMs, defer: this.catalog.defer }));
+                    attachCallAdmission(connectorContext, permit);
                     trackCredentialReads(connectorContext);
                     sentSecrets.include(sentSecretsFor(connectorContext));
                     dispatchContext = connectorContext;
@@ -534,14 +539,14 @@ export class InvocationService {
                 // cannot hold its permit past the deadline.
                 const attempt = yield* Effect.exit(Effect.scoped(Effect.gen({ self: this }, function* () {
                     stage = "admission";
-                    yield* timed((elapsed) => {
+                    const permit = yield* timed((elapsed) => {
                         admissionMs += elapsed;
                     }, admitted(this.registry, target, args, admissionSignal));
                     stage = "downstream";
                     const reply = yield* timed((elapsed) => {
                         connectorMs += elapsed;
                     }, Effect.tryPromise({
-                        try: () => Promise.resolve(call()),
+                        try: () => Promise.resolve(call(permit)),
                         catch: (error) => error,
                     }));
                     if (target.connector.kind === "mcp" && isDownstreamInputResult(reply)) {

package/dist/membership.d.ts

@@ -0,0 +1,51 @@
+import type { ConnectorAccess } from "./connector-access.js";
+import type { AuthenticatedIdentity, IdentityReference, InboundAuth } from "./types.js";
+/**
+ * A person or an agent, as deployment code lists it: a bare principal id in
+ * the namespace of the deployment's one interactive auth provider,
+ * `{ namespace, id }` when that is ambiguous or the id contains `:`, or
+ * `"agent:<name>"` for an agent declared in `agents`.
+ */
+export type MemberRef = string | Readonly<IdentityReference>;
+/** A resolved member reference. Humans match by principal, agents by name. */
+export type Member = {
+    kind: "human";
+    namespace: string;
+    id: string;
+} | {
+    kind: "agent";
+    name: string;
+};
+/** A declared pool after construction-time validation. */
+export interface ResolvedPool {
+    /** Resolved: the pool's own `readOnly`, else the deployment's. */
+    readOnly: boolean;
+    /** Exactly the pool's `tools`; nothing intersects or widens it. */
+    access: ConnectorAccess;
+    members: readonly Member[];
+    /** Trimmed `owner`: the Workspace address agents in this pool act as. */
+    owner?: string;
+}
+/** What resolving a reference needs to know about the deployment. */
+export interface MemberContext {
+    /** `activityActorNamespace` of each interactive provider, `undefined` where it has none. */
+    interactiveNamespaces: ReadonlyArray<string | undefined>;
+    agents: readonly string[];
+}
+/** The namespaces bare ids may resolve in, read from the resolved providers. */
+export declare function memberContext(auth: readonly InboundAuth[], agents: readonly string[]): MemberContext;
+/**
+ * Resolve one list of references, throwing on any that is malformed,
+ * ambiguous, unknown, or repeated (INV-11).
+ */
+export declare function resolveMembers(value: unknown, path: string, context: MemberContext): Member[];
+/**
+ * `maintainers`: people only. Required whenever an inbound provider can admit
+ * a person, which is any provider but the built-in agent-token adapter. With
+ * agents alone nobody can be a maintainer, so plain `/mcp` admits nobody.
+ */
+export declare function resolveMaintainers(value: unknown, admitsPeople: boolean, context: MemberContext): readonly IdentityReference[];
+/** Whether an admitted identity is this member. An agent never matches a person. */
+export declare function isMember(member: Member, identity: Readonly<AuthenticatedIdentity>): boolean;
+/** Whether an admitted identity is a listed maintainer. */
+export declare function isMaintainer(maintainers: readonly IdentityReference[], identity: Readonly<AuthenticatedIdentity>): boolean;

package/dist/membership.js

@@ -0,0 +1,121 @@
+// Who may open which endpoint (#837, decisions/0006): `maintainers` open plain
+// `/mcp`, and each pool's static `members` open `/mcp/<pool>`. References are
+// resolved once at construction; a request is matched against them and never
+// names its own scope (INV-4). Pure, so core reads it without any auth module.
+import { isAgentName } from "./agent-identity.js";
+import { ConfigError } from "./config-schema.js";
+import { validIdentityReference } from "./identity.js";
+const AGENT_PREFIX = "agent:";
+/** The namespaces bare ids may resolve in, read from the resolved providers. */
+export function memberContext(auth, agents) {
+    return {
+        interactiveNamespaces: auth
+            .filter((provider) => provider.interactiveOperator === true)
+            .map((provider) => typeof provider.activityActorNamespace === "string" &&
+            validIdentityReference({ namespace: provider.activityActorNamespace, id: "x" })
+            ? provider.activityActorNamespace
+            : undefined),
+        agents,
+    };
+}
+function resolveRef(value, path, context) {
+    if (typeof value === "string") {
+        if (value.startsWith(AGENT_PREFIX)) {
+            const name = value.slice(AGENT_PREFIX.length);
+            if (!isAgentName(name) || !context.agents.includes(name)) {
+                throw new ConfigError(`${path} names agent "${name}", which ConnectaConfig.agents does not declare.`);
+            }
+            return { kind: "agent", name };
+        }
+        if (value.includes(":")) {
+            throw new ConfigError(`${path} contains ":". Write a principal whose id contains ":" as { namespace, id }; ` +
+                'agents are "agent:<name>".');
+        }
+        if (!validIdentityReference({ namespace: "x", id: value })) {
+            throw new ConfigError(`${path} must be a principal id of 1 to 256 printable, non-space ASCII characters.`);
+        }
+        const namespaces = context.interactiveNamespaces;
+        if (namespaces.length !== 1) {
+            throw new ConfigError(`${path} is a bare principal id, which resolves only when exactly one interactive auth provider is ` +
+                `configured (found ${namespaces.length}). Write it as { namespace, id }.`);
+        }
+        const namespace = namespaces[0];
+        if (namespace === undefined) {
+            throw new ConfigError(`${path} is a bare principal id, but the interactive auth provider declares no activityActorNamespace. ` +
+                "Write it as { namespace, id }.");
+        }
+        return { kind: "human", namespace, id: value };
+    }
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        Object.keys(value).length !== 2 ||
+        !Object.hasOwn(value, "namespace") ||
+        !Object.hasOwn(value, "id")) {
+        throw new ConfigError(`${path} must be a principal id string, { namespace, id }, or "agent:<name>".`);
+    }
+    const { namespace, id } = value;
+    if (typeof namespace !== "string" || typeof id !== "string" || !validIdentityReference({ namespace, id })) {
+        throw new ConfigError(`${path} must have a namespace and id of 1 to 256 printable, non-space ASCII characters each.`);
+    }
+    return { kind: "human", namespace, id };
+}
+const memberKey = (member) => member.kind === "agent" ? `agent\0${member.name}` : `human\0${member.namespace}\0${member.id}`;
+/**
+ * Resolve one list of references, throwing on any that is malformed,
+ * ambiguous, unknown, or repeated (INV-11).
+ */
+export function resolveMembers(value, path, context) {
+    if (!Array.isArray(value)) {
+        throw new ConfigError(`${path} must be an array of principal ids, { namespace, id }, or "agent:<name>".`);
+    }
+    const seen = new Set();
+    return value.map((entry, index) => {
+        const member = resolveRef(entry, `${path}[${index}]`, context);
+        const key = memberKey(member);
+        if (seen.has(key))
+            throw new ConfigError(`${path}[${index}] repeats an earlier member.`);
+        seen.add(key);
+        return Object.freeze(member);
+    });
+}
+/**
+ * `maintainers`: people only. Required whenever an inbound provider can admit
+ * a person, which is any provider but the built-in agent-token adapter. With
+ * agents alone nobody can be a maintainer, so plain `/mcp` admits nobody.
+ */
+export function resolveMaintainers(value, admitsPeople, context) {
+    const path = "ConnectaConfig.maintainers";
+    if (value === undefined || (Array.isArray(value) && value.length === 0)) {
+        if (admitsPeople) {
+            throw new ConfigError(`${path} is required with inbound auth: list the people who may use plain /mcp, administer shared ` +
+                "credentials, manage agent tokens, and read activity.");
+        }
+        return Object.freeze([]);
+    }
+    if (!admitsPeople) {
+        throw new ConfigError(`${path} needs an inbound auth provider that admits people, such as clerkAuth or cloudflareAccessAuth. ` +
+            "Without one no maintainer can be admitted; agents are never maintainers.");
+    }
+    const members = resolveMembers(value, path, context);
+    return Object.freeze(members.map((member, index) => {
+        if (member.kind === "agent") {
+            throw new ConfigError(`${path}[${index}] is an agent. Agents are never maintainers; add them to a pool's members.`);
+        }
+        return Object.freeze({ namespace: member.namespace, id: member.id });
+    }));
+}
+/** Whether an admitted identity is this member. An agent never matches a person. */
+export function isMember(member, identity) {
+    if (member.kind === "agent")
+        return identity.agent !== undefined && identity.agent === member.name;
+    const principal = identity.principal;
+    return (identity.agent === undefined &&
+        principal !== undefined &&
+        principal.namespace === member.namespace &&
+        principal.id === member.id);
+}
+/** Whether an admitted identity is a listed maintainer. */
+export function isMaintainer(maintainers, identity) {
+    return maintainers.some((maintainer) => isMember({ kind: "human", ...maintainer }, identity));
+}