@anchrd/intel-api 0.6.6 → 0.7.0

package/dist/adapters/gate-applications/gate-applications.d.ts

@@ -0,0 +1,23 @@
+import type { AgentApplications } from "../../nodes/nodes.types.js";
+/**
+ * Intel's door to Gate's Applications surface (`anchrd/gate#223`/`#224`, Gate 0.10.x).
+ *
+ * ⚠️ This is the one Gate call Intel makes with the CALLER's bearer instead of its service key, and
+ * that is not a shortcut — the service key does not open this door. A Gate service key authorizes
+ * `/api/v1/authorization` and `/api/v1/schema` and nothing else (Gate's two-token rule); the
+ * Applications routes are admin-gated and resolve a real principal, so the person creating an agent
+ * needs `applications:write` in Gate and their act is audited in Gate under their own name. A
+ * service key here would have made Intel the author of every machine principal an installation ever
+ * grew, which is the opposite of what an audit trail is for.
+ *
+ * ⚠️ Nothing this module receives from Gate is logged, wrapped into a message, or returned other
+ * than through the one typed answer below. `create` is handed a plain-text key, and the shortest
+ * path from here to a leak is an error that quotes the response body — so no refusal names anything
+ * but the status Gate answered with.
+ */
+export interface GateApplicationsDeps {
+    fetch: (url: string, init?: RequestInit) => Promise<Response>;
+    gateUrl: string;
+    timeoutMs?: number;
+}
+export declare function createGateApplications(deps: GateApplicationsDeps): AgentApplications;

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

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { IntelError } from "../../shared/intel-error/intel-error.js";
+// Tolerant on purpose, unlike Intel's own contracts: this is somebody else's wire format, and a
+// 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) });
+const DefaultTimeoutMs = 10_000;
+export function createGateApplications(deps) {
+    const base = deps.gateUrl.replace(/\/+$/, "");
+    const timeoutMs = deps.timeoutMs ?? DefaultTimeoutMs;
+    // Gate's refusals, translated once. A 401/403 is the caller's missing `applications:write` and is
+    // permanent until somebody acts in Gate, so it is answered as a refusal rather than as an outage;
+    // everything else — a 5xx, a timeout, a DNS failure — is "Gate did not answer", and the caller is
+    // told that no agent was created rather than left to guess.
+    function refusal(status) {
+        if (status === 401 || status === 403) {
+            return new IntelError(403, "agent_application_forbidden", "Gate refused this account the management of applications — creating an agent needs the applications permission in Gate");
+        }
+        return new IntelError(502, "agent_application_unavailable", `Gate could not manage this agent's application (${status})`);
+    }
+    async function call(path, token, body) {
+        try {
+            return await deps.fetch(`${base}/api/v1/applications${path}`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch {
+            // ⚠️ The caught error is dropped rather than described. A fetch failure carries the URL, and
+            // the URL is the one place the bearer could still be if a caller ever put it in a query.
+            throw new IntelError(502, "agent_application_unavailable", "Gate did not answer, so no agent application was created or changed");
+        }
+    }
+    return {
+        async create(input) {
+            const response = await call("", input.token, { name: input.name });
+            if (!response.ok)
+                throw refusal(response.status);
+            const parsed = CreatedApplication.safeParse(await response.json().catch(() => null));
+            if (!parsed.success) {
+                // ⚠️ A 2xx Intel cannot read means a principal MAY exist in Gate that Intel cannot record.
+                // Nothing has been written on this side yet, so the agent does not come into being; the
+                // operator finds an unused application in Gate's list rather than an agent that half works.
+                throw new IntelError(502, "agent_application_unavailable", "Gate answered the application creation in a shape Intel cannot read");
+            }
+            return { id: parsed.data.id, 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.
+            const response = await call(`/${encodeURIComponent(input.applicationId)}/${input.enabled ? "enable" : "disable"}`, input.token, {});
+            // A 404 is the one status worth separating: the Application behind this agent is gone from
+            // Gate, and telling the operator that is more use than a generic outage they would retry.
+            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);
+        },
+    };
+}

package/dist/adapters/index-queue/index-queue.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import type { QueueProducer } from "./index-queue.types.js";
 export declare const IndexMessage: z.ZodObject<{
-    type: z.ZodLiteral<"knowledge.version">;
+    type: z.ZodLiteral<"node.version">;
     versionId: z.ZodString;
 }, z.core.$strict>;
 export type IndexMessage = z.infer<typeof IndexMessage>;

package/dist/adapters/index-queue/index-queue.js

@@ -1,12 +1,12 @@
 import { z } from "zod";
 export const IndexMessage = z.strictObject({
-    type: z.literal("knowledge.version"),
+    type: z.literal("node.version"),
     versionId: z.string().min(1),
 });
 export function createIndexQueue(queue) {
     return {
         async enqueue(versionId) {
-            await queue.send({ type: "knowledge.version", versionId });
+            await queue.send({ type: "node.version", versionId });
         },
     };
 }

package/dist/adapters/semantic-index/semantic-index.types.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeIndexTarget } from "../../knowledge/knowledge.types.js";
+import type { NodeIndexTarget } from "../../nodes/nodes.types.js";
 export interface WorkersAiBinding {
     run(model: string, input: {
         text: string[];
@@ -22,7 +22,7 @@ export interface SemanticHit {
     score: number;
 }
 export interface SemanticIndex {
-    replace(target: KnowledgeIndexTarget, content: string): Promise<void>;
+    replace(target: NodeIndexTarget, content: string): Promise<void>;
     search(query: string, limit: number): Promise<SemanticHit[]>;
 }
 export interface SemanticIndexDeps {

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

@@ -0,0 +1,16 @@
+import type { AgentRuntimeDeps, AgentRuntimeService } from "./agent-runtime.types.js";
+/**
+ * Intel's door to the agent runtime.
+ *
+ * ⚠️ The browser never talks to the runtime. It talks to Intel, and Intel forwards — one origin for
+ * the page, one session cookie, no CORS, and no Gate token in browser JavaScript. What travels on
+ * the forwarded call is the caller's OWN bearer, which the runtime then checks for `agents/run`
+ * exactly as it would from any other client. Intel impersonates nobody: there is no service key on
+ * this path, and a request that arrives without a usable session never reaches the binding.
+ *
+ * ⚠️ The three checks below are in this order on purpose. The capability comes first, so a caller
+ * who may not drive agents at all causes no storage read; the resource ACL comes second, because it
+ * is the question the runtime cannot answer; the binding comes last, so nobody learns whether this
+ * deployment has a runtime before they are allowed to ask.
+ */
+export declare function createAgentRuntimeService(deps: AgentRuntimeDeps): AgentRuntimeService;

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

@@ -0,0 +1,76 @@
+import { ProblemDetails } from "@anchrd/intel-contract";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+/**
+ * The host a service binding never resolves.
+ *
+ * A `Request` needs an absolute URL and a binding routes on the path alone, so this name exists
+ * only to make one. `.internal` is not a resolvable TLD: a call that ever left this Worker by
+ * mistake fails to connect rather than reaching a stranger who registered the domain.
+ */
+const RuntimeOrigin = "https://intel-agent.internal";
+/**
+ * Intel's door to the agent runtime.
+ *
+ * ⚠️ The browser never talks to the runtime. It talks to Intel, and Intel forwards — one origin for
+ * the page, one session cookie, no CORS, and no Gate token in browser JavaScript. What travels on
+ * the forwarded call is the caller's OWN bearer, which the runtime then checks for `agents/run`
+ * exactly as it would from any other client. Intel impersonates nobody: there is no service key on
+ * this path, and a request that arrives without a usable session never reaches the binding.
+ *
+ * ⚠️ The three checks below are in this order on purpose. The capability comes first, so a caller
+ * who may not drive agents at all causes no storage read; the resource ACL comes second, because it
+ * is the question the runtime cannot answer; the binding comes last, so nobody learns whether this
+ * deployment has a runtime before they are allowed to ask.
+ */
+export function createAgentRuntimeService(deps) {
+    async function reach(actor, agentId) {
+        if (!actor.canRun) {
+            throw new IntelError(403, "permission_required", "Permission required");
+        }
+        const node = await deps.visibleNode(actor, agentId);
+        // Not found and not visible answer alike, as everywhere else in the tree: the difference would
+        // tell somebody an agent exists that they may not see.
+        if (node?.kind !== "agent") {
+            throw new IntelError(404, "agent_not_found", "Agent was not found");
+        }
+        if (!deps.runtime) {
+            throw new IntelError(503, "agent_runtime_not_configured", "This installation has no agent runtime");
+        }
+        return deps.runtime;
+    }
+    async function forward(input) {
+        const runtime = await reach(input.actor, input.agentId);
+        const headers = new Headers({ authorization: `Bearer ${input.token}` });
+        if (input.body !== undefined)
+            headers.set("content-type", "application/json");
+        return await runtime.fetch(new Request(`${RuntimeOrigin}/agents/${encodeURIComponent(input.agentId)}${input.path}`, {
+            method: input.method,
+            headers,
+            ...(input.body === undefined ? {} : { body: input.body }),
+            ...(input.signal ? { signal: input.signal } : {}),
+        }));
+    }
+    return {
+        forward,
+        // 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,
+        async request(input) {
+            const response = await forward(input);
+            const body = await response.json().catch(() => null);
+            if (!response.ok) {
+                const problem = ProblemDetails.safeParse(body);
+                // ⚠️ The runtime's own words, and only those. Its refusals are written to be read — by a
+                // person on the Log tab and by a model on the MCP surface alike — while anything it could
+                // not explain arrives as a generic 500 body. Nothing about the forwarded call is added
+                // here: the URL, the binding and above all the bearer stay out of every message.
+                throw new IntelError(response.status, problem.success
+                    ? (problem.data.code ?? "agent_runtime_refused")
+                    : "agent_runtime_refused", problem.success
+                    ? (problem.data.detail ?? problem.data.title)
+                    : "The agent runtime refused this call");
+            }
+            return body;
+        },
+    };
+}

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

@@ -0,0 +1,57 @@
+import type { Node } from "@anchrd/intel-contract";
+import type { Actor } from "../nodes/nodes.types.js";
+/**
+ * The agent runtime Worker, as Intel is allowed to see it.
+ *
+ * One method, because that is all a service binding is. The Cloudflare adapter hands the binding
+ * over unchanged; nothing below this line knows it is one, so the whole seam is testable with a
+ * plain object that records what it was asked.
+ */
+export interface AgentRuntimeBinding {
+    fetch(request: Request): Promise<Response>;
+}
+/**
+ * Who is driving the agent.
+ *
+ * ⚠️ `canRun` is the caller's Gate capability, resolved once at the door — never something a body,
+ * an MCP argument or a definition may say. It is spelled beside the actor rather than derived here
+ * for the same reason `FlowActor` spells `canRun`: the service must not need a Gate client.
+ */
+export interface AgentActor extends Actor {
+    canRun: boolean;
+}
+export interface AgentRuntimeDeps {
+    /**
+     * 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.
+     */
+    runtime?: AgentRuntimeBinding;
+    /**
+     * The tree's own visibility lookup, unchanged on the way through. It is the check the runtime
+     * cannot make: the runtime knows Gate capabilities and nothing about Intel's resource ACLs, so
+     * "may this person drive agents at all" is its question and "may they reach THIS agent" is ours.
+     */
+    visibleNode(actor: Actor, nodeId: string): Promise<Node | null>;
+}
+export interface ForwardInput {
+    actor: AgentActor;
+    /** The caller's own Gate bearer, passed on unchanged. Never a service key (D19). */
+    token: string;
+    agentId: string;
+    method: "GET" | "POST";
+    /** The path below `/agents/:agentId`, exactly as the runtime mounts it. */
+    path: string;
+    body?: string;
+    signal?: AbortSignal;
+}
+export interface AgentRuntimeService {
+    /** The browser's way through: the runtime's answer, body and headers untouched. */
+    forward(input: ForwardInput): Promise<Response>;
+    /** The same door for a caller that wants the answer, not the response — Intel MCP uses this. */
+    request(input: ForwardInput): Promise<unknown>;
+    /**
+     * Whether this deployment has a runtime at all (#190). The answer `/capabilities` gives to an
+     * authenticated caller so the UI can stop offering agents instead of guessing from a 503.
+     */
+    available(): boolean;
+}

package/dist/bundle/bundle.d.ts

@@ -0,0 +1,4 @@
+import type { BundleDeps, BundleService } from "./bundle.types.js";
+export declare const MaxImportZipBytes: number;
+export declare const MaxImportEntryBytes: number;
+export declare function createBundle(deps: BundleDeps): BundleService;