@anchrd/intel-api 0.10.0 → 0.12.0

package/README.md

@@ -98,6 +98,34 @@ routes answer `503 agent_runtime_not_configured` and nothing else changes. Deplo
 before an Intel deployment that declares it — Wrangler refuses a binding to a service that does not
 exist yet.
 
+### What an agent costs, and what a model costs
+
+Two figures on the agent screen come from Cloudflare rather than from a table in this repository:
+what one agent has actually spent, per run and over the last 7 and 30 days, and what each offered
+model charges per million tokens. Both are read by Intel and never by the browser, because reading
+them needs an account credential and a credential does not belong in a single-page app.
+
+Set `AI_GATEWAY_ACCOUNT_ID` and `AI_GATEWAY_ID` — the same account and gateway the agent runtime
+uses — and add a Wrangler secret:
+
+```sh
+wrangler secret put AI_GATEWAY_READ_TOKEN   # Cloudflare API token: "AI Gateway: Read" + "Workers AI: Read"
+```
+
+⚠️ **This is not the runtime's `AI_GATEWAY_TOKEN`.** That one carries `AI Gateway: Run` and buys
+inference; this one only reads. Cloudflare cannot scope `AI Gateway: Read` to a single gateway — it
+is account-wide — which is worth knowing when the token is created and is not a reason against it.
+
+All three are optional. Without them the cost view says *"this installation has no AI Gateway read
+token"* and the model figures come off a built-in table that the interface marks as possibly out of
+date. Neither is an error state: an installation that gives Intel no Cloudflare credential is a
+supported installation. What is never done is show a zero — a missing figure and "cost nothing" are
+different answers, and only one of them is about money.
+
+The attribution comes from the agent runtime, which stamps `agentId` and `runId` into
+`cf-aig-metadata` on every model call. Runs made before that stamp existed appear with their token
+counts and without a cost, and say so.
+
 ### Creating an agent creates its Gate application
 
 An agent acts as its own machine principal, so creating an agent node also creates the Gate

package/dist/adapters/cloudflare/cloudflare.js

@@ -1,15 +1,18 @@
 import { createGateClient } from "@anchrd/gate-sdk";
 import { ulid } from "ulid";
+import { createAgentCosts } from "../../agent-costs/agent-costs.js";
 import { createAgentRuntimeService } from "../../agent-runtime/agent-runtime.js";
 import { createBrowserAuth } from "../../auth/auth.js";
 import { createBundle } from "../../bundle/bundle.js";
 import { createFlows } from "../../flows/flows.js";
 import { createIndexing, PermanentIndexingError } from "../../indexing/indexing.js";
 import { createIntel } from "../../intel/intel.js";
+import { createModelCatalog } from "../../model-catalog/model-catalog.js";
 import { createNodes } from "../../nodes/nodes.js";
 import { IntelError } from "../../shared/intel-error/intel-error.js";
 import { sha256Hex } from "../../shared/sha256/sha256.js";
 import { createTools } from "../../tools/tools.js";
+import { createCloudflareApi } from "../cloudflare-api/cloudflare-api.js";
 import { createContentStore } from "../content/content.js";
 import { createNodeRepository } from "../db/db.js";
 import { createFlowRepository } from "../db/db-flows.js";
@@ -133,6 +136,28 @@ export default {
             // same question as whether they may see the node, and no second answer is invented here.
             visibleNode: async (actor, nodeId) => await nodes.visibleNode(actor, nodeId),
         });
+        // ⚠️ One Cloudflare read client for both of the account's answers — the gateway's cost log
+        // (#251) and the Workers AI price list (#257) — because it is one token and one account. It is
+        // absent as a whole where any of the three variables is missing: a half-configured client would
+        // fail per call with a 401 that reads like a permission problem instead of saying, once, that
+        // this deployment was never given a token.
+        const gatewayAccountId = env.AI_GATEWAY_ACCOUNT_ID?.trim();
+        const gatewayId = env.AI_GATEWAY_ID?.trim();
+        const gatewayReadToken = env.AI_GATEWAY_READ_TOKEN?.trim();
+        const cloudflareApi = gatewayAccountId && gatewayId && gatewayReadToken
+            ? createCloudflareApi({
+                accountId: gatewayAccountId,
+                gatewayId,
+                token: gatewayReadToken,
+                fetch: globalThis.fetch.bind(globalThis),
+            })
+            : undefined;
+        const agentCosts = createAgentCosts({
+            ...(cloudflareApi ? { gateway: cloudflareApi } : {}),
+            visibleNode: async (actor, nodeId) => await nodes.visibleNode(actor, nodeId),
+            now,
+        });
+        const models = createModelCatalog({ ...(cloudflareApi ? { cloudflare: cloudflareApi } : {}) });
         const nodes = createNodes({
             repository: nodeRepository,
             content: contentStore,
@@ -223,6 +248,8 @@ export default {
                 indexing: createIndexQueue(env.INDEXING),
             }),
             agents,
+            agentCosts,
+            models,
             auth,
         }).fetch(request);
     },

package/dist/adapters/cloudflare/cloudflare.types.d.ts

@@ -39,6 +39,25 @@ export interface CloudflareEnv {
      * it is absent, creating an agent refuses by name instead of leaving one without a key.
      */
     AGENT_HANDOVER_SECRET?: string;
+    /**
+     * Where the AI Gateway lives and how to READ it (#251, #257).
+     *
+     * ⚠️ `AI_GATEWAY_READ_TOKEN` is not the agent runtime's `AI_GATEWAY_TOKEN` and must never be the
+     * same value. That one carries `AI Gateway: Run` and buys inference; this one carries
+     * `AI Gateway: Read` — plus `Workers AI: Read` for the model catalog — and buys nothing at all.
+     * One credential doing both would put a spending permission into the Worker that only reads.
+     *
+     * ⚠️ Cloudflare cannot scope `AI Gateway: Read` to a single gateway; it is account-wide, the same
+     * limitation `AI Gateway: Run` already had in #239. It is worth knowing when the token is created
+     * and is not a reason against the route: it reads and writes nothing.
+     *
+     * ⚠️ All three optional, together. A deployment that configures none of them gets a cost view that
+     * says "not configured" and a model catalog off the built-in table — both named states, neither an
+     * error. Intel without a Cloudflare token is a supported installation.
+     */
+    AI_GATEWAY_ACCOUNT_ID?: string;
+    AI_GATEWAY_ID?: string;
+    AI_GATEWAY_READ_TOKEN?: string;
     TOOL_SOURCE_ORIGINS: string;
     MCP_PORTAL_URL?: string;
     ALLOW_INSECURE_OAUTH?: string;

package/dist/adapters/cloudflare-api/cloudflare-api.d.ts

@@ -0,0 +1,22 @@
+import type { CloudflareAccountApi } from "./cloudflare-api.types.js";
+/**
+ * ⚠️ `Authorization: Bearer`, and NOT `cf-aig-authorization`. The two hosts take different headers
+ * and the agent runtime uses the other one: `gateway.ai.cloudflare.com` reads
+ * `cf-aig-authorization`, this REST host reads the plain header. Swapping them produces a 401 that
+ * says nothing about which of the two was wrong.
+ */
+export interface CloudflareApiDeps {
+    accountId: string;
+    gatewayId: string;
+    /**
+     * A Cloudflare API token, read-only by intent.
+     *
+     * ⚠️ It is NOT the `AI_GATEWAY_TOKEN` the agent runtime holds. That one carries
+     * `AI Gateway: Run` and buys inference; this one carries `AI Gateway: Read` (and, for the model
+     * catalog, `Workers AI: Read`) and buys nothing at all. One credential for both would put a
+     * spending permission into the Worker that only ever reads.
+     */
+    token: string;
+    fetch: typeof fetch;
+}
+export declare function createCloudflareApi(deps: CloudflareApiDeps): CloudflareAccountApi;

package/dist/adapters/cloudflare-api/cloudflare-api.js

@@ -0,0 +1,189 @@
+import { z } from "zod";
+import { IntelError } from "../../shared/intel-error/intel-error.js";
+const ApiOrigin = "https://api.cloudflare.com/client/v4";
+/**
+ * How many pages of gateway log are read before the answer is declared a floor.
+ *
+ * A run is several model turns and a five-minute schedule is 8 640 runs a month, so "read
+ * everything" is not on the table. Ten pages of a hundred is the last thirty days of a busy agent
+ * or the last few days of a very busy one; past that the screen says "at least this much" rather
+ * than a number nobody can check.
+ */
+const MaxPages = 10;
+const PerPage = 100;
+/**
+ * The gateway's log entry, read tolerantly.
+ *
+ * ⚠️ `metadata` arrives as an object on some responses and as a JSON string on others, and neither
+ * is documented as the one shape. Both are accepted; anything else means the call is unattributed,
+ * which is a state the caller can see rather than a parse failure that blanks the whole window.
+ */
+const LogEntry = z.object({
+    cost: z.number().nullish(),
+    model: z.string().nullish(),
+    created_at: z.string().nullish(),
+    metadata: z.union([z.string(), z.record(z.string(), z.unknown())]).nullish(),
+});
+/**
+ * ⚠️ `result` is required, only its contents may be null. An optional field would let ANY JSON body
+ * parse as an empty page — and an empty page reads as "this agent cost nothing", which is the one
+ * answer this whole path exists to avoid giving by accident.
+ */
+const LogResponse = z.object({
+    success: z.boolean().nullish(),
+    result: z.array(LogEntry).nullable(),
+});
+function readMetadata(raw) {
+    if (typeof raw === "string") {
+        try {
+            const parsed = JSON.parse(raw);
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed
+                : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    return raw && typeof raw === "object" && !Array.isArray(raw)
+        ? raw
+        : {};
+}
+/**
+ * ⚠️ Cloudflare's `properties` are a list of `{property_id, value}` pairs, not fields, and `value`
+ * is a string for the scalars and an array of `{unit, price, currency}` for the price. The units are
+ * the provider's own wording — "per M input tokens" — so they are matched loosely and never parsed
+ * as a contract: an unrecognised unit costs a missing price, and a missing price shows nothing,
+ * which is the behaviour #257 asks for anyway.
+ */
+const PriceEntry = z.object({
+    unit: z.string(),
+    price: z.union([z.number(), z.string()]),
+    currency: z.string().nullish(),
+});
+const ModelProperty = z.object({
+    property_id: z.string(),
+    value: z.union([z.string(), z.number(), z.boolean(), z.array(PriceEntry)]),
+});
+const ModelEntry = z.object({
+    name: z.string(),
+    properties: z.array(ModelProperty).nullish(),
+});
+// Required for the same reason `LogResponse.result` is: a body this reader does not recognise must
+// not come out as "the account offers no models".
+const ModelResponse = z.object({
+    success: z.boolean().nullish(),
+    result: z.array(ModelEntry).nullable(),
+});
+function propertyOf(properties, id) {
+    return properties.find((property) => property.property_id === id)?.value;
+}
+function priceFor(entries, side) {
+    const found = entries.find((entry) => {
+        const unit = entry.unit.toLowerCase();
+        return unit.includes(side) && unit.includes("token") && /\bm\b|million/.test(unit);
+    });
+    if (!found)
+        return undefined;
+    const value = typeof found.price === "string" ? Number(found.price) : found.price;
+    return Number.isFinite(value) ? value : undefined;
+}
+function readModel(entry) {
+    const properties = entry.properties ?? [];
+    const context = Number(propertyOf(properties, "context_window"));
+    const rawPrice = propertyOf(properties, "price");
+    const prices = Array.isArray(rawPrice) ? rawPrice : [];
+    const input = priceFor(prices, "input");
+    const output = priceFor(prices, "output");
+    return {
+        name: entry.name,
+        contextTokens: Number.isFinite(context) && context > 0 ? context : null,
+        // ⚠️ Both halves or neither. A model shown with an input price and no output price reads as if
+        // its answers were free, which is a worse statement than saying nothing.
+        price: input !== undefined && output !== undefined
+            ? { inputPerMillion: input, outputPerMillion: output }
+            : null,
+        functionCalling: String(propertyOf(properties, "function_calling") ?? "") === "true",
+    };
+}
+export function createCloudflareApi(deps) {
+    /**
+     * ⚠️ Neither the URL nor the body of a refusal is quoted onward. The URL carries the account id
+     * and the body carries whatever Cloudflare wrote about a token; this message is read by a person
+     * on a screen and by a model through the MCP surface alike. The status is kept, because it is the
+     * whole of what an operator can act on: 401/403 is the token's permissions, 404 is the gateway id,
+     * 429 is a limit.
+     */
+    async function get(path, query) {
+        const url = new URL(`${ApiOrigin}${path}`);
+        for (const [key, value] of Object.entries(query))
+            url.searchParams.set(key, value);
+        let response;
+        try {
+            response = await deps.fetch(url, {
+                headers: { authorization: `Bearer ${deps.token}`, accept: "application/json" },
+            });
+        }
+        catch {
+            throw new IntelError(502, "cloudflare_api_unreachable", "The Cloudflare API did not answer");
+        }
+        if (!response.ok) {
+            throw new IntelError(502, "cloudflare_api_refused", `The Cloudflare API refused this read (HTTP ${response.status})`);
+        }
+        return await response.json().catch(() => null);
+    }
+    return {
+        async gatewayCalls(query) {
+            const calls = [];
+            let partial = false;
+            for (let page = 1; page <= MaxPages; page += 1) {
+                const body = await get(`/accounts/${encodeURIComponent(deps.accountId)}/ai-gateway/gateways/${encodeURIComponent(deps.gatewayId)}/logs`, {
+                    page: String(page),
+                    per_page: String(PerPage),
+                    start_date: query.since.toISOString(),
+                    end_date: query.until.toISOString(),
+                    order_by: "created_at",
+                    order_by_direction: "desc",
+                    // ⚠️ Only documented scalar parameters travel. The endpoint also takes a `filters` array
+                    // whose query encoding Cloudflare documents nowhere — neither the reference nor the
+                    // curl example shows it — so a guess at it would either be ignored (a slow read) or
+                    // rejected (no read at all), and there is no way to tell those apart from the status.
+                    // The agent is therefore picked out below, from the metadata the runtime stamped.
+                });
+                const parsed = LogResponse.safeParse(body);
+                // A shape this reader cannot make sense of is a failure, not an empty window: an empty
+                // window reads as "this agent cost nothing".
+                if (!parsed.success) {
+                    throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered in a shape this version does not understand");
+                }
+                const entries = parsed.data.result ?? [];
+                for (const entry of entries) {
+                    const metadata = readMetadata(entry.metadata);
+                    if (metadata.agentId !== query.agentId)
+                        continue;
+                    calls.push({
+                        runId: typeof metadata.runId === "string" ? metadata.runId : null,
+                        model: entry.model ?? "",
+                        cost: entry.cost ?? 0,
+                        at: entry.created_at ?? query.until.toISOString(),
+                    });
+                }
+                if (entries.length < PerPage)
+                    return { calls, partial: false };
+                partial = page === MaxPages;
+            }
+            return { calls, partial };
+        },
+        async workersAiModels() {
+            const body = await get(`/accounts/${encodeURIComponent(deps.accountId)}/ai/models/search`, {
+                per_page: "200",
+                hide_experimental: "true",
+            });
+            const parsed = ModelResponse.safeParse(body);
+            if (!parsed.success) {
+                throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered in a shape this version does not understand");
+            }
+            return (parsed.data.result ?? []).map(readModel);
+        },
+    };
+}

package/dist/adapters/cloudflare-api/cloudflare-api.types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The two things Intel reads out of the Cloudflare account, and nothing else.
+ *
+ * ⚠️ Both are READS, and the port says so by having no other verb. The token behind it is
+ * account-wide — Cloudflare offers no per-gateway scope for `AI Gateway: Read`, the same limitation
+ * `AI Gateway: Run` already had in #239 — so the narrowness has to come from what this interface
+ * can express rather than from what the credential allows.
+ */
+export interface CloudflareAccountApi {
+    /**
+     * The gateway's own log lines for one agent, within a window.
+     *
+     * ⚠️ `cost` here is the **debit from the Cloudflare balance**, 1:1 — measured on 2026-08-07
+     * against the running installation: balance $19.77 + spend $0.23 = the $20.00 that was loaded.
+     * Cloudflare takes its 5 % when the balance is topped up and passes inference through without a
+     * markup, so this number means "what this costs us" and needs no conversion. A reader who
+     * multiplied it by anything would be inventing a second, wrong price.
+     */
+    gatewayCalls(query: GatewayCallQuery): Promise<GatewayCallPage>;
+    /**
+     * What Cloudflare currently charges for the models it serves itself (#257).
+     *
+     * ⚠️ Workers AI only. Cloudflare publishes no price list for the Anthropic models it resells
+     * through Unified Billing, so those figures have no live source and stay a table — which is the
+     * whole reason the catalog says, per entry, where its numbers came from.
+     */
+    workersAiModels(): Promise<WorkersAiModel[]>;
+}
+export interface GatewayCallQuery {
+    /** The value stamped as `cf-aig-metadata.agentId` by the agent runtime. */
+    agentId: string;
+    since: Date;
+    until: Date;
+}
+export interface GatewayCall {
+    /** From `cf-aig-metadata.runId`. `null` for a call made before the stamp existed. */
+    runId: string | null;
+    model: string;
+    /** US dollars, as billed. */
+    cost: number;
+    at: string;
+}
+export interface GatewayCallPage {
+    calls: GatewayCall[];
+    /**
+     * The window was cut off at the page cap, so every total built from it is a floor rather than a
+     * total.
+     *
+     * ⚠️ It exists so the screen can say "at least". A sum that silently stopped counting is the same
+     * failure as a missing number pretending to be zero, only harder to notice.
+     */
+    partial: boolean;
+}
+export interface WorkersAiModel {
+    /** The full `@cf/...` id, exactly as a definition names it. */
+    name: string;
+    contextTokens: number | null;
+    price: {
+        inputPerMillion: number;
+        outputPerMillion: number;
+    } | null;
+    /** Whether this model can call a tool at all. An agent is a tool loop; one that cannot is useless. */
+    functionCalling: boolean;
+}

package/dist/adapters/cloudflare-api/cloudflare-api.types.js

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

package/dist/agent-costs/agent-costs.d.ts

@@ -0,0 +1,16 @@
+import type { AgentCostsDeps, AgentCostsService } from "./agent-costs.types.js";
+/**
+ * What this agent has cost, read out of Cloudflare's AI Gateway log rather than computed here.
+ *
+ * ⚠️ Nothing in this file multiplies tokens by a price, and nothing may start to. The gateway
+ * publishes the billed figure per call and it is the debit from the account balance, 1:1 — measured
+ * on 2026-08-07 (#251). A price table beside it would be a second, self-maintained answer to a
+ * question that already has a first one, and the day the two disagree the wrong one is the one
+ * on screen.
+ *
+ * ⚠️ The three checks below are in the same order as the runtime proxy's, and for the same reasons:
+ * the capability first so a refusal costs no storage read; the resource ACL second, because seeing
+ * an agent and seeing its bill are the same question; the reader last, so nobody learns whether this
+ * deployment holds a Cloudflare token before they are allowed to ask.
+ */
+export declare function createAgentCosts(deps: AgentCostsDeps): AgentCostsService;

package/dist/agent-costs/agent-costs.js

@@ -0,0 +1,105 @@
+import { IntelError } from "../shared/intel-error/intel-error.js";
+/**
+ * The windows the profile shows, longest last.
+ *
+ * Two, and both of them, because they answer different questions: thirty days is what an agent
+ * costs to keep, seven is whether that changed. One number alone cannot say "this got more
+ * expensive last week".
+ */
+const Windows = [7, 30];
+const DayMs = 24 * 60 * 60 * 1_000;
+/**
+ * What this agent has cost, read out of Cloudflare's AI Gateway log rather than computed here.
+ *
+ * ⚠️ Nothing in this file multiplies tokens by a price, and nothing may start to. The gateway
+ * publishes the billed figure per call and it is the debit from the account balance, 1:1 — measured
+ * on 2026-08-07 (#251). A price table beside it would be a second, self-maintained answer to a
+ * question that already has a first one, and the day the two disagree the wrong one is the one
+ * on screen.
+ *
+ * ⚠️ The three checks below are in the same order as the runtime proxy's, and for the same reasons:
+ * the capability first so a refusal costs no storage read; the resource ACL second, because seeing
+ * an agent and seeing its bill are the same question; the reader last, so nobody learns whether this
+ * deployment holds a Cloudflare token before they are allowed to ask.
+ */
+export function createAgentCosts(deps) {
+    return {
+        async read(actor, agentId) {
+            if (!actor.canRun) {
+                throw new IntelError(403, "permission_required", "Permission required");
+            }
+            const node = await deps.visibleNode(actor, agentId);
+            // Not found and not visible answer alike, as everywhere else in the tree.
+            if (node?.kind !== "agent") {
+                throw new IntelError(404, "agent_not_found", "Agent was not found");
+            }
+            if (!deps.gateway)
+                return empty("not_configured");
+            const until = deps.now();
+            const longest = Windows[Windows.length - 1] ?? 30;
+            const since = new Date(until.getTime() - longest * DayMs);
+            let page;
+            try {
+                page = await deps.gateway.gatewayCalls({ agentId, since, until });
+            }
+            catch {
+                // ⚠️ Swallowed on purpose, and named rather than rethrown. The run list beside these figures
+                // is answered by the runtime and is perfectly readable; letting a Cloudflare outage take the
+                // whole screen down would hide the tokens too — and the tokens are the half that never
+                // depended on Cloudflare being reachable.
+                return empty("unreadable");
+            }
+            return {
+                status: "read",
+                currency: "USD",
+                runs: perRun(page.calls),
+                windows: Windows.map((days) => window(days, page.calls, until)),
+                partial: page.partial,
+            };
+        },
+    };
+}
+function empty(status) {
+    return {
+        status,
+        currency: "USD",
+        // ⚠️ Empty, and the status is what stops it reading as "free". Nothing here invents a zero:
+        // `runs: []` with `status: "read"` really does mean this agent has cost nothing yet.
+        runs: [],
+        windows: Windows.map((days) => ({ days, cost: 0, calls: 0, models: [] })),
+        partial: false,
+    };
+}
+function perRun(calls) {
+    const byRun = new Map();
+    for (const call of calls) {
+        // A call the runtime could not stamp — anything from before #251 — belongs to no run and is
+        // dropped from the per-run view. It still counts towards the windows below: it is the agent's
+        // money either way, and only its place in the list is unknown.
+        if (!call.runId)
+            continue;
+        const known = byRun.get(call.runId);
+        if (known) {
+            known.cost += call.cost;
+            known.calls += 1;
+            continue;
+        }
+        byRun.set(call.runId, { runId: call.runId, cost: call.cost, calls: 1 });
+    }
+    return [...byRun.values()];
+}
+function window(days, calls, until) {
+    const from = until.getTime() - days * DayMs;
+    const inside = calls.filter((call) => {
+        const at = Date.parse(call.at);
+        // An unparseable timestamp counts towards the longest window rather than being dropped: the
+        // money was spent, and a total that quietly omits it is the wrong kind of wrong.
+        return Number.isNaN(at) ? days === Windows[Windows.length - 1] : at >= from;
+    });
+    return {
+        days,
+        cost: inside.reduce((total, call) => total + call.cost, 0),
+        calls: inside.length,
+        models: [...new Set(inside.map((call) => call.model).filter((model) => model.length > 0))],
+    };
+}

package/dist/agent-costs/agent-costs.types.d.ts

@@ -0,0 +1,30 @@
+import type { AgentCosts, Node } from "@anchrd/intel-contract";
+import type { CloudflareAccountApi } from "../adapters/cloudflare-api/cloudflare-api.types.js";
+import type { AgentActor } from "../agent-runtime/agent-runtime.types.js";
+import type { Actor } from "../nodes/nodes.types.js";
+export interface AgentCostsDeps {
+    /**
+     * Absent where the deployment configured no account id, gateway id or read token.
+     *
+     * ⚠️ Absent is a NAMED state and never an error: an installation that never wants Intel to hold a
+     * Cloudflare token is a supported installation, and it should read "not configured" rather than
+     * a 502 somebody spends an afternoon on.
+     */
+    gateway?: Pick<CloudflareAccountApi, "gatewayCalls">;
+    /**
+     * The tree's own visibility lookup, unchanged on the way through — the same one the runtime proxy
+     * uses. What an agent spends is as sensitive as what it does, and neither answer may be kinder
+     * than the other.
+     */
+    visibleNode(actor: Actor, nodeId: string): Promise<Node | null>;
+    now(): Date;
+}
+export interface AgentCostsService {
+    /**
+     * ⚠️ The answer shape lives in `@anchrd/intel-contract` and not here, because the browser parses
+     * it. A second declaration in this package is how the screen and the service start disagreeing
+     * about what `status` can say — and `status` is the field that separates "cost nothing" from "not
+     * known" (#251).
+     */
+    read(actor: AgentActor, agentId: string): Promise<AgentCosts>;
+}

package/dist/agent-costs/agent-costs.types.js

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

package/dist/build/build.js

@@ -1,3 +1,4 @@
+import { UI_LANGUAGES } from "@anchrd/intel-contract";
 import { z } from "zod";
 const UiConfig = z.strictObject({
     theme: z.string().min(1).optional(),
@@ -100,8 +101,12 @@ export function createBuild(deps) {
                     }
                     catalogs[language] = candidateParsed.data;
                 }
-                if (config.defaultLanguage !== "en" && !(config.defaultLanguage in catalogs)) {
-                    throw new Error(`ui.defaultLanguage ${JSON.stringify(config.defaultLanguage)} is not listed in ui.languages`);
+                // A built-in language needs no entry in ui.languages — its catalog is already in the UI.
+                // Without this exception, `ui.defaultLanguage: "de"` would force the customer to list a copy
+                // of de.json that rots at every UI update, and nobody maintains that copy.
+                const builtIn = UI_LANGUAGES;
+                if (!builtIn.includes(config.defaultLanguage) && !(config.defaultLanguage in catalogs)) {
+                    throw new Error(`ui.defaultLanguage ${JSON.stringify(config.defaultLanguage)} is neither built in (${UI_LANGUAGES.join(", ")}) nor listed in ui.languages`);
                 }
                 const theme = config.theme
                     ? `/* Generated by \`intel build\` from ${asComment(config.theme)}. */\n${await readRequired(config.theme, "ui.theme")}\n`

package/dist/bundle/bundle.js

@@ -3,6 +3,7 @@ import { Unzip, UnzipInflate, Zip, ZipDeflate, ZipPassThrough } from "fflate";
 import { documentLinkTargets } from "../nodes/document-links/document-links.js";
 import { parseCsv } from "../shared/csv/csv.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
+import { plainTitle } from "../shared/plain-title/plain-title.js";
 // What every bundle leaves out, by decision rather than by accident (#136). The manifest says so,
 // because a backup that is silent about what it does not hold will be trusted with exactly that.
 const Excluded = ["version-history", "grants", "flow-runs", "archived-nodes"];
@@ -866,7 +867,7 @@ export function createBundle(deps) {
                     flows.push({
                         id: entry.newId,
                         parentId,
-                        title: entry.title,
+                        title: plainTitle(entry.title),
                         description: entry.description,
                         ownerId: actor.id,
                         currentVersionId: versionId,
@@ -953,7 +954,9 @@ export function createBundle(deps) {
                     parentId,
                     // Flows took the `continue` above; what reaches here is one of the five node kinds.
                     kind: entry.kind,
-                    title: entry.title,
+                    // A manifest title and a file name are both somebody else's text, and an export written
+                    // by an escaping chain carries the entity in both (#202).
+                    title: plainTitle(entry.title),
                     description: entry.description,
                     ownerId: actor.id,
                     currentVersionId: version?.id ?? null,

package/dist/flows/flows.js

@@ -1,5 +1,6 @@
 import { flowNodeLayer } from "@anchrd/intel-contract";
 import { IntelError } from "../shared/intel-error/intel-error.js";
+import { plainTitle } from "../shared/plain-title/plain-title.js";
 function invalid(detail) {
     throw new IntelError(400, "flow_graph_invalid", detail);
 }
@@ -1071,7 +1072,7 @@ export function createFlows(deps) {
                 flow: {
                     id: deps.id(),
                     parentId: input.parentId,
-                    title: input.title,
+                    title: plainTitle(input.title),
                     description: input.description,
                     ownerId: actor.id,
                     currentVersionId: null,
@@ -1099,7 +1100,7 @@ export function createFlows(deps) {
                 flow: {
                     ...current,
                     parentId: input.parentId === undefined ? current.parentId : input.parentId,
-                    title: input.title ?? current.title,
+                    title: input.title === undefined ? current.title : plainTitle(input.title),
                     description: input.description === undefined ? current.description : input.description,
                     updatedAt: deps.now().toISOString(),
                 },

package/dist/http/http.js

@@ -144,6 +144,26 @@ export function createHttp(deps) {
     app.get("/capabilities", (context) => {
         return context.json({ agentRuntime: deps.agents.available() });
     });
+    /**
+     * What the models on offer cost and how much they hold (#257).
+     *
+     * ⚠️ Intel asks Cloudflare, never the browser. The account endpoint needs a token and a token does
+     * not belong in a SPA — which is the sentence the hard-coded table in `packages/ui` used to carry
+     * as the reason it stayed hard-coded. This route is the answer to it: the figures cross the wire,
+     * the credential does not.
+     *
+     * ⚠️ No capability beyond being signed in. It is a fact about the installation and about nobody's
+     * data — the same footing `/capabilities` stands on.
+     *
+     * ⚠️ The `cache-control` is the caching the ticket asks for, and it is the caching that matters:
+     * the waste it names is "one fetch every time the select is opened", and that fetch is the
+     * browser's. A Worker isolate has nowhere durable to keep a table between requests, and inventing
+     * storage for a list of prices would cost more than the request it saved.
+     */
+    app.get("/models", async (context) => {
+        context.header("cache-control", "private, max-age=3600");
+        return context.json(await deps.models.list());
+    });
     /**
      * The agent runtime, reached through Intel.
      *
@@ -171,6 +191,23 @@ export function createHttp(deps) {
         { method: "POST", pattern: "/resume", path: () => "/resume" },
         { method: "POST", pattern: "/run", path: () => "/run" },
     ];
+    /**
+     * What this agent has cost — answered by Intel itself, not forwarded (#251).
+     *
+     * ⚠️ It stands under `/agents/:agentId` and is NOT in `runtimeRoutes`, which is the whole point of
+     * writing it out here. The runtime has no idea what anything costs: the figures come from
+     * Cloudflare's AI Gateway log, which needs an `AI Gateway: Read` token, and that token belongs in
+     * Intel rather than in the Worker that executes model-driven tool calls — the runtime's own
+     * `CLAUDE.md` keeps the number of credentials there deliberately small. The runtime's part is the
+     * stamp on the model call and nothing more.
+     *
+     * ⚠️ `agents/run`, matching the run list this stands beside. What an agent spends is as sensitive
+     * as what it did, and the two must not be reachable on different terms.
+     */
+    app.get("/agents/:agentId/costs", async (context) => {
+        const authorization = context.get("authorization");
+        return context.json(await deps.agentCosts.read(asAgentActor(authorization), context.req.param("agentId")));
+    });
     for (const route of runtimeRoutes) {
         app.on(route.method, `/agents/:agentId${route.pattern}`, async (context) => {
             const authorization = context.get("authorization");

package/dist/http/http.types.d.ts

@@ -1,8 +1,10 @@
 import type { GateClient } from "@anchrd/gate-sdk";
+import type { AgentCostsService } from "../agent-costs/agent-costs.types.js";
 import type { AgentRuntimeService } from "../agent-runtime/agent-runtime.types.js";
 import type { BrowserAuth } from "../auth/auth.types.js";
 import type { BundleService } from "../bundle/bundle.types.js";
 import type { FlowService } from "../flows/flows.types.js";
+import type { ModelCatalogService } from "../model-catalog/model-catalog.types.js";
 import type { NodeService } from "../nodes/nodes.types.js";
 import type { ToolService } from "../tools/tools.types.js";
 export interface HttpDeps {
@@ -12,6 +14,10 @@ export interface HttpDeps {
     tools: ToolService;
     bundle: BundleService;
     agents: AgentRuntimeService;
+    /** What an agent has cost, read out of the AI Gateway log rather than computed here (#251). */
+    agentCosts: AgentCostsService;
+    /** What the models on offer cost, read from Cloudflare rather than typed out here (#257). */
+    models: ModelCatalogService;
     resource: string;
     resourceMetadataUrl: string;
     auth?: Pick<BrowserAuth, "resolve">;

package/dist/intel/intel.js

@@ -73,6 +73,8 @@ export function createIntel(deps) {
         tools: deps.tools,
         bundle: deps.bundle,
         agents: deps.agents,
+        agentCosts: deps.agentCosts,
+        models: deps.models,
         resource,
         resourceMetadataUrl,
         ...(deps.auth ? { auth: deps.auth } : {}),
@@ -91,6 +93,7 @@ export function createIntel(deps) {
             // returned a credential beside its answer would be one somebody logs.
             bearer: bearer(context.req.raw.headers) ?? "",
             agents: deps.agents,
+            agentCosts: deps.agentCosts,
             flows: deps.flows,
             nodes: deps.nodes,
             tools: deps.tools,

package/dist/intel/intel.types.d.ts

@@ -1,8 +1,10 @@
 import type { GateClient } from "@anchrd/gate-sdk";
+import type { AgentCostsService } from "../agent-costs/agent-costs.types.js";
 import type { AgentRuntimeService } from "../agent-runtime/agent-runtime.types.js";
 import type { BrowserAuth } from "../auth/auth.types.js";
 import type { BundleService } from "../bundle/bundle.types.js";
 import type { FlowService } from "../flows/flows.types.js";
+import type { ModelCatalogService } from "../model-catalog/model-catalog.types.js";
 import type { NodeService } from "../nodes/nodes.types.js";
 import type { ToolService } from "../tools/tools.types.js";
 export interface IntelDeps {
@@ -14,5 +16,7 @@ export interface IntelDeps {
     tools: ToolService;
     bundle: BundleService;
     agents: AgentRuntimeService;
+    agentCosts: AgentCostsService;
+    models: ModelCatalogService;
     auth?: BrowserAuth;
 }

package/dist/mcp/mcp.js

@@ -912,6 +912,29 @@ export async function handleMcp(request, deps) {
             path: "/resume",
             body: "{}",
         })));
+        /**
+         * ⚠️ The MCP half of the profile's cost figures, in the same delivery slice — the repository's
+         * "every user-visible capability has an Intel MCP equivalent" rule.
+         *
+         * ⚠️ Under `agents/run` beside pause and resume, not under `knowledge/read`. What an agent
+         * spends is as sensitive as what it did, and this answer stands beside the run list rather than
+         * beside the node.
+         *
+         * ⚠️ `status` travels with the numbers and is not flattened away. A client that read an empty
+         * `runs` list as "this agent is free" would be reporting a Cloudflare outage as a saving.
+         */
+        server.registerTool("agent_costs", {
+            title: "Agent costs",
+            description: "What one agent has actually cost, read from Cloudflare's AI Gateway log: per run, and as a total over the last 7 and 30 days. `status` says whether the numbers were read at all — `not_configured` and `unreadable` both mean no figures, never zero cost. `partial` means the read hit its page limit, so the totals are a floor.",
+            inputSchema: PauseAgentInput,
+            annotations: {
+                title: "Agent costs",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.agentCosts.read(agentActor, input.nodeId)));
         server.registerTool("agent_run_now", {
             title: "Run agent now",
             description: "Fire one of the agent's own schedules straight away, against the document or flow it names. The run appears in the agent's run list; a target the agent does not schedule is refused.",

package/dist/mcp/mcp.types.d.ts

@@ -1,4 +1,5 @@
 import type { Authorized } from "@anchrd/gate-sdk";
+import type { AgentCostsService } from "../agent-costs/agent-costs.types.js";
 import type { AgentRuntimeService } from "../agent-runtime/agent-runtime.types.js";
 import type { BundleService } from "../bundle/bundle.types.js";
 import type { FlowService } from "../flows/flows.types.js";
@@ -16,4 +17,6 @@ export interface McpDeps {
     tools: ToolService;
     bundle: BundleService;
     agents: AgentRuntimeService;
+    /** What an agent has cost, out of the AI Gateway log — the MCP half of the profile's figures (#251). */
+    agentCosts: AgentCostsService;
 }

package/dist/model-catalog/model-catalog.d.ts

@@ -0,0 +1,2 @@
+import type { ModelCatalogDeps, ModelCatalogService } from "./model-catalog.types.js";
+export declare function createModelCatalog(deps: ModelCatalogDeps): ModelCatalogService;

package/dist/model-catalog/model-catalog.js

@@ -0,0 +1,99 @@
+/**
+ * The figures this package knows without asking anybody, and the ONLY place they are written down.
+ *
+ * ⚠️ It moved here out of `packages/ui` with #257, and the move is the point rather than the
+ * tidying. The comment it used to carry accused itself correctly — *"it is a copy and it ages
+ * silently"* — and named the reason it stayed a copy: the Cloudflare endpoint needs a token, and a
+ * token does not belong in a SPA. It belongs here. What the browser gets is the answer, never the
+ * credential, and the Workers AI half of this table is overwritten by the live one on every read.
+ *
+ * ⚠️ The Anthropic entries have no live source and will not get one. Cloudflare resells those models
+ * through Unified Billing and publishes no price list for them, so they stay `builtin` even on a
+ * perfectly healthy read — which is exactly why `source` is per entry and not per response.
+ *
+ * ⚠️ Workers AI models without `function_calling` are deliberately absent from the live merge. An
+ * agent is a tool loop; a model that cannot call a tool cannot run one.
+ *
+ * Collected 2026-08-06 from `GET /accounts/{id}/ai/models/search` and from Anthropic's model list.
+ */
+const builtin = [
+    entry("anthropic", "claude-opus-5", "Opus 5", 1_000_000, 5, 25),
+    entry("anthropic", "claude-sonnet-5", "Sonnet 5", 1_000_000, 3, 15),
+    entry("anthropic", "claude-sonnet-4", "Sonnet 4", 200_000, 3, 15),
+    entry("anthropic", "claude-haiku-4-5", "Haiku 4.5", 200_000, 1, 5),
+    entry("workers-ai", "@cf/openai/gpt-oss-120b", "GPT-OSS 120B", 128_000, 0.35, 0.75),
+    entry("workers-ai", "@cf/openai/gpt-oss-20b", "GPT-OSS 20B", 128_000, 0.2, 0.3),
+    entry("workers-ai", "@cf/moonshotai/kimi-k2.6", "Kimi K2.6", 262_144, 0.95, 4),
+    entry("workers-ai", "@cf/moonshotai/kimi-k2.7-code", "Kimi K2.7 Code", 262_144, 0.95, 4),
+    entry("workers-ai", "@cf/zai-org/glm-5.2", "GLM 5.2", 262_144, 1.4, 4.4),
+    entry("workers-ai", "@cf/zai-org/glm-4.7-flash", "GLM 4.7 Flash", 131_072, 0.0605, 0.4),
+    entry("workers-ai", "@cf/google/gemma-4-26b-a4b-it", "Gemma 4 26B", 256_000, 0.1, 0.3),
+    entry("workers-ai", "@cf/nvidia/nemotron-3-120b-a12b", "Nemotron 3 120B", 256_000, 0.5, 1.5),
+    entry("workers-ai", "@cf/meta/llama-4-scout-17b-16e-instruct", "Llama 4 Scout", 131_000, 0.27, 0.85),
+    entry("workers-ai", "@cf/meta/llama-3.3-70b-instruct-fp8-fast", "Llama 3.3 70B Fast", 24_000, 0.293, 2.253),
+    entry("workers-ai", "@cf/mistralai/mistral-small-3.1-24b-instruct", "Small 3.1 24B", 128_000, 0.351, 0.555),
+    entry("workers-ai", "@cf/ibm-granite/granite-4.0-h-micro", "Granite 4.0 Micro", 131_000, 0.017, 0.112),
+    entry("workers-ai", "@cf/qwen/qwen3-30b-a3b-fp8", "Qwen3 30B", 32_768, 0.0509, 0.335),
+];
+function entry(provider, model, name, contextTokens, inputPerMillion, outputPerMillion) {
+    return {
+        provider,
+        model,
+        name,
+        contextTokens,
+        price: { inputPerMillion, outputPerMillion },
+        source: "builtin",
+    };
+}
+/**
+ * The model's own name, taken from its id rather than invented.
+ *
+ * A live Workers AI model that is not in the table above has no written-out name anywhere, and
+ * "@cf/qwen/qwen3-30b-a3b-fp8" prettified by any rule short enough to write here comes out wrong —
+ * so the last segment of the id is used as it stands. A raw name is easier to recognise as raw than
+ * a wrong one is to recognise as wrong.
+ */
+function nameFromId(model) {
+    const segments = model.split("/");
+    return segments[segments.length - 1] ?? model;
+}
+export function createModelCatalog(deps) {
+    return {
+        async list() {
+            if (!deps.cloudflare)
+                return { entries: builtin, liveStatus: "not_configured" };
+            try {
+                const live = await deps.cloudflare.workersAiModels();
+                const merged = new Map(builtin.map((known) => [`${known.provider}:${known.model}`, known]));
+                for (const model of live) {
+                    // ⚠️ A model that cannot call a tool is skipped rather than listed without figures. It
+                    // would be an offer that produces a broken agent for whoever took it.
+                    if (!model.functionCalling)
+                        continue;
+                    const key = `workers-ai:${model.name}`;
+                    const known = merged.get(key);
+                    merged.set(key, {
+                        provider: "workers-ai",
+                        model: model.name,
+                        name: known?.name ?? nameFromId(model.name),
+                        // ⚠️ The live figure wins, and a live figure that is MISSING wins too — falling back to
+                        // the table for one of the two halves would produce an entry that is half fresh and
+                        // half years old, labelled fresh. Either the account answered for this model or it did
+                        // not.
+                        contextTokens: model.contextTokens,
+                        price: model.price,
+                        source: "cloudflare",
+                    });
+                }
+                return { entries: [...merged.values()], liveStatus: "read" };
+            }
+            catch {
+                // ⚠️ Named, not thrown. The select has to render either way — an agent whose model cannot be
+                // chosen is an agent nobody can repair from that screen — and the alternative to a stale
+                // price here is no price at all, which helps nobody choose. What the caller gets is the
+                // table plus the reason it is the table, and the screen says so.
+                return { entries: builtin, liveStatus: "unreadable" };
+            }
+        },
+    };
+}

package/dist/model-catalog/model-catalog.types.d.ts

@@ -0,0 +1,15 @@
+import type { ModelCatalog } from "@anchrd/intel-contract";
+import type { CloudflareAccountApi } from "../adapters/cloudflare-api/cloudflare-api.types.js";
+export interface ModelCatalogDeps {
+    /** Absent where the deployment configured no Cloudflare read token. A named state, not an error. */
+    cloudflare?: Pick<CloudflareAccountApi, "workersAiModels">;
+}
+export interface ModelCatalogService {
+    /**
+     * ⚠️ The answer shape lives in `@anchrd/intel-contract`, because the select in the browser parses
+     * it. Its `source` field is per ENTRY on purpose: Cloudflare publishes figures for the models it
+     * serves itself and none for the Anthropic models it resells, so a healthy read still leaves half
+     * the list on a written-out table (#257).
+     */
+    list(): Promise<ModelCatalog>;
+}

package/dist/model-catalog/model-catalog.types.js

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

package/dist/nodes/nodes.js

@@ -1,6 +1,7 @@
-import { AgentDefinition, AgentMediaType, TableMediaType, } from "@anchrd/intel-contract";
+import { AgentDefinition, AgentMediaType, agentReferenceAccepts, TableMediaType, } from "@anchrd/intel-contract";
 import { encodeCsv, parseCsv } from "../shared/csv/csv.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
+import { plainTitle } from "../shared/plain-title/plain-title.js";
 import { documentLinkTargets } from "./document-links/document-links.js";
 // ⚠️ The R2 key of a version written before #125 begins `knowledge/`, and it stays that way. A key
 // is stored in `node_versions.content_key` and read back from there; nothing derives one from ids,
@@ -327,6 +328,36 @@ export function createNodes(deps) {
             throw new IntelError(500, "content_missing", "Version content is missing");
         return { node, version, definition: parseStoredDefinition(body), applicationId };
     }
+    /**
+     * Whether every reference names a node its role can actually use (#255).
+     *
+     * ⚠️ Here and not in the screen. The screen offers only what a role accepts, but a definition can
+     * be written straight over the Intel MCP surface — and a `memory` reference pointing at a
+     * document is not a cosmetic mistake: `agent_remember` writes into what it is given, so the agent
+     * would overwrite the document somebody handed it.
+     *
+     * ⚠️ A reference to a node this actor cannot see is left alone, deliberately. Refusing it would
+     * answer "there is a node with that id and it is the wrong kind" to somebody who may not know the
+     * node exists (#41), and accepting it changes nothing: the runtime reads with the AGENT's grants,
+     * and what it may not read it reports as an unavailable reference. What is checked is what the
+     * writer can see, which is exactly what they chose.
+     *
+     * ⚠️ Ids are deduplicated before the reads. The contract allows two hundred references and the
+     * same folder twice; one lookup per row would make a large definition pay for the repetition.
+     */
+    async function checkReferences(actor, definition) {
+        const kinds = new Map();
+        for (const reference of definition.references) {
+            let kind = kinds.get(reference.nodeId);
+            if (kind === undefined) {
+                kind = (await deps.repository.getVisible(actor, reference.nodeId))?.kind ?? null;
+                kinds.set(reference.nodeId, kind);
+            }
+            if (kind !== null && !agentReferenceAccepts(reference.role, kind)) {
+                throw new IntelError(422, "agent_reference_kind_not_allowed", `A ${kind} cannot be used as ${reference.role}`);
+            }
+        }
+    }
     /**
      * The one place a caller's asked-for definition becomes the definition Intel stores (D30).
      *
@@ -635,7 +666,7 @@ export function createNodes(deps) {
                     id: deps.id(),
                     parentId: input.parentId,
                     kind: input.kind,
-                    title: input.title,
+                    title: plainTitle(input.title),
                     description: input.description,
                     ownerId: actor.id,
                     currentVersionId: null,
@@ -765,15 +796,20 @@ export function createNodes(deps) {
                 throw new IntelError(403, "node_forbidden", "Parent folder cannot be edited");
             }
             // Before Gate, for the same reason the runtime check is before Gate: a delegation the saver
-            // cannot back must not leave a machine principal behind for an agent that was never created.
+            // cannot back — or a reference no role can use (#255) — must not leave a machine principal
+            // behind for an agent that was never created.
+            await checkReferences(actor, input.definition);
             const definition = await delegationOf(actor, input.definition);
             const nodeId = deps.id();
+            // One title for both, and it is the unescaped one: Gate's name is minted before the node row
+            // and can never be brought back into line with it afterwards (#202).
+            const title = plainTitle(input.title);
             // The Application's name is what a person reads in Gate's list, so it has to be enough to
             // recognise the agent by. Title alone would leave two agents called "Research" indis-
             // tinguishable; the node ID is what the runtime's key map is keyed by anyway.
             const application = await deps.applications.create({
                 token: caller.token,
-                name: `Intel agent ${input.title} (${nodeId})`,
+                name: `Intel agent ${title} (${nodeId})`,
             });
             // ⚠️ The handover happens BEFORE the node is written, for the same reason Gate is asked before
             // it: at this moment nothing exists on Intel's side, so a runtime that does not take the key
@@ -799,7 +835,7 @@ export function createNodes(deps) {
                         id: nodeId,
                         parentId: input.parentId,
                         kind: "agent",
-                        title: input.title,
+                        title,
                         description: input.description,
                         ownerId: actor.id,
                         currentVersionId: null,
@@ -921,6 +957,7 @@ export function createNodes(deps) {
             if (node.currentVersionId !== input.baseVersionId) {
                 throw new IntelError(409, "version_conflict", "A newer version already exists");
             }
+            await checkReferences(actor, input.definition);
             const saved = await writeAgentVersion(actor, node, await delegationOf(actor, input.definition), input.baseVersionId, input.idempotencyKey);
             await deps.agentSchedules.sync({ token: caller.token, agentId: node.id });
             return saved;
@@ -1192,7 +1229,7 @@ export function createNodes(deps) {
                 node: {
                     ...current,
                     parentId: input.parentId === undefined ? current.parentId : input.parentId,
-                    title: input.title ?? current.title,
+                    title: input.title === undefined ? current.title : plainTitle(input.title),
                     description: input.description === undefined ? current.description : input.description,
                     updatedAt,
                 },

package/dist/shared/plain-title/plain-title.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ⚠️ A title is plain text, and an HTML entity in one is never what somebody meant.
+ *
+ * Intel escapes nothing, anywhere — the entity arrives already in the value (#202). The chain that
+ * carries a title to a write can HTML-escape what it hands to a model: the GitHub MCP server, for
+ * one, returns every string with `&` as `&` and `"` as `"`, so a model that copies a name
+ * out of one tool result into the next call writes the entity, not the character. Refusing the
+ * write would be the louder answer and the wrong one — the model reads the same escaped value
+ * again on its retry and cannot get past it. So the write boundary accepts it and stores what was
+ * meant.
+ *
+ * Repeated until it stops changing rather than once, because that is the failure the ticket names:
+ * a title read back escaped and written again is escaped twice, and a single round would leave
+ * `&` as `&` — still an entity, still spreading.
+ */
+export declare function plainTitle(title: string): string;

package/dist/shared/plain-title/plain-title.js

@@ -0,0 +1,45 @@
+// Exactly what an HTML escaper emits, and nothing else. `"` and `'` are Go's
+// `html.EscapeString` spelling of the quotes — the fingerprint of the tool that produced the
+// titles this exists for. A general entity table is deliberately not here: ` ` or `ä` in
+// a title is a person's choice, an escaped `&` never is.
+const Escapes = [
+    [/&lt;/g, "<"],
+    [/&gt;/g, ">"],
+    [/&quot;/g, '"'],
+    [/&#0*34;/g, '"'],
+    [/&apos;/g, "'"],
+    [/&#0*39;/g, "'"],
+    // Last in the pass, so one round of unescaping is the exact inverse of one round of escaping:
+    // `&amp;lt;` becomes `&lt;` here and only the NEXT round turns it into `<`.
+    [/&amp;/g, "&"],
+];
+// A title that survived one more escaping than any writer intended. Eight is far past anything a
+// real chain produces and stops a crafted title from spinning here.
+const MaxRounds = 8;
+/**
+ * ⚠️ A title is plain text, and an HTML entity in one is never what somebody meant.
+ *
+ * Intel escapes nothing, anywhere — the entity arrives already in the value (#202). The chain that
+ * carries a title to a write can HTML-escape what it hands to a model: the GitHub MCP server, for
+ * one, returns every string with `&` as `&amp;` and `"` as `&#34;`, so a model that copies a name
+ * out of one tool result into the next call writes the entity, not the character. Refusing the
+ * write would be the louder answer and the wrong one — the model reads the same escaped value
+ * again on its retry and cannot get past it. So the write boundary accepts it and stores what was
+ * meant.
+ *
+ * Repeated until it stops changing rather than once, because that is the failure the ticket names:
+ * a title read back escaped and written again is escaped twice, and a single round would leave
+ * `&amp;amp;` as `&amp;` — still an entity, still spreading.
+ */
+export function plainTitle(title) {
+    let current = title;
+    for (let round = 0; round < MaxRounds; round += 1) {
+        let next = current;
+        for (const [pattern, character] of Escapes)
+            next = next.replace(pattern, character);
+        if (next === current)
+            break;
+        current = next;
+    }
+    return current;
+}

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

@@ -15,9 +15,10 @@ export const ServerDirectoryTool = "portal_list_servers";
  *
  * ⚠️ 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.
+ * accepted from `structuredContent`, from `{ servers: [...] }`, from a JSON text block, or — the
+ * form the live portal actually uses — from the prose block `proseRows` reads. 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(),
@@ -26,10 +27,71 @@ const DirectoryRow = z.looseObject({
 });
 const DirectoryRows = z.array(DirectoryRow);
 const DirectoryEnvelope = z.looseObject({ servers: DirectoryRows });
+/** A line the portal meant as a directory entry: `- <display name> (<handle>): <state>`. */
+const ProseRow = /^\s*[-*•]\s+(.+?)\s*\(([^()\s]+)\)\s*:\s*(.*)$/;
+/** What claims to be an entry at all. Everything else in the block is a heading or a hint. */
+const ProseBullet = /^\s*[-*•]\s/;
+/**
+ * ⚠️ Never the ✓. A tick is decoration: a different locale, a plain-text client or a later version
+ * of the portal writes the same fact another way, and a reading that hangs on one code point would
+ * silently switch every server off. What is read is the word, and the word alone.
+ *
+ * It has to be the WHOLE state, not a word inside it, because "disabled" contains "enabled" and
+ * "not enabled" is built from it — a substring test would read both as switched on, and that is the
+ * one direction this must never get wrong. Anything else the portal might write ("aktiviert",
+ * "enabled (3 tools)") is therefore not offerable, and stays declared.
+ */
+function readsAsEnabled(state) {
+    const words = state.toLowerCase().match(/\p{L}+/gu);
+    return words !== null && words.length === 1 && words[0] === "enabled";
+}
+/**
+ * The portal's prose form: a heading, one bullet per server, a closing hint. It is what the live
+ * portal actually answers (#233), and it is read only after every JSON reading in `rows` has failed.
+ *
+ * ⚠️ This reading hangs on somebody else's wording and can break without warning. The portal owes
+ * Intel no format at all, so a reworded state, a translated page or a changed layout is a normal
+ * event here rather than a defect. Two things keep that from becoming a quiet widening:
+ *
+ * - **A bullet that does not read as a row refuses the whole answer.** Skipping it would hand back
+ *   a directory with one server missing, and a missing row is not a smaller list — it lets that
+ *   server's tools fall back onto the shorter handle that encloses them, which is exactly the
+ *   widening the split between `declared` and `servers` exists to prevent. The price is that a
+ *   portal which one day bullets its closing hint fails loudly with the same closed
+ *   `tool_servers_unavailable` that #233 found; that is the intended direction.
+ * - **Nothing read here can invent a server.** A handle no live tool confirms is never offered, so
+ *   a misread line costs an offer, never a delegation.
+ */
+function proseRows(answer) {
+    const parsed = [];
+    for (const block of answer.content) {
+        if (typeof block !== "object" || block === null || !("text" in block))
+            continue;
+        const text = block.text;
+        if (typeof text !== "string")
+            continue;
+        for (const line of text.split("\n")) {
+            if (!ProseBullet.test(line))
+                continue;
+            const [, name, handle, state] = ProseRow.exec(line) ?? [];
+            if (name === undefined || handle === undefined)
+                return null;
+            // `id` carries the handle and `name` the display name, but neither is believed on its own:
+            // both stay candidates in `toolServersFrom`, and the live tool list decides which one
+            // actually namespaces.
+            parsed.push({ id: handle, name, enabled: readsAsEnabled(state ?? "") });
+        }
+    }
+    return parsed.length > 0 ? parsed : null;
+}
 /**
  * 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.
+ *
+ * ⚠️ The prose reading comes last and is ADDITIONAL, never replacing. The portal is somebody else's
+ * product: it answers in prose today and may answer structured tomorrow, and a structured answer
+ * must keep winning on the day it arrives beside a human sentence.
  */
 function rows(answer) {
     const candidates = [answer.structuredContent];
@@ -42,8 +104,9 @@ function rows(answer) {
                 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.
+                // A text block that is not JSON may still be the directory — see `proseRows` above. It is
+                // not fed to the JSON readings here, and it does not make them fail either: the portal may
+                // well add a human sentence beside the payload.
             }
         }
     }
@@ -55,7 +118,7 @@ function rows(answer) {
         if (wrapped.success)
             return wrapped.data.servers;
     }
-    return null;
+    return proseRows(answer);
 }
 /**
  * ⚠️ The rule itself — longest match against declared handles, never a cut at an underscore — is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.7.0",
-    "@anchrd/intel-contract": "^0.7.0",
+    "@anchrd/intel-contract": "^0.9.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",