@codesoul-co/hypha-core / contracts/command-execution

• Package index: @codesoul-co/hypha-core
• Source: packages/core/src/contracts/command-execution.ts
• Exports: 7

Using this module

Use the Command execution module for declaring and runtime-validating contracts. It exports 6 interfaces, 1 type.

Import from the package entrypoint

import type {
  CommandExecutionRequest,
  CommandExecutionResult,
  CommandOutputChunk,
  ExecutionCancelRequest,
  ExecutionReceipt,
  ExecutionResourceUsage,
  CommandExecutionStatus,
} from '@codesoul-co/hypha-core';

Usage patterns

• Use the 7 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
CommandExecutionRequest	interface	interface CommandExecutionRequest	Command Execution Request interface with 35 public fields or methods.
CommandExecutionResult	interface	interface CommandExecutionResult	Command Execution Result interface with 25 public fields or methods.
CommandOutputChunk	interface	interface CommandOutputChunk	Command Output Chunk interface with 9 public fields or methods.
ExecutionCancelRequest	interface	interface ExecutionCancelRequest	Execution Cancel Request interface with 9 public fields or methods.
ExecutionReceipt	interface	interface ExecutionReceipt	Execution Receipt interface with 8 public fields or methods.
ExecutionResourceUsage	interface	interface ExecutionResourceUsage	Execution Resource Usage interface with 8 public fields or methods.
CommandExecutionStatus	type	type CommandExecutionStatus = 'queued' | 'starting' | 'running' | 'cancelling' | 'cancelled' | 'completed' | 'failed' | 'timed_out' | 'oom_killed' | 'resource_exceeded' | 'quarantined'	Public type alias for Command Execution Status; the declaration contains its complete type expression.

CommandExecutionRequest

Command Execution Request interface with 35 public fields or methods.

• Kind: interface
• Import: import type { CommandExecutionRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/command-execution

Declaration

export interface CommandExecutionRequest {
    executionId?: string;
    operationId: string;
    principal: ExecutionPrincipal;
    tenantId?: string;
    userId: string;
    workspaceId: string;
    sessionId?: string;
    runId: string;
    stepId?: string;
    agentId?: string;
    fsmState?: string;
    sandboxId?: string;
    environmentRef: SpecRef;
    executable: string;
    args?: string[];
    cwd?: string;
    env?: Record<string, string>;
    secretRefs?: string[];
    shell?: boolean;
    stdin?: string | Uint8Array;
    timeoutMs?: number;
    idleTimeoutMs?: number;
    maxStdoutBytes?: number;
    maxStderrBytes?: number;
    captureArtifacts?: boolean;
    captureFileMutations?: boolean;
    snapshotBefore?: boolean;
    snapshotAfter?: boolean;
    snapshotOnFailure?: boolean;
    networkAuthorizationRef?: string;
    idempotencyKey?: string;
    expectedWorkspaceSnapshotHash?: string;
    correlationId?: string;
    causationId?: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
agentId	property	agentId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
args	property	args?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
captureArtifacts	property	captureArtifacts?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
captureFileMutations	property	captureFileMutations?: boolean	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.
cwd	property	cwd?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
env	property	env?: Record<string, string>	Public property; its type, readonly modifier and optionality are shown in the signature.
environmentRef	property	environmentRef: SpecRef	Public property; its type, readonly modifier and optionality are shown in the signature.
executable	property	executable: 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.
expectedWorkspaceSnapshotHash	property	expectedWorkspaceSnapshotHash?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
fsmState	property	fsmState?: 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.
idleTimeoutMs	property	idleTimeoutMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxStderrBytes	property	maxStderrBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxStdoutBytes	property	maxStdoutBytes?: 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.
networkAuthorizationRef	property	networkAuthorizationRef?: 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.
runId	property	runId: 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.
secretRefs	property	secretRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
sessionId	property	sessionId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
shell	property	shell?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
snapshotAfter	property	snapshotAfter?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
snapshotBefore	property	snapshotBefore?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
snapshotOnFailure	property	snapshotOnFailure?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
stdin	property	stdin?: string | Uint8Array<ArrayBufferLike>	Public property; its type, readonly modifier and optionality are shown in the signature.
stepId	property	stepId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
tenantId	property	tenantId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
timeoutMs	property	timeoutMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
userId	property	userId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
workspaceId	property	workspaceId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

CommandExecutionResult

Command Execution Result interface with 25 public fields or methods.

• Kind: interface
• Import: import type { CommandExecutionResult } from '@codesoul-co/hypha-core';
• Source module: contracts/command-execution

Declaration

export interface CommandExecutionResult {
    executionId: string;
    revision: number;
    sandboxId: string;
    status: CommandExecutionStatus;
    exitCode: number | null;
    signal?: string;
    stdout?: string;
    stderr?: string;
    /** SHA-256 content hash of the bounded inline stdout value. */
    stdoutContentHash?: string;
    /** SHA-256 content hash of the bounded inline stderr value. */
    stderrContentHash?: string;
    stdoutTruncated?: boolean;
    stderrTruncated?: boolean;
    stdoutArtifactRef?: string;
    stderrArtifactRef?: string;
    changedFiles: FileMutation[];
    generatedArtifactRefs: string[];
    snapshotBeforeRef?: string;
    snapshotAfterRef?: string;
    resourceUsage?: ExecutionResourceUsage;
    externalReceipt?: ExecutionReceipt;
    startedAt: string;
    completedAt?: string;
    latencyMs?: number;
    error?: NormalizedExecutionError;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
changedFiles	property	changedFiles: FileMutation[]	Public property; its type, readonly modifier and optionality are shown in the signature.
completedAt	property	completedAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
error	property	error?: NormalizedExecutionError	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.
exitCode	property	exitCode: number	Public property; its type, readonly modifier and optionality are shown in the signature.
externalReceipt	property	externalReceipt?: ExecutionReceipt	Public property; its type, readonly modifier and optionality are shown in the signature.
generatedArtifactRefs	property	generatedArtifactRefs: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
latencyMs	property	latencyMs?: 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.
resourceUsage	property	resourceUsage?: ExecutionResourceUsage	Public property; its type, readonly modifier and optionality are shown in the signature.
revision	property	revision: number	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.
signal	property	signal?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
snapshotAfterRef	property	snapshotAfterRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
snapshotBeforeRef	property	snapshotBeforeRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
startedAt	property	startedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: CommandExecutionStatus	Public property; its type, readonly modifier and optionality are shown in the signature.
stderr	property	stderr?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
stderrArtifactRef	property	stderrArtifactRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
stderrContentHash	property	stderrContentHash?: string	SHA-256 content hash of the bounded inline stderr value.
stderrTruncated	property	stderrTruncated?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
stdout	property	stdout?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
stdoutArtifactRef	property	stdoutArtifactRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
stdoutContentHash	property	stdoutContentHash?: string	SHA-256 content hash of the bounded inline stdout value.
stdoutTruncated	property	stdoutTruncated?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.

CommandOutputChunk

Command Output Chunk interface with 9 public fields or methods.

• Kind: interface
• Import: import type { CommandOutputChunk } from '@codesoul-co/hypha-core';
• Source module: contracts/command-execution

Declaration

export interface CommandOutputChunk {
    executionId: string;
    sequence: number;
    stream: 'stdout' | 'stderr';
    encoding: 'utf8' | 'base64';
    content: string;
    byteLength: number;
    contentHash: string;
    emittedAt: string;
    truncated?: boolean;
}

Contract members

Member	Kind	Signature	Description
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.
emittedAt	property	emittedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
encoding	property	encoding: "utf8" | "base64"	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.
sequence	property	sequence: number	Public property; its type, readonly modifier and optionality are shown in the signature.
stream	property	stream: "stdout" | "stderr"	Public property; its type, readonly modifier and optionality are shown in the signature.
truncated	property	truncated?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionCancelRequest

Execution Cancel Request interface with 9 public fields or methods.

• Kind: interface
• Import: import type { ExecutionCancelRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/command-execution

Declaration

export interface ExecutionCancelRequest {
    operationId: string;
    executionId: string;
    principal: ExecutionPrincipal;
    expectedRevision: number;
    reason?: string;
    gracePeriodMs?: number;
    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.
expectedRevision	property	expectedRevision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
gracePeriodMs	property	gracePeriodMs?: 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.
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.
reason	property	reason?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionReceipt

Execution Receipt interface with 8 public fields or methods.

• Kind: interface
• Import: import type { ExecutionReceipt } from '@codesoul-co/hypha-core';
• Source module: contracts/command-execution

Declaration

export interface ExecutionReceipt {
    id: string;
    providerId: string;
    executionId: string;
    providerExecutionRef?: string;
    status: 'accepted' | 'completed' | 'rejected' | 'unknown';
    issuedAt: string;
    receiptHash: string;
    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.
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.
providerExecutionRef	property	providerExecutionRef?: 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.
receiptHash	property	receiptHash: string	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.

ExecutionResourceUsage

Execution Resource Usage interface with 8 public fields or methods.

• Kind: interface
• Import: import type { ExecutionResourceUsage } from '@codesoul-co/hypha-core';
• Source module: contracts/command-execution

Declaration

export interface ExecutionResourceUsage {
    cpuTimeMs?: number;
    peakMemoryBytes?: number;
    readBytes?: number;
    writtenBytes?: number;
    networkBytesSent?: number;
    networkBytesReceived?: number;
    processCountPeak?: number;
    outputBytes?: number;
}

Contract members

Member	Kind	Signature	Description
cpuTimeMs	property	cpuTimeMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
networkBytesReceived	property	networkBytesReceived?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
networkBytesSent	property	networkBytesSent?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
outputBytes	property	outputBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
peakMemoryBytes	property	peakMemoryBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
processCountPeak	property	processCountPeak?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
readBytes	property	readBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
writtenBytes	property	writtenBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

CommandExecutionStatus

Public type alias for Command Execution Status; the declaration contains its complete type expression.

• Kind: type
• Import: import type { CommandExecutionStatus } from '@codesoul-co/hypha-core';
• Source module: contracts/command-execution

Declaration

export type CommandExecutionStatus = 'queued' | 'starting' | 'running' | 'cancelling' | 'cancelled' | 'completed' | 'failed' | 'timed_out' | 'oom_killed' | 'resource_exceeded' | 'quarantined';