@zackbart/connecta 0.31.0 → 0.33.0

package/dist/meta-tools.js

@@ -210,12 +210,6 @@ async function stashResult(bytes, results, preview, rawText) {
             totalBytes,
             hint: `${results.write ? WRITE_ALREADY_RAN + " " : ""}Paging is unavailable: text contains unpaired surrogates and can't be paged as text; request the value as JSON (value mode or a JSON-returning call) to recover it.`,
         };
-    if (!results.pageable)
-        return {
-            truncated: true,
-            totalBytes,
-            hint: `${WRITE_ALREADY_RAN} Paging is unavailable for write results on read-only pools.`,
-        };
     const id = crypto.randomUUID();
     try {
         // Base64 permits byte-range decoding, and splitting the envelope across
@@ -270,7 +264,7 @@ async function stashResult(bytes, results, preview, rawText) {
     };
 }
 /** Program calls use the direct-call envelope, ledger, expiry and authority. */
-export async function pageProgramResult(registry, baseUrl, resolved, value, format, secrets, trust, requestScope, wireBytes = PROGRAM_RESULT_WIRE_BYTES) {
+export async function pageProgramResult(registry, baseUrl, resolved, value, format, secrets, requestScope, wireBytes = PROGRAM_RESULT_WIRE_BYTES) {
     const data = secrets.redact(value);
     const wire = JSON.stringify({ data, format });
     if (enc.encode(wire).length <= wireBytes)
@@ -279,7 +273,6 @@ export async function pageProgramResult(registry, baseUrl, resolved, value, form
     const bytes = enc.encode(text);
     const write = resolved.definition.classification !== "read";
     const notice = await stashResult(bytes, {
-        pageable: !write || trust === "trusted",
         binding: {
             identity: registry.resultIdentity(),
             baseUrl,
@@ -304,7 +297,7 @@ export async function pageProgramResult(registry, baseUrl, resolved, value, form
     };
 }
 /** Program returns share the direct stash, with all host-admitted call dependencies. */
-export async function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, trust, logger, maxChars, completedWrite) {
+export async function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, logger, maxChars, completedWrite) {
     const serialized = serializeResultText(value);
     if (serialized.length <= maxChars)
         return value;
@@ -314,7 +307,6 @@ export async function guardProgramReturn(value, registry, baseUrl, dependencies,
     const cap = Math.min(registry.maxResultBytes, ...dependencies.map((dependency) => resolveMaxResultBytes(registry.getConnector(dependency.connector)?.maxResultBytes, registry.maxResultBytes)));
     const results = {
         secrets,
-        pageable: !write || trust === "trusted",
         binding: {
             identity: registry.resultIdentity(),
             baseUrl,
@@ -522,6 +514,8 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     });
     const catalog = new CatalogService(registry, baseUrl, {
         requestScope,
+        // search_tools never shows a read-only endpoint's writes.
+        readOnly: opts.readOnly,
         probeTimeoutMs,
         concurrency: discoveryConcurrency,
         defer: opts.defer,
@@ -536,6 +530,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
         const outcome = await invocation.invoke(call.address, call.args ?? {}, {
             source,
             sentSecrets,
+            readOnly: opts.readOnly,
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
             ...(opts.requestSignal !== undefined ? { requestSignal: opts.requestSignal } : {}),
             unwrapResult: call.resultMode === "value",
@@ -557,7 +552,6 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 const cap = resolveMaxResultBytes(resolved.connector.maxResultBytes, globalCap);
                 const results = {
                     secrets,
-                    pageable: resolved.definition.classification === "read" || opts.trust === "trusted",
                     binding: {
                         identity: registry.resultIdentity(),
                         baseUrl,
@@ -788,7 +782,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     if (binding.program &&
                         !(await registry.recheckResultAccess(undefined, binding.classification, options.signal)))
                         return false;
-                    if (binding.classification === "write" && opts.trust !== "trusted")
+                    if (binding.classification === "write" && opts.readOnly === true)
                         return false;
                     const dependencies = binding.program ?? [binding];
                     for (const dependency of dependencies) {
@@ -809,7 +803,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                         if (!tool ||
                             !(dependency.access === "catalog" ||
                                 (dependency.classification === "read" && tool.classification === "read") ||
-                                opts.trust === "trusted"))
+                                opts.readOnly !== true))
                             return false;
                     }
                     return true;
@@ -915,9 +909,11 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
         },
     };
 }
-const SEARCH_DESC = `Use top-level search for catalog inspection or approval-required work before call_destructive_tool. Unknown-address read-only work belongs in one execute_code program that searches, calls, and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds tools that run unasked; "approvalRequired" finds the fail-closed complement. These filters grant no authority. Empty query browses. Returns { catalogErrors, tools, total, offset, limit, hasMore }; read catalogErrors and absence before selecting a tool. Compact schemas have schemaFormat="text".`;
-const CALL_DESC = "Call one known-address tool explicitly annotated readOnlyHint: true. Use execute_code for unknown-address, multiple, dependent, or reduced read-only work. Unannotated or write-capable tools fail closed to call_destructive_tool. A truncated result carries a connecta.result action.";
+const SEARCH_DESC = (readOnly) => `${readOnly ? "Use top-level search for catalog inspection; this read-only endpoint omits write tools." : "Use top-level search for catalog inspection or approval-required work before call_destructive_tool."} Unknown-address read-only work belongs in one execute_code program that searches, calls, and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds tools that run unasked; "approvalRequired" finds the fail-closed complement. These filters grant no authority. Empty query browses. Returns { catalogErrors, tools, total, offset, limit, hasMore }; read catalogErrors and absence before selecting a tool. Compact schemas have schemaFormat="text".`;
+const CALL_DESC = (readOnly) => `Call one known-address tool explicitly annotated readOnlyHint: true. Use execute_code for unknown-address, multiple, dependent, or reduced read-only work. ${readOnly ? "This endpoint is read-only and refuses every write." : "Unannotated or write-capable tools fail closed to call_destructive_tool."} A truncated result carries a connecta.result action.`;
 const CALL_DESTRUCTIVE_DESC = "Call any tool not explicitly annotated readOnlyHint: true. Include a short reason for the human reviewer after checking the schema and consequences. The reason grants no authority and is not sent downstream.";
+/** A read-only endpoint keeps the six-tool surface, so this tool says why it never writes here. */
+const CALL_DESTRUCTIVE_READ_ONLY_DESC = "This endpoint is read-only: search and describe omit write tools, and every write call here is refused. Reads still run; prefer call_tool or execute_code for them.";
 const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or reports required deployment configuration. force=true requests an OAuth restart when the verified user opens the /connect URL; this tool never accepts credentials.";
 const SKILLS_DESC = "List or fetch on-demand guidance. Fetch usage only when the always-loaded instructions are insufficient or a program needs repair.";
 /**
@@ -1001,7 +997,7 @@ export function registerMetaTools(server, registry, ctx) {
     const mt = createMetaTools(registry, ctx.baseUrl, {
         downstreamInput: Boolean(ctx.authElicitation),
         requestScope: ctx.requestScope,
-        trust: ctx.trust,
+        readOnly: ctx.readOnly,
         defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
         probeTimeoutMs: ctx.probeTimeoutMs,
         discoveryConcurrency: ctx.discoveryConcurrency,
@@ -1028,7 +1024,7 @@ export function registerMetaTools(server, registry, ctx) {
         return mt.skills(args);
     });
     server.registerTool("search_tools", {
-        description: describedFor(registry, SEARCH_DESC, "search"),
+        description: describedFor(registry, SEARCH_DESC(ctx.readOnly === true), "search"),
         inputSchema: SEARCH_INPUT,
         outputSchema: SEARCH_OUTPUT,
         annotations: READ_ONLY_REMOTE,
@@ -1037,7 +1033,7 @@ export function registerMetaTools(server, registry, ctx) {
         return mt.searchTools(args);
     });
     server.registerTool("call_tool", {
-        description: CALL_DESC,
+        description: CALL_DESC(ctx.readOnly === true),
         inputSchema: CALL_INPUT,
         // Default mode returns native content, so no structured result is promised.
         // call_tool admits only tools that are themselves explicitly read-only;
@@ -1050,7 +1046,9 @@ export function registerMetaTools(server, registry, ctx) {
             : mt.callTool(args);
     });
     server.registerTool("call_destructive_tool", {
-        description: describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),
+        description: ctx.readOnly === true
+            ? CALL_DESTRUCTIVE_READ_ONLY_DESC
+            : describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),
         inputSchema: CALL_DESTRUCTIVE_INPUT,
         annotations: {
             destructiveHint: true,

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" | "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 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,9 +112,9 @@ const AUTH_DENIAL_REASONS = new Set([
     "email_domain_denied",
     "gate_denied",
     "gate_failed",
+    "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.`);
+}

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

@@ -2,7 +2,7 @@ import type { ActivityOutcome } from "../activity.js";
 import type { ConnectaConfigDescription } from "../describe-config.js";
 import type { ConnectorStatus, ConnectorToolDescription } from "../types.js";
 import type { UiProblem } from "./model.js";
-/** The registry's final verdict, independent of the viewer's pool trust. */
+/** The registry's final verdict, independent of whether the viewer's endpoint is read-only. */
 export interface OperatorTool extends ConnectorToolDescription {
     address: string;
     classification: "read" | "write";
@@ -25,7 +25,7 @@ export interface OperatorConnectorOverlay {
     /** Latest visible call in the bounded activity window, or null when unknown. */
     lastCall: OperatorLastCall | null;
 }
-/** Whole connector access, or exact tool grants. Guarded grants still require a live read verdict. */
+/** Whole connector access, or exact tool grants. `requireReadOnly` is always false since guarded grants were removed (#837). */
 export interface OperatorGrant {
     connectorId: string;
     tools: "all" | Array<{
@@ -33,40 +33,162 @@ export interface OperatorGrant {
         requireReadOnly: boolean;
     }>;
 }
-export interface OperatorPool {
+export type OperatorRole = "maintainer" | "member";
+export type OperatorMember = {
+    kind: "human";
+    namespace: string;
+    id: string;
+    label: string | null;
+} | {
+    kind: "agent";
+    name: string;
+};
+export interface OperatorPoolV2 {
     name: string;
+    /** `/mcp/<name>`. */
+    humanPath: string;
+    /** `/agent/<name>`. */
+    agentPath: string;
+    readOnly: boolean;
+    /** Workspace address agents act as; null in the member view. */
+    owner: string | null;
+    /** The pool's declared tools, unfiltered. */
+    tools: OperatorGrant[];
+    /** Maintainer view only; [] for members. */
+    members: OperatorMember[];
+}
+/** Plain /mcp. Maintainer view only; null for members. */
+export interface OperatorRootEndpoint {
+    /** `/mcp`. */
     path: string;
-    trust: "trusted" | "read-only";
-    /** Pool access intersected with the caller's grants. */
-    grants: OperatorGrant[];
+    readOnly: boolean;
+    /** Humans only. */
+    maintainers: OperatorMember[];
+}
+/** What a member may see about one connector in their pools. */
+export interface OperatorMemberConnector {
+    id: string;
+    title: string;
+    pools: string[];
+    authScope: "shared" | "personal";
+    /** Tools their pools grant. */
+    tools: Array<{
+        address: string;
+        classification: "read" | "write";
+    }>;
+    /** Own connection state for personal connectors; null for shared ones. */
+    connection: {
+        state: ConnectorStatus["state"];
+        problem?: UiProblem;
+    } | null;
+    /** What the member may do. Always "none" for shared connectors. */
+    manage: OperatorMemberManage;
 }
-export interface OperatorViewer {
-    interactive: boolean;
-    grants: OperatorGrant[];
-    /** Trust of the root /mcp endpoint. */
-    trust: "trusted" | "read-only";
-    pools: OperatorPool[];
-    permissions: {
-        activity: boolean;
-        accessTokenManagement: boolean;
-        connectors: Array<{
-            id: string;
-            use: boolean;
-            manageSharedAuth: boolean;
-            connectPersonal: boolean;
-        }>;
+export type OperatorMemberManage = {
+    kind: "none";
+} | {
+    kind: "oauth";
+    actions: Array<"connect" | "restart" | "disconnect">;
+} | {
+    /** /ui/credentials/<id>, the member's own partition. */
+    kind: "credential";
+    label: string;
+    description?: string;
+    /** Labels and names, never values. */
+    fields?: Array<{
+        name: string;
+        label: string;
+        description?: string;
+    }>;
+    actions: Array<"save" | "test" | "clear">;
+};
+export interface OperatorAgent {
+    name: string;
+    pools: string[];
+    /**
+     * The agent's token slot. `revision` is the same opaque value GET
+     * /ui/access-tokens lists for the slot, on every state including "none":
+     * it changes on every commit to the slot, and a token mutation sends it as
+     * `expect`, so one decided from a stale view refuses with 409 `slot_changed`.
+     */
+    token: {
+        state: "none";
+        revision: string;
+    } | {
+        state: "issued";
+        issuedAt: string;
+        revision: string;
+    } | {
+        state: "revoked";
+        revokedAt: string;
+        revision: string;
     };
+    /** Latest activity row for this agent, null when activity is off or none is visible. */
+    lastSeenAt: string | null;
 }
-export interface OperatorUiContract {
-    schemaVersion: 1;
-    /** describeConfig's allowlisted snapshot, restricted to this caller's view. */
-    config: ConnectaConfigDescription;
-    /** Leaf provenance, built from the same allowlisted snapshot and scoped with it. */
-    configSources?: Record<string, "default" | "config">;
+/**
+ * Where a shared connector's credential comes from:
+ * - "vault": a declared operator credential slot that holds a saved value;
+ * - "missing": a declared slot, or a shared OAuth connector, with nothing saved yet;
+ * - "oauth": a shared OAuth grant, even when the grant is vault-sealed;
+ * - "config": supplied by deployment code or environment (literal headers, env values,
+ *   request-token callbacks, `api()` handlers that hold their own credentials), never shown;
+ * - "unauthenticated": the connector declares no auth at all.
+ * A token minted per request follows its underlying credential (a GitHub App key from a
+ * slot is "vault", from code is "config"). Absence of a slot alone never means
+ * "unauthenticated": that needs a connector that declares no auth.
+ */
+export type OperatorSharedSource = "vault" | "missing" | "oauth" | "config" | "unauthenticated";
+export type OperatorRunsAs = {
+    kind: "shared";
+    source: OperatorSharedSource;
+    savedAt: string | null;
+} | {
+    kind: "personal";
+    connectedMembers: number;
+    members: number;
+} | {
+    kind: "workspace";
+    humans: "self";
+    agents: string | null;
+} | {
+    kind: "workspaceFixed";
+    subject: string;
+};
+export interface OperatorConnectorPoolCell {
+    connectorId: string;
+    /** Null is plain /mcp. */
+    pool: string | null;
+    /** Connector-relative tool names, as in `OperatorGrant`, not addresses. */
+    tools: "all" | string[];
+    runsAs: OperatorRunsAs;
+}
+export interface OperatorUiContractV2 {
+    schemaVersion: 2;
+    role: OperatorRole;
+    /** Maintainer only; null for members. */
+    config: ConnectaConfigDescription | null;
+    /** Leaf provenance for Settings, as in v1. Maintainer only; null for members. */
+    configSources: Record<string, "default" | "config"> | null;
     live: {
+        /** Maintainer only; [] for members. */
         connectors: OperatorConnectorOverlay[];
-        /** Last-call lookup scans at most 1,000 recent rows. No payload or actor is returned. */
+        /** "forbidden" for members. */
         activity: "available" | "unconfigured" | "forbidden" | "unavailable";
     };
-    you: OperatorViewer;
+    /** Maintainer only. */
+    root: OperatorRootEndpoint | null;
+    /** Maintainer: all; member: their pools, owner null, members []. */
+    pools: OperatorPoolV2[];
+    /** Maintainer only; [] for members. */
+    agents: OperatorAgent[];
+    /** Maintainer only; [] for members. */
+    matrix: OperatorConnectorPoolCell[];
+    /** Member only; [] for maintainers, who read live.connectors. */
+    connectors: OperatorMemberConnector[];
+    you: {
+        interactive: boolean;
+    };
 }
+/** The operator contract `GET /ui/api/config` serves; schema version 1 was removed (#837). */
+export type OperatorUiContract = OperatorUiContractV2;