@xpert-ai/plugin-sdk 3.15.10 → 3.15.12

package/src/lib/managed-queue/index.d.ts

@@ -15,6 +15,15 @@ export type PluginJobProcessorMetadata = {
     jobName: string;
     concurrency?: number;
 };
+/** Physical worker pool chosen independently from a plugin's logical queue name. */
+export type ManagedQueueExecutionPool = 'default' | 'sandbox-browser';
+/** Readiness signal used to reject work before it is stranded in an unconsumed pool. */
+export type ManagedQueueExecutionPoolHealth = {
+    executionPool: ManagedQueueExecutionPool;
+    available: boolean;
+    workerCount: number;
+    warning?: string;
+};
 export type ManagedQueueRemoveOption = boolean | number | {
     age?: number;
     count?: number;
@@ -47,12 +56,15 @@ export type ManagedQueueEnqueueInput<TPayload = unknown> = {
     backoffMs?: ManagedQueueBackoffInput;
     removeOnComplete?: ManagedQueueRemoveOption;
     removeOnFail?: ManagedQueueRemoveOption;
+    /** Defaults to `default`; browser-heavy jobs must explicitly select the isolated pool. */
+    executionPool?: ManagedQueueExecutionPool;
 };
 export type ManagedQueueEnqueueResult = {
     jobId: string;
 };
 export type ManagedQueueCancelInput = {
     jobId: string;
+    executionPool?: ManagedQueueExecutionPool;
 };
 export type ManagedQueueCancelResult = {
     success: boolean;
@@ -100,7 +112,12 @@ export interface ManagedQueueService {
     cancel(input: ManagedQueueCancelInput): Promise<ManagedQueueCancelResult>;
     getJob<TPayload = unknown>(input: {
         jobId: string;
+        executionPool?: ManagedQueueExecutionPool;
     }): Promise<ManagedQueueJobSnapshot<TPayload> | null>;
+    /** Reports active BullMQ consumers for a physical execution pool. */
+    getExecutionPoolHealth(input: {
+        executionPool: ManagedQueueExecutionPool;
+    }): Promise<ManagedQueueExecutionPoolHealth>;
     getRedis(): Promise<ManagedQueueRedis>;
 }
 export declare function PluginJobProcessor(options: PluginJobProcessorOptions): ClassDecorator;

package/src/lib/runtime/capabilities/artifacts.d.ts

@@ -43,6 +43,10 @@ export type ArtifactVersionInput = {
 export type CreateArtifactVersionInput = ArtifactVersionInput & {
     artifactId: string;
 };
+/** Idempotently creates or reuses one immutable Artifact content version. */
+export type EnsureArtifactVersionInput = CreateArtifactVersionInput & {
+    idempotencyKey: string;
+};
 /** Access policy requested for an Artifact link. */
 export type ArtifactLinkAccessInput = {
     mode: ArtifactAccessMode;
@@ -66,6 +70,10 @@ export type CreateArtifactLinkInput = {
     presentation?: ArtifactLinkPresentationInput | null;
     metadata?: Record<string, unknown> | null;
 };
+/** Stable plugin-owned slot for one active durable share policy. */
+export type ArtifactShareInput = CreateArtifactLinkInput & {
+    shareKey: string;
+};
 /** Creates a short-lived signed preview link; never use this as a durable share URL. */
 export type CreateSignedArtifactPreviewLinkInput = Omit<CreateArtifactLinkInput, 'access'> & {
     ttlSeconds?: number | null;
@@ -76,6 +84,7 @@ export type ArtifactVersionRecord = {
     artifactId: string;
     versionNumber: number;
     status: ArtifactVersionStatus;
+    idempotencyKey?: string | null;
     sourceVersionId?: string | null;
     checksum?: string | null;
     mimeType: string;
@@ -84,6 +93,8 @@ export type ArtifactVersionRecord = {
     description?: string | null;
     size?: number | null;
     sha256?: string | null;
+    workspaceFileRef?: WorkspacePortableFileReference | null;
+    metadata?: Record<string, unknown> | null;
     createdAt?: string | Date;
 };
 /** Durable Artifact container returned to plugins. */
@@ -99,6 +110,7 @@ export type ArtifactRecord = ArtifactScopeInput & {
     description?: string | null;
     currentVersionId?: string | null;
     currentVersion?: ArtifactVersionRecord | null;
+    metadata?: Record<string, unknown> | null;
     createdAt?: string | Date;
     updatedAt?: string | Date;
 };
@@ -107,6 +119,7 @@ export type ArtifactLinkRecord = ArtifactScopeInput & {
     id: string;
     artifactId: string;
     artifactVersionId?: string | null;
+    shareKey?: string | null;
     versionMode: ArtifactLinkVersionMode;
     slug: string;
     publicUrl: string;
@@ -120,6 +133,7 @@ export type ArtifactLinkRecord = ArtifactScopeInput & {
     disposition: ArtifactLinkDisposition;
     allowDownload: boolean;
     safeHtmlProfile?: ArtifactSafeHtmlProfile | null;
+    metadata?: Record<string, unknown> | null;
     createdAt?: string | Date;
     updatedAt?: string | Date;
     artifact?: ArtifactRecord;
@@ -140,6 +154,27 @@ export type ListArtifactsResult = {
     page: number;
     pageSize: number;
 };
+export type FindArtifactBySourceInput = Pick<ArtifactSourceInput, 'pluginName' | 'resourceType' | 'resourceId'> & {
+    includeDeleted?: boolean | null;
+};
+export type ListArtifactVersionsInput = {
+    artifactId: string;
+    idempotencyKey?: string | null;
+    status?: ArtifactVersionStatus | 'all' | null;
+};
+export type EnsureArtifactVersionResult = {
+    version: ArtifactVersionRecord;
+    outcome: 'created' | 'reused';
+};
+export type ArtifactShareKeyInput = {
+    artifactId: string;
+    shareKey: string;
+};
+export type EnsureArtifactShareResult = {
+    link: ArtifactLinkRecord;
+    outcome: 'created' | 'reused' | 'replaced';
+    replacedLinkId?: string | null;
+};
 /** Mutable parts of an Artifact link; content versions remain immutable. */
 export type UpdateArtifactLinkAccessInput = {
     access?: ArtifactLinkAccessInput | null;
@@ -150,12 +185,18 @@ export type UpdateArtifactLinkAccessInput = {
 /** Platform runtime capability exposed to plugins for managing generated Artifacts. */
 export interface ArtifactsApi {
     createArtifact(input: CreateArtifactInput): Promise<ArtifactRecord>;
+    findArtifactBySource(input: FindArtifactBySourceInput): Promise<ArtifactRecord | null>;
     createArtifactVersion(input: CreateArtifactVersionInput): Promise<ArtifactVersionRecord>;
+    listArtifactVersions(input: ListArtifactVersionsInput): Promise<ArtifactVersionRecord[]>;
+    ensureArtifactVersion(input: EnsureArtifactVersionInput): Promise<EnsureArtifactVersionResult>;
     getArtifact(idOrSlug: string): Promise<ArtifactRecord>;
     listArtifacts(input?: ListArtifactsInput): Promise<ListArtifactsResult>;
     archiveArtifact(idOrSlug: string): Promise<ArtifactRecord>;
     deleteArtifact(idOrSlug: string): Promise<ArtifactRecord>;
     createArtifactLink(input: CreateArtifactLinkInput): Promise<ArtifactLinkRecord>;
+    getArtifactShare(input: ArtifactShareKeyInput): Promise<ArtifactLinkRecord | null>;
+    ensureArtifactShare(input: ArtifactShareInput): Promise<EnsureArtifactShareResult>;
+    revokeArtifactShare(input: ArtifactShareKeyInput): Promise<ArtifactLinkRecord | null>;
     createSignedPreviewLink(input: CreateSignedArtifactPreviewLinkInput): Promise<ArtifactLinkRecord>;
     updateArtifactLinkAccess(idOrSlug: string, patch: UpdateArtifactLinkAccessInput): Promise<ArtifactLinkRecord>;
     revokeArtifactLink(idOrSlug: string): Promise<ArtifactLinkRecord>;

package/src/lib/runtime/capabilities/index.d.ts

@@ -2,3 +2,4 @@ export * from './knowledgebase';
 export * from './knowledgebase-documents';
 export * from './artifacts';
 export * from './workspace-files';
+export * from './sandbox-jobs';

package/src/lib/runtime/capabilities/sandbox-jobs.d.ts

@@ -0,0 +1,142 @@
+import type { JSONValue } from '@xpert-ai/contracts';
+import type { WorkspaceFileScope, WorkspacePortableFileReference } from './workspace-files';
+/** Stable machine-readable failures emitted by the Sandbox Jobs capability. */
+export declare const SANDBOX_JOB_ERROR_CODES: readonly ["SANDBOX_ACTION_UNAVAILABLE", "SANDBOX_ACTION_INVALID", "SANDBOX_PROFILE_UNAVAILABLE", "SANDBOX_RUNTIME_UNAVAILABLE", "SANDBOX_VERSION_MISMATCH", "SANDBOX_CAPACITY_UNAVAILABLE", "SANDBOX_START_FAILED", "BROWSER_LAUNCH_FAILED", "EXPORT_TIMEOUT", "EXPORT_OOM", "EXPORT_INPUT_INVALID", "EXPORT_OUTPUT_INVALID", "SANDBOX_CANCELLED"];
+export type SandboxJobErrorCode = (typeof SANDBOX_JOB_ERROR_CODES)[number];
+/** Persisted lifecycle states for a generic isolated background execution. */
+export type SandboxJobStatus = 'waiting' | 'starting' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'lost';
+/** Portable Workspace Files input materialized under `/workspace/input`. */
+export type SandboxJobFileInput = {
+    /** Tenant-scoped portable reference; raw bytes never enter queue state. */
+    reference: WorkspacePortableFileReference;
+    /** Safe relative path below `/workspace/input`. */
+    targetPath: string;
+    /** Expected immutable byte length checked during materialization. */
+    size: number;
+    /** Expected lowercase SHA-256 checked during materialization. */
+    sha256: string;
+};
+/** Declares one output to validate and persist back into Workspace Files. */
+export type SandboxJobOutputRequest = {
+    path: string;
+    originalName: string;
+    mimeType: string;
+    destination: WorkspaceFileScope & {
+        folder: string;
+    };
+};
+/** Tenant and business ownership recorded for authorization, audit, and cleanup. */
+export type SandboxJobScope = {
+    tenantId: string;
+    organizationId?: string | null;
+    userId?: string | null;
+    pluginName: string;
+    businessResourceType: string;
+    businessResourceId: string;
+};
+/** Action-oriented request accepted from a plugin background handler. */
+export type SandboxJobRunInput = {
+    /** Optional caller-known UUID used when cancellation must be possible while run() is awaiting completion. */
+    jobId?: string;
+    action: string;
+    actionVersion: string;
+    /** Stable tenant-scoped key combining business identity and immutable input checksum. */
+    idempotencyKey: string;
+    scope: SandboxJobScope;
+    /** Small structured request; file bytes must be supplied through `files`. */
+    payload: JSONValue;
+    files?: SandboxJobFileInput[];
+    outputs: SandboxJobOutputRequest[];
+    /** Soft execution limit capped by the Runtime Definition's hard deadline. */
+    timeoutMs?: number;
+};
+/** Validated output evidence returned as a portable Workspace Files reference. */
+export type SandboxJobOutput = {
+    path: string;
+    originalName: string;
+    mimeType: string;
+    size: number;
+    sha256: string;
+    reference: WorkspacePortableFileReference;
+    fileUrl?: string;
+    workspacePath?: string;
+};
+/** Provider-neutral persisted view of a Sandbox Job and its runtime evidence. */
+export type SandboxJobSnapshot = {
+    id: string;
+    runtimeProfile: string;
+    sandboxRuntimeVersion: string;
+    action: string;
+    actionVersion: string;
+    status: SandboxJobStatus;
+    /** Attempt number; a new failed-job attempt may select a newly healthy Binding. */
+    attempt: number;
+    /** Provider and Binding are persisted so cleanup never depends on current selection. */
+    provider?: string | null;
+    runtimeBindingId?: string | null;
+    /** Opaque Provider identity used for reattachment and idempotent destruction. */
+    runtimeRef?: string | null;
+    artifactDigest?: string | null;
+    /** @deprecated Use runtimeRef. Kept for one compatibility cycle. */
+    containerRef?: string | null;
+    outputs: SandboxJobOutput[];
+    errorCode?: SandboxJobErrorCode | null;
+    errorMessage?: string | null;
+    createdAt?: Date | string | null;
+    startedAt?: Date | string | null;
+    finishedAt?: Date | string | null;
+};
+/** Successful `run()` result; failed executions reject with SandboxJobRuntimeError. */
+export type SandboxJobRunResult = SandboxJobSnapshot & {
+    status: 'succeeded';
+};
+/** Aggregated readiness of an Action, Runtime Definition, Worker, Binding, and Provider. */
+export type SandboxJobActionHealth = {
+    pluginName: string;
+    action: string;
+    actionVersion: string;
+    runtimeProfile?: string;
+    sandboxRuntimeVersion?: string;
+    provider?: string;
+    runtimeBindingId?: string;
+    artifactDigest?: string;
+    available: boolean;
+    reason?: 'ACTION_MISSING' | 'ACTION_INVALID' | 'PROFILE_MISSING' | 'VERSION_MISMATCH' | 'RUNTIME_UNBOUND' | 'PROVIDER_UNAVAILABLE' | 'PROFILE_UNHEALTHY';
+    message?: string;
+    manifest?: Record<string, string>;
+};
+/**
+ * Plugin-facing API for registered, structured Sandbox Actions.
+ *
+ * Callers choose only an Action and its version; images, commands, entrypoints,
+ * environment variables, and Provider options are resolved and enforced by Core.
+ */
+export interface SandboxJobsApi {
+    /** Starts, reattaches, or reuses a successful execution by tenant-scoped idempotency key. */
+    run(input: SandboxJobRunInput): Promise<SandboxJobRunResult>;
+    /** Cancels the logical Job and terminates its active Runtime when one exists. */
+    cancel(input: {
+        jobId: string;
+    }): Promise<SandboxJobSnapshot>;
+    /** Returns the active tenant's persisted Job snapshot, or null when inaccessible or absent. */
+    getJob(input: {
+        jobId: string;
+    }): Promise<SandboxJobSnapshot | null>;
+    /** Checks readiness before a product exposes or enqueues a browser-backed operation. */
+    getActionHealth(input: {
+        pluginName: string;
+        action: string;
+        actionVersion: string;
+    }): Promise<SandboxJobActionHealth>;
+}
+/** Error carrying retry policy and Job identity across plugin queue handlers. */
+export declare class SandboxJobRuntimeError extends Error {
+    readonly code: SandboxJobErrorCode;
+    readonly retryable: boolean;
+    readonly jobId?: string;
+    constructor(code: SandboxJobErrorCode, message: string, retryable: boolean, jobId?: string);
+}
+/** Narrows an unknown failure to the structured Sandbox Jobs runtime error contract. */
+export declare function isSandboxJobRuntimeError(error: unknown): error is SandboxJobRuntimeError;
+/** Runtime capability key used to resolve SandboxJobsApi from the platform registry. */
+export declare const SandboxJobsRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<SandboxJobsApi>;

package/src/lib/sandbox/index.d.ts

@@ -6,6 +6,12 @@ export * from './sandbox.decorator';
 export * from './sandbox.interface';
 export * from './sandbox.registry';
 export * from './terminal';
+export * from './runtime-provider';
+export * from './runtime-provider.decorator';
+export * from './runtime-provider.registry';
+export * from './workspace-mapper';
+export * from './workspace-mapper.decorator';
+export * from './workspace-mapper.registry';
 export * from './sandbox.interface';
 export * from './sandbox.decorator';
 export * from './sandbox.registry';

package/src/lib/sandbox/protocol.d.ts

@@ -155,6 +155,8 @@ export interface ExecuteResponse {
     truncated: boolean;
     /** Whether the command exceeded its timeout and was terminated */
     timedOut?: boolean;
+    /** Provider-observed container/process termination reason. */
+    terminationReason?: 'oom' | 'deadline' | 'cancelled' | 'container-died';
 }
 /**
  * Standardized error codes for file upload/download operations.
@@ -346,6 +348,8 @@ export interface SandboxBackendProtocol extends BackendProtocol {
     readonly id: string;
     /** Canonical sandbox environment identifier bound to this backend */
     readonly environmentId?: string | null;
+    /** Best-effort immediate termination for an ephemeral job sandbox. */
+    terminate?(): MaybePromise<void>;
 }
 export declare function isSandboxBackend(backend: unknown): backend is SandboxBackendProtocol;
 export declare function resolveSandboxBackend(sandbox: TSandboxConfigurable | SandboxBackendProtocol | null | undefined | unknown): SandboxBackendProtocol | null;

package/src/lib/sandbox/runtime-provider.d.ts

@@ -0,0 +1,181 @@
+/** Per-execution limits applied to the Runtime Definition's fixed Runner command. */
+export type SandboxRuntimeExecutionOptions = {
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+};
+/** Provider-observed reason why a Runtime execution stopped without a normal exit. */
+export type SandboxRuntimeTerminationReason = 'oom' | 'deadline' | 'cancelled' | 'runtime-died';
+/** Normalized process result returned by every Sandbox Runtime implementation. */
+export type SandboxRuntimeExecuteResponse = {
+    output: string;
+    exitCode: number | null;
+    truncated: boolean;
+    timedOut?: boolean;
+    terminationReason?: SandboxRuntimeTerminationReason;
+};
+/** Portable failure categories for Runtime workspace file operations. */
+export type SandboxRuntimeFileOperationError = 'file_not_found' | 'permission_denied' | 'is_directory' | 'invalid_path';
+export type SandboxRuntimeFileUploadResponse = {
+    path: string;
+    error: SandboxRuntimeFileOperationError | null;
+};
+export type SandboxRuntimeFileDownloadResponse = {
+    path: string;
+    content: Uint8Array | null;
+    error: SandboxRuntimeFileOperationError | null;
+};
+/** Resource policy requested by a provider-neutral Runtime Definition. */
+export type SandboxRuntimeResources = {
+    memoryMb: number;
+    cpu: number;
+    shmSizeMb: number;
+    tempDiskMb: number;
+};
+/** Network access that a Provider must enforce for the Runtime instance. */
+export type SandboxRuntimeNetworkPolicy = {
+    mode: 'none' | 'internal-only';
+    allowedHosts?: string[];
+};
+/** Mandatory process and filesystem hardening for a Runtime instance. */
+export type SandboxRuntimeSecurity = {
+    runAsNonRoot: boolean;
+    readOnlyRootFilesystem: boolean;
+    noNewPrivileges: boolean;
+    dropCapabilities: 'all';
+};
+/** Isolation guarantees a Provider advertises before it can be selected. */
+export type SandboxRuntimeProviderCapabilities = {
+    isolation: 'process' | 'hardened';
+    ephemeral: boolean;
+    resourceLimits: boolean;
+    networkPolicy: boolean;
+    readOnlyRootFilesystem: boolean;
+};
+/** Minimum Provider guarantees required by a Runtime Definition. */
+export type SandboxRuntimeRequirements = SandboxRuntimeProviderCapabilities;
+/**
+ * Provider-neutral execution profile published by the Sandbox Runtime Suite.
+ *
+ * Definitions select no image, engine, plugin, or host path. The platform owns
+ * the fixed Runner command and matches it to a compatible Provider Binding.
+ */
+export type SandboxRuntimeDefinition = {
+    /** Stable profile identity referenced by Action manifests. */
+    name: string;
+    /** Trusted Runner Host argv. Plugin callers cannot override this value. */
+    command: readonly string[];
+    /** Runner Host protocol version shared with compatible Action Bundles. */
+    contractVersion: string;
+    /** Version of the Runtime Suite contents, independent of Provider version. */
+    sandboxRuntimeVersion: string;
+    timeoutMs: number;
+    hardDeadlineMs: number;
+    resources: SandboxRuntimeResources;
+    networkPolicy: SandboxRuntimeNetworkPolicy;
+    security: SandboxRuntimeSecurity;
+    requirements: SandboxRuntimeRequirements;
+    expectedManifest: Record<string, string>;
+};
+/** Immutable or provider-addressable runtime artifact selected by a Binding. */
+export type SandboxRuntimeArtifact = {
+    kind: 'oci-image' | 'filesystem' | 'remote-runtime';
+    /** Provider-native immutable address; OCI production references must include a digest. */
+    reference: string;
+    /** Normalized digest retained separately as runtime evidence when available. */
+    digest?: string;
+};
+/** Provider-owned mapping from one Runtime Definition to an executable artifact. */
+export type SandboxRuntimeBinding = {
+    /** Stable Provider-owned Binding identity persisted on every attempt. */
+    id: string;
+    runtimeProfile: string;
+    /** Must match the registered Provider strategy type. */
+    provider: string;
+    /** Lower values are preferred. Ties are resolved by provider and binding id. */
+    priority: number;
+    providerVersion: string;
+    artifact: SandboxRuntimeArtifact;
+};
+/** Result of verifying an engine, artifact, security guarantees, and Runtime manifest. */
+export type SandboxRuntimeBindingHealth = {
+    available: boolean;
+    reason?: string;
+    manifest?: Record<string, string>;
+};
+/** Job-isolated storage roots passed to a Provider without exposing them to plugins. */
+export type SandboxRuntimeVolume = {
+    /** Path visible to the Xpert process. */
+    serverRoot: string;
+    /** Path suitable for a provider-side bind mount. */
+    hostRoot: string;
+};
+/** Fully resolved policy used to create or reattach one ephemeral Job Runtime. */
+export type SandboxRuntimeCreateOptions = {
+    tenantId: string;
+    workFor: {
+        type: 'job';
+        id: string;
+    };
+    definition: SandboxRuntimeDefinition;
+    binding: SandboxRuntimeBinding;
+    volume: SandboxRuntimeVolume;
+    ephemeral: true;
+    resources: SandboxRuntimeResources;
+    networkPolicy: SandboxRuntimeNetworkPolicy;
+    security: SandboxRuntimeSecurity;
+    hardDeadlineMs: number;
+};
+/** Persisted evidence required to destroy a Runtime even after Provider reload. */
+export type SandboxRuntimeDestroyOptions = {
+    tenantId: string;
+    workFor: {
+        type: 'job';
+        id: string;
+    };
+    runtimeProfile: string;
+    runtimeBindingId: string;
+    artifact: SandboxRuntimeArtifact;
+    runtimeRef?: string | null;
+};
+/**
+ * Minimal execution surface required by Sandbox Jobs.
+ *
+ * Implementations must constrain `execute()` to the Definition's trusted Runner
+ * argv and must confine all file operations to `workspaceRoot`.
+ */
+export interface SandboxRuntimeInstance {
+    readonly id: string;
+    /** Absolute path visible inside the isolated Runtime, normally `/workspace`. */
+    readonly workspaceRoot: string;
+    /** Executes Core-supplied argv after the Provider verifies the trusted Runner prefix. */
+    execute(argv: readonly string[], options?: SandboxRuntimeExecutionOptions): Promise<SandboxRuntimeExecuteResponse>;
+    /** Writes files only inside the instance workspace and returns per-path failures. */
+    uploadFiles(files: Array<[string, Uint8Array]>): Promise<SandboxRuntimeFileUploadResponse[]>;
+    /** Reads files only inside the instance workspace and returns per-path failures. */
+    downloadFiles(paths: string[]): Promise<SandboxRuntimeFileDownloadResponse[]>;
+    /** Best-effort immediate termination used by cancellation and deadline handling. */
+    terminate?(): Promise<void> | void;
+}
+/**
+ * Small Provider SPI for background Sandbox Jobs.
+ *
+ * This interface is intentionally independent from the interactive Agent Sandbox
+ * backend protocol. Providers are registered only by built-ins or system plugins,
+ * are selected from declared Bindings, and must make `destroy()` idempotent.
+ */
+export interface ISandboxRuntimeProvider {
+    readonly type: string;
+    readonly version: string;
+    readonly capabilities: SandboxRuntimeProviderCapabilities;
+    /** Lists immutable artifacts this Provider can bind to Runtime Definitions. */
+    listBindings(): Promise<readonly SandboxRuntimeBinding[]> | readonly SandboxRuntimeBinding[];
+    /** Probes the engine and artifact without creating a business Job instance. */
+    getBindingHealth(input: {
+        definition: SandboxRuntimeDefinition;
+        binding: SandboxRuntimeBinding;
+    }): Promise<SandboxRuntimeBindingHealth>;
+    /** Creates or reattaches the unique Runtime instance for the supplied Job scope. */
+    create(options: SandboxRuntimeCreateOptions): Promise<SandboxRuntimeInstance>;
+    /** Idempotently reclaims a Runtime by persisted scope, Binding, and runtimeRef evidence. */
+    destroy(options: SandboxRuntimeDestroyOptions): Promise<void>;
+}

package/src/lib/sandbox/runtime-provider.decorator.d.ts

@@ -0,0 +1,3 @@
+export declare const SANDBOX_RUNTIME_PROVIDER = "SANDBOX_RUNTIME_PROVIDER";
+/** Marks a built-in or system-plugin class as a named Sandbox Runtime Provider strategy. */
+export declare const SandboxRuntimeProviderStrategy: (provider: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/sandbox/runtime-provider.registry.d.ts

@@ -0,0 +1,9 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import type { ISandboxRuntimeProvider } from './runtime-provider';
+/** Discovers Runtime Provider strategies and rejects organization-scoped executable infrastructure. */
+export declare class SandboxRuntimeProviderRegistry extends BaseStrategyRegistry<ISandboxRuntimeProvider> {
+    private readonly runtimeLogger;
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+    upsert(instance: unknown): void;
+}

package/src/lib/sandbox/sandbox.interface.d.ts

@@ -39,6 +39,30 @@ export type SandboxProviderCreateOptions = {
      * Tenant identifier
      */
     tenantId?: string;
+    /** Registered runtime profile. Providers resolve this to an immutable image. */
+    profile?: string;
+    /** Immutable image reference selected by the profile registry. */
+    image?: string;
+    /** Job sandboxes are never reused after the action completes. */
+    ephemeral?: boolean;
+    resources?: {
+        memoryMb?: number;
+        cpu?: number;
+        shmSizeMb?: number;
+        tempDiskMb?: number;
+    };
+    networkPolicy?: {
+        mode: 'none' | 'internal-only';
+        allowedHosts?: string[];
+    };
+    security?: {
+        runAsNonRoot: boolean;
+        readOnlyRootFilesystem: boolean;
+        noNewPrivileges: boolean;
+        dropCapabilities: 'all';
+    };
+    /** Provider-enforced absolute lifetime for the sandbox. */
+    hardDeadlineMs?: number;
     workFor: {
         type: TSandboxWorkForType;
         id: string;
@@ -53,6 +77,22 @@ export interface ISandboxProvider<T extends SandboxBackendProtocol = SandboxBack
      * @param options
      */
     create(options?: SandboxProviderCreateOptions): Promise<T>;
+    /** Destroy an ephemeral sandbox by its stable work identity after process loss or cancellation. */
+    destroy?(options: SandboxProviderCreateOptions & {
+        containerRef?: string | null;
+    }): Promise<void>;
+    /** Provider-side image/runner readiness check used by profile health. */
+    getProfileHealth?(input: {
+        profile: string;
+        image?: string;
+        /** Exact trusted command used to read the runner manifest. */
+        manifestCommand?: readonly string[];
+        expectedManifest?: Record<string, string>;
+    }): Promise<{
+        available: boolean;
+        reason?: string;
+        manifest?: Record<string, string>;
+    }>;
     /**
      * Get default working directory for the sandbox instances
      */

package/src/lib/sandbox/workspace-mapper.d.ts

@@ -0,0 +1,20 @@
+import type { SandboxWorkspaceBinding } from './sandbox.interface';
+/** Server-visible and Provider-visible roots for the same isolated volume. */
+export type SandboxWorkspaceVolume = {
+    serverRoot: string;
+    hostRoot: string;
+};
+/** Optional server path to translate within a mapped volume. */
+export type SandboxWorkspaceMappingOptions = {
+    serverPath?: string;
+};
+/**
+ * Translates paths between platform volumes and Provider-visible workspaces.
+ * Engine-specific path logic belongs here instead of in OSS Volume services.
+ */
+export interface SandboxWorkspaceMapper {
+    /** Produces a Provider-visible binding for one path inside the isolated platform volume. */
+    mapVolumeToWorkspace(volume: SandboxWorkspaceVolume, options?: SandboxWorkspaceMappingOptions): SandboxWorkspaceBinding;
+    /** Converts a Provider-visible path back to its server path, rejecting escapes. */
+    mapWorkspaceToVolume(binding: SandboxWorkspaceBinding, workspacePath: string): string;
+}

package/src/lib/sandbox/workspace-mapper.decorator.d.ts

@@ -0,0 +1,3 @@
+export declare const SANDBOX_WORKSPACE_MAPPER = "SANDBOX_WORKSPACE_MAPPER";
+/** Associates a workspace path mapper with a named Runtime Provider strategy. */
+export declare const SandboxWorkspaceMapperStrategy: (provider: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/sandbox/workspace-mapper.registry.d.ts

@@ -0,0 +1,9 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import type { SandboxWorkspaceMapper } from './workspace-mapper';
+/** Discovers Provider path mappers while enforcing the same system-level trust boundary as Providers. */
+export declare class SandboxWorkspaceMapperRegistry extends BaseStrategyRegistry<SandboxWorkspaceMapper> {
+    private readonly mapperLogger;
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+    upsert(instance: unknown): void;
+}

package/src/lib/strategy.d.ts

@@ -1,4 +1,4 @@
-import { OnModuleInit } from '@nestjs/common';
+import { OnModuleInit, type Type } from '@nestjs/common';
 import { DiscoveryService, Reflector } from '@nestjs/core';
 import { StrategyBus } from './core/strategy-bus';
 export declare class BaseStrategyRegistry<S> implements OnModuleInit {
@@ -11,7 +11,7 @@ export declare class BaseStrategyRegistry<S> implements OnModuleInit {
     protected pluginStrategies: Map<string, Set<string>>;
     constructor(strategyKey: string, discoveryService: DiscoveryService, reflector: Reflector);
     onModuleInit(): void;
-    upsert(instance: any): void;
+    upsert(instance: unknown): void;
     /**
      * Remove all strategies registered by the given plugin for the given scope.
      */
@@ -38,3 +38,7 @@ export declare class BaseStrategyRegistry<S> implements OnModuleInit {
      */
     list(organizationId?: string): S[];
 }
+/** Returns whether a discovered provider can carry decorator metadata. */
+export declare function isStrategyInstance(instance: unknown): instance is object;
+/** Resolves the class used for plugin and organization metadata without reflecting over primitive provider values. */
+export declare function resolveStrategyMetadataTarget(instance: unknown): Type<unknown> | null;