@anchrd/intel-api 0.7.0 → 0.10.0

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

@@ -1,4 +1,4 @@
-import type { 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, SaveAgentDefinitionInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, ShareInput, ShareResult, UpdateNodeInput, UpdateTableRowsInput, UpdateTableRowsResult } from "@anchrd/intel-contract";
+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;
@@ -55,6 +55,26 @@ export interface NodeRepository {
     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>;
@@ -184,6 +204,19 @@ export interface AgentApplications {
         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;
@@ -198,6 +231,38 @@ export interface NodesDeps {
     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<{
@@ -205,6 +270,14 @@ export interface NodesDeps {
         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>;
@@ -254,14 +327,29 @@ export interface NodeService {
     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).
+     * An agent node, its first definition, and the Gate Application it runs as (#182, D29).
      *
-     * ⚠️ The answer carries the Application key ONCE. It is the only value any Intel service returns
-     * that is a credential, it is never written down on the way out, and the caller who receives it
-     * is the only one who will ever see it.
+     * ⚠️ 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>;
-    saveAgentDefinition(actor: Actor, input: SaveAgentDefinitionInput): Promise<NodeAgent>;
+    /**
+     * 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>;

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)),
+    };
+}

package/dist/tools/tools.js

@@ -1,10 +1,24 @@
+import { serverOf } from "@anchrd/intel-contract";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 import { reportUnexpectedError } from "../shared/report-unexpected-error/report-unexpected-error.js";
+import { ServerDirectoryTool, toolServersFrom, } from "./tool-servers/tool-servers.js";
 const CallTimeoutMs = 15_000;
 const MaxTools = 1_000;
 const MaxResultBytes = 1_000_000;
 // Refresh slightly early so a call cannot start with a token that expires mid-flight.
 const RefreshWindowMs = 30_000;
+/**
+ * An agent that delegates nothing — no servers, or no delegator to act for.
+ *
+ * ⚠️ It is answered without touching the token store at all. `delegatedBy` is empty for an archived
+ * agent, one whose definition Intel could not read, and one that was never given tools; asking the
+ * store for the connection of user "" would be a lookup that can only ever fail, on a path that has
+ * already decided the answer.
+ */
+function delegatesNothing(who) {
+    return (who.delegation !== null &&
+        (who.delegation.servers.length === 0 || who.delegation.delegatedBy.length === 0));
+}
 export function createTools(deps) {
     function portal() {
         if (!deps.portalUrl || !deps.sourceAllowed(deps.portalUrl)) {
@@ -12,12 +26,23 @@ export function createTools(deps) {
         }
         return deps.portalUrl;
     }
+    // One lookup per request, before anything else happens: everything below has to know whether it
+    // is answering a person or an agent, and a second lookup could answer differently mid-call.
+    async function acting(actor) {
+        const delegation = await deps.delegation(actor.id);
+        return {
+            actor,
+            connectionOf: delegation?.delegatedBy ?? actor.id,
+            delegation,
+        };
+    }
     // Authorization for tools lives entirely in the portal, so "may this user act" reduces to "does
     // this user have a usable portal token". ⚠️ The token is read per actor and never shared: one
     // operator token for everybody would make every catalog the same one and the portal's Access
-    // policies decorative (ADR-0003).
-    async function accessToken(actor) {
-        const stored = await deps.tokens.read(actor.id);
+    // policies decorative (ADR-0003). For an agent the actor IS somebody else — the delegator — which
+    // is the whole of D30 and the reason this takes an `Acting` rather than a `ToolActor`.
+    async function accessToken(who) {
+        const stored = await deps.tokens.read(who.connectionOf);
         if (!stored) {
             throw new IntelError(401, "portal_not_connected", "The portal has not signed this user in yet");
         }
@@ -33,20 +58,81 @@ export function createTools(deps) {
             // A token that cannot be renewed is dropped: leaving it would keep failing every call with a
             // stale credential. The browser answers this by signing in silently again (#60); an MCP
             // client sees the code and repeats its own authorization.
-            await deps.tokens.clear(actor.id);
+            await deps.tokens.clear(who.connectionOf);
             throw new IntelError(401, "portal_reconnect_required", "The portal sign-in for this user has expired");
         }
-        await deps.tokens.write(actor.id, refreshed);
+        await deps.tokens.write(who.connectionOf, refreshed);
         return refreshed.accessToken;
     }
-    // One live tools/list is both the catalog and the authorization answer: the portal only returns
-    // what this user may reach. Nothing here is cached as a permission.
-    async function capabilities(actor) {
-        const token = await accessToken(actor);
+    async function remoteTools(who) {
+        const token = await accessToken(who);
         const remote = await deps.remote.list(portal(), token, AbortSignal.timeout(CallTimeoutMs));
         if (remote.length > MaxTools) {
             throw new IntelError(502, "tool_catalog_too_large", "The portal returned too many tools");
         }
+        return remote;
+    }
+    /**
+     * The servers the portal says this connection reaches, confirmed against its live tool list.
+     *
+     * ⚠️ Fails rather than answering "none" when the portal keeps no directory. An empty list would
+     * be indistinguishable from "you have no servers", and the difference decides whether a screen
+     * says "connect something" or "this portal cannot be delegated from".
+     */
+    async function serverList(who, toolNames) {
+        if (!toolNames.includes(ServerDirectoryTool)) {
+            throw new IntelError(502, "tool_servers_unavailable", `The portal does not offer ${ServerDirectoryTool}, so its servers cannot be listed`);
+        }
+        const answer = await deps.remote.call({
+            url: portal(),
+            accessToken: await accessToken(who),
+            name: ServerDirectoryTool,
+            arguments: {},
+            signal: AbortSignal.timeout(CallTimeoutMs),
+        });
+        const directory = answer.isError ? null : toolServersFrom({ directory: answer, toolNames });
+        if (directory === null) {
+            throw new IntelError(502, "tool_servers_unavailable", "The portal did not answer with a server list this Intel can read");
+        }
+        return directory;
+    }
+    /**
+     * One live tools/list is both the catalog and the authorization answer: the portal only returns
+     * what this user may reach. Nothing here is cached as a permission.
+     *
+     * ⚠️ For an agent the list is cut to the delegated servers, and the cut is made against the
+     * portal's own directory rather than against the tool names — `tool-servers.ts` says why the
+     * namespace alone is not enough to attribute a tool. The second return value is the attribution
+     * itself, so the audit below names the server the cut actually used rather than guessing again.
+     */
+    async function capabilities(who) {
+        const delegated = who.delegation;
+        const serverOfTool = new Map();
+        if (delegatesNothing(who))
+            return { items: [], serverOfTool };
+        let remote = await remoteTools(who);
+        if (delegated) {
+            const directory = await serverList(who, remote.map((tool) => tool.name));
+            // ⚠️ Attributed against every identifier the portal DECLARED — including rows it marked
+            // disabled — and only then checked against the delegation. Attributing against the offerable
+            // subset (or against the delegation itself) would widen it: with `wiki` delegated and
+            // `wiki_extra` merely declared, `wiki_extra__read` starts with `wiki_` and would be handed
+            // over as a `wiki` tool. The longest match over the widest declared set is the only reading
+            // that no missing row can loosen.
+            const delegatedSet = new Set(delegated.servers);
+            // ⚠️ And the attribution is then required to land on a server that is still OFFERABLE — the
+            // narrow set, enabled and confirmed. Wide for attribution, narrow for permission: a portal
+            // that switches a server off takes it away from the agent here, which is revocation reaching
+            // an agent without anybody touching its definition (D30).
+            const offerable = new Set(directory.servers.map((server) => server.handle));
+            remote = remote.filter((tool) => {
+                const handle = serverOf(tool.name, directory.declared);
+                if (handle === null || !delegatedSet.has(handle) || !offerable.has(handle))
+                    return false;
+                serverOfTool.set(tool.name, handle);
+                return true;
+            });
+        }
         const items = [];
         for (const tool of remote) {
             items.push({
@@ -59,27 +145,63 @@ export function createTools(deps) {
                 }),
             });
         }
-        return items;
+        return { items, serverOfTool };
+    }
+    /**
+     * ⚠️ The refusal that costs nothing. A delegated caller naming a tool outside every delegated
+     * namespace is turned away here — before the token store, before `tools/list`, before the portal
+     * hears anything at all. The authoritative cut still happens in `capabilities`, against the
+     * portal's directory; this one exists so the portal is never touched on behalf of a call that was
+     * always going to be refused, and so the refusal can name the tool and the servers (D30).
+     */
+    function requireDelegated(who, name) {
+        const delegated = who.delegation;
+        if (!delegated)
+            return;
+        if (delegatesNothing(who)) {
+            throw new IntelError(403, "tool_not_delegated", `${name} is not available: this agent has no delegated MCP servers`);
+        }
+        if (serverOf(name, delegated.servers) === null) {
+            throw new IntelError(403, "tool_not_delegated", `${name} is not part of this agent's delegated servers (${delegated.servers.join(", ")})`);
+        }
     }
-    async function requireCapability(actor, name) {
-        const found = (await capabilities(actor)).find((capability) => capability.name === name);
+    async function requireCapability(who, name) {
+        const reachable = await capabilities(who);
+        const found = reachable.items.find((capability) => capability.name === name);
         if (!found) {
             throw new IntelError(404, "tool_not_available", `Tool ${name} is not available to you`);
         }
-        return found;
+        return { capability: found, server: reachable.serverOfTool.get(name) };
     }
-    async function call(actor, input) {
-        if (!actor.canExecute) {
+    async function call(who, input) {
+        if (!who.actor.canExecute) {
             throw new IntelError(403, "tool_execute_forbidden", "Tool execution permission is required");
         }
-        const capability = await requireCapability(actor, input.name);
+        requireDelegated(who, input.name);
+        const { capability, server } = await requireCapability(who, input.name);
         const validation = deps.validate(capability.inputSchema, input.arguments);
         if (!validation.valid) {
             throw new IntelError(400, "tool_arguments_invalid", validation.detail ?? "Invalid arguments");
         }
+        // ⚠️ Written before the call, not after it: an audit that only records what succeeded is a
+        // record of the harmless half. Both principals are named — the agent that acted and the person
+        // whose connection carried it (D30) — and no argument is.
+        //
+        // ⚠️ The server is the one the CUT used, carried out of `capabilities`, not a second guess made
+        // against the delegated handles. Re-deriving it here would name `wiki` for a tool the cut
+        // attributed to `wiki_extra`, and an audit row that names the wrong system is worse than none.
+        if (who.delegation) {
+            await deps.audit({
+                agentId: who.delegation.agentId,
+                applicationId: who.actor.id,
+                delegatedBy: who.delegation.delegatedBy,
+                server: server ?? "",
+                tool: capability.name,
+            });
+        }
         const result = await deps.remote.call({
             url: portal(),
-            accessToken: await accessToken(actor),
+            accessToken: await accessToken(who),
             name: capability.name,
             arguments: input.arguments,
             signal: AbortSignal.timeout(CallTimeoutMs),
@@ -89,41 +211,78 @@ export function createTools(deps) {
         }
         return result;
     }
+    // A token that is gone or beyond renewal is the same answer as never having signed in, so reading
+    // a catalog reports it as a state. Only a portal that does not answer stays an error — the view
+    // has to tell "sign in again" apart from "the portal failed", and a 401 here would otherwise look
+    // like an expired Intel session to the browser.
+    function disconnected(error) {
+        return (error instanceof IntelError &&
+            (error.code === "portal_not_connected" || error.code === "portal_reconnect_required"));
+    }
     return {
         async catalog(actor) {
-            const stored = await deps.tokens.read(actor.id);
+            const who = await acting(actor);
+            if (delegatesNothing(who))
+                return { portalConnected: true, items: [] };
+            const stored = await deps.tokens.read(who.connectionOf);
             // No portal sign-in yet is a normal state, not an error: the browser answers it by running
-            // the silent sign-in and asking again (#60).
+            // the silent sign-in and asking again (#60). For an agent it is the ordinary shape of
+            // revocation — the delegator disconnected, so the agent reaches nothing (D30).
+            if (!stored)
+                return { portalConnected: false, items: [] };
+            try {
+                return { portalConnected: true, items: (await capabilities(who)).items };
+            }
+            catch (error) {
+                if (disconnected(error))
+                    return { portalConnected: false, items: [] };
+                throw error;
+            }
+        },
+        async servers(actor) {
+            const who = await acting(actor);
+            if (delegatesNothing(who))
+                return { portalConnected: true, items: [] };
+            const stored = await deps.tokens.read(who.connectionOf);
             if (!stored)
                 return { portalConnected: false, items: [] };
             try {
-                return { portalConnected: true, items: await capabilities(actor) };
+                const remote = await remoteTools(who);
+                const { servers } = await serverList(who, remote.map((tool) => tool.name));
+                // ⚠️ An agent sees its own delegation, never the delegator's whole shelf. Its catalog is cut
+                // anyway, so the uncut list would grant nothing — it would only tell an agent, and through
+                // it a model, which other systems the person it acts for is connected to.
+                const delegated = who.delegation;
+                return {
+                    portalConnected: true,
+                    items: delegated
+                        ? servers.filter((server) => delegated.servers.includes(server.handle))
+                        : servers,
+                };
             }
             catch (error) {
-                // A token that is gone or beyond renewal is the same answer as never having signed in, so
-                // reading the catalog reports it as a state. Only a portal that does not answer stays an
-                // error — the view has to tell "sign in again" apart from "the portal failed", and a 401
-                // here would otherwise look like an expired Intel session to the browser.
-                if (error instanceof IntelError &&
-                    (error.code === "portal_not_connected" || error.code === "portal_reconnect_required")) {
+                if (disconnected(error))
                     return { portalConnected: false, items: [] };
-                }
                 throw error;
             }
         },
-        execute: async (actor, input) => await call(actor, input),
+        execute: async (actor, input) => await call(await acting(actor), input),
         async test(actor, input) {
-            const capability = await requireCapability(actor, input.name);
+            const who = await acting(actor);
+            requireDelegated(who, input.name);
+            const { capability } = await requireCapability(who, input.name);
             if (capability.annotations.readOnlyHint !== true ||
                 capability.annotations.destructiveHint === true) {
                 throw new IntelError(409, "tool_test_unsafe", "Only explicitly read-only, non-destructive tools can run in the test surface");
             }
-            return await call(actor, input);
+            return await call(who, input);
         },
         async unavailable(actor, names) {
             if (names.length === 0)
                 return [];
-            const available = new Set((await capabilities(actor)).map((capability) => capability.name));
+            const who = await acting(actor);
+            const reachable = await capabilities(who);
+            const available = new Set(reachable.items.map((capability) => capability.name));
             return names.filter((name) => !available.has(name));
         },
     };

package/dist/tools/tools.types.d.ts

@@ -1,4 +1,4 @@
-import type { ExecuteToolInput, TestToolInput, ToolCapability, ToolCatalog, ToolTestResult } from "@anchrd/intel-contract";
+import type { ExecuteToolInput, TestToolInput, ToolCapability, ToolCatalog, ToolServerCatalog, ToolTestResult } from "@anchrd/intel-contract";
 export interface ToolActor {
     id: string;
     email: string;
@@ -35,6 +35,25 @@ export interface RemoteTools {
         signal: AbortSignal;
     }): Promise<ToolTestResult>;
 }
+/**
+ * What an agent's definition delegates, resolved from the Gate Application the caller authenticated
+ * as (D30). `null` from the port means "this caller is not an agent" — the ordinary user path.
+ *
+ * ⚠️ Read fresh on every call and never cached as a permission. It is the same rule the catalog
+ * follows: the answer has to be able to change between two runs without anybody editing anything.
+ */
+export interface ToolDelegation {
+    agentId: string;
+    delegatedBy: string;
+    servers: string[];
+}
+export interface ToolAuditEvent {
+    agentId: string;
+    applicationId: string;
+    delegatedBy: string;
+    server: string;
+    tool: string;
+}
 export interface ToolDeps {
     portalUrl: string | null;
     remote: RemoteTools;
@@ -47,9 +66,12 @@ export interface ToolDeps {
         valid: boolean;
         detail?: string;
     };
+    delegation(applicationId: string): Promise<ToolDelegation | null>;
+    audit(event: ToolAuditEvent): Promise<void>;
 }
 export interface ToolService {
     catalog(actor: ToolActor): Promise<ToolCatalog>;
+    servers(actor: ToolActor): Promise<ToolServerCatalog>;
     execute(actor: ToolActor, input: ExecuteToolInput): Promise<ToolTestResult>;
     test(actor: ToolActor, input: TestToolInput): Promise<ToolTestResult>;
     unavailable(actor: ToolActor, names: string[]): Promise<string[]>;