@anchrd/intel-contract 0.12.0 → 0.14.0

package/dist/contract/share.d.ts

@@ -0,0 +1,142 @@
+import { z } from "zod";
+export declare const ResourceVerb: z.ZodEnum<{
+    read: "read";
+    write: "write";
+    execute: "execute";
+    share: "share";
+}>;
+export type ResourceVerb = z.infer<typeof ResourceVerb>;
+export declare const SharePrincipal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"user">;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"email">;
+    email: z.ZodEmail;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"organization">;
+}, z.core.$strict>], "type">;
+export type SharePrincipal = z.infer<typeof SharePrincipal>;
+export declare const ListGrantsInput: z.ZodObject<{
+    resourceId: z.ZodString;
+}, z.core.$strict>;
+export type ListGrantsInput = z.infer<typeof ListGrantsInput>;
+export declare const ResourceGrant: z.ZodObject<{
+    id: z.ZodString;
+    resourceId: z.ZodString;
+    principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"email">;
+        email: z.ZodEmail;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"organization">;
+    }, z.core.$strict>], "type">;
+    verb: z.ZodEnum<{
+        read: "read";
+        write: "write";
+        execute: "execute";
+        share: "share";
+    }>;
+    expiresAt: z.ZodNullable<z.ZodISODateTime>;
+    createdBy: z.ZodString;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type ResourceGrant = z.infer<typeof ResourceGrant>;
+export declare const ShareInput: z.ZodObject<{
+    resourceId: z.ZodString;
+    principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"email">;
+        email: z.ZodEmail;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"organization">;
+    }, z.core.$strict>], "type">;
+    verb: z.ZodEnum<{
+        read: "read";
+        write: "write";
+        execute: "execute";
+        share: "share";
+    }>;
+    expiresAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type ShareInput = z.infer<typeof ShareInput>;
+export declare const RevokeGrantInput: z.ZodObject<{
+    resourceId: z.ZodString;
+    grantId: z.ZodString;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type RevokeGrantInput = z.infer<typeof RevokeGrantInput>;
+export declare const UnreadableNodes: z.ZodObject<{
+    titles: z.ZodArray<z.ZodString>;
+    hidden: z.ZodNumber;
+}, z.core.$strict>;
+export type UnreadableNodes = z.infer<typeof UnreadableNodes>;
+export declare const ShareResult: z.ZodObject<{
+    grant: z.ZodObject<{
+        id: z.ZodString;
+        resourceId: z.ZodString;
+        principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"user">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"email">;
+            email: z.ZodEmail;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"organization">;
+        }, z.core.$strict>], "type">;
+        verb: z.ZodEnum<{
+            read: "read";
+            write: "write";
+            execute: "execute";
+            share: "share";
+        }>;
+        expiresAt: z.ZodNullable<z.ZodISODateTime>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    unreadable: z.ZodObject<{
+        titles: z.ZodArray<z.ZodString>;
+        hidden: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ShareResult = z.infer<typeof ShareResult>;
+export declare const ResourceGrantList: z.ZodObject<{
+    resourceId: z.ZodString;
+    applicableVerbs: z.ZodArray<z.ZodEnum<{
+        read: "read";
+        write: "write";
+        execute: "execute";
+        share: "share";
+    }>>;
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        resourceId: z.ZodString;
+        principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"user">;
+            id: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"email">;
+            email: z.ZodEmail;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"organization">;
+        }, z.core.$strict>], "type">;
+        verb: z.ZodEnum<{
+            read: "read";
+            write: "write";
+            execute: "execute";
+            share: "share";
+        }>;
+        expiresAt: z.ZodNullable<z.ZodISODateTime>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ResourceGrantList = z.infer<typeof ResourceGrantList>;
+export declare const RevokeGrantResult: z.ZodObject<{
+    revoked: z.ZodBoolean;
+}, z.core.$strict>;
+export type RevokeGrantResult = z.infer<typeof RevokeGrantResult>;

package/dist/contract/share.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId, IsoDateTime } from "./contract.js";
+// ⚠️ 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 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 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 const ResourceGrant = z.strictObject({
+    id: IntelId,
+    resourceId: IntelId,
+    principal: SharePrincipal,
+    verb: ResourceVerb,
+    expiresAt: IsoDateTime.nullable(),
+    createdBy: IntelId,
+    createdAt: IsoDateTime,
+});
+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: IsoDateTime.nullable()
+        .default(null)
+        .describe("When the grant stops working, or `null` for one that does not expire on its own."),
+    idempotencyKey: IdempotencyKey,
+});
+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,
+});
+// 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.
+export const UnreadableNodes = z.strictObject({
+    titles: z.array(z.string().min(1).max(240)),
+    hidden: z.number().int().nonnegative(),
+});
+// 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).
+export const ShareResult = z.strictObject({
+    grant: ResourceGrant,
+    unreadable: UnreadableNodes,
+});
+// `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 const RevokeGrantResult = z.strictObject({ revoked: z.boolean() });

package/dist/contract/table.d.ts

@@ -0,0 +1,162 @@
+import { z } from "zod";
+export declare const TableMediaType = "text/csv";
+export declare const TableColumn: z.ZodString;
+export declare const TableCell: z.ZodString;
+export declare const TableRow: z.ZodArray<z.ZodString>;
+export declare const DefineTableInput: z.ZodObject<{
+    nodeId: z.ZodString;
+    columns: z.ZodArray<z.ZodString>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type DefineTableInput = z.infer<typeof DefineTableInput>;
+export declare const AppendTableRowsInput: z.ZodObject<{
+    nodeId: z.ZodString;
+    rows: z.ZodArray<z.ZodArray<z.ZodString>>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type AppendTableRowsInput = z.infer<typeof AppendTableRowsInput>;
+export declare const GetTableInput: z.ZodObject<{
+    nodeId: z.ZodString;
+}, z.core.$strict>;
+export type GetTableInput = z.infer<typeof GetTableInput>;
+export declare const AppendTableRowsResult: z.ZodObject<{
+    node: z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodNullable<z.ZodString>;
+        kind: z.ZodEnum<{
+            folder: "folder";
+            document: "document";
+            table: "table";
+            attachment: "attachment";
+        }>;
+        title: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        ownerId: z.ZodString;
+        currentVersionId: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+        archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+    version: z.ZodObject<{
+        id: z.ZodString;
+        nodeId: z.ZodString;
+        sequence: z.ZodNumber;
+        contentKey: z.ZodString;
+        mediaType: z.ZodString;
+        contentHash: z.ZodString;
+        size: z.ZodNumber;
+        segment: z.ZodNullable<z.ZodEnum<{
+            append: "append";
+            snapshot: "snapshot";
+        }>>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    appended: z.ZodNumber;
+}, z.core.$strict>;
+export type AppendTableRowsResult = z.infer<typeof AppendTableRowsResult>;
+export declare const TableRowPosition: z.ZodNumber;
+export declare const UpdateTableRowsInput: z.ZodObject<{
+    nodeId: z.ZodString;
+    baseVersionId: z.ZodString;
+    updates: z.ZodArray<z.ZodObject<{
+        position: z.ZodNumber;
+        row: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type UpdateTableRowsInput = z.infer<typeof UpdateTableRowsInput>;
+export declare const UpdateTableRowsResult: z.ZodObject<{
+    node: z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodNullable<z.ZodString>;
+        kind: z.ZodEnum<{
+            folder: "folder";
+            document: "document";
+            table: "table";
+            attachment: "attachment";
+        }>;
+        title: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        ownerId: z.ZodString;
+        currentVersionId: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+        archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+    version: z.ZodObject<{
+        id: z.ZodString;
+        nodeId: z.ZodString;
+        sequence: z.ZodNumber;
+        contentKey: z.ZodString;
+        mediaType: z.ZodString;
+        contentHash: z.ZodString;
+        size: z.ZodNumber;
+        segment: z.ZodNullable<z.ZodEnum<{
+            append: "append";
+            snapshot: "snapshot";
+        }>>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    updated: z.ZodNumber;
+}, z.core.$strict>;
+export type UpdateTableRowsResult = z.infer<typeof UpdateTableRowsResult>;
+export declare const DeleteTableRowsInput: z.ZodObject<{
+    nodeId: z.ZodString;
+    baseVersionId: z.ZodString;
+    positions: z.ZodArray<z.ZodNumber>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type DeleteTableRowsInput = z.infer<typeof DeleteTableRowsInput>;
+export declare const DeleteTableRowsResult: z.ZodObject<{
+    node: z.ZodObject<{
+        id: z.ZodString;
+        parentId: z.ZodNullable<z.ZodString>;
+        kind: z.ZodEnum<{
+            folder: "folder";
+            document: "document";
+            table: "table";
+            attachment: "attachment";
+        }>;
+        title: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        ownerId: z.ZodString;
+        currentVersionId: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+        archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>;
+    version: z.ZodObject<{
+        id: z.ZodString;
+        nodeId: z.ZodString;
+        sequence: z.ZodNumber;
+        contentKey: z.ZodString;
+        mediaType: z.ZodString;
+        contentHash: z.ZodString;
+        size: z.ZodNumber;
+        segment: z.ZodNullable<z.ZodEnum<{
+            append: "append";
+            snapshot: "snapshot";
+        }>>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    deleted: z.ZodNumber;
+}, z.core.$strict>;
+export type DeleteTableRowsResult = z.infer<typeof DeleteTableRowsResult>;
+export declare const RedefineTableColumn: z.ZodObject<{
+    name: z.ZodString;
+    source: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type RedefineTableColumn = z.infer<typeof RedefineTableColumn>;
+export declare const RedefineTableInput: z.ZodObject<{
+    nodeId: z.ZodString;
+    baseVersionId: z.ZodString;
+    columns: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        source: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type RedefineTableInput = z.infer<typeof RedefineTableInput>;

package/dist/contract/table.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { IdempotencyKey, IntelId } from "./contract.js";
+import { Node, NodeVersion } from "./node.js";
+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,
+});
+// ⚠️ 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 const GetTableInput = z.strictObject({
+    nodeId: IntelId.describe("Table node to read as a grid: header and every row."),
+});
+export const AppendTableRowsResult = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    appended: z.number().int().positive(),
+});
+// 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 const UpdateTableRowsResult = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    updated: z.number().int().positive(),
+});
+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 const DeleteTableRowsResult = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    deleted: z.number().int().positive(),
+});
+// 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."),
+});
+// 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,
+});

package/dist/contract/tool.d.ts

@@ -0,0 +1,122 @@
+import { z } from "zod";
+/**
+ * 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/api/src/tools/tool-servers` for why splitting on the underscore
+ * alone would be ambiguous.
+ */
+export declare const ToolServerHandle: z.ZodString;
+export type ToolServerHandle = z.infer<typeof ToolServerHandle>;
+export declare const ToolSourceUrl: z.ZodURL;
+export declare const ToolName: z.ZodString;
+export declare const ToolAnnotations: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+    destructiveHint: z.ZodOptional<z.ZodBoolean>;
+    idempotentHint: z.ZodOptional<z.ZodBoolean>;
+    openWorldHint: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ToolAnnotations = z.infer<typeof ToolAnnotations>;
+export declare const ToolCapability: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    annotations: z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+        destructiveHint: z.ZodOptional<z.ZodBoolean>;
+        idempotentHint: z.ZodOptional<z.ZodBoolean>;
+        openWorldHint: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    fingerprint: z.ZodString;
+}, z.core.$strict>;
+export type ToolCapability = z.infer<typeof ToolCapability>;
+export declare const ToolCatalog: z.ZodObject<{
+    portalConnected: z.ZodBoolean;
+    items: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodNullable<z.ZodString>;
+        description: z.ZodNullable<z.ZodString>;
+        inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        outputSchema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        annotations: z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+            destructiveHint: z.ZodOptional<z.ZodBoolean>;
+            idempotentHint: z.ZodOptional<z.ZodBoolean>;
+            openWorldHint: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        fingerprint: z.ZodString;
+    }, z.core.$strict>>;
+    reached: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+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 declare const ToolServer: z.ZodObject<{
+    handle: z.ZodString;
+    name: z.ZodString;
+    toolCount: z.ZodNumber;
+}, z.core.$strict>;
+export type ToolServer = z.infer<typeof ToolServer>;
+export declare const ToolServerCatalog: z.ZodObject<{
+    portalConnected: z.ZodBoolean;
+    items: z.ZodArray<z.ZodObject<{
+        handle: z.ZodString;
+        name: z.ZodString;
+        toolCount: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+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/api` cuts a delegation with it, `packages/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/api/src/tools/tool-servers`. This function only reads a name.
+ */
+export declare function serverOf(toolName: string, handles: Iterable<string>): string | null;
+export declare const TestToolInput: z.ZodObject<{
+    name: z.ZodString;
+    arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type TestToolInput = z.infer<typeof TestToolInput>;
+export declare const ExecuteToolInput: z.ZodObject<{
+    name: z.ZodString;
+    arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type ExecuteToolInput = z.infer<typeof ExecuteToolInput>;
+export declare const ToolTestResult: z.ZodObject<{
+    isError: z.ZodBoolean;
+    content: z.ZodArray<z.ZodUnknown>;
+    structuredContent: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+export type ToolTestResult = z.infer<typeof ToolTestResult>;