@zackbart/connecta 0.32.0 → 0.34.0

package/dist/connector-caller.d.ts

@@ -9,8 +9,14 @@ export interface ConnectorCaller {
      * with or without a subject, a Connecta-issued access token.
      */
     authenticated: boolean;
-    /** The `/mcp/<pool>` the call arrived on, when it was a pool. */
+    /** The pool the call arrived on, at `/mcp/<pool>` or `/agent/<pool>`. */
     pool?: string;
+    /**
+     * That pool's configured `owner`, the Workspace address an agent acts as
+     * (decisions/0006). Core copies it from the admitted pool's config; no
+     * request can set it, and humans never act as it.
+     */
+    poolOwner?: string;
 }
 export declare function attachCaller(ctx: ConnectorContext, caller: ConnectorCaller | undefined): ConnectorContext;
 export declare function callerOf(ctx: ConnectorContext): ConnectorCaller | undefined;

package/dist/connector-caller.js

@@ -8,8 +8,10 @@
 // - maintained providers that act *as* the caller downstream — Google
 //   Workspace through domain-wide delegation (`src/providers/_shared/google/`) — which
 //   hand the identity to a deployment-config function that names the
-//   downstream subject (PRINCIPLES.md INV-3, #678). The
-//   provider never decides whose account to open; config does, from this.
+//   downstream subject (PRINCIPLES.md INV-3, #678), or, for an agent, use the
+//   admitted pool's configured owner (decisions/0006), and the scoped registry
+//   view hides the connector from an agent whose pool has none. The provider never
+//   decides whose account to open; config does, from this.
 //
 // Core sets it from the authorization that admitted the request, on the scoped
 // registry view that request receives, and `api()` hands handlers that same

package/dist/connectors/api-connector.d.ts

@@ -146,10 +146,33 @@ export interface ApiOptions {
 /** The closed options api() accepts; see `assertKnownOptions`. */
 export declare const API_OPTIONS: import("../config-schema.js").Field<unknown, unknown, true> & {
     readonly shape: {
-        callAdmission: import("../config-schema.js").Field<unknown, unknown, true> & {
-            readonly shape: {
-                rules: import("../config-schema.js").Field<unknown[], readonly unknown[] | undefined, true>;
-                maxPartitions: import("../config-schema.js").Field<unknown, unknown, true>;
+        callAdmission: Omit<import("../config-schema.js").Field<unknown, ConnectorCallAdmissionPolicy | undefined, true>, "parse"> & {
+            parse(value: unknown, path: string): ConnectorCallAdmissionPolicy;
+            readonly shape: import("../config-schema.js").Shape & {
+                maxPartitions: import("../config-schema.js").Field<number, number | undefined, true>;
+                rules: import("../config-schema.js").Field<{
+                    maxConcurrency?: number | undefined;
+                    maxQueueSize?: number | undefined;
+                    queueTimeoutMs?: number | undefined;
+                    retryAfterMs?: number | undefined;
+                    partitionKey?: ((input: Readonly<import("../types.js").ConnectorCallAdmissionInput>) => string) | undefined;
+                    budget?: {
+                        kind: "rolling-window";
+                        maxCalls: number;
+                        windowMs: number;
+                    } | undefined;
+                }[], readonly {
+                    readonly maxConcurrency: number | undefined;
+                    readonly maxQueueSize: number | undefined;
+                    readonly queueTimeoutMs: number | undefined;
+                    readonly retryAfterMs: number | undefined;
+                    readonly partitionKey: ((input: Readonly<import("../types.js").ConnectorCallAdmissionInput>) => string) | undefined;
+                    readonly budget: {
+                        readonly kind: "rolling-window";
+                        readonly maxCalls: number;
+                        readonly windowMs: number;
+                    } | undefined;
+                }[], false>;
             };
         };
         usageGuide: import("../config-schema.js").Field<unknown, unknown, true> & {

package/dist/connectors/api-connector.js

@@ -90,6 +90,8 @@ function describedApiAuth(opts) {
  */
 export function apiConnector(id, opts, oauth) {
     opts = assertKnownOptions(opts, `api(${JSON.stringify(id)})`, API_OPTIONS);
+    if (opts.callAdmission !== undefined)
+        CALL_ADMISSION.parse(opts.callAdmission, `api(${JSON.stringify(id)}).callAdmission`);
     assertStaticToolNames(opts.tools, `api(${JSON.stringify(id)}).tools`);
     if (opts.oauth !== undefined && oauth === undefined) {
         throw new Error(`api() connector "${id}" declares oauth but was built without its grant; construct it with api().`);

package/dist/connectors/remote-mcp.js

@@ -1024,6 +1024,8 @@ function registrationErrorCode(body) {
  */
 export function remoteMcp(id, opts) {
     opts = assertKnownOptions(opts, `remoteMcp(${JSON.stringify(id)})`, REMOTE_MCP_OPTIONS);
+    if (opts.callAdmission !== undefined)
+        CALL_ADMISSION.parse(opts.callAdmission, `remoteMcp(${JSON.stringify(id)}).callAdmission`);
     const skillsEnabled = opts.skills;
     if (skillsEnabled !== undefined && typeof skillsEnabled !== "boolean") {
         throw new Error(`[connecta] connector "${id}" skills must be a boolean.`);

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;
@@ -88,8 +98,11 @@ export interface ConnectaConfigDescription {
     };
     /** Whether the default /mcp endpoint refuses every write, and exact classification overrides from deployment code. */
     readOnly: boolean;
-    /** Whether deployment code configures a grant for plain `/mcp`. */
-    hasGrant: 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<{
@@ -97,14 +110,22 @@ export interface ConnectaConfigDescription {
         interactive: boolean;
         ui?: string;
     }>;
-    identity: Record<"connectorAccess" | "activityAccess" | "credentialAdministration" | "accessTokenManagement" | "personalConnection", "default" | "custom">;
-    /** `readOnly` is resolved: the pool's own value, else the deployment's. */
+    /** 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. `description` is the trimmed
+     * text the pool's endpoints add to their MCP instructions, or null.
+     */
     pools: Array<{
         name: string;
         path: string;
         tools: string[];
-        hasGrant: boolean;
+        members: DescribedMember[];
         readOnly: boolean;
+        owner: string | null;
+        description: string | null;
     }>;
     modules: {
         ui: {
@@ -125,7 +146,6 @@ export interface ConnectaConfigDescription {
         };
         accessTokens: {
             enabled: boolean;
-            maxActive?: number;
         };
     };
     /** Every accepted store implements `list` and `compareAndSet`, so only its kind is told. */
@@ -157,6 +177,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;
@@ -241,20 +233,24 @@ export function describeConfig(input) {
             requests: limitGroup(config.admission.requests, ownValue(ownValue(raw, "admission"), "requests"), Object.keys(D.admission.requests)),
         },
         readOnly: config.readOnly,
-        hasGrant: typeof config.grant === "function",
+        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]) => ({
             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,
+            description: input.pools.get(name)?.description ?? null,
         })),
         modules: {
             ui: { enabled: config.ui !== undefined },
@@ -277,12 +273,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/execute.js

@@ -798,18 +798,8 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 ...args,
                 includeSchemas: args.includeSchemas ?? "json",
                 includeSchemaKeys: args.includeSchemaKeys !== false,
-            }));
+            }, catalogDependency));
             boundedDiscoveryText(result, "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.");
-            for (const tool of result.tools)
-                catalogAddressDependency(tool.address);
-            for (const error of result.catalogErrors)
-                catalogDependency(error.connector);
-            for (const connector of result.absence?.configuredConnectors ?? [])
-                catalogDependency(connector);
-            for (const connector of result.queryAnalysis?.configuredConnectors ?? [])
-                catalogDependency(connector);
-            if (result.queryAnalysis?.connectorScope)
-                catalogDependency(result.queryAnalysis.connectorScope);
             return result;
         }),
         describe: (raw) => discovery("describe", async () => {

package/dist/fix-prompt.js

@@ -29,7 +29,7 @@ export function renderFixPrompt(spec, connectorId) {
             "own logs (lines prefixed [connecta]) or by reproducing the failure locally. Never put a secret in source, " +
             "a log line, or your reply: secrets belong in the deployment's environment or its credential vault.",
         "Make the smallest change that fixes it, then verify it by redeploying and refreshing the connection on the " +
-            "operator Connections page. If the fix needs something you cannot do yourself — a provider console setting, " +
-            "a secret only the operator holds — name that exact step instead.",
+            "operator Connectors page. If the fix needs a step you cannot do yourself, such as a provider console setting " +
+            "or a secret only the operator holds, name that exact step instead.",
     ].join("\n\n");
 }

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, readOnly, 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,8 +57,18 @@ function resolvePools(pools, readOnly, registry) {
                 }
             }
         }
+        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, { access, readOnly: pool.readOnly ?? readOnly, grant: pool.grant ?? (() => false) });
+        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() } : {}),
+            ...(pool.description !== undefined ? { description: pool.description.trim() } : {}),
+        }));
     }
     return resolved;
 }
@@ -191,7 +206,9 @@ export function createConnecta(config) {
         results: resolved.results,
         classification: resolved.classification,
     });
-    const pools = resolvePools(resolved.pools, resolved.readOnly, 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;
@@ -214,6 +231,8 @@ export function createConnecta(config) {
         registry,
         raw: input,
         config: resolved,
+        maintainers,
+        pools,
         executorName: configuredExecutorName,
         executorAdmits,
     });
@@ -222,6 +241,7 @@ export function createConnecta(config) {
         configDescription: description,
         configValueSources: describeConfigSources(description, input),
         registry,
+        maintainers,
         pools,
         executor,
         executorName: configuredExecutorName,

package/dist/invocation.js

@@ -3,6 +3,7 @@ import { hasControlCharacters } from "./tool-name.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";
@@ -494,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;
@@ -537,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,53 @@
+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;
+    /** Trimmed `description`, appended to this pool's MCP instructions. */
+    description?: 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));
+}

package/dist/module-contracts.d.ts

@@ -17,13 +17,30 @@ export interface ActivityModule {
     readonly recordTool: typeof recordToolActivity;
     readonly recordChange: typeof recordCatalogChangeActivity;
 }
-/** Optional client-token authentication and operator lifecycle. */
+/** Optional agent-token authentication and operator lifecycle. */
 export interface AccessTokensModule {
     readonly auth: import("./types.js").InboundAuth;
     handle(context: RouteContext): Promise<Response | null>;
-    /** Token policy for `describeConfig()`; never token material. */
-    describe?(): {
-        maxActive: number;
-        optionSources?: Readonly<Record<string, "default" | "config">>;
-    };
+    /**
+     * Every declared agent's token slot, in declaration order: the list GET
+     * /ui/access-tokens serves, which the maintainer's operator contract
+     * repeats field by field. Never secret material.
+     */
+    slots(): Promise<Array<{
+        name: string;
+        state: "none";
+        revision: string;
+    } | {
+        name: string;
+        state: "issued";
+        issuedAt: string;
+        revision: string;
+    } | {
+        name: string;
+        state: "revoked";
+        revokedAt: string;
+        revision: string;
+    }>>;
+    /** The same module bound to the deployment's declared `agents`; createConnecta calls it once. */
+    forAgents(agents: readonly string[]): AccessTokensModule;
 }