@anchrd/intel-contract 0.4.2 → 0.7.0

package/dist/contract/contract.js

@@ -16,10 +16,22 @@ export const SessionUser = z.strictObject({
     email: z.email(),
     name: z.string().min(1).max(240).nullable(),
 });
-// The fourth kind is `table` (#40). It is a kind of node, not a kind of thing: it hangs in the same
-// folder tree, inherits the same folder grants, carries the same immutable versions and the same
-// R2 body as a document (ADR-0004 §1). Only its media type and the one operation below differ.
-export const KnowledgeNodeKind = z.enum(["folder", "document", "attachment", "table"]);
+// What this installation is equipped to do — deployment facts, never the caller's permissions
+// (those stay behind each door, where `/session` deliberately does not carry them). `agentRuntime`
+// says whether an agent Worker is bound at all (#190): without it the UI offers no "New agent" and
+// an agent node explains itself instead of rendering views that could only end in a 503.
+export const IntelCapabilities = z.strictObject({
+    agentRuntime: z.boolean(),
+});
+// The fourth kind is `table` (#40) and the fifth is `agent` (#139). Each is a kind of node, not a
+// kind of thing: it hangs in the same folder tree, inherits the same folder grants, carries the
+// same immutable versions and the same R2 body as a document (ADR-0004 §1, ADR-0005 §1). Only the
+// media type and the operations below differ.
+//
+// ⚠️ `agent` being optional is load-bearing (ADR-0005 §1): an installation without a single agent
+// node is complete, not unfinished, and nothing here asks anyone to classify a document as a skill
+// or a policy in order to file it.
+export const NodeKind = z.enum(["folder", "document", "attachment", "table", "agent"]);
 // ⚠️ 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
@@ -34,10 +46,10 @@ export const SharePrincipal = z.discriminatedUnion("type", [
     z.strictObject({ type: z.literal("email"), email: z.email() }),
     z.strictObject({ type: z.literal("organization") }),
 ]);
-export const KnowledgeNode = z.strictObject({
+export const Node = z.strictObject({
     id: IntelId,
     parentId: IntelId.nullable(),
-    kind: KnowledgeNodeKind,
+    kind: NodeKind,
     title: z.string().min(1).max(240),
     description: z.string().max(2_000).nullable(),
     ownerId: IntelId,
@@ -46,7 +58,14 @@ export const KnowledgeNode = z.strictObject({
     updatedAt: IsoDateTime,
     archivedAt: IsoDateTime.nullable(),
 });
-export const KnowledgeVersion = z.strictObject({
+// What one table version carries (#135). An `append` holds only the rows one write added; a
+// `snapshot` holds the complete table — header and every row — so reading starts at the newest
+// snapshot and everything before it is history rather than content. Defining a table writes the
+// first snapshot; updating, deleting, and redefining write the later ones. Documents and
+// attachments carry `null`: each of their versions is complete by construction, and the word would
+// say nothing about them.
+export const NodeVersionSegment = z.enum(["append", "snapshot"]);
+export const NodeVersion = z.strictObject({
     id: IntelId,
     nodeId: IntelId,
     sequence: z.number().int().positive(),
@@ -54,10 +73,11 @@ export const KnowledgeVersion = z.strictObject({
     mediaType: z.string().min(1).max(160),
     contentHash: z.string().regex(/^[a-f0-9]{64}$/),
     size: z.number().int().nonnegative(),
+    segment: NodeVersionSegment.nullable(),
     createdBy: IntelId,
     createdAt: IsoDateTime,
 });
-export const ListKnowledgeNodesInput = z.strictObject({
+export const ListNodesInput = z.strictObject({
     parentId: IntelId.nullable().default(null),
     includeArchived: z.boolean().default(false),
     // ⚠️ Overrides `parentId` rather than narrowing beside it: what is archived is asked for across
@@ -69,30 +89,33 @@ export const ListKnowledgeNodesInput = z.strictObject({
     // caller would have to answer a question it is not asking.
     archivedOnly: z.boolean().optional(),
 });
-export const GetKnowledgeNodeInput = z.strictObject({ nodeId: IntelId });
-export const ListKnowledgeGrantsInput = z.strictObject({ resourceId: IntelId });
-export const CreateKnowledgeNodeInput = z.strictObject({
+export const GetNodeInput = z.strictObject({ nodeId: IntelId });
+// One pinned version of one node (#147). Both IDs, always: a version ID alone would let anyone
+// holding an ID read content whose node-level ACL they never passed, and a citation names both.
+export const GetNodeVersionInput = z.strictObject({ nodeId: IntelId, versionId: IntelId });
+export const ListGrantsInput = z.strictObject({ resourceId: IntelId });
+export const CreateNodeInput = z.strictObject({
     parentId: IntelId.nullable().default(null),
-    kind: KnowledgeNodeKind,
+    kind: NodeKind,
     title: z.string().trim().min(1).max(240),
     description: z.string().trim().max(2_000).nullable().default(null),
     idempotencyKey: z.string().min(8).max(200),
 });
-export const SaveKnowledgeVersionInput = z.strictObject({
+export const SaveNodeVersionInput = z.strictObject({
     nodeId: IntelId,
     baseVersionId: IntelId.nullable(),
     content: z.string().max(10_000_000),
     mediaType: z.string().min(1).max(160).default("text/markdown"),
     idempotencyKey: z.string().min(8).max(200),
 });
-export const SaveKnowledgeAttachmentInput = z.strictObject({
+export const SaveAttachmentInput = z.strictObject({
     nodeId: IntelId,
     baseVersionId: IntelId.nullable(),
     contentBase64: z.string().min(1).max(20_000_000),
     mediaType: z.string().min(1).max(160),
     idempotencyKey: z.string().min(8).max(200),
 });
-export const UpdateKnowledgeNodeInput = z
+export const UpdateNodeInput = z
     .strictObject({
     nodeId: IntelId,
     baseUpdatedAt: IsoDateTime,
@@ -102,30 +125,30 @@ export const UpdateKnowledgeNodeInput = z
     idempotencyKey: z.string().min(8).max(200),
 })
     .refine((input) => input.title !== undefined || input.description !== undefined || input.parentId !== undefined, { message: "At least one change is required" });
-export const ArchiveKnowledgeNodeInput = z.strictObject({
+export const ArchiveNodeInput = z.strictObject({
     nodeId: IntelId,
     baseUpdatedAt: IsoDateTime,
     archived: z.boolean(),
     idempotencyKey: z.string().min(8).max(200),
 });
-// ⚠️ `withChildren` gehört zur EBENE, nicht zum Knoten (#59). Ob etwas Kinder hat, die DIESER
-// Leser sehen darf, ist keine Eigenschaft der Sache — zwei Leser bekommen verschiedene Antworten.
-// Als Feld am Knoten müsste jede andere Stelle, die einen Knoten zurückgibt, es mitberechnen oder
-// lügen; als Liste neben den Einträgen kostet es nur die eine Antwort, die es braucht.
-export const KnowledgeNodeList = z.strictObject({
-    items: z.array(KnowledgeNode),
+// ⚠️ `withChildren` belongs to the LEVEL, not to the node (#59). Whether something has children
+// THIS reader may see is not a property of the thing — two readers get different answers. As a
+// field on the node, every other place that returns a node would have to compute it as well or
+// lie; as a list beside the entries it costs only the one answer that needs it.
+export const NodeList = z.strictObject({
+    items: z.array(Node),
     withChildren: z.array(IntelId).default([]),
 });
-export const KnowledgeVersionList = z.strictObject({ items: z.array(KnowledgeVersion) });
-export const KnowledgeDocument = z.strictObject({
-    node: KnowledgeNode,
-    version: KnowledgeVersion.nullable(),
+export const NodeVersionList = z.strictObject({ items: z.array(NodeVersion) });
+export const NodeDocument = z.strictObject({
+    node: Node,
+    version: NodeVersion.nullable(),
     content: z.string().nullable(),
 });
-export const KnowledgeAttachment = z.strictObject({
-    node: KnowledgeNode,
-    version: KnowledgeVersion,
-    resourceUri: z.string().regex(/^intel:\/\/knowledge\/[^/]+\/attachment$/),
+export const NodeAttachment = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    resourceUri: z.string().regex(/^intel:\/\/nodes\/[^/]+\/attachment$/),
 });
 // 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).
@@ -138,7 +161,7 @@ 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 DefineKnowledgeTableInput = z.strictObject({
+export const DefineTableInput = z.strictObject({
     nodeId: IntelId,
     columns: z
         .array(TableColumn)
@@ -151,31 +174,305 @@ export const DefineKnowledgeTableInput = z.strictObject({
 // 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 AppendKnowledgeTableRowsInput = z.strictObject({
+export const AppendTableRowsInput = z.strictObject({
     nodeId: IntelId,
     rows: z.array(TableRow).min(1).max(1_000),
     idempotencyKey: z.string().min(8).max(200),
 });
-export const GetKnowledgeTableInput = z.strictObject({ nodeId: IntelId });
+export const GetTableInput = z.strictObject({ nodeId: IntelId });
 // The table as a grid rather than as text: the server owns the one CSV reader, so no surface has to
 // grow a second one that would disagree with it about quoting.
-export const KnowledgeTable = z.strictObject({
-    node: KnowledgeNode,
+export const NodeTable = z.strictObject({
+    node: Node,
     columns: z.array(z.string()),
     rows: z.array(z.array(z.string())),
     // The newest append, or `null` while the table has no header yet.
     versionId: IntelId.nullable(),
 });
-export const AppendKnowledgeTableRowsResult = z.strictObject({
-    node: KnowledgeNode,
-    version: KnowledgeVersion,
+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();
+const distinctPositions = { error: "Row positions must be distinct" };
+// 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,
+    baseVersionId: IntelId,
+    updates: z
+        .array(z.strictObject({ position: TableRowPosition, row: TableRow }))
+        .min(1)
+        .max(1_000)
+        .refine((updates) => new Set(updates.map((update) => update.position)).size === updates.length, distinctPositions),
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const UpdateTableRowsResult = z.strictObject({
+    node: Node,
+    version: NodeVersion,
+    updated: z.number().int().positive(),
+});
+export const DeleteTableRowsInput = z.strictObject({
+    nodeId: IntelId,
+    baseVersionId: IntelId,
+    positions: z
+        .array(TableRowPosition)
+        .min(1)
+        .max(1_000)
+        .refine((positions) => new Set(positions).size === positions.length, distinctPositions),
+    idempotencyKey: z.string().min(8).max(200),
+});
+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,
+    source: TableColumn.nullable().default(null),
+});
+// 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,
+    baseVersionId: IntelId,
+    columns: z
+        .array(RedefineTableColumn)
+        .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: z.string().min(8).max(200),
+});
+// ── The agent definition (#139, ADR-0005 §4) ─────────────────────────────────────────────────────
+//
+// An agent's body is a definition, stored as an immutable version in R2 exactly like a document's.
+// Its own media type exists so a reader can tell a definition from prose without parsing it.
+export const AgentMediaType = "application/vnd.anchrd.agent+json";
+// ⚠️ The role lives on the AGENT, never on the node it names, and that is the whole difference to
+// the removed `context_policy` (ADR-0005 §2, #76). The same folder can be the system message for
+// one agent and nothing but search space for another; a node has no opinion about how it is used.
+// Any future field on a node saying how it should be loaded is `context_policy` under a new name.
+//
+//   system-message    prepended verbatim by the runtime
+//   semantic-context  search space; the agent searches it when it decides to
+//   memory            write target — ordinary Knowledge, versioned and readable like everything else
+export const AgentReferenceRole = z.enum(["system-message", "semantic-context", "memory"]);
+export const AgentReference = z.strictObject({ nodeId: IntelId, role: AgentReferenceRole });
+// A `document` target means the content of that document is the instruction — a "skill" somebody
+// wrote as ordinary text; a `flow` target means a run is started through Intel MCP and worked step
+// by step. Both are references, so nothing in here goes stale (ADR-0005 §4).
+//
+// ⚠️ Intel stores a schedule as a declared fact and never fires it. The alarm lives in the runtime
+// (ADR-0005 §3); Intel gains no scheduler, which is D24 confirmed rather than bent.
+export const AgentScheduleTarget = z.strictObject({
+    kind: z.enum(["document", "flow"]),
+    id: IntelId,
+});
+export const AgentSchedule = z.strictObject({
+    cron: z.string().trim().min(1).max(120),
+    target: AgentScheduleTarget,
+});
+export const AgentModel = z.strictObject({
+    provider: z.enum(["workers-ai", "anthropic"]),
+    model: z.string().trim().min(1).max(120),
+});
+/**
+ * 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 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");
+const ToolServerHandles = z.array(ToolServerHandle).max(32).default([]);
+/**
+ * What a caller may ASK for: whole MCP servers, and nothing about who delegates them (D30).
+ *
+ * ⚠️ The absence of `delegatedBy` is the point, and it is why the write shape differs from the read
+ * shape at all. Intel writes that field from the session it authorized; a caller who could name
+ * somebody else would be handing an agent a portal connection they do not have, and the agent would
+ * act on it unattended. Leaving the field out of the input makes that structural instead of a
+ * runtime overwrite: a body carrying it is a parse error at the boundary, on every surface, and no
+ * screen ever has to invent a value it has no business knowing.
+ */
+export const AgentToolSelection = z.strictObject({ servers: ToolServerHandles });
+/**
+ * What is STORED and read back: the selection plus whose portal connection it came from (D30).
+ *
+ * ⚠️ This is a selection, not a permission. Nothing here grants anything: whether a server is
+ * reachable is still decided by one live `tools/list` with `delegatedBy`'s own portal token, so a
+ * delegator who loses the server or the connection takes it away from the agent at the next run
+ * with no edit to this document.
+ *
+ * ⚠️ Read shape only. It appears in `AgentDefinition` and never in an input — see
+ * `AgentToolSelection` for why the two are deliberately different documents rather than one schema
+ * with an optional field.
+ */
+export const AgentToolDelegation = z.strictObject({
+    delegatedBy: IntelId,
+    servers: ToolServerHandles,
+});
+/**
+ * ⚠️ No accounts, no secrets and no channels — and the reason is mechanical rather than tidy
+ * (ADR-0005 §4): this body is read, shared, exported and put into model context, so a secret in it
+ * is a secret in a citation. Identity is Gate's, accounts are the portal's, channels are runtime
+ * configuration.
+ *
+ * ⚠️ `tools` is the one correction to that list (D30), and it is narrower than it looks. What is
+ * stored is a **selection of whole servers plus who delegated them**, never a mirrored permission
+ * and never a catalog: the catalog stays a live `tools/list` made with the delegator's token at the
+ * moment the agent runs. ADR-0005 §4's "no tools in the definition" forbade the mirror, and the
+ * mirror is still forbidden — a tool name, a schema or an account in here would be the thing that
+ * line was written against.
+ *
+ * ⚠️ Strict on purpose, and deliberately stricter than the runtime's own reader
+ * (`packages/agent/src/definition/definition.ts`, which is `z.object`). Intel is the writer: an
+ * unknown field here is a caller's mistake and is refused at the boundary. The runtime is the
+ * reader and released separately, so it must keep starting agents when Intel adds a field
+ * tomorrow. The asymmetry is the point, not an oversight.
+ */
+const AgentBody = {
+    references: z.array(AgentReference).max(200).default([]),
+    schedules: z.array(AgentSchedule).max(50).default([]),
+    model: AgentModel,
+};
+export const AgentDefinition = z.strictObject({
+    ...AgentBody,
+    // `null` is "this agent has no tools", and it is also what every definition written before D30
+    // parses to. An empty `servers` list means the same thing and is kept as its own state so
+    // removing the last server does not have to erase who was delegating.
+    tools: AgentToolDelegation.nullable().default(null),
+});
+/**
+ * The same document as `AgentDefinition`, minus the one field a caller may not write.
+ *
+ * ⚠️ Two schemas rather than one, and the split is load-bearing (#208, D30). Everything an agent IS
+ * comes from whoever edits it; **whose portal connection it acts on** does not, because that is an
+ * authority the editor would be granting to themselves. So the write shape simply has no place to
+ * put it: `{ tools: { servers: [...] } }` is what a screen or an MCP client sends, Intel adds
+ * `delegatedBy` from the session, and a body that tries to name one is refused by the strict object
+ * before any of it is read. The reading shape keeps the field because a reader must be able to see
+ * whose connection an agent runs on.
+ */
+export const AgentDefinitionInput = z.strictObject({
+    ...AgentBody,
+    tools: AgentToolSelection.nullable().default(null),
+});
+export const SaveAgentDefinitionInput = z.strictObject({
+    nodeId: IntelId,
+    baseVersionId: IntelId.nullable(),
+    definition: AgentDefinitionInput,
+    idempotencyKey: z.string().min(8).max(200),
+});
+export const GetAgentInput = z.strictObject({ nodeId: IntelId });
+// Switching an agent off and on again, and starting one run by hand. All three name only the agent
+// and — for a run — which of the targets it already schedules.
+//
+// ⚠️ Intel holds none of this. Whether an agent is paused is state of its Durable Object, not a
+// field of the definition: a definition is versioned, shared and read into model context (ADR-0005
+// §4), so every pause would otherwise be a new version and would tell the agent it is switched off.
+// These inputs are what Intel accepts and passes on, nothing that Intel stores.
+export const PauseAgentInput = z.strictObject({ nodeId: IntelId });
+export const RunAgentNowInput = z.strictObject({
+    nodeId: IntelId,
+    target: AgentScheduleTarget,
+});
+// ⚠️ Three states, not two, and the same three the flow list makes: omitted is the whole tree,
+// `null` is the root level, an ID is that folder. "Which agents may I use" is a question about the
+// tree rather than about one folder, so the useful answer has to be reachable without knowing where
+// somebody filed them.
+export const ListAgentsInput = z.strictObject({
+    parentId: IntelId.nullable().optional(),
+    includeArchived: z.boolean().default(false),
+});
+export const CreateAgentInput = z.strictObject({
+    parentId: IntelId.nullable().default(null),
+    title: z.string().trim().min(1).max(240),
+    description: z.string().trim().max(2_000).nullable().default(null),
+    definition: AgentDefinitionInput,
+    idempotencyKey: z.string().min(8).max(200),
+});
+// The ID of the Gate Application an agent runs as. Deliberately NOT an `IntelId`: it is Better
+// Auth's user ID, minted in Gate and only ever handed back to Gate, so validating it against
+// Intel's own ID shape would be Intel inventing a rule about somebody else's identifier.
+export const GateApplicationId = z.string().min(1).max(255);
+// The definition is `null` exactly while the node exists and no version has been written yet — the
+// same window in which a document's content is `null`.
+//
+// ⚠️ `applicationId` names the machine principal, it does not authenticate it (#182, D27). That is
+// why the ID may be stored, listed and drawn while the key may not: one is a name, the other is the
+// credential, and Gate hands the credential out exactly once and keeps only its hash. `null` means
+// this agent has no Application — an agent node written before #182, restored from a bundle, or
+// imported from another installation. Such an agent is not switched with its node, and giving it a
+// principal is an operator's act in Gate.
+export const NodeAgent = z.strictObject({
+    node: Node,
+    version: NodeVersion.nullable(),
+    definition: AgentDefinition.nullable(),
+    applicationId: GateApplicationId.nullable(),
+});
+/**
+ * ⚠️ There is NO key field in this file, and adding one back would be the regression (D29, #207).
+ *
+ * Until #207 the create answer carried the Application key in plain text, once, and a person had to
+ * carry it into a Worker secret by hand — which is why an agent created through the screen could
+ * never run (#200). The key now goes from Gate straight into the agent runtime over Intel's service
+ * binding and is encrypted into that agent's Durable Object; it reaches no browser, no MCP tool
+ * result and no response body at all. `NodeAgent` is a `z.strictObject`, so a field named `key`
+ * added anywhere in this file is a parse error at the boundary rather than a leak somebody has to
+ * spot in review.
+ *
+ * What `POST /nodes/agents` and `agent_create` answer is therefore exactly what every read answers:
+ * the node, its first definition, and the `applicationId` that NAMES the principal without
+ * authenticating it.
+ */
+export const CreatedAgent = NodeAgent;
+// Which agent's key is being replaced. `nodeId` and not the Application ID: this addresses an agent
+// in Intel's tree, and the Application behind it is Intel's to look up — a caller naming the
+// principal directly would be rotating a key for an agent nobody checked they may edit.
+export const RotateAgentKeyInput = z.strictObject({ nodeId: IntelId });
+/**
+ * What replacing an agent's key answers.
+ *
+ * ⚠️ No key, and that is the whole shape of D29: Intel asks Gate for a new one, hands it to the
+ * runtime over the service binding, and forgets it inside the same call. What the caller gets is
+ * the fact that it happened, so a screen can say so — `applicationId` names the principal whose key
+ * was replaced, which is a name and not a credential.
+ */
+export const AgentKeyRotated = z.strictObject({
+    nodeId: IntelId,
+    applicationId: GateApplicationId,
+    rotatedAt: IsoDateTime,
+});
+export const AgentList = z.strictObject({ items: z.array(Node) });
 // ⚠️ Kept for what is already stored, not for what is written. Relations were picked in a dialog
 // until #41; a link is now made where it is meant — in the text — and every link written from now
 // on is a `references`. Rewriting the old rows would destroy a distinction somebody chose on
 // purpose, and dropping the column would destroy it with them, so both stay readable.
-export const KnowledgeLinkRelation = z.enum(["references", "related", "depends_on", "implements"]);
+export const NodeLinkRelation = z.enum(["references", "related", "depends_on", "implements"]);
 // Where the link came from. `text` links are derived from a document's content and are rewritten
 // whenever it is saved; `manual` links were made in the dialog #41 removed and are now history.
 //
@@ -183,28 +480,28 @@ export const KnowledgeLinkRelation = z.enum(["references", "related", "depends_o
 // between them, and nothing may start writing `manual` again — that would be the two ways of saying
 // one thing that #41 exists to end. It exists so that saving a document cannot delete a link
 // somebody made before there was another way to make one.
-export const KnowledgeLinkOrigin = z.enum(["text", "manual"]);
-export const KnowledgeLink = z.strictObject({
+export const NodeLinkOrigin = z.enum(["text", "manual"]);
+export const NodeLink = z.strictObject({
     id: IntelId,
     sourceNodeId: IntelId,
     targetNodeId: IntelId,
-    relation: KnowledgeLinkRelation,
-    origin: KnowledgeLinkOrigin,
+    relation: NodeLinkRelation,
+    origin: NodeLinkOrigin,
     label: z.string().trim().min(1).max(120).nullable(),
     createdBy: IntelId,
     createdAt: IsoDateTime,
 });
-export const KnowledgeLinkList = z.strictObject({ items: z.array(KnowledgeLink) });
+export const NodeLinkList = z.strictObject({ items: z.array(NodeLink) });
 // The inline element a document link is, inside a BlockNote document (#41).
 //
 // ⚠️ The ID and nothing else. No title and no path travel with it: a stored title would go stale
 // the moment the target is renamed, a stored path the moment it is moved — and either one would
 // put a name the reader may not see into a document they may.
 export const DocumentLinkInlineType = "documentLink";
-export const ResolveKnowledgeLinksInput = z.strictObject({
+export const ResolveNodeLinksInput = z.strictObject({
     nodeIds: z.array(IntelId).min(1).max(200),
 });
-export const ResolvedKnowledgeLink = z.strictObject({
+export const ResolvedNodeLink = z.strictObject({
     nodeId: IntelId,
     title: z.string().min(1).max(240),
 });
@@ -213,15 +510,15 @@ export const ResolvedKnowledgeLink = z.strictObject({
 // side of a document link is drawn from, and an entry that says "something is here" is exactly the
 // leak this schema has to make impossible to write by accident. Deleted and unreadable therefore
 // look identical from the outside, which is the point.
-export const ResolveKnowledgeLinksResult = z.strictObject({
-    items: z.array(ResolvedKnowledgeLink),
+export const ResolveNodeLinksResult = z.strictObject({
+    items: z.array(ResolvedNodeLink),
 });
-export const KnowledgeGraphInput = z.strictObject({
+export const NodeGraphInput = z.strictObject({
     limit: z.number().int().min(1).max(500).default(250),
 });
-export const KnowledgeGraph = z.strictObject({
-    nodes: z.array(KnowledgeNode),
-    links: z.array(KnowledgeLink),
+export const NodeGraph = z.strictObject({
+    nodes: z.array(Node),
+    links: z.array(NodeLink),
 });
 export const BlockNoteMediaType = "application/vnd.anchrd.intel.blocknote+json";
 export const BlockNoteDocument = z.strictObject({
@@ -239,14 +536,14 @@ export const ResourceGrant = z.strictObject({
     createdBy: IntelId,
     createdAt: IsoDateTime,
 });
-export const ShareKnowledgeInput = z.strictObject({
+export const ShareInput = z.strictObject({
     resourceId: IntelId,
     principal: SharePrincipal,
     verb: ResourceVerb,
     expiresAt: IsoDateTime.nullable().default(null),
     idempotencyKey: z.string().min(8).max(200),
 });
-export const RevokeKnowledgeGrantInput = z.strictObject({
+export const RevokeGrantInput = z.strictObject({
     resourceId: IntelId,
     grantId: IntelId,
     idempotencyKey: z.string().min(8).max(200),
@@ -257,16 +554,16 @@ export const RevokeKnowledgeGrantInput = z.strictObject({
 //
 // ⚠️ `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 UnreadableKnowledge = z.strictObject({
+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 ShareKnowledgeResult = z.strictObject({
+export const ShareResult = z.strictObject({
     grant: ResourceGrant,
-    unreadable: UnreadableKnowledge,
+    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).
@@ -275,11 +572,16 @@ export const ResourceGrantList = z.strictObject({
     applicableVerbs: z.array(ResourceVerb).min(1),
     items: z.array(ResourceGrant),
 });
-export const SearchKnowledgeInput = z.strictObject({
+// `scopeId` is a cut, never a grant (#126): it narrows an answer the actor is already entitled to
+// and can only ever remove rows. Without it the search stays global over everything visible, which
+// is why it is optional rather than nullable — an absent field and `null` would otherwise be two
+// spellings of the same request.
+export const SearchInput = z.strictObject({
     query: z.string().trim().min(1).max(500),
     limit: z.number().int().min(1).max(50).default(10),
+    scopeId: IntelId.optional().describe("Optional folder node id. When given, only nodes filed in that folder or beneath it are searched."),
 });
-export const KnowledgeCitation = z.strictObject({
+export const NodeCitation = z.strictObject({
     nodeId: IntelId,
     versionId: IntelId,
     title: z.string(),
@@ -289,10 +591,10 @@ export const KnowledgeCitation = z.strictObject({
     score: z.number().min(0).max(1),
     match: z.enum(["lexical", "semantic", "hybrid"]),
 });
-export const SearchKnowledgeResult = z.strictObject({
-    items: z.array(KnowledgeCitation),
+export const SearchResult = z.strictObject({
+    items: z.array(NodeCitation),
 });
-export const ReindexKnowledgeResult = z.strictObject({ queued: z.number().int().nonnegative() });
+export const ReindexResult = z.strictObject({ queued: z.number().int().nonnegative() });
 export const RevokeGrantResult = z.strictObject({ revoked: z.boolean() });
 function isPrivateIpv4(hostname) {
     const parts = hostname.split(".").map(Number);
@@ -338,8 +640,11 @@ export const ToolSourceUrl = z.url().refine((value) => {
         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. Intel
-// never learns which server that is — the portal resolves it and attaches the 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(),
@@ -363,6 +668,58 @@ export const ToolCatalog = z.strictObject({
     portalConnected: z.boolean(),
     items: z.array(ToolCapability),
 });
+/**
+ * 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),
+});
+// 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),
+});
+/**
+ * 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 function serverOf(toolName, handles) {
+    let best = 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,
     arguments: z.record(z.string(), z.unknown()).default({}),
@@ -526,7 +883,7 @@ export const FlowGraph = z.strictObject({
 });
 export const Flow = z.strictObject({
     id: IntelId,
-    // The one thing a Flow shares with a document: its place in the Knowledge folder tree (ADR-0004).
+    // The one thing a Flow shares with a document: its place in the shared folder tree (ADR-0004).
     // Everything else stays apart — versions, R2 body and Vectorize belong to the document, the graph,
     // runs and approvals to the flow. `null` is the root of that same tree.
     parentId: IntelId.nullable(),
@@ -551,30 +908,52 @@ export const FlowDocument = z.strictObject({
     flow: Flow,
     version: FlowVersion.nullable(),
 });
-// Dasselbe für Flows: welche von ihnen einen anderen Flow rufen, den dieser Leser auch sehen darf
-// (#59). Ein Aufklapp-Pfeil an einem Flow, dessen Aufrufe alle verborgen sind, verspricht Inhalt,
-// den das Aufklappen nicht liefern kann.
+// One version as the history shows it: the metadata without the graph it carries. A flow's history
+// is as long as its edits, and a list that shipped every graph would pay for drawings nobody asked
+// for — whoever needs one asks for that one version.
+export const FlowVersionSummary = z.strictObject({
+    id: IntelId,
+    flowId: IntelId,
+    sequence: z.number().int().positive(),
+    createdBy: IntelId,
+    createdAt: IsoDateTime,
+    // Whether this is the version the flow currently publishes. Derived from the flow row when the
+    // list is read, never stored on the version: a version is immutable and "published" is not a
+    // property of it — it is the flow's choice, revocable without touching the version.
+    published: z.boolean(),
+});
+export const FlowVersionList = z.strictObject({
+    flowId: IntelId,
+    items: z.array(FlowVersionSummary),
+});
+// Both identifiers, deliberately: a version ID alone would resolve whatever version carries it,
+// whichever flow it belongs to, and the ACL is answered on the flow. The pair makes a foreign
+// version a 404 rather than a read.
+export const GetFlowVersionInput = z.strictObject({ flowId: IntelId, versionId: IntelId });
+// The same for flows: which of them call another flow that this reader may also see (#59). An
+// expand arrow on a flow whose calls are all hidden promises content that expanding it cannot
+// deliver.
 export const FlowList = z.strictObject({
     items: z.array(Flow),
     withCalls: z.array(IntelId).default([]),
 });
-export const FlowKnowledgeReference = z.strictObject({
+export const ReferencedNode = z.strictObject({
     id: IntelId,
     title: z.string().min(1).max(240),
 });
-// What a flow touches: the documents its Knowledge steps name and the tools its Tool steps call,
+// What a flow touches: the documents its tree links name and the tools its Tool steps call,
 // read straight out of the graph. Deliberately not a conflict report — there is no arithmetic here
 // and nothing that can go stale, because the graph is the answer. Whether a given person may reach
 // any of it is decided where it can be decided honestly: when the folder is shared, and at runtime
 // (ADR-0004 §4). For tools it can only ever be the latter, because the catalog is a live query with
 // the requesting user's own token (ADR-0003).
 //
-// ⚠️ `knowledge` names only what the asking user may see. The rest is `hiddenKnowledge`, a count.
+// ⚠️ `nodes` names only what the asking user may see. The rest is `hiddenNodes`, a count.
 export const FlowRequirements = z.strictObject({
     flowId: IntelId,
     versionId: IntelId.nullable(),
-    knowledge: z.array(FlowKnowledgeReference),
-    hiddenKnowledge: z.number().int().nonnegative(),
+    nodes: z.array(ReferencedNode),
+    hiddenNodes: z.number().int().nonnegative(),
     tools: z.array(ToolName),
 });
 // What stands between this flow and a run, asked on demand and answered for the person asking.
@@ -630,12 +1009,12 @@ export const ListFlowsInput = z.strictObject({
     // behind the relation graph has no such flag on purpose (#30). A drawing that includes what was
     // archived says the tidying up never happened.
     //
-    // ⚠️ `.optional()` rather than `.default(false)`, unlike `ListKnowledgeNodesInput`. This schema is
+    // ⚠️ `.optional()` rather than `.default(false)`, unlike `ListNodesInput`. This schema is
     // the argument type of `listFlows` on three layers, and a default makes the field required in the
     // *parsed* type — every existing caller that lists a folder would have to spell out the answer to
     // a question it is not asking. Absent means "without the archive" everywhere it is read.
     includeArchived: z.boolean().optional(),
-    // The same question for flows, and the same override of `parentId` — see `ListKnowledgeNodesInput`.
+    // The same question for flows, and the same override of `parentId` — see `ListNodesInput`.
     archivedOnly: z.boolean().optional(),
 });
 export const GetFlowInput = z.strictObject({ flowId: IntelId });
@@ -650,6 +1029,13 @@ export const PublishFlowInput = z.strictObject({
     versionId: IntelId,
     idempotencyKey: z.string().min(8).max(200),
 });
+// The way back out of a publication (#146). No versionId: what is withdrawn is whatever is
+// published now, and naming one would invite a race between reading it and revoking it. Versions
+// are untouched — republishing any of them is one `publish` away.
+export const UnpublishFlowInput = z.strictObject({
+    flowId: IntelId,
+    idempotencyKey: z.string().min(8).max(200),
+});
 export const PreviewFlowPublishInput = z.strictObject({ flowId: IntelId, versionId: IntelId });
 // One sub-flow call as publishing will leave it (ADR-0004 §5). `freezes` is the whole point of the
 // preview: it marks the calls whose `latest` publishing turns into `versionId`, so the author reads
@@ -682,7 +1068,14 @@ export const FlowPublishPreview = z.strictObject({
 // What accesses what, for one level of the shared tree (#19). A folder answers it for its contents,
 // a single flow for itself. Documents and flows are two kinds of thing that share one tree
 // (ADR-0004 §1), so the graph carries both and says which of them it is.
-export const RelationNodeKind = z.enum(["folder", "document", "attachment", "table", "flow"]);
+export const RelationNodeKind = z.enum([
+    "folder",
+    "document",
+    "attachment",
+    "table",
+    "agent",
+    "flow",
+]);
 export const RelationNode = z.strictObject({
     id: IntelId,
     kind: RelationNodeKind,
@@ -767,6 +1160,13 @@ export const StartFlowRunInput = z.strictObject({
     idempotencyKey: z.string().min(8).max(200),
 });
 export const GetFlowRunInput = z.strictObject({ runId: IntelId });
+// Ending a run on purpose (#145). Until this existed the only way off a parked manual step was
+// `completeStep` with `outcome: "failed"` — which recorded a step failure that never happened.
+// Cancelling records nothing into the step history: the run ends, the history stays true.
+export const CancelFlowRunInput = z.strictObject({
+    runId: IntelId,
+    idempotencyKey: z.string().min(8).max(200),
+});
 export const CompleteFlowRunStepInput = z.strictObject({
     runId: IntelId,
     nodeId: FlowNodeId,
@@ -801,7 +1201,7 @@ export const FlowRunFailure = z.strictObject({
 });
 // One run as a list shows it: what it did, never what it produced.
 //
-// ⚠️ Neither `input` nor `output` is in here, on purpose. A run reaches its Knowledge and its tools
+// ⚠️ Neither `input` nor `output` is in here, on purpose. A run reaches its nodes and its tools
 // with the rights of whoever started it, so its result is a way to content the next reader of this
 // list may have no claim to. Whoever wants a result asks for the run itself, where the same rule
 // decides again.
@@ -854,3 +1254,51 @@ export const FlowRunHistory = z.strictObject({
     steps: z.array(FlowRunStepRecord),
     trail: z.array(FlowRunTrailEntry),
 });
+// ── Bundle export (#136) ────────────────────────────────────────────────────────────────────────
+// The one name the importer looks for at the zip root. A different spelling would make a bundle a
+// naked folder, so the constant lives in the contract rather than in each surface.
+export const BundleManifestFilename = "manifest.json";
+// What a bundle entry can be. `flow` joins the five node kinds because a flow shares the folder
+// tree without being a node (ADR-0004), and the bundle mirrors the tree, not the tables.
+export const BundleEntryKind = z.enum([
+    "folder",
+    "document",
+    "table",
+    "attachment",
+    "agent",
+    "flow",
+]);
+// One entry of the manifest: the identity a re-import needs, next to the relative path where the
+// bytes sit in the zip. A folder carries no media type — it has no bytes.
+export const BundleManifestEntry = z.strictObject({
+    id: IntelId,
+    kind: BundleEntryKind,
+    title: z.string().min(1).max(240),
+    description: z.string().max(2_000).nullable(),
+    mediaType: z.string().min(1).max(160).nullable(),
+    // Relative to the zip root, forward slashes, no leading slash. Folders end with a slash so an
+    // empty folder still has an address.
+    path: z.string().min(1).max(4_000),
+});
+// What an export leaves out on purpose, named so a bundle says it rather than a reader guessing:
+// version history, grants/shares, flow runs, and archived nodes are not in any bundle (#136).
+export const BundleExclusion = z.enum(["version-history", "grants", "flow-runs", "archived-nodes"]);
+export const BundleManifest = z.strictObject({
+    version: z.literal(1),
+    exportedAt: IsoDateTime,
+    // The node the export started at; `null` is the root of the tree — the whole installation as the
+    // exporting caller may read it.
+    rootId: IntelId.nullable(),
+    entries: z.array(BundleManifestEntry),
+    excluded: z.array(BundleExclusion),
+});
+// ── Bundle import (#137) ────────────────────────────────────────────────────────────────────────
+// What one import made. Import always creates new nodes — no merge, no overwrite, no restored IDs
+// (#137, phase 1) — so the answer is counts and the new roots, never a diff. `replayed` marks the
+// idempotent second answer to the same key: nothing was created twice.
+export const BundleImportResult = z.strictObject({
+    nodes: z.number().int().nonnegative(),
+    flows: z.number().int().nonnegative(),
+    rootNodeIds: z.array(IntelId),
+    replayed: z.boolean(),
+});