@frockbot/plugin-shell 0.0.0 → 0.1.1

package/frockbot.json

@@ -0,0 +1,68 @@
+{
+  "schemaVersion": 4,
+  "id": "shell",
+  "displayName": "FrockBot Shell",
+  "version": "0.0.1",
+  "compatibility": {
+    "frockbot": ">=0.0.1"
+  },
+  "dependencies": {
+    "ui-theme": ">=0.0.1"
+  },
+  "contributions": {
+    "backend": [
+      {
+        "entry": "./backend",
+        "host": "bot"
+      }
+    ],
+    "runtime": {
+      "entry": "./agent"
+    },
+    "client": {
+      "entry": "./client",
+      "mounts": [
+        {
+          "slot": "authenticated-root",
+          "order": 10000
+        }
+      ],
+      "outlets": [
+        "frockbot.right-panel",
+        "frockbot.computer",
+        "frockbot.sidebar-bots",
+        "frockbot.sidebar-computer",
+        "frockbot.sidebar-actions",
+        "frockbot.user-profile",
+        "frockbot.bot-actions",
+        "frockbot.header-actions",
+        "frockbot.overlays",
+        "frockbot.bot-identity",
+        "frockbot.bot-avatar"
+      ]
+    }
+  },
+  "permissions": ["agent:turn"],
+  "configuration": {
+    "settings": [],
+    "connectionTypes": [],
+    "capabilities": [
+      {
+        "id": "user-voice",
+        "kind": "tool",
+        "connectionTypes": [],
+        "admission": {
+          "turnTypes": ["chat"]
+        }
+      },
+      {
+        "id": "parent-handoff",
+        "kind": "tool",
+        "connectionTypes": [],
+        "admission": {
+          "turnTypes": ["automation", "subagent"]
+        }
+      }
+    ]
+  }
+}

package/package.json

@@ -1,14 +1,95 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./agent": "./src/agent.ts",
+    "./approvals": "./src/approvals.ts",
+    "./backend": "./src/backend.ts",
+    "./backend-authoring": "./src/backend-authoring.ts",
+    "./backend-composition": "./src/backend-composition.ts",
+    "./backend-computer": "./src/backend-computer.ts",
+    "./backend-contracts": "./src/backend-contracts.ts",
+    "./backend-execution": "./src/backend-execution.ts",
+    "./backend-image": "./src/backend-image.ts",
+    "./backend-isolate": "./src/backend-isolate.ts",
+    "./backend-memory": "./src/backend-memory.ts",
+    "./backend-recovery": "./src/backend-recovery.ts",
+    "./backend-runner": "./src/backend-runner.ts",
+    "./backend-skills": "./src/backend-skills.ts",
+    "./backend-subagents": "./src/backend-subagents.ts",
+    "./client": "./src/client/index.ts",
+    "./debug-protocol": "./src/debug-protocol.ts",
+    "./client/FrockBotApp.vue": "./src/client/FrockBotApp.vue",
+    "./client/notify": "./src/client/notify.ts",
+    "./client/styles.css": "./src/client/styles.css",
+    "./frockbot.json": "./frockbot.json",
+    "./host": "./src/host.ts",
+    "./manifest": "./src/manifest.ts",
+    "./package.json": "./package.json",
+    "./run-cursor": "./src/run-cursor.ts",
+    "./run-protocol": "./src/run-protocol.ts",
+    "./settings-links": "./src/settings-links.ts",
+    "./shared": "./src/shared.ts",
+    "./skill-protocol": "./src/skill-protocol.ts",
+    "./unread": "./src/unread.ts"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@cordisjs/plugin-webui": "0.8.2",
+    "@frockbot/agent-runtime": "0.1.1",
+    "@frockbot/application-foundation": "0.1.1",
+    "@frockbot/catalog-core": "0.1.1",
+    "@frockbot/client-core": "0.1.1",
+    "@frockbot/client-ui": "0.1.1",
+    "@frockbot/computer-core": "0.1.1",
+    "@frockbot/computer-host-protocol": "0.1.1",
+    "@frockbot/configuration-core": "0.1.1",
+    "@frockbot/connection-core": "0.1.1",
+    "@frockbot/kernel-agent-loop": "0.1.1",
+    "@frockbot/kernel-composition": "0.1.1",
+    "@frockbot/kernel-contracts": "0.1.1",
+    "@frockbot/kernel-do": "0.1.1",
+    "@frockbot/machine-protocol": "0.1.1",
+    "@frockbot/plugin-authoring": "0.1.1",
+    "@frockbot/plugin-bot-template": "0.1.1",
+    "@frockbot/plugin-flock": "0.1.1",
+    "@frockbot/plugin-image": "0.1.1",
+    "@frockbot/plugin-machine-messages": "0.1.1",
+    "@frockbot/plugin-mcp": "0.1.1",
+    "@frockbot/plugin-memory": "0.1.1",
+    "@frockbot/plugin-routines": "0.1.1",
+    "@frockbot/plugin-skills": "0.1.1",
+    "@frockbot/plugin-subagents": "0.1.1",
+    "@frockbot/plugin-user-machine": "0.1.1",
+    "@frockbot/protocol": "0.1.1",
+    "cordis": "4.0.0-rc.8",
+    "vue": "3.5.41"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "latest",
+    "@frockbot/plugin-tools": "0.1.1",
+    "@types/bun": "1.3.6",
+    "@types/node": "26.2.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-shell"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/agent.test.ts

@@ -0,0 +1,372 @@
+// The Shell's runtime Contribution: what it admits, what it records, and what
+// ends a Turn.
+import { describe, expect, test } 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 {
+  shellAdmissionCeilingV1,
+  shellAgentPlugin,
+  PARENT_HANDOFF_CAPABILITY_V1,
+  SEND_MESSAGE_ALIAS_V1,
+  SEND_TO_USER_TOOL_V1,
+  USER_VOICE_CAPABILITY_V1,
+  WAKE_PARENT_TOOL_V1,
+} from "./agent.ts";
+
+const SESSION_ID = "user-1:bot-1";
+
+interface Mounted {
+  root: Context;
+  session: Session;
+  dispose(): Promise<void>;
+}
+
+async function mount(): Promise<Mounted> {
+  const root = new Context();
+  await root.plugin(SessionStore);
+  await root.plugin(ToolRegistry);
+  const session = root.sessions.create(SESSION_ID);
+  session.appendBatch([
+    { type: "turn/start", turn: 4 },
+    { type: "step/start", turn: 4, step: 2 },
+  ]);
+  await root.plugin(shellAgentPlugin);
+  return { root, session, dispose: () => root.fiber.dispose() };
+}
+
+function contextFor(turnType: TurnTypeV1): ToolExecutionContext {
+  return {
+    botId: "bot-1",
+    agentId: "bot-1",
+    sessionId: SESSION_ID,
+    compositionGenerationId: "2026-08-31T00:00:00.000Z:0123456789abcdef",
+    turnType,
+    effectId: "tool:4:2:0",
+    signal: new AbortController().signal,
+  };
+}
+
+function call(name: string, input: unknown): ToolCall {
+  return { id: "call-1", name, input };
+}
+
+/** Runs a tool the way the loop does: prepare, then execute what it admits. */
+async function invoke(
+  mounted: Mounted,
+  turnType: TurnTypeV1,
+  toolCall: ToolCall,
+) {
+  const context = contextFor(turnType);
+  const preparation = await mounted.root.tools.prepare(toolCall, context);
+  if (preparation.kind === "denied") return preparation.result;
+  return mounted.root.tools.executePrepared(preparation, context);
+}
+
+describe("the Shell's tool admission", () => {
+  test("offers the send tool and its alias on chat turns only", async () => {
+    const mounted = await mount();
+    try {
+      const chat = mounted.root.tools
+        .schemas({ turnType: "chat" })
+        .map((tool) => tool.name);
+      const automation = mounted.root.tools
+        .schemas({ turnType: "automation" })
+        .map((tool) => tool.name);
+      const subagent = mounted.root.tools
+        .schemas({ turnType: "subagent" })
+        .map((tool) => tool.name);
+
+      expect(chat).toContain(SEND_TO_USER_TOOL_V1);
+      expect(chat).toContain(SEND_MESSAGE_ALIAS_V1);
+      expect(chat).not.toContain(WAKE_PARENT_TOOL_V1);
+      expect(automation).toEqual([WAKE_PARENT_TOOL_V1]);
+      expect(subagent).toEqual([WAKE_PARENT_TOOL_V1]);
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("no role widens a subagent turn: chat-only tools are absent for all five", async () => {
+    const mounted = await mount();
+    try {
+      for (const subagentRole of [
+        "executor",
+        "browserUse",
+        "computerUse",
+        "watchVideo",
+        "videoReview",
+      ]) {
+        const names = mounted.root.tools
+          .schemas({ turnType: "subagent", subagentRole })
+          .map((tool) => tool.name);
+        // The turn-type ceiling comes first and no role can reach past it: the
+        // Shell's user-facing tools are chat-only, and the hand-off is the only
+        // thing any subagent role is offered here.
+        expect(names).not.toContain(SEND_TO_USER_TOOL_V1);
+        expect(names).not.toContain(SEND_MESSAGE_ALIAS_V1);
+        expect(names).toEqual([WAKE_PARENT_TOOL_V1]);
+      }
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("denies a hallucinated wake_parent on a chat turn", async () => {
+    const mounted = await mount();
+    try {
+      const result = await invoke(
+        mounted,
+        "chat",
+        call(WAKE_PARENT_TOOL_V1, { message: "done" }),
+      );
+
+      expect(result).toEqual({
+        content: `Tool is not available on a chat turn: ${WAKE_PARENT_TOOL_V1}`,
+        isError: true,
+      });
+      expect(
+        mounted.session.events.some((event) => event.type === "wake/parent"),
+      ).toBe(false);
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("denies send_to_user and its alias on an automation turn", async () => {
+    const mounted = await mount();
+    try {
+      for (const name of [SEND_TO_USER_TOOL_V1, SEND_MESSAGE_ALIAS_V1]) {
+        const result = await invoke(
+          mounted,
+          "automation",
+          call(name, { payload: { type: "text", text: "hi" } }),
+        );
+
+        expect(result).toEqual({
+          content: `Tool is not available on a automation turn: ${name}`,
+          isError: true,
+        });
+      }
+      expect(
+        mounted.session.events.some((event) => event.type === "send/to-user"),
+      ).toBe(false);
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("bounds each tool by the turn types its manifest Capability declares", () => {
+    expect(shellAdmissionCeilingV1(USER_VOICE_CAPABILITY_V1)).toEqual(["chat"]);
+    expect(shellAdmissionCeilingV1(PARENT_HANDOFF_CAPABILITY_V1)).toEqual([
+      "automation",
+      "subagent",
+    ]);
+    expect(shellAdmissionCeilingV1("not-a-capability")).toBeUndefined();
+  });
+});
+
+describe("send_to_user", () => {
+  test("records a text send and leaves the Turn running", async () => {
+    const mounted = await mount();
+    try {
+      const result = await invoke(
+        mounted,
+        "chat",
+        call(SEND_TO_USER_TOOL_V1, {
+          payload: { type: "text", text: "Booked for Tuesday." },
+        }),
+      );
+
+      expect(result.isError).toBe(false);
+      expect(result.endsTurn).toBeUndefined();
+      expect(
+        mounted.session.events.find((event) => event.type === "send/to-user"),
+      ).toMatchObject({
+        turn: 4,
+        step: 2,
+        occurrenceId: "tool:4:2:0",
+        payload: { type: "text", text: "Booked for Tuesday." },
+      });
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("ends the Turn on a widget and an approval, and on nothing else", async () => {
+    const mounted = await mount();
+    try {
+      const widget = await invoke(
+        mounted,
+        "chat",
+        call(SEND_TO_USER_TOOL_V1, {
+          payload: {
+            type: "widget",
+            widget: { prompt: "Which day?", options: ["Tue", "Thu"] },
+          },
+        }),
+      );
+      const attachment = await invoke(
+        mounted,
+        "chat",
+        call(SEND_TO_USER_TOOL_V1, {
+          payload: { type: "attachment", url: "https://files.example/a.pdf" },
+        }),
+      );
+
+      // An approval ends the Turn for the same reason a widget does: the Bot
+      // has nothing left to do until a person answers, and the answer is a
+      // later Turn's input rather than this one's.
+      const approval = await invoke(
+        mounted,
+        "chat",
+        call(SEND_TO_USER_TOOL_V1, {
+          payload: {
+            type: "approval",
+            approvalId: "ap-1",
+            action: "Delete the staging database",
+            risk: "high",
+          },
+        }),
+      );
+      const text = await invoke(
+        mounted,
+        "chat",
+        call(SEND_TO_USER_TOOL_V1, {
+          payload: { type: "text", text: "On it." },
+        }),
+      );
+      const secret = await invoke(
+        mounted,
+        "chat",
+        call(SEND_TO_USER_TOOL_V1, {
+          payload: {
+            type: "secret-request",
+            prompt: "Your API key",
+            secretName: "api_key",
+          },
+        }),
+      );
+      const card = await invoke(
+        mounted,
+        "chat",
+        call(SEND_TO_USER_TOOL_V1, {
+          payload: { type: "agent-card", agentId: "bot-2", title: "School" },
+        }),
+      );
+
+      expect(widget.endsTurn).toBe(true);
+      expect(approval.endsTurn).toBe(true);
+      expect(attachment.endsTurn).toBeUndefined();
+      expect(text.endsTurn).toBeUndefined();
+      expect(secret.endsTurn).toBeUndefined();
+      expect(card.endsTurn).toBeUndefined();
+      expect(
+        mounted.session.events
+          .filter((event) => event.type === "send/to-user")
+          .map((event) =>
+            event.type === "send/to-user" ? event.payload.type : undefined,
+          ),
+      ).toEqual([
+        "widget",
+        "attachment",
+        "approval",
+        "text",
+        "secret-request",
+        "agent-card",
+      ]);
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("refuses a malformed payload without recording anything", async () => {
+    const mounted = await mount();
+    try {
+      const result = await invoke(
+        mounted,
+        "chat",
+        call(SEND_TO_USER_TOOL_V1, { payload: { type: "shout", text: "hi" } }),
+      );
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("send_to_user.payload.type is invalid");
+      expect(result.endsTurn).toBeUndefined();
+      expect(
+        mounted.session.events.some((event) => event.type === "send/to-user"),
+      ).toBe(false);
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("records the alias under its own name and the same event", async () => {
+    const mounted = await mount();
+    try {
+      const result = await invoke(
+        mounted,
+        "chat",
+        call(SEND_MESSAGE_ALIAS_V1, {
+          payload: { type: "text", text: "Legacy." },
+        }),
+      );
+
+      expect(result.isError).toBe(false);
+      expect(
+        mounted.session.events.find((event) => event.type === "send/to-user"),
+      ).toMatchObject({ payload: { type: "text", text: "Legacy." } });
+    } finally {
+      await mounted.dispose();
+    }
+  });
+});
+
+describe("wake_parent", () => {
+  test("records the hand-off and always ends the Turn", async () => {
+    const mounted = await mount();
+    try {
+      const result = await invoke(
+        mounted,
+        "automation",
+        call(WAKE_PARENT_TOOL_V1, { message: "The invoice is paid." }),
+      );
+
+      expect(result).toMatchObject({ isError: false, endsTurn: true });
+      expect(
+        mounted.session.events.find((event) => event.type === "wake/parent"),
+      ).toMatchObject({
+        turn: 4,
+        step: 2,
+        occurrenceId: "tool:4:2:0",
+        message: "The invoice is paid.",
+      });
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("refuses an empty hand-off rather than ending the Turn on nothing", async () => {
+    const mounted = await mount();
+    try {
+      const result = await invoke(
+        mounted,
+        "subagent",
+        call(WAKE_PARENT_TOOL_V1, { message: "   " }),
+      );
+
+      expect(result.isError).toBe(true);
+      expect(result.endsTurn).toBeUndefined();
+      expect(
+        mounted.session.events.some((event) => event.type === "wake/parent"),
+      ).toBe(false);
+    } finally {
+      await mounted.dispose();
+    }
+  });
+});