@frockbot/applet-sdk 0.7.35 → 0.7.37

package/README.md

@@ -12,14 +12,16 @@ at any point.
 
 ## Entry points
 
-| Import                          | For                                                      |
-| ------------------------------- | -------------------------------------------------------- |
-| `@frockbot/applet-sdk/server`   | `Applet`, `table`, `t` — the Applet's `server.ts`        |
-| `@frockbot/applet-sdk/client`   | `createApplet`, `mount`, `newId` — the Applet's `ui.tsx` |
-| `@frockbot/applet-sdk/kit`      | the fourteen components (`src/kit/README.md`)            |
-| `@frockbot/applet-sdk/lint`     | the flat ESLint config and the five custom rules         |
-| `@frockbot/applet-sdk/protocol` | wire protocol v1, for the kernel and for tests           |
-| `@frockbot/applet-sdk/build`    | `runAppletBuildV1` — the five stages, for the service    |
+| Import                              | For                                                                  |
+| ----------------------------------- | -------------------------------------------------------------------- |
+| `@frockbot/applet-sdk/server`       | `Applet`, `table`, `t` — the Applet's `server.ts`                    |
+| `@frockbot/applet-sdk/client`       | `createApplet`, `mount`, `newId` — the Applet's `ui.tsx`             |
+| `@frockbot/applet-sdk/kit`          | the fourteen components (`src/kit/README.md`)                        |
+| `@frockbot/applet-sdk/lint`         | the flat ESLint config and the five custom rules                     |
+| `@frockbot/applet-sdk/protocol`     | wire protocol v1, for the kernel and for tests                       |
+| `@frockbot/applet-sdk/build`        | `runAppletBuildV1` — the five stages, for the service                |
+| `@frockbot/applet-sdk/plugin`       | types only: `PluginModule`, `PluginContext` — a Plugin's `plugin.ts` |
+| `@frockbot/applet-sdk/build/plugin` | `runPluginBuildV1` — the four Plugin stages, for the service         |
 
 ## The build
 
@@ -38,6 +40,21 @@ with the code.
 `scripts/build-applets-assets.ts` turns it into `applets/template.generated.ts`,
 which `applet_create` writes through the Workspace.
 
+## Plugins
+
+A Plugin (ADR 0026) is written against `@frockbot/applet-sdk/plugin`, which
+is declarations only: `plugin.ts` exports `tools` and `execute`, and may
+export `hooks`, `services` and `triggers`, beside a `plugin.json` descriptor.
+`tools` may be empty — a Plugin that only serves hooks is admissible, because
+the kernel's own descriptor contract admits one.
+`runPluginBuildV1(directory, { mode, id })` is four stages — `descriptor`,
+`typecheck`, `bundle`, `describe` — with no lint stage, because a Plugin's
+reach is a grant the descriptor declares and the kernel enforces. The bundle
+is one ESM module with every import inlined, and the manifest is read by
+running that module in Miniflare with no outbound network. `plugin/template/`
+is the scaffold a new Plugin starts as. `PluginContext` is held to the
+kernel's own `ctx` keys by `app/plugins/sdk-types.test.ts`.
+
 ## What runs where
 
 `server.ts` becomes a single ESM file whose only import is `cloudflare:workers`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.7.35",
+  "version": "0.7.37",
   "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.",
@@ -12,12 +12,15 @@
     "./lint": "./src/lint/index.ts",
     "./protocol": "./src/protocol/index.ts",
     "./build": "./src/build/pipeline.ts",
+    "./build/plugin": "./src/build/plugin.ts",
+    "./plugin": "./plugin/index.d.ts",
     "./package.json": "./package.json"
   },
   "files": [
     "src",
     "types",
     "template",
+    "plugin",
     "README.md"
   ],
   "scripts": {

package/plugin/index.d.ts

@@ -0,0 +1,386 @@
+/**
+ * `@frockbot/applet-sdk/plugin` — what a Plugin's `plugin.ts` is written
+ * against (ADR 0026).
+ *
+ * A Plugin is one ESM module with no imports of its own. It exports `tools`
+ * and `execute`, and may export `hooks`, `services` and `triggers`. The
+ * kernel's generated index imports the built module, checks these exports
+ * against the Plugin's `plugin.json` once at mount, and hands every call a
+ * narrow `ctx` naming only what that Plugin declared it may do.
+ *
+ * These declarations are types only. They mirror `core/contracts/isolate.ts`
+ * member for member — `BOT_ISOLATE_CONTEXT_KEYS_V1` is the list this file's
+ * `PluginContext` is tested against — so a Plugin that type-checks here sees
+ * the `ctx` the wrapper actually builds.
+ */
+
+/** A JSON Schema object, as a tool's `inputSchema`. */
+export type JsonSchema = { [key: string]: unknown };
+
+/** The loop events a Plugin may hook, in the order the loop raises them. */
+export type PluginHookEvent =
+  | "system-prompt/assemble"
+  | "agent/tool-exposure"
+  | "agent/request"
+  | "tools/pre-execute"
+  | "tools/post-execute"
+  | "agent/turn-stopping";
+
+/**
+ * The grants a Plugin may declare in `plugin.json`, in the kernel's order.
+ * `storage`, `http`, `schedule`, `ai`, `memory` and `workspace` each open one
+ * member of `ctx`; `files` and `computer` are declared to the authority and
+ * open nothing here.
+ */
+export type PluginGrant =
+  | "storage"
+  | "http"
+  | "schedule"
+  | "ai"
+  | "files"
+  | "memory"
+  | "workspace"
+  | "computer";
+
+/** One tool the Plugin offers the Bot. Its name must be in `plugin.json` too. */
+export interface PluginTool {
+  /** `^[a-z][a-z0-9_]{0,63}$`, unique within the Plugin. */
+  name: string;
+  description: string;
+  inputSchema: JsonSchema;
+  /** True when a retry under the same input is harmless. Default false. */
+  idempotent?: boolean;
+  /**
+   * Which Turn types may call it. Absent means every Turn type. Subagent
+   * roles narrow it further.
+   */
+  admission?: { turnTypes: string[]; subagentRoles?: string[] };
+}
+
+/** A capability call the authority could not serve. Never an exception. */
+export interface CapabilityFailure {
+  status: "unavailable";
+  reason: string;
+}
+
+export interface StorageEntry {
+  key: string;
+  value: unknown;
+}
+
+/**
+ * The `storage` grant: a key-value store scoped to this Plugin and this Bot.
+ * Keys are `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`; a value serializes to at
+ * most 64 KiB.
+ */
+export interface PluginStorage {
+  get(request: {
+    key: string;
+  }): Promise<{ status: "available"; value: unknown } | CapabilityFailure>;
+  put(request: {
+    key: string;
+    value: unknown;
+  }): Promise<{ status: "available"; value: unknown } | CapabilityFailure>;
+  delete(request: {
+    key: string;
+  }): Promise<{ status: "available"; value: unknown } | CapabilityFailure>;
+  list(request: {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+  }): Promise<
+    | { status: "available"; entries: StorageEntry[]; cursor?: string }
+    | CapabilityFailure
+  >;
+}
+
+/** This Plugin's settings values for this Bot, as the User set them. */
+export interface PluginSettings {
+  read(): Promise<
+    { status: "available"; values: Record<string, unknown> } | CapabilityFailure
+  >;
+}
+
+/** One Connection the Bot holds, as `capabilities.list()` names it. */
+export interface ConnectionSummary {
+  connectionId: string;
+  packageId: string;
+  connectionTypeId: string;
+  displayName: string;
+  generation: string;
+  safeMetadata: Record<string, unknown>;
+}
+
+/** The Bot's configured model, as `capabilities.list()` names it. */
+export interface ModelBindingSummary {
+  connectionId: string;
+  packageId: string;
+  provider: string;
+  providerModelId: string;
+  connectionGeneration: string;
+  catalogGeneration?: string;
+}
+
+/** What the Bot holds right now. Nothing here widens what the Plugin may do. */
+export interface CapabilityList {
+  status: "available";
+  connections: ConnectionSummary[];
+  model?: ModelBindingSummary;
+  memory: boolean;
+  workspace: boolean;
+  schedule: true;
+}
+
+/** An opaque, short-lived reference to a Connection — never its credential. */
+export interface ConnectionLease {
+  status: "available";
+  leaseId: string;
+  connectionId: string;
+  generation: string;
+  expiresAt: string;
+}
+
+/** One streamed model event. `text-delta` carries the text a reply grows by. */
+export type ModelStreamEvent =
+  | { type: "text-delta"; text: string }
+  | { type: string; [key: string]: unknown };
+
+/** The `ai` grant: the Bot's own configured model, never another. */
+export interface PluginModel {
+  invoke(request: { [key: string]: unknown }): Promise<
+    | {
+        status: "streaming";
+        requestId: string;
+        events: AsyncIterable<ModelStreamEvent>;
+      }
+    | CapabilityFailure
+  >;
+}
+
+export type MemoryScope = "bot" | "user" | "project";
+export type MemoryTier = "profile" | "log" | "note";
+
+/** The `memory` grant. */
+export interface PluginMemory {
+  read(request: {
+    scope: MemoryScope;
+    projectId?: string;
+  }): Promise<{ status: "available"; value: unknown } | CapabilityFailure>;
+  write(request: {
+    scope: MemoryScope;
+    projectId?: string;
+    tier?: MemoryTier;
+    fact: string;
+  }): Promise<{ status: "available"; value: unknown } | CapabilityFailure>;
+  forget(request: {
+    scope: MemoryScope;
+    projectId?: string;
+    tier?: MemoryTier;
+    fact: string;
+  }): Promise<{ status: "available"; value: unknown } | CapabilityFailure>;
+}
+
+/** A Workspace root without a User id; the authority supplies its own. */
+export type WorkspaceRoot =
+  | { kind: "bot-instructions"; botId: string }
+  | { kind: "user-instructions" }
+  | { kind: "package-declared"; packageId: string; rootId: string };
+
+export interface WorkspacePath {
+  root: WorkspaceRoot;
+  path: string;
+}
+
+export type WorkspaceOutcome =
+  { status: "available"; value: unknown } | CapabilityFailure;
+
+/** The `workspace` grant. */
+export interface PluginWorkspace {
+  read(path: WorkspacePath): Promise<WorkspaceOutcome>;
+  list(request: {
+    root: WorkspaceRoot;
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+  }): Promise<WorkspaceOutcome>;
+  stat(path: WorkspacePath): Promise<WorkspaceOutcome>;
+  write(request: {
+    path: WorkspacePath;
+    bytes: Uint8Array;
+    expectedGenerationId: string | null;
+    mediaType?: string;
+  }): Promise<WorkspaceOutcome>;
+  delete(request: {
+    path: WorkspacePath;
+    expectedGenerationId: string;
+  }): Promise<WorkspaceOutcome>;
+}
+
+/**
+ * The `ctx` every tool call and hook receives.
+ *
+ * Three context keys — `user`, `bot`, `session` — and one member per grant
+ * the Plugin declared. A grant the Plugin did not ask for is absent from
+ * `ctx` entirely, which is why every grant member is optional here.
+ */
+export interface PluginContext {
+  /** The tool being executed; absent inside a hook. */
+  readonly tool?: string;
+  /** The hook event being raised; absent inside a tool call. */
+  readonly event?: PluginHookEvent;
+  readonly user: { readonly userId: string };
+  readonly bot: { readonly botId: string };
+  readonly session: {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turnId: string;
+    readonly generationId: string;
+  };
+  /** This Plugin's id. */
+  readonly packageId: string;
+  /** How long this call may run, in milliseconds. */
+  readonly deadlineMs: number;
+  /** The names of the bindings the worker was given. */
+  readonly bindings: string[];
+  readonly capabilities: {
+    list(): Promise<CapabilityList | CapabilityFailure>;
+  };
+  /**
+   * The services other Plugins in the worker provide and this Plugin declared
+   * it consumes, by service name. Empty for a Plugin that consumes nothing.
+   */
+  readonly services: Record<string, unknown>;
+  readonly settings: PluginSettings;
+  /** The `ai` grant. */
+  readonly model?: PluginModel;
+  /** The `memory` grant. */
+  readonly memory?: PluginMemory;
+  /** The `workspace` grant. */
+  readonly workspace?: PluginWorkspace;
+  /** The `http` grant: a named Connection, credential attached server-side. */
+  readonly connection?: (
+    connectionId: string,
+  ) => Promise<ConnectionLease | CapabilityFailure>;
+  /** The `schedule` grant: a durable Routine operation attributed to this call. */
+  readonly schedule?: (request: {
+    callId: string;
+    input: unknown;
+  }) => Promise<
+    | { status: "completed"; content: string; isError: boolean }
+    | CapabilityFailure
+  >;
+  /** The `storage` grant. */
+  readonly storage?: PluginStorage;
+}
+
+/** `ctx` inside `execute`: the tool is named, no event is. */
+export interface PluginExecutionContext extends PluginContext {
+  readonly tool: string;
+  readonly event?: never;
+}
+
+/** `ctx` inside a hook: the event is named, no tool is. */
+export interface PluginHookContext extends PluginContext {
+  readonly tool?: never;
+  readonly event: PluginHookEvent;
+}
+
+/** One step of the loop, as a hook payload carries it. */
+export interface StepSnapshot {
+  step: number;
+  [key: string]: unknown;
+}
+
+/** One tool as the model is offered it. */
+export interface ToolSchema {
+  name: string;
+  description: string;
+  inputSchema: JsonSchema;
+  [key: string]: unknown;
+}
+
+/**
+ * What each hook receives, and the one value it may replace. A hook returns
+ * `undefined` to leave the value alone, or the replacement — the *whole*
+ * value, not a patch. A later Plugin sees an earlier Plugin's replacement.
+ * `agent/turn-stopping` is a notification: its return is ignored.
+ */
+export interface PluginHookPayloads {
+  "system-prompt/assemble": {
+    context: { [key: string]: unknown };
+    assembly: { [key: string]: unknown };
+  };
+  "agent/tool-exposure": { step: StepSnapshot; tools: ToolSchema[] };
+  "agent/request": { step: StepSnapshot; request: { [key: string]: unknown } };
+  "tools/pre-execute": {
+    call: { [key: string]: unknown };
+    context: { [key: string]: unknown };
+    preparation: { [key: string]: unknown };
+  };
+  "tools/post-execute": {
+    call: { [key: string]: unknown };
+    context: { [key: string]: unknown };
+    result: { [key: string]: unknown };
+  };
+  "agent/turn-stopping": { agent: { [key: string]: unknown }; turn: number };
+}
+
+export interface PluginHookReplacements {
+  "system-prompt/assemble": PluginHookPayloads["system-prompt/assemble"]["assembly"];
+  "agent/tool-exposure": ToolSchema[];
+  "agent/request": PluginHookPayloads["agent/request"]["request"];
+  "tools/pre-execute": PluginHookPayloads["tools/pre-execute"]["preparation"];
+  "tools/post-execute": PluginHookPayloads["tools/post-execute"]["result"];
+  "agent/turn-stopping": never;
+}
+
+export type PluginHook<Event extends PluginHookEvent> = (
+  payload: PluginHookPayloads[Event],
+  ctx: PluginHookContext,
+) =>
+  | Promise<PluginHookReplacements[Event] | undefined | void>
+  | PluginHookReplacements[Event]
+  | undefined
+  | void;
+
+export type PluginHooks = {
+  [Event in PluginHookEvent]?: PluginHook<Event>;
+};
+
+/** A trigger handler: what it returns, when non-empty, is what the Bot reads. */
+export type PluginTrigger = (
+  event: { [key: string]: unknown },
+  ctx: PluginContext,
+) => Promise<string | undefined | void> | string | undefined | void;
+
+/**
+ * A tool call's answer. A string is handed to the Bot as it is; anything else
+ * is JSON-serialized. Throw to answer with an error the Bot can read — the
+ * wrapper turns a thrown `Error` into an error result with its message.
+ */
+export type ToolResult = string | unknown;
+
+/**
+ * The module shape `plugin.ts` must satisfy. There is no default export —
+ * export each member by name:
+ *
+ * ```ts
+ * export const tools: PluginTool[] = [...];
+ * export const execute: PluginExecute = async (tool, input, ctx) => {...};
+ * export const hooks: PluginHooks = {...};
+ * ```
+ */
+export type PluginExecute = (
+  tool: string,
+  input: unknown,
+  ctx: PluginExecutionContext,
+) => Promise<ToolResult> | ToolResult;
+
+export interface PluginModule {
+  tools: PluginTool[];
+  execute: PluginExecute;
+  hooks?: PluginHooks;
+  /** Values other Plugins that `consume` a service of the same name receive. */
+  services?: Record<string, unknown>;
+  triggers?: Record<string, PluginTrigger>;
+}

package/plugin/template/plugin.json

@@ -0,0 +1,25 @@
+{
+  "id": "__PLUGIN_ID__",
+  "displayName": "__PLUGIN_NAME__",
+  "version": "1",
+  "contractVersion": 4,
+  "tools": [
+    {
+      "name": "note_count",
+      "description": "How many notes this Plugin has kept for this Bot.",
+      "inputSchema": { "type": "object", "properties": {} }
+    },
+    {
+      "name": "note_add",
+      "description": "Keep one short note for this Bot.",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "text": { "type": "string" } },
+        "required": ["text"]
+      }
+    }
+  ],
+  "hooks": [],
+  "grants": ["storage"],
+  "contextKeys": ["user", "bot", "session"]
+}

package/plugin/template/plugin.ts

@@ -0,0 +1,64 @@
+import type { PluginExecute, PluginTool } from "@frockbot/applet-sdk/plugin";
+
+/**
+ * __PLUGIN_NAME__: a starting point that already builds.
+ *
+ * Every tool here is also named in `plugin.json`, and the `storage` grant the
+ * descriptor declares is what makes `ctx.storage` exist. Change both files
+ * together: a tool the module exports but the descriptor omits, or the other
+ * way round, is refused at publish.
+ */
+export const tools: PluginTool[] = [
+  {
+    name: "note_count",
+    description: "How many notes this Plugin has kept for this Bot.",
+    inputSchema: { type: "object", properties: {} },
+    idempotent: true,
+  },
+  {
+    name: "note_add",
+    description: "Keep one short note for this Bot.",
+    inputSchema: {
+      type: "object",
+      properties: { text: { type: "string" } },
+      required: ["text"],
+    },
+  },
+];
+
+interface Notes {
+  entries: string[];
+}
+
+async function readNotes(
+  storage: NonNullable<Parameters<PluginExecute>[2]["storage"]>,
+): Promise<Notes> {
+  const outcome = await storage.get({ key: "notes" });
+  if (outcome.status !== "available" || !outcome.value) return { entries: [] };
+  return outcome.value as Notes;
+}
+
+/**
+ * A string answer goes to the Bot as it is. Throwing answers with an error
+ * the Bot can read, so a refusal is a thrown `Error`, never a quiet string.
+ */
+export const execute: PluginExecute = async (tool, input, ctx) => {
+  const storage = ctx.storage;
+  if (!storage) throw new Error("the storage grant is not open");
+  switch (tool) {
+    case "note_count": {
+      const notes = await readNotes(storage);
+      return `${notes.entries.length} note(s).`;
+    }
+    case "note_add": {
+      const text = String((input as { text?: unknown } | null)?.text ?? "");
+      if (text.length === 0) throw new Error("text is required");
+      const notes = await readNotes(storage);
+      notes.entries.push(text);
+      await storage.put({ key: "notes", value: notes });
+      return `Kept it. ${notes.entries.length} note(s) now.`;
+    }
+    default:
+      throw new Error(`unknown tool ${tool}`);
+  }
+};

package/src/build/paths.ts

@@ -60,6 +60,9 @@ export const SDK_WORKERS_TYPES = join(
   "types/cloudflare-workers.d.ts",
 );
 
+/** The Plugin declarations (`@frockbot/applet-sdk/plugin`), types only. */
+export const SDK_PLUGIN_TYPES = join(SDK_ROOT, "plugin/index.d.ts");
+
 function packageDirectory(specifier: string): string {
   return dirname(require.resolve(`${specifier}/package.json`));
 }

package/src/build/plugin.ts

@@ -0,0 +1,494 @@
+/**
+ * The Plugin build (ADR 0026): four named stages over one directory, sharing
+ * the Applet build's type checker, bundler and Miniflare boot.
+ *
+ *  1. `descriptor` — `plugin.json` parses and names the Plugin the caller
+ *     asked for. Nothing more is decided here: the app Worker holds the full
+ *     descriptor decoder and compares the manifest with it before it stores
+ *     anything.
+ *  2. `typecheck` — `plugin.ts` and its siblings against
+ *     `@frockbot/applet-sdk/plugin`, strict.
+ *  3. `bundle` — one ESM module. No import survives: the module is loaded by
+ *     a Worker with no bindings but the kernel's loopback, so a specifier the
+ *     bundler could not inline is a build failure, not a mount surprise.
+ *  4. `describe` — the bundle runs in Miniflare, with no outbound network,
+ *     and reports what it exports. That is the manifest: the truth about the
+ *     module, read by running it, exactly as the kernel's index will.
+ *
+ * `check` stops after the type checker. There is no lint stage: a Plugin's
+ * network access is a grant the descriptor declares and the kernel enforces
+ * at the egress, not a rule a linter could state.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { join, relative, resolve } from "node:path";
+
+import { build as esbuild } from "esbuild";
+import { convertV4MiniflareOptions, Miniflare } from "miniflare";
+import ts from "typescript";
+
+import type { AppletDiagnostic } from "../lint/index.js";
+import { APPLET_COMPATIBILITY_DATE } from "./runtime.js";
+import { SDK_PLUGIN_TYPES } from "./paths.js";
+
+export type PluginBuildStage =
+  "descriptor" | "typecheck" | "bundle" | "describe";
+
+/** The Plugin's `plugin.json`, as far as the build reads it. */
+export interface PluginBuildDescriptorV1 {
+  id: string;
+}
+
+/** What the built module exports, read by running it. */
+export interface PluginDescriptionV1 {
+  tools: {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+  }[];
+  hooks: string[];
+  services: string[];
+  triggers: string[];
+}
+
+export interface PluginBuildManifestV1 extends PluginDescriptionV1 {
+  contract: 1;
+  hashes: { module: string };
+}
+
+export type PluginBuildOutcome =
+  | { status: "checked" }
+  | { status: "built"; manifest: PluginBuildManifestV1; module: string }
+  | {
+      status: "failed";
+      stage: PluginBuildStage;
+      diagnostics: AppletDiagnostic[];
+    };
+
+const PLUGIN_ID = /^[a-z][a-z0-9-]{0,63}$/;
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+const MAX_TOOLS = 64;
+
+const COMPILER_OPTIONS: ts.CompilerOptions = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  strict: true,
+  noEmit: true,
+  skipLibCheck: true,
+  esModuleInterop: true,
+  forceConsistentCasingInFileNames: true,
+  // ES2022 for the language; the DOM lib for `fetch`, `Request` and
+  // `Response`, which the Workers runtime provides under the same names.
+  lib: ["lib.es2022.d.ts", "lib.dom.d.ts", "lib.dom.iterable.d.ts"],
+  types: [],
+};
+
+function thrown(error: unknown, file = "plugin.json"): AppletDiagnostic[] {
+  return [
+    {
+      file,
+      line: 1,
+      column: 1,
+      message: error instanceof Error ? error.message : String(error),
+      severity: "error",
+    },
+  ];
+}
+
+function sha256(text: string): string {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+export async function readPluginDescriptor(
+  directory: string,
+): Promise<PluginBuildDescriptorV1> {
+  let text: string;
+  try {
+    text = await readFile(join(directory, "plugin.json"), "utf8");
+  } catch {
+    throw new Error(`No plugin.json in the Plugin's source`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(
+      `plugin.json is not JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("plugin.json must be an object");
+  }
+  const id = (parsed as { id?: unknown }).id;
+  if (typeof id !== "string" || !PLUGIN_ID.test(id)) {
+    throw new Error('plugin.json "id" must match /^[a-z][a-z0-9-]{0,63}$/');
+  }
+  return { id };
+}
+
+async function pluginSources(directory: string): Promise<string[]> {
+  const found: string[] = [];
+  const walk = async (current: string): Promise<void> => {
+    for (const entry of await readdir(current, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (/\.ts$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+        found.push(path);
+      }
+    }
+  };
+  await walk(directory);
+  return found;
+}
+
+/** Type-check the Plugin against the SDK's Plugin declarations. */
+export async function typeCheckPlugin(
+  directory: string,
+): Promise<AppletDiagnostic[]> {
+  const root = resolve(directory);
+  const files = await pluginSources(root);
+  if (!files.some((file) => relative(root, file) === "plugin.ts")) {
+    return [
+      {
+        file: "plugin.ts",
+        line: 1,
+        column: 1,
+        message: "No plugin.ts found; a Plugin's module is plugin.ts.",
+        severity: "error",
+      },
+    ];
+  }
+  const program = ts.createProgram(files, {
+    ...COMPILER_OPTIONS,
+    paths: { "@frockbot/applet-sdk/plugin": [SDK_PLUGIN_TYPES] },
+  });
+  return ts
+    .getPreEmitDiagnostics(program)
+    .filter(
+      (diagnostic) =>
+        !diagnostic.file || diagnostic.file.fileName.startsWith(root),
+    )
+    .map((diagnostic) => {
+      const message = ts.flattenDiagnosticMessageText(
+        diagnostic.messageText,
+        " ",
+      );
+      if (!diagnostic.file || diagnostic.start === undefined) {
+        return {
+          file: "plugin.ts",
+          line: 1,
+          column: 1,
+          message,
+          severity: "error" as const,
+        };
+      }
+      const position = diagnostic.file.getLineAndCharacterOfPosition(
+        diagnostic.start,
+      );
+      return {
+        file: relative(root, diagnostic.file.fileName),
+        line: position.line + 1,
+        column: position.character + 1,
+        message: `${message} (TS${diagnostic.code})`,
+        severity:
+          diagnostic.category === ts.DiagnosticCategory.Error
+            ? ("error" as const)
+            : ("warning" as const),
+      };
+    });
+}
+
+/**
+ * One ESM module, every import inlined. `@frockbot/applet-sdk/plugin` is
+ * types only, so a value import of it is the one specifier that can never
+ * resolve — the message says so rather than reporting a missing package.
+ */
+export async function bundlePlugin(directory: string): Promise<string> {
+  const result = await esbuild({
+    entryPoints: [join(directory, "plugin.ts")],
+    bundle: true,
+    write: false,
+    format: "esm",
+    platform: "neutral",
+    target: "es2022",
+    minify: false,
+    legalComments: "none",
+    external: [],
+    plugins: [
+      {
+        name: "plugin-sdk-is-types-only",
+        setup(build) {
+          build.onResolve(
+            { filter: /^@frockbot\/applet-sdk\/plugin$/ },
+            () => ({
+              errors: [
+                {
+                  text: '"@frockbot/applet-sdk/plugin" is types only; import it with `import type`.',
+                },
+              ],
+            }),
+          );
+        },
+      },
+    ],
+    define: { "process.env.NODE_ENV": '"production"' },
+    logLevel: "silent",
+  });
+  const file = result.outputFiles?.[0];
+  if (!file) throw new Error("The bundler produced no output");
+  // The bundle's module comments carry the temp directory; keep the artifact a
+  // function of the source alone, as the Applet build does.
+  return file.text
+    .split("\n")
+    .map((line) =>
+      line.startsWith("// ") && line.includes(directory)
+        ? `// ${relative(directory, line.slice(3))}`
+        : line,
+    )
+    .join("\n");
+}
+
+/**
+ * The describing Worker. It imports the built module and answers `/describe`
+ * with what the module exports, in the shape the manifest carries. Anything
+ * the module does at import time runs here, inside workerd, with no outbound
+ * network and no bindings — never in this process.
+ */
+const DESCRIBE_WORKER = `
+import * as plugin from "./plugin.js";
+
+var TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+
+function names(value, label) {
+  if (value === undefined) return [];
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error('"' + label + '" must be an object');
+  }
+  return Object.keys(value).map(function (name) {
+    if (typeof value[name] !== "function" && label !== "services") {
+      throw new Error('"' + label + '"."' + name + '" must be a function');
+    }
+    return name;
+  });
+}
+
+function describe() {
+  if (!Array.isArray(plugin.tools)) {
+    throw new Error('the module must export a "tools" array');
+  }
+  if (typeof plugin.execute !== "function") {
+    throw new Error('the module must export an "execute" function');
+  }
+  var tools = plugin.tools.map(function (tool) {
+    if (!tool || typeof tool.name !== "string" || !TOOL_NAME.test(tool.name)) {
+      throw new Error("a tool has an invalid name");
+    }
+    if (typeof tool.description !== "string" || tool.description.length === 0) {
+      throw new Error('tool "' + tool.name + '" needs a description');
+    }
+    var schema =
+      tool.inputSchema && typeof tool.inputSchema === "object" && !Array.isArray(tool.inputSchema)
+        ? tool.inputSchema
+        : { type: "object" };
+    return { name: tool.name, description: tool.description, inputSchema: schema };
+  });
+  return {
+    tools: tools,
+    hooks: names(plugin.hooks, "hooks"),
+    services: names(plugin.services, "services"),
+    triggers: names(plugin.triggers, "triggers"),
+  };
+}
+
+export default {
+  async fetch(request) {
+    try {
+      return Response.json({ ok: true, description: describe() });
+    } catch (error) {
+      return Response.json(
+        { ok: false, error: String((error && error.message) || error) },
+        { status: 500 },
+      );
+    }
+  },
+};
+`;
+
+/** 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.
+ */
+export async function describePlugin(
+  moduleCode: string,
+): Promise<PluginDescriptionV1> {
+  try {
+    return await describeInWorkerd(moduleCode);
+  } catch (error) {
+    if (!(error instanceof RuntimeDidNotStart)) throw error;
+    return await describeInWorkerd(moduleCode);
+  }
+}
+
+async function describeInWorkerd(
+  moduleCode: string,
+): Promise<PluginDescriptionV1> {
+  const miniflare = new Miniflare(
+    convertV4MiniflareOptions({
+      modules: [
+        { type: "ESModule", path: "/index.mjs", contents: DESCRIBE_WORKER },
+        { type: "ESModule", path: "/plugin.js", contents: moduleCode },
+      ],
+      modulesRoot: "/",
+      compatibilityDate: APPLET_COMPATIBILITY_DATE,
+      // Import-time code runs with no way out: every fetch is answered here.
+      outboundService: async () =>
+        new Response("the build describes a Plugin without a network", {
+          status: 403,
+        }),
+      host: "127.0.0.1",
+      port: 0,
+    }),
+  );
+  let started = false;
+  try {
+    const url = await bootedWithin(miniflare.ready);
+    started = true;
+    const response = (await miniflare.dispatchFetch(
+      new URL(`/describe?${randomUUID()}`, url).toString(),
+    )) as unknown as Response;
+    const body = (await response.json()) as
+      | { ok: true; description: PluginDescriptionV1 }
+      | { ok: false; error: string };
+    if (!body.ok) {
+      throw new Error(`The Plugin could not describe itself: ${body.error}`);
+    }
+    return validateDescription(body.description);
+  } finally {
+    // A runtime that never started is let go of rather than waited on.
+    if (started) await miniflare.dispose();
+    else void miniflare.dispose().catch(() => {});
+  }
+}
+
+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`);
+  }
+  const seen = new Set<string>();
+  for (const tool of input.tools) {
+    if (seen.has(tool.name)) {
+      throw new Error(`The Plugin declares "${tool.name}" twice`);
+    }
+    seen.add(tool.name);
+  }
+  return {
+    tools: input.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: JSON.parse(JSON.stringify(tool.inputSchema)) as Record<
+        string,
+        unknown
+      >,
+    })),
+    hooks: [...input.hooks],
+    services: [...input.services],
+    triggers: [...input.triggers],
+  };
+}
+
+export interface PluginBuildPipelineOptions {
+  /** `check` stops after the type checker; `build` goes on to the module. */
+  mode: "check" | "build";
+  /** The id the caller asked for; `plugin.json` must agree. */
+  id?: string;
+}
+
+export async function runPluginBuildV1(
+  directory: string,
+  options: PluginBuildPipelineOptions,
+): Promise<PluginBuildOutcome> {
+  let descriptor: PluginBuildDescriptorV1;
+  try {
+    descriptor = await readPluginDescriptor(directory);
+    if (options.id !== undefined && descriptor.id !== options.id) {
+      throw new Error(
+        `plugin.json names "${descriptor.id}" but this build is for "${options.id}"`,
+      );
+    }
+  } catch (error) {
+    return {
+      status: "failed",
+      stage: "descriptor",
+      diagnostics: thrown(error),
+    };
+  }
+
+  const types = await typeCheckPlugin(directory);
+  if (types.some((diagnostic) => diagnostic.severity === "error")) {
+    return { status: "failed", stage: "typecheck", diagnostics: types };
+  }
+  if (options.mode === "check") return { status: "checked" };
+
+  let moduleCode: string;
+  try {
+    moduleCode = await bundlePlugin(directory);
+  } catch (error) {
+    return {
+      status: "failed",
+      stage: "bundle",
+      diagnostics: thrown(error, "plugin.ts"),
+    };
+  }
+
+  let description: PluginDescriptionV1;
+  try {
+    description = await describePlugin(moduleCode);
+  } catch (error) {
+    return {
+      status: "failed",
+      stage: "describe",
+      diagnostics: thrown(error, "plugin.ts"),
+    };
+  }
+  return {
+    status: "built",
+    manifest: {
+      contract: 1,
+      ...description,
+      hashes: { module: sha256(moduleCode) },
+    },
+    module: moduleCode,
+  };
+}