@frockbot/plugin-shell 0.0.0 → 0.1.1

package/src/backend-isolate.ts

@@ -0,0 +1,409 @@
+// The Bot Durable Object half of the isolate capability boundary.
+//
+// A loaded Bot Package sees exactly two bindings: `IDENTITY` (a plain object)
+// and `CAPABILITIES` (a loopback service binding). Every method behind
+// `CAPABILITIES` ends up here, in the authority that owns the Bot's durable
+// state — so an authority-widening request becomes a durable pending decision
+// rather than a grant, and a model call records its normalized request and
+// acquires its credential lease through the existing provider path before a
+// single byte leaves the account.
+import type {
+  IsolateAuthorityRequestV1,
+  IsolateCapabilityDescriptorV1,
+  IsolateModelInvocationV1,
+  IsolatePendingDecisionV1,
+  LlmStreamEvent,
+  NormalizedModelRequest,
+} from "@frockbot/kernel-contracts";
+import {
+  decodeIsolateAuthorityRequestV1,
+  encodeIsolateModelEventLineV1,
+} from "@frockbot/kernel-contracts";
+import type { BotIsolateArtifactStore } from "@frockbot/kernel-composition/isolate";
+
+/**
+ * The compatibility date every Bot isolate is loaded with. Pinned beside the
+ * gateway Worker's own so Bot-authored code cannot outrun the kernel wrapper.
+ */
+export const BOT_ISOLATE_COMPATIBILITY_DATE = "2026-08-27";
+
+/**
+ * What travels in `ctx.exports.BotCapabilities({ props })`. Structured-clonable
+ * by necessity: props cross into a loopback service binding.
+ */
+export interface BotCapabilitiesPropsV1 {
+  userId: string;
+  botId: string;
+  generationId: string;
+  packageId: string;
+  /** Already resolved and filtered to enabled Assignments by the authority. */
+  assignments: IsolateAssignmentV1[];
+}
+
+export const ISOLATE_DECISION_PREFIX = "isolate:decision:";
+export const ISOLATE_MODEL_REQUEST_PREFIX = "isolate:model-request:";
+
+/** A durable record that the Bot asked for authority it does not hold. */
+export interface IsolatePendingAuthorityDecisionV1 {
+  schemaVersion: 1;
+  decisionId: string;
+  botId: string;
+  packageId: string;
+  generationId: string;
+  capabilityId: string;
+  reason: string;
+  requestedAt: string;
+  status: "pending";
+}
+
+/** The intent recorded before a Bot-authored adapter's model call is forwarded. */
+export interface IsolateModelRequestRecordV1 {
+  schemaVersion: 1;
+  /** Minted by this Durable Object; the record is keyed by it. */
+  recordId: string;
+  /** The Bot's own correlation id. Bounded, and never a storage key. */
+  requestId: string;
+  botId: string;
+  packageId: string;
+  generationId: string;
+  capabilityId: string;
+  request: NormalizedModelRequest;
+  recordedAt: string;
+}
+
+/** The narrow storage surface this module needs from the Durable Object. */
+export interface IsolateCapabilityStore {
+  put(key: string, value: unknown): Promise<void>;
+  get<T>(key: string): Promise<T | undefined>;
+  list<T>(options: { prefix: string }): Promise<Map<string, T>>;
+}
+
+/** One enabled Assignment, already resolved the way `plugin-shell` resolves them. */
+export interface IsolateAssignmentV1 {
+  assignmentId: string;
+  packageId: string;
+  capabilityId: string;
+  kind: IsolateCapabilityDescriptorV1["kind"];
+  connectionId?: string;
+  providerModelId?: string;
+}
+
+/**
+ * The Bot's durable model binding, resolved by the authority from the Bot's
+ * own configuration and the User's Connection — never from anything the Bot
+ * supplied. An `invokeModel` request is authorized only when it names exactly
+ * this provider and this model, and it is forwarded carrying exactly this
+ * binding.
+ */
+export interface IsolateModelBindingV1 {
+  assignmentId: string;
+  packageId: string;
+  capabilityId: string;
+  connectionId: string;
+  provider: string;
+  providerModelId: string;
+  connectionGeneration?: string;
+  catalogGeneration?: string;
+}
+
+/** The bound Bot-supplied correlation id: a field, never a key, and never unbounded. */
+export const MAX_ISOLATE_REQUEST_ID = 256;
+
+export interface IsolateModelPath {
+  /** Streams through the mounted provider Plugin; the lease is taken inside it. */
+  stream(
+    request: NormalizedModelRequest,
+    signal: AbortSignal,
+  ): AsyncIterable<LlmStreamEvent>;
+}
+
+export interface IsolateCapabilityHostOptions {
+  storage: IsolateCapabilityStore;
+  botId: string;
+  packageId: string;
+  generationId: string;
+  /** Assignment-derived and nothing else. */
+  assignments: readonly IsolateAssignmentV1[];
+  /**
+   * The one model binding this Bot durably holds, or absent when it holds
+   * none. Absent means every model request is a pending decision.
+   */
+  modelBinding?: IsolateModelBindingV1;
+  /** Absent when the Bot has no enabled model Assignment at all. */
+  modelPath?: IsolateModelPath;
+  now?(): Date;
+  newId?(): string;
+}
+
+export interface IsolateCapabilityHost {
+  list(): Promise<IsolateCapabilityDescriptorV1[]>;
+  requestAuthority(request: unknown): Promise<IsolatePendingDecisionV1>;
+  invokeModel(
+    request: NormalizedModelRequest,
+  ): Promise<IsolateModelInvocationV1>;
+  pendingDecisions(): Promise<IsolatePendingAuthorityDecisionV1[]>;
+  recordedModelRequests(): Promise<IsolateModelRequestRecordV1[]>;
+}
+
+/**
+ * The enabled model Assignment that can serve this request, if any.
+ *
+ * An Assignment authorizes exactly one Package, one Connection, and one
+ * provider model: the Bot's durable binding. A request naming any other
+ * provider or model resolves to nothing, whatever the Bot claims about it —
+ * the Bot-supplied `modelBinding` is never read here or anywhere downstream.
+ */
+export function matchingModelAssignmentV1(
+  assignments: readonly IsolateAssignmentV1[],
+  binding: IsolateModelBindingV1 | undefined,
+  request: NormalizedModelRequest,
+): IsolateAssignmentV1 | undefined {
+  if (!binding) return undefined;
+  if (
+    request.provider !== binding.provider ||
+    request.model !== binding.providerModelId
+  ) {
+    return undefined;
+  }
+  return assignments.find(
+    (assignment) =>
+      assignment.kind === "model" &&
+      assignment.assignmentId === binding.assignmentId &&
+      assignment.packageId === binding.packageId &&
+      assignment.capabilityId === binding.capabilityId &&
+      assignment.connectionId === binding.connectionId &&
+      assignment.providerModelId === binding.providerModelId,
+  );
+}
+
+export function createIsolateCapabilityHost(
+  options: IsolateCapabilityHostOptions,
+): IsolateCapabilityHost {
+  const now = options.now ?? (() => new Date());
+  const newId = options.newId ?? (() => crypto.randomUUID());
+
+  async function recordDecision(
+    capabilityId: string,
+    reason: string,
+  ): Promise<IsolatePendingDecisionV1> {
+    const decisionId = `decision-${newId()}`;
+    const record: IsolatePendingAuthorityDecisionV1 = {
+      schemaVersion: 1,
+      decisionId,
+      botId: options.botId,
+      packageId: options.packageId,
+      generationId: options.generationId,
+      capabilityId,
+      reason,
+      requestedAt: now().toISOString(),
+      status: "pending",
+    };
+    await options.storage.put(
+      `${ISOLATE_DECISION_PREFIX}${decisionId}`,
+      record,
+    );
+    return { status: "pending-user-decision", decisionId };
+  }
+
+  return {
+    list(): Promise<IsolateCapabilityDescriptorV1[]> {
+      return Promise.resolve(
+        options.assignments.map((assignment) => ({
+          capabilityId: assignment.capabilityId,
+          kind: assignment.kind,
+        })),
+      );
+    },
+
+    async requestAuthority(
+      request: unknown,
+    ): Promise<IsolatePendingDecisionV1> {
+      const decoded: IsolateAuthorityRequestV1 =
+        decodeIsolateAuthorityRequestV1(request);
+      // Self-modification never widens authority, even when the capability is
+      // already assigned: the answer is a decision the User makes.
+      return await recordDecision(decoded.capabilityId, decoded.reason);
+    },
+
+    async invokeModel(
+      request: NormalizedModelRequest,
+    ): Promise<IsolateModelInvocationV1> {
+      if (request.requestId.length > MAX_ISOLATE_REQUEST_ID) {
+        throw new Error("isolate model request requestId is not bounded");
+      }
+      const binding = options.modelBinding;
+      const assignment = matchingModelAssignmentV1(
+        options.assignments,
+        binding,
+        request,
+      );
+      if (!assignment || !binding || !options.modelPath) {
+        return await recordDecision(
+          `models:${request.provider}:${request.model}`,
+          `Bot Package "${options.packageId}" asked to invoke a model with no matching enabled Assignment`,
+        );
+      }
+      // The binding the provider path receives is the authority's, never the
+      // Bot's: a Bot-composed request carries no Connection authority.
+      const forwarded: NormalizedModelRequest = {
+        ...structuredClone(request),
+        modelBinding: {
+          connectionId: binding.connectionId,
+          ...(binding.connectionGeneration
+            ? { connectionGeneration: binding.connectionGeneration }
+            : {}),
+          ...(binding.catalogGeneration
+            ? { catalogGeneration: binding.catalogGeneration }
+            : {}),
+        },
+      };
+      // Record the exact normalized request before forwarding; the provider
+      // path takes the credential lease on the way through. The record is
+      // keyed by an id this authority mints, so a Bot cannot overwrite one of
+      // its own earlier records by reusing a `requestId`.
+      const recordId = `model-request-${newId()}`;
+      const record: IsolateModelRequestRecordV1 = {
+        schemaVersion: 1,
+        recordId,
+        requestId: request.requestId,
+        botId: options.botId,
+        packageId: options.packageId,
+        generationId: options.generationId,
+        capabilityId: assignment.capabilityId,
+        request: forwarded,
+        recordedAt: now().toISOString(),
+      };
+      await options.storage.put(
+        `${ISOLATE_MODEL_REQUEST_PREFIX}${recordId}`,
+        record,
+      );
+      const controller = new AbortController();
+      const events = options.modelPath.stream(forwarded, controller.signal);
+      return {
+        status: "streaming",
+        requestId: request.requestId,
+        events: isolateModelEventStreamV1(events, controller),
+      };
+    },
+
+    async pendingDecisions(): Promise<IsolatePendingAuthorityDecisionV1[]> {
+      const stored =
+        await options.storage.list<IsolatePendingAuthorityDecisionV1>({
+          prefix: ISOLATE_DECISION_PREFIX,
+        });
+      return [...stored.values()];
+    },
+
+    async recordedModelRequests(): Promise<IsolateModelRequestRecordV1[]> {
+      const stored = await options.storage.list<IsolateModelRequestRecordV1>({
+        prefix: ISOLATE_MODEL_REQUEST_PREFIX,
+      });
+      return [...stored.values()];
+    },
+  };
+}
+
+/**
+ * Model events cross the isolate boundary as an NDJSON byte stream. A
+ * `ReadableStream` of JavaScript objects is not transferable over workerd RPC;
+ * a byte stream is, so the kernel encodes here and the generated wrapper
+ * decodes on the far side.
+ */
+export const ISOLATE_MODEL_FAILURE_MESSAGE =
+  "the model provider did not complete this request";
+
+export function isolateModelEventStreamV1(
+  events: AsyncIterable<LlmStreamEvent>,
+  controller?: AbortController,
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  const iterator = events[Symbol.asyncIterator]();
+  return new ReadableStream<Uint8Array>({
+    async pull(stream) {
+      try {
+        const next = await iterator.next();
+        if (next.done) {
+          stream.close();
+          return;
+        }
+        stream.enqueue(
+          encoder.encode(encodeIsolateModelEventLineV1(next.value)),
+        );
+      } catch {
+        // Provider errors are normalized before they cross into Bot code: a
+        // raw provider message can name endpoints, account state, or the
+        // credential that failed. The Bot learns that the request did not
+        // complete and nothing else; the durable record and the provider
+        // Plugin keep the detail.
+        stream.error(new Error(ISOLATE_MODEL_FAILURE_MESSAGE));
+      }
+    },
+    cancel(reason) {
+      controller?.abort(reason);
+      return iterator.return?.(undefined).then(() => undefined);
+    },
+  });
+}
+
+/**
+ * The content address of the bindings an isolate is loaded with: its
+ * Assignments and the Composition generation whose `CAPABILITIES` stub is
+ * baked into its `env`. A loader id is served from cache, so a Bot whose
+ * Assignments change must get a different isolate rather than one that keeps a
+ * revoked binding — and a new generation must get a different isolate rather
+ * than one whose `env` still names the generation it was first loaded under.
+ * Both are bindings the isolate was granted, so both belong in this digest and
+ * the loader id stays derived from the artifact set and the binding digest
+ * alone.
+ */
+export async function isolateBindingDigestV1(
+  assignments: readonly IsolateAssignmentV1[],
+  generationId: string,
+): Promise<string> {
+  const ordered = [...assignments]
+    .map((assignment) => ({
+      assignmentId: assignment.assignmentId,
+      packageId: assignment.packageId,
+      capabilityId: assignment.capabilityId,
+      kind: assignment.kind,
+      connectionId: assignment.connectionId ?? null,
+      providerModelId: assignment.providerModelId ?? null,
+    }))
+    .sort((left, right) => left.assignmentId.localeCompare(right.assignmentId));
+  return await sha256Hex(JSON.stringify({ generationId, ordered }));
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(value),
+  );
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Reads a Bot Package artifact from object storage and verifies its content
+ * address before a byte of it becomes code. Artifacts are immutable content,
+ * not state; the hash is the only thing that makes them safe to mount.
+ */
+export function createR2PackageArtifactStore(
+  bucket: R2Bucket,
+): BotIsolateArtifactStore {
+  return {
+    async loadPackageArtifact(contentHash: string): Promise<string> {
+      const object = await bucket.get(`packages/${contentHash}.mjs`);
+      if (!object) {
+        throw new Error(`package artifact "${contentHash}" is missing`);
+      }
+      const module = await object.text();
+      if ((await sha256Hex(module)) !== contentHash) {
+        throw new Error(
+          `package artifact "${contentHash}" failed hash verification`,
+        );
+      }
+      return module;
+    },
+  };
+}

package/src/backend-machine.ts

@@ -0,0 +1,144 @@
+// The Bot Durable Object's side of the registered machine (register rows 48,
+// 49).
+//
+// Three seams, and no rules: the rules are `plugin-user-machine`'s, and the
+// authority for the registry and the queue is the User Durable Object's. What
+// lives here is the wiring one admitted Turn needs —
+//
+//  * the runtime host the machine tools are handed, carrying this Bot's own
+//    durable storage (where an intent record lives) and four closed-over calls
+//    into the User object;
+//  * the dispatch the approval settlement performs once a person has said yes.
+//
+// The Shell owns this file for the same reason it owns `backend-routines.ts`:
+// it is the object that holds the approval record, the alarm that expires it,
+// and the route a person answers on, so the hand-off from "decided" to "queued"
+// has nowhere else it could honestly live.
+import type {
+  MachineCommandResultV1,
+  MachineCommandV1,
+  MachineListViewV1,
+} from "@frockbot/machine-protocol";
+import type { MachineMessagesRuntimeHostV1 } from "@frockbot/plugin-machine-messages/agent";
+import {
+  machineMessagesEnabledV1,
+  machineMessagesGateV1,
+  type MachineMessagesGateV1,
+} from "@frockbot/plugin-machine-messages/gate";
+import type {
+  MachineIntentStorageV1,
+  MachineRuntimeHostV1,
+  MachineWriterIdentityV1,
+} from "@frockbot/plugin-user-machine/agent";
+import {
+  dispatchMachineIntentV1,
+  type MachineDispatchAnswerV1,
+} from "@frockbot/plugin-user-machine/approval";
+import type { MachineIntentRecordV1 } from "@frockbot/plugin-user-machine/intent";
+import type { MachineTargetViewV1 } from "@frockbot/plugin-user-machine/target";
+
+/** The User Durable Object, as this Bot is allowed to see its machines. */
+export interface BotMachineSeamV1 {
+  list(): Promise<MachineListViewV1>;
+  describeTarget(machineId: string): Promise<MachineTargetViewV1>;
+  readResult(commandId: string): Promise<MachineCommandResultV1 | undefined>;
+  dispatch(command: MachineCommandV1): Promise<MachineDispatchAnswerV1>;
+}
+
+/** The Turn an intent record is attributed to. */
+export interface BotMachineTurnV1 {
+  sessionId: string;
+  turnId: string;
+  runId: string;
+}
+
+/**
+ * The runtime host for one admitted Turn.
+ *
+ * `storage` is the Bot's own, because an intent is Bot-scoped durable state:
+ * it is what the settlement reads back from an `approvalId` to know what a
+ * person actually approved.
+ */
+export function createBotMachineHost(
+  identity: { botId: string },
+  turn: BotMachineTurnV1,
+  storage: MachineIntentStorageV1,
+  seam: BotMachineSeamV1,
+): MachineRuntimeHostV1 {
+  return {
+    botId: identity.botId,
+    writer: {
+      sessionId: turn.sessionId,
+      turnId: turn.turnId,
+      runId: turn.runId,
+    },
+    storage,
+    list: () => seam.list(),
+    describeTarget: (machineId) => seam.describeTarget(machineId),
+    readResult: (commandId) => seam.readResult(commandId),
+  };
+}
+
+/**
+ * Put an approved command on its machine's queue, after the decision has
+ * committed.
+ *
+ * Outside the settling transaction on purpose: a cross-Durable-Object call
+ * inside one would make its atomicity a lie. It does not need to be inside
+ * one — the dispatch is idempotent on `commandId`, which is the Turn's own
+ * `effectId`, so a crash between the commit and this call is a retry and never
+ * a second command on somebody's laptop.
+ */
+export async function dispatchApprovedMachineIntentV1(
+  storage: MachineIntentStorageV1,
+  intent: MachineIntentRecordV1,
+  seam: Pick<BotMachineSeamV1, "dispatch">,
+  now: () => string = () => new Date().toISOString(),
+): Promise<MachineIntentRecordV1> {
+  return dispatchMachineIntentV1(
+    storage,
+    intent,
+    (command) => seam.dispatch(command),
+    now(),
+  );
+}
+
+/**
+ * Row 57g's gate, answered for one Turn.
+ *
+ * Two facts and one read. The setting is already in hand — it came from the
+ * same User configuration the rest of this Composition was resolved from — and
+ * the registry is asked for only when it is on, so a deployment with the
+ * feature off pays nothing for it.
+ *
+ * `undefined` means the tools are not mounted: off, or no connected macOS
+ * machine reporting `messages`. A Bot never sees a Messages tool it could only
+ * be refused by.
+ */
+export async function resolveBotMachineMessagesGateV1(
+  settings: Readonly<Record<string, string | number | boolean>> | undefined,
+  list: () => Promise<MachineListViewV1>,
+): Promise<MachineMessagesGateV1> {
+  if (!machineMessagesEnabledV1(settings)) return { status: "off" };
+  const view = await list();
+  return machineMessagesGateV1({ enabled: true, machines: view.machines });
+}
+
+/**
+ * The Messages host for one admitted Turn.
+ *
+ * It is the machine host plus `dispatch`, and it exists only because the six
+ * approval-exempt reads have no settlement to ride: `machine_exec` is queued by
+ * the approval settlement, and a read has no approval. Nothing else widens —
+ * the Package cannot enrol, revoke, or reach any machine this User does not
+ * own, because the seam it is handed is the same one the control tools use.
+ */
+export function createBotMachineMessagesHost(
+  machines: MachineRuntimeHostV1 & { writer: MachineWriterIdentityV1 },
+  seam: Pick<BotMachineSeamV1, "dispatch">,
+): MachineMessagesRuntimeHostV1 {
+  return {
+    machines,
+    dispatch: (command) => seam.dispatch(command),
+  };
+}

package/src/backend-memory.ts

@@ -0,0 +1,89 @@
+// The Bot Durable Object's half of the Memory seam.
+//
+// The Memory Package reads and writes Memory roots through a `MemoryStore`
+// over `WorkspaceFilesV1`. This module decides, for one admitted Turn, whether
+// such a surface exists, what provenance a write records, and where Project
+// membership is kept. It implements none of those.
+//
+// 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 surface handed to the Memory Package is a binding on the Durable
+// Object's environment, backed by object storage under ADR 0013; whether a
+// Computer host happens to be running changes nothing above this line.
+//
+// SEAM. `MEMORY_WORKSPACE_FILES` is bound in production by
+// `apps/cloudflare/src/bot-state.ts`: `WorkspaceFilesV1` with `surface:
+// "memory"`, so it serves Memory roots and refuses every other, with shared
+// roots' generations recorded in the *User* Durable Object and the Bot's own
+// root in the Bot's. A host that binds nothing gets `undefined` and the Memory
+// Package is then not mounted at all: a Turn with no readable Memory root
+// injects no Memory, visibly, rather than inventing a second store.
+import type { WorkspaceFilesV1 } from "@frockbot/kernel-contracts";
+import type {
+  MemoryProjectsV1,
+  MemoryRuntimeHostV1,
+} from "@frockbot/plugin-memory/agent";
+import { MemoryStore } from "@frockbot/plugin-memory/store";
+
+/** The Bot and User whose Memory a Turn may read and write. */
+export interface BotMemoryIdentity {
+  userId: string;
+  botId: string;
+}
+
+/** The run, Turn, and Session a Memory write records as its provenance. */
+export interface BotMemoryTurn {
+  runId: string;
+  turnId: string;
+  sessionId: string;
+}
+
+/**
+ * The narrow slice of the Durable Object environment this module reads. Named
+ * as its own type so each binding's absence is a typed state, not a cast.
+ */
+export interface BotMemoryEnv {
+  /** `WorkspaceFilesV1` with the Memory surface. Absent in a host with no bucket. */
+  MEMORY_WORKSPACE_FILES?: WorkspaceFilesV1;
+  /** The durable Project authority, in the User Durable Object. */
+  MEMORY_PROJECTS?: MemoryProjectsV1;
+  /** Display names per Bot id, for the `[via …]` tag on a shared fact. */
+  MEMORY_BOT_NAMES?: Readonly<Record<string, string>>;
+}
+
+/**
+ * The Memory seam one admitted Turn runs under, or `undefined` when the Bot's
+ * Memory surface is unavailable.
+ */
+export function createBotMemoryHost(
+  identity: BotMemoryIdentity,
+  turn: BotMemoryTurn,
+  env: object,
+): MemoryRuntimeHostV1 | undefined {
+  // SAFETY: the Memory 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 bindings = env as BotMemoryEnv;
+  const files = bindings.MEMORY_WORKSPACE_FILES;
+  if (!files) return undefined;
+  const owner = { userId: identity.userId, botId: identity.botId };
+  return {
+    owner,
+    store: new MemoryStore({
+      files,
+      owner,
+      ...(bindings.MEMORY_BOT_NAMES
+        ? { botNames: bindings.MEMORY_BOT_NAMES }
+        : {}),
+    }),
+    // A Bot changes Memory only inside a Turn whose run, Turn and Session its
+    // provenance names — the same rule Skills and Package authoring follow.
+    writer: {
+      sessionId: turn.sessionId,
+      turnId: turn.turnId,
+      runId: turn.runId,
+    },
+    ...(bindings.MEMORY_PROJECTS ? { projects: bindings.MEMORY_PROJECTS } : {}),
+  };
+}