@zackbart/connecta 0.32.0 → 0.33.0

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

@@ -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,41 +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;
-    path: string;
-    /** Whether this pool's endpoint refuses every write. */
+};
+export interface OperatorPoolV2 {
+    name: string;
+    /** `/mcp/<name>`. */
+    humanPath: string;
+    /** `/agent/<name>`. */
+    agentPath: string;
     readOnly: boolean;
-    /** Pool access intersected with the caller's grants. */
-    grants: OperatorGrant[];
+    /** 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[];
 }
-export interface OperatorViewer {
-    interactive: boolean;
-    grants: OperatorGrant[];
-    /** Whether the root /mcp endpoint refuses every write. */
+/** Plain /mcp. Maintainer view only; null for members. */
+export interface OperatorRootEndpoint {
+    /** `/mcp`. */
+    path: string;
     readOnly: boolean;
-    pools: OperatorPool[];
-    permissions: {
-        activity: boolean;
-        accessTokenManagement: boolean;
-        connectors: Array<{
-            id: string;
-            use: boolean;
-            manageSharedAuth: boolean;
-            connectPersonal: 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 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;

package/dist/operator-ui/endpoints.js

@@ -0,0 +1,192 @@
+/** How many chips an endpoint row shows before "+N more". */
+const ACCESS_CHIP_LIMIT = 4;
+function initialsOf(text) {
+    const words = text
+        .replace(/^user_/, "")
+        .split(/[\s._@-]+/)
+        .filter(Boolean);
+    const letters = words.length > 1 ? words[0][0] + words[1][0] : (words[0] ?? text).slice(0, 2);
+    return letters.toUpperCase();
+}
+function hueOf(key) {
+    let hash = 0;
+    for (const char of key)
+        hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
+    return hash % 6;
+}
+/** A member as a chip. Labels are null on Access deployments, where the raw id shows instead. */
+function accessChip(member) {
+    if (member.kind === "agent") {
+        const key = `agent:${member.name}`;
+        return { key, kind: "agent", text: key, initials: "", hue: hueOf(key) };
+    }
+    const key = `${member.namespace}:${member.id}`;
+    const text = member.label ?? member.id;
+    return { key, kind: "human", text, initials: initialsOf(text), hue: hueOf(key) };
+}
+/** Chips for one endpoint in contract order, people first, without repeats. */
+export function accessChips(members) {
+    const unique = new Map();
+    for (const chip of members.map(accessChip))
+        if (!unique.has(chip.key))
+            unique.set(chip.key, chip);
+    const chips = [...unique.values()];
+    return [...chips.filter((chip) => chip.kind === "human"), ...chips.filter((chip) => chip.kind === "agent")];
+}
+/** The chips a collapsed row shows, and how many the "+N more" button holds back. */
+export function visibleChips(chips, expanded) {
+    if (expanded || chips.length <= ACCESS_CHIP_LIMIT)
+        return { shown: chips, hidden: 0 };
+    return { shown: chips.slice(0, ACCESS_CHIP_LIMIT), hidden: chips.length - ACCESS_CHIP_LIMIT };
+}
+/** Matrix cells for one endpoint, keyed by connector id. */
+function cellsFor(contract, pool) {
+    return new Map(contract.matrix.filter((cell) => cell.pool === pool).map((cell) => [cell.connectorId, cell]));
+}
+/** Plain /mcp declares no tool list; its matrix cells are its grants. */
+function rootGrants(contract) {
+    return contract.matrix
+        .filter((cell) => cell.pool === null)
+        .map((cell) => ({
+        connectorId: cell.connectorId,
+        tools: cell.tools === "all" ? "all" : cell.tools.map((name) => ({ name, requireReadOnly: false })),
+    }));
+}
+/** Intersect declared grants with final live verdicts, in config order. */
+function endpointGroups(contract, grants, readOnly, pool) {
+    const cells = cellsFor(contract, pool);
+    return (contract.config?.connectors ?? []).flatMap((config) => {
+        const live = contract.live.connectors.find((c) => c.id === config.id);
+        const grant = grants.find((g) => g.connectorId === config.id);
+        if (!live || !grant)
+            return [];
+        const tools = live.tools.filter((tool) => {
+            if (readOnly && tool.classification !== "read")
+                return false;
+            return (grant.tools === "all" ||
+                grant.tools.some((g) => g.name === tool.name && (!g.requireReadOnly || tool.classification === "read")));
+        });
+        // A granted connector with no complete catalog still needs a visible fix.
+        return [{ config, live, tools, runsAs: cells.get(config.id)?.runsAs ?? null }];
+    });
+}
+const toolCount = (groups) => groups.reduce((n, group) => n + group.tools.length, 0);
+/** One row for plain /mcp, then one per pool, in contract order. Maintainer view only. */
+export function endpointRows(contract) {
+    if (contract.role !== "maintainer")
+        return [];
+    const rows = [];
+    if (contract.root) {
+        const groups = endpointGroups(contract, rootGrants(contract), contract.root.readOnly, null);
+        rows.push({
+            pool: null,
+            label: "Default",
+            path: contract.root.path,
+            agentPath: null,
+            readOnly: contract.root.readOnly,
+            toolCount: toolCount(groups),
+            groups,
+            access: accessChips(contract.root.maintainers),
+        });
+    }
+    for (const pool of contract.pools) {
+        const groups = endpointGroups(contract, pool.tools, pool.readOnly, pool.name);
+        rows.push({
+            pool: pool.name,
+            label: pool.name,
+            path: pool.humanPath,
+            agentPath: pool.members.some((member) => member.kind === "agent") ? pool.agentPath : null,
+            readOnly: pool.readOnly,
+            toolCount: toolCount(groups),
+            groups,
+            access: accessChips(pool.members),
+        });
+    }
+    return rows;
+}
+/** A calendar day, without the time: when a shared credential was saved. */
+function formatDay(value) {
+    const date = new Date(value);
+    return Number.isNaN(date.valueOf()) ? "" : date.toLocaleDateString(undefined, { dateStyle: "medium" });
+}
+/** Where a shared credential lives; a vault or OAuth date when the contract has one. */
+function sharedSourceLabel(source, date) {
+    switch (source) {
+        case "vault":
+            return date ? `saved ${date}` : "saved";
+        case "oauth":
+            return date ? `connected ${date}` : "connected";
+        case "missing":
+            return "not configured";
+        case "config":
+            return "set in deployment";
+        case "unauthenticated":
+            return "no credential needed";
+    }
+}
+/** Whose account a connector acts with on one endpoint, in one line. */
+export function runsAsLabel(runsAs, day = formatDay) {
+    switch (runsAs.kind) {
+        case "shared":
+            return `Shared · ${sharedSourceLabel(runsAs.source, runsAs.savedAt ? day(runsAs.savedAt) : "")}`;
+        case "personal":
+            return `Personal · ${runsAs.connectedMembers} of ${runsAs.members} connected`;
+        case "workspace":
+            return `Workspace · people: self · agents: ${runsAs.agents ?? "none"}`;
+        case "workspaceFixed":
+            return `Everyone acts as ${runsAs.subject}`;
+    }
+}
+export function matrixColumns(contract) {
+    if (contract.role !== "maintainer")
+        return [];
+    return [
+        ...(contract.root ? [{ pool: null, path: contract.root.path, readOnly: contract.root.readOnly }] : []),
+        ...contract.pools.map((pool) => ({ pool: pool.name, path: pool.humanPath, readOnly: pool.readOnly })),
+    ];
+}
+/** What one connector × endpoint cell holds, straight from the contract's matrix. */
+export function matrixCell(contract, connectorId, column) {
+    const cell = contract.matrix.find((c) => c.connectorId === connectorId && c.pool === column.pool);
+    if (!cell)
+        return { kind: "none" };
+    const live = contract.live.connectors.find((c) => c.id === connectorId)?.tools ?? [];
+    const tools = cell.tools === "all"
+        ? live.map(({ name, classification }) => ({ name, classification }))
+        : cell.tools.map((name) => ({ name, classification: live.find((t) => t.name === name)?.classification ?? null }));
+    return { kind: cell.tools === "all" ? "all" : "some", tools, runsAs: cell.runsAs };
+}
+/** The cell's visible text: "all", a count, or a dash. */
+export function matrixCellText(cell) {
+    if (cell.kind === "none")
+        return "—";
+    return cell.kind === "all" ? "all" : String(cell.tools.length);
+}
+/** The cell's accessible name, e.g. "GitHub on /support: 3 tools". */
+export function matrixCellLabel(connector, column, cell) {
+    const where = `${connector} on ${column.path}`;
+    if (cell.kind === "none")
+        return `${where}: no tools`;
+    const what = cell.kind === "all" ? "all tools" : `${cell.tools.length} ${cell.tools.length === 1 ? "tool" : "tools"}`;
+    return `${where}: ${what}${column.readOnly ? ", read-only" : ""}`;
+}
+/** The connector's subject for the matrix's Runs as column: the /mcp cell, else its first pool's. */
+export function connectorRunsAs(contract, connectorId) {
+    const cells = contract.matrix.filter((cell) => cell.connectorId === connectorId);
+    const root = cells.find((cell) => cell.pool === null);
+    if (root)
+        return root.runsAs;
+    for (const pool of contract.pools) {
+        const cell = cells.find((c) => c.pool === pool.name);
+        if (cell)
+            return cell.runsAs;
+    }
+    return null;
+}
+/** Who may use plain /mcp, for Settings: each maintainer by label, else by raw id. */
+export function rootAccessSentence(root) {
+    const names = root.maintainers.map((member) => (member.kind === "human" ? (member.label ?? member.id) : member.name));
+    return names.length
+        ? `Only maintainers can use ${root.path}: ${names.join(", ")}.`
+        : `Only maintainers can use ${root.path}, and none are listed.`;
+}

package/dist/operator-ui/fix-prompts.js

@@ -19,8 +19,8 @@ const CATALOGUE = {
     credential_required: {
         problem: "A connector with an operator-managed credential slot has no usable credential stored.",
         steps: [
-            "An operator with credential administration can add the credential on the operator page; that needs no code change.",
-            "If nobody can, grant credential administration through the deployment's identity config (credentialAdministration for shared auth, personalConnection for personal auth), which is denied by default.",
+            "With a credential vault configured, a maintainer adds a shared credential on the operator page, and a pool member saves their own personal one from their view of it; neither needs a code change. Without a vault, configure one first.",
+            "If nobody can, list the person in the deployment's maintainers for shared auth, or in the members of a pool containing the connector for personal auth.",
             "Check that the connector's credential declaration (label and fields) matches what the downstream actually needs.",
         ],
     },
@@ -57,9 +57,9 @@ const CATALOGUE = {
     oauth_action_failed: {
         problem: "Restarting or disconnecting a connector's downstream OAuth from the operator page failed.",
         steps: [
-            "Check that the connector implements startAuth and disconnectAuth, and that the storage holding its OAuth state is writable.",
+            "Check that the connector implements the hooks the action needs (startAuth, finishAuth, and verifyState to connect; disconnectAuth to disconnect), and that the storage holding its OAuth state is writable.",
             "Check the connector's OAuth client configuration, including the authorization server it discovers or is given.",
-            "Confirm the operator has the config-derived permission for this action (credentialAdministration for shared auth, personalConnection for personal auth).",
+            "Confirm the person is a maintainer for shared auth, or a member of a pool containing the connector for personal auth.",
         ],
     },
     catalog_failed: {