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

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

Using this module

Use the Sandbox provider module for declaring and runtime-validating contracts. It exports 6 interfaces, 3 types.

Import from the package entrypoint

import type {
  SandboxCapabilityDerivationInput,
  SandboxCapabilityNegotiationRequest,
  SandboxCapabilityNegotiationResult,
  SandboxCapabilityRequirement,
  SandboxProvider,
  SandboxProviderFactory,
  SandboxCapabilityName,
  SandboxProviderSelection,
} from '@codesoul-co/hypha-core';

// The complete export list is documented below.

Usage patterns

• Use the 9 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
SandboxCapabilityDerivationInput	interface	interface SandboxCapabilityDerivationInput	Sandbox Capability Derivation Input interface with 3 public fields or methods.
SandboxCapabilityNegotiationRequest	interface	interface SandboxCapabilityNegotiationRequest	Sandbox Capability Negotiation Request interface with 4 public fields or methods.
SandboxCapabilityNegotiationResult	interface	interface SandboxCapabilityNegotiationResult	Sandbox Capability Negotiation Result interface with 6 public fields or methods.
SandboxCapabilityRequirement	interface	interface SandboxCapabilityRequirement	Sandbox Capability Requirement interface with 3 public fields or methods.
SandboxProvider	interface	interface SandboxProvider	Sandbox Provider interface with 11 public fields or methods.
SandboxProviderFactory	interface	interface SandboxProviderFactory	Composition-root contract for constructing a configured SandboxProvider. Concrete adapters own their options; core only knows the provider type and stable id.
SandboxCapabilityName	type	type SandboxCapabilityName = keyof SandboxProviderCapabilities	Public type alias for Sandbox Capability Name; the declaration contains its complete type expression.
SandboxProviderSelection	type	type SandboxProviderSelection = Pick<ExecutionEnvironmentSpec, 'provider' | 'providerRef'>	Public type alias for Sandbox Provider Selection; the declaration contains its complete type expression.
SandboxProviderType	type	type SandboxProviderType = ExecutionEnvironmentSpec['provider']	Public type alias for Sandbox Provider Type; the declaration contains its complete type expression.

SandboxCapabilityDerivationInput

Sandbox Capability Derivation Input interface with 3 public fields or methods.

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

Declaration

export interface SandboxCapabilityDerivationInput {
    environment: ExecutionEnvironmentSpec;
    command?: Pick<CommandExecutionRequest, 'snapshotBefore' | 'snapshotAfter' | 'snapshotOnFailure'>;
    additionalRequirements?: SandboxCapabilityRequirement[];
}

Contract members

Member	Kind	Signature	Description
additionalRequirements	property	additionalRequirements?: SandboxCapabilityRequirement[]	Public property; its type, readonly modifier and optionality are shown in the signature.
command	property	command?: Pick<CommandExecutionRequest, "snapshotBefore" | "snapshotAfter" | "snapshotOnFailure">	Public property; its type, readonly modifier and optionality are shown in the signature.
environment	property	environment: ExecutionEnvironmentSpec	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxCapabilityNegotiationRequest

Sandbox Capability Negotiation Request interface with 4 public fields or methods.

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

Declaration

export interface SandboxCapabilityNegotiationRequest {
    providerId: string;
    capabilities: SandboxProviderCapabilities;
    requirements: SandboxCapabilityRequirement[];
    evaluatedAt: string;
}

Contract members

Member	Kind	Signature	Description
capabilities	property	capabilities: SandboxProviderCapabilities	Public property; its type, readonly modifier and optionality are shown in the signature.
evaluatedAt	property	evaluatedAt: string	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.
requirements	property	requirements: SandboxCapabilityRequirement[]	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxCapabilityNegotiationResult

Sandbox Capability Negotiation Result interface with 6 public fields or methods.

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

Declaration

export interface SandboxCapabilityNegotiationResult {
    providerId: string;
    compatible: boolean;
    capabilities: SandboxProviderCapabilities;
    requirements: SandboxCapabilityRequirement[];
    missingCapabilities: SandboxCapabilityName[];
    evaluatedAt: string;
}

Contract members

Member	Kind	Signature	Description
capabilities	property	capabilities: SandboxProviderCapabilities	Public property; its type, readonly modifier and optionality are shown in the signature.
compatible	property	compatible: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
evaluatedAt	property	evaluatedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
missingCapabilities	property	missingCapabilities: (keyof SandboxProviderCapabilities)[]	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.
requirements	property	requirements: SandboxCapabilityRequirement[]	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxCapabilityRequirement

Sandbox Capability Requirement interface with 3 public fields or methods.

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

Declaration

export interface SandboxCapabilityRequirement {
    capability: SandboxCapabilityName;
    source: 'environment' | 'command' | 'policy' | 'runtime';
    reason: string;
}

Contract members

Member	Kind	Signature	Description
capability	property	capability: keyof SandboxProviderCapabilities	Public property; its type, readonly modifier and optionality are shown in the signature.
reason	property	reason: string	Public property; its type, readonly modifier and optionality are shown in the signature.
source	property	source: "policy" | "environment" | "command" | "runtime"	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxProvider

Sandbox Provider interface with 11 public fields or methods.

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

Declaration

export interface SandboxProvider {
    readonly id: string;
    capabilities(): Promise<SandboxProviderCapabilities>;
    create(request: SandboxCreateRequest): Promise<SandboxRecord>;
    start(request: SandboxStartRequest): Promise<SandboxRecord>;
    execute(request: CommandExecutionRequest): Promise<CommandExecutionResult>;
    cancel(request: ExecutionCancelRequest): Promise<void>;
    terminate(request: SandboxTerminateRequest): Promise<void>;
    status(request: SandboxStatusRequest): Promise<SandboxRecord | null>;
    cleanup(request: SandboxCleanupRequest): Promise<void>;
    health(): Promise<ProviderHealth>;
    close?(): Promise<void>;
}

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<SandboxProviderCapabilities>	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.
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.
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.
terminate	method	terminate(request: SandboxTerminateRequest): Promise<void>	Public method; parameters and return type are shown in the signature.

SandboxProviderFactory

Composition-root contract for constructing a configured SandboxProvider. Concrete adapters own their options; core only knows the provider type and stable id.

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

Declaration

export interface SandboxProviderFactory {
    readonly providerType: SandboxProviderType;
    readonly providerId: string;
    create(): SandboxProvider | Promise<SandboxProvider>;
}

Contract members

Member	Kind	Signature	Description
create	method	create(): SandboxProvider | Promise<SandboxProvider>	Public method; parameters and return type are shown in the signature.
providerId	property	readonly providerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerType	property	readonly providerType: "mock" | "local_process" | "docker" | "remote_sandbox" | "custom"	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxCapabilityName

Public type alias for Sandbox Capability Name; the declaration contains its complete type expression.

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

Declaration

export type SandboxCapabilityName = keyof SandboxProviderCapabilities;

SandboxProviderSelection

Public type alias for Sandbox Provider Selection; the declaration contains its complete type expression.

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

Declaration

export type SandboxProviderSelection = Pick<ExecutionEnvironmentSpec, 'provider' | 'providerRef'>;

SandboxProviderType

Public type alias for Sandbox Provider Type; the declaration contains its complete type expression.

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

Declaration

export type SandboxProviderType = ExecutionEnvironmentSpec['provider'];