paperclip/doc/plugins/SANDBOX_PROVIDER_CAPABILITIES.md

Sandbox provider capability contract

A sandbox provider plugin declares an environment driver with kind: "sandbox_provider". Each driver can declare a set of optional sandbox capabilities. This document is the contract for a third-party provider author. It states what to declare, which worker methods each capability needs, what an omitted key means, and when the host narrows or denies a capability.

Read Sandbox file-sync lifecycle hooks for the native file-transfer hooks. Read the driver declaration shape in the plugin specification.

How the host resolves an effective capability

The host never trusts a declaration alone. For every run it resolves each capability as the intersection of three inputs:

effective = verified ∩ declared ∩ narrowing

• verified — the methods the live worker advertised in InitializeResult.supportedMethods. The host maps each capability to the worker methods it needs (see the table below). A capability is verified only when the worker advertises every required method. An empty or missing method list verifies nothing, so every capability resolves false.
• declared — the values in the driver declaration. A declared key is optional (see the next section).
• narrowing — a per-run restriction from the lease policy or the resolved provider config. A narrowing can only remove a capability, never add one.

A capability is effective only when all three allow it. A declaration therefore never grants a capability that the worker did not verify.

The declaration is optional and partial

Declare capabilities through the nested sandboxCapabilities object on the driver declaration:

environmentDrivers: [
  {
    driverKey: "my-provider",
    kind: "sandbox_provider",
    displayName: "My Provider",
    configSchema: { type: "object", properties: {} },
    sandboxCapabilities: {
      reusableLeases: true,
      nativeSyncIn: true,
      nativeSyncOut: true,
      persistentProcessSessions: false,
      independentControlCommands: false,
      incrementalSessionOutput: false,
    },
  },
]

Every key is optional. For a valid, identified provider each key has one of three states:

• Omitted — the host defers to verified worker discovery. The capability is effective when the worker advertises the required methods and no narrowing removes it. Omission is the correct default for a provider that follows the standard method contract. reusableLeases and incrementalSessionOutput are the two exceptions: an omitted key never grants either capability. Both are opt-in (see the next two sections).
• false — the host narrows the capability to off. The capability is never effective, even when the worker advertises the required methods.
• true — the host still requires the verified prerequisites. A true value never grants a capability without them. It documents intent and lets the host present the capability, but the worker must still advertise the required methods.

Reusable leases need an explicit opt-in

Reusable leases are the exception to the omission rule above. The host grants reusable-lease acquisition only when the declaration sets reusableLeases to true. The provider opts in through one of two fields:

• the nested sandboxCapabilities.reusableLeases: true, or
• the legacy supportsReusableLeases: true.

An omitted key leaves reusableLeases unset. An unset key does not make the provider eligible for reusable-lease acquisition, and it does not advertise provider-level reusable support. The host then always creates an ephemeral lease.

The opt-in never removes the other prerequisites. The worker must still verify all three lifecycle methods, environmentResumeLease, environmentReleaseLease, and environmentDestroyLease, and per-run narrowing still applies.

The two opt-in fields have a fixed precedence. The host keeps the legacy supportsReusableLeases field for backward compatibility, and it folds the field into sandboxCapabilities.reusableLeases.

• When only supportsReusableLeases is present, the host reads it as reusableLeases.
• When both supportsReusableLeases and sandboxCapabilities.reusableLeases are present, the nested value wins.

A manifest with legacy true and nested false therefore resolves to false. Prefer the nested sandboxCapabilities.reusableLeases in a new manifest.

Incremental session output needs an explicit opt-in

Incremental session output is the second exception to the omission rule. The host selects the session-output streaming path only when the declaration sets incrementalSessionOutput to true. An omitted key resolves the capability to false, so the host keeps the output-file poll path.

The reason is that this key is a behavioral guarantee, not a worker-method property. A generic one-shot provider can keep persistent process sessions and run independent control commands, yet it never emits incremental stdout and stderr from a live session. The two broad capabilities do not imply incremental output, so the host requires the provider to declare the behavior. A provider that streams incremental session output declares sandboxCapabilities.incrementalSessionOutput: true; every other provider omits the key and keeps the poll path.

The opt-in never removes the prerequisites. The worker must still verify environmentExecute, and per-run narrowing still applies. A config-resolution failure narrows the capability to off (see Failure behavior).

The capabilities and their worker-method prerequisites

Capability	Required worker methods	Meaning
reusableLeases	environmentResumeLease, environmentReleaseLease, and environmentDestroyLease	The host retains a provider lease and resumes it across runs.
nativeSyncIn	environmentSyncIn	The host transfers files into the sandbox through the native inbound hook.
nativeSyncOut	environmentSyncOut	The host transfers files out of the sandbox through the native outbound hook.
persistentProcessSessions	environmentExecute	The provider keeps a persistent process session open across commands.
independentControlCommands	environmentExecute	The provider runs a one-shot control command beside a long-lived command.
incrementalSessionOutput	environmentExecute	The provider streams incremental stdout and stderr from a live session. Opt-in: an omitted key resolves false.

Reusable leases need all three lifecycle methods. The host resumes a lease with environmentResumeLease, ends it with environmentReleaseLease, and tears down a stale lease with environmentDestroyLease. The reuse path destroys a stale lease when a resume fails, so a provider that cannot destroy a lease would strand it. A worker that omits any of the three methods never gets reusable leases, even with a positive declaration. The host then always creates an ephemeral lease.

The host advertises and consumes the two native sync methods as a pair. Define both or neither. See Sandbox file-sync lifecycle hooks.

Target and config narrowing

A narrowing removes a capability that the provider verified and declared but that this run cannot use.

• Ephemeral lease policy. A lease that the host does not retain never reuses. The host narrows reusableLeases to off for an ephemeral lease and keeps it on only for a reuse-by-environment lease.
• Kubernetes Job backend. A Job-backed lease, or a lease the host marked as unable to run native file sync, disables native sync. The host narrows nativeSyncIn and nativeSyncOut to off and keeps the base64-over-exec fallback.

Failure behavior

The host fails closed on two failure states. It never grants a capability from an unknown state.

• Config-resolution failure. A provider whose config the host cannot resolve is untrusted. The host narrows persistentProcessSessions and incrementalSessionOutput to off instead of allowing either through an empty config.
• Exact-plugin identity failure. A retained lease pins the exact plugin that acquired it. When that plugin is absent, or when it no longer declares this provider key with the sandbox_provider kind, the host cannot establish the declaration. It resolves every effective capability to false, no matter what methods a stale worker still advertises. An omitted sandboxCapabilities object on a valid, identified plugin is a different state; the host defers to verified discovery for that case.

Concurrency capabilities are not part of the contract

Earlier drafts listed two concurrency keys, concurrentSyncAndExec and concurrentSyncOperations. The runtime never exposed a scheduling choice that read either key, so a declaration had no effect. The host removed both keys. The strict capability validator now rejects them as unknown keys. The host can reintroduce a concurrency capability when a runtime path enforces it.