@zackbart/connecta 0.32.0 → 0.34.0

package/dist/operator-ui/connection-map.js

@@ -0,0 +1,375 @@
+import { endpointRows, hueOf, initialsOf } from "./endpoints.js";
+import { connectorVerdict } from "./view.js";
+/* Layout. One coordinate system, scaled by the SVG's viewBox. */
+const MAP_WIDTH = 1000;
+const COLUMN_X = [16, 280, 544];
+const COLUMN_WIDTH = [196, 196, 196];
+/** Each connector's read and write tools sit in a fourth column, joined by a straight link. */
+const TOOLS_X = 808;
+const TOOLS_WIDTH = 176;
+const NODE_HEIGHT = 54;
+const NODE_GAP = 12;
+const HEAD = 40;
+const FOOT = 12;
+/** Characters a node's name keeps before it is cut with an ellipsis. */
+const LABEL_LIMIT = [18, 17, 17];
+/** A read-only endpoint's name shares its row with the read-only chip. */
+const READ_ONLY_LABEL_LIMIT = 12;
+/** "a", "a and b", "a, b and c". */
+export function joinList(items) {
+    if (items.length <= 1)
+        return items[0] ?? "";
+    return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+function plural(count, one, many = `${one}s`) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+/** Cut a name to `limit` characters, ending in an ellipsis when it was longer. */
+export function truncate(text, limit) {
+    return text.length <= limit ? text : `${text.slice(0, limit - 1).trimEnd()}…`;
+}
+/** Where an endpoint's row opens on the Endpoints page. */
+export function endpointHref(path) {
+    return `/endpoints#${path.replace(/^\//, "")}`;
+}
+/** The endpoint path an Endpoints page hash names, or null. */
+export function endpointFromHash(hash) {
+    const value = hash.replace(/^#/, "");
+    return value.startsWith("mcp") ? `/${value}` : null;
+}
+function connectorHref(id, healthy) {
+    return `/connectors/${encodeURIComponent(id)}#${healthy ? "tools" : "connection"}`;
+}
+function tokenWorks(agent) {
+    return agent?.token.state === "issued";
+}
+/**
+ * People in the order the contract first lists them (plain /mcp's
+ * maintainers, then each pool's members), then every declared agent, then any
+ * agent a pool lists that is not declared. Plain /mcp admits no agents.
+ */
+function callersOf(contract, rows) {
+    const people = new Map();
+    const agents = new Map();
+    for (const agent of contract.agents) {
+        agents.set(agent.name, { id: `agent:${agent.name}`, kind: "agent", name: agent.name, agent, endpoints: [] });
+    }
+    const memberLists = rows.map((row) => [
+        row,
+        row.pool === null
+            ? (contract.root?.maintainers ?? [])
+            : (contract.pools.find((pool) => pool.name === row.pool)?.members ?? []),
+    ]);
+    for (const [row, members] of memberLists) {
+        for (const member of members) {
+            if (member.kind === "agent") {
+                if (row.pool === null)
+                    continue;
+                let caller = agents.get(member.name);
+                if (!caller) {
+                    caller = { id: `agent:${member.name}`, kind: "agent", name: member.name, agent: null, endpoints: [] };
+                    agents.set(member.name, caller);
+                }
+                if (!caller.endpoints.includes(row))
+                    caller.endpoints.push(row);
+                continue;
+            }
+            const id = `person:${member.namespace}:${member.id}`;
+            let caller = people.get(id);
+            if (!caller) {
+                caller = { id, kind: "person", name: member.label ?? member.id, agent: null, endpoints: [] };
+                people.set(id, caller);
+            }
+            if (!caller.endpoints.includes(row))
+                caller.endpoints.push(row);
+        }
+    }
+    return [...people.values(), ...agents.values()];
+}
+/** Unique live tools a set of endpoints serves, by address. */
+function servedTools(rows) {
+    const connectors = new Set();
+    const tools = new Map();
+    for (const row of rows) {
+        for (const group of row.groups) {
+            connectors.add(group.config.id);
+            for (const tool of group.tools)
+                tools.set(tool.address, tool.classification);
+        }
+    }
+    const write = [...tools.values()].filter((value) => value === "write").length;
+    return { connectors, tools: tools.size, write };
+}
+export function toolsPhrase(tools, write) {
+    if (!tools)
+        return "no tools";
+    return write ? `${plural(tools, "tool")}, ${write} write` : `${plural(tools, "tool")}, all read`;
+}
+function callerSummary(caller) {
+    const name = caller.name;
+    if (!caller.endpoints.length) {
+        return caller.kind === "agent" ? `${name} is in no endpoint, so it reaches nothing.` : `${name} reaches nothing.`;
+    }
+    const served = servedTools(caller.endpoints);
+    // An agent connects only at a pool's agent URL, never the people's one.
+    const through = joinList(caller.endpoints.map((row) => (caller.kind === "agent" ? (row.agentPath ?? row.path) : row.path)));
+    const reach = served.connectors.size
+        ? `${name} reaches ${plural(served.connectors.size, "connector")} through ${through}: ${toolsPhrase(served.tools, served.write)}.`
+        : `${name} uses ${through}, which serves no connectors.`;
+    if (caller.kind !== "agent" || tokenWorks(caller.agent))
+        return reach;
+    const state = caller.agent?.token.state;
+    return `${reach} ${state === "revoked" ? "Its token is revoked" : "It has no token"}, so it can't connect.`;
+}
+function callerDetail(caller, maintainers) {
+    if (caller.kind === "person")
+        return maintainers.has(caller.id) ? "maintainer" : "member";
+    const state = caller.agent?.token.state;
+    return state === "issued"
+        ? "agent · token issued"
+        : state === "revoked"
+            ? "agent · token revoked"
+            : "agent · no token";
+}
+function endpointSummary(row, callers) {
+    const listed = callers.filter((caller) => caller.endpoints.includes(row));
+    const people = listed.filter((caller) => caller.kind === "person").length;
+    const agents = listed.length - people;
+    const who = row.pool === null ? plural(people, "maintainer") : plural(people, "person", "people");
+    const users = agents ? `${who} and ${plural(agents, "agent")}` : who;
+    const served = servedTools([row]);
+    const mode = row.readOnly ? `${row.path} is read-only and serves ${users}` : `${row.path} serves ${users}`;
+    if (!served.connectors.size)
+        return `${mode}. It has no connectors.`;
+    return `${mode} with ${plural(served.connectors.size, "connector")}: ${toolsPhrase(served.tools, served.write)}.`;
+}
+const STATUS_SENTENCE = {
+    ok: "",
+    neutral: "",
+    warn: " It needs attention.",
+    danger: " It is failing.",
+};
+function connectorSummary(title, id, health, rows, callers) {
+    const on = rows.filter((row) => row.groups.some((group) => group.config.id === id));
+    const status = STATUS_SENTENCE[health.tone];
+    if (!on.length)
+        return `No endpoint serves ${title}, so nobody reaches it.${status}`;
+    const reaching = callers.filter((caller) => caller.endpoints.some((row) => on.includes(row)));
+    const people = reaching.filter((caller) => caller.kind === "person").length;
+    const agents = reaching.length - people;
+    const who = agents
+        ? `${plural(people, "person", "people")} and ${plural(agents, "agent")}`
+        : plural(people, "person", "people");
+    const verb = reaching.length === 1 ? "reaches" : "reach";
+    return `${who} ${verb} ${title} through ${joinList(on.map((row) => row.path))}.${status}`;
+}
+function edgePath(from, to) {
+    const x1 = from.x + from.width;
+    const y1 = from.y + from.height / 2;
+    const x2 = to.x;
+    const y2 = to.y + to.height / 2;
+    const dx = (x2 - x1) / 2;
+    return `M${x1},${y1} C${x1 + dx},${y1} ${x2 - dx},${y2} ${x2},${y2}`;
+}
+/** Each column's nodes stacked from the top, the shorter columns centered on the tallest. */
+function place(nodes) {
+    const columns = [0, 1, 2].map((column) => nodes.filter((node) => node.column === column));
+    const tallest = Math.max(1, ...columns.map((column) => column.length));
+    const body = tallest * (NODE_HEIGHT + NODE_GAP) - NODE_GAP;
+    columns.forEach((column, index) => {
+        const height = column.length * (NODE_HEIGHT + NODE_GAP) - NODE_GAP;
+        const top = HEAD + Math.max(0, (body - height) / 2);
+        column.forEach((node, position) => {
+            node.x = COLUMN_X[index];
+            node.width = COLUMN_WIDTH[index];
+            node.height = NODE_HEIGHT;
+            node.y = top + position * (NODE_HEIGHT + NODE_GAP);
+            if (node.kind === "connector")
+                node.toolsBox = { x: TOOLS_X, y: node.y, width: TOOLS_WIDTH, height: NODE_HEIGHT };
+        });
+    });
+    return HEAD + body + FOOT;
+}
+function node(fields, limit) {
+    return { hue: 0, ...fields, label: truncate(fields.name, limit), toolsBox: null, x: 0, y: 0, width: 0, height: 0 };
+}
+/** A connector's tile: two words' initials, a camel-case title's two capitals, or one letter. */
+export function monogram(title) {
+    const words = title.split(/[\s._-]+/).filter(Boolean);
+    if (words.length > 1)
+        return (words[0][0] + words[1][0]).toUpperCase();
+    const capitals = title.match(/[A-Z]/g) ?? [];
+    if (capitals.length >= 2)
+        return capitals[0] + capitals[1];
+    return (words[0] ?? title).charAt(0).toUpperCase();
+}
+/** The whole map for a maintainer's contract; an empty map for anyone else. */
+export function connectionMap(contract, options = {}) {
+    const rows = contract.role === "maintainer" ? endpointRows(contract) : [];
+    const callers = callersOf(contract, rows);
+    const maintainers = new Set((contract.root?.maintainers ?? []).flatMap((member) => member.kind === "human" ? [`person:${member.namespace}:${member.id}`] : []));
+    const connectors = (contract.role === "maintainer" ? (contract.config?.connectors ?? []) : []).flatMap((config) => {
+        const live = contract.live.connectors.find((c) => c.id === config.id);
+        return live ? [{ config, live, health: connectorVerdict(live, options.signals?.[config.id]) }] : [];
+    });
+    const health = new Map(connectors.map(({ config, health }) => [config.id, health]));
+    const nodes = [];
+    for (const caller of callers) {
+        const works = caller.kind === "person" || tokenWorks(caller.agent);
+        nodes.push(node({
+            id: caller.id,
+            kind: caller.kind,
+            column: 0,
+            name: caller.name,
+            detail: callerDetail(caller, maintainers),
+            href: caller.kind === "agent"
+                ? options.tokensPage
+                    ? "/tokens"
+                    : null
+                : caller.endpoints[0]
+                    ? endpointHref(caller.endpoints[0].path)
+                    : null,
+            tone: works ? "neutral" : "warn",
+            readOnly: false,
+            tools: null,
+            initials: caller.kind === "person" ? initialsOf(caller.name) : "",
+            hue: caller.kind === "person" ? hueOf(caller.id.slice("person:".length)) : 0,
+            summary: callerSummary(caller),
+        }, LABEL_LIMIT[0]));
+    }
+    for (const row of rows) {
+        const listed = callers.filter((caller) => caller.endpoints.includes(row)).length;
+        nodes.push(node({
+            id: `endpoint:${row.path}`,
+            kind: "endpoint",
+            column: 1,
+            name: row.path,
+            detail: `${row.pool === null ? "maintainers" : plural(listed, "caller")} · ${plural(row.groups.length, "connector")}`,
+            href: endpointHref(row.path),
+            tone: "neutral",
+            readOnly: row.readOnly,
+            tools: null,
+            initials: "",
+            summary: endpointSummary(row, callers),
+        }, row.readOnly ? READ_ONLY_LABEL_LIMIT : LABEL_LIMIT[1]));
+    }
+    for (const { config, live, health: verdict } of connectors) {
+        const title = config.title ?? config.id;
+        const read = live.tools.filter((tool) => tool.classification === "read").length;
+        const scope = config.authScope === "personal" ? "personal" : "shared";
+        // A failed or unobserved catalog has no tools to count, which is not zero tools.
+        const known = live.tools.length > 0 || (live.status === "ok" && !live.problem);
+        nodes.push(node({
+            id: `connector:${config.id}`,
+            kind: "connector",
+            column: 2,
+            name: title,
+            detail: verdict.tone === "ok" ? `${scope} · ${plural(live.tools.length, "tool")}` : verdict.label,
+            href: connectorHref(config.id, verdict.tone === "ok"),
+            tone: verdict.tone,
+            readOnly: false,
+            tools: known ? { read, write: live.tools.length - read } : null,
+            initials: monogram(title),
+            summary: connectorSummary(title, config.id, verdict, rows, callers),
+        }, LABEL_LIMIT[2]));
+    }
+    const height = place(nodes);
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const edges = [];
+    for (const caller of callers) {
+        for (const row of caller.endpoints) {
+            const from = byId.get(caller.id);
+            const to = byId.get(`endpoint:${row.path}`);
+            edges.push({
+                id: `${from.id}>${to.id}`,
+                from: from.id,
+                to: to.id,
+                kind: "access",
+                tone: "neutral",
+                readOnly: false,
+                noToken: caller.kind === "agent" && !tokenWorks(caller.agent),
+                served: null,
+                path: edgePath(from, to),
+            });
+        }
+    }
+    for (const row of rows) {
+        for (const group of row.groups) {
+            const from = byId.get(`endpoint:${row.path}`);
+            const to = byId.get(`connector:${group.config.id}`);
+            if (!to)
+                continue;
+            edges.push({
+                id: `${from.id}>${to.id}`,
+                from: from.id,
+                to: to.id,
+                kind: "grant",
+                tone: health.get(group.config.id)?.tone ?? "neutral",
+                readOnly: row.readOnly,
+                noToken: false,
+                served: {
+                    tools: group.tools.length,
+                    write: group.tools.filter((tool) => tool.classification === "write").length,
+                },
+                path: edgePath(from, to),
+            });
+        }
+    }
+    return {
+        nodes,
+        edges,
+        width: MAP_WIDTH,
+        height,
+        columns: [
+            { label: "Callers", count: callers.length, x: COLUMN_X[0] },
+            { label: "Endpoints", count: rows.length, x: COLUMN_X[1] },
+            { label: "Connectors", count: connectors.length, x: COLUMN_X[2] },
+            { label: "Tools", count: connectors.reduce((n, { live }) => n + live.tools.length, 0), x: TOOLS_X },
+        ],
+    };
+}
+/**
+ * What hovering a node lights up: every node and link on a path through it.
+ * Links are walked forward from the node and backward to it, never both ways
+ * from a neighbor, so a caller lights only what it reaches and a connector
+ * lights only who reaches it.
+ */
+export function mapHighlight(map, id) {
+    const nodes = new Set([id]);
+    const edges = new Set();
+    const walk = (forward) => {
+        const queue = [id];
+        const seen = new Set([id]);
+        while (queue.length) {
+            const current = queue.shift();
+            for (const edge of map.edges) {
+                if ((forward ? edge.from : edge.to) !== current)
+                    continue;
+                const target = forward ? edge.to : edge.from;
+                edges.add(edge.id);
+                nodes.add(target);
+                if (!seen.has(target)) {
+                    seen.add(target);
+                    queue.push(target);
+                }
+            }
+        }
+    };
+    walk(true);
+    walk(false);
+    return { nodes, edges };
+}
+export function mapList(map) {
+    const byId = new Map(map.nodes.map((n) => [n.id, n]));
+    return map.nodes
+        .filter((n) => n.kind === "endpoint")
+        .map((endpoint) => ({
+        endpoint,
+        callers: map.edges
+            .filter((edge) => edge.to === endpoint.id)
+            .map((edge) => ({ node: byId.get(edge.from), noToken: edge.noToken })),
+        connectors: map.edges
+            .filter((edge) => edge.from === endpoint.id)
+            .map((edge) => ({ node: byId.get(edge.to), served: edge.served ?? { tools: 0, write: 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;