@codesoul-co/hypha-core / modules/command-execution/index

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

Using this module

Use the Index module for executing runtime behavior at this boundary. It exports 19 constants, 5 functions.

Import from the package entrypoint

import {
  commandExecutionJsonSchemas,
  commandExecutionRequestExample,
  commandExecutionRequestJsonSchema,
  commandExecutionRequestSchema,
  commandExecutionResultExample,
  commandExecutionResultJsonSchema,
  commandExecutionResultSchema,
  commandExecutionStatusSchema,
} from '@codesoul-co/hypha-core';

// The complete export list is documented below.

Usage patterns

• The module exposes 5 functions as direct operation entrypoints. Every overload, required/optional parameter, and return type is documented below.
• The 19 constant/enum exports provide stable values, schemas, definitions, or defaults. Reuse these exports instead of copying internal values into an application.

Runtime validation example

import { commandExecutionRequestSchema } from '@codesoul-co/hypha-core';

declare function loadExternalInput(): unknown;
const input: unknown = loadExternalInput();
const parsed = commandExecutionRequestSchema.parse(input);

Parse untrusted configuration, network, or persisted input with the runtime schema before passing it to functions or classes that expect a validated contract.

Public exports

Symbol	Kind	Signature	Description
commandExecutionJsonSchemas	constant	const commandExecutionJsonSchemas: Record<string, JsonSchema>	Command Execution JSON Schemas constant exported by the modules/command-execution/index module.
commandExecutionRequestExample	constant	const commandExecutionRequestExample: CommandExecutionRequest	Valid example value for Command Execution Request.
commandExecutionRequestJsonSchema	constant	const commandExecutionRequestJsonSchema: JsonSchema	JSON Schema for Command Execution Request.
commandExecutionRequestSchema	constant	const commandExecutionRequestSchema: z.ZodEffects<z.ZodObject<{ executionId: z.ZodOptional<z.ZodString>; operationId: z.ZodString; principal: z.ZodObject<{ principalId: z.ZodString; type: z.ZodEnum<["user", "agent", "service", "system"]>; tenantId: z.ZodOptional<z.ZodString>; userId: z.ZodOptional<z.ZodString>; agentId: z.ZodOptional<z.ZodString>; roles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; permissionSc...	Runtime schema for Command Execution Request.
commandExecutionResultExample	constant	const commandExecutionResultExample: CommandExecutionResult	Valid example value for Command Execution Result.
commandExecutionResultJsonSchema	constant	const commandExecutionResultJsonSchema: JsonSchema	JSON Schema for Command Execution Result.
commandExecutionResultSchema	constant	const commandExecutionResultSchema: z.ZodEffects<z.ZodObject<{ executionId: z.ZodString; revision: z.ZodNumber; sandboxId: z.ZodString; status: z.ZodEnum<["queued", "starting", "running", "cancelling", "cancelled", "completed", "failed", "timed_out", "oom_killed", "resource_exceeded", "quarantined"]>; exitCode: z.ZodNullable<z.ZodNumber>; signal: z.ZodOptional<z.ZodString>; stdout: z.ZodOptional<z.ZodString>; stde...	Runtime schema for Command Execution Result.
commandExecutionStatusSchema	constant	const commandExecutionStatusSchema: z.ZodEnum<["queued", "starting", "running", "cancelling", "cancelled", "completed", "failed", "timed_out", "oom_killed", "resource_exceeded", "quarantined"]>	Runtime schema for Command Execution Status.
commandExecutionStatusTransitions	constant	const commandExecutionStatusTransitions: Readonly<Record<CommandExecutionStatus, readonly CommandExecutionStatus[]>>	Command Execution Status Transitions constant exported by the modules/command-execution/index module.
commandOutputChunkExample	constant	const commandOutputChunkExample: CommandOutputChunk	Valid example value for Command Output Chunk.
commandOutputChunkJsonSchema	constant	const commandOutputChunkJsonSchema: JsonSchema	JSON Schema for Command Output Chunk.
commandOutputChunkSchema	constant	const commandOutputChunkSchema: z.ZodEffects<z.ZodObject<{ executionId: z.ZodString; sequence: z.ZodNumber; stream: z.ZodEnum<["stdout", "stderr"]>; encoding: z.ZodEnum<["utf8", "base64"]>; content: z.ZodString; byteLength: z.ZodNumber; contentHash: z.ZodString; emittedAt: z.ZodString; truncated: z.ZodOptional<z.ZodBoolean>; }, "strict", z.ZodTypeAny, { executionId: string; contentHash: string; sequence: number; s...	Runtime schema for Command Output Chunk.
executionCancelRequestExample	constant	const executionCancelRequestExample: ExecutionCancelRequest	Valid example value for Execution Cancel Request.
executionCancelRequestJsonSchema	constant	const executionCancelRequestJsonSchema: JsonSchema	JSON Schema for Execution Cancel Request.
executionCancelRequestSchema	constant	const executionCancelRequestSchema: z.ZodObject<{ operationId: z.ZodString; executionId: z.ZodString; principal: z.ZodObject<{ principalId: z.ZodString; type: z.ZodEnum<["user", "agent", "service", "system"]>; tenantId: z.ZodOptional<z.ZodString>; userId: z.ZodOptional<z.ZodString>; agentId: z.ZodOptional<z.ZodString>; roles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; permissionScopes: z.ZodArray<z.ZodString,...	Runtime schema for Execution Cancel Request.
executionReceiptJsonSchema	constant	const executionReceiptJsonSchema: JsonSchema	JSON Schema for Execution Receipt.
executionReceiptSchema	constant	const executionReceiptSchema: z.ZodObject<{ id: z.ZodString; providerId: z.ZodString; executionId: z.ZodString; providerExecutionRef: z.ZodOptional<z.ZodString>; status: z.ZodEnum<["accepted", "completed", "rejected", "unknown"]>; issuedAt: z.ZodString; receiptHash: z.ZodString; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strict", z.ZodTypeAny, { status: "unknown" | "completed" | "rejected...	Runtime schema for Execution Receipt.
executionResourceUsageJsonSchema	constant	const executionResourceUsageJsonSchema: JsonSchema	JSON Schema for Execution Resource Usage.
executionResourceUsageSchema	constant	const executionResourceUsageSchema: z.ZodObject<{ cpuTimeMs: z.ZodOptional<z.ZodNumber>; peakMemoryBytes: z.ZodOptional<z.ZodNumber>; readBytes: z.ZodOptional<z.ZodNumber>; writtenBytes: z.ZodOptional<z.ZodNumber>; networkBytesSent: z.ZodOptional<z.ZodNumber>; networkBytesReceived: z.ZodOptional<z.ZodNumber>; processCountPeak: z.ZodOptional<z.ZodNumber>; outputBytes: z.ZodOptional<z.ZodNumber>; }, "strict", z.ZodT...	Runtime schema for Execution Resource Usage.
canTransitionCommandExecutionStatus	function	canTransitionCommandExecutionStatus(from: CommandExecutionStatus, to: CommandExecutionStatus): boolean	Can Transition Command Execution Status function with 1 public call signature; parameters and return types are listed below.
validateCommandExecutionRequest	function	validateCommandExecutionRequest(input: unknown): CommandExecutionRequest	Validate Command Execution Request function with 1 public call signature; parameters and return types are listed below.
validateCommandExecutionResult	function	validateCommandExecutionResult(input: unknown): CommandExecutionResult	Validate Command Execution Result function with 1 public call signature; parameters and return types are listed below.
validateCommandOutputChunk	function	validateCommandOutputChunk(input: unknown): CommandOutputChunk	Validate Command Output Chunk function with 1 public call signature; parameters and return types are listed below.
validateExecutionCancelRequest	function	validateExecutionCancelRequest(input: unknown): ExecutionCancelRequest	Validate Execution Cancel Request function with 1 public call signature; parameters and return types are listed below.

commandExecutionJsonSchemas

Command Execution JSON Schemas constant exported by the modules/command-execution/index module.

• Kind: constant
• Import: import { commandExecutionJsonSchemas } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const commandExecutionJsonSchemas: Record<string, JsonSchema>;

commandExecutionRequestExample

Valid example value for Command Execution Request.

• Kind: constant
• Import: import { commandExecutionRequestExample } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const commandExecutionRequestExample: CommandExecutionRequest;

commandExecutionRequestJsonSchema

JSON Schema for Command Execution Request.

• Kind: constant
• Import: import { commandExecutionRequestJsonSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const commandExecutionRequestJsonSchema: JsonSchema;

commandExecutionRequestSchema

Runtime schema for Command Execution Request.

• Kind: constant
• Import: import { commandExecutionRequestSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

// Exact type resolved from the package entrypoint; see source for the compiler expansion.
export declare const commandExecutionRequestSchema: (typeof import('@codesoul-co/hypha-core'))['commandExecutionRequestSchema'];

This compiler-expanded constant type is compacted. Its public name, top-level type, and source location remain here; use the module’s exported interfaces, types, or runtime schema for input/output fields.

commandExecutionResultExample

Valid example value for Command Execution Result.

• Kind: constant
• Import: import { commandExecutionResultExample } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const commandExecutionResultExample: CommandExecutionResult;

commandExecutionResultJsonSchema

JSON Schema for Command Execution Result.

• Kind: constant
• Import: import { commandExecutionResultJsonSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const commandExecutionResultJsonSchema: JsonSchema;

commandExecutionResultSchema

Runtime schema for Command Execution Result.

• Kind: constant
• Import: import { commandExecutionResultSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

// Exact type resolved from the package entrypoint; see source for the compiler expansion.
export declare const commandExecutionResultSchema: (typeof import('@codesoul-co/hypha-core'))['commandExecutionResultSchema'];

This compiler-expanded constant type is compacted. Its public name, top-level type, and source location remain here; use the module’s exported interfaces, types, or runtime schema for input/output fields.

commandExecutionStatusSchema

Runtime schema for Command Execution Status.

• Kind: constant
• Import: import { commandExecutionStatusSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const commandExecutionStatusSchema: z.ZodEnum<["queued", "starting", "running", "cancelling", "cancelled", "completed", "failed", "timed_out", "oom_killed", "resource_exceeded", "quarantined"]>;

commandExecutionStatusTransitions

Command Execution Status Transitions constant exported by the modules/command-execution/index module.

• Kind: constant
• Import: import { commandExecutionStatusTransitions } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const commandExecutionStatusTransitions: Readonly<Record<CommandExecutionStatus, readonly CommandExecutionStatus[]>>;

commandOutputChunkExample

Valid example value for Command Output Chunk.

• Kind: constant
• Import: import { commandOutputChunkExample } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const commandOutputChunkExample: CommandOutputChunk;

commandOutputChunkJsonSchema

JSON Schema for Command Output Chunk.

• Kind: constant
• Import: import { commandOutputChunkJsonSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const commandOutputChunkJsonSchema: JsonSchema;

commandOutputChunkSchema

Runtime schema for Command Output Chunk.

• Kind: constant
• Import: import { commandOutputChunkSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const commandOutputChunkSchema: z.ZodEffects<z.ZodObject<{ executionId: z.ZodString; sequence: z.ZodNumber; stream: z.ZodEnum<["stdout", "stderr"]>; encoding: z.ZodEnum<["utf8", "base64"]>; content: z.ZodString; byteLength: z.ZodNumber; contentHash: z.ZodString; emittedAt: z.ZodString; truncated: z.ZodOptional<z.ZodBoolean>; }, "strict", z.ZodTypeAny, { executionId: string; contentHash: string; sequence: number; stream: "stdout" | "stderr"; content: string; encoding: "utf8" | "base64"; byteLength: number; emittedAt: string; truncated?: boolean | undefined; }, { executionId: string; contentHash: string; sequence: number; stream: "stdout" | "stderr"; content: string; encoding: "utf8" | "base64"; byteLength: number; emittedAt: string; truncated?: boolean | undefined; }>, { executionId: string; contentHash: string; sequence: number; stream: "stdout" | "stderr"; content: string; encoding: "utf8" | "base64"; byteLength: number; emittedAt: string; truncated?: boolean | undefined; }, { executionId: string; contentHash: string; sequence: number; stream: "stdout" | "stderr"; content: string; encoding: "utf8" | "base64"; byteLength: number; emittedAt: string; truncated?: boolean | undefined; }>;

executionCancelRequestExample

Valid example value for Execution Cancel Request.

• Kind: constant
• Import: import { executionCancelRequestExample } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const executionCancelRequestExample: ExecutionCancelRequest;

executionCancelRequestJsonSchema

JSON Schema for Execution Cancel Request.

• Kind: constant
• Import: import { executionCancelRequestJsonSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const executionCancelRequestJsonSchema: JsonSchema;

executionCancelRequestSchema

Runtime schema for Execution Cancel Request.

• Kind: constant
• Import: import { executionCancelRequestSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const executionCancelRequestSchema: z.ZodObject<{ operationId: z.ZodString; executionId: z.ZodString; principal: z.ZodObject<{ principalId: z.ZodString; type: z.ZodEnum<["user", "agent", "service", "system"]>; tenantId: z.ZodOptional<z.ZodString>; userId: z.ZodOptional<z.ZodString>; agentId: z.ZodOptional<z.ZodString>; roles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; permissionScopes: z.ZodArray<z.ZodString, "many">; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strict", z.ZodTypeAny, { type: "user" | "agent" | "service" | "system"; principalId: string; permissionScopes: string[]; metadata?: Record<string, unknown> | undefined; agentId?: string | undefined; tenantId?: string | undefined; userId?: string | undefined; roles?: string[] | undefined; }, { type: "user" | "agent" | "service" | "system"; principalId: string; permissionScopes: string[]; metadata?: Record<string, unknown> | undefined; agentId?: string | undefined; tenantId?: string | undefined; userId?: string | undefined; roles?: string[] | undefined; }>; expectedRevision: z.ZodNumber; reason: z.ZodOptional<z.ZodString>; gracePeriodMs: z.ZodOptional<z.ZodNumber>; idempotencyKey: z.ZodOptional<z.ZodString>; correlationId: z.ZodOptional<z.ZodString>; causationId: z.ZodOptional<z.ZodString>; }, "strict", z.ZodTypeAny, { operationId: string; executionId: string; principal: { type: "user" | "agent" | "service" | "system"; principalId: string; permissionScopes: string[]; metadata?: Record<string, unknown> | undefined; agentId?: string | undefined; tenantId?: string | undefined; userId?: string | undefined; roles?: string[] | undefined; }; expectedRevision: number; reason?: string | undefined; correlationId?: string | undefined; causationId?: string | undefined; idempotencyKey?: string | undefined; gracePeriodMs?: number | undefined; }, { operationId: string; executionId: string; principal: { type: "user" | "agent" | "service" | "system"; principalId: string; permissionScopes: string[]; metadata?: Record<string, unknown> | undefined; agentId?: string | undefined; tenantId?: string | undefined; userId?: string | undefined; roles?: string[] | undefined; }; expectedRevision: number; reason?: string | undefined; correlationId?: string | undefined; causationId?: string | undefined; idempotencyKey?: string | undefined; gracePeriodMs?: number | undefined; }>;

executionReceiptJsonSchema

JSON Schema for Execution Receipt.

• Kind: constant
• Import: import { executionReceiptJsonSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const executionReceiptJsonSchema: JsonSchema;

executionReceiptSchema

Runtime schema for Execution Receipt.

• Kind: constant
• Import: import { executionReceiptSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const executionReceiptSchema: z.ZodObject<{ id: z.ZodString; providerId: z.ZodString; executionId: z.ZodString; providerExecutionRef: z.ZodOptional<z.ZodString>; status: z.ZodEnum<["accepted", "completed", "rejected", "unknown"]>; issuedAt: z.ZodString; receiptHash: z.ZodString; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strict", z.ZodTypeAny, { status: "unknown" | "completed" | "rejected" | "accepted"; id: string; executionId: string; providerId: string; issuedAt: string; receiptHash: string; metadata?: Record<string, unknown> | undefined; providerExecutionRef?: string | undefined; }, { status: "unknown" | "completed" | "rejected" | "accepted"; id: string; executionId: string; providerId: string; issuedAt: string; receiptHash: string; metadata?: Record<string, unknown> | undefined; providerExecutionRef?: string | undefined; }>;

executionResourceUsageJsonSchema

JSON Schema for Execution Resource Usage.

• Kind: constant
• Import: import { executionResourceUsageJsonSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const executionResourceUsageJsonSchema: JsonSchema;

executionResourceUsageSchema

Runtime schema for Execution Resource Usage.

• Kind: constant
• Import: import { executionResourceUsageSchema } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare const executionResourceUsageSchema: z.ZodObject<{ cpuTimeMs: z.ZodOptional<z.ZodNumber>; peakMemoryBytes: z.ZodOptional<z.ZodNumber>; readBytes: z.ZodOptional<z.ZodNumber>; writtenBytes: z.ZodOptional<z.ZodNumber>; networkBytesSent: z.ZodOptional<z.ZodNumber>; networkBytesReceived: z.ZodOptional<z.ZodNumber>; processCountPeak: z.ZodOptional<z.ZodNumber>; outputBytes: z.ZodOptional<z.ZodNumber>; }, "strict", z.ZodTypeAny, { cpuTimeMs?: number | undefined; peakMemoryBytes?: number | undefined; readBytes?: number | undefined; writtenBytes?: number | undefined; networkBytesSent?: number | undefined; networkBytesReceived?: number | undefined; processCountPeak?: number | undefined; outputBytes?: number | undefined; }, { cpuTimeMs?: number | undefined; peakMemoryBytes?: number | undefined; readBytes?: number | undefined; writtenBytes?: number | undefined; networkBytesSent?: number | undefined; networkBytesReceived?: number | undefined; processCountPeak?: number | undefined; outputBytes?: number | undefined; }>;

canTransitionCommandExecutionStatus

Can Transition Command Execution Status function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { canTransitionCommandExecutionStatus } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare function canTransitionCommandExecutionStatus(from: CommandExecutionStatus, to: CommandExecutionStatus): boolean;

Call signature

canTransitionCommandExecutionStatus(from: CommandExecutionStatus, to: CommandExecutionStatus): boolean

Parameters

Parameter	Type	Required	Description
from	CommandExecutionStatus	Yes	Required parameter; accepted values are defined by the type column.
to	CommandExecutionStatus	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: boolean
• Description: The return contract is defined by the type shown above.

validateCommandExecutionRequest

Validate Command Execution Request function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { validateCommandExecutionRequest } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare function validateCommandExecutionRequest(input: unknown): CommandExecutionRequest;

Call signature

validateCommandExecutionRequest(input: unknown): CommandExecutionRequest

Parameters

Parameter	Type	Required	Description
input	unknown	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: CommandExecutionRequest
• Description: The return contract is defined by the type shown above.

validateCommandExecutionResult

Validate Command Execution Result function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { validateCommandExecutionResult } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare function validateCommandExecutionResult(input: unknown): CommandExecutionResult;

Call signature

validateCommandExecutionResult(input: unknown): CommandExecutionResult

Parameters

Parameter	Type	Required	Description
input	unknown	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: CommandExecutionResult
• Description: The return contract is defined by the type shown above.

validateCommandOutputChunk

Validate Command Output Chunk function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { validateCommandOutputChunk } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare function validateCommandOutputChunk(input: unknown): CommandOutputChunk;

Call signature

validateCommandOutputChunk(input: unknown): CommandOutputChunk

Parameters

Parameter	Type	Required	Description
input	unknown	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: CommandOutputChunk
• Description: The return contract is defined by the type shown above.

validateExecutionCancelRequest

Validate Execution Cancel Request function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { validateExecutionCancelRequest } from '@codesoul-co/hypha-core';
• Source module: modules/command-execution/index

Declaration

export declare function validateExecutionCancelRequest(input: unknown): ExecutionCancelRequest;

Call signature

validateExecutionCancelRequest(input: unknown): ExecutionCancelRequest

Parameters

Parameter	Type	Required	Description
input	unknown	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: ExecutionCancelRequest
• Description: The return contract is defined by the type shown above.