A local-first multi-agent app development platform, built on PenguinHarness
/**
* The sandbox vocabulary a plugin compiles against — types only.
*
* It lives in core, alongside the rest of the plugin contract, because a backend is
* written against these names and nothing else: a package implementing {@link
* SandboxProvider} needs the policy it is handed and the argv it must return, not the
* harness that routes them. The routing itself (which policy goes to which backend, and
* the settings behind it) is the embedder's, and stays there.
*
* Confinement is argv rewriting and nothing else: a provider returns the argv the caller
* should spawn instead of its own, and never executes anything itself.
*
* Nothing here emits runtime code. The helpers that read these shapes
* (`SANDBOX_DIMENSIONS`, `providerDimensions`, `requestedDimensions`) are the embedder's
* and live in the server package, so a plugin carries no runtime dependency on core.
* A backend reaches the harness by contributing to the `sandbox.providers` slot (see
* the sandbox module's iface.ts in the server package).
*/
/**
* File-effect mode. `read-only` permits only required sinks (e.g. /dev/null);
* `workspace-write` also permits the workspace and a backend-defined temp area;
* `danger-full-access` means confinement is off and no provider is consulted.
*/
export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
/** A mode that actually confines — the modes a {@link SandboxPolicy} can carry. */
export type ConfinedSandboxMode = Exclude<SandboxMode, "danger-full-access">;
/**
* The isolation dimensions of this interface. A provider declares the subset it
* implements; `fs-write` is the floor every confining backend covers, while `network`
* and `mask-paths` are optional implementations (see {@link SandboxProvider.dimensions}).
* `network-local` is the local network level: only the host's localhost is reachable. It is
* its own dimension because a backend that can cut the network cannot necessarily keep the
* host's loopback while cutting the rest. `closed-temp` is withholding the temporary directory
* when a policy does not grant it ({@link SandboxPolicy.writableTemp}): a backend whose temp
* area is always writable (the DSH adaptor, which grants the host's /tmp under
* `workspace-write`) does not declare it, and a policy closing temp is never routed to it.
*/
export type SandboxDimension =
"fs-write" | "network" | "network-local" | "mask-paths" | "closed-temp";
/**
* The network levels, narrowest first: `none` = no network at all, `local` = only the host's
* localhost, absent = unrestricted.
*/
export type SandboxNetwork = "none" | "local";
/**
* What one confined execution is allowed to touch — carried PER CALL, not fixed on the
* provider. The optional members are the optional dimensions: present means the policy
* REQUIRES that dimension, and the service only routes such a policy to a provider that
* implements it (never silently dropped).
*/
export interface SandboxPolicy {
/**
* The file-effect mode this execution runs under (`fs-write`). A provider is normally
* consulted only for a confining mode; it is handed `danger-full-access` ONLY when the
* policy still requires another dimension (a network cut, a masked path). Then it must
* leave the filesystem unrestricted while enforcing that other dimension — "everything
* writable, but no network" is a real, expressible policy.
*/
mode: SandboxMode;
/** Absolute root directory `workspace-write` may write under. */
workspaceRoot: string;
/**
* Further absolute directories `workspace-write` may write under, beside the workspace:
* the Session's scratchpad, where the plan file, a goal's state file and the
* attachments live. The service sets it only under `workspace-write`. A backend that
* does not implement the field confines more narrowly than asked, never more widely, so
* no dimension guards it.
*
* Each root EXISTS on the host by the time a backend is handed the policy: the service
* creates it first (the scratchpad is made lazily, and can be removed mid-Session), and
* refuses the spawn when it cannot. A backend neither creates a root nor skips a missing
* one. `workspaceRoot` is not covered: a missing Workspace is a different error, and
* surfaces as such.
*/
writableRoots?: readonly string[];
/**
* `network`: "none" = the confined process gets no network at all (dimension `network`);
* "local" = it reaches the host's localhost and nothing else (dimension `network-local`).
*/
network?: SandboxNetwork;
/** `mask-paths`: absolute paths hidden from the confined process, reads included. */
maskPaths?: readonly string[];
/**
* The system temporary directory is writable, in either confining mode: shells and most
* tools need somewhere to write before they run anything. Absent = not granted — which the
* service hands only to a backend declaring `closed-temp`.
*/
writableTemp?: boolean;
}
/**
* Enforcement completeness for this host. `partial` means the backend or an older
* kernel ABI cannot govern every promised effect; a caller requiring an absolute
* boundary must not treat it as `full`. Reported as fact, never requested.
*/
export type SandboxEnforcement = "full" | "partial";
/**
* Evidence identifying a runner that failed BEFORE executing the wrapped command.
* A consumer applies `allowedExitCodes` when present, drops `informationalLines` by
* exact line equality, then matches `fatalSignatures` case-insensitively per remaining
* stderr line. Exit status alone never proves runner failure.
*/
export interface RunnerFailureRule {
allowedExitCodes?: readonly number[];
fatalSignatures: readonly string[];
informationalLines?: readonly string[];
}
/** The result of confining one argv. */
export interface ConfinedArgv {
/** The wrapped argv (runner, profile, separator, then the caller's argv). */
argv: string[];
/** How completely the backend enforces this policy here. */
enforcement: SandboxEnforcement;
/**
* The backend's denial DIALECT: the case-insensitive stderr substrings a denied
* effect produces under THIS backend. A consumer inferring denials matches these
* rather than a cross-backend union, which would claim denials a backend never emits.
*/
denialSignatures: readonly string[];
/** Structured runner-failure evidence (see {@link RunnerFailureRule}). */
runnerFailureRules: readonly RunnerFailureRule[];
/**
* Environment entries the RUNNER needs, laid over the command's own environment at
* spawn. A runner that is a script has to tell its interpreter how to behave — the
* desktop app's own binary runs a script only under `ELECTRON_RUN_AS_NODE`, and
* nothing in an argv can say so. These describe the runner, not the command: a runner
* that hands the environment on keeps them from the command it confines.
*/
env?: Readonly<Record<string, string>>;
}
/**
* A sandbox backend. `confine` must return enforcing argv or THROW — returning the
* original argv unconfined is forbidden, which is what makes the whole capability
* fail-closed.
*/
export interface SandboxProvider {
/**
* The dimensions this backend implements. Absent = `["fs-write"]`: a backend that
* says nothing governs file writes only, which is the honest default and exactly
* what a stock DSH backend is. The service routes by this declaration, so an
* unimplemented dimension can never be silently ignored.
*/
readonly dimensions?: readonly SandboxDimension[];
/**
* What enforces the confinement on this host, as an administrator would name it
* ("bubblewrap", "Landlock"). The settings card says what this machine enforces and by
* what; absent, it names the backend instead.
*/
readonly mechanism?: string;
/**
* What this backend leaves open on this host beyond the dimensions it does not declare —
* a policy field it cannot honour in full, a kernel that enforces only part of it — in an
* administrator's words. The settings card discloses them under what this machine enforces.
*/
readonly limits?: readonly SandboxLimit[];
confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv;
}
/** One limit of a backend on this host (see {@link SandboxProvider.limits}). */
export interface SandboxLimit {
text: string;
textZh?: string;
}
/** A provider, or a promise of one: backends load asynchronously (dynamic imports, probes). */
export type SandboxProviderLoad = SandboxProvider | PromiseLike<SandboxProvider | null> | null;
/**
* What a backend binds: a load, or a loader that produces one. A loader is called at boot and
* again after its failure whenever the sandbox's settings are saved — so a backend whose check
* failed on a setting (a wrong program path) recovers once that setting is fixed, no restart.
*/
export type SandboxProviderSource = SandboxProviderLoad | (() => SandboxProviderLoad);
/**
* The active confinement settings, resolved per spawn. A type literal with plain
* arrays because it parks as Json in the platform context (see PlatformCtx.sandbox).
*/
export type SandboxSettings = {
/** `danger-full-access` = confinement off; commands spawn exactly as before. */
mode: SandboxMode;
network?: SandboxNetwork;
maskPaths?: string[];
/** Grant the system temp directory writable (SandboxPolicy.writableTemp). Absent = granted. */
writableTemp?: boolean;
};