@anchrd/intel 0.59.0

package/src/contract/share.ts

@@ -0,0 +1,196 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId, IsoDateTime, NamedOrCounted } from "./contract.ts";
+
+// ⚠️ There is no `ContextPolicy`, and it is not coming back in this shape (#76). It said whether a
+// document should be pinned into a context, be found by relevance, or be named explicitly — an
+// instruction to a retrieval Intel does not perform. Intel hands out references and the agent
+// fetches what it needs (D24), so nothing here could ever have read it, and nothing did.
+//
+// Semantic search stays: as an MCP tool the agent calls, over everything or over one area.
+
+// One verb per grant, granted independently (ADR-0004 §2). Not a ladder: seeing a process must be
+// separable from being allowed to start it, and `execute` is meaningful only where a flow can live.
+export const ResourceVerb = z.enum(["read", "write", "execute", "share"]);
+export type ResourceVerb = z.infer<typeof ResourceVerb>;
+
+export const SharePrincipal = z.discriminatedUnion("type", [
+  z.strictObject({ type: z.literal("user"), id: IntelId }),
+  z.strictObject({ type: z.literal("email"), email: z.email() }),
+  z.strictObject({ type: z.literal("organization") }),
+]);
+export type SharePrincipal = z.infer<typeof SharePrincipal>;
+
+export const ListGrantsInput = z.strictObject({
+  resourceId: IntelId.describe(
+    "Node whose direct grants to list. Access inherited from a folder above is not a grant on this node and is not listed here.",
+  ),
+});
+export type ListGrantsInput = z.infer<typeof ListGrantsInput>;
+
+// The same three shapes for a flow (#530). Separate inputs rather than a widened `resourceId`,
+// because the id names a different table and a caller that passes the wrong kind should be told so
+// by the route it called rather than by a lookup that finds nothing.
+export const ListFlowGrantsInput = z.strictObject({
+  flowId: IntelId.describe(
+    "Flow whose direct grants to list. Access inherited from the folder it is filed in is not a grant on this flow and is not listed here.",
+  ),
+});
+export type ListFlowGrantsInput = z.infer<typeof ListFlowGrantsInput>;
+
+// ⚠️ A DIFFERENT question from the two above, not a fuller answer to them (#586). The `*GrantsInput`
+// pair asks what sits ON this one resource; these two ask who REACHES it once inheritance is
+// resolved — every grant along the folders above plus the owners, who need no grant row at all. On
+// the everyday resource, whose access comes from the folder it is filed in, the first answer is
+// empty and this one is not, so a caller that reaches for the wrong one is told "nobody" about
+// something half the organization can open.
+//
+// Two inputs rather than one widened `resourceId`, for the reason the pair above gives: the id
+// names a different table, and the queries behind them are two statements over two sets of tables.
+export const ListEffectiveAccessInput = z.strictObject({
+  resourceId: IntelId.describe(
+    "Node to answer for. The answer crosses the folders above it and names owners as well as grants, so it is not the list node_grant_list gives.",
+  ),
+});
+export type ListEffectiveAccessInput = z.infer<typeof ListEffectiveAccessInput>;
+
+export const ListFlowEffectiveAccessInput = z.strictObject({
+  flowId: IntelId.describe(
+    "Flow to answer for. The answer includes what the folder it is filed in passes down and names owners as well as grants, so it is not the list flow_grant_list gives.",
+  ),
+});
+export type ListFlowEffectiveAccessInput = z.infer<typeof ListFlowEffectiveAccessInput>;
+
+export const ResourceGrant = z.strictObject({
+  id: IntelId,
+  resourceId: IntelId,
+  principal: SharePrincipal,
+  verb: ResourceVerb,
+  expiresAt: IsoDateTime.nullable(),
+  createdBy: IntelId,
+  createdAt: IsoDateTime,
+});
+export type ResourceGrant = z.infer<typeof ResourceGrant>;
+
+// The word means exactly the same thing on a node grant and on a flow grant, so it is described
+// once — the rule this package states about `IdempotencyKey`, applied within one file rather than
+// across the package. Two copies are two places to drift, and both of them ship in `tools/list`.
+//
+// ⚠️ What is refused is decided by `deps.now()` in the application layer and cannot be expressed
+// here (#442); this sentence names the answer a caller gets, it does not produce it.
+const GrantExpiresAt = IsoDateTime.nullable()
+  .default(null)
+  .describe(
+    "When the grant stops working, or `null` for one that does not expire on its own. A time that is not in the future is refused with `grant_already_expired`: a grant that could never work is not created.",
+  );
+
+export const ShareInput = z.strictObject({
+  resourceId: IntelId.describe(
+    "Node to grant access to. A grant on a folder is inherited by everything beneath it, which is the usual way to share a whole area.",
+  ),
+  principal: SharePrincipal.describe(
+    "Who gets the access: a Gate user by id, someone by verified email address, or the whole organization.",
+  ),
+  verb: ResourceVerb.describe(
+    "What they may do. Each verb is granted on its own and none implies another: `read` reads, `write` writes, `execute` runs a flow, `share` passes access on. Seeing a process is deliberately separable from being allowed to start it.",
+  ),
+  expiresAt: GrantExpiresAt,
+  idempotencyKey: IdempotencyKey,
+});
+export type ShareInput = z.infer<typeof ShareInput>;
+
+export const RevokeGrantInput = z.strictObject({
+  resourceId: IntelId.describe(
+    "Node the grant sits on. Named alongside the grant id so access is decided on the node.",
+  ),
+  grantId: IntelId.describe("The grant to withdraw, from node_grant_list."),
+  idempotencyKey: IdempotencyKey,
+});
+export type RevokeGrantInput = z.infer<typeof RevokeGrantInput>;
+
+export const ShareFlowInput = z.strictObject({
+  flowId: IntelId.describe(
+    "Flow to grant access to. A grant here reaches this flow and nothing else — not the folder it is filed in, and not the flows it calls.",
+  ),
+  principal: SharePrincipal.describe(
+    "Who gets the access: a Gate user by id, someone by verified email address, or the whole organization.",
+  ),
+  verb: ResourceVerb.describe(
+    "What they may do. Each verb is granted on its own and none implies another: `read` opens the flow, `write` edits it, `execute` runs it, `share` passes access on.",
+  ),
+  expiresAt: GrantExpiresAt,
+  idempotencyKey: IdempotencyKey,
+});
+export type ShareFlowInput = z.infer<typeof ShareFlowInput>;
+
+export const RevokeFlowGrantInput = z.strictObject({
+  flowId: IntelId.describe(
+    "Flow the grant sits on. Named alongside the grant id so access is decided on the flow.",
+  ),
+  grantId: IntelId.describe("The grant to withdraw, from flow_grant_list."),
+  idempotencyKey: IdempotencyKey,
+});
+export type RevokeFlowGrantInput = z.infer<typeof RevokeFlowGrantInput>;
+
+// What a grant does not cover, reported to whoever just made it. A flow in the shared folder may
+// read a document outside it, and the run is re-authorized against the person running it — so the
+// grant can be complete and the flow still stop for them (ADR-0004 §4).
+//
+// ⚠️ `titles` holds only the documents the sharer may see; everything else is in `hidden` as a
+// number. A warning must not become a way of reading titles out of the tree.
+//
+// It IS `NamedOrCounted` — one schema, under the name this domain calls it by. The shape moved to
+// `contract.ts` when a refusal started carrying it too (#448); it is not restated here, because two
+// declarations of one rule are two places for it to drift.
+export const UnreadableNodes = NamedOrCounted;
+export type UnreadableNodes = z.infer<typeof UnreadableNodes>;
+
+// The grant is in the answer, so the warning cannot be mistaken for a refusal: it is written first
+// and described afterwards. Blocking would force everyone who uses a central policy document to
+// duplicate it, which is the opposite of what one tree is for (ADR-0004 §4).
+//
+// ⚠️ `unrunnable` is the second half of the same sentence and belongs to the flow grant (#530). A
+// grant on a folder covered every flow beneath it, so there was nothing to say; a grant on one flow
+// reaches that flow and stops, and the sub-flows it calls are then somebody else's to grant. It
+// carries the shape of `UnreadableNodes` because it answers the same question — what this grant
+// does NOT reach, named where the sharer may see it and counted where they may not — and it is
+// empty for every node grant.
+export const ShareResult = z.strictObject({
+  grant: ResourceGrant,
+  unreadable: UnreadableNodes,
+  unrunnable: UnreadableNodes.default({ titles: [], hidden: 0 }),
+});
+export type ShareResult = z.infer<typeof ShareResult>;
+
+// `applicableVerbs` travels with the list because the answer is the business layer's, not the
+// screen's: a document has nothing to execute, so `execute` is not offered on one (ADR-0004 §2).
+export const ResourceGrantList = z.strictObject({
+  resourceId: IntelId,
+  applicableVerbs: z.array(ResourceVerb).min(1),
+  items: z.array(ResourceGrant),
+});
+export type ResourceGrantList = z.infer<typeof ResourceGrantList>;
+
+// A display-only, effective view. Unlike ResourceGrantList it crosses ancestor folders and names
+// owners, because ownership grants access without creating a revocable grant row.
+//
+// ⚠️ `sources` names the folders the inherited grants sit on, so a reader can be told WHERE to go
+// to take one back rather than "somewhere above" (#803). It carries only the folders this reader
+// may see, by the rule `resolveVisibleTitles` follows for document links (#41): a folder that is
+// not theirs to see is absent, and absent is not distinguishable from "no longer there". A grant
+// can be in force from a folder the reader may not open — naming it would disclose an ancestor the
+// tree never showed them.
+export const ResourceAccessList = z.strictObject({
+  resourceId: IntelId,
+  ownerIds: z.array(IntelId),
+  items: z.array(ResourceGrant),
+  sources: z
+    .array(z.strictObject({ resourceId: IntelId, title: z.string() }))
+    .default([])
+    .describe(
+      "The folders the inherited grants sit on, named where the caller may see them. A grant whose resourceId is absent here is still in force; it is only unnamed.",
+    ),
+});
+export type ResourceAccessList = z.infer<typeof ResourceAccessList>;
+
+export const RevokeGrantResult = z.strictObject({ revoked: z.boolean() });
+export type RevokeGrantResult = z.infer<typeof RevokeGrantResult>;

package/src/contract/table.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId } from "./contract.ts";
+import { Node, NodeVersion } from "./node.ts";
+
+const distinctPositions = { error: "Row positions must be distinct" };
+
+// A table is CSV, and CSV is the whole format: it is what is stored, what is downloaded and what a
+// machine reads. There is no second representation to keep in step with it (#40).
+export const TableMediaType = "text/csv";
+
+// A column name is the contract between the table and everyone who appends to it, so it is trimmed,
+// non-empty and bounded like a title. Cells are not: a cell is text, and text is what CSV carries.
+export const TableColumn = z.string().trim().min(1).max(120);
+export const TableCell = z.string().max(4_000);
+export const TableRow = z.array(TableCell).min(1).max(64);
+
+// Writing the header, once. The columns are the contract (#40's comment), which is why this refuses
+// on a table that already has one: changing the header would silently reinterpret every row that
+// was appended under the old one.
+export const DefineTableInput = z.strictObject({
+  nodeId: IntelId.describe("Table node whose header is being written. It must not have one yet."),
+  columns: z
+    .array(TableColumn)
+    .describe(
+      "The column names, in order. They are the contract every later append is checked against, which is why this refuses on a table that already has a header — changing it would silently reinterpret the stored rows. Use node_table_update for that.",
+    )
+    .min(1)
+    .max(64)
+    .refine(
+      (columns) => new Set(columns.map((column) => column.toLowerCase())).size === columns.length,
+      { error: "Column names must be distinct" },
+    ),
+  idempotencyKey: IdempotencyKey,
+});
+export type DefineTableInput = z.infer<typeof DefineTableInput>;
+
+// ⚠️ No `baseVersionId`, and that absence is the feature. A document replaces its content and needs
+// to know which content it replaces; an append adds to the end and cannot collide with a second
+// append, so demanding a base version would invent a conflict that does not exist and force the
+// caller to read the whole table first — the exact cost #40 exists to remove.
+export const AppendTableRowsInput = z.strictObject({
+  nodeId: IntelId.describe("Table node to append to. It must already have a header."),
+  rows: z
+    .array(TableRow)
+    .min(1)
+    .max(1_000)
+    .describe(
+      "Rows to add at the end, each an array of cell strings in the header's order. No base version is needed: appending collides with nothing, so the table does not have to be read first.",
+    ),
+  idempotencyKey: IdempotencyKey,
+});
+export type AppendTableRowsInput = z.infer<typeof AppendTableRowsInput>;
+
+export const GetTableInput = z.strictObject({
+  nodeId: IntelId.describe("Table node to read as a grid: header and every row."),
+});
+export type GetTableInput = z.infer<typeof GetTableInput>;
+
+export const AppendTableRowsResult = z.strictObject({
+  node: Node,
+  version: NodeVersion,
+  appended: z.number().int().positive(),
+});
+export type AppendTableRowsResult = z.infer<typeof AppendTableRowsResult>;
+
+// A row's address is its position among the table's current rows, counted from zero and without the
+// header. Deliberately not an ID: rows carry no identity of their own (#135, and the same decision
+// the grid documents), so every mutation instead pins the state its positions refer to.
+export const TableRowPosition = z.number().int().nonnegative();
+
+// Replacing rows in place (#135). `baseVersionId` is the version the caller read the positions
+// from — required, never nullable, because a position into a table one has not read is a guess.
+// A table that moved on since answers `version_conflict` rather than editing the wrong rows; that
+// is the same optimistic concurrency the document save uses, and the deliberate opposite of
+// `append`, which needs no base because it collides with nothing.
+export const UpdateTableRowsInput = z.strictObject({
+  nodeId: IntelId.describe("Table node to change rows in."),
+  baseVersionId: IntelId.describe(
+    "The `versionId` from the node_table_get whose rows these positions were counted in. Required and never null: a position into a table nobody has read is a guess. If the table has moved on since, the call is refused rather than editing the wrong rows.",
+  ),
+  updates: z
+    .array(
+      z.strictObject({
+        position: TableRowPosition.describe(
+          "Zero-based position of the row to replace, counting data rows and not the header.",
+        ),
+        row: TableRow.describe(
+          "The complete replacement row, as cell strings in the header's order.",
+        ),
+      }),
+    )
+    .describe(
+      "Which rows to replace and with what. `position` is zero-based and counts data rows, not the header; `row` is the complete replacement, not a patch.",
+    )
+    .min(1)
+    .max(1_000)
+    .refine(
+      (updates) => new Set(updates.map((update) => update.position)).size === updates.length,
+      distinctPositions,
+    ),
+  idempotencyKey: IdempotencyKey,
+});
+export type UpdateTableRowsInput = z.infer<typeof UpdateTableRowsInput>;
+
+export const UpdateTableRowsResult = z.strictObject({
+  node: Node,
+  version: NodeVersion,
+  updated: z.number().int().positive(),
+});
+export type UpdateTableRowsResult = z.infer<typeof UpdateTableRowsResult>;
+
+export const DeleteTableRowsInput = z.strictObject({
+  nodeId: IntelId.describe("Table node to remove rows from."),
+  baseVersionId: IntelId.describe(
+    "The `versionId` from the node_table_get these positions were counted in. A table that has moved on since is refused rather than losing the wrong rows.",
+  ),
+  positions: z
+    .array(TableRowPosition)
+    .describe(
+      "Zero-based positions of the data rows to remove. All of them go in one call; the positions are read against the base version, so they do not shift while it runs.",
+    )
+    .min(1)
+    .max(1_000)
+    .refine((positions) => new Set(positions).size === positions.length, distinctPositions),
+  idempotencyKey: IdempotencyKey,
+});
+export type DeleteTableRowsInput = z.infer<typeof DeleteTableRowsInput>;
+
+export const DeleteTableRowsResult = z.strictObject({
+  node: Node,
+  version: NodeVersion,
+  deleted: z.number().int().positive(),
+});
+export type DeleteTableRowsResult = z.infer<typeof DeleteTableRowsResult>;
+
+// One entry per column the table will have afterwards, in order. `source` names the current column
+// whose cells fill it; `null` adds an empty column, and a current column no entry names is removed
+// together with its cells. Renaming is naming a source under a new name.
+export const RedefineTableColumn = z.strictObject({
+  name: TableColumn.describe("What the column is called afterwards."),
+  source: TableColumn.nullable()
+    .default(null)
+    .describe(
+      "The current column whose cells fill it, by its current name, or `null` for a new empty column.",
+    ),
+});
+export type RedefineTableColumn = z.infer<typeof RedefineTableColumn>;
+
+// Changing the header of a table that has one (#135). The mapping is explicit because it is the
+// whole difference to the blind re-definition `defineTable` keeps refusing: without it a new header
+// would silently reinterpret every stored row under names nobody matched to the old ones.
+export const RedefineTableInput = z.strictObject({
+  nodeId: IntelId.describe("Table node whose header is being changed."),
+  baseVersionId: IntelId.describe(
+    "The `versionId` from the node_table_get this mapping was written against. A table that has moved on since is refused.",
+  ),
+  columns: z
+    .array(RedefineTableColumn)
+    .describe(
+      "The complete new header, in order. Each entry names the current column whose cells fill it, or `null` for a new empty one; a current column that no entry names is removed with its cells. Renaming is naming a source under a new name. The mapping is explicit on purpose — a new header without one would reinterpret every stored row.",
+    )
+    .min(1)
+    .max(64)
+    .refine(
+      (columns) =>
+        new Set(columns.map((column) => column.name.toLowerCase())).size === columns.length,
+      { error: "Column names must be distinct" },
+    )
+    .refine(
+      (columns) => {
+        const sources = columns.map((column) => column.source).filter((source) => source !== null);
+        return new Set(sources).size === sources.length;
+      },
+      { error: "A current column can fill only one new column" },
+    ),
+  idempotencyKey: IdempotencyKey,
+});
+export type RedefineTableInput = z.infer<typeof RedefineTableInput>;

package/src/contract/tool.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+
+function normalizedHostname(url: URL): string {
+  return url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+}
+
+function isPrivateIpv4(hostname: string): boolean {
+  const parts = hostname.split(".").map(Number);
+  if (
+    parts.length !== 4 ||
+    parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)
+  ) {
+    return false;
+  }
+  const [first = 0, second = 0] = parts;
+  return (
+    first === 0 ||
+    first === 10 ||
+    first === 127 ||
+    (first === 100 && second >= 64 && second <= 127) ||
+    (first === 169 && second === 254) ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 168) ||
+    (first === 198 && (second === 18 || second === 19)) ||
+    first >= 224
+  );
+}
+
+function isPublicToolHost(url: URL): boolean {
+  const hostname = normalizedHostname(url);
+  if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1") {
+    return url.protocol === "http:";
+  }
+  if (
+    !hostname.includes(".") ||
+    hostname.endsWith(".local") ||
+    hostname.endsWith(".localhost") ||
+    hostname.endsWith(".internal") ||
+    isPrivateIpv4(hostname) ||
+    hostname.includes(":")
+  ) {
+    return false;
+  }
+  return url.protocol === "https:";
+}
+
+/**
+ * One MCP server as the portal names it. The handle is what the portal puts in front of every tool
+ * that server offers (`notion_notion-search` belongs to `notion`), and it is the only identifier
+ * Intel can both store and recognise again in a live `tools/list`.
+ *
+ * ⚠️ A handle is never invented from a tool name. Which servers exist is the portal's answer
+ * (`portal_list_servers`), and the prefix is only used to attribute a tool to a server that answer
+ * already named — see `packages/intel/src/tools/tool-servers` for why splitting on the underscore
+ * alone would be ambiguous.
+ */
+export const ToolServerHandle = z
+  .string()
+  .trim()
+  .min(1)
+  .max(120)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "A server handle is the portal's own identifier");
+export type ToolServerHandle = z.infer<typeof ToolServerHandle>;
+
+export const ToolSourceUrl = z.url().refine((value) => {
+  try {
+    const url = new URL(value);
+    return !url.username && !url.password && isPublicToolHost(url);
+  } catch {
+    return false;
+  }
+}, "The portal must use an approved public HTTPS host without embedded credentials");
+
+// The portal namespaces every upstream tool, so the name alone identifies the target server. The
+// portal is still the one that resolves it and attaches the credentials — Intel never holds an
+// upstream credential. Since D30 Intel does read the namespace for one purpose: attributing a tool
+// to a server the portal's own `portal_list_servers` already named, so a delegation can be cut to
+// whole servers. That is attribution, not routing.
+export const ToolName = z.string().min(1).max(240);
+
+export const ToolAnnotations = z.strictObject({
+  title: z.string().max(240).optional(),
+  readOnlyHint: z.boolean().optional(),
+  destructiveHint: z.boolean().optional(),
+  idempotentHint: z.boolean().optional(),
+  openWorldHint: z.boolean().optional(),
+});
+export type ToolAnnotations = z.infer<typeof ToolAnnotations>;
+
+export const ToolCapability = z.strictObject({
+  name: ToolName,
+  title: z.string().max(240).nullable(),
+  description: z.string().max(10_000).nullable(),
+  inputSchema: z.record(z.string(), z.unknown()),
+  outputSchema: z.record(z.string(), z.unknown()).nullable(),
+  annotations: ToolAnnotations,
+  fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+});
+export type ToolCapability = z.infer<typeof ToolCapability>;
+
+// The catalog reflects one live tools/list for the requesting user. It is never stored as a
+// permission mirror, so there is no per-source state and no Intel-owned connection status.
+export const ToolCatalog = z.strictObject({
+  portalConnected: z.boolean(),
+  items: z.array(ToolCapability),
+  /**
+   * Which delegated servers actually contributed a tool to this catalog (#289).
+   *
+   * ⚠️ Present only where the attribution was actually made — a delegated caller whose catalog was
+   * read. It is absent for an ordinary user, and absent as well when the answer comes from one of
+   * the short paths that never reach the portal (nothing delegated, no portal sign-in, connection
+   * dropped). Absent therefore means "not stated", never "nothing arrived"; `[]` is the second one.
+   *
+   * That it is missing rather than empty on those paths is deliberate rather than half-finished:
+   * the attribution already happens for a delegation — `capabilities` has to make it to cut the
+   * list — so naming it costs nothing there, while computing the same thing for an ordinary user
+   * would mean a second portal request per call, for a question their screen does not ask.
+   *
+   * ⚠️ It is the answer to "what arrived", never to "what was granted". A server missing here has
+   * been switched off, revoked, or is failing right now; the delegation in the definition is
+   * unchanged. Reading it the other way round would turn an outage into a permission change.
+   */
+  reached: z.array(ToolServerHandle).optional(),
+});
+export type ToolCatalog = z.infer<typeof ToolCatalog>;
+
+/**
+ * One MCP server the asking user reaches right now, as the portal itself names it (D30).
+ *
+ * ⚠️ `toolCount` is a fact about this moment and this user, not a size. It exists so a picker can
+ * say "9 tools" instead of showing a handle alone, and it must never be read as what an agent will
+ * get: the delegated run asks the portal again, with the delegator's token.
+ */
+export const ToolServer = z.strictObject({
+  handle: ToolServerHandle,
+  name: z.string().min(1).max(240),
+  toolCount: z.number().int().min(0),
+});
+export type ToolServer = z.infer<typeof ToolServer>;
+
+// The same live-query rule as the tool catalog, one level up. `portalConnected: false` is the state
+// of somebody who has not signed into the portal yet, and it is not an error.
+export const ToolServerCatalog = z.strictObject({
+  portalConnected: z.boolean(),
+  items: z.array(ToolServer),
+});
+export type ToolServerCatalog = z.infer<typeof ToolServerCatalog>;
+
+/**
+ * Which of the named servers a tool belongs to, or `null` for none of them.
+ *
+ * ⚠️ THE TRAP: a tool name does not say where its server name ends.
+ *
+ * The portal writes `<server>_<tool>`, and both halves may contain underscores — `intel_flow_get`
+ * reads equally well as server `intel` with tool `flow_get` and as a server called `intel_flow`
+ * with tool `get`. Splitting on the first underscore is therefore a guess that is wrong the day
+ * somebody adds a server whose name contains one, and on the API side being wrong means an agent
+ * delegated server A quietly reaching server B.
+ *
+ * So the prefix is never split. It is only ever MATCHED against handles the portal itself named,
+ * and the longest match wins: with `intel` and `intel_flow` both declared, `intel_flow_get` belongs
+ * to `intel_flow`, which is the only reading in which both declarations stay true.
+ *
+ * ⚠️ This lives in the contract because HOW A NAME IS READ is a property of the wire, and both
+ * surfaces read the same wire: `packages/intel` cuts a delegation with it, `packages/intel/ui` groups the
+ * tools screen with it (#212). A second implementation in the browser would be the third answer to
+ * one question — the underscore rule has already been answered differently in two places once
+ * (#106, #107), and the copies disagreed. What deliberately stays OUT of here is everything about
+ * reach: which handles are declared, which are enabled, which may be delegated and which one owns
+ * the portal's own management tools are decisions with consequences, and they belong to
+ * `packages/intel/src/tools/tool-servers`. This function only reads a name.
+ */
+export function serverOf(toolName: string, handles: Iterable<string>): string | null {
+  let best: string | null = null;
+  for (const handle of handles) {
+    if (!toolName.startsWith(`${handle}_`)) continue;
+    if (best === null || handle.length > best.length) best = handle;
+  }
+  return best;
+}
+
+export const TestToolInput = z.strictObject({
+  name: ToolName.describe(
+    "The tool's full name as tool_list reported it, including the server handle it is prefixed with. The portal routes on that prefix, so a bare name reaches nothing.",
+  ),
+  arguments: z
+    .record(z.string(), z.unknown())
+    .default({})
+    .describe(
+      "The arguments, shaped by that tool's own inputSchema from tool_list. Validated against it before anything is sent, so a wrong shape is refused here rather than by the far side.",
+    ),
+});
+export type TestToolInput = z.infer<typeof TestToolInput>;
+export const ExecuteToolInput = TestToolInput;
+export type ExecuteToolInput = z.infer<typeof ExecuteToolInput>;
+
+export const ToolTestResult = z.strictObject({
+  isError: z.boolean(),
+  content: z.array(z.unknown()),
+  structuredContent: z.unknown().optional(),
+});
+export type ToolTestResult = z.infer<typeof ToolTestResult>;