@codesoul-co/hypha-core / contracts/command-execution
模块用法
用于声明并运行时校验契约。Command execution 模块公开 6 接口、1 类型。
从包入口导入
ts
import type {
CommandExecutionRequest,
CommandExecutionResult,
CommandOutputChunk,
ExecutionCancelRequest,
ExecutionReceipt,
ExecutionResourceUsage,
CommandExecutionStatus,
} from '@codesoul-co/hypha-core';使用要点
- 7 个类型/接口用于应用代码、Adapter 或测试中的静态契约；请使用
import type，运行时不应依赖它们。
公共导出
| Symbol | 种类 | 签名 | 说明 |
|---|---|---|---|
CommandExecutionRequest | 接口 | interface CommandExecutionRequest | Command Execution Request 接口，共包含 35 个公开字段或方法。 |
CommandExecutionResult | 接口 | interface CommandExecutionResult | Command Execution Result 接口，共包含 25 个公开字段或方法。 |
CommandOutputChunk | 接口 | interface CommandOutputChunk | Command Output Chunk 接口，共包含 9 个公开字段或方法。 |
ExecutionCancelRequest | 接口 | interface ExecutionCancelRequest | Execution Cancel Request 接口，共包含 9 个公开字段或方法。 |
ExecutionReceipt | 接口 | interface ExecutionReceipt | Execution Receipt 接口，共包含 8 个公开字段或方法。 |
ExecutionResourceUsage | 接口 | interface ExecutionResourceUsage | Execution Resource Usage 接口，共包含 8 个公开字段或方法。 |
CommandExecutionStatus | 类型 | type CommandExecutionStatus = 'queued' | 'starting' | 'running' | 'cancelling' | 'cancelled' | 'completed' | 'failed' | 'timed_out' | 'oom_killed' | 'resource_exceeded' | 'quarantined' | Command Execution Status 公共类型别名；完整类型表达式见声明。 |
CommandExecutionRequest
Command Execution Request 接口，共包含 35 个公开字段或方法。
- 种类: 接口
- 导入:
import type { CommandExecutionRequest } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/command-execution
声明
text
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>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
agentId | 属性 | agentId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
args | 属性 | args?: string[] | 公开属性；类型、只读和可选状态以签名列为准。 |
captureArtifacts | 属性 | captureArtifacts?: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
captureFileMutations | 属性 | captureFileMutations?: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
causationId | 属性 | causationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
correlationId | 属性 | correlationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
cwd | 属性 | cwd?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
env | 属性 | env?: Record<string, string> | 公开属性；类型、只读和可选状态以签名列为准。 |
environmentRef | 属性 | environmentRef: SpecRef | 公开属性；类型、只读和可选状态以签名列为准。 |
executable | 属性 | executable: string | 公开属性；类型、只读和可选状态以签名列为准。 |
executionId | 属性 | executionId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
expectedWorkspaceSnapshotHash | 属性 | expectedWorkspaceSnapshotHash?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
fsmState | 属性 | fsmState?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
idempotencyKey | 属性 | idempotencyKey?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
idleTimeoutMs | 属性 | idleTimeoutMs?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
maxStderrBytes | 属性 | maxStderrBytes?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
maxStdoutBytes | 属性 | maxStdoutBytes?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
metadata | 属性 | metadata?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
networkAuthorizationRef | 属性 | networkAuthorizationRef?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
operationId | 属性 | operationId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
principal | 属性 | principal: ExecutionPrincipal | 公开属性；类型、只读和可选状态以签名列为准。 |
runId | 属性 | runId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
sandboxId | 属性 | sandboxId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
secretRefs | 属性 | secretRefs?: string[] | 公开属性；类型、只读和可选状态以签名列为准。 |
sessionId | 属性 | sessionId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
shell | 属性 | shell?: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
snapshotAfter | 属性 | snapshotAfter?: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
snapshotBefore | 属性 | snapshotBefore?: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
snapshotOnFailure | 属性 | snapshotOnFailure?: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
stdin | 属性 | stdin?: string | Uint8Array<ArrayBufferLike> | 公开属性；类型、只读和可选状态以签名列为准。 |
stepId | 属性 | stepId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
tenantId | 属性 | tenantId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
timeoutMs | 属性 | timeoutMs?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
userId | 属性 | userId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
workspaceId | 属性 | workspaceId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
CommandExecutionResult
Command Execution Result 接口，共包含 25 个公开字段或方法。
- 种类: 接口
- 导入:
import type { CommandExecutionResult } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/command-execution
声明
text
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>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
changedFiles | 属性 | changedFiles: FileMutation[] | 公开属性；类型、只读和可选状态以签名列为准。 |
completedAt | 属性 | completedAt?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
error | 属性 | error?: NormalizedExecutionError | 公开属性；类型、只读和可选状态以签名列为准。 |
executionId | 属性 | executionId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
exitCode | 属性 | exitCode: number | 公开属性；类型、只读和可选状态以签名列为准。 |
externalReceipt | 属性 | externalReceipt?: ExecutionReceipt | 公开属性；类型、只读和可选状态以签名列为准。 |
generatedArtifactRefs | 属性 | generatedArtifactRefs: string[] | 公开属性；类型、只读和可选状态以签名列为准。 |
latencyMs | 属性 | latencyMs?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
metadata | 属性 | metadata?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
resourceUsage | 属性 | resourceUsage?: ExecutionResourceUsage | 公开属性；类型、只读和可选状态以签名列为准。 |
revision | 属性 | revision: number | 公开属性；类型、只读和可选状态以签名列为准。 |
sandboxId | 属性 | sandboxId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
signal | 属性 | signal?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
snapshotAfterRef | 属性 | snapshotAfterRef?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
snapshotBeforeRef | 属性 | snapshotBeforeRef?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
startedAt | 属性 | startedAt: string | 公开属性；类型、只读和可选状态以签名列为准。 |
status | 属性 | status: CommandExecutionStatus | 公开属性；类型、只读和可选状态以签名列为准。 |
stderr | 属性 | stderr?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
stderrArtifactRef | 属性 | stderrArtifactRef?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
stderrContentHash | 属性 | stderrContentHash?: string | SHA-256 content hash of the bounded inline stderr value. |
stderrTruncated | 属性 | stderrTruncated?: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
stdout | 属性 | stdout?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
stdoutArtifactRef | 属性 | stdoutArtifactRef?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
stdoutContentHash | 属性 | stdoutContentHash?: string | SHA-256 content hash of the bounded inline stdout value. |
stdoutTruncated | 属性 | stdoutTruncated?: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
CommandOutputChunk
Command Output Chunk 接口，共包含 9 个公开字段或方法。
- 种类: 接口
- 导入:
import type { CommandOutputChunk } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/command-execution
声明
text
export interface CommandOutputChunk {
executionId: string;
sequence: number;
stream: 'stdout' | 'stderr';
encoding: 'utf8' | 'base64';
content: string;
byteLength: number;
contentHash: string;
emittedAt: string;
truncated?: boolean;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
byteLength | 属性 | byteLength: number | 公开属性；类型、只读和可选状态以签名列为准。 |
content | 属性 | content: string | 公开属性；类型、只读和可选状态以签名列为准。 |
contentHash | 属性 | contentHash: string | 公开属性；类型、只读和可选状态以签名列为准。 |
emittedAt | 属性 | emittedAt: string | 公开属性；类型、只读和可选状态以签名列为准。 |
encoding | 属性 | encoding: "utf8" | "base64" | 公开属性；类型、只读和可选状态以签名列为准。 |
executionId | 属性 | executionId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
sequence | 属性 | sequence: number | 公开属性；类型、只读和可选状态以签名列为准。 |
stream | 属性 | stream: "stdout" | "stderr" | 公开属性；类型、只读和可选状态以签名列为准。 |
truncated | 属性 | truncated?: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
ExecutionCancelRequest
Execution Cancel Request 接口，共包含 9 个公开字段或方法。
- 种类: 接口
- 导入:
import type { ExecutionCancelRequest } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/command-execution
声明
text
export interface ExecutionCancelRequest {
operationId: string;
executionId: string;
principal: ExecutionPrincipal;
expectedRevision: number;
reason?: string;
gracePeriodMs?: number;
idempotencyKey?: string;
correlationId?: string;
causationId?: string;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
causationId | 属性 | causationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
correlationId | 属性 | correlationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
executionId | 属性 | executionId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
expectedRevision | 属性 | expectedRevision: number | 公开属性；类型、只读和可选状态以签名列为准。 |
gracePeriodMs | 属性 | gracePeriodMs?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
idempotencyKey | 属性 | idempotencyKey?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
operationId | 属性 | operationId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
principal | 属性 | principal: ExecutionPrincipal | 公开属性；类型、只读和可选状态以签名列为准。 |
reason | 属性 | reason?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
ExecutionReceipt
Execution Receipt 接口，共包含 8 个公开字段或方法。
- 种类: 接口
- 导入:
import type { ExecutionReceipt } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/command-execution
声明
text
export interface ExecutionReceipt {
id: string;
providerId: string;
executionId: string;
providerExecutionRef?: string;
status: 'accepted' | 'completed' | 'rejected' | 'unknown';
issuedAt: string;
receiptHash: string;
metadata?: Record<string, unknown>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
executionId | 属性 | executionId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
id | 属性 | id: string | 公开属性；类型、只读和可选状态以签名列为准。 |
issuedAt | 属性 | issuedAt: string | 公开属性；类型、只读和可选状态以签名列为准。 |
metadata | 属性 | metadata?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
providerExecutionRef | 属性 | providerExecutionRef?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
providerId | 属性 | providerId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
receiptHash | 属性 | receiptHash: string | 公开属性；类型、只读和可选状态以签名列为准。 |
status | 属性 | status: "unknown" | "accepted" | "completed" | "rejected" | 公开属性；类型、只读和可选状态以签名列为准。 |
ExecutionResourceUsage
Execution Resource Usage 接口，共包含 8 个公开字段或方法。
- 种类: 接口
- 导入:
import type { ExecutionResourceUsage } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/command-execution
声明
text
export interface ExecutionResourceUsage {
cpuTimeMs?: number;
peakMemoryBytes?: number;
readBytes?: number;
writtenBytes?: number;
networkBytesSent?: number;
networkBytesReceived?: number;
processCountPeak?: number;
outputBytes?: number;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
cpuTimeMs | 属性 | cpuTimeMs?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
networkBytesReceived | 属性 | networkBytesReceived?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
networkBytesSent | 属性 | networkBytesSent?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
outputBytes | 属性 | outputBytes?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
peakMemoryBytes | 属性 | peakMemoryBytes?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
processCountPeak | 属性 | processCountPeak?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
readBytes | 属性 | readBytes?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
writtenBytes | 属性 | writtenBytes?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
CommandExecutionStatus
Command Execution Status 公共类型别名；完整类型表达式见声明。
- 种类: 类型
- 导入:
import type { CommandExecutionStatus } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/command-execution
声明
text
export type CommandExecutionStatus = 'queued' | 'starting' | 'running' | 'cancelling' | 'cancelled' | 'completed' | 'failed' | 'timed_out' | 'oom_killed' | 'resource_exceeded' | 'quarantined';