@codesoul-co/hypha-core / contracts/remote-sandbox-provider

• Package index: @codesoul-co/hypha-core
• Source: packages/core/src/contracts/remote-sandbox-provider.ts
• Exports: 11

Using this module

Use the Remote sandbox provider module for declaring and runtime-validating contracts. It exports 10 interfaces, 1 type.

Import from the package entrypoint

import type {
  RemoteArtifactChunk,
  RemoteArtifactChunkSequenceExpectation,
  RemoteArtifactDownloadRequest,
  RemoteArtifactTransferReceipt,
  RemoteArtifactUploadRequest,
  RemoteExecutionReconciliationRequest,
  RemoteExecutionReconciliationResult,
  RemoteOutputStreamRequest,
} from '@codesoul-co/hypha-core';

// The complete export list is documented below.

Usage patterns

• Use the 11 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.

Public exports

Symbol	Kind	Signature	Description
RemoteArtifactChunk	interface	interface RemoteArtifactChunk	Remote Artifact Chunk interface with 9 public fields or methods.
RemoteArtifactChunkSequenceExpectation	interface	interface RemoteArtifactChunkSequenceExpectation	Remote Artifact Chunk Sequence Expectation interface with 3 public fields or methods.
RemoteArtifactDownloadRequest	interface	interface RemoteArtifactDownloadRequest	Remote Artifact Download Request interface with 9 public fields or methods.
RemoteArtifactTransferReceipt	interface	interface RemoteArtifactTransferReceipt	Remote Artifact Transfer Receipt interface with 12 public fields or methods.
RemoteArtifactUploadRequest	interface	interface RemoteArtifactUploadRequest	Remote Artifact Upload Request interface with 12 public fields or methods.
RemoteExecutionReconciliationRequest	interface	interface RemoteExecutionReconciliationRequest	Remote Execution Reconciliation Request interface with 8 public fields or methods.
RemoteExecutionReconciliationResult	interface	interface RemoteExecutionReconciliationResult	Remote Execution Reconciliation Result interface with 8 public fields or methods.
RemoteOutputStreamRequest	interface	interface RemoteOutputStreamRequest	Remote Output Stream Request interface with 8 public fields or methods.
RemoteSandboxProvider	interface	interface RemoteSandboxProvider extends SandboxProvider	Remote Sandbox Provider interface with 15 public fields or methods.
RemoteSandboxProviderCapabilities	interface	interface RemoteSandboxProviderCapabilities extends SandboxProviderCapabilities	Remote Sandbox Provider Capabilities interface with 12 public fields or methods.
RemoteExecutionReconciliationState	type	type RemoteExecutionReconciliationState = 'not_found' | 'accepted' | 'running' | 'completed' | 'failed' | 'cancelled' | 'unknown'	Public type alias for Remote Execution Reconciliation State; the declaration contains its complete type expression.

RemoteArtifactChunk

Remote Artifact Chunk interface with 9 public fields or methods.

• Kind: interface
• Import: import type { RemoteArtifactChunk } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export interface RemoteArtifactChunk {
    transferId: string;
    artifactRef: string;
    sequence: number;
    offsetBytes: number;
    encoding: 'base64';
    content: string;
    byteLength: number;
    contentHash: string;
    final: boolean;
}

Contract members

Member	Kind	Signature	Description
artifactRef	property	artifactRef: string	Public property; its type, readonly modifier and optionality are shown in the signature.
byteLength	property	byteLength: number	Public property; its type, readonly modifier and optionality are shown in the signature.
content	property	content: string	Public property; its type, readonly modifier and optionality are shown in the signature.
contentHash	property	contentHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
encoding	property	encoding: "base64"	Public property; its type, readonly modifier and optionality are shown in the signature.
final	property	final: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
offsetBytes	property	offsetBytes: number	Public property; its type, readonly modifier and optionality are shown in the signature.
sequence	property	sequence: number	Public property; its type, readonly modifier and optionality are shown in the signature.
transferId	property	transferId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

RemoteArtifactChunkSequenceExpectation

Remote Artifact Chunk Sequence Expectation interface with 3 public fields or methods.

• Kind: interface
• Import: import type { RemoteArtifactChunkSequenceExpectation } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export interface RemoteArtifactChunkSequenceExpectation {
    transferId: string;
    artifactRef: string;
    sizeBytes: number;
}

Contract members

Member	Kind	Signature	Description
artifactRef	property	artifactRef: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sizeBytes	property	sizeBytes: number	Public property; its type, readonly modifier and optionality are shown in the signature.
transferId	property	transferId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

RemoteArtifactDownloadRequest

Remote Artifact Download Request interface with 9 public fields or methods.

• Kind: interface
• Import: import type { RemoteArtifactDownloadRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export interface RemoteArtifactDownloadRequest {
    operationId: string;
    sandboxId: string;
    principal: ExecutionPrincipal;
    artifactRef: string;
    maxBytes: number;
    expectedContentHash?: string;
    correlationId?: string;
    causationId?: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
artifactRef	property	artifactRef: string	Public property; its type, readonly modifier and optionality are shown in the signature.
causationId	property	causationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
correlationId	property	correlationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
expectedContentHash	property	expectedContentHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
maxBytes	property	maxBytes: number	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal: ExecutionPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
sandboxId	property	sandboxId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

RemoteArtifactTransferReceipt

Remote Artifact Transfer Receipt interface with 12 public fields or methods.

• Kind: interface
• Import: import type { RemoteArtifactTransferReceipt } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export interface RemoteArtifactTransferReceipt {
    id: string;
    providerId: string;
    sandboxId: string;
    artifactRef: string;
    direction: 'upload' | 'download';
    status: 'accepted' | 'completed' | 'rejected' | 'unknown';
    sizeBytes: number;
    contentHash?: string;
    providerTransferRef?: string;
    issuedAt: string;
    receiptHash: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
artifactRef	property	artifactRef: string	Public property; its type, readonly modifier and optionality are shown in the signature.
contentHash	property	contentHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
direction	property	direction: "upload" | "download"	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
issuedAt	property	issuedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerTransferRef	property	providerTransferRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
receiptHash	property	receiptHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sandboxId	property	sandboxId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sizeBytes	property	sizeBytes: number	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: "unknown" | "accepted" | "completed" | "rejected"	Public property; its type, readonly modifier and optionality are shown in the signature.

RemoteArtifactUploadRequest

Remote Artifact Upload Request interface with 12 public fields or methods.

• Kind: interface
• Import: import type { RemoteArtifactUploadRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export interface RemoteArtifactUploadRequest {
    operationId: string;
    sandboxId: string;
    principal: ExecutionPrincipal;
    expectedSandboxRevision: number;
    artifactRef: string;
    sizeBytes: number;
    contentHash: string;
    mediaType?: string;
    idempotencyKey: string;
    correlationId?: string;
    causationId?: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
artifactRef	property	artifactRef: string	Public property; its type, readonly modifier and optionality are shown in the signature.
causationId	property	causationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
contentHash	property	contentHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
correlationId	property	correlationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
expectedSandboxRevision	property	expectedSandboxRevision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey: string	Public property; its type, readonly modifier and optionality are shown in the signature.
mediaType	property	mediaType?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal: ExecutionPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
sandboxId	property	sandboxId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sizeBytes	property	sizeBytes: number	Public property; its type, readonly modifier and optionality are shown in the signature.

RemoteExecutionReconciliationRequest

Remote Execution Reconciliation Request interface with 8 public fields or methods.

• Kind: interface
• Import: import type { RemoteExecutionReconciliationRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export interface RemoteExecutionReconciliationRequest {
    operationId: string;
    executionId: string;
    sandboxId: string;
    principal: ExecutionPrincipal;
    providerExecutionRef?: string;
    idempotencyKey?: string;
    correlationId?: string;
    causationId?: string;
}

Contract members

Member	Kind	Signature	Description
causationId	property	causationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
correlationId	property	correlationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
executionId	property	executionId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal: ExecutionPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
providerExecutionRef	property	providerExecutionRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sandboxId	property	sandboxId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

RemoteExecutionReconciliationResult

Remote Execution Reconciliation Result interface with 8 public fields or methods.

• Kind: interface
• Import: import type { RemoteExecutionReconciliationResult } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export interface RemoteExecutionReconciliationResult {
    executionId: string;
    sandboxId: string;
    state: RemoteExecutionReconciliationState;
    providerExecutionRef?: string;
    observedAt: string;
    result?: CommandExecutionResult;
    receipt?: ExecutionReceipt;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
executionId	property	executionId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
observedAt	property	observedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerExecutionRef	property	providerExecutionRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
receipt	property	receipt?: ExecutionReceipt	Public property; its type, readonly modifier and optionality are shown in the signature.
result	property	result?: CommandExecutionResult	Public property; its type, readonly modifier and optionality are shown in the signature.
sandboxId	property	sandboxId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
state	property	state: RemoteExecutionReconciliationState	Public property; its type, readonly modifier and optionality are shown in the signature.

RemoteOutputStreamRequest

Remote Output Stream Request interface with 8 public fields or methods.

• Kind: interface
• Import: import type { RemoteOutputStreamRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export interface RemoteOutputStreamRequest {
    operationId: string;
    executionId: string;
    principal: ExecutionPrincipal;
    fromSequence?: number;
    maxChunks?: number;
    follow?: boolean;
    correlationId?: string;
    causationId?: string;
}

Contract members

Member	Kind	Signature	Description
causationId	property	causationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
correlationId	property	correlationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
executionId	property	executionId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
follow	property	follow?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
fromSequence	property	fromSequence?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxChunks	property	maxChunks?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal: ExecutionPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.

RemoteSandboxProvider

Remote Sandbox Provider interface with 15 public fields or methods.

• Kind: interface
• Import: import type { RemoteSandboxProvider } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export interface RemoteSandboxProvider extends SandboxProvider {
    capabilities(): Promise<RemoteSandboxProviderCapabilities>;
    reconcileExecution(request: RemoteExecutionReconciliationRequest): Promise<RemoteExecutionReconciliationResult>;
    streamOutput(request: RemoteOutputStreamRequest): AsyncIterable<CommandOutputChunk>;
    uploadArtifact(request: RemoteArtifactUploadRequest, chunks: AsyncIterable<RemoteArtifactChunk>): Promise<RemoteArtifactTransferReceipt>;
    downloadArtifact(request: RemoteArtifactDownloadRequest): AsyncIterable<RemoteArtifactChunk>;
}

Contract members

Member	Kind	Signature	Description
cancel	method	cancel(request: ExecutionCancelRequest): Promise<void>	Public method; parameters and return type are shown in the signature.
capabilities	method	capabilities(): Promise<RemoteSandboxProviderCapabilities>	Public method; parameters and return type are shown in the signature.
cleanup	method	cleanup(request: SandboxCleanupRequest): Promise<void>	Public method; parameters and return type are shown in the signature.
close	method	close?(): Promise<void>	Public method; parameters and return type are shown in the signature.
create	method	create(request: SandboxCreateRequest): Promise<SandboxRecord>	Public method; parameters and return type are shown in the signature.
downloadArtifact	method	downloadArtifact(request: RemoteArtifactDownloadRequest): AsyncIterable<RemoteArtifactChunk>	Public method; parameters and return type are shown in the signature.
execute	method	execute(request: CommandExecutionRequest): Promise<CommandExecutionResult>	Public method; parameters and return type are shown in the signature.
health	method	health(): Promise<ProviderHealth>	Public method; parameters and return type are shown in the signature.
id	property	readonly id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
reconcileExecution	method	reconcileExecution(request: RemoteExecutionReconciliationRequest): Promise<RemoteExecutionReconciliationResult>	Public method; parameters and return type are shown in the signature.
start	method	start(request: SandboxStartRequest): Promise<SandboxRecord>	Public method; parameters and return type are shown in the signature.
status	method	status(request: SandboxStatusRequest): Promise<SandboxRecord | null>	Public method; parameters and return type are shown in the signature.
streamOutput	method	streamOutput(request: RemoteOutputStreamRequest): AsyncIterable<CommandOutputChunk>	Public method; parameters and return type are shown in the signature.
terminate	method	terminate(request: SandboxTerminateRequest): Promise<void>	Public method; parameters and return type are shown in the signature.
uploadArtifact	method	uploadArtifact(request: RemoteArtifactUploadRequest, chunks: AsyncIterable<RemoteArtifactChunk>): Promise<RemoteArtifactTransferReceipt>	Public method; parameters and return type are shown in the signature.

RemoteSandboxProviderCapabilities

Remote Sandbox Provider Capabilities interface with 12 public fields or methods.

• Kind: interface
• Import: import type { RemoteSandboxProviderCapabilities } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export interface RemoteSandboxProviderCapabilities extends SandboxProviderCapabilities {
    remoteExecution: true;
}

Contract members

Member	Kind	Signature	Description
cancellation	property	cancellation: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
cpuLimits	property	cpuLimits: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
diskLimits	property	diskLimits: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
filesystemIsolation	property	filesystemIsolation: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
imageDigestPinning	property	imageDigestPinning: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
memoryLimits	property	memoryLimits: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
networkIsolation	property	networkIsolation: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
pidsLimit	property	pidsLimit: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
processIsolation	property	processIsolation: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
processTreeKill	property	processTreeKill: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
remoteExecution	property	remoteExecution: true	Public property; its type, readonly modifier and optionality are shown in the signature.
snapshots	property	snapshots: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.

RemoteExecutionReconciliationState

Public type alias for Remote Execution Reconciliation State; the declaration contains its complete type expression.

• Kind: type
• Import: import type { RemoteExecutionReconciliationState } from '@codesoul-co/hypha-core';
• Source module: contracts/remote-sandbox-provider

Declaration

export type RemoteExecutionReconciliationState = 'not_found' | 'accepted' | 'running' | 'completed' | 'failed' | 'cancelled' | 'unknown';