@zackbart/connecta 0.32.0 → 0.33.0

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,23 @@ 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,
         })),
         modules: {
             ui: { enabled: config.ui !== undefined },
@@ -277,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/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,17 @@ 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() } : {}),
+        }));
     }
     return resolved;
 }
@@ -191,7 +205,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 +230,8 @@ export function createConnecta(config) {
         registry,
         raw: input,
         config: resolved,
+        maintainers,
+        pools,
         executorName: configuredExecutorName,
         executorAdmits,
     });
@@ -222,6 +240,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,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));
+}

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;
 }

package/dist/operator-record.d.ts

@@ -8,7 +8,7 @@ type FailureStep = "MCP handshake" | "tools/list" | "tools/call" | "resources/re
  */
 export declare const OAUTH_ERROR_CODES: ReadonlySet<string>;
 /** Inbound denial facts, never identity text or provider diagnostics. */
-export type AuthDenialReason = "authentication_failed" | "authorization_header_invalid" | "token_type_mismatch" | "oauth_verification_failed" | "oauth_client_not_allowed" | "oauth_binding_mismatch" | "session_origin_mismatch" | "user_missing" | "email_lookup_failed" | "verified_email_invalid" | "email_domain_denied" | "gate_denied" | "gate_failed" | "default_grant_denied" | "default_grant_threw" | "pool_not_declared" | "pool_grant_denied" | "pool_grant_threw";
+export type AuthDenialReason = "authentication_failed" | "authorization_header_invalid" | "token_type_mismatch" | "oauth_verification_failed" | "oauth_client_not_allowed" | "oauth_binding_mismatch" | "session_origin_mismatch" | "user_missing" | "email_lookup_failed" | "verified_email_invalid" | "email_domain_denied" | "gate_denied" | "gate_failed" | "not_maintainer" | "pool_not_declared" | "not_pool_member";
 /**
  * Name `ctor`'s instances `label` in records and fixed text. Call once, at
  * module scope, beside the class. An error whose prototype chain reaches no
@@ -104,7 +104,7 @@ export declare function failureRecord(subject: FailureSubject, failure?: unknown
  * The events an operator log reports failures as. Closed: a new one is a
  * reviewed line here, never a string assembled at the call site.
  */
-export type FailureEvent = "negotiation cache read failed" | "negotiation cache write failed" | "connectorAccess grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP default endpoint request denied" | "MCP pool request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "result paging unavailable" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
+export type FailureEvent = "negotiation cache read failed" | "negotiation cache write failed" | "pool tool grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP default endpoint request denied" | "MCP pool request denied" | "MCP agent endpoint request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "operator agent slots read failed" | "result paging unavailable" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
 /**
  * Log one failure as `[connecta] <event>` and its record. A record
  * `failureRecord` did not build is replaced, whatever its shape, by a fixed

package/dist/operator-record.js

@@ -112,11 +112,9 @@ const AUTH_DENIAL_REASONS = new Set([
     "email_domain_denied",
     "gate_denied",
     "gate_failed",
-    "default_grant_denied",
-    "default_grant_threw",
+    "not_maintainer",
     "pool_not_declared",
-    "pool_grant_denied",
-    "pool_grant_threw",
+    "not_pool_member",
 ]);
 /** The registry's connector id grammar (src/registry.ts). */
 const CONNECTOR_ID_RE = /^[a-z0-9_-]{1,64}$/;

package/dist/operator-ui/agents.d.ts

@@ -0,0 +1,74 @@
+import type { OperatorUiContractV2 } from "./contract.js";
+import { type Notice, type RequestFailureFacts, type Tone } from "./view.js";
+/**
+ * The Tokens page's rows, computed from the slot list and contract v2 alone.
+ * Agents are declared in code: a row's only controls are its token's issue,
+ * rotate and revoke, so nothing here creates, renames or rebinds one.
+ */
+/** One declared agent's token slot, as `GET /ui/access-tokens` returns it. */
+export type AgentSlot = ({
+    name: string;
+    state: "none";
+} | {
+    name: string;
+    state: "issued";
+    issuedAt: string;
+} | {
+    name: string;
+    state: "revoked";
+    revokedAt: string;
+}) & {
+    /**
+     * The route's opaque slot revision; it changes on every slot commit (P3b,
+     * #837). A slot read without one is unresolved and never acted on.
+     */
+    revision?: string;
+};
+/** Issue and rotate are the same request; the slot's state names it. */
+export type SlotAction = "issue" | "rotate" | "revoke";
+export interface AgentRow {
+    name: string;
+    /** Pools it belongs to, from `agents[].pools`; empty when the contract does not list it. */
+    pools: string[];
+    slot: AgentSlot;
+    /**
+     * Whether `slot` comes from the live slot list. Only a live slot can be
+     * acted on: one known only from the contract may be stale, so its controls
+     * are disabled until a refresh lists it.
+     */
+    live: boolean;
+    /** Why its controls are off, or null when they work. */
+    blocked: string | null;
+    /** Its latest activity row; null is "never" (or history that is off). */
+    lastSeenAt: string | null;
+    actions: SlotAction[];
+}
+export declare function slotActions(slot: Pick<AgentSlot, "state">): SlotAction[];
+/**
+ * One agent's slot, resolved once for both what the row shows and what an
+ * action may do. The live slot list is authoritative; the contract's copy is
+ * shown only for an agent the list does not have, and is never acted on.
+ */
+export declare function resolveSlot(contract: OperatorUiContractV2 | null, slots: AgentSlot[], name: string): {
+    slot: AgentSlot;
+    live: boolean;
+} | null;
+/**
+ * One row per declared agent, in the slot list's order, then any agent only
+ * the contract lists. The contract adds pools and last seen.
+ */
+export declare function agentRows(contract: OperatorUiContractV2 | null, slots: AgentSlot[], unresolved?: readonly string[]): AgentRow[];
+export declare function slotBadge(slot: Pick<AgentSlot, "state">): {
+    label: string;
+    tone: Tone;
+};
+/** When the slot last changed, as "Issued <date>" or "Revoked <date>"; a dash when it never has. */
+export declare function slotSince(slot: AgentSlot, format: (value: string) => string): string;
+export declare function lastSeenLabel(lastSeenAt: string | null, format: (value: string) => string): string;
+/**
+ * Why a token operation did not land, in fixed sentences keyed by status.
+ * `outcome_unknown` (503) and `aborted` (499) are failures like any other and
+ * are never retried for the operator: an unknown rotation returned no secret,
+ * and only a new, deliberate rotation produces one.
+ */
+export declare function tokenFailureNotice(action: SlotAction, name: string, facts: RequestFailureFacts, productName: string): Notice;

package/dist/operator-ui/agents.js

@@ -0,0 +1,104 @@
+import { failure } from "./view.js";
+/** Why a row's controls are disabled when its slot is not in the live list. */
+const SLOT_UNAVAILABLE = "Token state unavailable, refresh";
+/** Why a row's controls are disabled until a fresh list read resolves its slot. */
+const SLOT_UNRESOLVED = "Refresh to continue";
+export function slotActions(slot) {
+    return slot.state === "issued" ? ["rotate", "revoke"] : ["issue"];
+}
+function contractSlot(agent) {
+    return { name: agent.name, ...agent.token };
+}
+function maintainerAgents(contract) {
+    return contract?.role === "maintainer" ? contract.agents : [];
+}
+/**
+ * One agent's slot, resolved once for both what the row shows and what an
+ * action may do. The live slot list is authoritative; the contract's copy is
+ * shown only for an agent the list does not have, and is never acted on.
+ */
+export function resolveSlot(contract, slots, name) {
+    const listed = slots.find((slot) => slot.name === name);
+    if (listed)
+        return { slot: listed, live: true };
+    const agent = maintainerAgents(contract).find((candidate) => candidate.name === name);
+    return agent ? { slot: contractSlot(agent), live: false } : null;
+}
+/**
+ * One row per declared agent, in the slot list's order, then any agent only
+ * the contract lists. The contract adds pools and last seen.
+ */
+export function agentRows(contract, slots, unresolved = []) {
+    const agents = maintainerAgents(contract);
+    const declared = new Map(agents.map((agent) => [agent.name, agent]));
+    const names = [...slots.map((slot) => slot.name), ...agents.map((agent) => agent.name)];
+    return [...new Set(names)].map((name) => {
+        const { slot, live } = resolveSlot(contract, slots, name);
+        const agent = declared.get(name);
+        return {
+            name,
+            pools: agent?.pools ?? [],
+            slot,
+            live,
+            blocked: !live ? SLOT_UNAVAILABLE : unresolved.includes(name) || !slot.revision ? SLOT_UNRESOLVED : null,
+            lastSeenAt: agent?.lastSeenAt ?? null,
+            actions: slotActions(slot),
+        };
+    });
+}
+export function slotBadge(slot) {
+    if (slot.state === "issued")
+        return { label: "Issued", tone: "ok" };
+    if (slot.state === "revoked")
+        return { label: "Revoked", tone: "warn" };
+    return { label: "No token", tone: "neutral" };
+}
+/** When the slot last changed, as "Issued <date>" or "Revoked <date>"; a dash when it never has. */
+export function slotSince(slot, format) {
+    if (slot.state === "issued")
+        return `Issued ${format(slot.issuedAt)}`;
+    if (slot.state === "revoked")
+        return `Revoked ${format(slot.revokedAt)}`;
+    return "—";
+}
+export function lastSeenLabel(lastSeenAt, format) {
+    return lastSeenAt ? format(lastSeenAt) : "never";
+}
+/**
+ * Why a token operation did not land, in fixed sentences keyed by status.
+ * `outcome_unknown` (503) and `aborted` (499) are failures like any other and
+ * are never retried for the operator: an unknown rotation returned no secret,
+ * and only a new, deliberate rotation produces one.
+ */
+export function tokenFailureNotice(action, name, facts, productName) {
+    if (facts.kind === "session")
+        return failure("Your session has ended. Sign in again, then retry.");
+    if (facts.kind === "forbidden")
+        return failure("You don't have permission to manage agent tokens.");
+    if (facts.kind === "stale") {
+        return failure(`${name}'s token changed before the request was sent, so nothing was sent. Check it and try again.`);
+    }
+    if (facts.kind === "network") {
+        return failure(`Couldn't reach ${productName}. Refresh to check ${name}'s token before trying again.`);
+    }
+    if (facts.status === 503) {
+        return failure(action === "revoke"
+            ? `Revocation outcome unknown for ${name}: revoke again to be sure its token is stopped.`
+            : `${action === "issue" ? "Issue" : "Rotation"} outcome unknown for ${name}: no secret was returned, so rotate again for a replacement.`);
+    }
+    if (facts.status === 499) {
+        return failure(action === "revoke"
+            ? `The request ended before ${name}'s revocation finished. Refresh to check its token before trying again.`
+            : `The request ended before ${name}'s token was delivered, so no secret was returned. Refresh to check its token before trying again.`);
+    }
+    // The route's compare-and-swap refused it: the slot moved after the list was read.
+    if (facts.status === 409 && facts.code === "slot_changed")
+        return failure("Changed since you looked, refresh.");
+    if (facts.status === 409)
+        return failure(`${name}'s token changed meanwhile. Reload and try again.`);
+    if (facts.status === 404)
+        return failure(`${name} is no longer declared in code. Reload the page.`);
+    return action === "revoke"
+        ? failure(`${name}'s token could not be revoked. Reload and try again.`)
+        : failure(`A token could not be issued for ${name}. Reload and try again.`);
+}