@anchrd/intel-api 0.7.0 → 0.9.0

package/README.md

@@ -112,17 +112,36 @@ caller without it is refused with `agent_application_forbidden`, and a Gate that
 with `agent_application_unavailable` — in which case **no agent node is created at all**. There is
 deliberately no half-created agent to repair later; the request is simply repeated.
 
-The response to `POST /api/v1/nodes/agents` (and to the `agent_create` MCP tool) is the only place
-in Intel where a credential appears:
-
-1. It carries `applicationKey.key` **once**, in plain text. Gate issues an Application key a single
-   time and stores only its hash, and Intel writes it to no table, no R2 object, no audit event and
-   no log. Nothing can hand it out a second time — `application_rotate_key` in Gate issues a new one.
-2. Put it into the agent runtime's `AGENT_APPLICATION_KEYS` secret, keyed by the **agent node ID**
-   that comes back as `applicationKey.agentId`, and store it nowhere else. That secret carries the
-   whole list, so `wrangler secret put` is given every entry, not only the new one.
-3. Grant the application what this agent may reach — its Gate roles, and the resource grants on the
-   Intel nodes it works with. That step is what makes the agent's reach its own and stays manual.
+**No response in Intel carries a credential.** The Application key Gate issues once, in plain text,
+is handed to the agent runtime over the `AGENT` service binding inside the same request, and the
+runtime encrypts it into that agent's Durable Object. Intel writes it to no table, no R2 object, no
+audit event, no log and no response body; the browser never sees it, and neither does an MCP client.
+The agent can run the moment it exists — there is no secret to set and no terminal to open.
+
+The handover carries the caller's own bearer plus `AGENT_HANDOVER_SECRET`, the one value Intel and
+the agent runtime share. The runtime cannot check Intel's resource ACLs, so that secret is what says
+the key came through Intel rather than off the open internet; without it on both Workers, creating an
+agent refuses by name.
+
+The handover happens **before** the node row, for the same reason the Gate call does: a runtime that
+will not take the key leaves no agent behind, and the freshly minted Application is switched off
+again. There is deliberately no half-created agent to repair later; the request is simply repeated.
+
+What still stays manual is the reach: grant the application its Gate roles and the resource grants
+on the Intel nodes it works with. That is what makes the agent's reach its own.
+
+`POST /api/v1/nodes/agents/<id>/rotate-key` (and the `agent_rotate_key` MCP tool) replaces the key:
+Intel asks Gate for a new one and hands it to the runtime the same way, the previous key stops
+working at once, and the answer names the principal and the moment rather than the key. It needs
+`knowledge:write` in Intel plus write access to the agent node, and the applications permission in
+Gate. It is the repair for a run that fails with `agent_key_missing`.
+
+**A written schedule is an armed one.** The agent runtime sets its alarm only when something tells
+it to look, so Intel calls `POST /agents/<id>/schedules/sync` over the same service binding after
+every definition write — creating an agent with schedules, and every save. That call goes down the
+handover route with the caller's own bearer beside `AGENT_HANDOVER_SECRET`, because arming an agent
+belongs to editing one and not to driving one. A save whose arming fails keeps the definition it
+wrote and answers `agent_schedules_not_armed`: the version is current, and saving again arms it.
 
 Intel keeps `applicationId` beside the node and returns it on every agent read. It names the
 principal without authenticating it, which is why it may be stored and shown while the key may not.

package/dist/adapters/cloudflare/cloudflare.js

@@ -25,6 +25,7 @@ import { createPortalTokenStore } from "../portal-tokens/portal-tokens.js";
 import { createRemoteTools } from "../remote-tools/remote-tools.js";
 import { createSemanticIndex } from "../semantic-index/semantic-index.js";
 import { createSessionCodec } from "../session-cookie/session-cookie.js";
+import { createToolDelegation } from "../tool-delegation/tool-delegation.js";
 import { createToolSourcePolicy } from "../tool-source-policy/tool-source-policy.js";
 // biome-ignore lint/performance/noBarrelFile: The package entry must expose Wrangler's named Workflow class.
 export { IntelFlowWorkflow } from "./cloudflare-flow-workflow.js";
@@ -65,31 +66,6 @@ export default {
         const flowRepository = createFlowRepository({ db: env.DB, now });
         const nodeRepository = createNodeRepository({ db: env.DB, now });
         const contentStore = createContentStore(env.CONTENT);
-        const nodes = createNodes({
-            repository: nodeRepository,
-            content: contentStore,
-            // ⚠️ Built from `GATE_URL` alone — no service key is handed to it, and none would help. The
-            // Applications surface is admin-gated on a real principal, so every call carries the bearer
-            // of the person making it, which the tree passes in per operation (#182).
-            applications: createGateApplications({
-                fetch: globalThis.fetch.bind(globalThis),
-                gateUrl: env.GATE_URL,
-            }),
-            // The binding's presence IS the signal (#190) — no separate configuration option exists.
-            agentRuntimeAvailable: () => env.AGENT !== undefined,
-            id: ulid,
-            now,
-            indexing: createIndexQueue(env.INDEXING),
-            semantic,
-            externalFlowCallers: async (who, folderId) => await flowRepository.externalCallers(who, folderId),
-            flowNodeReferences: async (who, folderId) => await flowRepository.nodeReferences(who, folderId),
-            hash: async (content) => {
-                const source = typeof content === "string"
-                    ? new TextEncoder().encode(content)
-                    : Uint8Array.from(content).buffer;
-                return await sha256Hex(crypto, source);
-            },
-        });
         const gate = createGateClient({ url: env.GATE_URL, serviceKey: env.GATE_SERVICE_KEY });
         const oauth = createOpenId({
             fetch: globalThis.fetch.bind(globalThis),
@@ -103,21 +79,22 @@ export default {
             crypto,
             now,
         });
-        const auth = createBrowserAuth({
-            baseUrl: env.INTEL_URL,
-            gateUrl: env.GATE_URL,
-            resource: intelResource,
-            oauth,
-            clients: createOAuthClientStore(env.DB),
-            sessions: createSessionCodec({ secret: env.INTEL_SESSION_SECRET, crypto }),
-            portalUrl,
-            portalTokens,
+        // Built before the tree since D30: saving an agent has to ask the portal, live, whether the
+        // person saving reaches every server they are delegating. The dependency runs one way — the
+        // tool service knows nothing about the tree, and the delegation lookup below reads D1 directly
+        // rather than through the node service.
+        const toolDelegation = createToolDelegation({
+            db: env.DB,
+            content: contentStore,
+            id: ulid,
             now,
         });
         const tools = createTools({
             portalUrl,
             remote: createRemoteTools({ fetch: globalThis.fetch.bind(globalThis) }),
             tokens: portalTokens,
+            delegation: toolDelegation.resolve,
+            audit: toolDelegation.audit,
             refresh: async (token) => {
                 try {
                     const refreshed = await oauth.refresh({
@@ -146,6 +123,65 @@ export default {
                 return await sha256Hex(crypto, JSON.stringify(value));
             },
         });
+        // ⚠️ Built before `nodes` and not after, because creating an agent has to be able to hand the
+        // runtime its key inside the same call (D29). Its `visibleNode` closes over `nodes` and is only
+        // ever called later, which is what keeps the two from being a cycle.
+        const agents = createAgentRuntimeService({
+            ...(env.AGENT ? { runtime: env.AGENT } : {}),
+            ...(env.AGENT_HANDOVER_SECRET ? { handoverSecret: env.AGENT_HANDOVER_SECRET } : {}),
+            // The tree's own visibility lookup, unchanged: whether somebody may reach an agent is the
+            // same question as whether they may see the node, and no second answer is invented here.
+            visibleNode: async (actor, nodeId) => await nodes.visibleNode(actor, nodeId),
+        });
+        const nodes = createNodes({
+            repository: nodeRepository,
+            content: contentStore,
+            // ⚠️ Built from `GATE_URL` alone — no service key is handed to it, and none would help. The
+            // Applications surface is admin-gated on a real principal, so every call carries the bearer
+            // of the person making it, which the tree passes in per operation (#182).
+            applications: createGateApplications({
+                fetch: globalThis.fetch.bind(globalThis),
+                gateUrl: env.GATE_URL,
+            }),
+            // The binding's presence IS the signal (#190) — no separate configuration option exists.
+            agentRuntimeAvailable: () => env.AGENT !== undefined,
+            // Where the Application key goes, and the only place it goes (D29). The same service the
+            // browser paths are proxied through, so there is one door to the runtime and not two.
+            agentKeys: { store: async (input) => await agents.storeKey(input) },
+            // The same door again (#214): a definition that was written is a schedule that has to be
+            // armed, and the runtime only looks when it is told to.
+            agentSchedules: { sync: async (input) => await agents.syncSchedules(input) },
+            id: ulid,
+            now,
+            indexing: createIndexQueue(env.INDEXING),
+            semantic,
+            externalFlowCallers: async (who, folderId) => await flowRepository.externalCallers(who, folderId),
+            flowNodeReferences: async (who, folderId) => await flowRepository.nodeReferences(who, folderId),
+            // ⚠️ `canExecute: true` is not a permission being granted here — the servers list touches
+            // nothing and executes nothing. It exists because `ToolActor` carries the flag for the one
+            // method that needs it, and a `false` would read as if listing were gated on execution.
+            toolServers: async (who) => {
+                const catalog = await tools.servers({ id: who.id, email: who.email, canExecute: true });
+                return catalog.items.map((server) => server.handle);
+            },
+            hash: async (content) => {
+                const source = typeof content === "string"
+                    ? new TextEncoder().encode(content)
+                    : Uint8Array.from(content).buffer;
+                return await sha256Hex(crypto, source);
+            },
+        });
+        const auth = createBrowserAuth({
+            baseUrl: env.INTEL_URL,
+            gateUrl: env.GATE_URL,
+            resource: intelResource,
+            oauth,
+            clients: createOAuthClientStore(env.DB),
+            sessions: createSessionCodec({ secret: env.INTEL_SESSION_SECRET, crypto }),
+            portalUrl,
+            portalTokens,
+            now,
+        });
         const flows = createFlows({
             repository: flowRepository,
             runtime: createFlowRuntime(env.FLOWS),
@@ -186,12 +222,7 @@ export default {
                 },
                 indexing: createIndexQueue(env.INDEXING),
             }),
-            agents: createAgentRuntimeService({
-                ...(env.AGENT ? { runtime: env.AGENT } : {}),
-                // The tree's own visibility lookup, unchanged: whether somebody may reach an agent is the
-                // same question as whether they may see the node, and no second answer is invented here.
-                visibleNode: async (actor, nodeId) => await nodes.visibleNode(actor, nodeId),
-            }),
+            agents,
             auth,
         }).fetch(request);
     },

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

@@ -30,6 +30,15 @@ export interface CloudflareEnv {
     GATE_SERVICE_KEY: string;
     INTEL_URL: string;
     INTEL_SESSION_SECRET: string;
+    /**
+     * The shared secret that proves a key handover reached the agent runtime through this Worker
+     * (D29, #207). The SAME value the agent Worker holds as `AGENT_HANDOVER_SECRET`.
+     *
+     * ⚠️ Optional exactly like `AGENT`: a deployment may run Intel without agents, and a hard
+     * requirement would make the whole installation fail to start over a feature nobody uses. Where
+     * it is absent, creating an agent refuses by name instead of leaving one without a key.
+     */
+    AGENT_HANDOVER_SECRET?: string;
     TOOL_SOURCE_ORIGINS: string;
     MCP_PORTAL_URL?: string;
     ALLOW_INSECURE_OAUTH?: string;

package/dist/adapters/db/db.js

@@ -928,6 +928,17 @@ export function createNodeRepository(deps) {
                     .bind(input.auditId, input.actorId, input.sourceNodeId, JSON.stringify({ targetNodeIds: input.links.map((link) => link.targetNodeId) }), input.occurredAt),
             ]);
         },
+        async recordAgentKeyRotation(input) {
+            // ⚠️ No node row moves, so there is nothing to batch this with — the event IS the write. The
+            // key is not among the columns and must not be added to them: audit is metadata, and a row
+            // that carried the credential would outlive every other copy of it.
+            await deps.db
+                .prepare(`INSERT INTO audit_events (
+          id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+        ) VALUES (?, ?, 'agent.rotate_key', 'node', ?, ?, ?)`)
+                .bind(input.auditId, input.actorId, input.nodeId, JSON.stringify({ applicationId: input.applicationId }), input.occurredAt)
+                .run();
+        },
         async graphVisible(actor, input) {
             const nodeResult = await deps.db
                 .prepare(`${visibleCte}

package/dist/adapters/gate-applications/gate-applications.js

@@ -4,6 +4,8 @@ import { IntelError } from "../../shared/intel-error/intel-error.js";
 // field Gate adds tomorrow must not stop an installation from creating an agent. Only what Intel
 // actually reads is named.
 const CreatedApplication = z.object({ id: z.string().min(1), key: z.string().min(1) });
+// The same tolerance, for the same reason. Only the key is read: the ID is the one Intel asked with.
+const RotatedApplication = z.object({ key: z.string().min(1) });
 const DefaultTimeoutMs = 10_000;
 export function createGateApplications(deps) {
     const base = deps.gateUrl.replace(/\/+$/, "");
@@ -50,6 +52,26 @@ export function createGateApplications(deps) {
             }
             return { id: parsed.data.id, key: parsed.data.key };
         },
+        async rotateKey(input) {
+            // Gate issues the replacement FIRST and only then revokes what was there, so a rotation that
+            // fails leaves the old key working rather than locking the agent out (`applications.ts` in
+            // `anchrd/gate`). Intel relies on that: the handover to the runtime happens after this call,
+            // and until it succeeds the agent keeps running on the key it had.
+            const response = await call(`/${encodeURIComponent(input.applicationId)}/rotate-key`, input.token, {});
+            if (response.status === 404) {
+                throw new IntelError(502, "agent_application_missing", "Gate does not know this agent's application any more");
+            }
+            if (!response.ok)
+                throw refusal(response.status);
+            const parsed = RotatedApplication.safeParse(await response.json().catch(() => null));
+            if (!parsed.success) {
+                // ⚠️ A 2xx Intel cannot read means the OLD key is already revoked in Gate and the new one is
+                // lost. The agent is broken either way, so the caller is told the rotation failed and rotates
+                // again — which is safe, because rotating twice is just another new key.
+                throw new IntelError(502, "agent_application_unavailable", "Gate answered the key rotation in a shape Intel cannot read");
+            }
+            return { key: parsed.data.key };
+        },
         async setEnabled(input) {
             // Both routes are idempotent in Gate, which is what lets a retried archive heal a run that
             // failed between the two writes instead of needing a repair path of its own.

package/dist/adapters/tool-delegation/tool-delegation.d.ts

@@ -0,0 +1,22 @@
+import type { ContentStore } from "../../nodes/nodes.types.js";
+import type { ToolAuditEvent, ToolDelegation } from "../../tools/tools.types.js";
+import type { D1Database } from "../db/db.types.js";
+/**
+ * The two D1 statements the delegated tool path needs (D30): who is acting, and a record that they
+ * did.
+ *
+ * ⚠️ Its own adapter rather than a method on the node repository, and deliberately so. The question
+ * is asked with a **Gate Application id** and no Intel actor at all — there is no ACL to apply,
+ * because the answer is not "may you read this agent" but "which agent are you". Hanging it off the
+ * tree's repository would put an unauthorized read next to authorized ones, which is the shape a
+ * later reader copies by accident.
+ */
+export declare function createToolDelegation(deps: {
+    db: D1Database;
+    content: ContentStore;
+    id(): string;
+    now(): Date;
+}): {
+    resolve(applicationId: string): Promise<ToolDelegation | null>;
+    audit(event: ToolAuditEvent): Promise<void>;
+};

package/dist/adapters/tool-delegation/tool-delegation.js

@@ -0,0 +1,90 @@
+import { AgentDefinition } from "@anchrd/intel-contract";
+import { reportUnexpectedError } from "../../shared/report-unexpected-error/report-unexpected-error.js";
+/**
+ * The two D1 statements the delegated tool path needs (D30): who is acting, and a record that they
+ * did.
+ *
+ * ⚠️ Its own adapter rather than a method on the node repository, and deliberately so. The question
+ * is asked with a **Gate Application id** and no Intel actor at all — there is no ACL to apply,
+ * because the answer is not "may you read this agent" but "which agent are you". Hanging it off the
+ * tree's repository would put an unauthorized read next to authorized ones, which is the shape a
+ * later reader copies by accident.
+ */
+export function createToolDelegation(deps) {
+    return {
+        /**
+         * ⚠️ `null` has exactly ONE meaning here and it is a strong claim: "this caller is not an
+         * agent", after which the tool service treats them as an ordinary person with a portal
+         * connection of their own. Every other outcome — an archived agent, an agent with no definition
+         * version yet, a body R2 lost, a body that will not parse, a definition with no `tools` — is an
+         * agent that delegates NOTHING, and is answered as an empty delegation. That is the difference
+         * between "act as yourself" and "act on nobody's connection", and only one of them is safe to
+         * fall into by accident.
+         *
+         * The joins are therefore LEFT: a row in `agent_applications` is already the whole answer to
+         * "is this an agent", and losing it to a missing version would turn a fresh agent into a user.
+         */
+        async resolve(applicationId) {
+            const row = await deps.db
+                .prepare(`SELECT a.node_id AS node_id, n.archived_at AS archived_at,
+                 v.content_key AS content_key
+          FROM agent_applications a
+          LEFT JOIN nodes n ON n.id = a.node_id
+          LEFT JOIN node_versions v ON v.id = n.current_version_id
+          WHERE a.application_id = ?`)
+                .bind(applicationId)
+                .first();
+            if (!row)
+                return null;
+            const nothing = { agentId: row.node_id, delegatedBy: "", servers: [] };
+            // Archiving an agent switches its Gate Application off, but Gate's own state is not what
+            // Intel is allowed to depend on: an archived agent reaches nothing through Intel from the
+            // moment it is archived, whatever another system still thinks.
+            if (row.archived_at !== null || row.content_key === null)
+                return nothing;
+            const body = await deps.content.get(row.content_key);
+            if (body === null) {
+                reportUnexpectedError(new Error(`agent ${row.node_id} has no readable definition body`));
+                return nothing;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                parsed = null;
+            }
+            const definition = AgentDefinition.safeParse(parsed);
+            if (!definition.success) {
+                reportUnexpectedError(new Error(`agent ${row.node_id} has a definition Intel cannot parse`));
+                return nothing;
+            }
+            const tools = definition.data.tools;
+            if (!tools)
+                return nothing;
+            return {
+                agentId: row.node_id,
+                delegatedBy: tools.delegatedBy,
+                servers: tools.servers,
+            };
+        },
+        async audit(event) {
+            // ⚠️ The agent's node is the resource and the Application is the actor, which is the only
+            // pairing that reads correctly later: `actor_id` is what authenticated, `resource_id` is what
+            // a person searches for. The tool and the server are metadata, and the ARGUMENTS are absent —
+            // an append-only table is the last place a payload should be copied to.
+            await deps.db
+                .prepare(`INSERT INTO audit_events (
+          id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+        ) VALUES (?, ?, 'tool.execute', 'agent', ?, ?, ?)`)
+                .bind(deps.id(), event.applicationId, event.agentId, JSON.stringify({
+                tool: event.tool,
+                server: event.server,
+                // Both principals, which is the whole point of the row: who acted, and whose portal
+                // connection made it possible (D30).
+                delegatedBy: event.delegatedBy,
+            }), deps.now().toISOString())
+                .run();
+        },
+    };
+}

package/dist/agent-runtime/agent-runtime.js

@@ -50,8 +50,82 @@ export function createAgentRuntimeService(deps) {
             ...(input.signal ? { signal: input.signal } : {}),
         }));
     }
+    /**
+     * The two routes Intel dials itself, rather than on a browser's behalf: `/key` and
+     * `/schedules/sync`.
+     *
+     * ⚠️ Neither goes through `forward`, and that is deliberate. `forward` asks `canRun` — the
+     * question for somebody driving an agent — while both of these belong to *maintaining* one, which
+     * Intel has already authorized with `knowledge/create` or `knowledge/write` plus the resource ACL.
+     * What travels instead is the caller's own bearer beside the handover secret: the bearer says who
+     * is behind the call, the secret says it came down Intel's binding at all. The runtime cannot
+     * check Intel's resource ACL — it knows Gate and nothing about the tree — so without the secret a
+     * published runtime hostname would open both routes to anybody holding `knowledge/write` (D29).
+     */
+    async function handover(call) {
+        if (!deps.runtime) {
+            throw new IntelError(503, "agent_runtime_not_configured", "This installation has no agent runtime");
+        }
+        const handoverSecret = deps.handoverSecret?.trim();
+        if (!handoverSecret) {
+            // ⚠️ Refused here rather than dialled and refused there. The runtime would answer 403, and
+            // a 403 reads like "this person may not" — which would send an operator looking at Gate
+            // permissions for a secret that was never set.
+            throw new IntelError(503, call.unconfigured.code, call.unconfigured.detail);
+        }
+        return await deps.runtime.fetch(new Request(`${RuntimeOrigin}/agents/${encodeURIComponent(call.agentId)}${call.path}`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${call.token}`,
+                "content-type": "application/json",
+                // ⚠️ Its own header, never folded into `authorization`: that one already carries the
+                // caller's Gate bearer on this very request, and two credentials in one header is how
+                // one of them ends up read as the other.
+                "x-intel-agent-handover": handoverSecret,
+            },
+            body: call.body,
+        }));
+    }
     return {
         forward,
+        async syncSchedules(input) {
+            const response = await handover({
+                agentId: input.agentId,
+                path: "/schedules/sync",
+                token: input.token,
+                // No schedules travel: the runtime re-reads the definition from Intel itself (#214).
+                body: "{}",
+                unconfigured: {
+                    code: "agent_schedule_sync_not_configured",
+                    detail: "This installation has no shared secret for reaching the agent runtime, so schedules cannot be armed",
+                },
+            });
+            if (response.ok)
+                return;
+            // ⚠️ Loud, and named after the state it leaves behind rather than after the call that failed.
+            // What the caller has to act on is not "the runtime answered 502" but "this agent's schedules
+            // are not armed", and the sentence says the repair: write the definition again.
+            throw new IntelError(502, "agent_schedules_not_armed", `The definition was saved, but the agent runtime did not arm its schedules (${response.status}). Saving the definition again arms them.`);
+        },
+        async storeKey(input) {
+            const response = await handover({
+                agentId: input.agentId,
+                path: "/key",
+                token: input.token,
+                body: JSON.stringify({ key: input.key }),
+                unconfigured: {
+                    code: "agent_key_handover_not_configured",
+                    detail: "This installation has no shared secret for handing an agent its application key",
+                },
+            });
+            if (response.ok)
+                return;
+            // ⚠️ The runtime's answer is read for its status and thrown away. Its body cannot be quoted
+            // here the way `request` quotes it: the call that produced it carried a credential, and an
+            // echoed body is the shortest path from a refusal to a key in a log. What the caller is told
+            // is that the agent has no usable key — which is the only thing they can act on anyway.
+            throw new IntelError(502, "agent_key_not_stored", `The agent runtime did not take this agent's application key (${response.status}), so the agent cannot run yet`);
+        },
         // A plain fact, not a probe: the binding is either configured or it is not, and nothing is
         // dialled to answer. Unlike `reach` this stands before any per-agent check — it names no agent.
         available: () => deps.runtime !== undefined,

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

@@ -21,6 +21,19 @@ export interface AgentActor extends Actor {
     canRun: boolean;
 }
 export interface AgentRuntimeDeps {
+    /**
+     * The shared secret that proves a key handover came down this binding (D29, #207).
+     *
+     * ⚠️ The SAME value the agent Worker holds as `AGENT_HANDOVER_SECRET`, and it travels on exactly
+     * one route. It is not a substitute for the caller's bearer, which travels beside it: the bearer
+     * says who is asking, this says the request came through Intel at all. The runtime cannot check
+     * Intel's resource ACLs — it knows Gate and nothing about the tree — so without this a published
+     * runtime hostname would let anybody with `knowledge/write` write the key of any agent.
+     *
+     * Absent, `storeKey` refuses by name rather than dialling the binding and being refused there:
+     * the deployment is misconfigured, and saying so beats a 403 that reads like a permission problem.
+     */
+    handoverSecret?: string;
     /**
      * Absent where a deployment runs no agent Worker. Every call then refuses by name instead of
      * failing somewhere unreadable — a customer may deploy Intel without agents.
@@ -44,9 +57,61 @@ export interface ForwardInput {
     body?: string;
     signal?: AbortSignal;
 }
+/**
+ * One agent's Application key, on its way from Gate into the agent's Durable Object (D29, #207).
+ *
+ * ⚠️ It exists as a parameter and never as a field of anything stored. The value is in one local
+ * variable from the moment Gate answers until this call returns, exactly as it was before D29 — what
+ * changed is where it goes: into the runtime instead of into a response the browser reads.
+ */
+export interface StoreKeyInput {
+    /** The caller's own Gate bearer, passed on unchanged. Never a service key (D19). */
+    token: string;
+    agentId: string;
+    key: string;
+}
+/**
+ * Which agent's alarm has to be brought in line with the definition Intel just wrote (#214).
+ *
+ * ⚠️ It carries no schedules. The runtime re-reads the definition from Intel itself, with the
+ * agent's own token, so this is a "look again" and never a second copy of the document — a schedule
+ * pushed down this call would be one the agent could act on without it ever having been written.
+ */
+export interface SyncSchedulesInput {
+    /** The caller's own Gate bearer, passed on unchanged. Never a service key (D19). */
+    token: string;
+    agentId: string;
+}
 export interface AgentRuntimeService {
     /** The browser's way through: the runtime's answer, body and headers untouched. */
     forward(input: ForwardInput): Promise<Response>;
+    /**
+     * Hands an agent the key of the Gate Application it runs as.
+     *
+     * ⚠️ The one door here that does NOT ask `canRun`, and that is deliberate. Its two callers —
+     * creating an agent and rotating its key — have already decided who may act: `knowledge/create`
+     * with a writable parent, or `knowledge/write` with the resource ACL of the agent node. Requiring
+     * `agents/run` on top would mean a person who may create agents but never run one creates keyless
+     * agents, which is #200 arrived at from the other side. The runtime makes the same distinction at
+     * its own door.
+     *
+     * ⚠️ It fails loudly. A handover that quietly did not happen is an agent that exists, looks
+     * right, and dies at its first run — the whole failure this ticket removes.
+     */
+    storeKey(input: StoreKeyInput): Promise<void>;
+    /**
+     * Arms the agent's alarm for whatever the definition Intel just wrote schedules (#214).
+     *
+     * ⚠️ Like `storeKey` and unlike everything else here, it does NOT ask `canRun`. Its two callers —
+     * creating an agent and saving its definition — have already decided who may act: `knowledge/
+     * create` with a writable parent, or `knowledge/write` with the resource ACL of the agent node.
+     * Requiring `agents/run` on top would mean an editor who may not drive agents saves a schedule
+     * that is never armed, which is the failure this exists to remove.
+     *
+     * ⚠️ It fails loudly, for the same reason `storeKey` does. A sync that quietly did not happen is
+     * an agent whose profile shows a schedule that will never fire.
+     */
+    syncSchedules(input: SyncSchedulesInput): Promise<void>;
     /** The same door for a caller that wants the answer, not the response — Intel MCP uses this. */
     request(input: ForwardInput): Promise<unknown>;
     /**

package/dist/bundle/bundle.js

@@ -915,6 +915,19 @@ export function createBundle(deps) {
                         }
                         const remapped = {
                             ...definition,
+                            /**
+                             * ⚠️ A delegation NEVER travels in a file (#208, D30). `tools.delegatedBy` names
+                             * whose portal connection an agent acts on, and the only thing that may write it is
+                             * a person saving the agent in a session Intel authorized — the save path proves
+                             * they reach every named server first. A bundle is a document somebody hands over;
+                             * carrying the field through would let a crafted file name a local user and hand an
+                             * imported agent that person's connection, with no act of theirs anywhere.
+                             *
+                             * The consequence is deliberate and mild: an imported agent arrives with no tools,
+                             * and whoever wants it to have some gives them in the profile — which is the same
+                             * act D30 made the only way in.
+                             */
+                            tools: null,
                             references: definition.references.map((reference) => idMap.has(reference.nodeId)
                                 ? { ...reference, nodeId: idMap.get(reference.nodeId) }
                                 : reference),