@frockbot/kernel-composition 0.0.0 → 0.1.1

package/src/isolate-wrapper.ts

@@ -0,0 +1,247 @@
+// The kernel-generated wrapper module (`index.js`) for a Bot isolate.
+//
+// This is composition, not contract: the kernel *generates* this text and
+// content-addresses it together with `package.js`, so changing a byte of it is
+// a new artifact set and therefore a new loader identity. Bot code never
+// implements the wrapper; it exports `tools` and `execute` and the wrapper
+// adapts, decodes the invocation, enforces the deadline, and hands user code a
+// narrow `ctx` that names only what the isolate may do.
+//
+// The wrapper is emitted as plain JavaScript because it is a module in the
+// loaded Worker's module map, not a source file this repository compiles.
+
+/**
+ * The deadline guard, shared verbatim between the generated wrapper and the
+ * Bun test that proves it. Kept as source text so the tested function and the
+ * shipped function cannot drift.
+ */
+export const BOT_ISOLATE_DEADLINE_SOURCE = `function withIsolateDeadline(work, deadlineMs) {
+  if (!Number.isSafeInteger(deadlineMs) || deadlineMs <= 0 || deadlineMs > 60000) {
+    return Promise.reject(new Error("isolate invocation deadline is out of range"));
+  }
+  let timer;
+  const expiry = new Promise(function (_resolve, reject) {
+    timer = setTimeout(function () {
+      reject(new Error("isolate invocation exceeded its deadline of " + deadlineMs + "ms"));
+    }, deadlineMs);
+  });
+  return Promise.race([Promise.resolve().then(work), expiry]).finally(function () {
+    clearTimeout(timer);
+  });
+}`;
+
+/**
+ * The invocation guard. The isolate re-decodes what the Durable Object sent:
+ * the boundary is crossed in both directions and both sides decode.
+ */
+export const BOT_ISOLATE_INVOCATION_SOURCE = `var TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+var INVOCATION_KEYS = [
+  "schemaVersion",
+  "tool",
+  "input",
+  "botId",
+  "sessionId",
+  "runId",
+  "turnId",
+  "generationId",
+  "deadlineMs",
+];
+function decodeInvocation(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("isolate tool invocation must be an object");
+  }
+  // Exact keys, like the outbound twin: an invocation carrying a field this
+  // contract does not declare is not this contract's invocation.
+  if (
+    Object.keys(value).length !== INVOCATION_KEYS.length ||
+    !INVOCATION_KEYS.every(function (key) {
+      return Object.hasOwn(value, key);
+    })
+  ) {
+    throw new Error("isolate tool invocation has invalid fields");
+  }
+  if (value.schemaVersion !== 1) {
+    throw new Error("isolate tool invocation schemaVersion is unsupported");
+  }
+  if (typeof value.tool !== "string" || !TOOL_NAME.test(value.tool)) {
+    throw new Error("isolate tool invocation tool is invalid");
+  }
+  for (const key of ["botId", "sessionId", "runId", "turnId", "generationId"]) {
+    if (typeof value[key] !== "string" || value[key].length === 0) {
+      throw new Error("isolate tool invocation " + key + " is invalid");
+    }
+  }
+  return value;
+}`;
+
+/** Decodes one NDJSON line of the `invokeModel` byte stream inside the isolate. */
+export const BOT_ISOLATE_MODEL_SOURCE = `async function* modelEvents(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (;;) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      buffer += decoder.decode(chunk.value, { stream: true });
+      let newline = buffer.indexOf("\\n");
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (line.length > 0) yield JSON.parse(line);
+        newline = buffer.indexOf("\\n");
+      }
+    }
+    const tail = buffer.trim();
+    if (tail.length > 0) yield JSON.parse(tail);
+  } finally {
+    reader.releaseLock();
+  }
+}`;
+
+/**
+ * The wrapper module text. Content-addressed with `package.js`; bump
+ * `BOT_ISOLATE_WRAPPER_VERSION` whenever this string changes so the mounted
+ * module set — and therefore the loader id — changes with it.
+ */
+export const BOT_ISOLATE_WRAPPER_SOURCE = `// Generated by @frockbot/kernel-composition. Do not edit inside the isolate.
+import { WorkerEntrypoint } from "cloudflare:workers";
+import * as botPackage from "./package.js";
+
+const CONTRACT_VERSION = 2;
+
+${BOT_ISOLATE_DEADLINE_SOURCE}
+
+${BOT_ISOLATE_INVOCATION_SOURCE}
+
+${BOT_ISOLATE_MODEL_SOURCE}
+
+function declaredTools() {
+  const declared = Array.isArray(botPackage.tools) ? botPackage.tools : [];
+  if (declared.length === 0) {
+    throw new Error('package.js must export a non-empty "tools" array');
+  }
+  if (typeof botPackage.execute !== "function") {
+    throw new Error('package.js must export an "execute" function');
+  }
+  return declared.map(function (tool) {
+    if (!tool || typeof tool.name !== "string" || !TOOL_NAME.test(tool.name)) {
+      throw new Error("package.js declared a tool with an invalid name");
+    }
+    const schema =
+      tool.inputSchema && typeof tool.inputSchema === "object" && !Array.isArray(tool.inputSchema)
+        ? tool.inputSchema
+        : {};
+    // Contract version 2: a tool may name the turn types it is offered on.
+    // The kernel decodes and bounds it; the wrapper only carries it across.
+    const admission =
+      tool.admission && typeof tool.admission === "object"
+        ? {
+            turnTypes: tool.admission.turnTypes,
+            ...(tool.admission.subagentRoles
+              ? { subagentRoles: tool.admission.subagentRoles }
+              : {}),
+          }
+        : undefined;
+    return Object.assign(
+      {
+        name: tool.name,
+        description: typeof tool.description === "string" ? tool.description : "",
+        inputSchema: schema,
+        idempotent: tool.idempotent === true,
+      },
+      admission ? { admission: admission } : {},
+    );
+  });
+}
+
+function narrowContext(env, invocation) {
+  const capabilities = env.CAPABILITIES;
+  return {
+    tool: invocation.tool,
+    botId: invocation.botId,
+    sessionId: invocation.sessionId,
+    runId: invocation.runId,
+    turnId: invocation.turnId,
+    generationId: invocation.generationId,
+    packageId: env.IDENTITY.packageId,
+    deadlineMs: invocation.deadlineMs,
+    // What this isolate holds, by name. Everything else is out of scope:
+    // globalOutbound is null and no host binding is in env.
+    bindings: Object.keys(env).sort(),
+    listCapabilities: function () {
+      return capabilities.list();
+    },
+    requestAuthority: function (request) {
+      return capabilities.requestAuthority(request);
+    },
+    invokeModel: async function (request) {
+      const outcome = await capabilities.invokeModel(request);
+      if (!outcome || outcome.status !== "streaming") return outcome;
+      return {
+        status: "streaming",
+        requestId: outcome.requestId,
+        events: modelEvents(outcome.events),
+      };
+    },
+  };
+}
+
+export default class extends WorkerEntrypoint {
+  async health() {
+    return {
+      schemaVersion: 1,
+      ok: true,
+      packageId: this.env.IDENTITY.packageId,
+      contractVersion: CONTRACT_VERSION,
+      tools: declaredTools(),
+    };
+  }
+
+  async execute(rawInvocation) {
+    let invocation;
+    try {
+      invocation = decodeInvocation(rawInvocation);
+    } catch (error) {
+      return {
+        schemaVersion: 1,
+        content: String((error && error.message) || error),
+        isError: true,
+      };
+    }
+    try {
+      const context = narrowContext(this.env, invocation);
+      const value = await withIsolateDeadline(function () {
+        return botPackage.execute(invocation.tool, invocation.input, context);
+      }, invocation.deadlineMs);
+      return {
+        schemaVersion: 1,
+        content: typeof value === "string" ? value : JSON.stringify(value ?? null),
+        isError: false,
+      };
+    } catch (error) {
+      return {
+        schemaVersion: 1,
+        content: String((error && error.message) || error),
+        isError: true,
+      };
+    }
+  }
+}
+`;
+
+/** Bumped with any change to the wrapper text; folded into the loader id. */
+export const BOT_ISOLATE_WRAPPER_VERSION = "wrapper-v2";
+
+export const BOT_ISOLATE_MAIN_MODULE = "index.js";
+export const BOT_ISOLATE_PACKAGE_MODULE = "package.js";
+
+/** The exactly-two-entry module map a Bot isolate mounts. */
+export function botIsolateModuleMap(packageSource: string): {
+  [path: string]: { js: string };
+} {
+  return {
+    [BOT_ISOLATE_MAIN_MODULE]: { js: BOT_ISOLATE_WRAPPER_SOURCE },
+    [BOT_ISOLATE_PACKAGE_MODULE]: { js: packageSource },
+  };
+}