Interface: LocalCommandBuilder<TIn, TOut, THandle>

Defined in: node/src/builders/local-command-builder.ts:35

Fluent builder for a one-shot local OS subprocess command (local.command(id)).

Compiles to a passive LocalCommandNode participating in StepASTNode and provides .asCheck() and .asTool() projections for deterministic gates and post-flight-diffed agent tools.

Extends

• AstBuilder<LocalCommandNode<TIn, TOut, THandle>>

Type Parameters

Type Parameter	Default type	Description
TIn	unknown	Validated command input payload type.
TOut	unknown	Validated command output payload type.
THandle	unknown	Runtime handle type of the active isolation scope.

Methods

argv()

argv(args): LocalCommandBuilder<TIn, TOut, THandle>;

Defined in: node/src/builders/local-command-builder.ts:86

Binds the static argument vector or synchronous input-to-argv mapper function.

Index 0 of the returned array specifies the executable binary and subsequent entries are arguments.

Parameters

Parameter	Type	Description
args	| readonly string[] | BivariantCallback<[input: TIn], readonly string[]>	Argument vector or mapper.

Returns

LocalCommandBuilder<TIn, TOut, THandle>

Updated immutable command builder.

---

asCheck()

asCheck(): AstBuilder<LocalCommandCheckNode<THandle>> & LocalCommandCheckNode<THandle>;

Defined in: node/src/builders/local-command-builder.ts:155

Projects this command into a passive LocalCommandCheckNode (type: 'node:command-check').

Reports { ok: true, deficits: [] } when the command exits with code 0.

Returns

AstBuilder<LocalCommandCheckNode<THandle>> & LocalCommandCheckNode<THandle>

Check builder and AST descriptor.

---

asTool()

asTool(): AstBuilder<LocalCommandToolNode<THandle>> & LocalCommandToolNode<THandle>;

Defined in: node/src/builders/local-command-builder.ts:165

Projects this command into a post-flight-diffed LocalCommandToolNode (type: 'node:command-tool').

Defaults inputSchema to z.object({}) when argv is a static array and sets effectTracking: 'subprocess-post-flight' so workspace mutations are verified post-flight.

Returns

AstBuilder<LocalCommandToolNode<THandle>> & LocalCommandToolNode<THandle>

Tool builder and AST descriptor.

---

env()

env(envVars): LocalCommandBuilder<TIn, TOut, THandle>;

Defined in: node/src/builders/local-command-builder.ts:73

Binds static string or symbolic EnvRef environment variables injected into the subprocess.

Symbolic EnvRef entries are resolved via ctx.resolveEnv at leaf execution time.

Parameters

Parameter	Type	Description
envVars	Readonly<Record<string, string | EnvRef>>	Environment variable map.

Returns

LocalCommandBuilder<TIn, TOut, THandle>

Updated immutable command builder.

---

input()

input<TNewIn>(schema): LocalCommandBuilder<TNewIn, TOut, THandle>;

Defined in: node/src/builders/local-command-builder.ts:112

Binds the Zod validation schema for the command's input payload.

Narrows TIn for subsequent .argv(fn), .stdin(fn), and .unrepeatable(cmd, { key }) callbacks.

Type Parameters

Type Parameter	Description
TNewIn	New validated command input payload type.

Parameters

Parameter	Type	Description
schema	ZodType<TNewIn>	Zod input schema.

Returns

LocalCommandBuilder<TNewIn, TOut, THandle>

Updated immutable command builder narrowed to TNewIn.

---

output()

output<TNewOut>(schema): LocalCommandBuilder<TIn, TNewOut, THandle>;

Defined in: node/src/builders/local-command-builder.ts:127

Binds the Zod validation schema for the command's parsed stdout output.

Validates trimmed JSON or string stdout before returning from executeLocalCommandStep.

Type Parameters

Type Parameter	Description
TNewOut	New validated command output payload type.

Parameters

Parameter	Type	Description
schema	ZodType<TNewOut>	Zod output schema.

Returns

LocalCommandBuilder<TIn, TNewOut, THandle>

Updated immutable command builder narrowed to TNewOut.

---

runner()

runner(runner): LocalCommandBuilder<TIn, TOut, THandle>;

Defined in: node/src/builders/local-command-builder.ts:49

Binds the NodeRunnerNode pool governing concurrency slots for this command.

Acquires a one-shot slot via RunnerDriver.withSlot whenever the command executes.

Parameters

Parameter	Type	Description
runner	MaybeBuilder<NodeRunnerNode>	Runner pool AST node or builder.

Returns

LocalCommandBuilder<TIn, TOut, THandle>

Updated immutable command builder.

---

stdin()

stdin(mode): LocalCommandBuilder<TIn, TOut, THandle>;

Defined in: node/src/builders/local-command-builder.ts:60

Configures standard input handling ('closed' or a synchronous payload mapper).

Enforces closed stdin by default so interactive CLI prompts never hang runner slots.

Parameters

Parameter	Type	Description
mode	| "closed" | BivariantCallback<[input: TIn], string | Uint8Array<ArrayBufferLike>>	Standard input mode or mapper.

Returns

LocalCommandBuilder<TIn, TOut, THandle>

Updated immutable command builder.

---

timeoutMinutes()

timeoutMinutes(minutes): LocalCommandBuilder<TIn, TOut, THandle>;

Defined in: node/src/builders/local-command-builder.ts:99

Sets the execution timeout in minutes before the subprocess group is terminated.

Sends SIGTERM followed by SIGKILL to the detached process group when the timeout expires.

Parameters

Parameter	Type	Description
minutes	number	Positive timeout duration in minutes.

Returns

LocalCommandBuilder<TIn, TOut, THandle>

Updated immutable command builder.

---

toAST()

toAST(): LocalCommandNode;

Defined in: core/dist/ast/ast-builder.d.ts:19

Compiles the current builder configuration into a deeply frozen passive AST node.

Validates required builder invariants at compilation time and returns an immutable plain-object AST representation containing zero execution methods.

Returns

LocalCommandNode

Deeply frozen passive AST node.

Inherited from

AstBuilder.toAST

---

unrepeatable()

unrepeatable<TPreIn>(preCheckCmd, options): LocalCommandBuilder<TIn, TOut, THandle>;

Defined in: node/src/builders/local-command-builder.ts:143

Configures a pre-flight idempotency check command that skips execution when preCheckCmd returns true.

Prevents side-effecting commands from re-executing when their external effect is already present.

Type Parameters

Type Parameter	Default type	Description
TPreIn	TIn	Input payload type of preCheckCmd.

Parameters

Parameter	Type	Description
preCheckCmd	MaybeBuilder<LocalCommandNode<TPreIn, boolean, THandle>>	Boolean pre-check command node or builder.
options	LocalCommandUnrepeatableOptions<TIn>	Deduplication key configuration.

Returns

LocalCommandBuilder<TIn, TOut, THandle>

Updated immutable command builder.

Properties

Property	Modifier	Type	Description	Defined in
id	readonly	string	Unique identifier of the local command.	node/src/builders/local-command-builder.ts:38