@frockbot/plugin-subagents 0.0.0 → 0.1.1

package/src/backend.ts

@@ -0,0 +1,193 @@
+// The Subagents gateway Contribution: the authenticated HTTP surface.
+//
+// Three routes:
+//
+//   GET  /api/bots/:botId/tasks                 the Bot's task list
+//   GET  /api/bots/:botId/tasks/:taskId         one task
+//   POST /api/bots/:botId/tasks/:taskId/stop    explicit, authenticated cancel
+//
+// The gateway owns none of this state. It carries the request to the *parent*
+// Bot Durable Object — the authority, per ADR 0017 — which proves directory
+// membership before it answers, so a Bot that is not this User's is a 404 here
+// for the same reason it is one on `/api/bots/:id/settings`, and never because
+// this module checked.
+//
+// A child Session is never reachable from here. The Subagent Durable Object is
+// an execution host with no route of its own, and a task's summary reaches the
+// User through this list and through the parent's transcript — never as a
+// second conversation.
+import type { Plugin } from "cordis";
+import { isTaskIdV1, SubagentDecodeError } from "./records.js";
+import {
+  decodeTaskListViewV1,
+  decodeTaskViewV1,
+  type TaskListViewV1,
+  type TaskViewV1,
+} from "./shared.js";
+
+export interface SubagentsGatewayHost {
+  listTasks(userId: string, botId: string): Promise<TaskListViewV1>;
+  readTask(userId: string, botId: string, taskId: string): Promise<TaskViewV1>;
+  /**
+   * The User's own cancellation. It is the same durable act the Bot's
+   * `task_stop` performs, through a second authenticated door — never a second
+   * mechanism, so a task cannot be terminal on one path and live on the other.
+   */
+  stopTask(userId: string, botId: string, taskId: string): Promise<TaskViewV1>;
+}
+
+export interface SubagentsBackendRouteContribution {
+  packageId: string;
+  route(
+    request: Request,
+    url: URL,
+    context: { userId?: string; client: "browser" | "desktop" },
+  ): Promise<Response | undefined>;
+}
+
+const TASKS = /^\/api\/bots\/([^/]+)\/tasks$/;
+const TASK = /^\/api\/bots\/([^/]+)\/tasks\/([^/]+)$/;
+const TASK_STOP = /^\/api\/bots\/([^/]+)\/tasks\/([^/]+)\/stop$/;
+
+/**
+ * A Bot id may not carry `#`, and this is one of the two doors that is why.
+ *
+ * The Subagent Durable Object is `<userId>:<botId>#task:<taskId>` in the same
+ * namespace as the Bot's own object (ADR 0017), so a `#` smuggled through a
+ * path segment would let a caller name an object the directory never minted.
+ * `PUBLIC_IDENTIFIER_PATTERN` excludes `#`; this route restates the check at
+ * its own door rather than trusting the next one.
+ */
+const BOT_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+
+function jsonError(status: number, message: string): Response {
+  return Response.json({ error: message }, { status });
+}
+
+function pathSegment(value: string): string {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    throw new SubagentDecodeError("request path is invalid");
+  }
+  if (!BOT_ID.test(decoded)) {
+    throw new SubagentDecodeError("invalid bot id");
+  }
+  return decoded;
+}
+
+/**
+ * A task id from a path segment. Restated here for the same reason the Bot id
+ * is: a task id becomes part of a Durable Object name (ADR 0017), so the door
+ * it arrives at is the door that checks it.
+ */
+function taskSegment(value: string): string {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    throw new SubagentDecodeError("request path is invalid");
+  }
+  if (!isTaskIdV1(decoded)) {
+    throw new SubagentDecodeError("invalid task id");
+  }
+  return decoded;
+}
+
+/** A Bot the caller does not own, and one that does not exist, are one answer. */
+function isMissingBot(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    (error.name === "BotNotFoundError" || error.name === "TaskNotFoundError")
+  );
+}
+
+function errorResponse(error: unknown): Response {
+  if (isMissingBot(error)) {
+    return jsonError(404, error instanceof Error ? error.message : "not found");
+  }
+  if (
+    error instanceof SubagentDecodeError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      error.name === "SubagentDecodeError")
+  ) {
+    return jsonError(
+      400,
+      error instanceof Error ? error.message : "task request is invalid",
+    );
+  }
+  return jsonError(
+    500,
+    error instanceof Error ? error.message : "task request failed",
+  );
+}
+
+export function createSubagentsBackendContribution(
+  host: SubagentsGatewayHost,
+): SubagentsBackendRouteContribution {
+  return {
+    packageId: "subagents",
+    async route(request, url, context) {
+      const tasks = TASKS.exec(url.pathname);
+      const task = TASK.exec(url.pathname);
+      const stop = TASK_STOP.exec(url.pathname);
+      if (!tasks && !task && !stop) return undefined;
+      if (!context.userId) return undefined;
+      if ([...url.searchParams.keys()].length > 0) {
+        return jsonError(400, "task routes take no query parameters");
+      }
+      const userId = context.userId;
+      try {
+        if (stop) {
+          if (request.method !== "POST") {
+            return jsonError(405, "method not allowed");
+          }
+          return Response.json(
+            decodeTaskViewV1(
+              await host.stopTask(
+                userId,
+                pathSegment(stop[1]!),
+                taskSegment(stop[2]!),
+              ),
+            ),
+          );
+        }
+        if (request.method !== "GET") {
+          return jsonError(405, "method not allowed");
+        }
+        if (task) {
+          return Response.json(
+            decodeTaskViewV1(
+              await host.readTask(
+                userId,
+                pathSegment(task[1]!),
+                taskSegment(task[2]!),
+              ),
+            ),
+          );
+        }
+        return Response.json(
+          decodeTaskListViewV1(
+            await host.listTasks(userId, pathSegment(tasks![1]!)),
+          ),
+        );
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  };
+}
+
+export namespace createSubagentsBackendContribution {
+  export function plugin(
+    host: SubagentsGatewayHost,
+    lifecycle: { mount(value: SubagentsBackendRouteContribution): () => void },
+  ): Plugin {
+    return () => lifecycle.mount(createSubagentsBackendContribution(host));
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./models.js";
+export * from "./quota.js";
+export * from "./records.js";
+export * from "./roles.js";
+export * from "./shared.js";
+export * from "./storage-keys.js";
+export * from "./store.js";
+export * from "./testing.js";

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;

package/src/models.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, test } from "bun:test";
+import {
+  renderAvailableSubagentModelsPromptV1,
+  resolveSubagentModelV1,
+  subagentModelCatalogV1,
+  subagentModelSlugV1,
+} from "./models.js";
+import type { TaskModelBindingV1 } from "./records.js";
+
+function assignment(
+  packageId: string,
+  providerModelId: string,
+  assignmentId = `asg-${providerModelId}`,
+): TaskModelBindingV1 {
+  return {
+    assignmentId,
+    packageId,
+    capabilityId: `${packageId}-models`,
+    connectionId: `conn-${assignmentId}`,
+    provider: packageId,
+    providerModelId,
+  };
+}
+
+const DEFAULT = assignment("provider-ollama-cloud", "glm-5.3-flash:cloud");
+const SECOND = assignment("provider-foundation", "sand-automation");
+
+describe("the slug", () => {
+  test("is the Package and the provider model, and nothing else", () => {
+    expect(subagentModelSlugV1(DEFAULT)).toBe(
+      "provider-ollama-cloud/glm-5.3-flash:cloud",
+    );
+  });
+});
+
+describe("the catalog one Turn is offered", () => {
+  test("is built from the Bot's enabled model Assignments, default first", () => {
+    const catalog = subagentModelCatalogV1({
+      assignments: [SECOND, DEFAULT],
+      defaultBinding: DEFAULT,
+      turnType: "chat",
+    });
+    expect(catalog.map((option) => option.slug)).toEqual([
+      "provider-ollama-cloud/glm-5.3-flash:cloud",
+      "provider-foundation/sand-automation",
+    ]);
+    expect(catalog[0]?.isDefault).toBe(true);
+    expect(catalog[1]?.isDefault).toBe(false);
+  });
+
+  test("keeps one entry per slug when two Assignments name one model", () => {
+    const twin = assignment(
+      "provider-ollama-cloud",
+      "glm-5.3-flash:cloud",
+      "asg-twin",
+    );
+    expect(
+      subagentModelCatalogV1({
+        assignments: [DEFAULT, twin],
+        defaultBinding: DEFAULT,
+        turnType: "chat",
+      }),
+    ).toHaveLength(1);
+  });
+
+  test("renders exactly one slug on an automation turn — the Bot's own binding", () => {
+    for (const turnType of ["automation", "subagent"] as const) {
+      const catalog = subagentModelCatalogV1({
+        assignments: [SECOND, DEFAULT],
+        defaultBinding: DEFAULT,
+        turnType,
+      });
+      expect(catalog.map((option) => option.slug)).toEqual([
+        "provider-ollama-cloud/glm-5.3-flash:cloud",
+      ]);
+    }
+  });
+
+  test("is empty for a Bot with no enabled model Assignment", () => {
+    expect(
+      subagentModelCatalogV1({ assignments: [], turnType: "chat" }),
+    ).toEqual([]);
+  });
+});
+
+describe("resolving a `Task` model against the catalog", () => {
+  const catalog = subagentModelCatalogV1({
+    assignments: [SECOND, DEFAULT],
+    defaultBinding: DEFAULT,
+    turnType: "chat",
+  });
+
+  test("an omitted model inherits the parent's binding", () => {
+    const resolved = resolveSubagentModelV1(catalog, undefined);
+    expect(resolved).toMatchObject({
+      status: "resolved",
+      model: { slug: "provider-ollama-cloud/glm-5.3-flash:cloud" },
+    });
+  });
+
+  test("a named slug resolves to the Assignment that carries it", () => {
+    const resolved = resolveSubagentModelV1(
+      catalog,
+      "provider-foundation/sand-automation",
+    );
+    expect(resolved).toMatchObject({
+      status: "resolved",
+      model: { binding: { assignmentId: SECOND.assignmentId } },
+    });
+  });
+
+  test("a slug the Turn was not offered is refused, with the list it was", () => {
+    const resolved = resolveSubagentModelV1(catalog, "anthropic/opus");
+    expect(resolved).toMatchObject({ status: "refused" });
+    expect(resolved.status === "refused" && resolved.reason).toContain(
+      "provider-ollama-cloud/glm-5.3-flash:cloud",
+    );
+  });
+
+  test("an automation turn refuses the second slug it was not shown", () => {
+    const narrowed = subagentModelCatalogV1({
+      assignments: [SECOND, DEFAULT],
+      defaultBinding: DEFAULT,
+      turnType: "automation",
+    });
+    expect(
+      resolveSubagentModelV1(narrowed, "provider-foundation/sand-automation"),
+    ).toMatchObject({ status: "refused" });
+  });
+
+  test("a Bot with no model Assignment is refused rather than defaulted", () => {
+    expect(resolveSubagentModelV1([], undefined)).toMatchObject({
+      status: "refused",
+    });
+    expect(resolveSubagentModelV1([], "anything/at-all")).toMatchObject({
+      status: "refused",
+    });
+  });
+});
+
+describe("<available_subagent_models>", () => {
+  test("renders one element per slug and marks the default", () => {
+    const rendered = renderAvailableSubagentModelsPromptV1(
+      subagentModelCatalogV1({
+        assignments: [SECOND, DEFAULT],
+        defaultBinding: DEFAULT,
+        turnType: "chat",
+      }),
+    );
+    expect(rendered).toContain("<available_subagent_models>");
+    expect(rendered).toContain(
+      '<model slug="provider-ollama-cloud/glm-5.3-flash:cloud" provider="provider-ollama-cloud" default="true" />',
+    );
+    expect(rendered).toContain(
+      '<model slug="provider-foundation/sand-automation" provider="provider-foundation" />',
+    );
+  });
+
+  test("renders exactly one model line on an automation turn", () => {
+    const rendered = renderAvailableSubagentModelsPromptV1(
+      subagentModelCatalogV1({
+        assignments: [SECOND, DEFAULT],
+        defaultBinding: DEFAULT,
+        turnType: "automation",
+      }),
+    );
+    expect(
+      rendered.split("\n").filter((line) => line.includes("<model ")),
+    ).toHaveLength(1);
+  });
+
+  test("renders nothing at all for an empty catalog", () => {
+    expect(renderAvailableSubagentModelsPromptV1([])).toBe("");
+  });
+});

package/src/models.ts

@@ -0,0 +1,185 @@
+// Per-turn subagent model slugs.
+//
+// GrokBot injects `<available_subagent_models>` into the system prompt of every
+// turn that may dispatch one, and `createTaskTool` reads the slug back out of
+// the `model` argument (`docs/research/grokbot-computer.md` l.472–474). Two
+// rules come with it: an automation turn holds exactly one slug — the Bot's own
+// default binding, GrokBot's `sand-automation` — and an omitted `model`
+// inherits the parent's binding rather than picking anything.
+//
+// A slug is `<packageId>/<providerModelId>`. It names an *Assignment*, not a
+// provider: resolution runs against the Bot's enabled model Assignments, so a
+// slug the Bot invents resolves to nothing and the dispatch is refused.
+
+import type { TurnTypeV1 } from "@frockbot/kernel-contracts";
+import {
+  decodeTaskModelBindingV1,
+  SubagentDecodeError,
+  type TaskModelBindingV1,
+  type TaskModelV1,
+} from "./records.js";
+
+/** Most slugs the prompt section will ever render. A catalog, not a directory. */
+export const SUBAGENT_MODEL_CATALOG_LIMIT_V1 = 32;
+
+/** One offerable model, projected from one enabled model Assignment. */
+export interface SubagentModelOptionV1 {
+  slug: string;
+  binding: TaskModelBindingV1;
+  /** True for the Bot's own durable binding: what an omitted `model` inherits. */
+  isDefault: boolean;
+}
+
+export function subagentModelSlugV1(binding: {
+  packageId: string;
+  providerModelId: string;
+}): string {
+  return `${binding.packageId}/${binding.providerModelId}`;
+}
+
+/**
+ * The turn types that may see more than one slug.
+ *
+ * An `automation` or `subagent` turn renders exactly one — the Bot's default
+ * binding. It is not a permission (the Assignments are the same either way); it
+ * is that an unattended Turn choosing a model per task is a decision with
+ * nobody to answer for it.
+ */
+export function subagentModelsAreNarrowedV1(turnType: TurnTypeV1): boolean {
+  return turnType === "automation" || turnType === "subagent";
+}
+
+/**
+ * The catalog one Turn is offered.
+ *
+ * `assignments` are the Bot's enabled model Assignments, already resolved by
+ * the Shell; `defaultBinding` is the Bot's own durable binding. A duplicate
+ * slug is kept once — two Assignments naming one provider model are one choice.
+ */
+export function subagentModelCatalogV1(input: {
+  assignments: readonly TaskModelBindingV1[];
+  defaultBinding?: TaskModelBindingV1;
+  turnType: TurnTypeV1;
+}): SubagentModelOptionV1[] {
+  const defaultSlug = input.defaultBinding
+    ? subagentModelSlugV1(input.defaultBinding)
+    : undefined;
+  const seen = new Set<string>();
+  const options: SubagentModelOptionV1[] = [];
+  const consider = (binding: TaskModelBindingV1) => {
+    const slug = subagentModelSlugV1(binding);
+    if (seen.has(slug)) return;
+    if (options.length >= SUBAGENT_MODEL_CATALOG_LIMIT_V1) return;
+    seen.add(slug);
+    options.push({ slug, binding, isDefault: slug === defaultSlug });
+  };
+  // The default first, so the one slug a narrowed turn renders is always the
+  // Bot's own binding and never whichever Assignment happens to sort first.
+  if (input.defaultBinding) consider(input.defaultBinding);
+  if (!subagentModelsAreNarrowedV1(input.turnType)) {
+    for (const assignment of input.assignments) consider(assignment);
+  }
+  return subagentModelsAreNarrowedV1(input.turnType)
+    ? options.slice(0, 1)
+    : options;
+}
+
+export type SubagentModelResolutionV1 =
+  | { status: "resolved"; model: TaskModelV1 }
+  | { status: "refused"; reason: string };
+
+/**
+ * The model one dispatch pins.
+ *
+ * An omitted slug inherits the parent's binding. A named slug must be in the
+ * catalog this Turn was offered — a Bot that names a model it was not shown is
+ * refused with the list it *was* shown, which is the honest answer and also the
+ * one that repairs the next attempt.
+ */
+export function resolveSubagentModelV1(
+  catalog: readonly SubagentModelOptionV1[],
+  requested: string | undefined,
+): SubagentModelResolutionV1 {
+  if (requested === undefined) {
+    const inherited = catalog.find((option) => option.isDefault) ?? catalog[0];
+    if (!inherited) {
+      return {
+        status: "refused",
+        reason:
+          "this Bot has no enabled model Assignment, so a subagent has no model to run on",
+      };
+    }
+    return {
+      status: "resolved",
+      model: { binding: inherited.binding, slug: inherited.slug },
+    };
+  }
+  const match = catalog.find((option) => option.slug === requested);
+  if (!match) {
+    const offered = catalog.map((option) => option.slug).join(", ");
+    return {
+      status: "refused",
+      reason:
+        offered.length > 0
+          ? `model "${requested}" is not one of this Turn's subagent models (${offered})`
+          : `model "${requested}" is not available: this Bot has no enabled model Assignment`,
+    };
+  }
+  return {
+    status: "resolved",
+    model: { binding: match.binding, slug: match.slug },
+  };
+}
+
+function escapeAttribute(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * The `<available_subagent_models>` block, in the shape
+ * `renderSkillCatalogPromptV1` established: an element per entry, then the
+ * sentences that say what the list is and what reading it does not authorize.
+ * An empty catalog renders nothing at all rather than an empty element.
+ */
+export function renderAvailableSubagentModelsPromptV1(
+  catalog: readonly SubagentModelOptionV1[],
+): string {
+  if (catalog.length === 0) return "";
+  const entries = catalog.map((option) => {
+    const attributes = [
+      `slug="${escapeAttribute(option.slug)}"`,
+      `provider="${escapeAttribute(option.binding.provider)}"`,
+      ...(option.isDefault ? ['default="true"'] : []),
+    ].join(" ");
+    return `  <model ${attributes} />`;
+  });
+  return [
+    "<available_subagent_models>",
+    ...entries,
+    "</available_subagent_models>",
+    "These are the models a subagent you dispatch may run on. Pass one slug as the Task tool's `model`.",
+    "Omit `model` and the subagent inherits the model you are running on.",
+  ].join("\n");
+}
+
+/**
+ * Decodes a model binding that crossed the Shell seam. The Shell resolves it
+ * from the Bot's own configuration and the User's Connection; this Package
+ * accepts nothing else, and never anything a Bot supplied.
+ */
+export function decodeSubagentModelBindingV1(
+  value: unknown,
+  label = "subagent model binding",
+): TaskModelBindingV1 {
+  try {
+    return decodeTaskModelBindingV1(value, label);
+  } catch (error) {
+    throw error instanceof SubagentDecodeError
+      ? error
+      : new SubagentDecodeError(`${label} is invalid`);
+  }
+}

package/src/quota.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeSubagentSlotReceiptV1,
+  releaseSubagentSlotV1,
+  reserveSubagentSlotV1,
+  SUBAGENT_SLOT_LIMIT_V1,
+} from "./quota.js";
+import { createMemorySubagentStorageV1 } from "./testing.js";
+
+function request(botId: string, taskId: string) {
+  return {
+    schemaVersion: 1 as const,
+    userId: "user",
+    botId,
+    taskId,
+    reservedAt: "2026-09-01T00:00:00.000Z",
+  };
+}
+
+describe("the per-User concurrent-subagent bound", () => {
+  test("admits up to the bound and refuses the one past it", async () => {
+    const storage = createMemorySubagentStorageV1();
+    for (let index = 0; index < SUBAGENT_SLOT_LIMIT_V1; index += 1) {
+      expect(
+        await reserveSubagentSlotV1(storage, request("bot", `tk-${index}`)),
+      ).toMatchObject({ status: "reserved" });
+    }
+    const refused = await reserveSubagentSlotV1(
+      storage,
+      request("bot", "tk-past"),
+    );
+    expect(refused).toMatchObject({ status: "refused", held: 8, limit: 8 });
+    expect(refused.status === "refused" && refused.reason).toContain(
+      "the bound is 8",
+    );
+  });
+
+  test("counts across a User's Bots, which is the whole reason it lives here", async () => {
+    const storage = createMemorySubagentStorageV1();
+    for (let index = 0; index < 4; index += 1) {
+      await reserveSubagentSlotV1(storage, request("bot-a", `tk-${index}`));
+    }
+    for (let index = 0; index < 4; index += 1) {
+      await reserveSubagentSlotV1(storage, request("bot-b", `tk-${index}`));
+    }
+    expect(
+      await reserveSubagentSlotV1(storage, request("bot-c", "tk-0")),
+    ).toMatchObject({ status: "refused" });
+  });
+
+  test("is idempotent per task: a resumed dispatch takes no second slot", async () => {
+    const storage = createMemorySubagentStorageV1();
+    await reserveSubagentSlotV1(storage, request("bot", "tk-1"));
+    const again = await reserveSubagentSlotV1(storage, request("bot", "tk-1"));
+    expect(again).toMatchObject({ status: "reserved", held: 1 });
+  });
+
+  test("a release gives the slot back, and releasing twice is a no-op", async () => {
+    const storage = createMemorySubagentStorageV1();
+    await reserveSubagentSlotV1(storage, request("bot", "tk-1"));
+    expect(
+      await releaseSubagentSlotV1(storage, { botId: "bot", taskId: "tk-1" }),
+    ).toMatchObject({ held: 0 });
+    expect(
+      await releaseSubagentSlotV1(storage, { botId: "bot", taskId: "tk-1" }),
+    ).toMatchObject({ held: 0 });
+  });
+});
+
+describe("the receipt that crosses the Durable Object seam", () => {
+  test("decodes both statuses and refuses anything else", async () => {
+    const storage = createMemorySubagentStorageV1();
+    const reserved = await reserveSubagentSlotV1(
+      storage,
+      request("bot", "tk-1"),
+    );
+    expect(decodeSubagentSlotReceiptV1(reserved)).toEqual(reserved);
+    expect(() =>
+      decodeSubagentSlotReceiptV1({ ...reserved, status: "maybe" }),
+    ).toThrow(/status is invalid/);
+  });
+});