npm - @frockbot/plugin-authoring - Versions diffs - 0.1.4 → 0.2.0 - Mend

@frockbot/plugin-authoring 0.1.4 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-authoring",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -21,7 +21,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-contracts": "0.1.4",
+    "@frockbot/kernel-contracts": "0.2.0",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/agent.test.ts CHANGED Viewed

@@ -3,16 +3,18 @@ import { SessionStore, type Session } from "@frockbot/kernel-contracts";
 import { Context } from "cordis";
 import {
   createPackageAuthorTool,
+  createPackageInspectSelfTool,
+  createPackageUndoTool,
   openTurnPositionV1,
   type AuthorPackageRequestV1,
   type PackageAuthoringHost,
 } from "./agent.ts";
-import type { AuthorPackageOutcomeV1 } from "./shared.ts";
+import { sha256HexV1, type AuthorPackageOutcomeV1 } from "./shared.ts";
 const INPUT = {
   packageId: "weather-lookup",
   displayName: "Weather lookup",
-  tool: { name: "weather_lookup", description: "Looks up", inputSchema: {} },
+  tools: [{ name: "weather_lookup", description: "Looks up", inputSchema: {} }],
   source: "export const tools = [];\nexport async function execute() {}\n",
 };
@@ -55,6 +57,24 @@ function stubHost(
       seen.push(request);
       return Promise.resolve(outcome);
     },
+    undoEffectIdFor: () => Promise.resolve("undo-0123456789abcdef"),
+    undo: () =>
+      Promise.resolve({
+        status: "recorded",
+        effectId: "undo-0123456789abcdef",
+        generationId: "revert-generation",
+        targetGenerationId: "target-generation",
+      }),
+    inspectSelf: () =>
+      Promise.resolve({
+        contextContract: "interface BotPackageExecutionContextV1 {}",
+        composition: {
+          generationId: "current-generation",
+          status: "active",
+          members: [],
+        },
+        failures: [],
+      }),
   };
 }
@@ -95,6 +115,47 @@ describe("the package_author tool", () => {
     await dispose();
   });
+  test("includes the UI HTML hash and declared hooks in the effect identity", async () => {
+    const { sessions, dispose } = await openSession();
+    const effectInputs: Parameters<PackageAuthoringHost["effectIdFor"]>[0][] =
+      [];
+    const host = stubHost({
+      status: "authored",
+      packageId: "weather-lookup",
+      version: "0.0.1",
+      contentHash: "b".repeat(64),
+      generationId: "2026-08-31T01:00:00.000Z:fedcba9876543210",
+    });
+    host.effectIdFor = (input) => {
+      effectInputs.push(input);
+      return Promise.resolve("author-0123456789abcdef");
+    };
+    const tool = createPackageAuthorTool(host, sessions);
+    const html = "<!doctype html><h1>Weather</h1>";
+    await tool.execute(
+      {
+        ...INPUT,
+        hooks: ["agent/tool-exposure"],
+        ui: {
+          html,
+          mounts: [{ slot: "frockbot.tool-result:weather_lookup" }],
+        },
+      },
+      CONTEXT,
+    );
+    expect(effectInputs).toEqual([
+      {
+        packageId: "weather-lookup",
+        sourceHash: await sha256HexV1(INPUT.source),
+        uiHtmlHash: await sha256HexV1(html),
+        hooks: ["agent/tool-exposure"],
+      },
+    ]);
+    await dispose();
+  });
   test("a refusal leaves the intent recorded and no authored event", async () => {
     const { session, sessions, dispose } = await openSession();
     const tool = createPackageAuthorTool(
@@ -160,3 +221,41 @@ describe("the package_author tool", () => {
     await root.fiber.dispose();
   });
 });
+describe("the Package setup companion tools", () => {
+  test("package_undo records intent before the durable revert outcome", async () => {
+    const { session, sessions, dispose } = await openSession();
+    const host = stubHost({
+      status: "refused",
+      reason: "unused",
+      failureId: "unused",
+    });
+    const tool = createPackageUndoTool(host, sessions);
+    const result = await tool.execute({}, CONTEXT);
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("activates on the next Turn");
+    expect(result.content).toContain("did not undo any action");
+    expect(session.events.slice(-2).map((event) => event.type)).toEqual([
+      "package/undo-intent",
+      "package/undo-recorded",
+    ]);
+    await dispose();
+  });
+  test("package_inspect_self returns the host's generated catalog read-only", async () => {
+    const host = stubHost({
+      status: "refused",
+      reason: "unused",
+      failureId: "unused",
+    });
+    const tool = createPackageInspectSelfTool(host);
+    const result = await tool.execute({}, CONTEXT);
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("BotPackageExecutionContextV1");
+    expect(tool.idempotent).toBe(true);
+  });
+});

package/src/agent.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-// The Package Authoring runtime Contribution: one tool, `package_author`.
+// The Package Authoring runtime Contribution: author, undo, and self-inspect.
 //
 // The Package holds no authority of its own. It decodes the model's input at
 // the seam, appends the two session events that make the effect visible in the
@@ -10,12 +10,18 @@ import type {
   ToolDefinition,
   ToolExecutionContext,
 } from "@frockbot/kernel-contracts";
+import { BOT_ISOLATE_CONTEXT_SUMMARY_V1 } from "@frockbot/kernel-contracts";
 import type { Plugin } from "cordis";
 import {
   AUTHOR_PACKAGE_INPUT_SCHEMA_V1,
+  PACKAGE_UNDO_INPUT_SCHEMA_V1,
   type AuthorPackageInputV1,
   type AuthorPackageOutcomeV1,
+  type PackageInspectSelfOutcomeV1,
+  type PackageUndoInputV1,
+  type PackageUndoOutcomeV1,
   decodeAuthorPackageInputV1,
+  decodePackageUndoInputV1,
   sha256HexV1,
 } from "./shared.js";
@@ -33,6 +39,13 @@ export interface AuthorPackageRequestV1 {
   position: AuthoringTurnPositionV1;
 }
+export interface PackageUndoRequestV1 {
+  input: PackageUndoInputV1;
+  effectId: string;
+  sessionId: string;
+  position: AuthoringTurnPositionV1;
+}
 /**
  * The kernel-hosted seam this Package receives. Implemented by the Durable
  * Object host (`@frockbot/plugin-shell/backend-authoring`), which owns the
@@ -44,8 +57,13 @@ export interface PackageAuthoringHost {
   effectIdFor(input: {
     packageId: string;
     sourceHash: string;
+    uiHtmlHash?: string;
+    hooks?: AuthorPackageInputV1["hooks"];
   }): Promise<string>;
   author(request: AuthorPackageRequestV1): Promise<AuthorPackageOutcomeV1>;
+  undoEffectIdFor(input: PackageUndoInputV1): Promise<string>;
+  undo(request: PackageUndoRequestV1): Promise<PackageUndoOutcomeV1>;
+  inspectSelf(): Promise<PackageInspectSelfOutcomeV1>;
 }
 /**
@@ -105,8 +123,7 @@ export function createPackageAuthorTool(
     // not part of the narrow reach of `browserUse`, `computerUse`, or the two
     // video roles. See `@frockbot/plugin-subagents` `SUBAGENT_TOOL_REACH_V1`.
     admission: { subagentRoles: ["executor"] },
-    description:
-      "Author a Package for yourself: one tool implemented in a single TypeScript file that runs in your own isolate. The Package is recorded as a new Composition generation and activates on your next Turn.",
+    description: `Author a Package for yourself: tools implemented in one TypeScript file that runs in your own isolate. Declare every exported tool in tools; the names must match exactly. The Package is recorded as a new Composition generation and activates on your next Turn. ${BOT_ISOLATE_CONTEXT_SUMMARY_V1}`,
     inputSchema: AUTHOR_PACKAGE_INPUT_SCHEMA_V1,
     idempotent: false,
     validate: (input: unknown) => {
@@ -137,9 +154,14 @@ export function createPackageAuthorTool(
         };
       }
       const sourceHash = await sha256HexV1(decoded.source);
+      const uiHtmlHash = decoded.ui
+        ? await sha256HexV1(decoded.ui.html)
+        : undefined;
       const effectId = await host.effectIdFor({
         packageId: decoded.packageId,
         sourceHash,
+        ...(uiHtmlHash === undefined ? {} : { uiHtmlHash }),
+        ...(decoded.hooks === undefined ? {} : { hooks: decoded.hooks }),
       });
       const position = openTurnPositionV1(session);
       // Intent before effect: the session event and the durable intent record
@@ -179,12 +201,119 @@ export function createPackageAuthorTool(
   };
 }
-/** The runtime Contribution. Registers `package_author` and nothing else. */
+export function createPackageUndoTool(
+  host: PackageAuthoringHost,
+  sessions: { get(sessionId: string): Session | undefined },
+): ToolDefinition {
+  return {
+    name: "package_undo",
+    admission: { subagentRoles: ["executor"] },
+    description:
+      "Undo your latest Package setup change, or restore an earlier Composition generation. This only changes Package setup; it never undoes actions taken through Connections. The resulting generation activates on the next Turn.",
+    inputSchema: PACKAGE_UNDO_INPUT_SCHEMA_V1,
+    idempotent: false,
+    validate: (input) => {
+      try {
+        decodePackageUndoInputV1(input);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    execute: async (input: unknown, context: ToolExecutionContext) => {
+      let decoded: PackageUndoInputV1;
+      try {
+        decoded = decodePackageUndoInputV1(input);
+      } catch (error) {
+        return {
+          content: `package_undo input was rejected: ${errorMessage(error)}`,
+          isError: true,
+        };
+      }
+      const session = sessions.get(context.sessionId);
+      if (!session) {
+        return {
+          content: `package_undo cannot record its intent: session "${context.sessionId}" is unavailable`,
+          isError: true,
+        };
+      }
+      const effectId = await host.undoEffectIdFor(decoded);
+      const position = openTurnPositionV1(session);
+      session.append({
+        type: "package/undo-intent",
+        ...position,
+        effectId,
+        ...(decoded.generationId
+          ? { requestedGenerationId: decoded.generationId }
+          : {}),
+      });
+      await session.flush();
+      const outcome = await host.undo({
+        input: decoded,
+        effectId,
+        sessionId: context.sessionId,
+        position,
+      });
+      if (outcome.status === "refused") {
+        return {
+          content: `Package undo was refused: ${outcome.reason} A durable failure record "${outcome.failureId}" was written. No connection action was undone.`,
+          isError: true,
+        };
+      }
+      session.append({
+        type: "package/undo-recorded",
+        ...position,
+        effectId,
+        generationId: outcome.generationId,
+        targetGenerationId: outcome.targetGenerationId,
+      });
+      await session.flush();
+      return {
+        content: `Package setup will return to Composition generation "${outcome.targetGenerationId}" through new pending generation "${outcome.generationId}". It activates on the next Turn. This changed Package setup only; it did not undo any action taken through a Connection.`,
+        isError: false,
+      };
+    },
+  };
+}
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+export function createPackageInspectSelfTool(
+  host: PackageAuthoringHost,
+): ToolDefinition {
+  return {
+    name: "package_inspect_self",
+    admission: { subagentRoles: ["executor"] },
+    description:
+      "Read your exact Package execution context contract, current Composition (including your stored Package source), and latest authoring or activation failure per authored Package.",
+    inputSchema: { type: "object", additionalProperties: false },
+    idempotent: true,
+    validate: (input) =>
+      Boolean(input && typeof input === "object" && !Array.isArray(input)) &&
+      Object.keys(input as Record<string, unknown>).length === 0,
+    execute: async () => ({
+      content: JSON.stringify(await host.inspectSelf(), null, 2),
+      isError: false,
+    }),
+  };
+}
+/** The runtime Contribution. Registers the three chat-first setup tools. */
 export function createAuthoringRuntimePlugin(
   host: PackageAuthoringHost,
 ): Plugin.Function {
-  const plugin: Plugin.Function = (ctx) =>
-    ctx.tools.register(createPackageAuthorTool(host, ctx.sessions));
+  const plugin: Plugin.Function = (ctx) => {
+    const disposers = [
+      ctx.tools.register(createPackageAuthorTool(host, ctx.sessions)),
+      ctx.tools.register(createPackageUndoTool(host, ctx.sessions)),
+      ctx.tools.register(createPackageInspectSelfTool(host)),
+    ];
+    return () => {
+      for (const dispose of disposers.reverse()) dispose();
+    };
+  };
   plugin.inject = ["tools", "sessions"];
   return plugin;
 }

package/src/records.test.ts CHANGED Viewed

@@ -19,6 +19,7 @@ const INTENT: AuthorshipIntentV1 = {
   packageId: "weather-lookup",
   version: "0.0.1",
   sourceHash: "a".repeat(64),
+  manifestHash: "b".repeat(64),
   sourceBytes: 64,
   recordedAt: "2026-08-31T00:00:00.000Z",
   status: "recorded",

package/src/records.ts CHANGED Viewed

@@ -11,6 +11,10 @@ export const AUTHORSHIP_INTENT_PREFIX = "authorship:intent:";
 export const AUTHORSHIP_ARTIFACT_PREFIX = "authorship:artifact:";
 export const AUTHORSHIP_FAILURE_PREFIX = "authorship:failure:";
 export const AUTHORSHIP_PACKAGE_PREFIX = "authorship:package:";
+export const AUTHORSHIP_MANIFEST_PREFIX = "authorship:manifest:";
+export const AUTHORSHIP_LATEST_FAILURE_PREFIX = "authorship:latest-failure:";
+export const AUTHORSHIP_UNDO_INTENT_PREFIX = "authorship:undo-intent:";
+export const AUTHORSHIP_UNDO_OUTCOME_PREFIX = "authorship:undo-outcome:";
 export const ARTIFACT_PREFIX = "artifact:";
 export function authorshipIntentKey(effectId: string): string {
@@ -30,6 +34,22 @@ export function authorshipPackageKey(packageId: string): string {
   return `${AUTHORSHIP_PACKAGE_PREFIX}${packageId}`;
 }
+export function authorshipManifestKey(manifestHash: string): string {
+  return `${AUTHORSHIP_MANIFEST_PREFIX}${manifestHash}`;
+}
+export function authorshipLatestFailureKey(packageId: string): string {
+  return `${AUTHORSHIP_LATEST_FAILURE_PREFIX}${packageId}`;
+}
+export function authorshipUndoIntentKey(effectId: string): string {
+  return `${AUTHORSHIP_UNDO_INTENT_PREFIX}${effectId}`;
+}
+export function authorshipUndoOutcomeKey(effectId: string): string {
+  return `${AUTHORSHIP_UNDO_OUTCOME_PREFIX}${effectId}`;
+}
 export function artifactKey(contentHash: string): string {
   return `${ARTIFACT_PREFIX}${contentHash}`;
 }
@@ -43,8 +63,10 @@ export interface AuthorshipIntentV1 {
   turnId: string;
   packageId: string;
   version: string;
-  /** sha-256 of the source text. The source itself is never durable state. */
+  /** sha-256 of the source text stored in the immutable Package content store. */
   sourceHash: string;
+  /** sha-256 of the exact manifest recorded before bundling starts. */
+  manifestHash: string;
   sourceBytes: number;
   recordedAt: string;
   status: "recorded";
@@ -59,6 +81,9 @@ export interface AuthoredArtifactRecordV1 {
   bundlerVersion: string;
   effectId: string;
   r2Key: string;
+  sourceHash: string;
+  sourceR2Key: string;
+  manifestHash: string;
   provenance: {
     kind: "bot";
     packageId: string;
@@ -72,6 +97,16 @@ export interface AuthoredArtifactRecordV1 {
   createdAt: string;
 }
+/** The exact immutable manifest mounted for one Bot-authored member. */
+export interface AuthoredManifestRecordV1 {
+  schemaVersion: 1;
+  manifestHash: string;
+  packageId: string;
+  version: string;
+  manifest: unknown;
+  createdAt: string;
+}
 /** The latest recorded version of one authored Package identity. */
 export interface AuthoredPackageRecordV1 {
   schemaVersion: 1;
@@ -96,10 +131,44 @@ export interface AuthoringFailureRecordV1 {
   recordedAt: string;
 }
+export interface PackageUndoIntentV1 {
+  schemaVersion: 1;
+  effectId: string;
+  botId: string;
+  runId: string;
+  turnId: string;
+  requestedGenerationId?: string;
+  targetGenerationId: string;
+  recordedAt: string;
+  status: "recorded";
+}
+export type PackageUndoRecordV1 =
+  | {
+      schemaVersion: 1;
+      effectId: string;
+      generationId: string;
+      targetGenerationId: string;
+      recordedAt: string;
+      status: "recorded";
+    }
+  | {
+      schemaVersion: 1;
+      effectId: string;
+      failureId: string;
+      reason: string;
+      recordedAt: string;
+      status: "refused";
+    };
 export function artifactR2KeyV1(contentHash: string): string {
   return `packages/${contentHash}.mjs`;
 }
+export function sourceR2KeyV1(sourceHash: string): string {
+  return `packages/${sourceHash}.ts`;
+}
 /**
  * The durable outcome of one authoring effect, written under
  * `authorship:artifact:<effectId>` in the same put as `artifact:<contentHash>`.

package/src/shared.test.ts CHANGED Viewed

@@ -10,23 +10,44 @@ import {
 const VALID = {
   packageId: "weather-lookup",
   displayName: "Weather lookup",
-  tool: {
-    name: "weather_lookup",
-    description: "Looks up the weather",
-    inputSchema: { type: "object", properties: { city: { type: "string" } } },
-  },
+  tools: [
+    {
+      name: "weather_lookup",
+      description: "Looks up the weather",
+      inputSchema: {
+        type: "object",
+        properties: { city: { type: "string" } },
+      },
+    },
+  ],
   source: "export const tools = [];\nexport async function execute() {}\n",
 };
 describe("decodeAuthorPackageInputV1", () => {
-  test("accepts the exact v1 shape and the optional model Contribution", () => {
+  test("accepts the exact plural shape and canonicalizes the legacy singular shape", () => {
     expect(decodeAuthorPackageInputV1(VALID)).toEqual(VALID);
+    const { tools: _tools, ...rest } = VALID;
     expect(
+      decodeAuthorPackageInputV1({ ...rest, tool: VALID.tools[0] }),
+    ).toEqual(VALID);
+  });
+  test("accepts only declared public waterfall hooks", () => {
+    expect(
+      decodeAuthorPackageInputV1({
+        ...VALID,
+        hooks: ["agent/tool-exposure", "tools/post-execute"],
+      }).hooks,
+    ).toEqual(["agent/tool-exposure", "tools/post-execute"]);
+    expect(() =>
+      decodeAuthorPackageInputV1({ ...VALID, hooks: ["agent/request"] }),
+    ).toThrow(/hooks\[0\] is invalid/);
+    expect(() =>
       decodeAuthorPackageInputV1({
         ...VALID,
-        model: { providerId: "ollama-cloud", modelId: "qwen3-coder:480b" },
-      }).model,
-    ).toEqual({ providerId: "ollama-cloud", modelId: "qwen3-coder:480b" });
+        hooks: ["agent/tool-exposure", "agent/tool-exposure"],
+      }),
+    ).toThrow(/duplicate events/);
   });
   test.each([
@@ -37,16 +58,17 @@ describe("decodeAuthorPackageInputV1", () => {
     ["a one-character package id", { ...VALID, packageId: "a" }],
     [
       "a tool name with a dash",
-      { ...VALID, tool: { ...VALID.tool, name: "a-b" } },
+      { ...VALID, tools: [{ ...VALID.tools[0]!, name: "a-b" }] },
     ],
     ["an empty source", { ...VALID, source: "" }],
     [
       "a non-object input schema",
-      { ...VALID, tool: { ...VALID.tool, inputSchema: "object" } },
+      { ...VALID, tools: [{ ...VALID.tools[0]!, inputSchema: "object" }] },
     ],
+    ["a removed model declaration", { ...VALID, model: { providerId: "x" } }],
     [
-      "a partial model Contribution",
-      { ...VALID, model: { providerId: "ollama-cloud" } },
+      "duplicate tool names",
+      { ...VALID, tools: [VALID.tools[0], VALID.tools[0]] },
     ],
   ])("rejects %s", (_label, input) => {
     expect(() => decodeAuthorPackageInputV1(input)).toThrow();
@@ -60,10 +82,39 @@ describe("decodeAuthorPackageInputV1", () => {
       }),
     ).toThrow();
   });
+  test("accepts one inline iframe page and refuses external resources or an oversized page", () => {
+    const ui = {
+      html: "<!doctype html><style>body{color:red}</style><script>window.frockbot.resize()</script>",
+      mounts: [
+        { slot: "frockbot.tool-result:weather_lookup", order: 10 },
+        { slot: "frockbot.bot-settings-sections" },
+      ],
+    };
+    expect(
+      decodeAuthorPackageInputV1({
+        ...VALID,
+        hooks: ["agent/tool-exposure"],
+        ui,
+      }),
+    ).toMatchObject({ hooks: ["agent/tool-exposure"], ui });
+    expect(() =>
+      decodeAuthorPackageInputV1({
+        ...VALID,
+        ui: { ...ui, html: '<script src="https://example.com/x.js"></script>' },
+      }),
+    ).toThrow("inline resources only");
+    expect(() =>
+      decodeAuthorPackageInputV1({
+        ...VALID,
+        ui: { ...ui, html: "a".repeat(256 * 1024 + 1) },
+      }),
+    ).toThrow();
+  });
 });
 describe("authoring identity", () => {
-  test("the effect id is deterministic in the run and the exact source", async () => {
+  test("the effect id is deterministic in the run, source, UI, and hooks", async () => {
     const sourceHash = await sha256HexV1(VALID.source);
     const first = await authoringEffectIdV1({
       runId: "run-1",
@@ -85,10 +136,25 @@ describe("authoring identity", () => {
       packageId: VALID.packageId,
       sourceHash: await sha256HexV1(`${VALID.source}//`),
     });
+    const otherUi = await authoringEffectIdV1({
+      runId: "run-1",
+      packageId: VALID.packageId,
+      sourceHash,
+      uiHtmlHash: await sha256HexV1("<!doctype html><h1>Weather</h1>"),
+    });
+    const otherHooks = await authoringEffectIdV1({
+      runId: "run-1",
+      packageId: VALID.packageId,
+      sourceHash,
+      hooks: ["agent/tool-exposure"],
+    });
     expect(first).toBe(second);
     expect(first).not.toBe(otherRun);
     expect(first).not.toBe(otherSource);
+    expect(first).not.toBe(otherUi);
+    expect(first).not.toBe(otherHooks);
+    expect(otherUi).not.toBe(otherHooks);
     expect(first.length).toBeLessThanOrEqual(200);
   });
@@ -98,41 +164,71 @@ describe("authoring identity", () => {
     expect(() => authoredVersionV1(0)).toThrow();
   });
-  test("the synthesized manifest declares only the isolate host", () => {
+  test("the synthesized manifest declares only the isolate host, tools and hooks", () => {
     const manifest = authoredManifestV1({
       packageId: VALID.packageId,
       displayName: VALID.displayName,
       version: "0.0.1",
-      tool: VALID.tool,
-      model: { providerId: "ollama-cloud", modelId: "qwen3-coder:480b" },
+      tools: VALID.tools,
+      hooks: ["agent/tool-exposure"],
     });
     const contributions = manifest.contributions as Record<
       string,
       { host?: string; binding?: string }
     >;
-    expect(Object.keys(contributions).toSorted()).toEqual(["model", "runtime"]);
+    expect(Object.keys(contributions)).toEqual(["runtime"]);
     expect(contributions.runtime?.host).toBe("bot-isolate");
-    expect(contributions.model?.host).toBe("bot-isolate");
-    // A Bot-authored model adapter is a translation layer over a kernel
-    // binding, never a network client.
-    expect(contributions.model?.binding).toBe("capabilities.invokeModel");
+    expect(manifest.tools).toEqual(VALID.tools);
+    expect(manifest.hooks).toEqual(["agent/tool-exposure"]);
     expect(manifest.permissions).toEqual([]);
   });
-  test("the manifest hash moves when the declared model Contribution moves", () => {
+  test("the manifest moves when its declared tool set moves", () => {
     const base = authoredManifestV1({
       packageId: VALID.packageId,
       displayName: VALID.displayName,
       version: "0.0.1",
-      tool: VALID.tool,
+      tools: VALID.tools,
     });
     const withModel = authoredManifestV1({
       packageId: VALID.packageId,
       displayName: VALID.displayName,
       version: "0.0.1",
-      tool: VALID.tool,
-      model: { providerId: "ollama-cloud", modelId: "qwen3-coder:480b" },
+      tools: [
+        ...VALID.tools,
+        { name: "forecast", description: "Forecasts", inputSchema: {} },
+      ],
     });
     expect(JSON.stringify(base)).not.toBe(JSON.stringify(withModel));
   });
+  test("extends the same manifest with a content-addressed iframe contribution", () => {
+    const artifact = {
+      contentHash: "a".repeat(64),
+      size: 42,
+      mediaType: "text/html" as const,
+      bundlerVersion: "frockbot-inline-html@1",
+    };
+    const manifest = authoredManifestV1({
+      packageId: VALID.packageId,
+      displayName: VALID.displayName,
+      version: "0.0.1",
+      tools: VALID.tools,
+      ui: {
+        artifact,
+        mounts: [{ slot: "frockbot.tool-result:weather_lookup" }],
+      },
+    });
+    expect(manifest).toMatchObject({
+      schemaVersion: 3,
+      contributions: {
+        runtime: { host: "bot-isolate" },
+        client: {
+          kind: "iframe",
+          artifact,
+          mounts: [{ slot: "frockbot.tool-result:weather_lookup" }],
+        },
+      },
+    });
+  });
 });

package/src/shared.ts CHANGED Viewed

@@ -6,23 +6,29 @@
 // immutable artifact and a pending Composition generation. Activation is a
 // separate event, at the next admitted Turn. A model never overwrites a
 // version; re-authoring the same `packageId` appends the next one.
-import { PACKAGE_BUNDLE_MAX_SOURCE_BYTES } from "@frockbot/kernel-contracts";
+import {
+  BOT_ISOLATE_HOOK_EVENTS_V1,
+  isBotIsolateHookEventNameV1,
+  PACKAGE_BUNDLE_MAX_SOURCE_BYTES,
+  type BotIsolateHookEventNameV1,
+} from "@frockbot/kernel-contracts";
 /** The `package_author` tool input. */
 export interface AuthorPackageInputV1 {
   /** Stable Plugin identity; re-authoring appends a version. */
   packageId: string;
   displayName: string;
-  tool: { name: string; description: string; inputSchema: unknown };
+  /** Every tool the immutable Package artifact is expected to export. */
+  tools: Array<{ name: string; description: string; inputSchema: unknown }>;
+  /** Waterfall events the immutable artifact is expected to hook. */
+  hooks?: BotIsolateHookEventNameV1[];
   /** TypeScript text; exactly one `package.ts`. */
   source: string;
-  /**
-   * D6 addendum. The authored Package declares a model Contribution: an
-   * adapter that forwards to `CAPABILITIES.invokeModel`. It is a translation
-   * layer over a kernel-declared binding, never a network client, and it is
-   * callable only where an enabled model capability matches.
-   */
-  model?: { providerId: string; modelId: string };
+  /** Optional sandboxed page. All CSS and JavaScript must be inline. */
+  ui?: {
+    html: string;
+    mounts: Array<{ slot: string; order?: number }>;
+  };
 }
 export type AuthorPackageOutcomeV1 =
@@ -42,8 +48,61 @@ export type AuthorPackageOutcomeV1 =
       failureId: string;
     };
+export interface PackageUndoInputV1 {
+  /** Absent means the generation before the most recent authored change. */
+  generationId?: string;
+}
+export type PackageUndoOutcomeV1 =
+  | {
+      status: "recorded";
+      effectId: string;
+      generationId: string;
+      targetGenerationId: string;
+    }
+  | { status: "refused"; reason: string; failureId: string };
+export interface PackageInspectMemberV1 {
+  packageId: string;
+  version: string;
+  provenance: Record<string, unknown>;
+  declaredTools: string[];
+  source?: string;
+}
+export interface PackageInspectFailureV1 {
+  packageId: string;
+  authoring?: {
+    failureId: string;
+    phase: string;
+    reason: string;
+    diagnostics: string[];
+    recordedAt: string;
+  };
+  activation?: {
+    generationId: string;
+    attempt: number;
+    phase: string;
+    message: string;
+    diagnostics: string[];
+    at: string;
+    quarantined: boolean;
+  };
+}
+export interface PackageInspectSelfOutcomeV1 {
+  contextContract: string;
+  composition: {
+    generationId: string;
+    status: string;
+    members: PackageInspectMemberV1[];
+  };
+  failures: PackageInspectFailureV1[];
+}
 export const AUTHORED_PACKAGE_ID = /^[a-z][a-z0-9-]{2,63}$/;
 export const AUTHORED_TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+export const AUTHORED_TOOLS_MAX = 64;
 /**
  * The shape of an authored id, not its authority: a Bot may not shadow a
  * first-party or User Package, and that rule is enforced against the Bot's
@@ -112,12 +171,20 @@ export function decodeAuthorPackageInputV1(
   label = "package_author input",
 ): AuthorPackageInputV1 {
   const value = record(input, label);
+  // `tool` is accepted for one compatibility release, but the decoded shape
+  // is always the plural declaration the manifest and mount path enforce.
   exactKeys(
     value,
-    ["packageId", "displayName", "tool", "source"],
-    ["model"],
+    ["packageId", "displayName", "source"],
+    ["tools", "tool", "hooks", "ui"],
     label,
   );
+  if (
+    (value.tools === undefined && value.tool === undefined) ||
+    (value.tools !== undefined && value.tool !== undefined)
+  ) {
+    throw new Error(`${label} must declare exactly one of tools or tool`);
+  }
   const packageId = boundedString(
     value.packageId,
     `${label}.packageId`,
@@ -131,19 +198,53 @@ export function decodeAuthorPackageInputV1(
     `${label}.displayName`,
     128,
   );
-  const tool = record(value.tool, `${label}.tool`);
-  exactKeys(tool, ["name", "description", "inputSchema"], [], `${label}.tool`);
-  const name = boundedString(tool.name, `${label}.tool.name`, 64);
-  if (!AUTHORED_TOOL_NAME.test(name)) {
-    throw new Error(`${label}.tool.name is invalid`);
+  const declaredTools = value.tools === undefined ? [value.tool] : value.tools;
+  if (
+    !Array.isArray(declaredTools) ||
+    declaredTools.length === 0 ||
+    declaredTools.length > AUTHORED_TOOLS_MAX
+  ) {
+    throw new Error(`${label}.tools must be a non-empty bounded array`);
+  }
+  const tools = declaredTools.map((candidate, index) => {
+    const toolLabel = `${label}.tools[${index}]`;
+    const tool = record(candidate, toolLabel);
+    exactKeys(tool, ["name", "description", "inputSchema"], [], toolLabel);
+    const name = boundedString(tool.name, `${toolLabel}.name`, 64);
+    if (!AUTHORED_TOOL_NAME.test(name)) {
+      throw new Error(`${toolLabel}.name is invalid`);
+    }
+    const description = boundedString(
+      tool.description,
+      `${toolLabel}.description`,
+      1_024,
+    );
+    const inputSchema = record(tool.inputSchema, `${toolLabel}.inputSchema`);
+    requireJsonValue(inputSchema, `${toolLabel}.inputSchema`);
+    return { name, description, inputSchema };
+  });
+  if (new Set(tools.map((tool) => tool.name)).size !== tools.length) {
+    throw new Error(`${label}.tools contains duplicate names`);
+  }
+  let hooks: BotIsolateHookEventNameV1[] | undefined;
+  if (value.hooks !== undefined) {
+    if (
+      !Array.isArray(value.hooks) ||
+      value.hooks.length === 0 ||
+      value.hooks.length > BOT_ISOLATE_HOOK_EVENTS_V1.length
+    ) {
+      throw new Error(`${label}.hooks must be a non-empty bounded array`);
+    }
+    hooks = value.hooks.map((hook, index) => {
+      if (!isBotIsolateHookEventNameV1(hook)) {
+        throw new Error(`${label}.hooks[${index}] is invalid`);
+      }
+      return hook;
+    });
+    if (new Set(hooks).size !== hooks.length) {
+      throw new Error(`${label}.hooks contains duplicate events`);
+    }
   }
-  const description = boundedString(
-    tool.description,
-    `${label}.tool.description`,
-    1_024,
-  );
-  const inputSchema = record(tool.inputSchema, `${label}.tool.inputSchema`);
-  requireJsonValue(inputSchema, `${label}.tool.inputSchema`);
   const source = boundedString(
     value.source,
     `${label}.source`,
@@ -155,25 +256,73 @@ export function decodeAuthorPackageInputV1(
   ) {
     throw new Error(`${label}.source exceeds the per-Package source quota`);
   }
-  let model: AuthorPackageInputV1["model"];
-  if (value.model !== undefined) {
-    const declared = record(value.model, `${label}.model`);
-    exactKeys(declared, ["providerId", "modelId"], [], `${label}.model`);
-    model = {
-      providerId: boundedString(
-        declared.providerId,
-        `${label}.model.providerId`,
-        128,
-      ),
-      modelId: boundedString(declared.modelId, `${label}.model.modelId`, 128),
-    };
+  let ui: AuthorPackageInputV1["ui"];
+  if (value.ui !== undefined) {
+    const rawUi = record(value.ui, `${label}.ui`);
+    exactKeys(rawUi, ["html", "mounts"], [], `${label}.ui`);
+    const html = boundedString(
+      rawUi.html,
+      `${label}.ui.html`,
+      PACKAGE_BUNDLE_MAX_SOURCE_BYTES,
+    );
+    if (
+      new TextEncoder().encode(html).byteLength >
+      PACKAGE_BUNDLE_MAX_SOURCE_BYTES
+    ) {
+      throw new Error(`${label}.ui.html exceeds the per-Package source quota`);
+    }
+    if (
+      /<(?:script|iframe|img|audio|video|source|embed|input)\b[^>]*\bsrc\s*=\s*["'](?!data:)/i.test(
+        html,
+      ) ||
+      /<object\b[^>]*\bdata\s*=\s*["'](?!data:)/i.test(html) ||
+      /\bsrcset\s*=/i.test(html) ||
+      /<link\b/i.test(html) ||
+      /@import\b/i.test(html) ||
+      /<meta\b[^>]*http-equiv\s*=\s*["']?refresh/i.test(html) ||
+      /url\(\s*["']?(?!data:|["']?\s*\))/i.test(html)
+    ) {
+      throw new Error(`${label}.ui.html may contain inline resources only`);
+    }
+    if (
+      !Array.isArray(rawUi.mounts) ||
+      rawUi.mounts.length === 0 ||
+      rawUi.mounts.length > 64
+    ) {
+      throw new Error(`${label}.ui.mounts must be a non-empty bounded array`);
+    }
+    const mounts = rawUi.mounts.map((candidate, index) => {
+      const mount = record(candidate, `${label}.ui.mounts[${index}]`);
+      exactKeys(mount, ["slot"], ["order"], `${label}.ui.mounts[${index}]`);
+      const slot = boundedString(
+        mount.slot,
+        `${label}.ui.mounts[${index}].slot`,
+        160,
+      );
+      if (
+        slot !== "frockbot.bot-settings-sections" &&
+        !slot.startsWith("frockbot.tool-result:")
+      ) {
+        throw new Error(`${label}.ui.mounts[${index}].slot is not iframe-safe`);
+      }
+      const order = mount.order;
+      if (
+        order !== undefined &&
+        (typeof order !== "number" || !Number.isFinite(order))
+      ) {
+        throw new Error(`${label}.ui.mounts[${index}].order must be finite`);
+      }
+      return { slot, ...(order === undefined ? {} : { order }) };
+    });
+    ui = { html, mounts };
   }
   return {
     packageId,
     displayName,
-    tool: { name, description, inputSchema },
+    tools,
+    ...(hooks === undefined ? {} : { hooks }),
     source,
-    ...(model ? { model } : {}),
+    ...(ui ? { ui } : {}),
   };
 }
@@ -181,7 +330,7 @@ export function decodeAuthorPackageInputV1(
 export const AUTHOR_PACKAGE_INPUT_SCHEMA_V1 = {
   type: "object",
   additionalProperties: false,
-  required: ["packageId", "displayName", "tool", "source"],
+  required: ["packageId", "displayName", "tools", "source"],
   properties: {
     packageId: {
       type: "string",
@@ -189,35 +338,97 @@ export const AUTHOR_PACKAGE_INPUT_SCHEMA_V1 = {
         "Stable lowercase Package identity. Re-authoring it appends a version.",
     },
     displayName: { type: "string" },
-    tool: {
-      type: "object",
-      additionalProperties: false,
-      required: ["name", "description", "inputSchema"],
-      properties: {
-        name: { type: "string" },
-        description: { type: "string" },
-        inputSchema: { type: "object" },
+    tools: {
+      type: "array",
+      minItems: 1,
+      maxItems: AUTHORED_TOOLS_MAX,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["name", "description", "inputSchema"],
+        properties: {
+          name: { type: "string" },
+          description: { type: "string" },
+          inputSchema: { type: "object" },
+        },
       },
     },
+    hooks: {
+      type: "array",
+      minItems: 1,
+      maxItems: BOT_ISOLATE_HOOK_EVENTS_V1.length,
+      uniqueItems: true,
+      items: { type: "string", enum: BOT_ISOLATE_HOOK_EVENTS_V1 },
+      description:
+        "Waterfall loop events exported from `hooks`; names must match exactly.",
+    },
     source: {
       type: "string",
       description:
-        "TypeScript for one package.ts that exports `tools` and `execute(tool, input, ctx)`. No imports: the isolate has no network and no npm. `ctx.invokeModel(request)` is the only model path.",
+        "TypeScript for one package.ts that exports `tools` and `execute(tool, input, ctx)`. No imports: the isolate has no network and no npm. `ctx.model.invoke(request)` uses the Bot's configured model binding.",
     },
-    model: {
+    ui: {
       type: "object",
       additionalProperties: false,
-      required: ["providerId", "modelId"],
-      description:
-        "Declare a model Contribution that forwards to the kernel model binding.",
+      required: ["html", "mounts"],
       properties: {
-        providerId: { type: "string" },
-        modelId: { type: "string" },
+        html: {
+          type: "string",
+          description:
+            "One ui.html page (maximum 256 KB). CSS and JavaScript must be inline; images may use data: URLs.",
+        },
+        mounts: {
+          type: "array",
+          minItems: 1,
+          maxItems: 64,
+          items: {
+            type: "object",
+            additionalProperties: false,
+            required: ["slot"],
+            properties: {
+              slot: {
+                type: "string",
+                description:
+                  "frockbot.bot-settings-sections or frockbot.tool-result:<declaredToolName>",
+              },
+              order: { type: "number" },
+            },
+          },
+        },
       },
     },
   },
 } as const;
+export function decodePackageUndoInputV1(
+  input: unknown,
+  label = "package_undo input",
+): PackageUndoInputV1 {
+  const value = record(input, label);
+  exactKeys(value, [], ["generationId"], label);
+  return value.generationId === undefined
+    ? {}
+    : {
+        generationId: boundedString(
+          value.generationId,
+          `${label}.generationId`,
+          256,
+        ),
+      };
+}
+export const PACKAGE_UNDO_INPUT_SCHEMA_V1 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    generationId: {
+      type: "string",
+      description:
+        "Optional earlier Composition generation. Omit to undo your most recent Package change.",
+    },
+  },
+} as const;
 export async function sha256HexV1(value: string): Promise<string> {
   const digest = await crypto.subtle.digest(
     "SHA-256",
@@ -230,20 +441,40 @@ export async function sha256HexV1(value: string): Promise<string> {
 /**
  * The idempotency key for one authoring effect. Deterministic in the admitted
- * run and the exact source, so a resumed Turn that re-executes the same tool
- * call lands on the same effect instead of bundling a second time.
+ * run and every independently bundled or declared execution dimension, so a
+ * resumed Turn that re-executes the same tool call lands on the same effect
+ * instead of bundling a second time.
  */
 export async function authoringEffectIdV1(input: {
   runId: string;
   packageId: string;
   sourceHash: string;
+  uiHtmlHash?: string;
+  hooks?: BotIsolateHookEventNameV1[];
 }): Promise<string> {
   const digest = await sha256HexV1(
-    JSON.stringify([input.runId, input.packageId, input.sourceHash]),
+    JSON.stringify([
+      input.runId,
+      input.packageId,
+      input.sourceHash,
+      input.uiHtmlHash ?? null,
+      input.hooks ?? [],
+    ]),
   );
   return `author-${digest.slice(0, 32)}`;
 }
+/** One undo effect per admitted run and requested target (or default target). */
+export async function packageUndoEffectIdV1(input: {
+  runId: string;
+  generationId?: string;
+}): Promise<string> {
+  const digest = await sha256HexV1(
+    JSON.stringify([input.runId, input.generationId ?? "latest"]),
+  );
+  return `undo-${digest.slice(0, 32)}`;
+}
 /** `0.0.1`, `0.0.2`, … — a version is appended, never overwritten. */
 export function authoredVersionV1(ordinal: number): string {
   if (!Number.isSafeInteger(ordinal) || ordinal < 1) {
@@ -260,15 +491,25 @@ export function authoredSpecifierV1(packageId: string): string {
 /**
  * The manifest an authored Package is content-addressed by. It is synthesized
  * rather than authored so a Bot cannot declare a Contribution host the kernel
- * did not offer it: exactly one Bot isolate runtime Contribution, plus the
- * declared model binding when the Package asked for one.
+ * did not offer it: exactly one Bot isolate runtime Contribution and the exact
+ * tool names mount health must report. Model access is a method on the narrow
+ * Package context, not a separate manifest Contribution.
  */
 export function authoredManifestV1(input: {
   packageId: string;
   displayName: string;
   version: string;
-  tool: AuthorPackageInputV1["tool"];
-  model?: AuthorPackageInputV1["model"];
+  tools: AuthorPackageInputV1["tools"];
+  hooks?: AuthorPackageInputV1["hooks"];
+  ui?: {
+    artifact: {
+      contentHash: string;
+      size: number;
+      mediaType: "text/html";
+      bundlerVersion: string;
+    };
+    mounts: Array<{ slot: string; order?: number }>;
+  };
 }): Record<string, unknown> {
   return {
     schemaVersion: 3,
@@ -279,25 +520,18 @@ export function authoredManifestV1(input: {
     dependencies: {},
     contributions: {
       runtime: { entry: "./package.js", host: "bot-isolate" },
-      ...(input.model
+      ...(input.ui
         ? {
-            model: {
-              entry: "./package.js",
-              host: "bot-isolate",
-              binding: "capabilities.invokeModel",
-              providerId: input.model.providerId,
-              modelId: input.model.modelId,
+            client: {
+              kind: "iframe",
+              artifact: { ...input.ui.artifact },
+              mounts: input.ui.mounts.map((mount) => ({ ...mount })),
             },
           }
         : {}),
     },
-    tools: [
-      {
-        name: input.tool.name,
-        description: input.tool.description,
-        inputSchema: input.tool.inputSchema,
-      },
-    ],
+    tools: input.tools.map((tool) => ({ ...tool })),
+    ...(input.hooks === undefined ? {} : { hooks: [...input.hooks] }),
     permissions: [],
   };
 }