@frockbot/plugin-bot-template 0.0.0 → 0.1.0

package/frockbot.json

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": 4,
+  "id": "bot-template",
+  "displayName": "Bot templates",
+  "version": "0.0.1",
+  "compatibility": { "frockbot": ">=0.0.1" },
+  "dependencies": {
+    "settings": ">=0.0.1",
+    "shell": ">=0.0.1",
+    "ui-theme": ">=0.0.1"
+  },
+  "contributions": {
+    "backend": [
+      { "entry": "./backend", "host": "gateway" },
+      { "entry": "./user", "host": "user" }
+    ],
+    "runtime": { "entry": "./agent" },
+    "client": {
+      "entry": "./client",
+      "mounts": [
+        {
+          "slot": "frockbot.bot-settings-primary-sections",
+          "order": 20
+        },
+        { "slot": "frockbot.bot-settings-sections", "order": 21 }
+      ],
+      "outlets": []
+    }
+  },
+  "permissions": ["bot:self-manage"],
+  "configuration": {
+    "settings": [],
+    "connectionTypes": [],
+    "capabilities": [
+      {
+        "id": "bot-template-export",
+        "kind": "tool",
+        "connectionTypes": [],
+        "admission": { "turnTypes": ["chat"] }
+      }
+    ]
+  }
+}

package/package.json

@@ -1,14 +1,55 @@
 {
   "name": "@frockbot/plugin-bot-template",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./agent": "./src/agent.ts",
+    "./backend": "./src/backend.ts",
+    "./client": "./src/client/index.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./manifest": "./src/manifest.ts",
+    "./package.json": "./package.json",
+    "./scrub": "./src/scrub.ts",
+    "./shared": "./src/shared.ts",
+    "./user": "./src/user.ts"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "build": "vite build",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/client-core": "0.1.0",
+    "@frockbot/client-ui": "0.1.0",
+    "@frockbot/configuration-core": "0.1.0",
+    "@frockbot/connection-core": "0.1.0",
+    "@frockbot/kernel-agent-loop": "0.1.0",
+    "@frockbot/kernel-contracts": "0.1.0",
+    "@frockbot/plugin-settings": "0.1.0",
+    "@frockbot/plugin-shell": "0.1.0",
+    "@frockbot/template-core": "0.1.0",
+    "cordis": "4.0.0-rc.8",
+    "vue": "3.5.41"
+  },
+  "devDependencies": {
+    "@frockbot/plugin-tools": "0.1.0",
+    "@types/bun": "1.4.0",
+    "@vitejs/plugin-vue": "6.0.8",
+    "typescript": "5.9.3",
+    "vite": "8.2.2",
+    "vue-tsc": "3.3.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-bot-template"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/agent.test.ts

@@ -0,0 +1,194 @@
+// The Bot's own export tool: what it admits, what it stages, and what it says.
+import { describe, expect, it } from "bun:test";
+import {
+  SessionStore,
+  type Session,
+  type ToolCall,
+  type ToolExecutionContext,
+  type TurnTypeV1,
+} from "@frockbot/kernel-contracts";
+import { ToolRegistry } from "@frockbot/plugin-tools";
+import { Context } from "cordis";
+import {
+  BOT_EXPORT_TEMPLATE_TOOL_V1,
+  createBotTemplateRuntimePlugin,
+  stageCommandIdV1,
+} from "./agent.ts";
+import type { TemplateShareReceiptV1 } from "./shared.ts";
+
+const SESSION_ID = "user-1:budget";
+const SHARE_ID = `user-1.${"a".repeat(32)}`;
+
+function receipt(commandId: string): TemplateShareReceiptV1 {
+  return {
+    schemaVersion: 1,
+    commandId,
+    status: "applied",
+    share: {
+      schemaVersion: 1,
+      shareId: SHARE_ID,
+      hash: "b".repeat(64),
+      botId: "budget",
+      visibility: "private",
+      createdAt: "2026-08-31T00:00:00.000Z",
+    },
+    summary: {
+      schemaVersion: 1,
+      botId: "budget",
+      skills: 2,
+      routines: 1,
+      packages: 0,
+      publicServers: 0,
+      needsConnection: 1,
+      omitted: [{ reason: "memory", count: 1 }],
+    },
+  };
+}
+
+async function mount(
+  stage: (input: {
+    commandId: string;
+    botId: string;
+  }) => Promise<TemplateShareReceiptV1> = (input) =>
+    Promise.resolve(receipt(input.commandId)),
+) {
+  const root = new Context();
+  await root.plugin(SessionStore);
+  await root.plugin(ToolRegistry);
+  const session: Session = root.sessions.create(SESSION_ID);
+  session.appendBatch([
+    { type: "turn/start", turn: 1 },
+    { type: "step/start", turn: 1, step: 0 },
+  ]);
+  await root.plugin(
+    createBotTemplateRuntimePlugin({
+      owner: { userId: "user-1", botId: "budget" },
+      stageTemplate: stage,
+    }),
+  );
+  return { root, session, dispose: () => root.fiber.dispose() };
+}
+
+function contextFor(turnType: TurnTypeV1): ToolExecutionContext {
+  return {
+    botId: "budget",
+    agentId: "budget",
+    sessionId: SESSION_ID,
+    compositionGenerationId: "2026-08-31T00:00:00.000Z:0123456789abcdef",
+    turnType,
+    effectId: "tool:1:0:0",
+    signal: new AbortController().signal,
+  };
+}
+
+const call: ToolCall = {
+  id: "call-1",
+  name: BOT_EXPORT_TEMPLATE_TOOL_V1,
+  input: {},
+};
+
+async function invoke(
+  mounted: Awaited<ReturnType<typeof mount>>,
+  turnType: TurnTypeV1,
+) {
+  const context = contextFor(turnType);
+  const preparation = await mounted.root.tools.prepare(call, context);
+  if (preparation.kind === "denied") return preparation.result;
+  return mounted.root.tools.executePrepared(preparation, context);
+}
+
+describe("bot_export_template", () => {
+  it("is offered on chat turns only", async () => {
+    const mounted = await mount();
+    try {
+      const names = (turnType: TurnTypeV1) =>
+        mounted.root.tools.schemas({ turnType }).map((tool) => tool.name);
+      expect(names("chat")).toContain(BOT_EXPORT_TEMPLATE_TOOL_V1);
+      for (const turnType of ["automation", "subagent"] as const) {
+        expect(names(turnType)).not.toContain(BOT_EXPORT_TEMPLATE_TOOL_V1);
+      }
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  it("declares itself idempotent", async () => {
+    const mounted = await mount();
+    try {
+      const preparation = await mounted.root.tools.prepare(
+        call,
+        contextFor("chat"),
+      );
+      expect(preparation.kind).toBe("ready");
+      if (preparation.kind === "ready") {
+        expect(preparation.idempotent).toBe(true);
+      }
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  it("stages with a command id derived from the occurrence", async () => {
+    const staged: string[] = [];
+    const mounted = await mount((input) => {
+      staged.push(input.commandId);
+      return Promise.resolve(receipt(input.commandId));
+    });
+    try {
+      await invoke(mounted, "chat");
+      await invoke(mounted, "chat");
+      expect(staged).toEqual([
+        stageCommandIdV1("tool:1:0:0"),
+        stageCommandIdV1("tool:1:0:0"),
+      ]);
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  it("records an agent-card naming what was packed and scrubbed", async () => {
+    const mounted = await mount();
+    try {
+      const result = await invoke(mounted, "chat");
+      expect(result.isError).toBe(false);
+      expect(result.content).toContain(SHARE_ID);
+      const sends = mounted.session.events.filter(
+        (event) => event.type === "send/to-user",
+      );
+      expect(sends).toHaveLength(1);
+      const payload = (sends[0] as { payload: Record<string, unknown> })
+        .payload;
+      expect(payload.type).toBe("agent-card");
+      expect(payload.title).toBe("Bot template staged");
+      expect(String(payload.body)).toContain("Memory");
+      expect(String(payload.body)).toContain(
+        "Nothing is shared until you choose",
+      );
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  it("never leaves the Turn, so the card is not the last word", async () => {
+    const mounted = await mount();
+    try {
+      const result = await invoke(mounted, "chat");
+      expect(result.endsTurn).toBeUndefined();
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  it("reports a staging failure as a refusal, not a throw", async () => {
+    const mounted = await mount(() =>
+      Promise.reject(new Error("the User authority is unavailable")),
+    );
+    try {
+      const result = await invoke(mounted, "chat");
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("the User authority is unavailable");
+    } finally {
+      await mounted.dispose();
+    }
+  });
+});

package/src/agent.ts

@@ -0,0 +1,221 @@
+// The Bot's own `bot_export_template`.
+//
+// GATE. Register line 446: `create_bot_share_json` is gated by `gates.botShare`
+// — a turn-type gate. The manifest Capability declares `turnTypes: ["chat"]`,
+// and the registration reads that ceiling back out of the manifest rather than
+// restating it, so an automation or subagent Turn is never offered
+// this tool. Packing a Bot into a shareable recipe is a thing a User is in the
+// room for.
+//
+// AUTHORITY. The tool *stages*, and staging is always `visibility: "private"`.
+// "Publication beyond the authoring User is a User action": choosing `link` or
+// `public` is a click in Bot settings, and there is no tool argument, no
+// second tool, and no host method here that could do it. What the tool returns
+// is an `agent-card` naming what was packed and what was scrubbed — the one
+// voice a Bot has to its User (`kernel-contracts/src/send-to-user.ts`).
+//
+// REPLAY. `idempotent: true`, and honestly so: the staging command id is
+// derived from the durable tool-call occurrence, so a replay after eviction
+// carries the same `commandId`, meets the receipt the User Durable Object
+// already wrote, and reports the share it already made instead of staging a
+// second one.
+import {
+  decodeTurnTypeV1,
+  type Session,
+  type ToolDefinition,
+  type ToolExecutionContext,
+  type ToolExecutionResult,
+  type TurnTypeV1,
+} from "@frockbot/kernel-contracts";
+// Merges the Agent loop's event declarations into the cordis Context type.
+import type {} from "@frockbot/kernel-agent-loop/agent";
+import type { Plugin } from "cordis";
+import manifest from "../frockbot.json" with { type: "json" };
+import { describeTemplateSummaryV1 } from "./scrub.js";
+import type { TemplateShareReceiptV1 } from "./shared.js";
+
+export const BOT_EXPORT_TEMPLATE_TOOL_V1 = "bot_export_template";
+export const BOT_TEMPLATE_EXPORT_CAPABILITY_V1 = "bot-template-export";
+
+/** The User and Bot one admitted Turn's export runs as. */
+export interface BotTemplateOwnerV1 {
+  userId: string;
+  botId: string;
+}
+
+/**
+ * The host seam, supplied by the Bot Durable Object for one admitted Turn.
+ *
+ * Exactly one method, and it is the User's own `template/stage` command. There
+ * is no `setVisibility` here and no `revoke`: a Bot cannot publish, so the seam
+ * it holds cannot express publication.
+ */
+export interface BotTemplateRuntimeHostV1 {
+  owner: BotTemplateOwnerV1;
+  stageTemplate(input: {
+    commandId: string;
+    botId: string;
+  }): Promise<TemplateShareReceiptV1>;
+}
+
+/** The manifest's own ceiling for a Capability, read back from the manifest. */
+export function botTemplateAdmissionCeilingV1(
+  capabilityId: string,
+): readonly TurnTypeV1[] | undefined {
+  const capabilities = (
+    manifest as {
+      configuration?: {
+        capabilities?: Array<{
+          id: string;
+          admission?: { turnTypes: string[] };
+        }>;
+      };
+    }
+  ).configuration?.capabilities;
+  const turnTypes = capabilities?.find(
+    (candidate) => candidate.id === capabilityId,
+  )?.admission?.turnTypes;
+  if (!turnTypes) return undefined;
+  return turnTypes.map((turnType) =>
+    decodeTurnTypeV1(
+      turnType,
+      `bot-template capability "${capabilityId}" admission`,
+    ),
+  );
+}
+
+function refusal(reason: string): ToolExecutionResult {
+  return { content: reason, isError: true };
+}
+
+/** The open step a send belongs to, mirroring the Shell's own rule. */
+function openStepPositionV1(
+  session: Session,
+  tool: string,
+): { turn: number; step: number } {
+  const started = session.events.findLast(
+    (event) => event.type === "step/start",
+  );
+  const ended = session.events.findLast((event) => event.type === "step/end");
+  if (started?.type !== "step/start") {
+    throw new Error(`${tool} has no open step to record against`);
+  }
+  if (
+    ended?.type === "step/end" &&
+    ended.turn === started.turn &&
+    ended.step === started.step
+  ) {
+    throw new Error(`${tool} has no open step to record against`);
+  }
+  return { turn: started.turn, step: started.step };
+}
+
+/** A `commandId` derived from the occurrence, so a retry reuses one receipt. */
+export function stageCommandIdV1(effectId: string): string {
+  return `template-stage-${effectId.replace(/[^a-zA-Z0-9._-]/g, "-")}`.slice(
+    0,
+    120,
+  );
+}
+
+const DESCRIPTION = [
+  "Pack yourself into a shareable Bot template: a recipe, not a backup.",
+  "It carries your name, description, your own Skills, your Routines' prompts,",
+  "the Catalog Packages your User installed, and public MCP server addresses.",
+  "It never carries Memory, credentials, Connections, Assignments, your model,",
+  "webhook keys, uploaded images, or anything from your Computer.",
+  "The template is staged privately and shared with nobody:",
+  "only your User can choose to publish it, from Bot settings.",
+].join(" ");
+
+export function createBotExportTemplateTool(
+  host: BotTemplateRuntimeHostV1,
+  sessions: { get(sessionId: string): Session | undefined },
+): ToolDefinition {
+  return {
+    name: BOT_EXPORT_TEMPLATE_TOOL_V1,
+    description: DESCRIPTION,
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    admission: { turnTypes: ["chat"] },
+    // The staging command id is derived from the occurrence, so re-running
+    // meets the durable receipt and reports the same share.
+    idempotent: true,
+    validate: (input: unknown) =>
+      input === undefined ||
+      (typeof input === "object" &&
+        input !== null &&
+        !Array.isArray(input) &&
+        Object.keys(input).length === 0),
+    execute: async (
+      _input: unknown,
+      context: ToolExecutionContext,
+    ): Promise<ToolExecutionResult> => {
+      let receipt: TemplateShareReceiptV1;
+      try {
+        receipt = await host.stageTemplate({
+          commandId: stageCommandIdV1(context.effectId),
+          botId: host.owner.botId,
+        });
+      } catch (error) {
+        return refusal(
+          `${BOT_EXPORT_TEMPLATE_TOOL_V1} failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      const body = receipt.summary
+        ? describeTemplateSummaryV1(receipt.summary)
+        : "The template was staged privately. Nothing is shared until your User chooses a visibility.";
+      const session = sessions.get(context.sessionId);
+      if (session) {
+        try {
+          session.append({
+            type: "send/to-user",
+            ...openStepPositionV1(session, BOT_EXPORT_TEMPLATE_TOOL_V1),
+            occurrenceId: context.effectId,
+            payload: {
+              type: "agent-card",
+              agentId: host.owner.botId,
+              title: "Bot template staged",
+              body,
+            },
+          });
+          await session.flush();
+        } catch {
+          // The share is already durable. A card that could not be recorded is
+          // a missing card, never a reason to look as if the export failed.
+        }
+      }
+      return {
+        content: `Staged a private Bot template (${receipt.share.shareId}). ${body}`,
+        isError: false,
+      };
+    },
+  };
+}
+
+/**
+ * The runtime Contribution. One tool, bounded by the manifest's own ceiling,
+ * and registered only when the host seam exists — a Turn with no User authority
+ * to stage through is a Turn where the tool is simply absent.
+ */
+export function createBotTemplateRuntimePlugin(
+  host: BotTemplateRuntimeHostV1,
+): Plugin.Function {
+  const plugin: Plugin.Function = (ctx) => {
+    const ceiling = botTemplateAdmissionCeilingV1(
+      BOT_TEMPLATE_EXPORT_CAPABILITY_V1,
+    );
+    const dispose = ctx.tools.register(
+      createBotExportTemplateTool(host, ctx.sessions),
+      ceiling ? { admissionCeiling: ceiling } : undefined,
+    );
+    return () => dispose();
+  };
+  plugin.inject = ["tools", "sessions"];
+  return plugin;
+}
+
+export default createBotTemplateRuntimePlugin;