@alvin0/ai-agent-sdk-sandbox 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,731 @@
+//#region src/entries.d.ts
+/**
+ * Nested filesystem carve-outs.
+ *
+ * A single writable root is not enough: an agent that may write in a repository
+ * must still be kept out of `.git`, and an operator must be able to reopen one
+ * directory beneath a denied parent. Entries express that as an overlapping
+ * list resolved by path specificity — the deepest matching entry wins, so
+ * `/repo = write`, `/repo/a = deny`, `/repo/a/b = write` behaves as written.
+ */
+/** What one entry grants for the subtree it names. */
+type FileSystemAccess = 'write' | 'read' | 'deny';
+/** One carve-out in a filesystem policy. */
+interface FileSystemEntry {
+  /** Absolute path whose subtree this entry governs. */
+  readonly path: string;
+  /** Access granted for that subtree, overriding any broader entry. */
+  readonly access: FileSystemAccess;
+}
+/**
+ * Order entries from broadest to narrowest so a consumer can apply them in
+ * sequence and let the most specific one win. Equal-depth entries keep a stable
+ * lexical order so a policy always produces the same backend profile.
+ */
+declare function orderEntries(entries: readonly FileSystemEntry[]): readonly FileSystemEntry[];
+/**
+ * Resolve the effective access for one target against an ordered entry list.
+ * @param target - absolute path being evaluated.
+ * @param entries - carve-outs, in any order.
+ * @param fallback - access to use when no entry covers the target.
+ */
+declare function accessFor(target: string, entries: readonly FileSystemEntry[], fallback: FileSystemAccess): FileSystemAccess;
+/**
+ * Entries that carve a narrower rule *inside* `root`. A backend that grants
+ * `root` wholesale must re-apply these afterwards or the grant is too wide.
+ */
+declare function entriesWithin(root: string, entries: readonly FileSystemEntry[]): readonly FileSystemEntry[];
+//#endregion
+//#region src/mode.d.ts
+/** File-effect vocabulary shared by every sandbox backend and consumer. */
+/**
+ * File-effect policy for confined processes. `read-only` permits only the sinks
+ * a shell requires (`/dev/null` and its platform equivalent); `workspace-write`
+ * additionally permits the workspace root and a backend-defined temp area;
+ * `danger-full-access` bypasses confinement entirely.
+ *
+ * Network reachability and process visibility are deliberately outside this
+ * vocabulary — they are governed by their own seam, not by a file-effect mode.
+ */
+type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** A confining mode — the only modes a provider can be asked to enforce. */
+type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>;
+/**
+ * Enforcement completeness for this host, reported as a fact rather than
+ * promised. `partial` means the selected backend cannot govern every file
+ * effect the mode promises; `fence-only` means no process confinement exists on
+ * this platform and just the in-process path fence applies, so a consumer that
+ * needs a kernel boundary must reject it rather than treat it as enforcement.
+ */
+type SandboxEnforcement = 'full' | 'partial' | 'fence-only';
+/** Every mode, in widening order of authority. */
+declare const SANDBOX_MODES: readonly SandboxMode[];
+/** Whether an arbitrary value is one of the known modes. */
+declare function isSandboxMode(value: unknown): value is SandboxMode;
+/** Whether a mode still asks a provider to confine the execution. */
+declare function isConfinedMode(mode: SandboxMode): mode is ConfinedSandboxMode;
+/** Rank used when a narrower mode must not be widened by a weaker source. */
+declare function modeAuthority(mode: SandboxMode): number;
+//#endregion
+//#region src/network.d.ts
+/**
+ * Network reachability — a seam of its own, deliberately not a file-effect mode.
+ *
+ * `SandboxMode` governs file effects and says so. Folding network reachability
+ * into it would make the mode claim something it does not decide, and a mode
+ * that lies about its scope is worse than one with a narrow one. So network is
+ * a second, independent axis carried on the same policy: a call can be
+ * `read-only` on the filesystem and still reach the internet, or writable in
+ * its workspace and reach nothing.
+ *
+ * The distinction matters because the two are enforced by different mechanisms
+ * — mount bindings versus a network namespace — and a host can provide one
+ * without the other.
+ */
+/**
+ * What a confined execution may reach.
+ *
+ * `loopback` is not a weaker `deny`: it is what a command needs when the
+ * deployment runs a proxy or a language server it is meant to talk to, and
+ * nothing else. On a host whose only mechanism is a network namespace the two
+ * enforce identically, which the enforcement report says rather than hides.
+ */
+type NetworkMode = 'deny' | 'loopback' | 'allow-all';
+/** Every network mode, in widening order of reach. */
+declare const NETWORK_MODES: readonly NetworkMode[];
+/** How completely a backend enforces a network mode. */
+type NetworkEnforcement = 'full' | 'loopback-only' | 'none';
+/** Whether an arbitrary value is one of the known network modes. */
+declare function isNetworkMode(value: unknown): value is NetworkMode;
+/** Rank used so an untrusted request can narrow reach but never widen it. */
+declare function networkAuthority(mode: NetworkMode): number;
+/**
+ * Narrow a network mode toward a stricter one, refusing to widen.
+ * @param ceiling - the reach already permitted.
+ * @param requested - the reach being asked for.
+ * @returns the stricter of the two.
+ */
+declare function narrowNetwork(ceiling: NetworkMode, requested: NetworkMode | undefined): NetworkMode;
+//#endregion
+//#region src/approval.d.ts
+/** How long a minted approval remains usable. */
+type SandboxApprovalScope = 'single-call' | 'session';
+/** What an approval permits, beyond what the session already allows. */
+interface SandboxApprovalGrant {
+  /**
+   * Whether the approval survives the call it was minted for.
+   *
+   * `single-call` — the default — is consumed the first time a policy is
+   * resolved with it, so a grant given for one operation cannot be replayed
+   * for the next. A person approving "read this file" approved one read.
+   */
+  readonly scope?: SandboxApprovalScope;
+  /** Wall-clock deadline in epoch milliseconds, after which it is refused. */
+  readonly expiresAt?: number;
+  /** Mode the approval raises this call to. */
+  readonly mode?: SandboxMode;
+  /** Entries the approval may add, including widening ones. */
+  readonly entries?: readonly FileSystemEntry[];
+  /** Network reach the approval raises this call to. */
+  readonly network?: NetworkMode;
+  /** Free-text reason, carried for audit; never interpreted. */
+  readonly justification?: string;
+}
+/**
+ * An approval token. Structurally it is just its grant, but only a value minted
+ * by {@link approveSandboxEscalation} is accepted — a look-alike object, however
+ * carefully shaped, is refused.
+ */
+interface SandboxApproval extends SandboxApprovalGrant {
+  readonly approved: true;
+}
+/**
+ * Mint an approval. Call this only after the host has actually authorized the
+ * escalation; the SDK cannot tell an approved grant from a requested one, which
+ * is precisely why this call has to be the place the distinction is made.
+ */
+declare function approveSandboxEscalation(grant: SandboxApprovalGrant): SandboxApproval;
+/** Whether a value is an approval this module minted. */
+declare function isSandboxApproval(value: unknown): value is SandboxApproval;
+/** Whether a minted approval has already been used up. */
+declare function isSandboxApprovalSpent(approval: SandboxApproval): boolean;
+/**
+ * Accept an approval, or refuse it loudly.
+ * @throws SandboxPolicyError when the value was not minted here — which is what
+ *   a forged approval arriving through a tool payload looks like.
+ */
+declare function requireSandboxApproval(value: unknown, now?: number): SandboxApproval;
+//#endregion
+//#region src/exec.d.ts
+/**
+ * Reading a command for what it *does*, not just what it touches.
+ *
+ * The file seam cannot tell `systemctl status nginx` from `systemctl restart
+ * nginx`: both are argv, neither writes a file the policy cares about, and one
+ * observes while the other changes the machine. Deciding between them needs the
+ * command read semantically, before any of it runs.
+ *
+ * This is a classifier, and a classifier is a guess. Two rules keep the guess
+ * from becoming a hazard: a command it does not recognise is never allowed, and
+ * a command that hides other commands — a shell string, a pipeline, a chain —
+ * is classified by the riskiest thing inside it rather than by its wrapper.
+ */
+/** What a command does to the machine, in increasing order of consequence. */
+type ExecCapability = 'observe' | 'use' | 'modify' | 'service-control' | 'package-install' | 'privilege' | 'credential' | 'critical' | 'unknown';
+/** What a harness should do with a command carrying that capability. */
+type ExecOutcome = 'allow' | 'allow-scoped' | 'ask-approval' | 'deny';
+/** One classified command, and why it was classified that way. */
+interface ExecClassification {
+  readonly capability: ExecCapability;
+  readonly outcome: ExecOutcome;
+  /** The program the decision was made about, after unwrapping. */
+  readonly program: string;
+  /** Why, in terms a person approving it can check. */
+  readonly reason: string;
+  /** Every command found inside a shell string or chain, already classified. */
+  readonly parts: readonly ExecClassification[];
+}
+/** The outcome each capability maps to, before a deployment adjusts it. */
+declare const DEFAULT_EXEC_OUTCOMES: Readonly<Record<ExecCapability, ExecOutcome>>;
+/**
+ * Classify one command.
+ * @param argv - the exact argv, program first. A shell string is read through.
+ * @param outcomes - the capability-to-outcome mapping a deployment uses.
+ */
+declare function classifyExec(argv: readonly string[], outcomes?: Readonly<Record<ExecCapability, ExecOutcome>>): ExecClassification;
+/**
+ * Every command an argv actually runs.
+ *
+ * A shell invocation carries its real command in a string, and that string can
+ * hold several. Splitting it with a pattern cannot work: `grep -E 'a|b'` puts a
+ * separator inside a quoted word, and a pattern either splits there — inventing
+ * commands out of a regex — or refuses to split anywhere a quote appears. The
+ * script is therefore walked one character at a time, so a separator only
+ * separates when nothing is quoting it.
+ */
+declare function splitCommands(argv: readonly string[]): readonly (readonly string[])[];
+/**
+ * Split a shell script into commands, respecting quotes and escapes.
+ *
+ * Deliberately not a shell parser: it does not expand, substitute, or
+ * understand control flow. It answers one question — which words belong to
+ * which command — and leaves the rest to the classifier, which treats anything
+ * it cannot read as something to ask about.
+ */
+declare function tokenizeScript(script: string): readonly (readonly string[])[];
+//#endregion
+//#region src/errors.d.ts
+/** Fail-closed error surface. Silent unconfined passthrough is never legal. */
+/** Thrown when no backend on this host can enforce a confining policy. */
+declare class SandboxUnavailableError extends Error {
+  readonly platform: string;
+  readonly code: 'SANDBOX_UNAVAILABLE';
+  /** Runner ids that were considered for this platform, in chain order. */
+  readonly attempted: readonly string[];
+  constructor(platform: string, attempted?: readonly string[], detail?: string);
+}
+/** Thrown by the in-process fence when a mutation leaves the permitted roots. */
+declare class SandboxDeniedError extends Error {
+  readonly path: string;
+  readonly mode: string;
+  readonly writableRoots: readonly string[];
+  readonly code: 'SANDBOX_DENIED';
+  constructor(path: string, mode: string, writableRoots: readonly string[]);
+}
+/** Thrown when a policy is structurally unusable before any backend is asked. */
+declare class SandboxPolicyError extends Error {
+  readonly code: 'SANDBOX_POLICY_INVALID';
+  constructor(message: string);
+}
+//#endregion
+//#region src/policy.d.ts
+/** The complete file-effect policy resolved for one capability call. */
+interface SandboxExecutionPolicy {
+  /** The file-effect mode this execution runs under. */
+  readonly mode: SandboxMode;
+  /** Absolute root directory `workspace-write` may write under. */
+  readonly workspaceRoot: string;
+  /** Nested carve-outs layered over the mode's base grant. */
+  readonly entries?: readonly FileSystemEntry[];
+  /** Untrusted per-call carve-outs, kept separate so they can only intersect. */
+  readonly restrictions?: readonly FileSystemEntry[];
+  /** Carve-outs carried by a minted approval and therefore allowed to widen. */
+  readonly approvedEntries?: readonly FileSystemEntry[];
+  /**
+   * The access in force where no layer applies.
+   *
+   * `read` — the default — means the host is readable and a policy closes
+   * paths one at a time, which is a deny-list: it protects what someone
+   * remembered to name. `deny` inverts that into an allow-list, where nothing
+   * is readable until an entry says so, and a path nobody thought about is
+   * closed rather than open.
+   */
+  readonly baseline?: FileSystemAccess;
+  /**
+   * What this execution may reach over the network. Independent of
+   * {@link SandboxExecutionPolicy.mode}, which governs file effects only.
+   */
+  readonly network?: NetworkMode;
+  /** Opaque calling-session identity; backends key per-session state off it. */
+  readonly sessionId?: string;
+}
+/**
+ * A policy narrowed to a confining mode — the only shape a provider accepts.
+ * Resolution happens at the consumer boundary; the provider treats what it
+ * receives as fully specified and never re-defaults anything.
+ */
+interface SandboxPolicy extends SandboxExecutionPolicy {
+  readonly mode: ConfinedSandboxMode;
+}
+/**
+ * Inputs that select the policy for one capability call.
+ *
+ * `mode` and `entries` are the UNTRUSTED half: they arrive from whatever asked
+ * for the execution, which in an agent is a model-authored tool payload. They
+ * may only narrow. Widening lives behind {@link approval}, which a tool payload
+ * cannot contain because it is a capability rather than data.
+ */
+interface SandboxPolicyRequest {
+  /**
+   * The mode the caller asks for. Honoured only when it is at least as strict
+   * as the session's own mode — a request can tighten its own execution, never
+   * loosen it.
+   */
+  readonly mode?: SandboxMode;
+  /** The calling session's mode, as last logged for that session. */
+  readonly sessionMode?: SandboxMode;
+  /** The calling session's immutable cwd; becomes the workspace boundary. */
+  readonly cwd?: string;
+  /**
+   * Carve-outs the caller asks for. Restrictions only: a `write` entry here is
+   * an escalation attempt and is refused, because granting write to `.git` or
+   * `~/.ssh` defeats the boundary just as completely as raising the mode.
+   */
+  readonly entries?: readonly FileSystemEntry[];
+  /** The network reach the caller asks for; honoured only when it narrows. */
+  readonly network?: NetworkMode;
+  /** An approval minted by `approveSandboxEscalation`; the only way to widen. */
+  readonly approval?: SandboxApproval;
+  /** Opaque calling-session identity. */
+  readonly sessionId?: string;
+}
+/** Deployment-level fallbacks applied when a request omits them. */
+interface SandboxPolicyDefaults {
+  /** Mode for calls that carry neither an override nor a session mode. */
+  readonly mode: SandboxMode;
+  /** Workspace root for agentless calls and sessions without a cwd. */
+  readonly workspaceRoot: string;
+  /** Carve-outs that always apply, before request-supplied ones. */
+  readonly entries?: readonly FileSystemEntry[];
+  /** Access where no layer applies; see {@link SandboxExecutionPolicy.baseline}. */
+  readonly baseline?: FileSystemAccess;
+  /**
+   * Network reach for calls that do not narrow it. Defaults to `allow-all`,
+   * which is what this package did before the seam existed; a deployment
+   * running anything untrusted should set `deny` and widen per call.
+   */
+  readonly network?: NetworkMode;
+}
+/**
+ * Resolve the complete policy for one capability call.
+ *
+ * Authority only ever decreases across untrusted inputs: the deployment default
+ * and the session's mode set a ceiling, a request may narrow beneath it, and a
+ * minted approval is the single path that raises it. A session cwd is its
+ * `workspace-write` boundary; the configured root is the fallback for agentless
+ * calls and sessions without a cwd.
+ * @param request - the calling session's untrusted ask, plus any approval.
+ * @param defaults - deployment mode, workspace root, and standing carve-outs.
+ * @throws SandboxPolicyError when a request tries to widen without an approval.
+ */
+declare function resolveSandboxPolicy(request: SandboxPolicyRequest, defaults: SandboxPolicyDefaults): SandboxExecutionPolicy;
+/**
+ * Narrow a resolved policy to the confining shape a provider accepts.
+ * @returns the confining policy, or `undefined` under `danger-full-access`,
+ *   whose consumer spawns its original argv and never calls the provider.
+ */
+declare function confiningPolicy(policy: SandboxExecutionPolicy): SandboxPolicy | undefined;
+/**
+ * Narrow a policy toward a stricter mode without widening it. Used where a
+ * consumer may tighten a caller's policy but must never loosen it.
+ */
+declare function narrowPolicy(policy: SandboxExecutionPolicy, mode: SandboxMode): SandboxExecutionPolicy;
+//#endregion
+//#region src/classify.d.ts
+/**
+ * Outcome classification.
+ *
+ * Two failures look alike in a shell but mean opposite things. A *denial* means
+ * confinement worked and blocked the command. A *runner failure* means the
+ * sandbox itself refused or crashed and the command never ran at all. Reporting
+ * the second as the first sends a model off rewriting correct code, so runner
+ * failure is always checked first and never inferred from an exit code alone.
+ */
+/** Evidence that a runner failed before it executed the wrapped command. */
+interface RunnerFailureRule {
+  /** Nonzero exits this rule may match; omitted permits any nonzero exit. */
+  readonly allowedExitCodes?: readonly number[];
+  /** Case-insensitive substrings identifying a fatal runner diagnostic. */
+  readonly fatalSignatures: readonly string[];
+  /** Benign lines removed by exact, case-insensitive full-line equality first. */
+  readonly informationalLines?: readonly string[];
+  /**
+   * Substrings that disqualify a line from proving runner failure, applied
+   * before {@link fatalSignatures}. A runner reports the child's failed `exec`
+   * under its own name and often its own exit code, so the prefix that
+   * identifies its diagnostics also matches an ordinary missing program; this
+   * is how that one case is carved back out.
+   */
+  readonly excludedSignatures?: readonly string[];
+}
+/** What a finished confined command turned out to be. */
+type SandboxOutcomeKind = 'success' | 'runner-failure' | 'denied' | 'command-failure';
+/** The observable result of spawning a confined argv. */
+interface CommandOutcome {
+  /** Process exit code; a signalled process reports its conventional code. */
+  readonly exitCode: number;
+  /** Stderr text as produced, never rewritten by classification. */
+  readonly stderr: string;
+  /** Terminating signal name, when the host reports one. */
+  readonly signal?: string | null;
+  /**
+   * Whether the runner reported, on a channel of its own, that it executed the
+   * command. Stderr cannot answer this: the runner and the command share that
+   * stream, so a command can print the runner's fatal signature and exit with
+   * the runner's code, and claim it never ran. When this is `true` no
+   * runner-failure rule applies, because the claim is already contradicted by
+   * evidence the command could not write.
+   */
+  readonly childStarted?: boolean;
+}
+/** Evidence a consumer needs to classify one confined command's outcome. */
+interface SandboxClassificationInput {
+  /** Denial dialect of the backend that actually wrapped this command. */
+  readonly denialSignatures: readonly string[];
+  /** Structured runner-failure evidence for that same backend. */
+  readonly runnerFailureRules: readonly RunnerFailureRule[];
+}
+/** A classified outcome plus the stderr line that proved it. */
+interface SandboxClassification {
+  readonly kind: SandboxOutcomeKind;
+  /** The stderr line that matched, kept verbatim for the caller to surface. */
+  readonly evidence?: string;
+}
+/**
+ * Classify one confined command's outcome.
+ *
+ * Runner failure is tested first, then a seccomp kill (deterministic, no text
+ * matching needed), then the backend's own denial dialect. A cross-backend
+ * union of denial strings is deliberately not used: it would claim denials a
+ * given backend never produces.
+ */
+declare function classifyOutcome(outcome: CommandOutcome, input: SandboxClassificationInput): SandboxClassification;
+/**
+ * Append a short, factual note to stderr explaining a sandbox outcome, so a
+ * reader never has to infer confinement from a bare error string.
+ */
+declare function annotateStderr(stderr: string, classification: SandboxClassification, mode: string): string;
+//#endregion
+//#region src/provider.d.ts
+/** The argv to spawn in place of the caller's own, plus how to read its result. */
+interface ConfinedArgv {
+  /** The wrapped argv: runner, profile arguments, separator, caller's argv. */
+  readonly argv: readonly string[];
+  /** How completely the selected backend enforces this policy's file effects. */
+  readonly enforcement: SandboxEnforcement;
+  /**
+   * How completely it enforces the policy's network reach. `none` means the
+   * command can reach whatever the host can, whatever the policy asked for —
+   * a separate fact from file enforcement, because a host can provide one
+   * mechanism and not the other.
+   */
+  readonly networkEnforcement: NetworkEnforcement;
+  /** Identifier of the backend that produced this wrap. */
+  readonly backend: string;
+  /**
+   * The selected backend's denial DIALECT: the stderr substrings a file effect
+   * denied by THIS backend produces. Matched instead of a cross-backend union,
+   * which would claim denials this backend never emits.
+   */
+  readonly denialSignatures: readonly string[];
+  /** Structured evidence that the runner failed before the command ran. */
+  readonly runnerFailureRules: readonly RunnerFailureRule[];
+  /** Environment additions marking the confinement for child processes. */
+  readonly env: Readonly<Record<string, string>>;
+  /**
+   * File descriptor the runner reports its own status on, when it has one.
+   *
+   * The consumer must give the spawned process a pipe at this descriptor and
+   * read it back: it is the only channel a confined command cannot write to,
+   * and therefore the only evidence that distinguishes a runner that failed
+   * from a command claiming the runner failed.
+   */
+  readonly statusFd?: number;
+}
+/**
+ * In-process path fence. It governs file effects a tool performs itself, which
+ * no process sandbox can see, and is the only enforcement available on a
+ * platform without a process backend.
+ */
+interface FsFence {
+  /** Throw `SandboxDeniedError` unless the path may be written. */
+  assertWritable(path: string): Promise<void>;
+  /** Whether the path may be written, without throwing. */
+  isWritable(path: string): Promise<boolean>;
+  /** Whether the path may be read; `deny` carve-outs make this false. */
+  isReadable(path: string): Promise<boolean>;
+  /** The roots this fence permits writes under, for surfacing to a caller. */
+  readonly writableRoots: readonly string[];
+  /** Whether the path's inode carries another name this policy never examined. */
+  isAliased(path: string): Promise<boolean>;
+}
+/**
+ * Abstract process-sandbox service. `confine` must return an enforcing argv or
+ * fail closed; silent unconfined passthrough is forbidden.
+ */
+interface SandboxProvider {
+  /** Stable identifier of this provider implementation. */
+  readonly id: string;
+  /**
+   * Wrap `argv` so it executes confined under `policy` on this host.
+   * @param argv - the exact argv the caller is about to spawn, NOT a shell
+   *   string; a shell-shaped consumer passes `['bash', '-c', command]`.
+   * @param policy - the file-effect policy this execution runs under.
+   * @returns the argv to spawn instead, plus its enforcement and dialects.
+   */
+  confine(argv: readonly string[], policy: SandboxPolicy): Promise<ConfinedArgv>;
+  /** Build the in-process fence for the same policy the backends receive. */
+  fence(policy: SandboxPolicy): FsFence;
+}
+/** Filesystem facts the Universal contract cannot read for itself. */
+interface PathResolver {
+  /** Canonical path with symlinks resolved, for the nearest existing ancestor. */
+  realpath(path: string): Promise<string>;
+  /** Whether the path currently exists. */
+  exists(path: string): Promise<boolean>;
+  /**
+   * The target of a symbolic link, or `undefined` when the path is not one.
+   *
+   * Existence has to be judged without following links: a link pointing at a
+   * path that does not exist yet still exists itself, and treating it as absent
+   * makes the resolver judge the link's own name instead of where it leads —
+   * which is inside the workspace, and therefore writable.
+   */
+  readLink?(path: string): Promise<string | undefined>;
+  /**
+   * How many names refer to this file's inode, when the host can say.
+   *
+   * A path boundary cannot see a hard link: two names for one inode, one inside
+   * the workspace and one outside, let a write reach past the boundary through
+   * the inside name. A count above one means the file is reachable under
+   * another name this policy never examined.
+   */
+  hardLinkCount?(path: string): Promise<number>;
+}
+//#endregion
+//#region src/roots.d.ts
+/**
+ * Directory names never writable inside a granted root. Writing `.git` lets a
+ * command install a hook that runs arbitrary code on the next git invocation,
+ * which defeats the point of confining the command; the credential files are
+ * there so a confined command cannot rewrite the caller's own authentication.
+ * They stay readable — this is a write boundary, not a read boundary.
+ */
+declare const PROTECTED_SUBPATHS: readonly string[];
+/** Where a layer came from, which decides ties at equal path specificity. */
+type GrantOrigin = 'mode' | 'protected' | 'entry' | 'restriction' | 'approval';
+/** One subtree's access, overriding whatever the layers beneath it said. */
+interface GrantLayer {
+  /** Absolute, normalized path whose subtree this layer governs. */
+  readonly path: string;
+  /** Access this layer establishes for that subtree. */
+  readonly access: FileSystemAccess;
+  /** What contributed the layer; an explicit entry outranks a generated one. */
+  readonly origin: GrantOrigin;
+}
+/**
+ * The baseline every policy starts from: the host is readable and nothing is
+ * writable. Layers only ever move a subtree away from this.
+ */
+declare const BASELINE_ACCESS: FileSystemAccess;
+/** Optional platform inputs the caller knows and this package must not guess. */
+interface WritableRootOptions {
+  /** Temp directories `workspace-write` may also use (e.g. the OS temp root). */
+  readonly tempRoots?: readonly string[];
+  /** Whether to layer {@link PROTECTED_SUBPATHS} under every granted root. */
+  readonly protectSubpaths?: boolean;
+  /**
+   * Absolute paths the platform hides outright — credential stores and host
+   * daemon sockets. Layered as `deny` above the mode grant and below any
+   * explicit entry, so a deployment can still reopen one deliberately while a
+   * tool-supplied restriction cannot widen it.
+   */
+  readonly deniedPaths?: readonly string[];
+  /**
+   * Permit writes to a file whose inode carries more than one name. Off by
+   * default: a hard link reaching out of the workspace is otherwise invisible
+   * to a boundary made of paths.
+   */
+  readonly allowAliasedWrites?: boolean;
+}
+/**
+ * Resolve a policy into the ordered layers that express it.
+ *
+ * Layers are sorted broadest to narrowest, and an explicit entry wins a tie at
+ * equal depth so a deployment can deliberately reopen a protected subpath. A
+ * layer that would not change the access already in force is dropped, so the
+ * result carries no mount or profile rule that does nothing.
+ */
+declare function grantLayers(policy: SandboxPolicy, options?: WritableRootOptions): readonly GrantLayer[];
+/**
+ * The access in force at one path, given layers already applied in order.
+ * The last layer whose subtree contains the path wins, which is what makes a
+ * narrower grant reopen a denied parent.
+ */
+declare function accessInLayers(target: string, layers: readonly GrantLayer[], baseline?: FileSystemAccess): FileSystemAccess;
+/** The write grants and re-denials one policy resolves to. */
+interface WritableRootSet {
+  /** Subtrees that end up writable, broadest first. */
+  readonly roots: readonly string[];
+  /** Subtrees inside those roots that are not writable, in application order. */
+  readonly denied: readonly string[];
+}
+/**
+ * The writable subtrees and their re-denials, flattened from {@link grantLayers}
+ * for callers that only need the two lists. Order is preserved; a narrower grant
+ * beneath a denial appears in `roots` after the denial it reopens.
+ */
+declare function writableRoots(policy: SandboxPolicy, options?: WritableRootOptions): WritableRootSet;
+/** Subtrees whose contents must not be readable, for backends that can mask. */
+declare function unreadablePaths(policy: SandboxPolicy, options?: WritableRootOptions): readonly string[];
+//#endregion
+//#region src/fence.d.ts
+/**
+ * Build the fence for one policy.
+ * @param policy - the same policy the process backends receive.
+ * @param resolver - filesystem facts used to defeat symlinked paths.
+ * @param options - platform temp roots and protected-subpath behaviour.
+ */
+declare function createFsFence(policy: SandboxPolicy, resolver: PathResolver, options?: WritableRootOptions): FsFence;
+//#endregion
+//#region src/path.d.ts
+/**
+ * Pure, dependency-free path algebra shared by every sandbox backend.
+ *
+ * This package is Universal: it must never import `node:path`, so the lexical
+ * rules both POSIX and Win32 backends rely on live here as string operations.
+ * Filesystem-dependent resolution (realpath, existence) is injected through
+ * {@link PathResolver} by the Node-elevated provider instead.
+ */
+/** Which lexical dialect a path is written in. */
+type PathFlavor = 'posix' | 'win32';
+/** Detect the dialect of an absolute path from its own shape. */
+declare function detectFlavor(path: string): PathFlavor;
+/** Whether the path is absolute in either dialect. */
+declare function isAbsolutePath(path: string): boolean;
+/**
+ * Collapse separators and resolve `.` / `..` lexically, without touching the
+ * filesystem. A `..` that would escape the root is dropped, matching how both
+ * bwrap and Seatbelt treat an over-popped absolute path.
+ */
+declare function normalizePath(path: string): string;
+/** Normalized segments below the root prefix; the root itself has none. */
+declare function pathSegments(path: string): readonly string[];
+/**
+ * Specificity rank used to order overlapping policy entries. A deeper path is
+ * more specific, so it is applied later and wins over a broader ancestor.
+ */
+declare function pathDepth(path: string): number;
+/** Whether two paths identify the same location lexically. */
+declare function samePath(left: string, right: string): boolean;
+/**
+ * Whether `candidate` is `root` itself or lies beneath it. Comparison is
+ * segment-wise, so `/repo-secrets` is never treated as inside `/repo`.
+ */
+declare function containsPath(root: string, candidate: string): boolean;
+/** Append relative segments to an absolute base, normalizing the result. */
+declare function joinPath(base: string, ...parts: readonly string[]): string;
+/** The parent of a normalized path, or `undefined` at a filesystem root. */
+declare function parentPath(path: string): string | undefined;
+/** Every ancestor of `path` from the filesystem root down to `path` itself. */
+declare function ancestorPaths(path: string): readonly string[];
+/** Drop paths already covered by a broader entry in the same list. */
+declare function dedupeRoots(roots: readonly string[]): readonly string[];
+//#endregion
+//#region src/resources.d.ts
+/**
+ * Resource limits — a third axis, and the one this package enforces weakest.
+ *
+ * A filesystem boundary can be completely correct while the host falls over: a
+ * fork storm, a growing allocation, or a loop that never ends costs nothing in
+ * file effects. Measured against the current backends, 150 processes, 2 GB of
+ * memory and 20 000 files met no resistance at all.
+ *
+ * What a host can actually promise differs so much that the promise has to be
+ * reported rather than assumed. A real quota needs cgroup v2 or a Job Object;
+ * without one, limits can still be observed and acted on, which stops a runaway
+ * but does not prevent the spike that precedes it.
+ */
+/** What a confined execution may consume. Every field is optional. */
+interface ResourceLimits {
+  /** Wall-clock time before the execution is ended. */
+  readonly wallClockMs?: number;
+  /** Resident memory across the whole process tree. */
+  readonly memoryBytes?: number;
+  /** Processes in the tree, including the sandbox process itself. */
+  readonly processes?: number;
+  /** Accumulated CPU time across the tree. */
+  readonly cpuMs?: number;
+}
+/**
+ * How a host enforces those limits.
+ *
+ * `quota` means the kernel refuses to exceed them. `monitor` means they are
+ * sampled and the execution is ended once exceeded — which bounds a runaway but
+ * not the spike between two samples. `none` means nothing is watching.
+ */
+type ResourceEnforcement = 'quota' | 'monitor' | 'none';
+/** Why a supervised execution was ended. */
+type ResourceBreach = 'wall-clock' | 'memory' | 'processes' | 'cpu';
+/** What a supervised execution actually consumed. */
+interface ResourceUsage {
+  /** Highest resident memory observed across the tree. */
+  readonly peakMemoryBytes: number;
+  /** Highest process count observed in the tree. */
+  readonly peakProcesses: number;
+  /** Highest accumulated CPU time observed. */
+  readonly cpuMs: number;
+  /** Wall-clock time the execution ran for. */
+  readonly wallClockMs: number;
+}
+/** Whether any limit is set at all, so a caller can skip supervision entirely. */
+declare function hasResourceLimits(limits: ResourceLimits): boolean;
+/**
+ * The first limit the usage exceeds, or `undefined` while it is within them.
+ * Checked in the order a runaway usually announces itself.
+ */
+declare function breachedLimit(usage: ResourceUsage, limits: ResourceLimits): ResourceBreach | undefined;
+//#endregion
+//#region src/violation.d.ts
+/** The enforcement layer that observed a violation. */
+type SandboxViolationBackend = 'bwrap' | 'seatbelt' | 'windows-acl' | 'fence' | 'custom';
+/** Why a file effect was refused, normalized across backend dialects. */
+type SandboxViolationReason = 'operation-not-permitted' | 'permission-denied' | 'read-only-filesystem' | 'policy-denied' | 'runner-failure';
+/** One observed violation, retaining the evidence that identified it. */
+interface SandboxViolation {
+  readonly backend: SandboxViolationBackend;
+  readonly reason: SandboxViolationReason;
+  readonly mode: string;
+  /** The path involved, when the backend named one. */
+  readonly path?: string;
+  /** Bounded evidence excerpt; never the whole output. */
+  readonly snippet: string;
+}
+/**
+ * Build a violation record from a classified outcome.
+ * @returns the record, or `undefined` when the outcome was not a violation.
+ */
+declare function sandboxViolation(classification: SandboxClassification, backend: SandboxViolationBackend, mode: string): SandboxViolation | undefined;
+//#endregion
+export { BASELINE_ACCESS, type CommandOutcome, type ConfinedArgv, type ConfinedSandboxMode, DEFAULT_EXEC_OUTCOMES, type ExecCapability, type ExecClassification, type ExecOutcome, type FileSystemAccess, type FileSystemEntry, type FsFence, type GrantLayer, type GrantOrigin, NETWORK_MODES, type NetworkEnforcement, type NetworkMode, PROTECTED_SUBPATHS, type PathFlavor, type PathResolver, type ResourceBreach, type ResourceEnforcement, type ResourceLimits, type ResourceUsage, type RunnerFailureRule, SANDBOX_MODES, type SandboxApproval, type SandboxApprovalGrant, type SandboxApprovalScope, type SandboxClassification, type SandboxClassificationInput, SandboxDeniedError, type SandboxEnforcement, type SandboxExecutionPolicy, type SandboxMode, type SandboxOutcomeKind, type SandboxPolicy, type SandboxPolicyDefaults, SandboxPolicyError, type SandboxPolicyRequest, type SandboxProvider, SandboxUnavailableError, type SandboxViolation, type SandboxViolationBackend, type SandboxViolationReason, type WritableRootOptions, type WritableRootSet, accessFor, accessInLayers, ancestorPaths, annotateStderr, approveSandboxEscalation, breachedLimit, classifyExec, classifyOutcome, confiningPolicy, containsPath, createFsFence, dedupeRoots, detectFlavor, entriesWithin, grantLayers, hasResourceLimits, isAbsolutePath, isConfinedMode, isNetworkMode, isSandboxApproval, isSandboxApprovalSpent, isSandboxMode, joinPath, modeAuthority, narrowNetwork, narrowPolicy, networkAuthority, normalizePath, orderEntries, parentPath, pathDepth, pathSegments, requireSandboxApproval, resolveSandboxPolicy, samePath, sandboxViolation, splitCommands, tokenizeScript, unreadablePaths, writableRoots };
+//# sourceMappingURL=index.d.ts.map