@frockbot/kernel-composition 0.1.4 → 0.2.1

package/src/isolate-wrapper.ts

@@ -9,6 +9,10 @@
 //
 // 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.
+import {
+  BOT_ISOLATE_HOOK_EVENTS_V1,
+  type BotPackageContextV1,
+} from "@frockbot/kernel-contracts";
 
 /**
  * The deadline guard, shared verbatim between the generated wrapper and the
@@ -35,6 +39,7 @@ export const BOT_ISOLATE_DEADLINE_SOURCE = `function withIsolateDeadline(work, d
  * 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 HOOK_EVENTS = ${JSON.stringify(BOT_ISOLATE_HOOK_EVENTS_V1)};
 var INVOCATION_KEYS = [
   "schemaVersion",
   "tool",
@@ -72,6 +77,42 @@ function decodeInvocation(value) {
     }
   }
   return value;
+}
+var HOOK_INVOCATION_KEYS = [
+  "schemaVersion",
+  "event",
+  "payload",
+  "botId",
+  "sessionId",
+  "runId",
+  "turnId",
+  "generationId",
+  "deadlineMs",
+];
+function decodeHookInvocation(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("isolate hook invocation must be an object");
+  }
+  if (
+    Object.keys(value).length !== HOOK_INVOCATION_KEYS.length ||
+    !HOOK_INVOCATION_KEYS.every(function (key) {
+      return Object.hasOwn(value, key);
+    })
+  ) {
+    throw new Error("isolate hook invocation has invalid fields");
+  }
+  if (value.schemaVersion !== 1 || !HOOK_EVENTS.includes(value.event)) {
+    throw new Error("isolate hook invocation is unsupported");
+  }
+  if (!value.payload || typeof value.payload !== "object" || Array.isArray(value.payload)) {
+    throw new Error("isolate hook invocation payload is invalid");
+  }
+  for (const key of ["botId", "sessionId", "runId", "turnId", "generationId"]) {
+    if (typeof value[key] !== "string" || value[key].length === 0) {
+      throw new Error("isolate hook invocation " + key + " is invalid");
+    }
+  }
+  return value;
 }`;
 
 /** Decodes one NDJSON line of the `invokeModel` byte stream inside the isolate. */
@@ -99,6 +140,86 @@ export const BOT_ISOLATE_MODEL_SOURCE = `async function* modelEvents(stream) {
   }
 }`;
 
+const BOT_ISOLATE_CONTEXT_PROPERTY_SOURCE_V1 = {
+  tool: "invocation.tool",
+  event: "invocation.event",
+  botId: "invocation.botId",
+  sessionId: "invocation.sessionId",
+  runId: "invocation.runId",
+  turnId: "invocation.turnId",
+  generationId: "invocation.generationId",
+  packageId: "env.IDENTITY.packageId",
+  deadlineMs: "invocation.deadlineMs",
+  bindings: "Object.keys(env).sort()",
+  capabilities: `{
+      list: function () {
+        return capabilities.list();
+      },
+    }`,
+  model: `{
+      invoke: 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),
+        };
+      },
+    }`,
+  tools: `{
+      invoke: function (request) {
+        return capabilities.invokeTool(request);
+      },
+    }`,
+  memory: `{
+      read: function (request) {
+        return capabilities.memoryRead(request);
+      },
+      write: function (request) {
+        return capabilities.memoryWrite(request);
+      },
+      forget: function (request) {
+        return capabilities.memoryForget(request);
+      },
+    }`,
+  workspace: `{
+      read: function (path) {
+        return capabilities.workspaceRead(path);
+      },
+      list: function (request) {
+        return capabilities.workspaceList(request);
+      },
+      stat: function (path) {
+        return capabilities.workspaceStat(path);
+      },
+      write: function (request) {
+        return capabilities.workspaceWrite(request);
+      },
+      delete: function (request) {
+        return capabilities.workspaceDelete(request);
+      },
+    }`,
+  connection:
+    "function (connectionId) { return capabilities.connection(connectionId); }",
+  notify: "function (request) { return capabilities.notify(request); }",
+  schedule: "function (request) { return capabilities.schedule(request); }",
+} satisfies Record<keyof BotPackageContextV1, string>;
+
+/** The keys the generated wrapper actually places on `ctx`. */
+export const BOT_ISOLATE_NARROW_CONTEXT_KEYS_V1 = Object.keys(
+  BOT_ISOLATE_CONTEXT_PROPERTY_SOURCE_V1,
+) as Array<keyof BotPackageContextV1>;
+
+export const BOT_ISOLATE_NARROW_CONTEXT_SOURCE_V1 = `function narrowContext(env, invocation) {
+  const capabilities = env.CAPABILITIES;
+  return {
+${Object.entries(BOT_ISOLATE_CONTEXT_PROPERTY_SOURCE_V1)
+  .map(([key, source]) => `    ${JSON.stringify(key)}: ${source},`)
+  .join("\n")}
+  };
+}`;
+
 /**
  * The wrapper module text. Content-addressed with `package.js`; bump
  * `BOT_ISOLATE_WRAPPER_VERSION` whenever this string changes so the mounted
@@ -108,7 +229,7 @@ export const BOT_ISOLATE_WRAPPER_SOURCE = `// Generated by @frockbot/kernel-comp
 import { WorkerEntrypoint } from "cloudflare:workers";
 import * as botPackage from "./package.js";
 
-const CONTRACT_VERSION = 2;
+const CONTRACT_VERSION = 3;
 
 ${BOT_ISOLATE_DEADLINE_SOURCE}
 
@@ -155,38 +276,24 @@ function declaredTools() {
   });
 }
 
-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),
-      };
-    },
-  };
+function declaredHooks() {
+  if (botPackage.hooks === undefined) return [];
+  if (!botPackage.hooks || typeof botPackage.hooks !== "object" || Array.isArray(botPackage.hooks)) {
+    throw new Error('package.js "hooks" must be an object');
+  }
+  return Object.keys(botPackage.hooks).map(function (event) {
+    if (!HOOK_EVENTS.includes(event)) {
+      throw new Error('package.js declared an unsupported hook "' + event + '"');
+    }
+    if (typeof botPackage.hooks[event] !== "function") {
+      throw new Error('package.js hook "' + event + '" must be a function');
+    }
+    return event;
+  });
 }
 
+${BOT_ISOLATE_NARROW_CONTEXT_SOURCE_V1}
+
 export default class extends WorkerEntrypoint {
   async health() {
     return {
@@ -195,6 +302,7 @@ export default class extends WorkerEntrypoint {
       packageId: this.env.IDENTITY.packageId,
       contractVersion: CONTRACT_VERSION,
       tools: declaredTools(),
+      hooks: declaredHooks(),
     };
   }
 
@@ -227,11 +335,26 @@ export default class extends WorkerEntrypoint {
       };
     }
   }
+
+  async hook(rawInvocation) {
+    const invocation = decodeHookInvocation(rawInvocation);
+    const hooks = declaredHooks();
+    if (!hooks.includes(invocation.event)) {
+      throw new Error('package.js did not declare hook "' + invocation.event + '"');
+    }
+    const context = narrowContext(this.env, invocation);
+    const replacement = await withIsolateDeadline(function () {
+      return botPackage.hooks[invocation.event](invocation.payload, context);
+    }, invocation.deadlineMs);
+    return replacement === undefined
+      ? { schemaVersion: 1, status: "unchanged" }
+      : { schemaVersion: 1, status: "replaced", replacement: replacement };
+  }
 }
 `;
 
 /** 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_WRAPPER_VERSION = "wrapper-v4";
 
 export const BOT_ISOLATE_MAIN_MODULE = "index.js";
 export const BOT_ISOLATE_PACKAGE_MODULE = "package.js";

package/src/manifest.ts

@@ -1,14 +1,19 @@
-import { decodeTurnTypeV1, type TurnTypeV1 } from "@frockbot/kernel-contracts";
+import {
+  isBotIsolateHookEventNameV1,
+  decodeTurnTypeV1,
+  type BotIsolateHookEventNameV1,
+  type TurnTypeV1,
+} from "@frockbot/kernel-contracts";
 
 /** The Contribution kinds a Package manifest can declare. */
 export type ManifestContributionKind =
   "backend" | "runtime" | "client" | "desktop" | "mobile";
 
 /**
- * Every execution host a Contribution can be mounted in. `bot-isolate` is not
- * manifest-declared: it is derived from a Composition member carrying an
- * immutable artifact, so a Package's provenance — not its manifest — decides
- * whether it runs in the kernel isolate or a loaded Dynamic Worker.
+ * Every execution host a Contribution can be mounted in. A Bot-authored
+ * manifest declares `bot-isolate`, but provenance and an immutable artifact
+ * still decide whether the host accepts it; a manifest never grants itself
+ * that execution authority.
  */
 export type ContributionKind = ManifestContributionKind | "bot-isolate";
 
@@ -19,6 +24,15 @@ export interface BackendContribution {
 
 export interface RuntimeContribution {
   entry: string;
+  /** Present only on a Bot-authored manifest; provenance still decides host authority. */
+  host?: "bot-isolate";
+}
+
+/** A Bot-authored manifest's durable declaration; isolate health supplies details at mount. */
+export interface ManifestToolDeclaration {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
 }
 
 export interface ClientMount {
@@ -26,12 +40,37 @@ export interface ClientMount {
   order?: number;
 }
 
-export interface ClientContribution {
+/** A reviewed first-party client module compiled into the hosted bundle. */
+export interface ClientModuleContribution {
   entry: string;
   mounts: ClientMount[];
   outlets: string[];
 }
 
+/** Immutable HTML bytes rendered only by the first-party sandbox host. */
+export interface ClientIframeArtifactV1 {
+  contentHash: string;
+  size: number;
+  mediaType: "text/html";
+  bundlerVersion: string;
+}
+
+/** A non-first-party page. It never becomes JavaScript in the app origin. */
+export interface ClientIframeContribution {
+  kind: "iframe";
+  artifact: ClientIframeArtifactV1;
+  mounts: ClientMount[];
+}
+
+export type ClientContribution =
+  ClientModuleContribution | ClientIframeContribution;
+
+export function isClientIframeContribution(
+  contribution: ClientContribution,
+): contribution is ClientIframeContribution {
+  return "kind" in contribution && contribution.kind === "iframe";
+}
+
 export interface DesktopContribution {
   entry: string;
   execution: "sandboxed-renderer" | "trusted-main";
@@ -146,6 +185,10 @@ export interface FrockBotManifest {
   };
   permissions: string[];
   configuration?: PackageConfiguration;
+  /** Present exactly when `contributions.runtime.host` is `bot-isolate`. */
+  tools?: ManifestToolDeclaration[];
+  /** Bot-isolate waterfalls the immutable artifact declares it exports. */
+  hooks?: BotIsolateHookEventNameV1[];
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -166,6 +209,88 @@ function exactFields(
   }
 }
 
+function validateManifestJson(value: unknown, label: string, depth = 0): void {
+  if (depth > 16) throw new Error(`${label} is too deeply nested`);
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  ) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) validateManifestJson(entry, label, depth + 1);
+    return;
+  }
+  if (!isRecord(value)) throw new Error(`${label} must contain only JSON`);
+  for (const entry of Object.values(value)) {
+    validateManifestJson(entry, label, depth + 1);
+  }
+}
+
+function decodeManifestTools(
+  value: unknown,
+): ManifestToolDeclaration[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length === 0 || value.length > 64) {
+    throw new Error("manifest tools must be a non-empty bounded array");
+  }
+  const tools = value.map((candidate, index) => {
+    if (!isRecord(candidate)) {
+      throw new Error(`manifest tools[${index}] must be an object`);
+    }
+    exactFields(
+      candidate,
+      ["name", "description", "inputSchema"],
+      `manifest tools[${index}]`,
+    );
+    const name = requiredString(candidate, "name");
+    if (!/^[a-z][a-z0-9_]{0,63}$/.test(name)) {
+      throw new Error(`manifest tools[${index}] name is invalid`);
+    }
+    const description = requiredString(candidate, "description");
+    if (description.length > 1_024) {
+      throw new Error(`manifest tools[${index}] description is too long`);
+    }
+    if (!isRecord(candidate.inputSchema)) {
+      throw new Error(`manifest tools[${index}] inputSchema must be an object`);
+    }
+    validateManifestJson(
+      candidate.inputSchema,
+      `manifest tools[${index}] inputSchema`,
+    );
+    return {
+      name,
+      description,
+      inputSchema: structuredClone(candidate.inputSchema),
+    };
+  });
+  if (new Set(tools.map((tool) => tool.name)).size !== tools.length) {
+    throw new Error("manifest tools contains duplicate names");
+  }
+  return tools;
+}
+
+function decodeManifestHooks(
+  value: unknown,
+): BotIsolateHookEventNameV1[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length === 0 || value.length > 16) {
+    throw new Error("manifest hooks must be a non-empty bounded array");
+  }
+  const hooks = value.map((hook, index) => {
+    if (!isBotIsolateHookEventNameV1(hook)) {
+      throw new Error(`manifest hooks[${index}] is invalid`);
+    }
+    return hook;
+  });
+  if (new Set(hooks).size !== hooks.length) {
+    throw new Error("manifest hooks contains duplicates");
+  }
+  return hooks;
+}
+
 function requiredString(record: Record<string, unknown>, key: string): string {
   const value = record[key];
   if (typeof value !== "string" || !value.trim()) {
@@ -368,43 +493,102 @@ function decodeV2(value: Record<string, unknown>): FrockBotManifest {
     }
     exactFields(
       value.contributions.runtime,
-      ["entry"],
+      ["entry", ...(isV3OrLater(value) ? ["host"] : [])],
       "manifest runtime contribution",
     );
+    const host = value.contributions.runtime.host;
+    if (host !== undefined && host !== "bot-isolate") {
+      throw new Error("manifest runtime host is invalid");
+    }
     contributions.runtime = {
       entry: relativeEntry(value.contributions.runtime, "entry"),
+      ...(host === "bot-isolate" ? { host } : {}),
     };
   }
   if (value.contributions.client !== undefined) {
     const client = value.contributions.client;
     if (!isRecord(client))
       throw new Error("manifest client contribution must be an object");
-    exactFields(
-      client,
-      ["entry", "mounts", "outlets"],
-      "manifest client contribution",
-    );
     const mounts = client.mounts;
     if (!Array.isArray(mounts)) {
       throw new Error("manifest client mounts must be an array");
     }
-    contributions.client = {
-      entry: relativeEntry(client, "entry"),
-      mounts: mounts.map((mount) => {
-        if (!isRecord(mount))
-          throw new Error("manifest client mount must be an object");
-        exactFields(mount, ["slot", "order"], "manifest client mount");
-        const order = mount.order;
-        if (
-          order !== undefined &&
-          (typeof order !== "number" || !Number.isFinite(order))
-        ) {
-          throw new Error("manifest client mount order must be finite");
-        }
-        return { slot: requiredString(mount, "slot"), order };
-      }),
-      outlets: optionalStringArray(client, "outlets"),
-    };
+    const decodedMounts = mounts.map((mount) => {
+      if (!isRecord(mount))
+        throw new Error("manifest client mount must be an object");
+      exactFields(mount, ["slot", "order"], "manifest client mount");
+      const order = mount.order;
+      if (
+        order !== undefined &&
+        (typeof order !== "number" || !Number.isFinite(order))
+      ) {
+        throw new Error("manifest client mount order must be finite");
+      }
+      return {
+        slot: requiredString(mount, "slot"),
+        ...(order === undefined ? {} : { order }),
+      };
+    });
+    if (client.kind === "iframe") {
+      if (!isV3OrLater(value)) {
+        throw new Error("manifest iframe client requires schema version 3");
+      }
+      exactFields(
+        client,
+        ["kind", "artifact", "mounts"],
+        "manifest iframe client contribution",
+      );
+      if (!isRecord(client.artifact)) {
+        throw new Error("manifest iframe client artifact must be an object");
+      }
+      exactFields(
+        client.artifact,
+        ["contentHash", "size", "mediaType", "bundlerVersion"],
+        "manifest iframe client artifact",
+      );
+      const artifact = client.artifact;
+      if (
+        typeof artifact.contentHash !== "string" ||
+        !/^[0-9a-f]{64}$/.test(artifact.contentHash)
+      ) {
+        throw new Error(
+          "manifest iframe client artifact contentHash must be a sha-256 digest",
+        );
+      }
+      if (
+        !Number.isSafeInteger(artifact.size) ||
+        (artifact.size as number) < 0 ||
+        (artifact.size as number) > 256 * 1024
+      ) {
+        throw new Error(
+          "manifest iframe client artifact size must be within the 256 KB quota",
+        );
+      }
+      if (artifact.mediaType !== "text/html") {
+        throw new Error("manifest iframe client artifact mediaType is invalid");
+      }
+      contributions.client = {
+        kind: "iframe",
+        artifact: {
+          contentHash: artifact.contentHash,
+          size: artifact.size as number,
+          mediaType: "text/html",
+          bundlerVersion: requiredString(artifact, "bundlerVersion"),
+        },
+        mounts: decodedMounts,
+      };
+    } else {
+      exactFields(
+        client,
+        ["entry", "mounts", "outlets"],
+        "manifest client contribution",
+      );
+      contributions.client = {
+        entry: relativeEntry(client, "entry"),
+        mounts: decodedMounts,
+        outlets: optionalStringArray(client, "outlets"),
+      };
+    }
   }
   if (value.contributions.mobile !== undefined) {
     const mobile = value.contributions.mobile;
@@ -1218,23 +1402,79 @@ function decodeConfiguration(
 
 function decodeV3(value: Record<string, unknown>): FrockBotManifest {
   const base = decodeV2(value);
+  const tools = decodeManifestTools(value.tools);
+  const hooks = decodeManifestHooks(value.hooks);
+  const botIsolate = base.contributions.runtime?.host === "bot-isolate";
+  if (botIsolate !== (tools !== undefined)) {
+    throw new Error(
+      "manifest bot-isolate runtime and tools declaration must appear together",
+    );
+  }
+  if (!botIsolate && hooks !== undefined) {
+    throw new Error("manifest hooks require a bot-isolate runtime");
+  }
+  validateIframeClientContribution(base.contributions.client, tools);
   return {
     ...base,
     schemaVersion: 3,
     configuration: decodeConfiguration(value.configuration, false),
+    ...(tools ? { tools } : {}),
+    ...(hooks ? { hooks } : {}),
   };
 }
 
 /** v4 is v3 plus the Capability admission ceiling, and nothing else. */
 function decodeV4(value: Record<string, unknown>): FrockBotManifest {
   const base = decodeV2(value);
+  const tools = decodeManifestTools(value.tools);
+  const hooks = decodeManifestHooks(value.hooks);
+  const botIsolate = base.contributions.runtime?.host === "bot-isolate";
+  if (botIsolate !== (tools !== undefined)) {
+    throw new Error(
+      "manifest bot-isolate runtime and tools declaration must appear together",
+    );
+  }
+  if (!botIsolate && hooks !== undefined) {
+    throw new Error("manifest hooks require a bot-isolate runtime");
+  }
+  validateIframeClientContribution(base.contributions.client, tools);
   return {
     ...base,
     schemaVersion: 4,
     configuration: decodeConfiguration(value.configuration, true),
+    ...(tools ? { tools } : {}),
+    ...(hooks ? { hooks } : {}),
   };
 }
 
+function validateIframeClientContribution(
+  client: ClientContribution | undefined,
+  tools: ManifestToolDeclaration[] | undefined,
+): void {
+  if (!client || !isClientIframeContribution(client)) return;
+  if (client.mounts.length === 0 || client.mounts.length > 64) {
+    throw new Error(
+      "manifest iframe client mounts must be a non-empty bounded array",
+    );
+  }
+  const toolNames = new Set((tools ?? []).map((tool) => tool.name));
+  for (const mount of client.mounts) {
+    if (mount.slot === "frockbot.bot-settings-sections") continue;
+    const prefix = "frockbot.tool-result:";
+    if (!mount.slot.startsWith(prefix)) {
+      throw new Error(
+        `manifest iframe client slot "${mount.slot}" is not iframe-safe`,
+      );
+    }
+    const toolName = mount.slot.slice(prefix.length);
+    if (!toolNames.has(toolName)) {
+      throw new Error(
+        `manifest iframe client tool-result slot names undeclared tool "${toolName}"`,
+      );
+    }
+  }
+}
+
 export function decodeFrockBotManifest(value: unknown): FrockBotManifest {
   if (!isRecord(value)) throw new Error("manifest must be an object");
   if (value.schemaVersion === 1) {
@@ -1270,6 +1510,8 @@ export function decodeFrockBotManifest(value: unknown): FrockBotManifest {
         "defaultEnablement",
         "contributions",
         ...(isV3OrLater(value) ? ["configuration"] : []),
+        ...(isV3OrLater(value) ? ["tools"] : []),
+        ...(isV3OrLater(value) ? ["hooks"] : []),
       ],
       "manifest",
     );