Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

16.9 KB
Raw Blame
/**
 * The sandbox service: owns the registered backends, routes each spawn's policy to a
 * backend that implements the dimensions it requires, and produces the SpawnConfiner
 * closure the runtime transports into core's command-session seam.
 *
 * Routing is by CAPABILITY, not by registration order: of the mounted backends covering
 * every dimension a policy requires, the one implementing the most dimensions wins, so a
 * native backend (penguin-bwrap) serves every policy it covers even when the portable DSH
 * adaptor is mounted beside it, and the adaptor serves only where it is the one left — a
 * Linux host refusing bubblewrap's user namespaces, where it confines files through
 * Landlock. Registration order only breaks ties. A request nothing covers fails closed —
 * never a silent unconfined run, and never a silently dropped dimension.
 */
import fs from "node:fs";
import type { SpawnConfiner } from "@adelie/core";
import type {
  SandboxDimension,
  SandboxLimit,
  SandboxPolicy,
  SandboxProvider,
  SandboxProviderSource,
  SandboxSettings,
} from "@adelie/core/plugin";
import { providerDimensions, requestedDimensions } from "./dimensions.js";
import { Interface, Module, Provide } from "@adelie/core/kernel";
import type { Slot, ClassCtx, Json } from "@adelie/core/kernel";

interface MountedProvider {
  name: string;
  provider: SandboxProvider;
}

/** How one registration's latest load settled. */
type LoadOutcome = { provider: SandboxProvider } | { declined: true } | { error: string };

interface Registration {
  name: string;
  source: SandboxProviderSource;
  outcome?: LoadOutcome;
  /** Counts the loads started; only the latest one's outcome is recorded. */
  attempts: number;
}

/** Settles one load: a provider, a decline (null), or the failure's message. */
function settle(source: SandboxProviderSource): Promise<LoadOutcome> {
  return Promise.resolve()
    .then(() => (typeof source === "function" ? source() : source))
    .then(
      (provider): LoadOutcome =>
        provider === null || provider === undefined ? { declined: true } : { provider },
      (err: unknown): LoadOutcome => ({ error: err instanceof Error ? err.message : String(err) }),
    );
}

export class SandboxService {
  private mounted: MountedProvider[] = [];
  /**
   * name → why it FAILED: it could not load, or failed its check on a host it is meant for —
   * never silently absent. Surfaced in the fail-closed message and on the settings card.
   */
  private loadErrors = new Map<string, string>();
  /**
   * The backends that declined: this host is not theirs (a Linux backend on Windows). Nothing
   * is wrong with a deployment that installs one backend per platform, so a decline is not a
   * failure — it is listed only when NO backend serves, where it is the explanation.
   */
  private declinedNames: string[] = [];
  /** Every registration in routing order, with how its latest load settled. */
  private readonly registrations: Registration[];
  /**
   * Ships with confinement OFF (`danger-full-access`): the default flips to
   * workspace-write together with the deployment-facing config surface, so a
   * deployment gains the switch before the enforcement — otherwise every host without
   * a usable backend would fail every command the moment this code arrives.
   */
  private settings: SandboxSettings = { mode: "danger-full-access" };
  private readonly ready: Promise<void>;

  /**
   * @param registrations - the backends plugins registered (see the sandbox registry on
   *   PenguinInterface). Loading is async, but create() and the confiner are sync: a
   *   confining policy resolved before loading settles fails closed rather than
   *   waiting. The default settings never consult a backend, so that window only
   *   exists for deployments flipping the mode in the first milliseconds after boot.
   */
  constructor(registrations: Iterable<[string, SandboxProviderSource]> = []) {
    const loads: Registration[] = [...registrations].map(([name, source]) => ({
      name,
      source,
      attempts: 1,
    }));
    this.registrations = loads;
    // Every source is settled at once (a backend's check runs while the others load, and a
    // rejection is handled the moment it happens); the results are recorded in registration
    // order, which is routing order.
    const settled = loads.map((r) => settle(r.source));
    this.ready = (async () => {
      for (const [i, result] of settled.entries()) {
        loads[i]!.outcome = await result;
        this.record();
      }
    })();
  }

  /** Rebuilds the mounted / failed / declined views from the registrations, in routing order. */
  private record(): void {
    const mounted: MountedProvider[] = [];
    const errors = new Map<string, string>();
    const declined: string[] = [];
    for (const { name, outcome } of this.registrations) {
      if (outcome === undefined) continue;
      if ("provider" in outcome) mounted.push({ name, provider: outcome.provider });
      else if ("error" in outcome) errors.set(name, outcome.error);
      else declined.push(name);
    }
    this.mounted = mounted;
    this.loadErrors = errors;
    this.declinedNames = declined;
  }

  /**
   * Loads again every backend whose load failed and that registered a loader (a bare promise
   * cannot be re-run). Called after the sandbox's settings are saved: a backend whose check
   * failed on its own setting mounts once that setting is fixed. Resolves when those settle.
   */
  retryFailed(): Promise<void> {
    return this.ready.then(async () => {
      await Promise.all(
        this.registrations
          .filter((r) => r.outcome !== undefined && "error" in r.outcome)
          .filter((r) => typeof r.source === "function")
          .map(async (r) => {
            // Saves in quick succession each probe their own setting; an older probe that
            // settles last must not overwrite the newer outcome.
            const attempt = ++r.attempts;
            const outcome = await settle(r.source);
            if (r.attempts !== attempt) return;
            r.outcome = outcome;
            this.record();
          }),
      );
    });
  }

  /** Resolves when every registered backend has loaded (or failed to). */
  whenReady(): Promise<void> {
    return this.ready;
  }

  /** Replaces the active settings (the config surface's write path). */
  configure(settings: SandboxSettings): void {
    this.settings = settings;
  }

  /** The active settings as a plain copy (the config surface's read side). */
  currentSettings(): SandboxSettings {
    return copySettings(this.settings);
  }

  /**
   * The active settings as parked state, or undefined for the pristine default. The
   * omission is load-bearing compatibility: a default deployment keeps parking
   * `{ motd }`, which any platform bundle's context schema accepts. Once confinement
   * is configured the field enters the document, and from then on pushing a
   * sandbox-ignorant bundle is BLOCKED by schema validation — the right failure:
   * refusing the swap beats a swap that silently un-confines the deployment.
   */
  parkedSettings(): SandboxSettings | undefined {
    const s = this.settings;
    if (
      s.mode === "danger-full-access" &&
      s.network === undefined &&
      s.maskPaths === undefined &&
      s.writableTemp === undefined
    ) {
      return undefined;
    }
    return copySettings(s);
  }

  /** The backends that failed to load, each with why (diagnostics / the config surface). */
  failures(): Array<{ name: string; reason: string }> {
    return [...this.loadErrors].map(([name, reason]) => ({ name, reason }));
  }

  /** The backends that declined because this host is not theirs (the config surface). */
  declined(): string[] {
    return [...this.declinedNames];
  }

  /**
   * The mounted backends and what each implements, in routing preference: the one a policy
   * goes to first (diagnostics / the config surface).
   */
  backends(): Array<{
    name: string;
    dimensions: readonly SandboxDimension[];
    mechanism?: string;
    limits?: readonly SandboxLimit[];
  }> {
    return byPreference(this.mounted).map(({ name, provider }) => ({
      name,
      dimensions: providerDimensions(provider),
      ...(provider.mechanism !== undefined ? { mechanism: provider.mechanism } : {}),
      ...(provider.limits !== undefined && provider.limits.length > 0
        ? { limits: provider.limits }
        : {}),
    }));
  }

  /**
   * The closure handed to the runtime: rewrites each spawn's argv under the active
   * settings. Pure and self-contained, so the previous platform's confiner keeps
   * serving during a hot-swap freeze window.
   */
  confiner(): SpawnConfiner {
    return this.confinerFor(() => this.settings);
  }

  /**
   * The same closure under a policy the caller keeps — a Session's own snapshot. The
   * backends are still this service's, so a backend change reaches every Session.
   */
  confinerFor(policyOf: () => SandboxSettings): SpawnConfiner {
    return (argv, opts) => {
      const settings = policyOf();
      const required = requestedDimensions(settings);
      // Full access with nothing else asked (no network cut, no masked paths) is genuinely
      // unconfined — spawn as-is. But full access that STILL cuts the network or masks a path
      // needs a backend: returning here would silently drop that half of the policy. So the
      // short-circuit is "no confinement dimension beyond fs-write", not "mode is full".
      if (settings.mode === "danger-full-access" && required.length === 1) return { argv };
      const provider = this.pick(required, settings.mode);
      // Only workspace-write binds further writable roots; under read-only (or full access
      // with a network cut) every backend ignores them, so neither the field nor the
      // directory is made there.
      const scratchpadDir = settings.mode === "workspace-write" ? opts.scratchpadDir : undefined;
      // The Session's scratchpad is created lazily (on the first thing written into it), and a
      // command, an agent or the user can remove it mid-Session, but a backend binding it needs
      // it on disk: bubblewrap refuses to start on a missing bind source. Ensured on every
      // spawn, here, where every confined spawn meets — see SandboxPolicy.writableRoots.
      if (scratchpadDir !== undefined) ensureScratchpad(scratchpadDir);
      // workspaceRoot is the Session's Workspace, never the per-command cwd: a command
      // running in a workdir outside the Workspace must not widen the writable roots.
      const policy: SandboxPolicy = {
        mode: settings.mode,
        workspaceRoot: opts.workspaceDir,
        // The Session's scratchpad is writable beside the Workspace: the plan file, a goal's
        // state file and the attachments live there, and hooks and commands both write it.
        ...(scratchpadDir !== undefined ? { writableRoots: [scratchpadDir] } : {}),
        ...(settings.network !== undefined ? { network: settings.network } : {}),
        ...(settings.maskPaths !== undefined && settings.maskPaths.length > 0
          ? { maskPaths: settings.maskPaths }
          : {}),
        // On unless turned off: without a writable temp directory a shell cannot start.
        ...(settings.writableTemp !== false ? { writableTemp: true } : {}),
      };
      // ConfinedArgv also carries enforcement / denialSignatures / runnerFailureRules;
      // the classification consumer (denial vs runner failure) lands with escalation. The
      // rules' informational lines are what the runner reports on every run (the Landlock
      // launcher on an older kernel): the spawn drops them from the command's stderr.
      const confined = provider.confine(argv, policy);
      const runnerLines = confined.runnerFailureRules.flatMap((r) => r.informationalLines ?? []);
      return {
        argv: confined.argv,
        ...(confined.env !== undefined ? { env: confined.env } : {}),
        ...(runnerLines.length > 0 ? { runnerLines } : {}),
      };
    };
  }

  /**
   * The preferred mounted backend implementing every required dimension (byPreference), or a
   * fail-closed throw.
   */
  private pick(required: readonly SandboxDimension[], mode: string): SandboxProvider {
    const match = byPreference(this.mounted).find(({ provider }) => {
      const implemented = providerDimensions(provider);
      return required.every((dimension) => implemented.includes(dimension));
    });
    if (match !== undefined) return match.provider;
    throw new Error(
      this.mounted.length === 0
        ? `sandbox mode "${mode}" is configured but no sandbox backend is mounted${this.failedSuffix()}; ` +
            "refusing to run the command unconfined."
        : `sandbox policy requires ${required.join(" + ")}, but no mounted sandbox backend ` +
            `implements all of it (${this.mounted
              .map(({ name, provider }) => `${name}: ${providerDimensions(provider).join(", ")}`)
              .join("; ")})${this.failedSuffix()}; refusing to run the command unconfined.`,
    );
  }

  private failedSuffix(): string {
    const parts = [...this.loadErrors].map(([name, message]) => `${name} (${message})`);
    if (this.declinedNames.length > 0) {
      parts.push(`${this.declinedNames.join(", ")} (not for this host)`);
    }
    return parts.length === 0 ? "" : `; backends not in use: ${parts.join("; ")}`;
  }
}

/**
 * Backends in routing preference: more implemented dimensions first, registration order among
 * equals (the sort is stable). Bubblewrap and the DSH adaptor both cover a files-only policy;
 * the one that could also have cut the network or masked a path is the one that serves it, on
 * whatever order the Projects' plugin lists name them in.
 */
function byPreference(mounted: readonly MountedProvider[]): MountedProvider[] {
  const size = (m: MountedProvider) => providerDimensions(m.provider).length;
  return [...mounted].sort((a, b) => size(b) - size(a));
}

/**
 * Creates the Session's scratchpad if it is missing (a no-op when it exists). A failure
 * throws, fail-closed: dropping the root and confining without it would start the command
 * but leave it unable to write the directory it was told it may write.
 *
 * Known race, left as is: deleting a Session removes its scratchpad, and a run that outlives
 * the delete (a command still being spawned for it) recreates the directory here. The cost is
 * an empty, orphaned directory under the Agent's scratchpad that nothing cleans up; it holds
 * only what that last run writes, and no access outlives the Session.
 */
function ensureScratchpad(dir: string): void {
  try {
    fs.mkdirSync(dir, { recursive: true });
  } catch (err) {
    // A filesystem error's message leads with its errno (`EACCES: permission denied, …`).
    throw new Error(
      `cannot prepare the Session scratchpad ${dir} for the sandbox ` +
        `(${err instanceof Error ? err.message : String(err)}); refusing to run the command without it.`,
      { cause: err },
    );
  }
}

function copySettings(settings: SandboxSettings): SandboxSettings {
  return {
    mode: settings.mode,
    ...(settings.network !== undefined ? { network: settings.network } : {}),
    ...(settings.maskPaths !== undefined ? { maskPaths: [...settings.maskPaths] } : {}),
    ...(settings.writableTemp !== undefined ? { writableTemp: settings.writableTemp } : {}),
  };
}

/** Confinement: settings, the active confiner, and which backends are mounted. */
export abstract class Sandbox extends Interface<
  Pick<
    SandboxService,
    | "configure"
    | "currentSettings"
    | "parkedSettings"
    | "backends"
    | "failures"
    | "declined"
    | "retryFailed"
    | "confiner"
    | "confinerFor"
    | "whenReady"
  >
>() {}

export interface SandboxSlots {
  /**
   * A backend: its static half here (name, the dimensions it implements), its code half
   * bound by the contributor — a provider, or a promise of one for backends that probe.
   */
  providers: Slot<{ name: string; dimensions: SandboxDimension[] }, SandboxProviderSource>;
}

@Module({
  context: {
    version: 1,
    schema: {
      "settings?": {
        mode: "'read-only'|'workspace-write'|'danger-full-access'",
        "network?": "'none'|'local'",
        "maskPaths?": "string[]",
        "writableTemp?": "boolean",
      },
    },
  },
})
export class SandboxModule {
  @Provide() sandbox!: Sandbox;
  setup({ contributions }: ClassCtx, context: Json) {
    const providers = (contributions.providers ?? []).map(
      (c) =>
        [c.data.name as string, c.code as SandboxProviderSource] as [string, SandboxProviderSource],
    );
    const sandbox = new SandboxService(providers);
    // Parked settings ride the swap: without this every push would construct a fresh
    // service on defaults and silently un-confine a confining deployment.
    const parked = (context as { settings?: SandboxSettings } | null)?.settings;
    if (parked !== undefined) sandbox.configure(parked);
    this.sandbox = sandbox;
  }

  park(): Json {
    const settings = this.sandbox.parkedSettings();
    return settings === undefined ? null : { settings };
  }
}