@agent-compose/sdk 0.7.0 → 0.8.0

package/dist/sandbox.d.ts

@@ -1,303 +1,28 @@
 /**
- * Sandbox provider registry — creates and manages isolated execution environments.
+ * Sandbox module — public surface.
  *
- * Providers: "vercel" (Vercel Sandbox), "e2b" (E2B), "e2b-desktop" (E2B Desktop).
- * Each provider validates its required env vars at creation time.
+ * Implementation lives in `sandbox/`:
+ *   - `sandbox/network-policy.ts` — egress policy shape + per-provider translators
+ *   - `sandbox/sizes.ts`          — machine sizes + E2B template aliases
+ *   - `sandbox/devbox.ts`         — the ADR-0038 per-member desktop machine alias
+ *   - `sandbox/provider-def.ts`   — provider contract, create opts, fleet tag
+ *   - `sandbox/exec-stream.ts`    — SSE exec-stream parser (broker clients)
+ *   - `sandbox/providers/*`       — vercel / e2b / e2b-desktop / local providers
+ *   - `sandbox/registry.ts`       — provider registry + fleet management
  */
-import { Sandbox } from "e2b";
-import type { SandboxNetworkOpts as E2bNetworkOpts } from "e2b";
-import { Sandbox as Desktop } from "@e2b/desktop";
-import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult } from "./types/sandbox.js";
-import type { ConnectorRequestRules } from "./types/workflow-metadata.js";
-import type { NetworkPolicy as VercelNetworkPolicy } from "@vercel/sandbox";
 export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions, SandboxCommandResult, SandboxDuplexProcess, SandboxSpawnDuplexOptions } from "./types/sandbox.js";
-export type SandboxProviderName = "vercel" | "e2b" | "e2b-desktop";
-export declare const AGENT_COMPOSE_TAG: string;
-/**
- * Network policy for outbound HTTPS requests — ONE shape for every provider;
- * only the enforcement point differs. When a sandbox makes a request matching
- * a domain in `allow`, the egress layer injects the specified headers before
- * forwarding — credentials never exist inside the VM. Both providers enforce
- * this natively at the platform edge from the resolved policy passed at
- * create: Vercel via its firewall (`requestRules` translate to native `match`
- * rules), E2B via its native network firewall (`toE2bNetwork` →
- * `allowOut`/`denyOut`/`rules`). See `toVercelNetworkPolicy` / `toE2bNetwork`.
- */
-export interface SandboxNetworkHeaderTransform {
-    headers?: Record<string, string>;
-}
-export interface SandboxNetworkAllowRule {
-    transform?: SandboxNetworkHeaderTransform[];
-    /** Tier-2 request gate (method/path) — the transform only applies when the
-     *  request matches. Honoured on Vercel (translated to native `match` rules).
-     *  NOT honoured on E2B: its native rules carry only a `transform`, no
-     *  method/path matcher, so a brokered credential rides ALL requests to an
-     *  allowed host there (see `toE2bNetwork`). Present on connector-auth rules;
-     *  see `ConnectorRequestRules`. */
-    requestRules?: ConnectorRequestRules;
-}
-export interface SandboxNetworkSubnetPolicy {
-    allow?: string[];
-    deny?: string[];
-}
-export type SandboxNetworkPolicy = "allow-all" | "deny-all" | {
-    allow?: string[] | Record<string, SandboxNetworkAllowRule[]>;
-    subnets?: SandboxNetworkSubnetPolicy;
-};
-/** Sandbox machine size. A coarse small/medium/large knob that maps to
- *  provider machine specs at create time. Vercel honours it natively via
- *  `resources.vcpus` (2048 MB RAM per vCPU). E2B sizing is baked into the
- *  template, so E2B ignores this field. Default: "small". */
-/** Sandbox hardware SKU. Named for the actual machine spec (vCPU + RAM) rather
- *  than abstract t-shirt sizes. Memory is always 2048 MB per vCPU:
- *    2vcpu-4gb   =  2 vCPU /  4 GiB  (Vercel's own default machine)
- *    4vcpu-8gb   =  4 vCPU /  8 GiB
- *    8vcpu-16gb  =  8 vCPU / 16 GiB  (per-sandbox ceiling on STANDARD accounts —
- *                                     probed live: 16 & 32 vCPU 400 on dev)
- *    32vcpu-64gb = 32 vCPU / 64 GiB  (ENTERPRISE ONLY — standard accounts reject >8 vCPU) */
-export type SandboxSize = "2vcpu-4gb" | "4vcpu-8gb" | "8vcpu-16gb" | "32vcpu-64gb";
-/** SKU → Vercel vCPU count (RAM follows at 2048 MB/vCPU). */
-export declare const SANDBOX_VCPUS: Record<SandboxSize, number>;
-/** SDK fallback size when neither the caller nor the deployment specifies one.
- *  Deliberately conservative — the OPERATIONAL default is the server's
- *  `SANDBOX_DEFAULT_SIZE` env var (now also `2vcpu-4gb`). Keeping the default
- *  small matters because Vercel rate-limits creation by vCPUs-per-window
- *  (`api-sandboxes-vcpus-creation`); a large default 429s bursty/simultaneous
- *  creates. Workloads that need more RAM/CPU declare `resources.size` on the
- *  workflow rather than inflating the default for everyone. */
-export declare const DEFAULT_SANDBOX_SIZE: SandboxSize;
-/** The E2B sizes we pre-build a template for. E2B sizing is template-baked
- *  (no per-create cpu/mem knob), so honouring `resources.size` on E2B means
- *  ONE pre-built template per size. `32vcpu-64gb` is absent (E2B has no
- *  >8-vCPU equivalent). `8vcpu-16gb` is also absent: it needs 16 GiB RAM, but
- *  the E2B account caps memory at 8 GiB (`Template.build` 400s with
- *  "Memory can't be higher than 8192 MiB"). Add it back here (and rebuild the
- *  templates) only once the account's memory limit is raised. The register/
- *  invoke guards reject an unsupported E2B size before it can reach here. */
-export declare const E2B_TEMPLATE_SIZES: readonly SandboxSize[];
-/** Is `size` one E2B can be built/booted at? `32vcpu-64gb` (no >8-vCPU E2B
- *  equivalent) and `8vcpu-16gb` (exceeds the account's 8 GiB memory cap) are
- *  not — the guards lean on this so the "no E2B equivalent" decision lives in
- *  exactly one place. */
-export declare function isE2bSupportedSize(size: SandboxSize): boolean;
-/** Machine spec for a SandboxSize, in the shape `Template.build` wants. RAM is
- *  always 2048 MB/vCPU, matching the size name + Vercel parity
- *  (`SANDBOX_VCPUS` × 2048). Used by `infra/e2b-template/build.ts` to stamp the
- *  per-size base + agent-env templates. */
-export declare function e2bMachineSpec(size: SandboxSize): {
-    cpuCount: number;
-    memoryMB: number;
-};
-/** Stable E2B template ALIAS for the platform base at a given size
- *  (`agent-compose-base-<size>`). Aliases — not snapshot ids — so the refs are
- *  multi-account-clean: the same string resolves in any E2B account that built
- *  the templates. Built by `infra/e2b-template/build.ts`; the E2B provider
- *  boots this when a run on E2B declares no explicit `bootFrom`/template. */
-export declare function e2bBaseTemplate(size: SandboxSize): string;
-/** Stable E2B template ALIAS for the agent runtime (base + claude binary) at a
- *  given size (`agent-env-<size>`). The agent default templates boot from this
- *  via `bootFrom: { snapshotId: e2bAgentEnvTemplate(size) }`. Multi-account-clean
- *  for the same reason as `e2bBaseTemplate`. */
-export declare function e2bAgentEnvTemplate(size: SandboxSize): string;
-/** Is `id` one of the platform-managed E2B template aliases — a
- *  `agent-compose-base-<size>` or `agent-env-<size>` for a supported size?
- *
- *  These are stable, platform-built, multi-account-clean strings (NOT tenant
- *  captures), so any workflow may boot from them: the same alias resolves to
- *  the same platform base in every account, and there is no tenant data behind
- *  it to leak. The dispatch snapshot gate uses this to vouch a platform E2B
- *  boot alias without it having to be a team-owned capture or a published
- *  template's bootFrom. */
-export declare function isPlatformE2bTemplateAlias(id: string): boolean;
-export interface SandboxCreateOpts {
-    envs: Record<string, string>;
-    metadata: Record<string, string>;
-    timeoutMs: number;
-    /** Provider-specific template/snapshot identifier. E2B: template id or
-     *  snapshot id (omit → E2B's default base). Vercel: snapshot id (omit → node24). */
-    template?: string;
-    /** Machine size. Vercel maps it to `resources.vcpus`; E2B ignores it
-     *  (size is template-defined). Omit → `DEFAULT_SANDBOX_SIZE`. */
-    size?: SandboxSize;
-    /** Outbound request policy with header transforms — ONE shape for every
-     *  provider; only the enforcement point differs. Both providers enforce +
-     *  inject natively at create from this value: Vercel via its firewall
-     *  (`toVercelNetworkPolicy`), E2B via its native network firewall
-     *  (`toE2bNetwork` → `network: { allowOut, denyOut, rules }`). */
-    networkPolicy?: SandboxNetworkPolicy;
-}
-/**
- * What the provider reports as "currently alive" — the single input to orphan
- * reconciliation. `metadata` is best-effort: E2B populates it from sandbox
- * labels, Vercel from sandbox tags (max 5, stamped at create). Callers
- * that need runId correlation cross-reference `sandboxId` against their own
- * state (server: `workflow_runs.sandbox_id` + `run_agent_sandboxes.provider_sandbox_id`).
- */
-export interface OwnedSandbox {
-    sandboxId: string;
-    createdAt: Date;
-    metadata: Record<string, string>;
-}
-interface SandboxProviderDef {
-    requiredEnv: Record<string, string>;
-    create: (opts: SandboxCreateOpts, env: Record<string, string>) => Promise<SandboxProvider>;
-    reconnect?: (sandboxId: string) => Promise<SandboxProvider>;
-    killAll?: (env: Record<string, string>) => Promise<void>;
-    /**
-     * Returns the number of sandboxes currently running against this provider.
-     * Used for quota observability — account-wide, not per-instance.
-     *
-     * Both providers scope by our AGENT_COMPOSE_TAG (E2B metadata labels,
-     * Vercel tags) so each fleet only reports its own sandboxes; DD aggregates
-     * across instances with `sum by {provider}`.
-     */
-    getActiveCount?: (env: Record<string, string>) => Promise<number>;
-    /**
-     * Provider's view of what's currently alive for our account/fleet.
-     * The reconciliation SoT — a sandbox missing from this list IS dead,
-     * regardless of what our DB says. Implemented by listing the provider's
-     * running sandboxes; E2B filters by metadata tag, Vercel by the `executor`
-     * sandbox tag.
-     */
-    listOwned?: (env: Record<string, string>) => Promise<OwnedSandbox[]>;
-    /**
-     * Delete a snapshot by id. Called from the customer-initiated
-     * `DELETE /workflows/:runId/snapshot` route. Best-effort — the DB is
-     * source of truth; an orphan on the provider side is benign and cleaned
-     * up eventually by the provider's own retention.
-     */
-    deleteSnapshot?: (snapshotId: string, env: Record<string, string>) => Promise<void>;
-    /**
-     * Does this snapshot id resolve on the provider for this account? A cheap
-     * metadata lookup — NEVER provisions a sandbox. Used at server boot to
-     * validate that the platform base snapshots the default templates boot from
-     * actually exist for this deployment (catching e.g. a dev-account snapshot
-     * baked into prod). Returns true if it resolves, false if the provider
-     * reports it does not exist. Transport/credential errors PROPAGATE — an
-     * indeterminate result must not be reported as "missing".
-     */
-    snapshotExists?: (snapshotId: string, env: Record<string, string>) => Promise<boolean>;
-}
-export declare function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider;
-export declare function makeDesktopSandboxProvider(sb: Desktop): DesktopSandboxProvider;
-export interface ParseSseExecStreamOptions {
-    onStdout?: (data: string) => void;
-    onStderr?: (data: string) => void;
-}
-/**
- * Parse an SSE exec stream from a ReadableStream.
- * Used by the agent sandbox broker in runner.ts.
- */
-export declare function parseSseExecStream(body: ReadableStream<Uint8Array>, opts?: ParseSseExecStreamOptions): Promise<SandboxCommandResult>;
-/** Matches a path containing a dot-dot segment — literal (`/../`) or
- *  percent-encoded (`%2e%2e`, `%2f` boundaries). `DOT_SEGMENT_PATH_RE2` is
- *  the RE2 form handed to Vercel's matcher: wrapped in `.*` so it behaves
- *  identically under search and full-match semantics (RE2 has no lookaround,
- *  so the guard is a positive match on the traversal pattern, used as a
- *  credential-stripping first rule). `DOT_SEGMENT_RE` is the local JS twin
- *  used to validate DECLARED prefixes. */
-export declare const DOT_SEGMENT_PATH_RE2 = ".*(?:^|/|%2[fF])(?:\\.|%2[eE]){2}(?:/|%2[fF]|$).*";
-/**
- * Translate our policy shape into Vercel's native `NetworkPolicy`.
- *
- * The shapes are identical except for Tier-2: our `requestRules`
- * (`{ methods, pathPrefixes }`) become Vercel `match` rules
- * (`{ method, path: { startsWith } }`) — one rule per path prefix, since a
- * Vercel matcher carries a single path.
- *
- * Dot-segment defense: prefix matching is raw — `/repos/acme/../../user`
- * starts with `/repos/acme/` but the origin normalizes it to `/user`, riding
- * the credential outside its declared scope. We don't get to assume the
- * enforcer RFC-3986-normalizes before matching, so every domain with a path
- * gate gets a transform-free FIRST rule matching dot-segment paths
- * (first-match-wins ⇒ such requests go out credential-free), and declared
- * prefixes themselves are validated (must start with "/", no dot-segments).
- *
- * Accepted divergence from iron-proxy (E2B): off-gate requests to an allowed
- * domain pass WITHOUT the transform (Vercel terminates TLS only for
- * transform-bearing domains and applies first-match-wins) — iron-proxy
- * REFUSES them instead. Reachability differs; the property that matters is
- * preserved on both substrates: the brokered credential rides only declared
- * method/path combinations. Pinned by vercel-network-policy.test.ts.
- */
-export declare function toVercelNetworkPolicy(policy: SandboxNetworkPolicy): VercelNetworkPolicy;
-/**
- * Translate our policy shape into E2B's native `network` config
- * (`SandboxNetworkOpts`) — the E2B analogue of `toVercelNetworkPolicy`.
- *
- *   - `allowOut`: the set of allowed egress targets — every host named in
- *     `allow` PLUS every CIDR in `subnets.allow`. The Archil raw-TCP
- *     data-plane CIDRs ride here as FIRST-CLASS allow entries (E2B has no
- *     root-exemption to lean on, unlike the old in-VM iptables model).
- *   - `denyOut`: the all-traffic sentinel (`0.0.0.0/0`) so the policy is
- *     DEFAULT-DENY — only `allowOut` targets pass. E2B applies allow before
- *     deny, so a host in both lists is allowed.
- *   - `rules`: per-host header injection. For each host carrying transform(s),
- *     emit one rule per transform with `{ transform: { headers } }`. A host
- *     with a rule MUST also be in `allowOut` (registering a rule does not
- *     grant egress on its own — E2B's API requires the host in `allowOut`).
- *
- * BEHAVIOURAL DIVERGENCE FROM iron-proxy / Vercel — path/method gating is NOT
- * available on E2B native rules. An `SandboxNetworkRule` carries only a
- * `transform` (header injection); there is no method/path matcher. So our
- * Tier-2 `requestRules` (`{ methods, pathPrefixes }`) cannot be enforced here:
- * a brokered credential rides EVERY request to an allowed host on E2B, whereas
- * Vercel (native `match`) and the old iron-proxy gated it to the declared
- * method+path. The host allowlist still confines WHICH hosts the credential
- * can reach; it just can't narrow to a method/path within an allowed host.
- *
- * String policies map straight through: "allow-all" → no restriction (omit
- * `allowOut`/`denyOut`), "deny-all" → block all egress.
- */
-export declare function toE2bNetwork(policy: SandboxNetworkPolicy): E2bNetworkOpts;
-/** Vercel caps sandbox tags at 5. Build the tag set with the fleet `executor`
- *  tag always present and always winning over caller metadata — `listOwned` /
- *  orphan reconciliation scope on it, so a clobbered or dropped executor tag
- *  makes the sandbox invisible to cleanup. When metadata overflows the cap,
- *  keep executor + the lexicographically-first 4 metadata keys, so what gets
- *  dropped is deterministic rather than dependent on object insertion order. */
-export declare const VERCEL_MAX_TAGS = 5;
-export declare function buildVercelTags(metadata: Record<string, string>): Record<string, string>;
-/** Minimal SandboxProvider that targets the current process's host VM.
- *  `commands.run` → `child_process.spawn`; `files.write` → `fs.writeFile`;
- *  `kill` is a no-op because the caller IS the VM. Used by
- *  `defineSandboxEnvironment` so setup recipes read like imperative
- *  provisioning scripts. Uses `node:child_process` — works under both Node
- *  (the runner executes `node /tmp/runner.bundle.js`) and Bun. */
-export declare function makeLocalSandboxProvider(): SandboxProvider;
-declare const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef>;
-/** Provision a sandbox for the named provider. */
-export declare function createSandbox(provider: SandboxProviderName, opts: SandboxCreateOpts): Promise<SandboxProvider>;
-/** Reconnect to an existing sandbox by provider + provider-native sandbox ID. */
-export declare function reconnectSandbox(provider: SandboxProviderName, sandboxId: string): Promise<SandboxProvider>;
-/** Delete a snapshot by id on the named provider. No live sandbox needed. */
-export declare function deleteSandboxSnapshot(provider: SandboxProviderName, snapshotId: string): Promise<void>;
-/**
- * Does `snapshotId` resolve on the named provider for this account? A cheap
- * metadata lookup — never provisions a sandbox. `true` = resolves, `false` =
- * provider says it does not exist. Transport/credential errors propagate (an
- * indeterminate result is not "missing"). Used at server boot to validate the
- * platform base snapshots the default templates boot from.
- */
-export declare function snapshotResolves(provider: SandboxProviderName, snapshotId: string): Promise<boolean>;
-/**
- * Current active-sandbox count per configured provider, for quota gauges.
- * Skips providers whose required env isn't set or which don't implement
- * `getActiveCount`. Errors are surfaced per-provider so one flaky provider
- * doesn't silence the rest.
- */
-export type SandboxQuotaResult = Partial<Record<SandboxProviderName, number | Error>>;
-export declare function getSandboxQuotas(): Promise<SandboxQuotaResult>;
-/**
- * List every alive sandbox owned by this fleet, across all configured
- * providers — the orphan-reconciler SoT. Providers without `listOwned`
- * or missing env are skipped. Errors propagate per-provider so one flaky
- * provider doesn't silence the rest.
- */
-export type OwnedSandboxResult = Partial<Record<SandboxProviderName, OwnedSandbox[] | Error>>;
-export declare function listOwnedSandboxes(): Promise<OwnedSandboxResult>;
-/** Kill a sandbox by provider + native ID. Used by the orphan reconciler. */
-export declare function killSandboxById(provider: SandboxProviderName, sandboxId: string): Promise<void>;
-/** Kill all sandboxes across all registered providers. Call at startup to clean up after crashes. */
-export declare function killAllSandboxes(onError?: (provider: SandboxProviderName, err: unknown) => void): Promise<void>;
-export { SANDBOX_PROVIDERS };
+export type { SandboxNetworkHeaderTransform, SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxNetworkPolicy, } from "./sandbox/network-policy.js";
+export { DOT_SEGMENT_PATH_RE2, toVercelNetworkPolicy, toE2bNetwork } from "./sandbox/network-policy.js";
+export type { SandboxSize } from "./sandbox/sizes.js";
+export { SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES, isE2bSupportedSize, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate, isPlatformE2bTemplateAlias, } from "./sandbox/sizes.js";
+export { E2B_DEVBOX_TEMPLATE, E2B_DEVBOX_SPEC, E2B_DEVBOX_RECIPE_VERSION, e2bDevboxTemplateRef, } from "./sandbox/devbox.js";
+export { AGENT_COMPOSE_TAG } from "./sandbox/provider-def.js";
+export type { SandboxCreateOpts, OwnedSandbox } from "./sandbox/provider-def.js";
+export { parseSseExecStream } from "./sandbox/exec-stream.js";
+export type { ParseSseExecStreamOptions } from "./sandbox/exec-stream.js";
+export { makeSandboxProvider } from "./sandbox/providers/e2b.js";
+export { makeDesktopSandboxProvider } from "./sandbox/providers/desktop.js";
+export { VERCEL_MAX_TAGS, buildVercelTags } from "./sandbox/providers/vercel.js";
+export { makeLocalSandboxProvider } from "./sandbox/providers/local.js";
+export { SANDBOX_PROVIDERS, createSandbox, reconnectSandbox, deleteSandboxSnapshot, snapshotResolves, getSandboxQuotas, listOwnedSandboxes, killSandboxById, killAllSandboxes, } from "./sandbox/registry.js";
+export type { SandboxProviderName, SandboxQuotaResult, OwnedSandboxResult } from "./sandbox/registry.js";

package/dist/step-invocation/__tests__/foreground-recovery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/step-invocation/invoker.d.ts

@@ -75,6 +75,11 @@ export interface InvokeStepOptions {
         runnerPid: number;
         resultToken: string;
     }) => void;
+    /** Ceiling on the durable-result recovery poll after a live-stream fault
+     *  (default 45m — the wedged-runner backstop). The activity passes its step
+     *  ceiling so a stream fault on a step with hours of legitimate work left
+     *  recovers instead of timing out; startToClose is the real wall. */
+    recoveryDeadlineMs?: number;
 }
 /** A step running as a background command (ADR-0028). The activity races its
  *  `wait()` against a server pause request; on a pause it freezes the VM
@@ -114,4 +119,9 @@ export declare function reconnectStep<TOutput = unknown>(sandbox: SandboxProvide
     stepIndex: number;
 }, opts?: Pick<InvokeStepOptions, "onStdout" | "onStderr"> & {
     signal?: AbortSignal;
+    /** Ceiling on the durable-result poll (default 45m — the wedged-runner
+     *  backstop). A worker-death recovery reconnecting MID-step passes the
+     *  step ceiling instead: hours of legitimate work may remain, and the
+     *  activity's per-attempt startToClose already bounds it server-side. */
+    pollDeadlineMs?: number;
 }): Promise<RunningStep<TOutput>>;

package/dist/step-invocation/protocol.d.ts

@@ -60,6 +60,11 @@ export declare function requestContextPath(stepIndex: number): string;
  *  drop the tail of a heavy stdout stream — the invoker falls back to
  *  reading this file when no sentinel is found on stdout. */
 export declare function stepResultFilePath(token: string): string;
+/** Sandbox-side pidfile the FOREGROUND launch writes (`echo $$ > …`) before
+ *  spawning the runner pipeline — the wrapping shell's pid. The recovery path
+ *  reads it back to probe `/proc/<pid>` liveness when the live stream/wait
+ *  call dies mid-step (providers with no background-process pid — Vercel). */
+export declare function stepPidFilePath(token: string): string;
 /** Sandbox-side path where the runner's stdout is tee'd as a durable LOG file,
  *  keyed by the per-invocation token. The live output rides E2B's connect-web
  *  command stream, which THROWS on a compressed large frame (gRPC-web cannot

package/dist/types/api-compliance.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Break-glass compliance session wire types (ADR-0051).
+ *
+ * A team admin has no default access to a scoped (Private/Shared) document.
+ * To view one they don't hold a grant on, they open a READ-ONLY,
+ * owner-approved, time-boxed compliance session over a scope (one factory, or
+ * the whole team). These are the shapes the server's `/api/v1/compliance/*`
+ * routes emit — `client.ts` is a thin typed wrapper over them.
+ */
+export type ComplianceScopeKind = "factory" | "team";
+export type ComplianceStatus = "pending" | "active" | "expired" | "revoked";
+/** One break-glass compliance session. `expiresAt` is null while pending —
+ *  the TTL clock starts at approval, not request. */
+export interface ComplianceSession {
+    id: string;
+    teamId: string;
+    requestedByUserId: string | null;
+    requestedByLabel: string | null;
+    approvedByUserId: string | null;
+    approvedByLabel: string | null;
+    reason: string;
+    scopeKind: ComplianceScopeKind;
+    /** The factory this session covers (factory scope); null for team scope. */
+    scopeRef: string | null;
+    status: ComplianceStatus;
+    ttlSeconds: number;
+    expiresAt: string | null;
+    revokedByUserId: string | null;
+    revokedByLabel: string | null;
+    createdAt: string;
+    approvedAt: string | null;
+    revokedAt: string | null;
+}
+/** One per-document access recorded under an active session — the individual
+ *  audit trail the session's reasoned entry authorizes. */
+export interface ComplianceAccess {
+    id: string;
+    sessionId: string;
+    /** Nulled when the accessed file is later deleted (ON DELETE SET NULL);
+     *  `filePath` is the durable snapshot that survives. */
+    fileId: string | null;
+    filePath: string;
+    accessedByUserId: string | null;
+    accessedByLabel: string | null;
+    accessedAt: string;
+}
+export interface RequestComplianceSessionInput {
+    scopeKind: ComplianceScopeKind;
+    /** Required for factory scope; must be omitted for team scope. */
+    scopeRef?: string | null;
+    reason: string;
+    /** Session lifetime once approved — 15 min floor, 7 day ceiling. */
+    ttlSeconds: number;
+}
+export interface ListComplianceSessionsOptions {
+    status?: ComplianceStatus;
+    limit?: number;
+    cursor?: string;
+}
+export interface ComplianceSessionsPage {
+    sessions: ComplianceSession[];
+    nextCursor: string | null;
+}
+export interface ListComplianceAccessesOptions {
+    limit?: number;
+    cursor?: string;
+}
+export interface ComplianceAccessesPage {
+    accesses: ComplianceAccess[];
+    nextCursor: string | null;
+}