@anchrd/intel-contract 0.5.0 → 0.8.0

package/dist/contract/contract.d.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
 export declare const IntelId: z.ZodString;
 export declare const IsoDateTime: z.ZodISODateTime;
+export declare const UI_LANGUAGES: readonly ["en", "de", "es"];
+export type UiLanguage = (typeof UI_LANGUAGES)[number];
 export declare const ProblemDetails: z.ZodObject<{
     type: z.ZodString;
     status: z.ZodNumber;
@@ -478,6 +480,7 @@ export declare const AgentScheduleTarget: z.ZodObject<{
 export type AgentScheduleTarget = z.infer<typeof AgentScheduleTarget>;
 export declare const AgentSchedule: z.ZodObject<{
     cron: z.ZodString;
+    timezone: z.ZodDefault<z.ZodString>;
     target: z.ZodObject<{
         kind: z.ZodEnum<{
             document: "document";
@@ -496,18 +499,53 @@ export declare const AgentModel: z.ZodObject<{
 }, z.core.$strict>;
 export type AgentModel = z.infer<typeof AgentModel>;
 /**
- * ⚠️ No accounts, no secrets, no channels, and no tools — 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, and the tool catalog is a live `tools/list` that is never mirrored.
+ * 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`.
  *
- * ⚠️ 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.
+ * ⚠️ 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>;
+/**
+ * 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 declare const AgentToolSelection: z.ZodObject<{
+    servers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type AgentToolSelection = z.infer<typeof AgentToolSelection>;
+/**
+ * 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 declare const AgentToolDelegation: z.ZodObject<{
+    delegatedBy: z.ZodString;
+    servers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type AgentToolDelegation = z.infer<typeof AgentToolDelegation>;
 export declare const AgentDefinition: z.ZodObject<{
+    tools: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        delegatedBy: z.ZodString;
+        servers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
     references: z.ZodDefault<z.ZodArray<z.ZodObject<{
         nodeId: z.ZodString;
         role: z.ZodEnum<{
@@ -518,6 +556,7 @@ export declare const AgentDefinition: z.ZodObject<{
     }, z.core.$strict>>>;
     schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
         cron: z.ZodString;
+        timezone: z.ZodDefault<z.ZodString>;
         target: z.ZodObject<{
             kind: z.ZodEnum<{
                 document: "document";
@@ -535,10 +574,56 @@ export declare const AgentDefinition: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type AgentDefinition = z.infer<typeof AgentDefinition>;
+/**
+ * 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 declare const AgentDefinitionInput: z.ZodObject<{
+    tools: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        servers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    references: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        role: z.ZodEnum<{
+            "system-message": "system-message";
+            "semantic-context": "semantic-context";
+            memory: "memory";
+        }>;
+    }, z.core.$strict>>>;
+    schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        cron: z.ZodString;
+        timezone: z.ZodDefault<z.ZodString>;
+        target: z.ZodObject<{
+            kind: z.ZodEnum<{
+                document: "document";
+                flow: "flow";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>;
+    model: z.ZodObject<{
+        provider: z.ZodEnum<{
+            "workers-ai": "workers-ai";
+            anthropic: "anthropic";
+        }>;
+        model: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type AgentDefinitionInput = z.infer<typeof AgentDefinitionInput>;
 export declare const SaveAgentDefinitionInput: z.ZodObject<{
     nodeId: z.ZodString;
     baseVersionId: z.ZodNullable<z.ZodString>;
     definition: z.ZodObject<{
+        tools: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            servers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
         references: z.ZodDefault<z.ZodArray<z.ZodObject<{
             nodeId: z.ZodString;
             role: z.ZodEnum<{
@@ -549,6 +634,7 @@ export declare const SaveAgentDefinitionInput: z.ZodObject<{
         }, z.core.$strict>>>;
         schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
             cron: z.ZodString;
+            timezone: z.ZodDefault<z.ZodString>;
             target: z.ZodObject<{
                 kind: z.ZodEnum<{
                     document: "document";
@@ -597,6 +683,9 @@ export declare const CreateAgentInput: z.ZodObject<{
     title: z.ZodString;
     description: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     definition: z.ZodObject<{
+        tools: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            servers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
         references: z.ZodDefault<z.ZodArray<z.ZodObject<{
             nodeId: z.ZodString;
             role: z.ZodEnum<{
@@ -607,6 +696,7 @@ export declare const CreateAgentInput: z.ZodObject<{
         }, z.core.$strict>>>;
         schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
             cron: z.ZodString;
+            timezone: z.ZodDefault<z.ZodString>;
             target: z.ZodObject<{
                 kind: z.ZodEnum<{
                     document: "document";
@@ -662,6 +752,10 @@ export declare const NodeAgent: z.ZodObject<{
         createdAt: z.ZodISODateTime;
     }, z.core.$strict>>;
     definition: z.ZodNullable<z.ZodObject<{
+        tools: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            delegatedBy: z.ZodString;
+            servers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
         references: z.ZodDefault<z.ZodArray<z.ZodObject<{
             nodeId: z.ZodString;
             role: z.ZodEnum<{
@@ -672,6 +766,7 @@ export declare const NodeAgent: z.ZodObject<{
         }, z.core.$strict>>>;
         schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
             cron: z.ZodString;
+            timezone: z.ZodDefault<z.ZodString>;
             target: z.ZodObject<{
                 kind: z.ZodEnum<{
                     document: "document";
@@ -692,36 +787,19 @@ export declare const NodeAgent: z.ZodObject<{
 }, z.core.$strict>;
 export type NodeAgent = z.infer<typeof NodeAgent>;
 /**
- * The single value in Intel's wire formats that IS a credential (#182, D27).
+ * ⚠️ There is NO key field in this file, and adding one back would be the regression (D29, #207).
  *
- * ⚠️ It exists for exactly one response — the one that created the agent — and for no other. Gate
- * returns an Application key once in plain text and stores only its hash, so this is not a value
- * Intel could fetch again later even if it wanted to; nothing in Intel writes it to D1, to R2, to
- * an audit event or to a log, and no read surface has a field it could travel in. What the caller
- * does with it is named in `notice` rather than left to them: it belongs in the agent runtime's
- * `AGENT_APPLICATION_KEYS` secret, keyed by `agentId`, and nowhere else.
+ * 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.
  *
- * ⚠️ `agentId` is the Intel node ID and not the Application ID, because that is the key the runtime
- * looks an entry up by. Writing the Application ID into the runtime's map would produce a
- * deployment that parses, starts, and then cannot find a single agent.
- */
-export declare const AgentApplicationKey: z.ZodObject<{
-    agentId: z.ZodString;
-    applicationId: z.ZodString;
-    key: z.ZodString;
-    notice: z.ZodString;
-}, z.core.$strict>;
-export type AgentApplicationKey = z.infer<typeof AgentApplicationKey>;
-/**
- * What `POST /nodes/agents` and `agent_create` answer, and the only shape carrying a key. Every
- * other agent read answers with the plain `NodeAgent` above.
- *
- * ⚠️ `applicationKey` is `null` on a REPLAY, and that is the honest answer rather than a gap. An
- * idempotency key repeated after the first response was lost still returns the agent that exists —
- * the promise every create in Intel makes — but the key belonged to the one response that created
- * it and is gone from Gate. Minting a second principal to fill this field would leave the
- * installation with two machine accounts for one agent, one of which nobody would ever switch off.
- * `application_rotate_key` in Gate is the way to a new key, and it is a deliberate act.
+ * 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 declare const CreatedAgent: z.ZodObject<{
     node: z.ZodObject<{
@@ -758,6 +836,10 @@ export declare const CreatedAgent: z.ZodObject<{
         createdAt: z.ZodISODateTime;
     }, z.core.$strict>>;
     definition: z.ZodNullable<z.ZodObject<{
+        tools: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            delegatedBy: z.ZodString;
+            servers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
         references: z.ZodDefault<z.ZodArray<z.ZodObject<{
             nodeId: z.ZodString;
             role: z.ZodEnum<{
@@ -768,6 +850,7 @@ export declare const CreatedAgent: z.ZodObject<{
         }, z.core.$strict>>>;
         schedules: z.ZodDefault<z.ZodArray<z.ZodObject<{
             cron: z.ZodString;
+            timezone: z.ZodDefault<z.ZodString>;
             target: z.ZodObject<{
                 kind: z.ZodEnum<{
                     document: "document";
@@ -785,14 +868,26 @@ export declare const CreatedAgent: z.ZodObject<{
         }, z.core.$strict>;
     }, z.core.$strict>>;
     applicationId: z.ZodNullable<z.ZodString>;
-    applicationKey: z.ZodNullable<z.ZodObject<{
-        agentId: z.ZodString;
-        applicationId: z.ZodString;
-        key: z.ZodString;
-        notice: z.ZodString;
-    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type CreatedAgent = z.infer<typeof CreatedAgent>;
+export declare const RotateAgentKeyInput: z.ZodObject<{
+    nodeId: z.ZodString;
+}, z.core.$strict>;
+export type RotateAgentKeyInput = z.infer<typeof RotateAgentKeyInput>;
+/**
+ * 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 declare const AgentKeyRotated: z.ZodObject<{
+    nodeId: z.ZodString;
+    applicationId: z.ZodString;
+    rotatedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type AgentKeyRotated = z.infer<typeof AgentKeyRotated>;
 export declare const AgentList: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -1141,6 +1236,53 @@ export declare const ToolCatalog: z.ZodObject<{
     }, z.core.$strict>>;
 }, 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>>;

package/dist/contract/contract.js

@@ -1,6 +1,14 @@
 import { z } from "zod";
 export const IntelId = z.string().min(1).max(128);
 export const IsoDateTime = z.iso.datetime({ offset: true });
+// The languages whose UI catalog ships inside intel-ui. They live here rather than only in the UI
+// because `intel build` has to know them: a built-in language may be chosen as `ui.defaultLanguage`
+// without the customer listing a copy under `ui.languages` that would rot at every UI update.
+//
+// ⚠️ The list is a claim about the contents of packages/ui/src/i18n and cannot be checked here.
+// `i18n.unit.ts` compares it against the catalogs actually built in; a language listed here without
+// a file gives a red run there instead of a UI that starts on a catalog which does not exist.
+export const UI_LANGUAGES = ["en", "de", "es"];
 export const ProblemDetails = z.strictObject({
     type: z.string(),
     status: z.number().int().min(400).max(599),
@@ -283,8 +291,42 @@ export const AgentScheduleTarget = z.strictObject({
     kind: z.enum(["document", "flow"]),
     id: IntelId,
 });
+/**
+ * ⚠️ `timezone` is what the cron expression is READ IN, and it belongs to the schedule rather than
+ * to whoever is looking at it (#228). "Every morning at eight" means eight o'clock where the person
+ * who wrote it sits — in Berlin that is 06:00 UTC in summer and 07:00 in winter, and a field that
+ * does not carry the zone cannot express that difference. A UTC cron is an hour wrong twice a year
+ * and nobody sees why.
+ *
+ * The UI suggests the reader's own zone when a schedule is created, but it is not a per-user
+ * setting: an agent's schedule would otherwise move whenever its owner travelled, and it would mean
+ * different times to two people reading the same definition. What is stored is the answer.
+ *
+ * ⚠️ The default is `"UTC"`, and it is load-bearing rather than tidy: every definition written
+ * before this field parses to it and therefore keeps firing exactly when it did. A default of
+ * "whatever the writer's browser says" would silently move every existing schedule at the next save.
+ *
+ * The name is validated against this runtime's own tz database rather than a pattern. A regular
+ * expression would accept `Mars/Olympus`, and the failure would surface inside a Durable Object
+ * alarm — the place where nobody is watching.
+ */
+const IanaTimezone = z
+    .string()
+    .trim()
+    .min(1)
+    .max(64)
+    .refine((zone) => {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, { message: "must be an IANA timezone name this runtime knows, for example Europe/Berlin" });
 export const AgentSchedule = z.strictObject({
     cron: z.string().trim().min(1).max(120),
+    timezone: IanaTimezone.default("UTC"),
     target: AgentScheduleTarget,
 });
 export const AgentModel = z.strictObject({
@@ -292,10 +334,61 @@ export const AgentModel = z.strictObject({
     model: z.string().trim().min(1).max(120),
 });
 /**
- * ⚠️ No accounts, no secrets, no channels, and no tools — 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, and the tool catalog is a live `tools/list` that is never mirrored.
+ * 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
@@ -303,15 +396,37 @@ export const AgentModel = z.strictObject({
  * reader and released separately, so it must keep starting agents when Intel adds a field
  * tomorrow. The asymmetry is the point, not an oversight.
  */
-export const AgentDefinition = z.strictObject({
+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: AgentDefinition,
+    definition: AgentDefinitionInput,
     idempotencyKey: z.string().min(8).max(200),
 });
 export const GetAgentInput = z.strictObject({ nodeId: IntelId });
@@ -339,7 +454,7 @@ 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: AgentDefinition,
+    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
@@ -362,38 +477,37 @@ export const NodeAgent = z.strictObject({
     applicationId: GateApplicationId.nullable(),
 });
 /**
- * The single value in Intel's wire formats that IS a credential (#182, D27).
+ * ⚠️ There is NO key field in this file, and adding one back would be the regression (D29, #207).
  *
- * ⚠️ It exists for exactly one response — the one that created the agent — and for no other. Gate
- * returns an Application key once in plain text and stores only its hash, so this is not a value
- * Intel could fetch again later even if it wanted to; nothing in Intel writes it to D1, to R2, to
- * an audit event or to a log, and no read surface has a field it could travel in. What the caller
- * does with it is named in `notice` rather than left to them: it belongs in the agent runtime's
- * `AGENT_APPLICATION_KEYS` secret, keyed by `agentId`, and nowhere else.
+ * 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.
  *
- * ⚠️ `agentId` is the Intel node ID and not the Application ID, because that is the key the runtime
- * looks an entry up by. Writing the Application ID into the runtime's map would produce a
- * deployment that parses, starts, and then cannot find a single agent.
+ * 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 AgentApplicationKey = z.strictObject({
-    agentId: IntelId,
-    applicationId: GateApplicationId,
-    key: z.string().min(1),
-    notice: z.string().min(1),
-});
+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 `POST /nodes/agents` and `agent_create` answer, and the only shape carrying a key. Every
- * other agent read answers with the plain `NodeAgent` above.
+ * What replacing an agent's key answers.
  *
- * ⚠️ `applicationKey` is `null` on a REPLAY, and that is the honest answer rather than a gap. An
- * idempotency key repeated after the first response was lost still returns the agent that exists —
- * the promise every create in Intel makes — but the key belonged to the one response that created
- * it and is gone from Gate. Minting a second principal to fill this field would leave the
- * installation with two machine accounts for one agent, one of which nobody would ever switch off.
- * `application_rotate_key` in Gate is the way to a new key, and it is a deliberate act.
+ * ⚠️ 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 CreatedAgent = NodeAgent.extend({
-    applicationKey: AgentApplicationKey.nullable(),
+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
@@ -568,8 +682,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(),
@@ -593,6 +710,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({}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {