@frockbot/plugin-subagents 0.0.0 → 0.1.0

package/src/roles.ts

@@ -0,0 +1,76 @@
+// The five subagent roles, and the tool reach each one has.
+//
+// A role is the *second* ceiling dimension on the tool catalog. The first is
+// the turn type: a `subagent` Turn is never offered `Task`, `user_voice`, or
+// anything else a Package declared chat-only. The second is the role: within
+// the work tools a subagent Turn does reach, `browserUse` reaches the browser
+// and not the shell, and `watchVideo` reaches neither.
+//
+// The kernel holds none of this. `ToolRegistry` treats a role exactly as it
+// treats a turn type — an opaque string a registration may narrow itself by —
+// and every table below is *declaration*: a Package says which roles its tool
+// serves, in its own tool definition or its own manifest Capability, and the
+// registry intersects the two. This module is where the first-party Packages'
+// answers are written down together so they can be read as one catalog and
+// tested as one table.
+//
+// Reference: `docs/research/grokbot-computer.md` l.351–356.
+
+import { TASK_TYPES_V1, type TaskTypeV1 } from "./records.js";
+
+/** A subagent role. The same five names a `Task` may name as its `type`. */
+export type SubagentRoleV1 = TaskTypeV1;
+
+/** Every role, in catalog order. */
+export const SUBAGENT_ROLES_V1: readonly SubagentRoleV1[] = TASK_TYPES_V1;
+
+/**
+ * What each role is for, in one line, as the `Task` tool describes it and as
+ * the task list shows it.
+ */
+export const SUBAGENT_ROLE_SUMMARIES_V1: Record<SubagentRoleV1, string> = {
+  executor: "does general work with the Bot's full work toolset",
+  browserUse: "drives web pages through the browser, and nothing else",
+  computerUse: "drives the shared desktop: shell, screen, and browser",
+  watchVideo: "watches the attachments it was given and reports on them",
+  videoReview: "reviews the attachments it was given and reports on them",
+};
+
+/**
+ * The reach one tool declares, as the set of roles it is offered to.
+ *
+ * A Package writes the literal array in its own tool definition — these
+ * constants are the record of what the first-party answers *are*, not a
+ * runtime dependency: `plugin-computer` cannot import this Package, and should
+ * not have to, for the kernel to enforce the ceiling.
+ */
+export const SUBAGENT_TOOL_REACH_V1 = {
+  /**
+   * Reading, and the attachments a task was handed. Every role, including the
+   * two video roles, whose whole job is to read what they were given.
+   */
+  read: SUBAGENT_ROLES_V1,
+  /** Handing the Turn back to the parent. Every role can finish. */
+  handoff: SUBAGENT_ROLES_V1,
+  /** General work tools: memory, skills, routines, MCP, the web, authoring. */
+  work: ["executor"],
+  /** Page-level browser control. */
+  browser: ["executor", "browserUse", "computerUse"],
+  /** The shell and the desktop screen: `computer_exec`, screenshots, processes. */
+  desktop: ["executor", "computerUse"],
+} as const satisfies Record<string, readonly SubagentRoleV1[]>;
+
+/** The reach names, for a table-driven test to walk. */
+export type SubagentToolReachV1 = keyof typeof SUBAGENT_TOOL_REACH_V1;
+
+/**
+ * Whether a tool of this reach is offered to this role — the same predicate
+ * `ToolRegistry` applies, restated over the reach names so the catalog can be
+ * asserted as a table rather than as a mounted runtime.
+ */
+export function subagentRoleAdmitsV1(
+  role: SubagentRoleV1,
+  reach: SubagentToolReachV1,
+): boolean {
+  return (SUBAGENT_TOOL_REACH_V1[reach] as readonly string[]).includes(role);
+}

package/src/shared.ts

@@ -0,0 +1,232 @@
+// The DTOs the task surface crosses seams with, and their exact codecs.
+//
+// A view is projected from a `TaskRecordV1` and carries strictly less: no
+// prompt, no binding secrets, no child transcript. A child Session never enters
+// the visible transcript at all (ADR 0017 — the child is an execution host, and
+// its Session is its own durable state), so this list is the only door onto a
+// task and it is deliberately a narrow one.
+
+import {
+  isTaskIdV1,
+  subagentExactKeys,
+  subagentText,
+  subagentTimestamp,
+  SubagentDecodeError,
+  TASK_DESCRIPTION_MAX_V1,
+  TASK_STATUSES_V1,
+  TASK_SUMMARY_MAX_V1,
+  TASK_TYPES_V1,
+  type TaskRecordV1,
+  type TaskStatusV1,
+  type TaskTypeV1,
+} from "./records.js";
+
+/** Most rows one task-list answer carries. */
+export const TASK_LIST_LIMIT_V1 = 50;
+
+export interface TaskViewV1 {
+  schemaVersion: 1;
+  taskId: string;
+  type: TaskTypeV1;
+  description: string;
+  status: TaskStatusV1;
+  model: string;
+  background: boolean;
+  createdAt: string;
+  deadlineAt: string;
+  settledAt?: string;
+  summary?: string;
+  failure?: string;
+}
+
+export interface TaskListViewV1 {
+  schemaVersion: 1;
+  botId: string;
+  active: number;
+  tasks: TaskViewV1[];
+}
+
+/** The view one durable record projects onto. Never the reverse. */
+export function taskViewV1(record: TaskRecordV1): TaskViewV1 {
+  return {
+    schemaVersion: 1,
+    taskId: record.taskId,
+    type: record.type,
+    description: record.description,
+    status: record.status,
+    model: record.model.slug,
+    background: record.background,
+    createdAt: record.createdAt,
+    deadlineAt: record.deadlineAt,
+    ...(record.outcome === undefined
+      ? {}
+      : {
+          settledAt: record.outcome.settledAt,
+          ...(record.outcome.summary === undefined
+            ? {}
+            : { summary: record.outcome.summary }),
+          ...(record.outcome.failure === undefined
+            ? {}
+            : { failure: record.outcome.failure }),
+        }),
+  };
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new SubagentDecodeError(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+export function decodeTaskViewV1(
+  value: unknown,
+  label = "task view",
+): TaskViewV1 {
+  const candidate = record(value, label);
+  subagentExactKeys(
+    candidate,
+    [
+      "schemaVersion",
+      "taskId",
+      "type",
+      "description",
+      "status",
+      "model",
+      "background",
+      "createdAt",
+      "deadlineAt",
+    ],
+    ["settledAt", "summary", "failure"],
+    label,
+  );
+  if (candidate.schemaVersion !== 1) {
+    throw new SubagentDecodeError(`${label} schemaVersion is unsupported`);
+  }
+  if (!isTaskIdV1(candidate.taskId)) {
+    throw new SubagentDecodeError(`${label} taskId is invalid`);
+  }
+  const type = TASK_TYPES_V1.find((known) => known === candidate.type);
+  if (!type) throw new SubagentDecodeError(`${label} type is invalid`);
+  const status = TASK_STATUSES_V1.find((known) => known === candidate.status);
+  if (!status) throw new SubagentDecodeError(`${label} status is invalid`);
+  if (typeof candidate.background !== "boolean") {
+    throw new SubagentDecodeError(`${label} background must be a boolean`);
+  }
+  return {
+    schemaVersion: 1,
+    taskId: candidate.taskId,
+    type,
+    description: subagentText(
+      candidate.description,
+      TASK_DESCRIPTION_MAX_V1,
+      `${label}.description`,
+    ),
+    status,
+    model: subagentText(candidate.model, 512, `${label}.model`),
+    background: candidate.background,
+    createdAt: subagentTimestamp(candidate.createdAt, `${label}.createdAt`),
+    deadlineAt: subagentTimestamp(candidate.deadlineAt, `${label}.deadlineAt`),
+    ...(candidate.settledAt === undefined
+      ? {}
+      : {
+          settledAt: subagentTimestamp(
+            candidate.settledAt,
+            `${label}.settledAt`,
+          ),
+        }),
+    ...(candidate.summary === undefined
+      ? {}
+      : {
+          summary: subagentText(
+            candidate.summary,
+            TASK_SUMMARY_MAX_V1,
+            `${label}.summary`,
+          ),
+        }),
+    ...(candidate.failure === undefined
+      ? {}
+      : {
+          failure: subagentText(
+            candidate.failure,
+            TASK_SUMMARY_MAX_V1,
+            `${label}.failure`,
+          ),
+        }),
+  };
+}
+
+export function decodeTaskListViewV1(value: unknown): TaskListViewV1 {
+  const label = "task list";
+  const candidate = record(value, label);
+  subagentExactKeys(
+    candidate,
+    ["schemaVersion", "botId", "active", "tasks"],
+    [],
+    label,
+  );
+  if (candidate.schemaVersion !== 1) {
+    throw new SubagentDecodeError(`${label} schemaVersion is unsupported`);
+  }
+  if (
+    !Number.isSafeInteger(candidate.active) ||
+    (candidate.active as number) < 0
+  ) {
+    throw new SubagentDecodeError(`${label} active is invalid`);
+  }
+  if (!Array.isArray(candidate.tasks)) {
+    throw new SubagentDecodeError(`${label} tasks must be an array`);
+  }
+  if (candidate.tasks.length > TASK_LIST_LIMIT_V1) {
+    throw new SubagentDecodeError(`${label} carries too many tasks`);
+  }
+  return {
+    schemaVersion: 1,
+    botId: subagentText(candidate.botId, 128, `${label}.botId`),
+    active: candidate.active as number,
+    tasks: candidate.tasks.map((entry, index) =>
+      decodeTaskViewV1(entry, `${label}.tasks[${index}]`),
+    ),
+  };
+}
+
+/** The dispatch one `Task` call becomes, once the tool input has been decoded. */
+export interface TaskDispatchReceiptV1 {
+  schemaVersion: 1;
+  status: "dispatched";
+  taskId: string;
+  model: string;
+  background: boolean;
+}
+
+export function decodeTaskDispatchReceiptV1(
+  value: unknown,
+): TaskDispatchReceiptV1 {
+  const label = "task dispatch receipt";
+  const candidate = record(value, label);
+  subagentExactKeys(
+    candidate,
+    ["schemaVersion", "status", "taskId", "model", "background"],
+    [],
+    label,
+  );
+  if (candidate.schemaVersion !== 1) {
+    throw new SubagentDecodeError(`${label} schemaVersion is unsupported`);
+  }
+  if (candidate.status !== "dispatched") {
+    throw new SubagentDecodeError(`${label} status is invalid`);
+  }
+  if (!isTaskIdV1(candidate.taskId)) {
+    throw new SubagentDecodeError(`${label} taskId is invalid`);
+  }
+  if (typeof candidate.background !== "boolean") {
+    throw new SubagentDecodeError(`${label} background must be a boolean`);
+  }
+  return {
+    schemaVersion: 1,
+    status: "dispatched",
+    taskId: candidate.taskId,
+    model: subagentText(candidate.model, 512, `${label}.model`),
+    background: candidate.background,
+  };
+}

package/src/storage-keys.ts

@@ -0,0 +1,148 @@
+// The Bot Durable Object storage keys the Subagents Package owns.
+//
+// They live here rather than in `@frockbot/kernel-do` because the kernel
+// imports no Package and holds no product policy; the Durable Object hands this
+// Package a storage seam and this module decides what it writes under.
+//
+// Every key below is *parent* state. ADR 0017: the parent Bot Durable Object is
+// the authority for a task — admission, bounds, leases, lifecycle, terminal
+// outcome — and the Subagent Durable Object holds only its own Session.
+
+import { TASK_ID_MAX_V1 } from "./records.js";
+
+/** One `TaskRecordV1`. */
+export const TASK_PREFIX = "task:";
+/**
+ * The membership set that *is* the per-Bot concurrency counter. Written in the
+ * same transaction that writes the record, deleted in the one that settles it,
+ * so counting keys and reading records can never disagree.
+ */
+export const TASK_ACTIVE_PREFIX = "task-active:";
+/** One bounded queue of pending `task_message` payloads (G2 drains them). */
+export const TASK_MESSAGE_PREFIX = "task-msg:";
+/**
+ * The durable intent to cancel one task: written before the child is asked to
+ * stop, so an interrupted `task_stop` is read back rather than repeated, and
+ * deleted by the settle that makes the cancellation terminal.
+ */
+export const TASK_STOP_PREFIX = "task-stop:";
+/** The `computerUse` desktop-lease intent: the effect named before the host call. */
+export const TASK_DESKTOP_LEASE_KEY = "task-lease:desktop";
+/** The bounded reverse index the Bot-level task list reads, newest first. */
+export const TASK_INDEX_PREFIX = "task-index:";
+/** The task index's monotonic sequence, addressable by key alone. */
+export const TASK_INDEX_CURSOR_KEY = "task-index-cursor";
+
+/**
+ * The child Durable Object's own record of what it was handed. It is the only
+ * key in this module written in the *child* object, and it is deliberately not
+ * authority: it records the parent, the pinned Composition generation, and the
+ * pinned binding so a child that is asked what it is doing can answer without
+ * the parent telling it again.
+ */
+export const TASK_CONTEXT_PREFIX = "task-context:";
+
+/** Most index rows retained. Trimming loses an index row, never a task record. */
+export const TASK_INDEX_LIMIT = 100;
+
+const SEQUENCE_CEILING = 1_000_000_000;
+
+function requireTaskId(taskId: string): string {
+  if (
+    typeof taskId !== "string" ||
+    taskId.length === 0 ||
+    taskId.length > TASK_ID_MAX_V1 ||
+    taskId.includes(":")
+  ) {
+    throw new Error("task id is invalid");
+  }
+  return taskId;
+}
+
+export function taskKeyV1(taskId: string): string {
+  return `${TASK_PREFIX}${requireTaskId(taskId)}`;
+}
+
+export function taskActiveKeyV1(taskId: string): string {
+  return `${TASK_ACTIVE_PREFIX}${requireTaskId(taskId)}`;
+}
+
+export function taskContextKeyV1(taskId: string): string {
+  return `${TASK_CONTEXT_PREFIX}${requireTaskId(taskId)}`;
+}
+
+export function taskStopKeyV1(taskId: string): string {
+  return `${TASK_STOP_PREFIX}${requireTaskId(taskId)}`;
+}
+
+export function taskMessagePrefixV1(taskId: string): string {
+  return `${TASK_MESSAGE_PREFIX}${requireTaskId(taskId)}:`;
+}
+
+/** Message keys ascend, so a prefix listing drains oldest first. */
+export function taskMessageKeyV1(taskId: string, seq: number): string {
+  if (!Number.isSafeInteger(seq) || seq < 0 || seq >= SEQUENCE_CEILING) {
+    throw new Error("task message sequence is out of range");
+  }
+  return `${taskMessagePrefixV1(taskId)}${String(seq).padStart(10, "0")}`;
+}
+
+/**
+ * Index keys descend, so a prefix listing returns the newest task first without
+ * reading every record.
+ */
+export function taskIndexKeyV1(seq: number): string {
+  if (!Number.isSafeInteger(seq) || seq < 0 || seq >= SEQUENCE_CEILING) {
+    throw new Error("task index sequence is out of range");
+  }
+  return `${TASK_INDEX_PREFIX}${String(SEQUENCE_CEILING - seq).padStart(10, "0")}`;
+}
+
+/** The sequence the next index row takes, given the keys already stored. */
+export function nextTaskIndexSequenceV1(keys: readonly string[]): number {
+  let highest = -1;
+  for (const key of keys) {
+    const encoded = Number(key.slice(key.lastIndexOf(":") + 1));
+    if (!Number.isSafeInteger(encoded)) continue;
+    highest = Math.max(highest, SEQUENCE_CEILING - encoded);
+  }
+  return highest + 1;
+}
+
+/**
+ * The name of the Subagent Durable Object one task runs in.
+ *
+ * The same `BotState` class in the same `BOT_STATES` namespace, so there is no
+ * migration and no second identity: `#` cannot appear in a Bot id (it is
+ * outside `PUBLIC_IDENTIFIER_PATTERN`), so the suffix is unforgeable from any
+ * caller-supplied path segment and a Subagent object can never collide with a
+ * Bot object.
+ */
+export function subagentDurableObjectNameV1(identity: {
+  userId: string;
+  botId: string;
+  taskId: string;
+}): string {
+  return `${identity.userId}:${identity.botId}#task:${requireTaskId(identity.taskId)}`;
+}
+
+/** The Session a child Turn records its own events on. */
+export function taskSessionIdV1(taskId: string): string {
+  return `task:${requireTaskId(taskId)}`;
+}
+
+/**
+ * The task whose Session and Subagent Durable Object a child Turn actually
+ * runs in — the *anchor*.
+ *
+ * For a first dispatch that is the task itself. For a resume it is the task
+ * that was resumed, because "the same child Durable Object and Session" is the
+ * whole point of resuming: the child picks its prior transcript up from its own
+ * cursor rather than starting blank a second time.
+ */
+export function taskAnchorIdV1(childSessionId: string): string {
+  const anchor = childSessionId.startsWith("task:")
+    ? childSessionId.slice("task:".length)
+    : childSessionId;
+  return requireTaskId(anchor);
+}