@frockbot/plugin-flock 0.3.16 → 0.3.17

package/frockbot.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 3,
+  "schemaVersion": 4,
   "id": "flock",
   "displayName": "Flock",
   "version": "0.0.1",
@@ -33,7 +33,13 @@
     "settings": [],
     "connectionTypes": [],
     "capabilities": [
-      { "id": "bot-self-management", "kind": "tool", "connectionTypes": [] }
+      { "id": "bot-self-management", "kind": "tool", "connectionTypes": [] },
+      {
+        "id": "bot-messaging",
+        "kind": "tool",
+        "connectionTypes": [],
+        "admission": { "turnTypes": ["chat"] }
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-flock",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "private": false,
   "type": "module",
   "exports": {
@@ -14,6 +14,7 @@
     "./client/state": "./src/client/state.ts",
     "./frockbot.json": "./frockbot.json",
     "./manifest": "./src/manifest.ts",
+    "./quota": "./src/quota.ts",
     "./package.json": "./package.json",
     "./shared": "./src/shared.ts",
     "./user": "./src/user.ts"
@@ -27,16 +28,16 @@
     "typecheck": "vue-tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/client-core": "0.3.16",
-    "@frockbot/client-ui": "0.3.16",
-    "@frockbot/configuration-core": "0.3.16",
-    "@frockbot/kernel-contracts": "0.3.16",
-    "@frockbot/plugin-shell": "0.3.16",
+    "@frockbot/client-core": "0.3.17",
+    "@frockbot/client-ui": "0.3.17",
+    "@frockbot/configuration-core": "0.3.17",
+    "@frockbot/kernel-contracts": "0.3.17",
+    "@frockbot/plugin-shell": "0.3.17",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
-    "@frockbot/plugin-testkit": "0.3.16",
+    "@frockbot/plugin-testkit": "0.3.17",
     "@types/bun": "1.4.0",
     "@vitejs/plugin-vue": "6.0.8",
     "css-tree": "2.3.1",

package/src/agent.test.ts

@@ -17,6 +17,8 @@ import {
 import type { SessionEvent } from "@frockbot/kernel-contracts";
 import {
   createBotCreateTool,
+  createBotMessageTool,
+  createTeammatesPromptSectionV1,
   createBotUpdateTool,
   createdBotIdV1,
   decodeBotUpdateInputV1,
@@ -162,6 +164,12 @@ function harness(initial?: Partial<BotSettingsViewV1>): Harness {
         };
       },
       listBots: () => flock.listBots(),
+      messageBot: async (request) => ({
+        targetBotId: request.targetBotId,
+        targetBotName: "Teammate",
+        runId: `agent-${request.effectId}`,
+        text: "Teammate answer",
+      }),
       createBot: (command) =>
         // The command crosses the User Durable Object seam, so it decodes on
         // the way in exactly as the production RPC does.
@@ -390,3 +398,34 @@ describe("the self-management seam", () => {
     expect(createBotCreateTool(host).admission).toBeUndefined();
   });
 });
+
+describe("bot_message", () => {
+  test("returns the target Bot's reply as the tool result", async () => {
+    const test1 = harness();
+    const result = await createBotMessageTool(test1.host).execute(
+      { target_id: "researcher", message: "What changed?" },
+      CONTEXT,
+    );
+
+    expect(result).toEqual({ content: "Teammate answer", isError: false });
+    expect(createBotMessageTool(test1.host).idempotent).toBe(true);
+  });
+
+  test("the teammates section names the other Bots and their descriptions", async () => {
+    const test1 = harness();
+    await createBotCreateTool(test1.host).execute(
+      { name: "Researcher", description: "Finds primary sources." },
+      CONTEXT,
+    );
+    const prompt = await createTeammatesPromptSectionV1(test1.host).render({
+      sessionId: "user-1:bot-1",
+      provider: "test",
+      model: "test",
+      turnType: "chat",
+    });
+
+    expect(prompt).toContain("<teammates>");
+    expect(prompt).toContain("Researcher");
+    expect(prompt).toContain("Finds primary sources.");
+  });
+});

package/src/agent.ts

@@ -1,12 +1,13 @@
-// The Flock runtime Contribution: a Bot's own self-management tools.
+// The Flock runtime Contribution: a Bot's flock tools and prompt context.
 //
-// GrokBot exposes two of these and no more (§2.12): `UpdateAgent`, where only
-// the fields the call carries change, and `CreateAgent`, which makes a new
-// agent in the same user's flock. **There is no delete tool** — deletion is a
+// GrokBot's self-management surface (§2.12) has `UpdateAgent`, where only the
+// fields the call carries change, and `CreateAgent`, which makes a new agent
+// in the same user's flock. **There is no delete tool** — deletion is a
 // user-only action — and this Package matches that: `bot_update` cannot
-// archive, restore, or remove anything, and no third tool exists to do it.
+// archive, restore, or remove anything. Direct Bot messaging is the separate
+// `bot_message` capability and does not mutate either Bot.
 //
-// AUTHORITY. "Self-modification never widens authority." Both tools run
+// AUTHORITY. "Self-modification never widens authority." The mutation tools run
 // through paths the Bot's User already owns:
 //
 //  - `bot_update` issues the same `bot/set-profile` command the settings UI
@@ -48,18 +49,23 @@ import {
   type OperationReceiptV1,
 } from "@frockbot/configuration-core";
 import type {
+  PromptSection,
   ToolDefinition,
   ToolExecutionContext,
   ToolExecutionResult,
+  TurnTypeV1,
 } from "@frockbot/kernel-contracts";
+import { decodeTurnTypeV1 } from "@frockbot/kernel-contracts";
 import type { Plugin } from "cordis";
 import {
   FlockConflictError,
+  isFlockIdentifier,
   randomSheepRecipeV1,
   type BotDirectoryViewV1,
   type CreateBotCommandV1,
   type FlockReceiptV1,
 } from "./shared.js";
+import manifest from "../frockbot.json" with { type: "json" };
 export type {
   BotDirectoryViewV1,
   CreateBotCommandV1,
@@ -79,10 +85,9 @@ export interface FlockSelfOwnerV1 {
  * not registered at all: a Bot changes itself only inside a Turn whose Session
  * and Turn its provenance can name.
  *
- * Every method is a command the User's own surfaces already issue. This
- * Package holds no authority: the Bot Durable Object owns the profile, the
- * User Durable Object owns the Flock directory, and neither is reachable from
- * here except through these four calls.
+ * This Package holds no authority: the Bot Durable Object owns profiles and
+ * Turn admission, while the User Durable Object owns the Flock directory and
+ * concurrency slots. Each is reachable only through the narrow calls below.
  */
 export interface FlockSelfRuntimeHostV1 {
   owner: FlockSelfOwnerV1;
@@ -98,8 +103,31 @@ export interface FlockSelfRuntimeHostV1 {
   listBots(): Promise<BotDirectoryViewV1>;
   /** The User's own `bot/create` path, and no wider. */
   createBot(command: CreateBotCommandV1): Promise<FlockReceiptV1>;
+  /** Ask another Bot registered to this same User. */
+  messageBot(request: BotMessageRequestV1): Promise<BotMessageOutcomeV1>;
+  /** Sender cue for an inbound agent Turn, when this is one. */
+  inboundAgent?:
+    { kind: "bot"; fromBotId: string; fromBotName: string } | { kind: "voice" };
 }
 
+export interface BotMessageRequestV1 {
+  targetBotId: string;
+  message: string;
+  effectId: string;
+}
+
+export interface BotMessageOutcomeV1 {
+  targetBotId: string;
+  targetBotName: string;
+  runId: string;
+  text: string;
+}
+
+export const BOT_MESSAGE_TOOL_V1 = "bot_message";
+export const BOT_MESSAGING_CAPABILITY_V1 = "bot-messaging";
+export const TEAMMATES_PROMPT_SECTION_V1 = "teammates";
+export const INBOUND_AGENT_PROMPT_SECTION_V1 = "agent-message";
+
 /** How many times a command is re-issued after losing an optimistic race. */
 const REVISION_RETRIES = 3;
 
@@ -159,6 +187,22 @@ const BOT_CREATE_SCHEMA = {
   additionalProperties: false,
 } as const;
 
+const BOT_MESSAGE_SCHEMA = {
+  type: "object",
+  properties: {
+    target_id: {
+      type: "string",
+      description: "The id of another Bot listed in <teammates>.",
+    },
+    message: {
+      type: "string",
+      description: "The complete question or task to send to that Bot.",
+    },
+  },
+  required: ["target_id", "message"],
+  additionalProperties: false,
+} as const;
+
 interface BotUpdateInputV1 {
   profile: BotProfilePatchV1;
   notifyOnUpdates?: boolean;
@@ -169,6 +213,11 @@ interface BotCreateInputV1 {
   description?: string;
 }
 
+interface BotMessageInputV1 {
+  targetId: string;
+  message: string;
+}
+
 function fields(
   input: unknown,
   allowed: readonly string[],
@@ -266,6 +315,37 @@ export function decodeBotCreateInputV1(input: unknown): BotCreateInputV1 {
   };
 }
 
+export function decodeBotMessageInputV1(input: unknown): BotMessageInputV1 {
+  const value = fields(input, ["target_id", "message"]);
+  if (!isFlockIdentifier(value.target_id)) {
+    throw new Error("target_id is invalid");
+  }
+  const message = patchText(value.message, "message", 32_000);
+  if (!message) throw new Error("message must not be empty");
+  return { targetId: value.target_id, message };
+}
+
+function flockAdmissionCeilingV1(
+  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;
+  return turnTypes?.map((value) =>
+    decodeTurnTypeV1(value, `flock capability "${capabilityId}" admission`),
+  );
+}
+
 function refusal(reason: string): ToolExecutionResult {
   return { content: reason, isError: true };
 }
@@ -549,24 +629,128 @@ export function createBotCreateTool(
   };
 }
 
+export function createBotMessageTool(
+  host: FlockSelfRuntimeHostV1,
+): ToolDefinition {
+  return {
+    name: BOT_MESSAGE_TOOL_V1,
+    description:
+      "Ask one of your User's other Bots a question. Use a target_id from <teammates>. The other Bot runs an agent Turn and its send_to_user-style reply is returned here as this tool result. Do not message yourself or fan out speculatively.",
+    inputSchema: BOT_MESSAGE_SCHEMA as unknown as Record<string, unknown>,
+    idempotent: true,
+    validate: (input) => {
+      try {
+        decodeBotMessageInputV1(input);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    execute: async (input: unknown, context: ToolExecutionContext) => {
+      let decoded: BotMessageInputV1;
+      try {
+        decoded = decodeBotMessageInputV1(input);
+      } catch (error) {
+        return refusal(
+          `bot_message was refused: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      if (decoded.targetId === host.owner.botId) {
+        return refusal("bot_message was refused: a Bot cannot message itself");
+      }
+      try {
+        const outcome = await host.messageBot({
+          targetBotId: decoded.targetId,
+          message: decoded.message,
+          effectId: context.effectId,
+        });
+        return { content: outcome.text, isError: false };
+      } catch (error) {
+        return refusal(
+          `bot_message failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    },
+  };
+}
+
+function promptText(value: string): string {
+  return value.replace(/[<>]/g, (character) =>
+    character === "<" ? "&lt;" : "&gt;",
+  );
+}
+
+export function createTeammatesPromptSectionV1(
+  host: FlockSelfRuntimeHostV1,
+): PromptSection {
+  return {
+    id: TEAMMATES_PROMPT_SECTION_V1,
+    order: 92,
+    render: async (context) => {
+      if (context.turnType !== "chat") return "";
+      const teammates = (await host.listBots()).bots.filter(
+        (bot) => bot.botId !== host.owner.botId,
+      );
+      if (teammates.length === 0) return "";
+      const lines = teammates.map((bot) => {
+        const description = bot.initialDescription?.trim();
+        return `- ${promptText(bot.botId)}: ${promptText(bot.initialName)}${
+          description ? ` — ${promptText(description)}` : ""
+        }`;
+      });
+      return [
+        "<teammates>",
+        "These are the other Bots owned by your User. Use bot_message only when another Bot's perspective or specialty is materially useful.",
+        ...lines,
+        "</teammates>",
+      ].join("\n");
+    },
+  };
+}
+
+export function createInboundAgentPromptSectionV1(
+  host: FlockSelfRuntimeHostV1,
+): PromptSection {
+  return {
+    id: INBOUND_AGENT_PROMPT_SECTION_V1,
+    order: 93,
+    render: (context) => {
+      if (context.turnType !== "agent" || !host.inboundAgent) return "";
+      if (host.inboundAgent.kind === "voice") {
+        return "The User's Voice session asked you the current question. Answer it directly with send_to_user; that answer returns to Voice.";
+      }
+      return `Bot ${promptText(host.inboundAgent.fromBotName)} (${promptText(host.inboundAgent.fromBotId)}) asked you the current question. Answer it directly with send_to_user; that answer returns to the asking Bot.`;
+    },
+  };
+}
+
 /**
- * The runtime Contribution. Registers the two self-management tools; both are
- * work tools, offered on every turn type, because an automation or a subagent
- * Turn is as entitled to correct its own title as a chat Turn is.
+ * The runtime Contribution. The two self-management tools remain work tools
+ * on every turn type. `bot_message` is separately bounded to chat by the
+ * manifest so an inbound agent Turn cannot recursively fan out.
  */
 export function createFlockRuntimePlugin(
   host: FlockSelfRuntimeHostV1,
 ): Plugin.Function {
   const plugin: Plugin.Function = (ctx) => {
+    const messagingCeiling = flockAdmissionCeilingV1(
+      BOT_MESSAGING_CAPABILITY_V1,
+    );
     const disposers = [
+      ctx.systemPrompt.register(createTeammatesPromptSectionV1(host)),
+      ctx.systemPrompt.register(createInboundAgentPromptSectionV1(host)),
       ctx.tools.register(createBotUpdateTool(host)),
       ctx.tools.register(createBotCreateTool(host)),
+      ctx.tools.register(
+        createBotMessageTool(host),
+        messagingCeiling ? { admissionCeiling: messagingCeiling } : undefined,
+      ),
     ];
     return () => {
       for (const dispose of disposers.toReversed()) dispose();
     };
   };
-  plugin.inject = ["tools"];
+  plugin.inject = ["tools", "systemPrompt"];
   return plugin;
 }
 

package/src/quota.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AGENT_TURN_CONCURRENCY_PER_USER_V1,
+  releaseAgentTurnSlotV1,
+  reserveAgentTurnSlotV1,
+  type AgentTurnSlotTransactionV1,
+} from "./quota.js";
+
+function storage() {
+  const records = new Map<string, unknown>();
+  const transaction: AgentTurnSlotTransactionV1 = {
+    list: async <T>({ prefix }: { prefix: string }) =>
+      new Map([...records].filter(([key]) => key.startsWith(prefix))) as Map<
+        string,
+        T
+      >,
+    put: async (key, value) => void records.set(key, value),
+    delete: async (key) => records.delete(key),
+  };
+  return {
+    ...transaction,
+    transaction: async <T>(
+      callback: (tx: AgentTurnSlotTransactionV1) => Promise<T>,
+    ) => callback(transaction),
+  };
+}
+
+function request(requesterId: string, runId: string) {
+  return {
+    schemaVersion: 1 as const,
+    userId: "user",
+    requesterId,
+    runId,
+    reservedAt: "2026-09-04T00:00:00.000Z",
+  };
+}
+
+describe("agent Turn concurrency", () => {
+  test("is one fixed per-User budget across requesting Bots", async () => {
+    const state = storage();
+    for (
+      let index = 0;
+      index < AGENT_TURN_CONCURRENCY_PER_USER_V1;
+      index += 1
+    ) {
+      expect(
+        await reserveAgentTurnSlotV1(
+          state,
+          request(index % 2 ? "bot-a" : "bot-b", `run-${index}`),
+        ),
+      ).toMatchObject({ status: "reserved" });
+    }
+    expect(
+      await reserveAgentTurnSlotV1(state, request("bot-c", "run-past")),
+    ).toMatchObject({ status: "refused", held: 8, limit: 8 });
+  });
+
+  test("reserve and release are idempotent for one run", async () => {
+    const state = storage();
+    await reserveAgentTurnSlotV1(state, request("bot-a", "run-1"));
+    expect(
+      await reserveAgentTurnSlotV1(state, request("bot-a", "run-1")),
+    ).toMatchObject({ status: "reserved", held: 1 });
+    expect(
+      await releaseAgentTurnSlotV1(state, {
+        requesterId: "bot-a",
+        runId: "run-1",
+      }),
+    ).toMatchObject({ held: 0 });
+  });
+});

package/src/quota.ts

@@ -0,0 +1,153 @@
+/** Durable per-User concurrency budget for agent-lane Turns. */
+export const AGENT_TURN_CONCURRENCY_PER_USER_V1 = 8;
+export const AGENT_TURN_SLOT_PREFIX_V1 = "agent-turn:slot:";
+
+const ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,255}$/;
+
+export interface AgentTurnSlotRequestV1 {
+  schemaVersion: 1;
+  userId: string;
+  requesterId: string;
+  runId: string;
+  reservedAt: string;
+}
+
+export type AgentTurnSlotReceiptV1 =
+  | {
+      schemaVersion: 1;
+      status: "reserved";
+      requesterId: string;
+      runId: string;
+      held: number;
+      limit: number;
+    }
+  | {
+      schemaVersion: 1;
+      status: "refused";
+      requesterId: string;
+      runId: string;
+      reason: string;
+      held: number;
+      limit: number;
+    };
+
+export interface AgentTurnSlotTransactionV1 {
+  list<T>(options: { prefix: string; limit?: number }): Promise<Map<string, T>>;
+  put(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+}
+
+export interface AgentTurnSlotStorageV1 extends AgentTurnSlotTransactionV1 {
+  transaction<T>(
+    callback: (storage: AgentTurnSlotTransactionV1) => Promise<T>,
+  ): Promise<T>;
+}
+
+export function agentTurnSlotKeyV1(requesterId: string, runId: string): string {
+  if (!ID.test(requesterId) || !ID.test(runId)) {
+    throw new Error("agent Turn slot key is invalid");
+  }
+  return `${AGENT_TURN_SLOT_PREFIX_V1}${requesterId}:${runId}`;
+}
+
+export async function reserveAgentTurnSlotV1(
+  storage: AgentTurnSlotStorageV1,
+  request: AgentTurnSlotRequestV1,
+): Promise<AgentTurnSlotReceiptV1> {
+  const key = agentTurnSlotKeyV1(request.requesterId, request.runId);
+  return storage.transaction(async (transaction) => {
+    const held = await transaction.list({ prefix: AGENT_TURN_SLOT_PREFIX_V1 });
+    if (held.has(key)) {
+      return {
+        schemaVersion: 1,
+        status: "reserved",
+        requesterId: request.requesterId,
+        runId: request.runId,
+        held: held.size,
+        limit: AGENT_TURN_CONCURRENCY_PER_USER_V1,
+      };
+    }
+    if (held.size >= AGENT_TURN_CONCURRENCY_PER_USER_V1) {
+      return {
+        schemaVersion: 1,
+        status: "refused",
+        requesterId: request.requesterId,
+        runId: request.runId,
+        reason: `this User already has ${held.size} agent Turns running; the bound is ${AGENT_TURN_CONCURRENCY_PER_USER_V1}`,
+        held: held.size,
+        limit: AGENT_TURN_CONCURRENCY_PER_USER_V1,
+      };
+    }
+    await transaction.put(key, {
+      schemaVersion: 1,
+      requesterId: request.requesterId,
+      runId: request.runId,
+      reservedAt: request.reservedAt,
+    });
+    return {
+      schemaVersion: 1,
+      status: "reserved",
+      requesterId: request.requesterId,
+      runId: request.runId,
+      held: held.size + 1,
+      limit: AGENT_TURN_CONCURRENCY_PER_USER_V1,
+    };
+  });
+}
+
+export async function releaseAgentTurnSlotV1(
+  storage: AgentTurnSlotStorageV1,
+  request: { requesterId: string; runId: string },
+): Promise<{ schemaVersion: 1; status: "released"; held: number }> {
+  const key = agentTurnSlotKeyV1(request.requesterId, request.runId);
+  return storage.transaction(async (transaction) => {
+    await transaction.delete(key);
+    const held = await transaction.list({ prefix: AGENT_TURN_SLOT_PREFIX_V1 });
+    return { schemaVersion: 1, status: "released", held: held.size };
+  });
+}
+
+export function decodeAgentTurnSlotReceiptV1(
+  input: unknown,
+): AgentTurnSlotReceiptV1 {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("agent Turn slot receipt must be an object");
+  }
+  const value = input as Record<string, unknown>;
+  const requesterId = value.requesterId;
+  const runId = value.runId;
+  const held = value.held;
+  const limit = value.limit;
+  if (
+    value.schemaVersion !== 1 ||
+    (value.status !== "reserved" && value.status !== "refused") ||
+    typeof requesterId !== "string" ||
+    typeof runId !== "string" ||
+    !Number.isSafeInteger(held) ||
+    !Number.isSafeInteger(limit)
+  ) {
+    throw new Error("agent Turn slot receipt is invalid");
+  }
+  if (value.status === "refused") {
+    if (typeof value.reason !== "string" || !value.reason) {
+      throw new Error("agent Turn slot refusal is invalid");
+    }
+    return {
+      schemaVersion: 1,
+      status: "refused",
+      requesterId,
+      runId,
+      reason: value.reason,
+      held: held as number,
+      limit: limit as number,
+    };
+  }
+  return {
+    schemaVersion: 1,
+    status: "reserved",
+    requesterId,
+    runId,
+    held: held as number,
+    limit: limit as number,
+  };
+}