@frockbot/plugin-flock 0.0.0 → 0.1.0

package/frockbot.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 3,
+  "id": "flock",
+  "displayName": "Flock",
+  "version": "0.0.1",
+  "compatibility": { "frockbot": ">=0.0.1" },
+  "dependencies": {
+    "shell": ">=0.0.1",
+    "ui-theme": ">=0.0.1"
+  },
+  "contributions": {
+    "backend": [
+      { "entry": "./backend", "host": "gateway" },
+      { "entry": "./user", "host": "user" },
+      { "entry": "./bot", "host": "bot" }
+    ],
+    "runtime": { "entry": "./agent" },
+    "client": {
+      "entry": "./client",
+      "mounts": [
+        { "slot": "frockbot.sidebar-bots", "order": 10 },
+        { "slot": "frockbot.overlays", "order": 10 },
+        { "slot": "frockbot.bot-identity", "order": 10 },
+        { "slot": "frockbot.bot-avatar", "order": 10 },
+        { "slot": "frockbot.bot-avatar-editor", "order": 10 }
+      ],
+      "outlets": []
+    }
+  },
+  "permissions": ["bot:self-manage"],
+  "configuration": {
+    "settings": [],
+    "connectionTypes": [],
+    "capabilities": [
+      { "id": "bot-self-management", "kind": "tool", "connectionTypes": [] }
+    ]
+  }
+}

package/package.json

@@ -1,14 +1,55 @@
 {
   "name": "@frockbot/plugin-flock",
-  "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",
+    "./assets/manifest.json": "./assets/manifest.json",
+    "./backend": "./src/backend.ts",
+    "./bot": "./src/bot.ts",
+    "./client": "./src/client/index.ts",
+    "./client/BotAvatar.vue": "./src/client/BotAvatar.vue",
+    "./client/state": "./src/client/state.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./manifest": "./src/manifest.ts",
+    "./package.json": "./package.json",
+    "./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/kernel-contracts": "0.1.0",
+    "@frockbot/plugin-shell": "0.1.0",
+    "cordis": "4.0.0-rc.8",
+    "vue": "3.5.41"
+  },
+  "devDependencies": {
+    "@frockbot/plugin-testkit": "0.1.0",
+    "@types/bun": "1.4.0",
+    "@vitejs/plugin-vue": "6.0.8",
+    "css-tree": "2.3.1",
+    "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-flock"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/agent.test.ts

@@ -0,0 +1,401 @@
+// The Flock runtime Contribution: what a Bot may change about itself, what it
+// records when it does, and what it refuses.
+//
+// The host here is a small in-memory stand-in for the two Durable Objects,
+// built out of the production `applyBotProfilePatchV1` and the production
+// `FlockUserBackendContribution`, so what these prove is the real partial-patch
+// and directory behaviour rather than a double's.
+import { describe, expect, test } from "bun:test";
+import {
+  applyBotProfilePatchV1,
+  ConfigurationConflictError,
+  initializeBotSettingsV1,
+  type BotSettingsViewV1,
+  type ConfigurationCommandV1,
+  type OperationReceiptV1,
+} from "@frockbot/configuration-core";
+import type { SessionEvent } from "@frockbot/kernel-contracts";
+import {
+  createBotCreateTool,
+  createBotUpdateTool,
+  createdBotIdV1,
+  decodeBotUpdateInputV1,
+  type FlockSelfRuntimeHostV1,
+} from "./agent.ts";
+import { createFlockUserBackendContribution } from "./user.ts";
+import { decodeCreateBotCommandV1 } from "./shared.ts";
+
+const OWNER = { userId: "user-1", botId: "bot-1" };
+const WRITER = {
+  kind: "bot" as const,
+  botId: "bot-1",
+  sessionId: "user-1:bot-1",
+  turnId: "turn-4",
+};
+
+const CONTEXT = {
+  botId: "bot-1",
+  agentId: "bot-1",
+  sessionId: "user-1:bot-1",
+  compositionGenerationId: "2026-08-31T00:00:00.000Z:0123456789abcdef",
+  turnType: "chat" as const,
+  effectId: "tool:1:1:0",
+  signal: new AbortController().signal,
+};
+
+/** An in-memory Durable Object storage with the transaction seam Flock uses. */
+function memoryStorage() {
+  const map = new Map<string, unknown>();
+  const surface = {
+    get: async <T>(key: string) => map.get(key) as T | undefined,
+    put: async (key: unknown, value?: unknown) => {
+      if (typeof key === "string") map.set(key, value);
+      else
+        for (const [entry, item] of Object.entries(
+          key as Record<string, unknown>,
+        ))
+          map.set(entry, item);
+    },
+    delete: async (key: string) => map.delete(key),
+    list: async <T>({ prefix }: { prefix: string }) =>
+      new Map(
+        [...map.entries()]
+          .filter(([key]) => key.startsWith(prefix))
+          .map(([key, value]) => [key, value as T]),
+      ),
+    setAlarm: async () => {},
+  };
+  return {
+    ...surface,
+    transaction: async <T>(callback: (tx: typeof surface) => Promise<T>) =>
+      callback(surface),
+  };
+}
+
+interface Harness {
+  host: FlockSelfRuntimeHostV1;
+  settings(): BotSettingsViewV1;
+  announcements(): SessionEvent[];
+  commands(): Array<Extract<ConfigurationCommandV1, { botId: string }>>;
+  /** Forces the next `commandSelf` to lose an optimistic race exactly once. */
+  raceOnce(): void;
+}
+
+function harness(initial?: Partial<BotSettingsViewV1>): Harness {
+  let settings: BotSettingsViewV1 = {
+    ...initializeBotSettingsV1("bot-1"),
+    profile: { name: "General" },
+    ...initial,
+  };
+  const announcements: SessionEvent[] = [];
+  const commands: Array<Extract<ConfigurationCommandV1, { botId: string }>> =
+    [];
+  let race = false;
+  const storage = memoryStorage();
+  const flock = createFlockUserBackendContribution({
+    storage,
+    readUserSettings: () =>
+      Promise.resolve({
+        schemaVersion: 1,
+        revision: 0,
+        profile: { name: "User" },
+        packages: [],
+        connections: [],
+      }),
+    now: () => new Date("2026-08-31T10:00:00.000Z"),
+    random: () => 0,
+    commandBotLifecycle: () => {
+      throw new Error("not used");
+    },
+    readBotLifecycle: () => {
+      throw new Error("not used");
+    },
+  });
+  return {
+    settings: () => settings,
+    announcements: () => announcements,
+    commands: () => commands,
+    raceOnce: () => {
+      race = true;
+    },
+    host: {
+      owner: OWNER,
+      writer: WRITER,
+      readSelf: async () => structuredClone(settings),
+      commandSelf: async (command): Promise<OperationReceiptV1> => {
+        if (race) {
+          race = false;
+          settings = { ...settings, revision: settings.revision + 1 };
+          throw new ConfigurationConflictError(settings.revision);
+        }
+        if (command.expectedRevision !== settings.revision) {
+          throw new ConfigurationConflictError(settings.revision);
+        }
+        commands.push(command);
+        const revision = settings.revision + 1;
+        if (command.type === "bot/set-profile") {
+          const profile = applyBotProfilePatchV1(
+            settings.profile,
+            command.profile,
+            command.namedBy ?? "user",
+          );
+          // The Bot Durable Object appends the announcement in the same
+          // transaction that writes the name; the seam is reproduced here.
+          if (profile.name !== settings.profile.name) {
+            announcements.push({
+              type: "bot/renamed",
+              seq: announcements.length,
+              timestamp: "2026-08-31T10:00:00.000Z",
+              from: settings.profile.name,
+              to: profile.name,
+              namedBy: profile.namedBy ?? "user",
+              ...(command.writer ? { writer: command.writer } : {}),
+            });
+          }
+          settings = { ...settings, revision, profile };
+        } else if (command.type === "bot/update-notifications") {
+          settings = {
+            ...settings,
+            revision,
+            notifications: command.notifications,
+          };
+        } else {
+          throw new Error(`unexpected command ${command.type}`);
+        }
+        return {
+          schemaVersion: 1,
+          commandId: command.commandId,
+          revision,
+          status: "applied",
+        };
+      },
+      listBots: () => flock.listBots(),
+      createBot: (command) =>
+        // The command crosses the User Durable Object seam, so it decodes on
+        // the way in exactly as the production RPC does.
+        flock.createBot(OWNER.userId, decodeCreateBotCommandV1(command)),
+    },
+  };
+}
+
+describe("bot_update", () => {
+  test("changes only the fields it was given", async () => {
+    const test1 = harness({
+      profile: { name: "General", description: "A helper.", title: "Aide" },
+    });
+    const tool = createBotUpdateTool(test1.host);
+
+    const result = await tool.execute({ title: "Chief of staff" }, CONTEXT);
+
+    expect(result.isError).toBe(false);
+    expect(test1.settings().profile).toEqual({
+      name: "General",
+      description: "A helper.",
+      title: "Chief of staff",
+    });
+    expect(test1.announcements()).toEqual([]);
+  });
+
+  test("clears an optional field with the empty string", async () => {
+    const test1 = harness({
+      profile: { name: "General", title: "Aide", description: "A helper." },
+    });
+
+    await createBotUpdateTool(test1.host).execute({ title: "" }, CONTEXT);
+
+    expect(test1.settings().profile).toEqual({
+      name: "General",
+      description: "A helper.",
+    });
+  });
+
+  test("a self-rename records the Bot as the writer and announces it", async () => {
+    const test1 = harness();
+
+    const result = await createBotUpdateTool(test1.host).execute(
+      { name: "Chief of staff" },
+      CONTEXT,
+    );
+
+    expect(result.isError).toBe(false);
+    expect(test1.settings().profile).toEqual({
+      name: "Chief of staff",
+      namedBy: "bot",
+    });
+    expect(test1.announcements()).toEqual([
+      {
+        type: "bot/renamed",
+        seq: 0,
+        timestamp: "2026-08-31T10:00:00.000Z",
+        from: "General",
+        to: "Chief of staff",
+        namedBy: "bot",
+        writer: WRITER,
+      },
+    ]);
+    // The provenance the command carried is the Bot itself, never a target.
+    const command = test1.commands()[0]!;
+    expect(command.type).toBe("bot/set-profile");
+    expect(
+      command.type === "bot/set-profile" ? command.namedBy : undefined,
+    ).toBe("bot");
+    expect(
+      command.type === "bot/set-profile" ? command.writer : undefined,
+    ).toEqual(WRITER);
+  });
+
+  test("writes nothing when the profile already holds every value", async () => {
+    const test1 = harness({ profile: { name: "General", title: "Aide" } });
+
+    const result = await createBotUpdateTool(test1.host).execute(
+      { title: "Aide" },
+      CONTEXT,
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("Nothing changed");
+    expect(test1.commands()).toEqual([]);
+  });
+
+  test("a replay after eviction re-runs without a second announcement", async () => {
+    const test1 = harness();
+    const tool = createBotUpdateTool(test1.host);
+
+    await tool.execute({ name: "Chief of staff" }, CONTEXT);
+    // The registry recovers an idempotent tool by executing it again under the
+    // same effect id.
+    expect(tool.idempotent).toBe(true);
+    const replay = await tool.execute({ name: "Chief of staff" }, CONTEXT);
+
+    expect(replay.isError).toBe(false);
+    expect(test1.announcements()).toHaveLength(1);
+    expect(test1.commands()).toHaveLength(1);
+  });
+
+  test("changes notifications alongside the profile", async () => {
+    const test1 = harness();
+
+    const result = await createBotUpdateTool(test1.host).execute(
+      { title: "Aide", notify_on_updates: false },
+      CONTEXT,
+    );
+
+    expect(result.isError).toBe(false);
+    expect(test1.settings().notifications).toEqual({ enabled: false });
+    expect(test1.commands().map((command) => command.type)).toEqual([
+      "bot/set-profile",
+      "bot/update-notifications",
+    ]);
+  });
+
+  test("re-issues the command after losing an optimistic race", async () => {
+    const test1 = harness();
+    test1.raceOnce();
+
+    const result = await createBotUpdateTool(test1.host).execute(
+      { title: "Aide" },
+      CONTEXT,
+    );
+
+    expect(result.isError).toBe(false);
+    expect(test1.settings().profile.title).toBe("Aide");
+  });
+
+  test("refuses an empty call, an unknown field, and a blank name", () => {
+    expect(() => decodeBotUpdateInputV1({})).toThrow();
+    expect(() => decodeBotUpdateInputV1({ archived: true })).toThrow();
+    expect(() => decodeBotUpdateInputV1({ name: "  " })).toThrow();
+  });
+
+  test("offers no way to archive, restore, or delete a Bot", () => {
+    const tool = createBotUpdateTool(harness().host);
+    const schema = tool.inputSchema as { properties: Record<string, unknown> };
+
+    expect(Object.keys(schema.properties)).toEqual([
+      "name",
+      "description",
+      "title",
+      "hidden_from_sidebar",
+      "notify_on_updates",
+    ]);
+  });
+});
+
+describe("bot_create", () => {
+  test("registers one Bot in the User's flock with its description", async () => {
+    const test1 = harness();
+
+    const result = await createBotCreateTool(test1.host).execute(
+      { name: "Budget", description: "Watches the money." },
+      CONTEXT,
+    );
+
+    expect(result.isError).toBe(false);
+    const directory = await test1.host.listBots();
+    expect(directory.bots).toHaveLength(1);
+    const created = directory.bots[0]!;
+    expect(created.initialName).toBe("Budget");
+    expect(created.initialDescription).toBe("Watches the money.");
+    expect(created.botId).toBe(
+      await createdBotIdV1(OWNER, CONTEXT.effectId, "Budget"),
+    );
+    // The new Bot receives no authority beyond what `bot/create` grants: no
+    // model of its own and no Assignment.
+    expect(created.initialModel).toBeUndefined();
+    expect(created.initialModelBinding).toBeUndefined();
+    expect(result.content).toContain(created.botId);
+  });
+
+  test("records the creating Bot and Turn on the registration", async () => {
+    const test1 = harness();
+
+    await createBotCreateTool(test1.host).execute({ name: "Budget" }, CONTEXT);
+
+    expect((await test1.host.listBots()).bots[0]!.createdBy).toEqual(WRITER);
+  });
+
+  test("a replay after eviction creates exactly one Bot", async () => {
+    const test1 = harness();
+    const tool = createBotCreateTool(test1.host);
+    expect(tool.idempotent).toBe(true);
+
+    const first = await tool.execute({ name: "Budget" }, CONTEXT);
+    const replay = await tool.execute({ name: "Budget" }, CONTEXT);
+
+    expect(first.isError).toBe(false);
+    expect(replay.isError).toBe(false);
+    expect(replay.content).toContain("already exists");
+    expect((await test1.host.listBots()).bots).toHaveLength(1);
+  });
+
+  test("a different occurrence creates a distinct Bot", async () => {
+    const test1 = harness();
+    const tool = createBotCreateTool(test1.host);
+
+    await tool.execute({ name: "Budget" }, CONTEXT);
+    await tool.execute(
+      { name: "Budget" },
+      { ...CONTEXT, effectId: "tool:1:3:0" },
+    );
+
+    const ids = (await test1.host.listBots()).bots.map((bot) => bot.botId);
+    expect(new Set(ids).size).toBe(2);
+  });
+
+  test("refuses a nameless call and an unknown field", async () => {
+    const tool = createBotCreateTool(harness().host);
+
+    expect(tool.validate?.({})).toBe(false);
+    expect(tool.validate?.({ name: "Budget", model: "glm" })).toBe(false);
+    expect(tool.validate?.({ name: "Budget" })).toBe(true);
+  });
+});
+
+describe("the self-management seam", () => {
+  test("both tools are work tools, offered on every turn type", () => {
+    const host = harness().host;
+
+    expect(createBotUpdateTool(host).admission).toBeUndefined();
+    expect(createBotCreateTool(host).admission).toBeUndefined();
+  });
+});