@anchrd/intel-api 0.6.6 → 0.7.0

package/dist/http/http.js

@@ -1,4 +1,4 @@
-import { AppendKnowledgeTableRowsInput, ArchiveFlowInput, ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeNodeInput, DefineKnowledgeTableInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, KnowledgeGraphInput, ListFlowRunsInput, ListFlowsInput, ListKnowledgeNodesInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, ResolveKnowledgeLinksInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
+import { AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListNodesInput, NodeGraphInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, ResolveNodeLinksInput, RevokeGrantInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateFlowInput, UpdateNodeInput, UpdateTableRowsInput, } from "@anchrd/intel-contract";
 import { Hono } from "hono";
 import { z } from "zod";
 import { authorizeBearer, bearer, permits, } from "../shared/gate-authorization/gate-authorization.js";
@@ -30,6 +30,32 @@ function asActor(authorization) {
         isAdmin: authorization.can("intel", "admin"),
     };
 }
+// The exporting caller: the node actor plus whether flows may ride along in the bundle at all.
+// Gate's `flows/read` is asked here once, so the bundle service never re-derives a capability.
+function asBundleActor(authorization) {
+    return {
+        id: authorization.identity.id,
+        email: authorization.identity.email,
+        isAdmin: authorization.can("intel", "admin"),
+        canReadFlows: permits(authorization, "flows", "read"),
+        canCreateFlows: permits(authorization, "flows", "create"),
+    };
+}
+// The idempotency key of an import travels as a header: the body is the zip itself, so there is no
+// JSON envelope to put it in, and a query string would drag it into logs (#137).
+const ImportIdempotencyKey = z.string().min(8).max(200);
+// A bundle export streamed as a download. `content-length` is deliberately absent: the zip is
+// written while it leaves, which is the whole point of streaming it (#136).
+function zipResponse(bundle) {
+    return new Response(bundle.stream, {
+        headers: {
+            "cache-control": "private, no-store",
+            "content-disposition": contentDisposition(bundle.filename),
+            "content-type": "application/zip",
+            "x-content-type-options": "nosniff",
+        },
+    });
+}
 function asToolActor(authorization) {
     return {
         id: authorization.identity.id,
@@ -52,11 +78,24 @@ function asFlowActor(authorization) {
         isAdmin: authorization.can("intel", "admin"),
     };
 }
+// The same `agents/run` the agent Worker asks for, resolved once at Intel's door. `intel/admin`
+// opens it for the same reason it opens every other one — `permits` is where that lives.
+function asAgentActor(authorization) {
+    return {
+        id: authorization.identity.id,
+        email: authorization.identity.email,
+        isAdmin: authorization.can("intel", "admin"),
+        canRun: permits(authorization, "agents", "run"),
+    };
+}
 export function createHttp(deps) {
     const app = new Hono();
     async function authenticated(headers) {
         const token = bearer(headers) ?? (await deps.auth?.resolve(headers))?.bearer ?? null;
-        return token ? await authorizeBearer(deps.gate, token, deps.resource) : null;
+        if (!token)
+            return null;
+        const authorization = await authorizeBearer(deps.gate, token, deps.resource);
+        return authorization ? { authorization, token } : null;
     }
     app.onError((error, context) => {
         if (error instanceof IntelError) {
@@ -71,12 +110,13 @@ export function createHttp(deps) {
         return context.json(problem(500, "internal_error", "Internal server error"), 500);
     });
     app.use("*", async (context, next) => {
-        const authorization = await authenticated(context.req.raw.headers);
-        if (!authorization) {
+        const session = await authenticated(context.req.raw.headers);
+        if (!session) {
             context.header("WWW-Authenticate", `Bearer resource_metadata="${deps.resourceMetadataUrl}"`);
             return context.json(problem(401, "authentication_required", "Authentication required"), 401);
         }
-        context.set("authorization", authorization);
+        context.set("authorization", session.authorization);
+        context.set("token", session.token);
         await next();
     });
     function requireCapability(context, handle, fn) {
@@ -96,42 +136,195 @@ export function createHttp(deps) {
             name: identity.name ?? null,
         });
     });
-    app.get("/knowledge", async (context) => {
+    // What this deployment is equipped to do (#190) — facts about the installation, not about the
+    // caller, which is why it needs no capability beyond being signed in. `/session` stays identity
+    // only on purpose; this is the separate answer the UI asks for instead of reading a 503 as one.
+    // It sits behind the auth middleware like everything else, so an anonymous probe still learns
+    // nothing about whether a runtime exists.
+    app.get("/capabilities", (context) => {
+        return context.json({ agentRuntime: deps.agents.available() });
+    });
+    /**
+     * The agent runtime, reached through Intel.
+     *
+     * ⚠️ This list IS the door. The runtime serves more than what stands here — `/mcp` is the agent's
+     * own MCP surface, which the portal dials with its own credential (ADR-0005 §7), and
+     * `/mail/inbound` is authorized by a webhook signature. Neither is a browser path, and neither
+     * becomes one by being reachable: anything not named below is a 404 from Hono's router, so there
+     * is no allow-list beside the routes that could go quietly out of step with them.
+     *
+     * ⚠️ `agents/run` — not `knowledge/read`. Reading an agent's page is a knowledge read; driving the
+     * agent is the capability the runtime itself insists on, and Intel refuses on the same terms
+     * BEFORE the binding is touched, so a denial never reaches the runtime at all.
+     */
+    const runtimeRoutes = [
+        { method: "GET", pattern: "/state", path: () => "/state" },
+        { method: "GET", pattern: "/runs", path: () => "/runs" },
+        {
+            method: "GET",
+            pattern: "/runs/:runId",
+            path: (context) => `/runs/${encodeURIComponent(context.req.param("runId") ?? "")}`,
+        },
+        { method: "GET", pattern: "/log", path: () => "/log" },
+        { method: "POST", pattern: "/chat", path: () => "/chat" },
+        { method: "POST", pattern: "/pause", path: () => "/pause" },
+        { method: "POST", pattern: "/resume", path: () => "/resume" },
+        { method: "POST", pattern: "/run", path: () => "/run" },
+    ];
+    for (const route of runtimeRoutes) {
+        app.on(route.method, `/agents/:agentId${route.pattern}`, async (context) => {
+            const authorization = context.get("authorization");
+            // The runtime's answer is returned untouched, headers included: the chat is a stream, and a
+            // body read here to inspect it would be a stream nobody could read afterwards.
+            return await deps.agents.forward({
+                actor: asAgentActor(authorization),
+                token: context.get("token"),
+                agentId: context.req.param("agentId"),
+                method: route.method,
+                path: route.path(context),
+                ...(route.method === "POST" ? { body: await context.req.text() } : {}),
+                signal: context.req.raw.signal,
+            });
+        });
+    }
+    app.get("/nodes", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
         const url = new URL(context.req.url);
         const unknownQuery = [];
         url.searchParams.forEach((_value, key) => {
-            if (key !== "parentId" && key !== "includeArchived")
+            if (key !== "parentId" && key !== "includeArchived" && key !== "archivedOnly") {
                 unknownQuery.push(key);
+            }
         });
         if (unknownQuery.length) {
             throw new IntelError(400, "invalid_request", `Unknown query parameters: ${unknownQuery.join(", ")}`);
         }
-        const input = ListKnowledgeNodesInput.parse({
+        const input = ListNodesInput.parse({
             parentId: url.searchParams.get("parentId"),
             includeArchived: url.searchParams.get("includeArchived") === "true",
+            ...(url.searchParams.get("archivedOnly") === "true" ? { archivedOnly: true } : {}),
         });
-        return context.json(await deps.knowledge.list(asActor(auth), input));
+        return context.json(await deps.nodes.list(asActor(auth), input));
     });
-    app.get("/knowledge/graph", async (context) => {
+    app.get("/nodes/graph", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
         const url = new URL(context.req.url);
-        const input = KnowledgeGraphInput.parse({
+        const input = NodeGraphInput.parse({
             limit: url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : undefined,
         });
-        return context.json(await deps.knowledge.graph(asActor(auth), input));
+        return context.json(await deps.nodes.graph(asActor(auth), input));
+    });
+    // ⚠️ Before `/nodes/:nodeId`, or the router would read "agents" as a node ID. Same order and same
+    // reason as `/nodes/graph` above.
+    app.get("/nodes/agents", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        const url = new URL(context.req.url);
+        requireKnownQuery(url, ["parentId", "includeArchived"]);
+        const parentId = url.searchParams.get("parentId");
+        // ⚠️ The key is only set when the caller sent it. Omitted means the whole tree and `null` means
+        // the root level, so defaulting a missing parameter to `null` here would silently answer a
+        // different question than the one asked.
+        const input = ListAgentsInput.parse({
+            ...(url.searchParams.has("parentId") ? { parentId: parentId === "" ? null : parentId } : {}),
+            includeArchived: url.searchParams.get("includeArchived") === "true",
+        });
+        return context.json(await deps.nodes.listAgents(asActor(auth), input));
+    });
+    /**
+     * ⚠️ The one response in Intel's HTTP surface that carries a credential (#182, D27).
+     *
+     * `applicationKey` is the Gate Application key of the new agent, in plain text, exactly once —
+     * Gate issues it once and keeps only a hash, and Intel writes it nowhere. It belongs in the agent
+     * runtime's `AGENT_APPLICATION_KEYS` secret; the answer says so rather than assuming the caller
+     * knows. The caller's own bearer is what creates the principal, so this needs `applications:write`
+     * in Gate on top of `knowledge:create` in Intel.
+     */
+    app.post("/nodes/agents", async (context) => {
+        const auth = requireCapability(context, "knowledge", "create");
+        const input = CreateAgentInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.nodes.createAgent(asActor(auth), input, { token: context.get("token") }), 201);
+    });
+    // ⚠️ Before `/nodes/:nodeId`, or the router would read "export" as a node ID. The root has no
+    // node to address, so the whole installation — as this caller may read it — exports here (#136).
+    app.get("/nodes/export", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        return zipResponse(await deps.bundle.exportSubtree(asBundleActor(auth), null));
+    });
+    // The reverse door (#137): a zip bundle — or a naked zipped folder — lands as a new subtree.
+    // The body IS the zip, streamed to the service rather than read whole here; `knowledge/create`
+    // like every other way of making nodes, and the resource-level write check is the service's.
+    async function importBundle(context, targetNodeId) {
+        const auth = requireCapability(context, "knowledge", "create");
+        const idempotencyKey = ImportIdempotencyKey.parse(context.req.header("idempotency-key"));
+        const body = context.req.raw.body;
+        if (body === null) {
+            throw new IntelError(400, "invalid_request", "A zip request body is required");
+        }
+        const result = await deps.bundle.importBundle(asBundleActor(auth), {
+            targetNodeId,
+            zip: body,
+            idempotencyKey,
+        });
+        // A replay answers 200: nothing was created by THIS request, and the summary is the earlier
+        // import's. 201 stays the word for rows that exist because of this call.
+        return context.json(result, result.replayed ? 200 : 201);
+    }
+    // ⚠️ Before `/nodes/:nodeId`, or the router would read "import" as a node ID.
+    app.post("/nodes/import", async (context) => await importBundle(context, null));
+    app.get("/nodes/:nodeId", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        return context.json(await deps.nodes.get(asActor(auth), context.req.param("nodeId")));
+    });
+    app.post("/nodes/:nodeId/import", async (context) => {
+        const input = GetNodeInput.parse({ nodeId: context.req.param("nodeId") });
+        return await importBundle(context, input.nodeId);
+    });
+    // One subtree — a folder with everything beneath it, or a single node — as a zip bundle (#136).
+    app.get("/nodes/:nodeId/export", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        const input = GetNodeInput.parse({ nodeId: context.req.param("nodeId") });
+        return zipResponse(await deps.bundle.exportSubtree(asBundleActor(auth), input.nodeId));
+    });
+    app.get("/nodes/:nodeId/agent", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        return context.json(await deps.nodes.getAgent(asActor(auth), { nodeId: context.req.param("nodeId") }));
+    });
+    app.post("/nodes/:nodeId/agent", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = SaveAgentDefinitionInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.saveAgentDefinition(asActor(auth), input), 201);
+    });
+    app.get("/nodes/:nodeId/versions", async (context) => {
+        const auth = requireCapability(context, "knowledge", "read");
+        return context.json(await deps.nodes.listVersions(asActor(auth), context.req.param("nodeId")));
     });
-    app.get("/knowledge/:nodeId", async (context) => {
+    // The content behind one row of the list above (#147): what a version-pinned citation points at.
+    // Read capability like every other node read; the resource ACL and the node/version pairing are
+    // the service's to refuse.
+    app.get("/nodes/:nodeId/versions/:versionId/content", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
-        return context.json(await deps.knowledge.get(asActor(auth), context.req.param("nodeId")));
+        const input = GetNodeVersionInput.parse({
+            nodeId: context.req.param("nodeId"),
+            versionId: context.req.param("versionId"),
+        });
+        return context.json(await deps.nodes.getVersion(asActor(auth), input.nodeId, input.versionId));
     });
-    app.get("/knowledge/:nodeId/versions", async (context) => {
+    // The metadata half of an attachment (#148): what `node_attachment_get` answers an agent, for
+    // HTTP callers who so far could only stream the bytes. Without the `resourceUri` — an MCP
+    // resource address says nothing to an HTTP client, whose address for the bytes is the sibling
+    // route below.
+    app.get("/nodes/:nodeId/attachment/meta", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
-        return context.json(await deps.knowledge.listVersions(asActor(auth), context.req.param("nodeId")));
+        const input = GetNodeInput.parse({ nodeId: context.req.param("nodeId") });
+        const { node, version } = await deps.nodes.getAttachment(asActor(auth), input.nodeId);
+        return context.json({ node, version });
     });
-    app.get("/knowledge/:nodeId/attachment", async (context) => {
+    app.get("/nodes/:nodeId/attachment", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
-        const { attachment, body } = await deps.knowledge.readAttachment(asActor(auth), context.req.param("nodeId"));
+        const { attachment, body } = await deps.nodes.readAttachment(asActor(auth), context.req.param("nodeId"));
         return new Response(body, {
             headers: {
                 "cache-control": "private, no-store",
@@ -141,116 +334,146 @@ export function createHttp(deps) {
             },
         });
     });
-    app.get("/knowledge/:nodeId/table", async (context) => {
+    app.get("/nodes/:nodeId/table", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
-        return context.json(await deps.knowledge.getTable(asActor(auth), context.req.param("nodeId")));
+        return context.json(await deps.nodes.getTable(asActor(auth), context.req.param("nodeId")));
     });
     // Defining the header and appending rows are two routes because they are two decisions: the
     // header is written once and is the contract, an append is the everyday write (#40).
-    app.post("/knowledge/:nodeId/table", async (context) => {
+    app.post("/nodes/:nodeId/table", async (context) => {
         const auth = requireCapability(context, "knowledge", "write");
-        const input = DefineKnowledgeTableInput.parse(await context.req.json().catch(() => null));
+        const input = DefineTableInput.parse(await context.req.json().catch(() => null));
         if (input.nodeId !== context.req.param("nodeId")) {
             throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
         }
-        return context.json(await deps.knowledge.defineTable(asActor(auth), input), 201);
+        return context.json(await deps.nodes.defineTable(asActor(auth), input), 201);
     });
-    app.post("/knowledge/:nodeId/table/rows", async (context) => {
+    app.post("/nodes/:nodeId/table/rows", async (context) => {
         const auth = requireCapability(context, "knowledge", "write");
-        const input = AppendKnowledgeTableRowsInput.parse(await context.req.json().catch(() => null));
+        const input = AppendTableRowsInput.parse(await context.req.json().catch(() => null));
         if (input.nodeId !== context.req.param("nodeId")) {
             throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
         }
-        return context.json(await deps.knowledge.appendTableRows(asActor(auth), input), 201);
+        return context.json(await deps.nodes.appendTableRows(asActor(auth), input), 201);
     });
-    app.get("/knowledge/:nodeId/links", async (context) => {
+    // The three mutations beside the append (#135). Action-style POSTs like the archive and revoke
+    // routes, because a row has no address of its own to PUT to: positions live in the body, next to
+    // the `baseVersionId` that says which state they mean. Each writes one snapshot version, so the
+    // 201 is the same statement the append's 201 makes.
+    app.post("/nodes/:nodeId/table/rows/update", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = UpdateTableRowsInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.updateTableRows(asActor(auth), input), 201);
+    });
+    app.post("/nodes/:nodeId/table/rows/delete", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = DeleteTableRowsInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.deleteTableRows(asActor(auth), input), 201);
+    });
+    app.post("/nodes/:nodeId/table/redefine", async (context) => {
+        const auth = requireCapability(context, "knowledge", "write");
+        const input = RedefineTableInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
+        return context.json(await deps.nodes.redefineTable(asActor(auth), input), 201);
+    });
+    app.get("/nodes/:nodeId/links", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
-        return context.json(await deps.knowledge.listLinks(asActor(auth), context.req.param("nodeId")));
+        return context.json(await deps.nodes.listLinks(asActor(auth), context.req.param("nodeId")));
     });
     // A document link's name, for whoever is reading the text (#41). A POST because the list of IDs
     // is the request body — putting them in a query string would put the tree's identifiers into
-    // logs and referrers. `knowledge/read` and nothing more: it answers with what this reader may
+    // logs and referrers. The `knowledge/read` capability and nothing more: it answers with what this reader may
     // already see, and stays silent about the rest rather than saying that there is a rest.
     //
     // There is no route to create or delete a link any more. A relationship is written where it is
-    // meant, in the text, and `POST /knowledge/:nodeId/versions` is what records it.
-    app.post("/knowledge/links/resolve", async (context) => {
+    // meant, in the text, and `POST /nodes/:nodeId/versions` is what records it.
+    app.post("/nodes/links/resolve", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
-        const input = ResolveKnowledgeLinksInput.parse(await context.req.json().catch(() => null));
-        return context.json(await deps.knowledge.resolveLinks(asActor(auth), input));
+        const input = ResolveNodeLinksInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.nodes.resolveLinks(asActor(auth), input));
     });
-    app.post("/knowledge/search", async (context) => {
+    app.post("/nodes/search", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
-        const input = SearchKnowledgeInput.parse(await context.req.json().catch(() => null));
-        return context.json(await deps.knowledge.search(asActor(auth), input));
+        const input = SearchInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.nodes.search(asActor(auth), input));
     });
     app.post("/search/reindex", async (context) => {
         const auth = requireCapability(context, "intel", "admin");
         z.strictObject({}).parse(await context.req.json().catch(() => null));
-        return context.json(await deps.knowledge.reindex(asActor(auth)), 202);
+        return context.json(await deps.nodes.reindex(asActor(auth)), 202);
     });
-    app.post("/knowledge", async (context) => {
+    app.post("/nodes", async (context) => {
         const auth = requireCapability(context, "knowledge", "create");
-        const input = CreateKnowledgeNodeInput.parse(await context.req.json().catch(() => null));
-        return context.json(await deps.knowledge.create(asActor(auth), input), 201);
+        const input = CreateNodeInput.parse(await context.req.json().catch(() => null));
+        return context.json(await deps.nodes.create(asActor(auth), input), 201);
     });
-    app.post("/knowledge/:nodeId/versions", async (context) => {
+    app.post("/nodes/:nodeId/versions", async (context) => {
         const auth = requireCapability(context, "knowledge", "write");
-        const input = SaveKnowledgeVersionInput.parse(await context.req.json().catch(() => null));
+        const input = SaveNodeVersionInput.parse(await context.req.json().catch(() => null));
         if (input.nodeId !== context.req.param("nodeId")) {
             throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
         }
-        return context.json(await deps.knowledge.save(asActor(auth), input), 201);
+        return context.json(await deps.nodes.save(asActor(auth), input), 201);
     });
-    app.post("/knowledge/:nodeId/attachment", async (context) => {
+    app.post("/nodes/:nodeId/attachment", async (context) => {
         const auth = requireCapability(context, "knowledge", "write");
-        const input = SaveKnowledgeAttachmentInput.parse(await context.req.json().catch(() => null));
+        const input = SaveAttachmentInput.parse(await context.req.json().catch(() => null));
         if (input.nodeId !== context.req.param("nodeId")) {
             throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
         }
-        return context.json(await deps.knowledge.saveAttachment(asActor(auth), input), 201);
+        return context.json(await deps.nodes.saveAttachment(asActor(auth), input), 201);
     });
-    app.patch("/knowledge/:nodeId", async (context) => {
+    app.patch("/nodes/:nodeId", async (context) => {
         const auth = requireCapability(context, "knowledge", "write");
-        const input = UpdateKnowledgeNodeInput.parse(await context.req.json().catch(() => null));
+        const input = UpdateNodeInput.parse(await context.req.json().catch(() => null));
         if (input.nodeId !== context.req.param("nodeId")) {
             throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
         }
-        return context.json(await deps.knowledge.update(asActor(auth), input));
+        return context.json(await deps.nodes.update(asActor(auth), input));
     });
-    app.post("/knowledge/:nodeId/archive", async (context) => {
+    app.post("/nodes/:nodeId/archive", async (context) => {
         const auth = requireCapability(context, "knowledge", "write");
-        const input = ArchiveKnowledgeNodeInput.parse(await context.req.json().catch(() => null));
+        const input = ArchiveNodeInput.parse(await context.req.json().catch(() => null));
         if (input.nodeId !== context.req.param("nodeId")) {
             throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
         }
-        return context.json(await deps.knowledge.archive(asActor(auth), input));
+        // The caller's own bearer, for the one thing archiving may have to do in Gate: switch off the
+        // Application behind an agent (#182). Every other kind never reaches it.
+        return context.json(await deps.nodes.archive(asActor(auth), input, { token: context.get("token") }));
     });
-    app.get("/knowledge/:nodeId/grants", async (context) => {
+    app.get("/nodes/:nodeId/grants", async (context) => {
         const auth = requireCapability(context, "knowledge", "share");
-        return context.json(await deps.knowledge.listGrants(asActor(auth), context.req.param("nodeId")));
+        return context.json(await deps.nodes.listGrants(asActor(auth), context.req.param("nodeId")));
     });
-    app.post("/knowledge/:nodeId/grants", async (context) => {
+    app.post("/nodes/:nodeId/grants", async (context) => {
         const auth = requireCapability(context, "knowledge", "share");
-        const input = ShareKnowledgeInput.parse(await context.req.json().catch(() => null));
+        const input = ShareInput.parse(await context.req.json().catch(() => null));
         if (input.resourceId !== context.req.param("nodeId")) {
             throw new IntelError(400, "node_id_mismatch", "Path and body resource IDs differ");
         }
-        return context.json(await deps.knowledge.share(asActor(auth), input), 201);
+        return context.json(await deps.nodes.share(asActor(auth), input), 201);
     });
-    app.post("/knowledge/:nodeId/grants/:grantId/revoke", async (context) => {
+    app.post("/nodes/:nodeId/grants/:grantId/revoke", async (context) => {
         const auth = requireCapability(context, "knowledge", "share");
-        const input = RevokeKnowledgeGrantInput.parse(await context.req.json().catch(() => null));
+        const input = RevokeGrantInput.parse(await context.req.json().catch(() => null));
         if (input.resourceId !== context.req.param("nodeId") ||
             input.grantId !== context.req.param("grantId")) {
             throw new IntelError(400, "grant_id_mismatch", "Path and body grant IDs differ");
         }
-        return context.json(await deps.knowledge.revokeGrant(asActor(auth), input));
+        return context.json(await deps.nodes.revokeGrant(asActor(auth), input));
     });
     app.get("/flows", async (context) => {
         const auth = requireCapability(context, "flows", "read");
         const url = new URL(context.req.url);
-        requireKnownQuery(url, ["parentId", "includeArchived"]);
+        requireKnownQuery(url, ["parentId", "includeArchived", "archivedOnly"]);
         // Absent means "every flow I may see"; present but empty means the root of the shared tree.
         // Without that distinction a tree level and a full list would be the same request.
         const parentId = url.searchParams.get("parentId");
@@ -259,11 +482,12 @@ export function createHttp(deps) {
         const input = ListFlowsInput.parse({
             ...(url.searchParams.has("parentId") ? { parentId: parentId === "" ? null : parentId } : {}),
             ...(url.searchParams.get("includeArchived") === "true" ? { includeArchived: true } : {}),
+            ...(url.searchParams.get("archivedOnly") === "true" ? { archivedOnly: true } : {}),
         });
         return context.json(await deps.flows.list(asFlowActor(auth), input));
     });
     // ⚠️ Before `/flows/:flowId`, or the router would read "graph" as a flow ID. Same order and same
-    // reason as `/knowledge/graph`.
+    // reason as `/nodes/graph`.
     app.get("/flows/graph", async (context) => {
         const auth = requireCapability(context, "flows", "read");
         const url = new URL(context.req.url);
@@ -284,6 +508,13 @@ export function createHttp(deps) {
         const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
         return context.json(await deps.flows.get(asFlowActor(auth), input.flowId));
     });
+    // A single flow as the same bundle shape a node export makes: one entry plus the manifest
+    // (#136). `flows/read` like every other read of the graph.
+    app.get("/flows/:flowId/export", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return zipResponse(await deps.bundle.exportFlow(asBundleActor(auth), input.flowId));
+    });
     // What this flow calls, read out of its graph. The tree lists where a flow is filed; this lists
     // what it runs, and a shared subflow answers both questions at once (ADR-0004 §3).
     app.get("/flows/:flowId/calls", async (context) => {
@@ -308,7 +539,7 @@ export function createHttp(deps) {
         return context.json(await deps.flows.listRequirements(asFlowActor(auth), input.flowId));
     });
     // A flow has no grant route of its own. It is shared through the folder it is filed in, under
-    // /knowledge/:nodeId/grants — one place answers the question for the documents and the flows in
+    // /nodes/:nodeId/grants — one place answers the question for the documents and the flows in
     // that folder alike (ADR-0004 §2).
     app.post("/flows", async (context) => {
         const auth = requireCapability(context, "flows", "create");
@@ -341,6 +572,22 @@ export function createHttp(deps) {
         }
         return context.json(await deps.flows.save(asFlowActor(auth), input), 201);
     });
+    // The GET beside `POST /flows/:flowId/versions`: the same collection, read instead of appended
+    // to (#144). `flows/read` like `GET /flows/:flowId` — the history describes a flow the caller
+    // may already open.
+    app.get("/flows/:flowId/versions", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.listVersions(asFlowActor(auth), input.flowId));
+    });
+    app.get("/flows/:flowId/versions/:versionId", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowVersionInput.parse({
+            flowId: context.req.param("flowId"),
+            versionId: context.req.param("versionId"),
+        });
+        return context.json(await deps.flows.getVersion(asFlowActor(auth), input));
+    });
     // What publishing would freeze, before it is published (ADR-0004 §5). A GET because it reads and
     // changes nothing; the `publish` capability because it answers a question only a publisher has.
     app.get("/flows/:flowId/versions/:versionId/publish-preview", async (context) => {
@@ -359,6 +606,15 @@ export function createHttp(deps) {
         }
         return context.json(await deps.flows.publish(asFlowActor(auth), input));
     });
+    // The reverse of publish, behind the same capability: whoever may publish may withdraw (#146).
+    app.post("/flows/:flowId/unpublish", async (context) => {
+        const auth = requireCapability(context, "flows", "publish");
+        const input = UnpublishFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.unpublish(asFlowActor(auth), input));
+    });
     app.post("/flows/:flowId/runs", async (context) => {
         const auth = requireCapability(context, "flows", "run");
         const input = StartFlowRunInput.parse(await context.req.json().catch(() => null));
@@ -403,6 +659,16 @@ export function createHttp(deps) {
         }
         return context.json(await deps.flows.completeStep(asFlowActor(auth), input));
     });
+    // `flows/run`, the same capability the start asked for: whoever may start a run may end it
+    // (#145). The resource-level `execute` is the service's question, asked against the flow.
+    app.post("/flow-runs/:runId/cancel", async (context) => {
+        const auth = requireCapability(context, "flows", "run");
+        const input = CancelFlowRunInput.parse(await context.req.json().catch(() => null));
+        if (input.runId !== context.req.param("runId")) {
+            throw new IntelError(400, "run_id_mismatch", "Path and body run IDs differ");
+        }
+        return context.json(await deps.flows.cancelRun(asFlowActor(auth), input));
+    });
     app.get("/tools", async (context) => {
         const auth = requireCapability(context, "tools", "read");
         return context.json(await deps.tools.catalog(asToolActor(auth)));

package/dist/http/http.types.d.ts

@@ -1,13 +1,17 @@
 import type { GateClient } from "@anchrd/gate-sdk";
+import type { AgentRuntimeService } from "../agent-runtime/agent-runtime.types.js";
 import type { BrowserAuth } from "../auth/auth.types.js";
+import type { BundleService } from "../bundle/bundle.types.js";
 import type { FlowService } from "../flows/flows.types.js";
-import type { KnowledgeService } from "../knowledge/knowledge.types.js";
+import type { NodeService } from "../nodes/nodes.types.js";
 import type { ToolService } from "../tools/tools.types.js";
 export interface HttpDeps {
     gate: Pick<GateClient, "authorize">;
-    knowledge: KnowledgeService;
+    nodes: NodeService;
     flows: FlowService;
     tools: ToolService;
+    bundle: BundleService;
+    agents: AgentRuntimeService;
     resource: string;
     resourceMetadataUrl: string;
     auth?: Pick<BrowserAuth, "resolve">;

package/dist/indexing/indexing.js

@@ -10,7 +10,7 @@ function indexText(mediaType, content) {
     catch (error) {
         // Immutable content never becomes parsable on a retry, so treating this as transient would
         // requeue the version until the queue gives up and would bury the real cause.
-        throw new PermanentIndexingError(`Knowledge version content is not a valid BlockNote document: ${error instanceof Error ? error.message : "unknown parse failure"}`);
+        throw new PermanentIndexingError(`Node version content is not a valid BlockNote document: ${error instanceof Error ? error.message : "unknown parse failure"}`);
     }
 }
 async function readCanonical(deps, target) {
@@ -29,13 +29,25 @@ export function createIndexing(deps) {
             const target = await deps.repository.getTarget(versionId);
             if (!target)
                 return;
+            // ⚠️ An agent's body is a definition, not something to read: node IDs, a cron line and a model
+            // name (ADR-0005 §4). Indexing it verbatim would fill the index with identifiers and, worse,
+            // put them into the passage a searcher is shown — the definition names nodes the searcher may
+            // have no access to, and a snippet is the one place their IDs would become visible without
+            // the tree being asked. What makes an agent findable is what a person wrote about it, so the
+            // text is its description, and the FTS table indexes the title on its own (#139).
+            if (target.kind === "agent") {
+                await deps.repository.replace(target, target.description ?? "");
+                await deps.semantic?.replace(target, target.description ?? "");
+                await deps.repository.markIndexed(versionId, deps.now().toISOString());
+                return;
+            }
             // An attachment is one object of bytes; text kinds may be several, because a table's content
             // is the join of its versions (#40). A missing segment fails the whole pass rather than
             // indexing a table with a hole in it.
             const canonical = await readCanonical(deps, target);
             if (canonical === null) {
                 await deps.repository.markError(versionId, "content_missing", deps.now().toISOString());
-                throw new Error("Knowledge version content is missing");
+                throw new Error("Node version content is missing");
             }
             try {
                 const text = typeof canonical === "string"