@usine/agents/child-host

Classes

LocalProcess

Children run as processes on this machine.

Extends

• Schema.Class

Constructors

Constructor

new LocalProcess(…args): LocalProcess

Parameters

Parameter	Type
…args	[props?: object, options?: MakeOptions]

Returns

LocalProcess

---

RemoteShell

Children run on another machine, each as one SSH command whose standard streams are the child’s.

Extends

• Schema.Class

Constructors

Constructor

new RemoteShell(…args): RemoteShell

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

RemoteShell

Properties

destination

readonly destination: string

The SSH destination, passed to the client as one argument.

ssh

readonly ssh: object

args

readonly args: readonly string[]

command

readonly command: string

sshEnvironment

readonly sshEnvironment: object

The SSH client’s own process environment: what SSH needs to reach the machine, never the orchestrator’s secrets (ADR 0011), and the variables an -o SendEnv= option in ssh names. Only those reach the child, so a value that must stay out of the command line, such as a Gateway caller token, travels here; never log this field.

Index Signature

[key: string]: string

Interfaces

HostInvocation

One command for a host to run.

Properties

args

readonly args: readonly string[]

command

readonly command: string

cwd?

readonly optional cwd?: string

The directory the command starts in; the host user’s home directory when absent.

environment?

readonly optional environment?: Readonly<Record<string, string | undefined>>

The command’s complete environment on this machine. On a remote shell, the variables exported on top of the shell’s own environment; undefined values are skipped.

pidFile?

readonly optional pidFile?: string

On a remote shell, holds the command’s pid while it runs, so cleanup can stop it after its SSH client is gone.

Type Aliases

ChildHost

ChildHost = typeof ChildHost.Type

Where an Attempt’s children run, chosen by the Worker that prepared its checkout.

---

SshCommand

SshCommand = typeof SshCommand.Type

The local SSH executable and the options placed before the destination.

Variables

CHILD_KILL_SCRIPT

const CHILD_KILL_SCRIPT: string

Stops every child an Attempt still runs on a remote host before its worktree is kept or removed: for each <worktree>.child-*.pid that childPidFile names, TERM, a bounded wait, then KILL. Run it with sh -c and the worktree as $1; stdout reports one outcome per pid file. An SSH client that exits does not prove its remote command has stopped.

---

ChildHost

const ChildHost: Schema.Union<readonly [typeof LocalProcess, typeof RemoteShell]>

Where an Attempt’s children run, chosen by the Worker that prepared its checkout.

---

childPidFile

const childPidFile: (worktree, session) => string

Where a remote child’s pid is kept while it runs: beside its worktree, named by the child’s number in its session id.

Parameters

Parameter	Type
worktree	string
session	AgentSessionId

Returns

string

---

sshArguments

const sshArguments: (host, invocation) => string[]

The SSH client’s arguments that run invocation on the host’s machine: its options, the destination, and one remote command line.

Parameters

Parameter	Type
host	RemoteShell
invocation	HostInvocation

Returns

string[]

---

SshCommand

const SshCommand: Schema.Struct<{ args: Schema.$Array<Schema.String>; command: Schema.NonEmptyString; }>

The local SSH executable and the options placed before the destination.