@anchrd/intel-api 0.6.7 → 0.9.0

package/dist/nodes/nodes.types.d.ts

@@ -0,0 +1,402 @@
+import type { AgentKeyRotated, AgentList, AppendTableRowsInput, AppendTableRowsResult, ArchiveNodeInput, CreateAgentInput, CreatedAgent, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, DeleteTableRowsResult, Flow, FlowVersion, GetAgentInput, ListAgentsInput, ListNodesInput, Node, NodeAgent, NodeAttachment, NodeCitation, NodeDocument, NodeGraph, NodeGraphInput, NodeLink, NodeTable, NodeVersion, RedefineTableInput, ResolveNodeLinksInput, ResolveNodeLinksResult, ResourceGrant, ResourceGrantList, ResourceVerb, RevokeGrantInput, RotateAgentKeyInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, ShareInput, ShareResult, UpdateNodeInput, UpdateTableRowsInput, UpdateTableRowsResult } from "@anchrd/intel-contract";
+import type { SemanticIndex } from "../adapters/semantic-index/semantic-index.types.js";
+export interface Actor {
+    id: string;
+    email: string;
+    isAdmin?: boolean;
+}
+export interface NewNode {
+    node: Node;
+    actorId: string;
+    idempotencyKey: string;
+    auditId: string;
+    application?: {
+        id: string;
+    } | undefined;
+}
+export interface NewNodeVersion {
+    version: NodeVersion;
+    actorId: string;
+    baseVersionId: string | null;
+    idempotencyKey: string;
+    auditId: string;
+}
+export interface NewTableVersion {
+    version: Omit<NodeVersion, "sequence">;
+    actorId: string;
+    idempotencyKey: string;
+    auditId: string;
+}
+export type TableSnapshotOperation = "node.table_update" | "node.table_delete" | "node.table_redefine";
+export interface NewTableSnapshot {
+    version: NodeVersion;
+    actorId: string;
+    baseVersionId: string;
+    operation: TableSnapshotOperation;
+    metadata: Record<string, unknown>;
+    idempotencyKey: string;
+    auditId: string;
+}
+export interface NodeRepository {
+    listVisible(actor: Actor, input: ListNodesInput): Promise<{
+        items: Node[];
+        withChildren: string[];
+    }>;
+    listVisibleBounded(actor: Actor, input: {
+        parentId: string | null;
+        limit: number;
+    }): Promise<BoundedChildren>;
+    listVisibleAgents(actor: Actor, input: ListAgentsInput): Promise<Node[]>;
+    listVisibleAgentDefinitionKeys(actor: Actor, folderId: string): Promise<string[]>;
+    getVisible(actor: Actor, nodeId: string): Promise<Node | null>;
+    listVisibleSubtree(actor: Actor, rootId: string | null): Promise<SubtreeNode[]>;
+    can(actor: Actor, nodeId: string, verb: ResourceVerb): Promise<boolean>;
+    findIdempotentNode(actorId: string, operation: "node.create" | "node.save" | "node.append" | "node.update" | "node.archive" | "node.share" | "node.revoke" | TableSnapshotOperation, idempotencyKey: string): Promise<string | null>;
+    findIdempotentRevocation(actorId: string, idempotencyKey: string): Promise<boolean | null>;
+    insertNode(input: NewNode): Promise<Node>;
+    agentApplicationId(nodeId: string): Promise<string | null>;
+    /**
+     * The audit row for replacing the key of the Application an agent runs as (D29, #207).
+     *
+     * ⚠️ Its own write because it is the only mutation on an agent node that changes nothing IN the
+     * node — no version, no row, nothing a reader could diff afterwards. Swapping which credential an
+     * agent acts with is the most security-relevant thing anybody does to it, and without this it
+     * would be the one act on the tree that leaves no trace in Intel at all. Gate audits its side;
+     * Gate does not know which Intel node the principal belongs to.
+     *
+     * ⚠️ `applicationId` names the principal and is a name, not a credential. The key itself is not a
+     * parameter here and must never become one — audit is metadata, and this is exactly the row a
+     * "helpful" second field would leak it into.
+     */
+    recordAgentKeyRotation(input: {
+        auditId: string;
+        actorId: string;
+        nodeId: string;
+        applicationId: string;
+        occurredAt: string;
+    }): Promise<void>;
+    getVersion(versionId: string): Promise<NodeVersion | null>;
+    appendVersion(input: NewNodeVersion): Promise<"saved" | "conflict">;
+    appendTableVersion(input: NewTableVersion): Promise<NodeVersion>;
+    appendTableSnapshot(input: NewTableSnapshot): Promise<"saved" | "conflict">;
+    listVersionContentKeys(nodeId: string): Promise<string[]>;
+    tableHeaderContentKey(nodeId: string): Promise<string | null>;
+    listVersions(nodeId: string): Promise<NodeVersion[]>;
+    updateNode(input: {
+        node: Node;
+        baseUpdatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"cycle" | "conflict" | Node>;
+    archiveNode(input: {
+        nodeId: string;
+        baseUpdatedAt: string;
+        archivedAt: string | null;
+        updatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"conflict" | Node>;
+    listGrants(resourceId: string): Promise<ResourceGrant[]>;
+    organizationExecuteReaches(nodeId: string, exceptGrantId: string): Promise<boolean>;
+    listLinksVisible(actor: Actor, nodeId: string): Promise<NodeLink[]>;
+    resolveVisibleTitles(actor: Actor, nodeIds: string[]): Promise<Array<{
+        nodeId: string;
+        title: string;
+    }>>;
+    replaceTextLinks(input: {
+        sourceNodeId: string;
+        links: Array<{
+            id: string;
+            targetNodeId: string;
+        }>;
+        actorId: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<void>;
+    graphVisible(actor: Actor, input: NodeGraphInput): Promise<NodeGraph>;
+    setGrant(input: {
+        grant: ResourceGrant;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<ResourceGrant>;
+    revokeGrant(input: {
+        resourceId: string;
+        grantId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<boolean>;
+    searchVisible(actor: Actor, input: SearchInput): Promise<NodeCitation[]>;
+    hydrateVisibleCitations(actor: Actor, nodeIds: string[], scopeId?: string): Promise<NodeCitation[]>;
+    listCurrentVersionIds(input: {
+        after: string | null;
+        limit: number;
+    }): Promise<string[]>;
+    importTree(input: ImportTreeInput): Promise<"created" | "replayed">;
+    findImportReplay(actorId: string, idempotencyKey: string): Promise<Record<string, unknown> | null>;
+}
+export interface ImportedLink {
+    id: string;
+    sourceNodeId: string;
+    targetNodeId: string;
+}
+/**
+ * Everything one bundle import creates, as one write (#137).
+ *
+ * ⚠️ The whole point of this shape is the atomicity: every row lands in one `db.batch`, which D1
+ * runs as one transaction, so a partial import cannot exist — either the whole subtree stands or
+ * nothing does. The R2 objects behind `versions` are written before and deleted again by the
+ * caller when the batch refuses.
+ *
+ * `nodes` must come parents before children: the tree's foreign key checks each row as it lands.
+ */
+export interface ImportTreeInput {
+    nodes: Node[];
+    versions: NodeVersion[];
+    links: ImportedLink[];
+    flows: Flow[];
+    flowVersions: FlowVersion[];
+    actorId: string;
+    idempotencyKey: string;
+    auditId: string;
+    auditResourceId: string;
+    metadata: Record<string, unknown>;
+    occurredAt: string;
+}
+export interface ContentStore {
+    get(key: string): Promise<string | null>;
+    getBytes(key: string): Promise<ArrayBuffer | null>;
+    getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
+    put(key: string, content: string, mediaType: string): Promise<void>;
+    putBytes(key: string, content: ArrayBuffer, mediaType: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface NodeAttachmentBody {
+    attachment: NodeAttachment;
+    body: ReadableStream<Uint8Array>;
+}
+/**
+ * Gate's Applications surface, as the tree needs it (#182).
+ *
+ * ⚠️ Every call carries the CALLER's own Gate bearer, never a service key. Creating and switching a
+ * machine principal is an administrative act in Gate, gated on `applications:write` and audited
+ * there under the person who performed it; Intel's service key does not open that door at all
+ * (Gate's two-token rule). The token is therefore a parameter of the operation rather than a field
+ * of the actor: it must be impossible to reach for by accident from a service that has no business
+ * with it, and it must never end up on an audit row or in a log line.
+ */
+export interface AgentApplications {
+    /**
+     * A new machine principal, named so a person can recognise the agent behind it.
+     *
+     * ⚠️ The returned key is plain text, the only time it exists in readable form anywhere, and it is
+     * gone from Gate the moment this call returns. It is passed straight back to the caller who asked
+     * for it and is written nowhere on the way (D27).
+     */
+    create(input: {
+        token: string;
+        name: string;
+    }): Promise<{
+        id: string;
+        key: string;
+    }>;
+    /**
+     * A replacement key for an Application that already exists, invalidating every earlier one.
+     *
+     * ⚠️ Gate issues before it revokes, so a failed rotation leaves the old key working. That is what
+     * makes `rotate-key` a safe repair rather than a way to lock an agent out: the only state this
+     * can leave behind is "new key issued, runtime never got it", and rotating again fixes it.
+     */
+    rotateKey(input: {
+        token: string;
+        applicationId: string;
+    }): Promise<{
+        key: string;
+    }>;
+    setEnabled(input: {
+        token: string;
+        applicationId: string;
+        enabled: boolean;
+    }): Promise<void>;
+}
+export interface GateCaller {
+    token: string;
+}
+export interface NodesDeps {
+    repository: NodeRepository;
+    content: ContentStore;
+    applications: AgentApplications;
+    agentRuntimeAvailable(): boolean;
+    /**
+     * The runtime's key store, as the tree needs it (D29, #207).
+     *
+     * ⚠️ This is where the Application key GOES, and it is the only place it goes. Gate hands it out
+     * once, this port carries it into the agent's Durable Object over the service binding, and the
+     * local variable that held it dies with the call. Nothing in this file writes it to D1, R2, an
+     * audit row, a log line or a response — the proof is the absence of the value in every argument
+     * every port was called with, not a redaction somebody could forget.
+     */
+    agentKeys: {
+        store(input: {
+            token: string;
+            agentId: string;
+            key: string;
+        }): Promise<void>;
+    };
+    /**
+     * The runtime's alarm, brought in line with the definition that was just written (#214).
+     *
+     * ⚠️ Required, not optional, and it carries no schedules. The runtime arms its alarm only when
+     * something tells it to look — a chat turn, a resume, a manual run, or this call — so a definition
+     * written without it leaves an agent whose schedules are visible in its profile and fire never.
+     * What travels is the agent's ID and the caller's bearer; the runtime re-reads the definition from
+     * Intel with the agent's own token, which is what keeps a schedule something that was written
+     * before it can be acted on.
+     */
+    agentSchedules: {
+        sync(input: {
+            token: string;
+            agentId: string;
+        }): Promise<void>;
+    };
+    id(): string;
+    now(): Date;
+    externalFlowCallers(actor: Actor, folderId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    flowNodeReferences(actor: Actor, folderId: string): Promise<string[]>;
+    /**
+     * The handles of the MCP servers this actor reaches through the portal right now (D30).
+     *
+     * ⚠️ Injected as a live question, never as a stored list. Delegating a server is only allowed to
+     * somebody who has it themselves, and "has it" can only be answered by asking the portal at the
+     * moment of the save — a mirrored table here would be the permission mirror ADR-0003 removed.
+     */
+    toolServers(actor: Actor): Promise<string[]>;
+    hash(content: string | Uint8Array): Promise<string>;
+    indexing: {
+        enqueue(versionId: string): Promise<void>;
+    };
+    semantic?: SemanticIndex | undefined;
+}
+export type FolderAccess = "ok" | "missing" | "not-a-folder" | "forbidden";
+export interface SubtreeNode {
+    node: Node;
+    version: {
+        id: string;
+        mediaType: string;
+        contentKey: string;
+    } | null;
+}
+export interface BoundedChildren {
+    items: Node[];
+    total: number;
+}
+export interface NodeService {
+    list(actor: Actor, input: ListNodesInput): Promise<{
+        items: Node[];
+    }>;
+    /**
+     * One level of the tree as this actor may see it, bounded: at most `limit` current children, and
+     * `total` for how many there are. Its caller is the relation graph, which draws a bounded picture
+     * and must not read a folder of a thousand documents to do it (#30).
+     *
+     * ⚠️ `total` counts what passed the visibility predicate and nothing else, or the size a picture
+     * reports would become a way of learning that something is filed here.
+     */
+    childrenBounded(actor: Actor, input: {
+        parentId: string | null;
+        limit: number;
+    }): Promise<BoundedChildren>;
+    get(actor: Actor, nodeId: string): Promise<NodeDocument>;
+    getVersion(actor: Actor, nodeId: string, versionId: string): Promise<NodeDocument>;
+    folderAccess(actor: Actor, folderId: string): Promise<FolderAccess>;
+    create(actor: Actor, input: CreateNodeInput): Promise<Node>;
+    save(actor: Actor, input: SaveNodeVersionInput): Promise<NodeDocument>;
+    saveAttachment(actor: Actor, input: SaveAttachmentInput): Promise<NodeDocument>;
+    getTable(actor: Actor, nodeId: string): Promise<NodeTable>;
+    defineTable(actor: Actor, input: DefineTableInput): Promise<NodeTable>;
+    appendTableRows(actor: Actor, input: AppendTableRowsInput): Promise<AppendTableRowsResult>;
+    updateTableRows(actor: Actor, input: UpdateTableRowsInput): Promise<UpdateTableRowsResult>;
+    deleteTableRows(actor: Actor, input: DeleteTableRowsInput): Promise<DeleteTableRowsResult>;
+    redefineTable(actor: Actor, input: RedefineTableInput): Promise<NodeTable>;
+    getAgent(actor: Actor, input: GetAgentInput): Promise<NodeAgent>;
+    /**
+     * An agent node, its first definition, and the Gate Application it runs as (#182, D29).
+     *
+     * ⚠️ The answer carries NO key. The one Gate issues goes straight into the agent runtime over the
+     * service binding, inside this call, and the caller never sees it — which is what makes an agent
+     * created through the screen able to run without a terminal step (#200, #207).
+     */
+    createAgent(actor: Actor, input: CreateAgentInput, caller: GateCaller): Promise<CreatedAgent>;
+    /**
+     * Replace the key of the Application an agent runs as, and give the new one to the runtime.
+     *
+     * ⚠️ The repair path for an agent that answers `agent_key_missing`, and the only one: Gate keeps
+     * a key hashed, so an agent whose Durable Object lost its key cannot be handed the old one back.
+     * It is a write on the agent node — `knowledge/write` and the resource ACL — not a run.
+     */
+    rotateAgentKey(actor: Actor, input: RotateAgentKeyInput, caller: GateCaller): Promise<AgentKeyRotated>;
+    /**
+     * A new definition version for an agent, and the alarm that goes with it (#214).
+     *
+     * ⚠️ It takes the caller's bearer for the same reason `createAgent` does: the runtime is told to
+     * re-arm over the service binding, and what travels on that call is the person behind this request
+     * — never a service key (D19).
+     */
+    saveAgentDefinition(actor: Actor, input: SaveAgentDefinitionInput, caller: GateCaller): Promise<NodeAgent>;
+    listAgents(actor: Actor, input: ListAgentsInput): Promise<AgentList>;
+    getAttachment(actor: Actor, nodeId: string): Promise<NodeAttachment>;
+    readAttachment(actor: Actor, nodeId: string): Promise<NodeAttachmentBody>;
+    listVersions(actor: Actor, nodeId: string): Promise<{
+        items: NodeVersion[];
+    }>;
+    update(actor: Actor, input: UpdateNodeInput): Promise<Node>;
+    /**
+     * Archiving and restoring, for every kind — and for an agent, its Gate Application with it (#182).
+     *
+     * ⚠️ The Gate call comes FIRST and the node row second. An archived agent whose principal is
+     * still live is exactly the access nobody can see any more, so that state must not be reachable
+     * by a write that half succeeded; the opposite order can only leave a live agent whose principal
+     * is off, which stops working loudly and is repaired by repeating the call.
+     */
+    archive(actor: Actor, input: ArchiveNodeInput, caller: GateCaller): Promise<Node>;
+    listGrants(actor: Actor, resourceId: string): Promise<ResourceGrantList>;
+    listLinks(actor: Actor, nodeId: string): Promise<{
+        items: NodeLink[];
+    }>;
+    resolveLinks(actor: Actor, input: ResolveNodeLinksInput): Promise<ResolveNodeLinksResult>;
+    graph(actor: Actor, input: NodeGraphInput): Promise<NodeGraph>;
+    visibleNode(actor: Actor, nodeId: string): Promise<Node | null>;
+    share(actor: Actor, input: ShareInput): Promise<ShareResult>;
+    revokeGrant(actor: Actor, input: RevokeGrantInput): Promise<{
+        revoked: boolean;
+    }>;
+    search(actor: Actor, input: SearchInput): Promise<{
+        items: NodeCitation[];
+    }>;
+    reindex(actor: Actor): Promise<{
+        queued: number;
+    }>;
+}
+export interface NodeIndexTarget {
+    nodeId: string;
+    versionId: string;
+    title: string;
+    description: string | null;
+    contentKeys: string[];
+    mediaType: string;
+    kind: "document" | "attachment" | "table" | "agent";
+    updatedAt: string;
+}
+export interface NodeIndexRepository {
+    getTarget(versionId: string): Promise<NodeIndexTarget | null>;
+    replace(target: NodeIndexTarget, content: string): Promise<void>;
+    markIndexed(versionId: string, occurredAt: string): Promise<void>;
+    markError(versionId: string, message: string, occurredAt: string): Promise<void>;
+}

package/dist/nodes/nodes.types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/tool-servers/tool-servers.d.ts

@@ -0,0 +1,46 @@
+import { type ToolServer } from "@anchrd/intel-contract";
+/**
+ * The portal's own directory tool. It is an ordinary entry in `tools/list`, so it is reached the
+ * same way every other tool is: `tools/call` with the asking user's portal token.
+ *
+ * ⚠️ Its presence in the live list is also the permission check. A deployment whose portal does not
+ * offer it, or a user whose Access policies hide it, gets no server list at all — and therefore
+ * cannot delegate anything. That is deliberate: the alternative would be inventing the server list
+ * out of tool names, which is exactly the guess this module exists to avoid.
+ */
+export declare const ServerDirectoryTool = "portal_list_servers";
+export interface ToolServerDirectoryAnswer {
+    isError: boolean;
+    content: unknown[];
+    structuredContent?: unknown;
+}
+/**
+ * The servers this user reaches: the portal's directory, confirmed against the portal's live tool
+ * list.
+ *
+ * Two sets come out of one answer, and keeping them apart is the whole of this function:
+ *
+ * - **`declared`** — every identifier the directory mentions at all, disabled rows included. It is
+ *   the universe `serverOf` attributes against, and it must be as WIDE as possible. ⚠️ Narrowing it
+ *   widens the delegation: drop `wiki_extra` because the portal marked it disabled, and the live
+ *   tool `wiki_extra__read` falls back onto `wiki` — a tool of a server nobody delegated, handed to
+ *   an agent that was given `wiki`. Filtering therefore happens after attribution, never before it.
+ * - **the returned list** — what may actually be delegated: enabled, and confirmed by at least one
+ *   live tool. Intel cannot prove that a directory identifier is the same string the namespace uses,
+ *   so it only ever offers handles it has just seen work.
+ *
+ * ⚠️ What remains outside Intel's reach: a directory that omits a server whose tools ARE in
+ * `tools/list`. Nothing in the answer distinguishes that from a tool of the enclosing namespace, and
+ * the portal is the authority on its own servers — so an incomplete directory widens by exactly one
+ * namespace level, and it is a portal defect rather than something this code can detect.
+ */
+export interface ToolServerDirectory {
+    /** Every identifier the directory mentioned. Attribute against this, never against `servers`. */
+    declared: string[];
+    /** What may be offered and delegated: enabled, and confirmed by a live tool. */
+    servers: ToolServer[];
+}
+export declare function toolServersFrom(input: {
+    directory: ToolServerDirectoryAnswer;
+    toolNames: string[];
+}): ToolServerDirectory | null;

package/dist/tools/tool-servers/tool-servers.js

@@ -0,0 +1,114 @@
+import { serverOf } from "@anchrd/intel-contract";
+import { z } from "zod";
+/**
+ * The portal's own directory tool. It is an ordinary entry in `tools/list`, so it is reached the
+ * same way every other tool is: `tools/call` with the asking user's portal token.
+ *
+ * ⚠️ Its presence in the live list is also the permission check. A deployment whose portal does not
+ * offer it, or a user whose Access policies hide it, gets no server list at all — and therefore
+ * cannot delegate anything. That is deliberate: the alternative would be inventing the server list
+ * out of tool names, which is exactly the guess this module exists to avoid.
+ */
+export const ServerDirectoryTool = "portal_list_servers";
+/**
+ * What the portal answers about one server, read as tolerantly as possible.
+ *
+ * ⚠️ Only the shape is assumed, never the vocabulary. The portal is somebody else's product and its
+ * payload is not part of any contract Intel owns, so every field is optional and the answer is
+ * accepted from `structuredContent`, from `{ servers: [...] }` or from a JSON text block. What
+ * makes a row usable is not that it parsed but that its identifier is confirmed against the live
+ * tool list below.
+ */
+const DirectoryRow = z.looseObject({
+    id: z.string().optional(),
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+});
+const DirectoryRows = z.array(DirectoryRow);
+const DirectoryEnvelope = z.looseObject({ servers: DirectoryRows });
+/**
+ * Every place the portal could reasonably have put its list, tried in order. An MCP tool result is
+ * either structured or text, and a server that answers with `{ servers: [...] }` is as likely as
+ * one that answers with a bare array.
+ */
+function rows(answer) {
+    const candidates = [answer.structuredContent];
+    for (const block of answer.content) {
+        if (typeof block === "object" && block !== null && "text" in block) {
+            const text = block.text;
+            if (typeof text !== "string")
+                continue;
+            try {
+                candidates.push(JSON.parse(text));
+            }
+            catch {
+                // A text block that is not JSON is prose, not a directory. Skip it rather than fail: the
+                // portal may well add a human sentence beside the payload.
+            }
+        }
+    }
+    for (const candidate of candidates) {
+        const bare = DirectoryRows.safeParse(candidate);
+        if (bare.success)
+            return bare.data;
+        const wrapped = DirectoryEnvelope.safeParse(candidate);
+        if (wrapped.success)
+            return wrapped.data.servers;
+    }
+    return null;
+}
+/**
+ * ⚠️ The rule itself — longest match against declared handles, never a cut at an underscore — is
+ * `serverOf` in `@anchrd/intel-contract`, because the tools screen has to read a name exactly the
+ * way the delegation does (#212). What stays here is what the rule is USED for: a tool whose prefix
+ * matches no declared handle belongs to no server and can never be delegated, which is what keeps
+ * the portal's own management tools (`portal_list_servers`, `portal_toggle_servers`) out of an
+ * agent's reach — the portal does not list itself as an upstream server.
+ */
+/**
+ * ⚠️ A handle that would carry the portal's OWN tools is never a server anybody can be given.
+ *
+ * The portal does not list itself as an upstream, so in practice `portal` never appears in the
+ * directory — but "in practice" is not a guard. One row called `portal` (an upstream a customer
+ * happens to name that way, a future portal that describes itself) would make `portal_toggle_servers`
+ * a delegable tool, and an agent could then switch its delegator's MCP servers on and off. The rule
+ * is written as a question about reach rather than as a blocklist of one string: if delegating this
+ * handle would hand over `portal_list_servers`, the handle is refused.
+ */
+function ownsTheDirectory(handle) {
+    return ServerDirectoryTool.startsWith(`${handle}_`);
+}
+export function toolServersFrom(input) {
+    const parsed = rows(input.directory);
+    if (parsed === null)
+        return null;
+    // `id` and `name` are both offered as candidates because the portal's directory names them
+    // separately and only one of them is the namespace. The live list decides which.
+    const display = new Map();
+    const offerable = new Set();
+    for (const row of parsed) {
+        for (const candidate of [row.name, row.id]) {
+            if (candidate === undefined || candidate.length === 0)
+                continue;
+            if (ownsTheDirectory(candidate))
+                continue;
+            if (!display.has(candidate))
+                display.set(candidate, row.name ?? row.id ?? candidate);
+            if (row.enabled !== false)
+                offerable.add(candidate);
+        }
+    }
+    const counts = new Map();
+    for (const toolName of input.toolNames) {
+        const handle = serverOf(toolName, display.keys());
+        if (handle === null || !offerable.has(handle))
+            continue;
+        counts.set(handle, (counts.get(handle) ?? 0) + 1);
+    }
+    return {
+        declared: [...display.keys()],
+        servers: [...counts.entries()]
+            .map(([handle, toolCount]) => ({ handle, name: display.get(handle) ?? handle, toolCount }))
+            .sort((a, b) => a.handle.localeCompare(b.handle)),
+    };
+}