@frockbot/applet-sdk 0.7.38 → 0.7.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.7.38",
+  "version": "0.7.39",
   "private": false,
   "type": "module",
   "description": "Authoring SDK for FrockBot Applets: schema-first Durable Object server, TanStack DB client, component kit, linter, and the build pipeline.",

package/plugin/index.d.ts

@@ -347,11 +347,37 @@ export type PluginHooks = {
   [Event in PluginHookEvent]?: PluginHook<Event>;
 };
 
-/** A trigger handler: what it returns, when non-empty, is what the Bot reads. */
+/**
+ * One delivery handed to a trigger: the posted body as it arrived, and the
+ * headers lower-cased with the door's own credential removed.
+ */
+export interface PluginTriggerDelivery {
+  headers: Record<string, string>;
+  body: string;
+}
+
+/** A trigger's refusal: the Routine does not fire, and the receipt says why. */
+export interface PluginTriggerDrop {
+  drop: true;
+  reason?: string;
+}
+
+/**
+ * A trigger handler: a non-empty string fires the Routine with that text.
+ * A `{ drop: true }` — or nothing at all — leaves it unfired.
+ */
 export type PluginTrigger = (
-  event: { [key: string]: unknown },
+  delivery: PluginTriggerDelivery,
   ctx: PluginContext,
-) => Promise<string | undefined | void> | string | undefined | void;
+) =>
+  | Promise<string | PluginTriggerDrop | undefined | void>
+  | string
+  | PluginTriggerDrop
+  | undefined
+  | void;
+
+/** Every trigger the module exports, by the name `plugin.json` declares. */
+export type PluginTriggers = Record<string, PluginTrigger>;
 
 /**
  * A tool call's answer. A string is handed to the Bot as it is; anything else
@@ -382,5 +408,5 @@ export interface PluginModule {
   hooks?: PluginHooks;
   /** Values other Plugins that `consume` a service of the same name receive. */
   services?: Record<string, unknown>;
-  triggers?: Record<string, PluginTrigger>;
+  triggers?: PluginTriggers;
 }

package/src/build/artifacts.ts

@@ -29,6 +29,7 @@ import { build as esbuild, type Metafile } from "esbuild";
 import type { AppletDescriptionV1 } from "../server/applet.js";
 import { readDescriptor, type AppletBuildManifestV1 } from "./manifest.js";
 import { bundlerNodePaths, SDK_ENTRIES, SDK_ROOT } from "./paths.js";
+import { withOneMoreBoot } from "./boot.js";
 import { startAppletRuntime } from "./runtime.js";
 
 export interface AppletArtifactsV1 {
@@ -160,8 +161,18 @@ function page(title: string, script: string): string {
   ].join("\n");
 }
 
-/** Ask the built module what it declares, by running it. */
-export async function readDescription(
+/**
+ * Ask the built module what it declares, by running it. A boot that never
+ * reports ready is tried once more (`boot.ts`) before the build gives up.
+ */
+export function readDescription(
+  serverCode: string,
+  appletId: string,
+): Promise<AppletDescriptionV1> {
+  return withOneMoreBoot(() => describeInRuntime(serverCode, appletId));
+}
+
+async function describeInRuntime(
   serverCode: string,
   appletId: string,
 ): Promise<AppletDescriptionV1> {

package/src/build/boot.ts

@@ -0,0 +1,46 @@
+// A workerd boot, bounded.
+//
+// Each build spawns its own workerd through Miniflare, and a spawn
+// occasionally never reports ready (a bun+workerd spawn race, roughly one
+// boot in fifty). A build that awaited `ready` unbounded would hang to the
+// test's timeout, or hang the build container's request. So a boot is given
+// a deadline, a boot that misses it is let go of rather than waited on, and
+// the caller tries once more before answering with the deadline as its
+// diagnostic.
+
+/** How long a workerd boot is given before the build gives up on it. */
+export const BOOT_DEADLINE_MS = 30_000;
+
+/** A workerd that never reported ready; the boot, not the code, failed. */
+export class RuntimeDidNotStart extends Error {}
+
+/** `ready`, or a `RuntimeDidNotStart` when it has not settled in time. */
+export async function bootedWithin<T>(ready: Promise<T>): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () =>
+        reject(
+          new RuntimeDidNotStart(
+            `The Workers runtime did not start within ${BOOT_DEADLINE_MS}ms`,
+          ),
+        ),
+      BOOT_DEADLINE_MS,
+    );
+  });
+  try {
+    return await Promise.race([ready, deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Runs `boot` again, once, when the runtime never came up the first time. */
+export async function withOneMoreBoot<T>(boot: () => Promise<T>): Promise<T> {
+  try {
+    return await boot();
+  } catch (error) {
+    if (!(error instanceof RuntimeDidNotStart)) throw error;
+    return await boot();
+  }
+}

package/src/build/plugin.ts

@@ -29,6 +29,7 @@ import { convertV4MiniflareOptions, Miniflare } from "miniflare";
 import ts from "typescript";
 
 import type { AppletDiagnostic } from "../lint/index.js";
+import { bootedWithin, withOneMoreBoot } from "./boot.js";
 import { APPLET_COMPATIBILITY_DATE } from "./runtime.js";
 import { SDK_PLUGIN_TYPES } from "./paths.js";
 
@@ -317,28 +318,15 @@ export default {
 };
 `;
 
-/** How long a workerd boot is given before the build gives up on it. */
-const BOOT_DEADLINE_MS = 30_000;
-
-/** A workerd that never reported ready; the boot, not the Plugin, failed. */
-class RuntimeDidNotStart extends Error {}
-
 /**
- * Ask the built module what it exports, by running it.
- *
- * Each build spawns its own workerd, and a spawn occasionally never reports
- * ready. A boot that misses the deadline is let go of and tried once more, so
- * a build answers rather than hanging on a runtime that never came up.
+ * Ask the built module what it exports, by running it. The boot is bounded
+ * and tried once more (`boot.ts`), so a build answers rather than hanging on
+ * a runtime that never came up.
  */
-export async function describePlugin(
+export function describePlugin(
   moduleCode: string,
 ): Promise<PluginDescriptionV1> {
-  try {
-    return await describeInWorkerd(moduleCode);
-  } catch (error) {
-    if (!(error instanceof RuntimeDidNotStart)) throw error;
-    return await describeInWorkerd(moduleCode);
-  }
+  return withOneMoreBoot(() => describeInWorkerd(moduleCode));
 }
 
 async function describeInWorkerd(
@@ -382,26 +370,6 @@ async function describeInWorkerd(
   }
 }
 
-async function bootedWithin(ready: Promise<URL>): Promise<URL> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const deadline = new Promise<never>((_, reject) => {
-    timer = setTimeout(
-      () =>
-        reject(
-          new RuntimeDidNotStart(
-            `The Workers runtime did not start within ${BOOT_DEADLINE_MS}ms`,
-          ),
-        ),
-      BOOT_DEADLINE_MS,
-    );
-  });
-  try {
-    return await Promise.race([ready, deadline]);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
 function validateDescription(input: PluginDescriptionV1): PluginDescriptionV1 {
   if (!Array.isArray(input.tools) || input.tools.length > MAX_TOOLS) {
     throw new Error(`The Plugin declares more than ${MAX_TOOLS} tools`);

package/src/build/runtime.ts

@@ -10,6 +10,8 @@
 
 import { convertV4MiniflareOptions, Miniflare } from "miniflare";
 
+import { bootedWithin } from "./boot.js";
+
 /** Pinned with the SDK: the runtime an Applet is checked against. */
 export const APPLET_COMPATIBILITY_DATE = "2026-08-27";
 
@@ -110,7 +112,14 @@ export async function startAppletRuntime(
     }),
   );
 
-  const url = await miniflare.ready;
+  let url: URL;
+  try {
+    url = await bootedWithin(miniflare.ready);
+  } catch (error) {
+    // A runtime that never started is let go of rather than waited on.
+    void miniflare.dispose().catch(() => {});
+    throw error;
+  }
   return {
     url,
     fetch: (path, init) =>