@frockbot/plugin-shell 0.0.0 → 0.1.1

package/src/backend-composition.ts

@@ -0,0 +1,242 @@
+// The Shell Package owns the Composition a Turn runs on. First-party members
+// are the compiled Foundation runtime, mounted in the kernel isolate; members
+// carrying an immutable artifact are Bot isolate members, mounted through the
+// kernel's `BotIsolateContributionHost` as a loaded Dynamic Worker with
+// `globalOutbound` disabled.
+import {
+  createFoundationRuntime,
+  type FoundationAgentPackage,
+  type FoundationRuntime,
+  type RuntimeModelSelection,
+} from "@frockbot/agent-runtime/runtime";
+import { createFoundationRuntimeApplication } from "@frockbot/application-foundation/runtime";
+import type { AgentEffectAdmission } from "@frockbot/kernel-agent-loop/agent";
+import {
+  CompositionMountFailureError,
+  type CompositionFailurePhaseV1,
+} from "@frockbot/kernel-composition/activation";
+import type { ApplicationPlan } from "@frockbot/kernel-composition/compiler";
+import {
+  bootstrapGeneration,
+  type CompositionGenerationV1,
+  type CompositionHost,
+  type CompositionMemberV1,
+  type MountedComposition,
+} from "@frockbot/kernel-composition/generation";
+import {
+  BotIsolateContributionHost,
+  botIsolatePackageDescriptorV1,
+  type BotIsolateArtifactStore,
+  type BotIsolateLimits,
+  type BotIsolateLoader,
+} from "@frockbot/kernel-composition/isolate";
+import type { ActiveContribution } from "@frockbot/kernel-composition";
+import {
+  type BotCapabilitiesStub,
+  type PersistSessionEvents,
+  type SessionEvent,
+  type TurnTypeV1,
+} from "@frockbot/kernel-contracts";
+
+/** The bootstrap generation for a compiled first-party application. */
+export function bootstrapCompositionGeneration(
+  plan: ApplicationPlan,
+  createdAt: string,
+): Promise<CompositionGenerationV1> {
+  return bootstrapGeneration(
+    plan.packages.map((pkg) => ({
+      packageId: pkg.id,
+      specifier: pkg.specifier,
+      version: pkg.version,
+      manifest: pkg.manifest,
+    })),
+    { createdAt },
+  );
+}
+
+export interface ShellMountedComposition extends MountedComposition {
+  readonly runtime: FoundationRuntime;
+}
+
+/** Everything the Bot Durable Object supplies for isolate members. */
+export interface ShellIsolateMountOptions {
+  userId: string;
+  runId: string;
+  turnId: string;
+  loader: BotIsolateLoader;
+  artifacts: BotIsolateArtifactStore;
+  /**
+   * Mints the loopback `CAPABILITIES` service binding for one Package —
+   * `ctx.exports.BotCapabilities({ props })` in the Durable Object.
+   */
+  capabilitiesFor(member: CompositionMemberV1): BotCapabilitiesStub;
+  /**
+   * Content address of the Assignment-derived bindings this isolate is granted
+   * — the Assignments *and* the Composition generation whose `CAPABILITIES`
+   * stub is baked into its `env`. Required: it is what keeps a cached isolate
+   * from answering under a stale authority.
+   */
+  bindingDigest: string;
+  compatibilityDate: string;
+  limits?: BotIsolateLimits;
+  deadlineMs?: number;
+}
+
+export interface ShellCompositionMountOptions {
+  botId: string;
+  sessionId: string;
+  sessionEvents: readonly SessionEvent[];
+  persistSessionEvents?: PersistSessionEvents;
+  agentPackages?: readonly FoundationAgentPackage[];
+  modelSelection?: RuntimeModelSelection;
+  systemPromptSection?: string;
+  /**
+   * Durably linearizes each provider or tool effect against Stop immediately
+   * before it is used. The Bot Durable Object owns the transaction; the mounted
+   * runtime only presents the exact effect identity.
+   */
+  admitEffect(effect: AgentEffectAdmission): Promise<boolean>;
+  /**
+   * The turn type the admitted Turn runs on; the mounted Agent trims its tool
+   * catalog to it. Absent ⇒ `chat`.
+   */
+  turnType?: TurnTypeV1;
+  /**
+   * The subagent role the admitted Turn runs under; the mounted Agent trims
+   * its catalog to it as well. Absent ⇒ no role narrowing.
+   */
+  subagentRole?: string;
+  /** Absent when the host cannot load isolates; isolate members then fail verify. */
+  isolate?: ShellIsolateMountOptions;
+}
+
+export interface ShellCompositionHost extends CompositionHost {
+  mount(
+    generation: CompositionGenerationV1,
+    signal: AbortSignal,
+  ): Promise<ShellMountedComposition>;
+}
+
+interface MemberVerificationFailure {
+  phase: CompositionFailurePhaseV1;
+  message: string;
+}
+
+function memberFailure(error: unknown): MemberVerificationFailure {
+  if (error instanceof CompositionMountFailureError) {
+    return { phase: error.phase, message: error.message };
+  }
+  return {
+    phase: "mount",
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+/** Mounts one pinned generation as the Cordis root a single Turn runs on. */
+export function createShellCompositionHost(
+  options: ShellCompositionMountOptions,
+): ShellCompositionHost {
+  return {
+    async mount(generation, signal) {
+      signal.throwIfAborted();
+      const runtime = await createFoundationRuntime(undefined, {
+        agentId: options.botId,
+        sessionId: options.sessionId,
+        sessionEvents: options.sessionEvents,
+        application: await createFoundationRuntimeApplication(),
+        composition: {
+          generationId: generation.generationId,
+          artifactSetHash: generation.artifactSetHash,
+        },
+        persistSessionEvents: options.persistSessionEvents,
+        admitEffect: options.admitEffect,
+        agentPackages: options.agentPackages,
+        modelSelection: options.modelSelection,
+        systemPromptSection: options.systemPromptSection,
+        ...(options.turnType ? { turnType: options.turnType } : {}),
+        ...(options.subagentRole ? { subagentRole: options.subagentRole } : {}),
+      });
+
+      const isolateMembers = generation.members.filter(
+        (member) => member.artifact !== undefined,
+      );
+      const active: ActiveContribution[] = [];
+      const failures: MemberVerificationFailure[] = [];
+      for (const member of isolateMembers) {
+        if (!options.isolate) {
+          failures.push({
+            phase: "mount",
+            message: `package "${member.packageId}" needs a Bot isolate and this host has no loader`,
+          });
+          continue;
+        }
+        const isolate = options.isolate;
+        try {
+          signal.throwIfAborted();
+          const host = new BotIsolateContributionHost({
+            loader: isolate.loader,
+            artifacts: isolate.artifacts,
+            tools: runtime.root.tools,
+            userId: isolate.userId,
+            botId: options.botId,
+            sessionId: options.sessionId,
+            runId: isolate.runId,
+            turnId: isolate.turnId,
+            generationId: generation.generationId,
+            capabilities: isolate.capabilitiesFor(member),
+            compatibilityDate: isolate.compatibilityDate,
+            bindingDigest: isolate.bindingDigest,
+            ...(isolate.limits ? { limits: isolate.limits } : {}),
+            ...(isolate.deadlineMs === undefined
+              ? {}
+              : { deadlineMs: isolate.deadlineMs }),
+          });
+          // Mount and health-check are one guarded phase (Worker Loader spike).
+          const prepared = await host.prepare(
+            botIsolatePackageDescriptorV1(member),
+          );
+          if (!prepared) {
+            failures.push({
+              phase: "resolve",
+              message: `package "${member.packageId}" declared no Bot isolate contribution`,
+            });
+            continue;
+          }
+          active.push(await prepared.commit());
+        } catch (error) {
+          failures.push(memberFailure(error));
+        }
+      }
+
+      const dispose = async () => {
+        for (const contribution of active.toReversed()) {
+          await contribution.dispose();
+        }
+        await runtime.dispose();
+      };
+
+      return {
+        generation,
+        root: runtime.root,
+        runtime,
+        // First-party members run in the kernel isolate and have nothing to
+        // health-check; an isolate member that failed to resolve, mount, or
+        // answer `health()` surfaces here, carrying the load site it failed at
+        // so `activateCompositionV1` records the phase rather than guessing it.
+        verify: () => {
+          if (failures.length === 0) return Promise.resolve();
+          return Promise.reject(
+            new CompositionMountFailureError(
+              failures[0]!.phase,
+              `Composition generation "${generation.generationId}" failed verification: ${failures
+                .map((failure) => failure.message)
+                .join("; ")}`,
+              failures.map((failure) => `${failure.phase}: ${failure.message}`),
+            ),
+          );
+        },
+        dispose,
+      };
+    },
+  };
+}

package/src/backend-computer.ts

@@ -0,0 +1,76 @@
+// The Bot Durable Object's half of the Computer sync seam (ADR 0013).
+//
+// The durable-root sync reconciles two halves: the Workspace on the Computer,
+// which the Computer provider Package owns, and object storage, whose
+// authority is this Durable Object. This module supplies the second half for
+// one admitted Turn — the store surface, the effect records a push writes
+// before it runs, and the generation ledger a removal's writer is recovered
+// from. It runs no sync and implements no interface; the provider Package does
+// both.
+//
+// ATTRIBUTION. Nothing here names a writer for what the sync finds. "A file
+// that reaches a durable root without passing through the Workspace file
+// surface (a shell write on the Computer) is mirrored to object storage by the
+// sync with an unattributed writer": one Computer serves all of a User's Bots,
+// so this object cannot know which Bot's process wrote a file, and the Turn
+// that happens to be running is not evidence. A Bot that means to author a
+// Skill writes it through the Workspace file surface, which records real
+// provenance.
+//
+// HIBERNATION. Nothing here reaches a Computer. It is a description of what a
+// sync may use if one happens, handed to the provider Package; whether a
+// Computer is awake is decided by the Bot using it and by nothing on this
+// path. "The Computer wakes only when a Bot uses it."
+//
+// SEAM. `WORKSPACE_SYNC_FILES` and `WORKSPACE_SYNC_EFFECTS` are constructed
+// onto the Durable Object environment by `apps/cloudflare/src/bot-state.ts`,
+// the same way `WORKSPACE_FILES` is: neither is a Worker binding, and a host
+// that binds neither simply has no sync — the durable roots then live on the
+// Computer alone, visibly, rather than syncing to a store this module invented.
+import type {
+  WorkspaceFilesV1,
+  WorkspaceGenerationsV1,
+  WorkspaceSyncEffectsV1,
+} from "@frockbot/kernel-contracts";
+import type { ComputerSyncHostV1 } from "@frockbot/computer-core";
+
+/**
+ * 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 BotComputerSyncEnv {
+  /** The durable roots in object storage, built with the `sync` surface. */
+  WORKSPACE_SYNC_FILES?: WorkspaceFilesV1;
+  /** Where a push records its intent, in this Bot's Durable Object. */
+  WORKSPACE_SYNC_EFFECTS?: WorkspaceSyncEffectsV1;
+  /** This object's generation ledger, read to recover a removal's writer. */
+  WORKSPACE_SYNC_GENERATIONS?: WorkspaceGenerationsV1;
+}
+
+/**
+ * The Computer sync seam one admitted Turn runs under, or `undefined` when the
+ * object-storage side is unavailable.
+ *
+ * It takes no identity and no Turn, and that is the point: see ATTRIBUTION
+ * above. What a sync finds on the Computer is attributed to nobody, so knowing
+ * which Bot, Session, and Turn asked for the sync would only be an invitation
+ * to record a writer this seam cannot support.
+ */
+export function createBotComputerSyncHost(
+  env: object,
+): ComputerSyncHostV1 | undefined {
+  // SAFETY: these surfaces are constructed onto the Durable Object environment
+  // rather than declared in the generated `Env`; they are not Worker bindings.
+  const bound = env as BotComputerSyncEnv;
+  const store = bound.WORKSPACE_SYNC_FILES;
+  if (!store) return undefined;
+  return {
+    store,
+    ...(bound.WORKSPACE_SYNC_EFFECTS
+      ? { effects: bound.WORKSPACE_SYNC_EFFECTS }
+      : {}),
+    ...(bound.WORKSPACE_SYNC_GENERATIONS
+      ? { generations: bound.WORKSPACE_SYNC_GENERATIONS }
+      : {}),
+  };
+}