@anchrd/intel-api 0.7.0 → 0.10.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/json-schema/json-schema.js

@@ -1,31 +1,77 @@
-import Ajv, {} from "ajv";
-// Tool schemas come from remote catalogs and are therefore untrusted: allErrors lets a crafted
-// schema amplify validation work, and Ajv keeps every compiled schema for the life of the isolate.
-const MaxCompiledSchemas = 200;
+import { Validator } from "@cfworker/json-schema";
+import { reportUnexpectedError } from "../../shared/report-unexpected-error/report-unexpected-error.js";
+// ⚠️ This validator must not generate code, and Ajv must never come back. Ajv turns a schema into
+// JavaScript with `new Function`, and workerd answers that with `EvalError: Code generation from
+// strings disallowed for this context` — so `compile` threw for EVERY schema in production, the
+// catch called it a broken schema, and each tool call died with 400 "The cached tool schema is
+// invalid" while nothing was wrong with any schema (#229). Ajv is usable only with schemas
+// precompiled at build time; these arrive from a remote catalog and are unknown until the call.
+// `@cfworker/json-schema` interprets the schema instead, which is what it was written for.
+//
+// ⚠️ The `workerd` test pool does not prove this on its own: it replaces `globalThis.Function` with
+// a proxy onto an unsafe-eval binding, so Ajv compiled happily in every test while failing in every
+// deployment. `json-schema.int.ts` therefore takes that patch away for the length of the test — it
+// is the only thing that turns red when a code-generating validator returns.
+// Tool schemas come from remote catalogs and are therefore untrusted: `ShortCircuit` stops at the
+// first error so a crafted schema cannot amplify the work of one call, and the prepared validators
+// are bounded because each one holds its dereferenced schema for the life of the isolate.
+const MaxPreparedSchemas = 200;
+const ShortCircuit = true;
+const MaxDetailLength = 2_000;
+// A tool schema that names its draft gets that draft: draft-07 ignores keywords sitting beside a
+// `$ref` and the later drafts apply them, so guessing here would validate a foreign catalog against
+// rules its author never wrote. Unnamed means 2020-12, the draft the MCP generators emit when they
+// stay silent.
+const DefaultDraft = "2020-12";
+const DraftsByMetaSchema = [
+    ["draft-04", "4"],
+    ["draft-07", "7"],
+    ["2019-09", "2019-09"],
+    ["2020-12", "2020-12"],
+];
+function draftOf(schema) {
+    const declared = schema.$schema;
+    if (typeof declared !== "string")
+        return DefaultDraft;
+    return DraftsByMetaSchema.find(([marker]) => declared.includes(marker))?.[1] ?? DefaultDraft;
+}
 export function createJsonSchemaValidator() {
-    const ajv = new Ajv({ allErrors: false, strict: false });
-    const compiled = new Map();
+    const prepared = new Map();
     return (schema, value) => {
-        try {
-            const key = JSON.stringify(schema);
-            let validate = compiled.get(key);
-            if (!validate) {
-                if (compiled.size >= MaxCompiledSchemas) {
-                    compiled.clear();
-                    ajv.removeSchema();
-                }
-                validate = ajv.compile(schema);
-                compiled.set(key, validate);
+        const key = JSON.stringify(schema);
+        let validator = prepared.get(key);
+        if (!validator) {
+            try {
+                validator = new Validator(schema, draftOf(schema), ShortCircuit);
+            }
+            catch (error) {
+                // A schema this validator cannot even read is still refused by name — but the caller hears
+                // that it was the schema, not their arguments, and the reason itself goes to the log. The
+                // old wording claimed a broken schema for every failure, which is what hid #229 for weeks.
+                reportUnexpectedError(error);
+                return { valid: false, detail: "The tool schema could not be read; the reason was logged" };
             }
-            if (validate(value))
+            if (prepared.size >= MaxPreparedSchemas)
+                prepared.clear();
+            prepared.set(key, validator);
+        }
+        try {
+            const result = validator.validate(value);
+            if (result.valid)
                 return { valid: true };
-            return {
-                valid: false,
-                detail: ajv.errorsText(validate.errors, { separator: "; " }).slice(0, 2_000),
-            };
+            return { valid: false, detail: describe(result) };
         }
-        catch {
-            return { valid: false, detail: "The cached tool schema is invalid" };
+        catch (error) {
+            // An unresolvable `$ref` only shows up while walking the instance, so this is the same
+            // unreadable schema arriving one step later — and never a statement about the arguments.
+            reportUnexpectedError(error);
+            return { valid: false, detail: "The tool schema could not be read; the reason was logged" };
         }
     };
 }
+function describe(result) {
+    return result.errors
+        .map((unit) => `${unit.instanceLocation}: ${unit.error}`)
+        .join("; ")
+        .slice(0, MaxDetailLength);
+}

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,