@frockbot/plugin-shell 0.0.0 → 0.1.0

package/src/backend-runner.ts

@@ -0,0 +1,251 @@
+import type {
+  AgentEffectAdmission,
+  AgentHandle,
+} from "@frockbot/kernel-agent-loop/agent";
+import {
+  type PersistSessionEvents,
+  type SessionEvent,
+  type SkillRefV1,
+  turnFailureMessage,
+  type TurnTypeV1,
+  validateToolOccurrenceJournal,
+} from "@frockbot/kernel-contracts";
+import type { ShellMountedComposition } from "./backend-composition.js";
+import {
+  BotTurnExecutionError,
+  BotTurnReconciliationRequiredError,
+  BotTurnRecoveryRequiredError,
+} from "@frockbot/kernel-do";
+import type { BotTurnCommand, BotTurnCompletion } from "./backend-contracts.js";
+
+export {
+  BotTurnExecutionError,
+  BotTurnReconciliationRequiredError,
+  BotTurnRecoveryRequiredError,
+};
+
+function appendedSessionEvents(
+  previous: readonly SessionEvent[],
+  candidate: readonly SessionEvent[],
+): SessionEvent[] {
+  if (
+    candidate.length < previous.length ||
+    previous.some(
+      (event, index) =>
+        JSON.stringify(event) !== JSON.stringify(candidate[index]),
+    )
+  ) {
+    throw new Error("candidate changed durable session history");
+  }
+  return structuredClone(candidate.slice(previous.length));
+}
+
+/**
+ * Classifies one finished Agent handle against the durable history it started
+ * from. Shared by the Composition-mounted and the resident execution paths, so
+ * both reach exactly the same durable terminal, recovery, or reconciliation
+ * outcome.
+ */
+function settleBotTurn(
+  handle: AgentHandle,
+  command: BotTurnCommand,
+  previousEvents: readonly SessionEvent[],
+): BotTurnCompletion {
+  const events = [...handle.agent.session.events];
+  const turnStart = events.findLast((event) => event.type === "turn/start");
+  const currentTurn =
+    turnStart?.type === "turn/start" ? turnStart.turn : undefined;
+  const terminalTurn = events.findLast(
+    (event) => event.type === "turn/end" && event.turn === currentTurn,
+  );
+  if (!terminalTurn || terminalTurn.type !== "turn/end") {
+    const unresolvedTool = [
+      ...validateToolOccurrenceJournal(events).values(),
+    ].find((entry) => entry.intent && !entry.result);
+    if (unresolvedTool) {
+      throw new BotTurnReconciliationRequiredError(
+        `Tool effect "${unresolvedTool.occurrence.occurrenceId}" requires reconciliation`,
+        appendedSessionEvents(previousEvents, events),
+      );
+    }
+    const reconciliation = events.findLast(
+      (event) =>
+        event.type === "model/reconciliation-required" &&
+        event.turn === currentTurn,
+    );
+    if (reconciliation?.type === "model/reconciliation-required") {
+      throw new BotTurnReconciliationRequiredError(
+        reconciliation.reason,
+        appendedSessionEvents(previousEvents, events),
+      );
+    }
+    const latestRequest = events.findLast(
+      (event) => event.type === "model/request" && event.turn === currentTurn,
+    );
+    const hasDurableOutcome =
+      latestRequest?.type === "model/request" &&
+      events.some(
+        (event) =>
+          (event.type === "assistant/message" ||
+            event.type === "model/effect-not-started") &&
+          event.requestId === latestRequest.request.requestId,
+      );
+    if (hasDurableOutcome) {
+      throw new BotTurnRecoveryRequiredError(
+        appendedSessionEvents(previousEvents, events),
+      );
+    }
+    throw new BotTurnExecutionError(
+      "Bot turn did not reach a durable terminal state",
+      appendedSessionEvents(previousEvents, events),
+    );
+  }
+  if (terminalTurn.outcome !== "completed") {
+    throw new BotTurnExecutionError(
+      turnFailureMessage(terminalTurn.outcome, terminalTurn.reason),
+      appendedSessionEvents(previousEvents, events),
+    );
+  }
+  const message = handle.agent.session.deriveMessages().at(-1);
+  const assistantText = message?.role === "assistant" ? message.content : "";
+  return {
+    runId: command.runId,
+    // A Turn the Bot ended by speaking through `send_to_user` writes no
+    // assistant message at all, so the derived text falls back to the last
+    // text payload it sent. Every other payload leaves the text empty and
+    // reaches the client as a projected `send/to-user` event instead.
+    text: assistantText || lastSentTextV1(events),
+    events: appendedSessionEvents(previousEvents, events),
+  };
+}
+
+/** The last `text` payload the Turn sent, or `""` when it sent none. */
+function lastSentTextV1(events: readonly SessionEvent[]): string {
+  const sent = events.findLast(
+    (event) => event.type === "send/to-user" && event.payload.type === "text",
+  );
+  return sent?.type === "send/to-user" && sent.payload.type === "text"
+    ? sent.payload.text
+    : "";
+}
+
+function turnExecutionError(
+  error: unknown,
+  previousEvents: readonly SessionEvent[],
+  events: readonly SessionEvent[],
+): never {
+  if (
+    error instanceof BotTurnExecutionError ||
+    error instanceof BotTurnReconciliationRequiredError ||
+    error instanceof BotTurnRecoveryRequiredError
+  ) {
+    throw error;
+  }
+  throw new BotTurnExecutionError(
+    error instanceof Error ? error.message : "Bot turn failed",
+    appendedSessionEvents(previousEvents, events),
+  );
+}
+
+export interface ExecuteBotTurnOptions {
+  command: BotTurnCommand;
+  previousEvents: readonly SessionEvent[];
+  /** The mounted Composition for the generation this Turn was pinned to. */
+  composition: ShellMountedComposition;
+  resume?: boolean;
+}
+
+export async function executeBotTurn(
+  options: ExecuteBotTurnOptions,
+): Promise<BotTurnCompletion> {
+  const { command, previousEvents, composition, resume } = options;
+  const runtime = composition.runtime;
+  try {
+    if (resume) runtime.agent.agent.resume();
+    else {
+      runtime.agent.agent.send({
+        text: command.text,
+        ...(command.skills ? { skills: command.skills } : {}),
+      });
+    }
+    await runtime.agent.agent.whenIdle();
+    return settleBotTurn(runtime.agent, command, previousEvents);
+  } catch (error) {
+    turnExecutionError(error, previousEvents, [
+      ...runtime.agent.agent.session.events,
+    ]);
+  } finally {
+    await composition.dispose();
+  }
+}
+
+export interface ExecuteResidentBotTurnOptions {
+  botId: string;
+  command: BotTurnCommand;
+  previousEvents: readonly SessionEvent[];
+  persistSessionEvents: PersistSessionEvents;
+  beforeStart(): Promise<boolean>;
+  admitEffect(effect: AgentEffectAdmission): Promise<boolean>;
+  resume?: boolean;
+}
+
+export interface ResidentTurnRuntime {
+  execute(input: {
+    botId: string;
+    sessionId: string;
+    runId: string;
+    previousEvents: readonly SessionEvent[];
+    persistSessionEvents: PersistSessionEvents;
+    beforeStart(): Promise<boolean>;
+    admitEffect(effect: AgentEffectAdmission): Promise<boolean>;
+    resume?: boolean;
+    text: string;
+    skills?: SkillRefV1[];
+    turnType: TurnTypeV1;
+    subagentRole?: string;
+  }): Promise<AgentHandle>;
+}
+
+/**
+ * Runs one Turn on the Bot Durable Object's resident Cordis root. The root
+ * outlives the Turn, so nothing is disposed here; the durable effect fence and
+ * the session persistence are the caller's.
+ */
+export async function executeResidentBotTurn(
+  runtime: ResidentTurnRuntime,
+  options: ExecuteResidentBotTurnOptions,
+): Promise<BotTurnCompletion> {
+  const {
+    botId,
+    command,
+    previousEvents,
+    persistSessionEvents,
+    beforeStart,
+    admitEffect,
+    resume,
+  } = options;
+  let handle: AgentHandle | undefined;
+  try {
+    handle = await runtime.execute({
+      botId,
+      sessionId: command.sessionId,
+      runId: command.runId,
+      previousEvents,
+      persistSessionEvents,
+      beforeStart,
+      admitEffect,
+      resume,
+      text: command.text,
+      ...(command.skills ? { skills: command.skills } : {}),
+      turnType: command.turnType ?? "chat",
+      ...(command.subagentRole ? { subagentRole: command.subagentRole } : {}),
+    });
+    return settleBotTurn(handle, command, previousEvents);
+  } catch (error) {
+    turnExecutionError(
+      error,
+      previousEvents,
+      handle ? [...handle.agent.session.events] : [...previousEvents],
+    );
+  }
+}

package/src/backend-skills.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "bun:test";
+import { FakeWorkspace } from "@frockbot/plugin-skills/testing";
+import {
+  createBotPluginSkillsSource,
+  createBotSkillsHost,
+} from "./backend-skills.ts";
+
+const IDENTITY = { userId: "user-1", botId: "bot-1" };
+const TURN = { runId: "run-9", turnId: "turn-4", sessionId: "user-1:bot-1" };
+
+describe("the Bot Skills seam", () => {
+  test("mounts nothing when the Workspace file surface is unbound", () => {
+    expect(createBotSkillsHost(IDENTITY, TURN, {})).toBeUndefined();
+  });
+
+  test("binds the Bot's own root and its Turn provenance when it is bound", () => {
+    const workspace = new FakeWorkspace();
+    const host = createBotSkillsHost(IDENTITY, TURN, {
+      WORKSPACE_FILES: workspace,
+    });
+    expect(host).toBeDefined();
+    expect(host?.owner).toEqual(IDENTITY);
+    expect(host?.writer).toEqual({
+      sessionId: "user-1:bot-1",
+      turnId: "turn-4",
+      runId: "run-9",
+    });
+    expect(host?.reads).toBe(workspace);
+    expect(host?.files).toBe(workspace);
+    // The seam reaches the Workspace and nothing else: no Computer is opened
+    // to build it, so a hibernated Computer changes none of this.
+    expect(workspace.calls).toEqual([]);
+  });
+});
+
+describe("the plugin-borne Skill index seam", () => {
+  const READER = {
+    readEntry: (generation: string, catalogId: string) =>
+      Promise.resolve(
+        catalogId === "skillful"
+          ? {
+              packageId: "skillful",
+              skills: [
+                {
+                  name: "Roster check",
+                  description: "Use this when rostering.",
+                  body: `body at ${generation}`,
+                },
+              ],
+            }
+          : undefined,
+      ),
+  };
+
+  test("mounts nothing when no Catalog is bound", () => {
+    expect(createBotPluginSkillsSource([], undefined)).toBeUndefined();
+  });
+
+  test("reads only installed entries, at the generation each install pinned", async () => {
+    const source = createBotPluginSkillsSource(
+      [
+        {
+          packageId: "skillful",
+          state: "installed",
+          catalogId: "skillful",
+          catalogGeneration: "gen-3",
+        },
+        // A first-party install carries no Catalog identity, so there is no
+        // entry to index; a disabled Package's recipes are not read either.
+        { packageId: "clock", state: "installed" },
+        {
+          packageId: "off",
+          state: "disabled",
+          catalogId: "off",
+          catalogGeneration: "gen-3",
+        },
+      ],
+      READER,
+    );
+
+    expect(await source?.read()).toEqual({
+      status: "ok",
+      packages: [
+        {
+          packageId: "skillful",
+          catalogId: "skillful",
+          generation: "gen-3",
+          skills: [
+            {
+              name: "Roster check",
+              description: "Use this when rostering.",
+              body: "body at gen-3",
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  test("an uninstalled entry leaves nothing to index", async () => {
+    const source = createBotPluginSkillsSource([], READER);
+    expect(await source?.read()).toEqual({ status: "ok", packages: [] });
+  });
+
+  test("a Catalog read that throws is an unavailable index, not a failed Turn", async () => {
+    const source = createBotPluginSkillsSource(
+      [
+        {
+          packageId: "skillful",
+          state: "installed",
+          catalogId: "skillful",
+          catalogGeneration: "gen-3",
+        },
+      ],
+      {
+        readEntry: () => Promise.reject(new Error("R2 is down")),
+      },
+    );
+
+    const outcome = await source?.read();
+    expect(outcome?.status).toBe("unavailable");
+    expect(outcome?.status === "unavailable" ? outcome.reason : "").toContain(
+      "R2 is down",
+    );
+  });
+});

package/src/backend-skills.ts

@@ -0,0 +1,198 @@
+// The Bot Durable Object's half of the Skills seam.
+//
+// The Skills Package reads a Bot's instruction root through the
+// kernel-declared `WorkspaceReadsV1` and writes through `WorkspaceFilesV1`.
+// This module decides, for one admitted Turn, whether such a surface exists
+// and what provenance a write records. It implements neither interface.
+//
+// HIBERNATION. "The Agent loop, Memory, Skills, Package composition, and
+// Routines function correctly while the Computer is hibernated and do not wake
+// it." Nothing here reaches the Computer registry, a Computer provider, or a
+// Sprite. The Workspace surface handed to the Skills Package is a binding on
+// the Durable Object's environment, and the durable-root sync of ADR 0013
+// backs it from object storage; whether a Computer host happens to be running
+// changes nothing above this line.
+//
+// SEAM. `WORKSPACE_FILES` is bound in production by
+// `apps/cloudflare/src/workspace.ts`: `WorkspaceFilesV1` over object storage,
+// with every generation recorded in this Bot's Durable Object (Step 3a of
+// `docs/plans/slice-2.md`). A host that binds nothing — a test, a shell with no
+// bucket — still gets `undefined` here, and the Skills Package is then not
+// mounted at all: a Turn with no readable instruction root loads no
+// instructions, visibly, rather than inventing a second store to read them
+// from.
+import type {
+  WorkspaceFilesV1,
+  WorkspaceReadsV1,
+} from "@frockbot/kernel-contracts";
+import type { SkillsRuntimeHostV1 } from "@frockbot/plugin-skills/agent";
+import type {
+  PluginSkillPackageV1,
+  PluginSkillsSourceV1,
+} from "@frockbot/plugin-skills/plugin-index";
+
+/** The Bot and User whose Skills a Turn may load. */
+export interface BotSkillsIdentity {
+  userId: string;
+  botId: string;
+}
+
+/** The run, Turn, and Session a Bot-authored Skill records as its provenance. */
+export interface BotSkillsTurn {
+  runId: string;
+  turnId: string;
+  sessionId: string;
+}
+
+/**
+ * The narrow slice of the Durable Object environment this module reads. Named
+ * as its own type so the binding's absence is a typed state, not a cast.
+ */
+export interface BotSkillsEnv {
+  WORKSPACE_FILES?: WorkspaceFilesV1;
+  /**
+   * The Package Catalog reader, constructed onto the Bot Durable Object's
+   * environment the same way `WORKSPACE_FILES` is. Absent for a deployment
+   * with no Catalog, and the Turn then carries no plugin-borne Skills.
+   */
+  PACKAGE_CATALOG_ENTRIES?: BotSkillCatalogReaderV1;
+}
+
+/**
+ * The Skills seam one admitted Turn runs under, or `undefined` when the Bot's
+ * Workspace file surface is unavailable.
+ */
+export function createBotSkillsHost(
+  identity: BotSkillsIdentity,
+  turn: BotSkillsTurn,
+  env: object,
+  pluginSkills?: PluginSkillsSourceV1,
+): SkillsRuntimeHostV1 | undefined {
+  // SAFETY: the Workspace file surface is constructed onto the Durable Object
+  // environment rather than declared in the generated `Env`, because it is not
+  // a Worker binding. Absence is a supported state, not an error.
+  const files = (env as BotSkillsEnv).WORKSPACE_FILES;
+  if (!files) return undefined;
+  return {
+    owner: { userId: identity.userId, botId: identity.botId },
+    reads: files,
+    files,
+    // A Bot writes a Skill only inside a Turn whose run, Turn and Session its
+    // provenance names — the same rule Package authoring follows.
+    writer: {
+      sessionId: turn.sessionId,
+      turnId: turn.turnId,
+      runId: turn.runId,
+    },
+    ...(pluginSkills ? { pluginSkills } : {}),
+  };
+}
+
+/**
+ * The read-only half of the same seam, for a question asked outside a Turn.
+ *
+ * The composer's `/` and `@` popover needs the Bot's Skill catalog before any
+ * Turn exists, and reading a catalog needs no provenance: there is nothing to
+ * attribute. So this returns reads and no writer at all — a caller holding it
+ * can enumerate an instruction root and can write nothing.
+ */
+export function createBotSkillsReads(
+  env: object,
+): WorkspaceReadsV1 | undefined {
+  return (env as BotSkillsEnv).WORKSPACE_FILES;
+}
+
+/**
+ * The Catalog reader the plugin-borne Skill index needs, named structurally.
+ *
+ * Structural rather than imported so this module keeps naming no Cloudflare
+ * type: `R2PackageCatalog` in `apps/cloudflare/src/package-catalog.ts` already
+ * satisfies it, and a test satisfies it with an object literal. The reader is
+ * asked for one entry at one *pinned* generation, never for the live pointer:
+ * a Turn reads exactly the immutable generation its User is pinned to.
+ */
+export interface BotSkillCatalogReaderV1 {
+  readEntry(
+    generation: string,
+    catalogId: string,
+  ): Promise<
+    | {
+        packageId: string;
+        skills: readonly {
+          name: string;
+          description?: string;
+          body?: string;
+        }[];
+      }
+    | undefined
+  >;
+}
+
+/** One installed Package, as the User's settings record it. */
+export interface BotInstalledPackageV1 {
+  packageId: string;
+  state: "installed" | "disabled" | "failed";
+  catalogId?: string;
+  catalogGeneration?: string;
+}
+
+/**
+ * The plugin-borne Skill index for one Turn.
+ *
+ * Reads only the entries the User has actually installed, at the generation
+ * each install recorded. That is what makes an uninstall remove a Skill: the
+ * row is gone from the User's settings, so the next Turn's index does not
+ * name it, and no copy of the body exists anywhere to go stale. A disabled
+ * Package contributes nothing either — a Bot that may not run a Package's
+ * tools should not be reading its recipes.
+ */
+export function createBotPluginSkillsSource(
+  installed: readonly BotInstalledPackageV1[],
+  reader: BotSkillCatalogReaderV1 | undefined,
+): PluginSkillsSourceV1 | undefined {
+  if (!reader) return undefined;
+  const rows = installed.filter(
+    (row) =>
+      row.state === "installed" &&
+      row.catalogId !== undefined &&
+      row.catalogGeneration !== undefined,
+  );
+  return {
+    read: async () => {
+      const packages: PluginSkillPackageV1[] = [];
+      for (const row of rows) {
+        const catalogId = row.catalogId as string;
+        const generation = row.catalogGeneration as string;
+        try {
+          const entry = await reader.readEntry(generation, catalogId);
+          if (!entry) continue;
+          if (entry.skills.length === 0) continue;
+          packages.push({
+            packageId: entry.packageId,
+            catalogId,
+            generation,
+            skills: entry.skills,
+          });
+        } catch (error) {
+          // A Catalog read that fails is an unavailable index, not a failed
+          // Turn: the loader records it as a refusal in `skill/injected` and
+          // the Bot runs with the Skills it could read.
+          return {
+            status: "unavailable",
+            reason: `Catalog entry "${catalogId}" at generation "${generation}" could not be read: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          };
+        }
+      }
+      return { status: "ok", packages };
+    },
+  };
+}
+
+/** The Catalog reader bound on this host, or `undefined` when there is none. */
+export function createBotSkillCatalogReader(
+  env: object,
+): BotSkillCatalogReaderV1 | undefined {
+  return (env as BotSkillsEnv).PACKAGE_CATALOG_ENTRIES;
+}