zeitlich 0.2.41 → 0.2.42

package/src/lib/sandbox/index.ts

@@ -4,6 +4,7 @@ export { toTree } from "./tree";
 export type {
   Sandbox,
   SandboxCapabilities,
+  SandboxCapability,
   SandboxCreateOptions,
   SandboxFileSystem,
   SandboxOps,

package/src/lib/sandbox/manager.ts

@@ -1,11 +1,34 @@
 import type {
   Sandbox,
+  SandboxCapability,
   SandboxCreateOptions,
   SandboxOps,
   PrefixedSandboxOps,
   SandboxProvider,
   SandboxSnapshot,
 } from "./types";
+import { SandboxNotSupportedError } from "./types";
+
+/**
+ * Method names the manager treats as capability-gated, mirroring the
+ * conditional fields on {@link SandboxProvider}. The full list is used
+ * by the constructor-time consistency check below to assert that, for
+ * each gated method present on the provider at runtime, the matching
+ * capability is also declared in `supportedCapabilities` (and vice
+ * versa). This is the runtime half of the type↔runtime alignment guard
+ * the type-level constraint can't enforce on its own.
+ */
+const CAP_METHOD_TO_CAPABILITY: ReadonlyArray<{
+  method: string;
+  capability: SandboxCapability;
+}> = [
+  { method: "pause", capability: "pause" },
+  { method: "resume", capability: "resume" },
+  { method: "snapshot", capability: "snapshot" },
+  { method: "deleteSnapshot", capability: "snapshot" },
+  { method: "restore", capability: "restore" },
+  { method: "fork", capability: "fork" },
+];
 
 /**
  * Result returned by {@link SandboxManagerHooks.onPreCreate}.
@@ -61,8 +84,16 @@ export interface SandboxManagerHooks<
 /**
  * Stateless facade over a {@link SandboxProvider}.
  *
- * Delegates all lifecycle operations to the provider, which is responsible
- * for its own instance management strategy (e.g. in-memory map, remote API).
+ * Generic over the same capability set (`TCaps`) as the underlying
+ * provider. The manager's lifecycle methods are always present on the
+ * class (so existing call sites compile unchanged), but
+ * {@link SandboxManager.createActivities} is capability-gated: only
+ * activities whose capability the provider declares via
+ * {@link SandboxProvider.supportedCapabilities} are wrapped, and the
+ * returned object's type omits absent ones.
+ *
+ * The default `TCaps = SandboxCapability` keeps the full method surface
+ * for existing usages that only pass `TOptions` / `TSandbox` / `TId`.
  *
  * Optional {@link SandboxManagerHooks} can be passed at construction time.
  * The `onPreCreate` hook runs inside the `createSandbox` activity, receiving
@@ -105,16 +136,62 @@ export class SandboxManager<
   TSandbox extends Sandbox = Sandbox,
   TId extends string = string,
   TCtx = unknown,
+  TCaps extends SandboxCapability = SandboxCapability,
 > {
   private hooks: SandboxManagerHooks<TOptions, TCtx>;
 
   constructor(
-    private provider: SandboxProvider<TOptions, TSandbox> & {
+    private provider: SandboxProvider<TOptions, TSandbox, TCaps> & {
       readonly id: TId;
     },
     options?: { hooks?: SandboxManagerHooks<TOptions, TCtx> }
   ) {
     this.hooks = options?.hooks ?? {};
+    this.assertCapabilityRuntimeConsistency();
+  }
+
+  /**
+   * Verifies that the provider's runtime `supportedCapabilities` set is
+   * consistent with the gated methods physically present on the provider.
+   *
+   * Belt-and-suspenders complement to the type-level
+   * `ReadonlySet<TCaps & SandboxCapability>` constraint: TypeScript can
+   * prevent the runtime set from containing capabilities not declared in
+   * `TCaps`, but it cannot detect a provider that **declares** a cap in
+   * `TCaps` and forgets to include it in the runtime set (or that ships
+   * a method without listing its cap). Both shapes silently break
+   * activity registration, so we trip a loud failure at construction
+   * time instead.
+   *
+   * Adapters that derive both surfaces from a single `as const`
+   * capability array (the recommended pattern) pass this check by
+   * construction.
+   */
+  private assertCapabilityRuntimeConsistency(): void {
+    const supported = this.provider
+      .supportedCapabilities as ReadonlySet<SandboxCapability>;
+    for (const { method, capability } of CAP_METHOD_TO_CAPABILITY) {
+      const hasMethod =
+        typeof (this.provider as unknown as Record<string, unknown>)[method] ===
+        "function";
+      const declaresCap = supported.has(capability);
+      if (hasMethod && !declaresCap) {
+        throw new Error(
+          `Sandbox provider "${this.provider.id}" implements ${method}() but ` +
+            `does not list "${capability}" in supportedCapabilities. ` +
+            `Add the capability to the provider's runtime set so activities ` +
+            `for it can be registered.`
+        );
+      }
+      if (declaresCap && !hasMethod) {
+        throw new Error(
+          `Sandbox provider "${this.provider.id}" lists "${capability}" in ` +
+            `supportedCapabilities but does not implement ${method}(). ` +
+            `Either add the method to the provider or remove the capability ` +
+            `from supportedCapabilities.`
+        );
+      }
+    }
   }
 
   async create(
@@ -165,35 +242,84 @@ export class SandboxManager<
     await this.provider.destroy(id);
   }
 
+  /**
+   * Capability-gated lifecycle methods on the underlying provider.
+   *
+   * These manager methods always exist at runtime; calling one whose
+   * capability is absent from the provider's `supportedCapabilities`
+   * throws an error. The activities returned from
+   * {@link SandboxManager.createActivities} are gated at the type level
+   * via `TCaps`, which is where compile-time safety is enforced.
+   */
   async pause(id: string, ttlSeconds?: number): Promise<void> {
-    await this.provider.pause(id, ttlSeconds);
+    const fn = this.providerMethod("pause") as
+      | ((id: string, ttlSeconds?: number) => Promise<void>)
+      | undefined;
+    if (!fn) throw this.unsupported("pause");
+    await fn.call(this.provider, id, ttlSeconds);
   }
 
   async resume(id: string): Promise<void> {
-    await this.provider.resume(id);
+    const fn = this.providerMethod("resume") as
+      | ((id: string) => Promise<void>)
+      | undefined;
+    if (!fn) throw this.unsupported("resume");
+    await fn.call(this.provider, id);
   }
 
   async snapshot(id: string, options?: TOptions): Promise<SandboxSnapshot> {
-    return this.provider.snapshot(id, options);
+    const fn = this.providerMethod("snapshot") as
+      | ((id: string, options?: TOptions) => Promise<SandboxSnapshot>)
+      | undefined;
+    if (!fn) throw this.unsupported("snapshot");
+    return fn.call(this.provider, id, options);
   }
 
   async restore(
     snapshot: SandboxSnapshot,
     options?: TOptions
   ): Promise<string> {
-    const sandbox = await this.provider.restore(snapshot, options);
+    const fn = this.providerMethod("restore") as
+      | ((snap: SandboxSnapshot, options?: TOptions) => Promise<TSandbox>)
+      | undefined;
+    if (!fn) throw this.unsupported("restore");
+    const sandbox = await fn.call(this.provider, snapshot, options);
     return sandbox.id;
   }
 
   async deleteSnapshot(snapshot: SandboxSnapshot): Promise<void> {
-    await this.provider.deleteSnapshot(snapshot);
+    const fn = this.providerMethod("deleteSnapshot") as
+      | ((snap: SandboxSnapshot) => Promise<void>)
+      | undefined;
+    if (!fn) throw this.unsupported("deleteSnapshot");
+    await fn.call(this.provider, snapshot);
   }
 
   async fork(sandboxId: string, options?: TOptions): Promise<string> {
-    const sandbox = await this.provider.fork(sandboxId, options);
+    const fn = this.providerMethod("fork") as
+      | ((id: string, options?: TOptions) => Promise<TSandbox>)
+      | undefined;
+    if (!fn) throw this.unsupported("fork");
+    const sandbox = await fn.call(this.provider, sandboxId, options);
     return sandbox.id;
   }
 
+  private providerMethod(name: string): unknown {
+    const value = (this.provider as unknown as Record<string, unknown>)[name];
+    return typeof value === "function" ? value : undefined;
+  }
+
+  /**
+   * Constructs the structured error thrown when an unsupported lifecycle
+   * method is invoked through the manager. Uses the public
+   * {@link SandboxNotSupportedError} symbol so consumers that catch on
+   * `instanceof SandboxNotSupportedError` (the documented compatibility
+   * path) keep matching after the refactor.
+   */
+  private unsupported(name: string): SandboxNotSupportedError {
+    return new SandboxNotSupportedError(name);
+  }
+
   /**
    * Returns Temporal activity functions with prefixed names.
    *
@@ -201,6 +327,11 @@ export class SandboxManager<
    * to pass the workflow/scope name. Use the matching `proxy*SandboxOps()`
    * helper from the adapter's `/workflow` entrypoint on the workflow side.
    *
+   * Activities are only registered for capabilities the provider declares
+   * via {@link SandboxProvider.supportedCapabilities}: methods omitted
+   * from the cap set are not wrapped, and the returned object's type
+   * omits the corresponding keys.
+   *
    * @param scope - Workflow name (appended to the provider id)
    *
    * @example
@@ -211,14 +342,25 @@ export class SandboxManager<
    *
    * const dmgr = new SandboxManager(new DaytonaSandboxProvider(config));
    * dmgr.createActivities("CodingAgent");
-   * // registers: daytonaCodingAgentCreateSandbox, …
+   * // registers: daytonaCodingAgentCreateSandbox, daytonaCodingAgentDestroySandbox
+   * // (snapshot/restore/fork/pause/resume omitted — Daytona doesn't declare them)
    * ```
    */
   createActivities<S extends string>(
     scope: S
-  ): PrefixedSandboxOps<`${TId}${Capitalize<S>}`, TOptions, TCtx> {
+  ): PrefixedSandboxOps<`${TId}${Capitalize<S>}`, TOptions, TCtx, TCaps> {
     const prefix = `${this.provider.id}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`;
-    const ops: SandboxOps<TOptions, TCtx> = {
+    const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
+    // The set is statically typed against the (possibly narrow) `TCaps`,
+    // but we need to probe every well-known capability here. Widen for
+    // the duration of the lookup; the constructor-time consistency check
+    // already ensures these probes can't accidentally observe a method
+    // present on the provider that's missing from the declared set.
+    const supported = this.provider
+      .supportedCapabilities as ReadonlySet<SandboxCapability>;
+
+    type WideOps = SandboxOps<TOptions, TCtx>;
+    const ops: Partial<WideOps> = {
       createSandbox: async (
         options?: TOptions,
         ctx?: TCtx
@@ -228,42 +370,56 @@ export class SandboxManager<
       destroySandbox: async (sandboxId: string): Promise<void> => {
         await this.destroy(sandboxId);
       },
-      pauseSandbox: async (
+    };
+
+    if (supported.has("pause")) {
+      ops.pauseSandbox = async (
         sandboxId: string,
         ttlSeconds?: number
       ): Promise<void> => {
         await this.pause(sandboxId, ttlSeconds);
-      },
-      resumeSandbox: async (sandboxId: string): Promise<void> => {
+      };
+    }
+    if (supported.has("resume")) {
+      ops.resumeSandbox = async (sandboxId: string): Promise<void> => {
         await this.resume(sandboxId);
-      },
-      snapshotSandbox: async (
+      };
+    }
+    if (supported.has("snapshot")) {
+      ops.snapshotSandbox = async (
         sandboxId: string,
         options?: TOptions
       ): Promise<SandboxSnapshot> => {
         return this.snapshot(sandboxId, options);
-      },
-      restoreSandbox: async (
+      };
+      ops.deleteSandboxSnapshot = async (
+        snapshot: SandboxSnapshot
+      ): Promise<void> => {
+        await this.deleteSnapshot(snapshot);
+      };
+    }
+    if (supported.has("restore")) {
+      ops.restoreSandbox = async (
         snapshot: SandboxSnapshot,
         options?: TOptions
       ): Promise<string> => {
         return this.restore(snapshot, options);
-      },
-      deleteSandboxSnapshot: async (
-        snapshot: SandboxSnapshot
-      ): Promise<void> => {
-        await this.deleteSnapshot(snapshot);
-      },
-      forkSandbox: async (
+      };
+    }
+    if (supported.has("fork")) {
+      ops.forkSandbox = async (
         sandboxId: string,
         options?: TOptions
       ): Promise<string> => {
         return this.fork(sandboxId, options);
-      },
-    };
-    const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
+      };
+    }
+
+    const entries = Object.entries(ops).filter(
+      ([, v]) => typeof v === "function"
+    );
     return Object.fromEntries(
-      Object.entries(ops).map(([k, v]) => [`${prefix}${cap(k)}`, v])
-    ) as PrefixedSandboxOps<`${TId}${Capitalize<S>}`, TOptions, TCtx>;
+      entries.map(([k, v]) => [`${prefix}${cap(k)}`, v])
+    ) as PrefixedSandboxOps<`${TId}${Capitalize<S>}`, TOptions, TCtx, TCaps>;
   }
 }

package/src/lib/sandbox/types.ts

@@ -84,6 +84,14 @@ export interface ExecResult {
 // Capabilities
 // ============================================================================
 
+/**
+ * Runtime capability flags carried by a {@link Sandbox} instance.
+ *
+ * These are an orthogonal mechanism to the type-level
+ * {@link SandboxCapability} union: this flag bag is for runtime
+ * introspection ("does the sandbox support a filesystem?") whereas
+ * {@link SandboxCapability} narrows the type-level provider/ops contract.
+ */
 export interface SandboxCapabilities {
   /** Sandbox supports filesystem operations */
   filesystem: boolean;
@@ -93,6 +101,24 @@ export interface SandboxCapabilities {
   persistence: boolean;
 }
 
+/**
+ * Type-level capability vocabulary for {@link SandboxProvider} and
+ * {@link SandboxOps}. Adapters declare the subset they actually support; the
+ * conditional types on each contract gate the corresponding methods so
+ * unsupported calls become a compile-time error rather than a runtime
+ * {@link SandboxNotSupportedError}.
+ *
+ * `pause` and `resume` are split because some adapters might support one
+ * direction without the other. The `snapshot` cap covers both `snapshot()`
+ * and `deleteSnapshot()` since they always travel together in practice.
+ */
+export type SandboxCapability =
+  | "pause"
+  | "resume"
+  | "snapshot"
+  | "restore"
+  | "fork";
+
 // ============================================================================
 // Sandbox
 // ============================================================================
@@ -145,88 +171,196 @@ export interface SandboxCreateResult {
   sandbox: Sandbox;
 }
 
-export interface SandboxProvider<
-  TOptions extends SandboxCreateOptions = SandboxCreateOptions,
-  TSandbox extends Sandbox = Sandbox,
+/**
+ * Internal helper: drop keys whose value is `never` from an object type.
+ *
+ * Used by the capability-gated contracts below so that an absent capability
+ * removes the corresponding key entirely, instead of leaving a required
+ * field with type `never` (which would make implementations impossible).
+ */
+type OmitNever<T> = {
+  [K in keyof T as [T[K]] extends [never] ? never : K]: T[K];
+};
+
+/**
+ * Capability-gated provider lifecycle methods.
+ *
+ * Each field becomes `never` when its capability is absent from `TCaps`;
+ * the wrapping `OmitNever` removes those keys entirely, so the method
+ * isn't part of the type surface for adapters that don't support it.
+ */
+type SandboxProviderCapMethods<
+  TOptions extends SandboxCreateOptions,
+  TSandbox extends Sandbox,
+  TCaps extends SandboxCapability,
+> = OmitNever<{
+  pause: "pause" extends TCaps
+    ? (sandboxId: string, ttlSeconds?: number) => Promise<void>
+    : never;
+  resume: "resume" extends TCaps ? (sandboxId: string) => Promise<void> : never;
+  snapshot: "snapshot" extends TCaps
+    ? (sandboxId: string, options?: TOptions) => Promise<SandboxSnapshot>
+    : never;
+  deleteSnapshot: "snapshot" extends TCaps
+    ? (snapshot: SandboxSnapshot) => Promise<void>
+    : never;
+  restore: "restore" extends TCaps
+    ? (snapshot: SandboxSnapshot, options?: TOptions) => Promise<TSandbox>
+    : never;
+  fork: "fork" extends TCaps
+    ? (sandboxId: string, options?: TOptions) => Promise<TSandbox>
+    : never;
+}>;
+
+/**
+ * Always-present provider lifecycle methods. These do not depend on the
+ * capability set and are required by every adapter.
+ */
+interface SandboxProviderBase<
+  TOptions extends SandboxCreateOptions,
+  TSandbox extends Sandbox,
+  TCaps extends SandboxCapability,
 > {
   readonly id: string;
   readonly capabilities: SandboxCapabilities;
+  /**
+   * Runtime-introspectable list of supported capabilities.
+   *
+   * Constrained to `ReadonlySet<TCaps & SandboxCapability>` so the runtime
+   * set cannot include capabilities not declared at the type level — a
+   * provider typed as `SandboxProvider<…, never>` cannot ship a runtime
+   * set that contains `"pause"`, etc.
+   *
+   * The other direction (type declares a cap, runtime set omits it)
+   * cannot be enforced by TypeScript alone; adapters should derive both
+   * `TCaps` and the runtime set from the same `as const` array (see
+   * `SandboxManager`'s constructor-time consistency check) so the two
+   * surfaces cannot drift.
+   */
+  readonly supportedCapabilities: ReadonlySet<TCaps & SandboxCapability>;
 
   create(options?: TOptions): Promise<SandboxCreateResult>;
   get(sandboxId: string): Promise<TSandbox>;
   destroy(sandboxId: string): Promise<void>;
-  pause(sandboxId: string, ttlSeconds?: number): Promise<void>;
-  /** Resume a paused sandbox. No-op if already running. */
-  resume(sandboxId: string): Promise<void>;
-  /**
-   * Capture a snapshot of a running sandbox. `options` is a per-call override
-   * merged on top of the provider's static defaults.
-   */
-  snapshot(sandboxId: string, options?: TOptions): Promise<SandboxSnapshot>;
-  /**
-   * Restore a sandbox from a snapshot. `options` is a per-call override
-   * merged on top of the provider's static defaults.
-   */
-  restore(snapshot: SandboxSnapshot, options?: TOptions): Promise<Sandbox>;
-  /** Delete a previously captured snapshot. No-op if already deleted. */
-  deleteSnapshot(snapshot: SandboxSnapshot): Promise<void>;
-  /**
-   * Fork a running sandbox into a new one. `options` is a per-call override
-   * merged on top of the provider's static defaults.
-   */
-  fork(sandboxId: string, options?: TOptions): Promise<Sandbox>;
 }
 
+/**
+ * Provider-side sandbox lifecycle contract.
+ *
+ * Generic over an optional capability set (`TCaps`). Each capability gates
+ * a specific method: when the cap is absent the corresponding key is
+ * **removed** from the type entirely, so calling it produces a TypeScript
+ * error at the call site instead of a runtime
+ * {@link SandboxNotSupportedError}.
+ *
+ * The default `TCaps = SandboxCapability` resolves to the full union, so
+ * existing usages that only pass `TOptions` / `TSandbox` continue to see
+ * the full method surface (backwards compatible).
+ *
+ * Adapters that don't support a method should narrow `TCaps` accordingly:
+ *
+ * - In-memory / E2B: `SandboxCapability` (default — all caps present).
+ * - Bedrock Code Interpreter / Daytona: `never` (only base ops).
+ * - Bedrock AgentCore Runtime: `"pause" | "resume"`.
+ */
+export type SandboxProvider<
+  TOptions extends SandboxCreateOptions = SandboxCreateOptions,
+  TSandbox extends Sandbox = Sandbox,
+  TCaps extends SandboxCapability = SandboxCapability,
+> = SandboxProviderBase<TOptions, TSandbox, TCaps> &
+  SandboxProviderCapMethods<TOptions, TSandbox, TCaps>;
+
 // ============================================================================
 // SandboxOps — workflow-side activity interface (like ThreadOps)
 // ============================================================================
 
-export interface SandboxOps<
-  TOptions extends SandboxCreateOptions = SandboxCreateOptions,
-  TCtx = unknown,
+/**
+ * Capability-gated workflow-side methods. Mirrors the provider's gating:
+ * keys whose capability is absent from `TCaps` are removed from the type.
+ */
+type SandboxOpsCapMethods<
+  TOptions extends SandboxCreateOptions,
+  TCaps extends SandboxCapability,
+> = OmitNever<{
+  pauseSandbox: "pause" extends TCaps
+    ? (sandboxId: string) => Promise<void>
+    : never;
+  resumeSandbox: "resume" extends TCaps
+    ? (sandboxId: string) => Promise<void>
+    : never;
+  snapshotSandbox: "snapshot" extends TCaps
+    ? (sandboxId: string, options?: TOptions) => Promise<SandboxSnapshot>
+    : never;
+  deleteSandboxSnapshot: "snapshot" extends TCaps
+    ? (snapshot: SandboxSnapshot) => Promise<void>
+    : never;
+  restoreSandbox: "restore" extends TCaps
+    ? (snapshot: SandboxSnapshot, options?: TOptions) => Promise<string>
+    : never;
+  forkSandbox: "fork" extends TCaps
+    ? (sandboxId: string, options?: TOptions) => Promise<string>
+    : never;
+}>;
+
+/**
+ * Always-present workflow-side lifecycle methods.
+ */
+interface SandboxOpsBase<
+  TOptions extends SandboxCreateOptions,
+  TCtx,
 > {
   createSandbox(
     options?: TOptions,
     ctx?: TCtx
   ): Promise<{ sandboxId: string } | null>;
   destroySandbox(sandboxId: string): Promise<void>;
-  pauseSandbox(sandboxId: string): Promise<void>;
-  /** Resume a paused sandbox. No-op if already running. */
-  resumeSandbox(sandboxId: string): Promise<void>;
-  /** Capture a snapshot. `options` is a per-call override merged on top of provider defaults. */
-  snapshotSandbox(
-    sandboxId: string,
-    options?: TOptions
-  ): Promise<SandboxSnapshot>;
-  /** Create a fresh sandbox from a snapshot. `options` is a per-call override merged on top of provider defaults. */
-  restoreSandbox(
-    snapshot: SandboxSnapshot,
-    options?: TOptions
-  ): Promise<string>;
-  /** Delete a previously captured snapshot. No-op if already deleted. */
-  deleteSandboxSnapshot(snapshot: SandboxSnapshot): Promise<void>;
-  /** Fork a running sandbox. `options` is a per-call override merged on top of provider defaults. */
-  forkSandbox(sandboxId: string, options?: TOptions): Promise<string>;
 }
 
+/**
+ * Workflow-side counterpart to {@link SandboxProvider}. Exposed as a set of
+ * Temporal activities and consumed by `createSession`'s `sandboxOps` field
+ * and by `defineSubagent`'s `sandbox.proxy`.
+ *
+ * Generic over a capability set (`TCaps`) — same semantics as the provider:
+ * keys whose capability is absent are removed from the type, so calling
+ * them is a TypeScript error rather than a runtime throw. The default
+ * `TCaps = SandboxCapability` keeps the full method surface for existing
+ * consumers.
+ */
+export type SandboxOps<
+  TOptions extends SandboxCreateOptions = SandboxCreateOptions,
+  TCtx = unknown,
+  TCaps extends SandboxCapability = SandboxCapability,
+> = SandboxOpsBase<TOptions, TCtx> & SandboxOpsCapMethods<TOptions, TCaps>;
+
 /**
  * Maps generic {@link SandboxOps} method names to adapter-prefixed names.
  *
+ * Inherits the capability gating from {@link SandboxOps}: when `TCaps` omits
+ * a capability the prefixed key carries the `never` type so call sites are
+ * type-protected.
+ *
  * @example
  * ```typescript
  * type InMemOps = PrefixedSandboxOps<"inMemory">;
- * // → { inMemoryCreateSandbox, inMemoryDestroySandbox, inMemorySnapshotSandbox }
+ * // → { inMemoryCreateSandbox, inMemoryDestroySandbox, inMemorySnapshotSandbox, … }
  * ```
  */
 export type PrefixedSandboxOps<
   TPrefix extends string,
   TOptions extends SandboxCreateOptions = SandboxCreateOptions,
   TCtx = unknown,
+  TCaps extends SandboxCapability = SandboxCapability,
 > = {
   [K in keyof SandboxOps<
     TOptions,
-    TCtx
-  > as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions, TCtx>[K];
+    TCtx,
+    TCaps
+  > as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<
+    TOptions,
+    TCtx,
+    TCaps
+  >[K];
 };
 
 // ============================================================================
@@ -235,6 +369,15 @@ export type PrefixedSandboxOps<
 
 import { ApplicationFailure } from "@temporalio/common";
 
+/**
+ * Thrown by adapters that still surface an unsupported method at runtime.
+ *
+ * After the capability-generic refactor most adapters drop their
+ * unsupported methods entirely so the type system rejects them at call
+ * sites. This symbol is still exported so consumers running against older
+ * adapter versions can keep their backwards-compatible error-handling
+ * paths until they finish migrating.
+ */
 export class SandboxNotSupportedError extends ApplicationFailure {
   constructor(operation: string) {
     super(

package/src/lib/session/index.ts

@@ -5,6 +5,7 @@ export type {
   PrefixedThreadOps,
   ScopedPrefix,
   SessionConfig,
+  SessionRequiredCaps,
   SessionResult,
   ZeitlichSession,
 } from "./types";