@frockbot/plugin-subagents 0.0.0 → 0.1.0

package/src/quota.ts

@@ -0,0 +1,222 @@
+// The per-User concurrent-subagent bound, as durable User Durable Object state.
+//
+// A Bot's own bound (four) is countable in the Bot Durable Object, because the
+// keys are there. A User's (eight) is not: a User's Bots are separate objects
+// and no one of them can see the others. So the counter lives where the
+// authority for User-scoped state already is, and the Bot Durable Object
+// *reserves* a slot over a narrow RPC before it dispatches — the
+// `AUTHORING_QUOTA_RESERVATION_PREFIX` pattern in `plugin-authoring/src/quota.ts`.
+//
+// The one difference from the authoring quota is what a unit *is*. An authored
+// generation is spent; a running subagent is *held*, and comes back. So the
+// reservation is a live key that a settle releases, not a day counter that only
+// ever rises — and both halves are idempotent on `(botId, taskId)`, so a
+// resumed Turn neither takes a second slot nor releases someone else's.
+
+import { isTaskIdV1, TASK_CONCURRENCY_PER_USER_V1 } from "./records.js";
+
+/** `PUBLIC_IDENTIFIER_PATTERN`: the shape every Bot id already has. */
+const SLOT_BOT_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+
+export const SUBAGENT_SLOT_PREFIX = "subagent:slot:";
+
+/** The durable per-User bound, overridable by nothing today: it is the plan's. */
+export const SUBAGENT_SLOT_LIMIT_V1 = TASK_CONCURRENCY_PER_USER_V1;
+
+export function subagentSlotKeyV1(botId: string, taskId: string): string {
+  // Two ids, one key. Neither may carry the separator, or a key would be
+  // ambiguous about where the Bot ends and the task begins — and both patterns
+  // already exclude it, so this is the check that says so out loud.
+  if (!isTaskIdV1(taskId) || !SLOT_BOT_ID.test(botId)) {
+    throw new Error("subagent slot key is invalid");
+  }
+  return `${SUBAGENT_SLOT_PREFIX}${botId}:${taskId}`;
+}
+
+export interface SubagentSlotRequestV1 {
+  schemaVersion: 1;
+  userId: string;
+  botId: string;
+  taskId: string;
+  reservedAt: string;
+}
+
+export type SubagentSlotReceiptV1 =
+  | {
+      schemaVersion: 1;
+      status: "reserved";
+      botId: string;
+      taskId: string;
+      held: number;
+      limit: number;
+    }
+  | {
+      schemaVersion: 1;
+      status: "refused";
+      botId: string;
+      taskId: string;
+      reason: string;
+      held: number;
+      limit: number;
+    };
+
+interface StoredSubagentSlotV1 {
+  schemaVersion: 1;
+  botId: string;
+  taskId: string;
+  reservedAt: string;
+}
+
+/**
+ * The narrow storage surface this module needs from the User Durable Object.
+ * Deliberately the same shape as {@link TaskStorageWritesV1}, so one in-memory
+ * fake — and one Durable Object storage — satisfies both sides of the bound.
+ */
+export interface SubagentSlotTransaction {
+  get<T>(key: string): Promise<T | undefined>;
+  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 SubagentSlotStorage extends SubagentSlotTransaction {
+  transaction<T>(
+    callback: (storage: SubagentSlotTransaction) => Promise<T>,
+  ): Promise<T>;
+}
+
+/**
+ * Takes one slot for a task, or refuses. Never throws for a breach: a bound is
+ * an observable outcome the Bot's tool result reports.
+ */
+export async function reserveSubagentSlotV1(
+  storage: SubagentSlotStorage,
+  request: SubagentSlotRequestV1,
+): Promise<SubagentSlotReceiptV1> {
+  const key = subagentSlotKeyV1(request.botId, request.taskId);
+  // One transaction from the count to the write: the read-modify-write spans
+  // awaits, so two dispatches racing at the bound must not both be admitted.
+  return storage.transaction(async (transaction) => {
+    const held = await transaction.list<StoredSubagentSlotV1>({
+      prefix: SUBAGENT_SLOT_PREFIX,
+    });
+    if (held.has(key)) {
+      // Already ours. A resumed Turn re-executing the same dispatch reads its
+      // own reservation back rather than taking a second one.
+      return {
+        schemaVersion: 1,
+        status: "reserved",
+        botId: request.botId,
+        taskId: request.taskId,
+        held: held.size,
+        limit: SUBAGENT_SLOT_LIMIT_V1,
+      };
+    }
+    if (held.size >= SUBAGENT_SLOT_LIMIT_V1) {
+      return {
+        schemaVersion: 1,
+        status: "refused",
+        botId: request.botId,
+        taskId: request.taskId,
+        reason: `this User already has ${held.size} subagents running; the bound is ${SUBAGENT_SLOT_LIMIT_V1}`,
+        held: held.size,
+        limit: SUBAGENT_SLOT_LIMIT_V1,
+      };
+    }
+    await transaction.put(key, {
+      schemaVersion: 1,
+      botId: request.botId,
+      taskId: request.taskId,
+      reservedAt: request.reservedAt,
+    } satisfies StoredSubagentSlotV1);
+    return {
+      schemaVersion: 1,
+      status: "reserved",
+      botId: request.botId,
+      taskId: request.taskId,
+      held: held.size + 1,
+      limit: SUBAGENT_SLOT_LIMIT_V1,
+    };
+  });
+}
+
+/** Gives one slot back. Idempotent: releasing a slot nobody holds is a no-op. */
+export async function releaseSubagentSlotV1(
+  storage: SubagentSlotStorage,
+  request: { botId: string; taskId: string },
+): Promise<{ schemaVersion: 1; status: "released"; held: number }> {
+  const key = subagentSlotKeyV1(request.botId, request.taskId);
+  return storage.transaction(async (transaction) => {
+    await transaction.delete(key);
+    const held = await transaction.list<StoredSubagentSlotV1>({
+      prefix: SUBAGENT_SLOT_PREFIX,
+    });
+    return { schemaVersion: 1, status: "released", held: held.size };
+  });
+}
+
+export function decodeSubagentSlotReceiptV1(
+  input: unknown,
+  label = "subagent slot receipt",
+): SubagentSlotReceiptV1 {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const value = input as Record<string, unknown>;
+  if (value.schemaVersion !== 1) {
+    throw new Error(`${label}.schemaVersion is unsupported`);
+  }
+  const text = (name: string, maximum: number): string => {
+    const candidate = value[name];
+    if (
+      typeof candidate !== "string" ||
+      candidate.length === 0 ||
+      candidate.length > maximum
+    ) {
+      throw new Error(`${label}.${name} is invalid`);
+    }
+    return candidate;
+  };
+  const integer = (name: string): number => {
+    const candidate = value[name];
+    if (!Number.isSafeInteger(candidate) || (candidate as number) < 0) {
+      throw new Error(`${label}.${name} is invalid`);
+    }
+    return candidate as number;
+  };
+  const botId = text("botId", 128);
+  const taskId = text("taskId", 128);
+  if (value.status === "reserved") {
+    return {
+      schemaVersion: 1,
+      status: "reserved",
+      botId,
+      taskId,
+      held: integer("held"),
+      limit: integer("limit"),
+    };
+  }
+  if (value.status === "refused") {
+    return {
+      schemaVersion: 1,
+      status: "refused",
+      botId,
+      taskId,
+      reason: text("reason", 1_024),
+      held: integer("held"),
+      limit: integer("limit"),
+    };
+  }
+  throw new Error(`${label}.status is invalid`);
+}
+
+/** The narrow RPC the Bot Durable Object calls on the User Durable Object. */
+export interface SubagentSlotBinding {
+  reserve(request: SubagentSlotRequestV1): Promise<SubagentSlotReceiptV1>;
+  release(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    taskId: string;
+  }): Promise<void>;
+}

package/src/records.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeTaskDesktopLeaseIntentV1,
+  decodeTaskMessageRecordV1,
+  decodeTaskModelBindingV1,
+  decodeTaskOutcomeV1,
+  decodeTaskRecordV1,
+  taskPromptDigestV1,
+  utf8ByteLengthV1,
+  TASK_ATTACHMENT_LIMIT_V1,
+  TASK_CONCURRENCY_PER_BOT_V1,
+  TASK_CONCURRENCY_PER_USER_V1,
+  TASK_DEADLINE_MS_V1,
+  TASK_MAX_DEPTH_V1,
+  TASK_MESSAGE_QUEUE_LIMIT_V1,
+  TASK_PROMPT_MAX_BYTES_V1,
+  type TaskRecordV1,
+} from "./records.js";
+
+const BINDING = {
+  assignmentId: "asg-1",
+  packageId: "provider-ollama-cloud",
+  capabilityId: "ollama-cloud-models",
+  connectionId: "conn-1",
+  provider: "ollama-cloud",
+  providerModelId: "glm-5.3-flash:cloud",
+};
+
+function taskRecord(overrides: Record<string, unknown> = {}): unknown {
+  return {
+    schemaVersion: 1,
+    taskId: "tk-1",
+    type: "executor",
+    description: "Summarise the changelog",
+    promptDigest: "a".repeat(64),
+    model: { binding: BINDING, slug: "provider-ollama-cloud/glm-5.3-flash" },
+    compositionGenerationId: "gen-1",
+    background: true,
+    depth: 1,
+    status: "queued",
+    dispatch: { runId: "run-1", turnId: "run-1", sessionId: "user:bot" },
+    childSessionId: "task:tk-1",
+    attachments: [],
+    createdAt: "2026-09-01T00:00:00.000Z",
+    deadlineAt: "2026-09-01T00:30:00.000Z",
+    ...overrides,
+  };
+}
+
+describe("the bounds the plan states", () => {
+  test("are stated once, here, and are the values the plan names", () => {
+    expect({
+      perBot: TASK_CONCURRENCY_PER_BOT_V1,
+      perUser: TASK_CONCURRENCY_PER_USER_V1,
+      depth: TASK_MAX_DEPTH_V1,
+      promptBytes: TASK_PROMPT_MAX_BYTES_V1,
+      attachments: TASK_ATTACHMENT_LIMIT_V1,
+      queuedMessages: TASK_MESSAGE_QUEUE_LIMIT_V1,
+      lifetimeMs: TASK_DEADLINE_MS_V1,
+    }).toEqual({
+      perBot: 4,
+      perUser: 8,
+      depth: 1,
+      promptBytes: 32_768,
+      attachments: 4,
+      queuedMessages: 16,
+      lifetimeMs: 30 * 60_000,
+    });
+  });
+
+  test("the prompt bound is bytes, not characters", () => {
+    expect(utf8ByteLengthV1("é")).toBe(2);
+  });
+});
+
+describe("TaskRecordV1 decodes exactly", () => {
+  test("accepts a queued record and returns it field for field", () => {
+    const decoded = decodeTaskRecordV1(taskRecord());
+    expect(decoded).toEqual(taskRecord() as TaskRecordV1);
+  });
+
+  test("accepts a settled record whose outcome agrees with its status", () => {
+    const decoded = decodeTaskRecordV1(
+      taskRecord({
+        status: "completed",
+        outcome: {
+          status: "completed",
+          settledAt: "2026-09-01T00:10:00.000Z",
+          summary: "Done.",
+        },
+      }),
+    );
+    expect(decoded.outcome).toMatchObject({ status: "completed" });
+  });
+
+  test("refuses an unknown field rather than dropping it", () => {
+    expect(() => decodeTaskRecordV1(taskRecord({ prompt: "leaked" }))).toThrow(
+      /unknown field "prompt"/,
+    );
+  });
+
+  test("refuses a missing required field", () => {
+    const { model: _model, ...rest } = taskRecord() as Record<string, unknown>;
+    expect(() => decodeTaskRecordV1(rest)).toThrow(/is missing "model"/);
+  });
+
+  test("refuses a non-enumerable own property", () => {
+    const candidate = taskRecord() as Record<string, unknown>;
+    Object.defineProperty(candidate, "smuggled", {
+      value: 1,
+      enumerable: false,
+    });
+    expect(() => decodeTaskRecordV1(candidate)).toThrow(
+      /has a non-enumerable field/,
+    );
+  });
+
+  test("refuses an unknown status and an unknown type", () => {
+    expect(() => decodeTaskRecordV1(taskRecord({ status: "paused" }))).toThrow(
+      /status is invalid/,
+    );
+    expect(() =>
+      decodeTaskRecordV1(taskRecord({ type: "researcher" })),
+    ).toThrow(/type is invalid/);
+  });
+
+  test("refuses a depth past one: a subagent never dispatches a subagent", () => {
+    expect(() => decodeTaskRecordV1(taskRecord({ depth: 2 }))).toThrow(
+      /depth is invalid/,
+    );
+  });
+
+  test("refuses a terminal status with no outcome, and an outcome with none", () => {
+    expect(() =>
+      decodeTaskRecordV1(taskRecord({ status: "completed" })),
+    ).toThrow(/inconsistent terminal state/);
+    expect(() =>
+      decodeTaskRecordV1(
+        taskRecord({
+          outcome: {
+            status: "completed",
+            settledAt: "2026-09-01T00:10:00.000Z",
+          },
+        }),
+      ),
+    ).toThrow(/inconsistent terminal state/);
+  });
+
+  test("refuses an outcome that disagrees with the record's status", () => {
+    expect(() =>
+      decodeTaskRecordV1(
+        taskRecord({
+          status: "failed",
+          outcome: {
+            status: "completed",
+            settledAt: "2026-09-01T00:10:00.000Z",
+          },
+        }),
+      ),
+    ).toThrow(/outcome disagrees with its status/);
+  });
+
+  test("refuses more attachments than the bound allows", () => {
+    expect(() =>
+      decodeTaskRecordV1(
+        taskRecord({ attachments: ["a", "b", "c", "d", "e"] }),
+      ),
+    ).toThrow(/at most 4 entries/);
+  });
+});
+
+describe("the model binding a task pins", () => {
+  test("accepts exactly the fields the Shell resolves", () => {
+    expect(decodeTaskModelBindingV1(BINDING)).toEqual(BINDING);
+  });
+
+  test("refuses a binding carrying anything else", () => {
+    expect(() =>
+      decodeTaskModelBindingV1({ ...BINDING, apiKey: "secret" }),
+    ).toThrow(/unknown field "apiKey"/);
+  });
+});
+
+describe("the terminal outcome", () => {
+  test("refuses a non-terminal status", () => {
+    expect(() =>
+      decodeTaskOutcomeV1({
+        status: "running",
+        settledAt: "2026-09-01T00:10:00.000Z",
+      }),
+    ).toThrow(/status is invalid/);
+  });
+
+  test("refuses a completion that also carries a failure", () => {
+    expect(() =>
+      decodeTaskOutcomeV1({
+        status: "completed",
+        settledAt: "2026-09-01T00:10:00.000Z",
+        summary: "ok",
+        failure: "not ok",
+      }),
+    ).toThrow(/completed and carries a failure at once/);
+  });
+});
+
+describe("the other records this Package writes", () => {
+  test("a queued message decodes exactly", () => {
+    const message = {
+      schemaVersion: 1 as const,
+      taskId: "tk-1",
+      seq: 0,
+      message: "one more thing",
+      createdAt: "2026-09-01T00:00:00.000Z",
+    };
+    expect(decodeTaskMessageRecordV1(message)).toEqual(message);
+    expect(() =>
+      decodeTaskMessageRecordV1({ ...message, priority: "high" }),
+    ).toThrow(/unknown field "priority"/);
+  });
+
+  test("the desktop lease intent names one scope and nothing else", () => {
+    const intent = {
+      schemaVersion: 1 as const,
+      taskId: "tk-1",
+      scope: "desktop-gui" as const,
+      recordedAt: "2026-09-01T00:00:00.000Z",
+    };
+    expect(decodeTaskDesktopLeaseIntentV1(intent)).toEqual({
+      ...intent,
+      scope: "desktop-gui" as const,
+    });
+    expect(() =>
+      decodeTaskDesktopLeaseIntentV1({ ...intent, scope: "browser" }),
+    ).toThrow(/scope is invalid/);
+  });
+});
+
+describe("the prompt digest", () => {
+  test("is stable, and is what the record carries instead of the prompt", async () => {
+    const digest = await taskPromptDigestV1("do the thing");
+    expect(digest).toMatch(/^[0-9a-f]{64}$/);
+    expect(await taskPromptDigestV1("do the thing")).toBe(digest);
+    expect(await taskPromptDigestV1("do the other thing")).not.toBe(digest);
+  });
+});