@usine/executor

The usine scoped Worker contract with local, exe.dev, and SSH adapters.

Modules

Classes

AttemptWorkspace

The serializable location and RunSpec of an Attempt checkout. Owning this record does not grant access to live resources or credentials.

Extends

Schema.Class

Constructors

Constructor

new AttemptWorkspace(…args): AttemptWorkspace

Parameters

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

Returns

AttemptWorkspace

Properties

spec

readonly spec: RunSpec

worker

readonly worker: string & Brand<"WorkerName">

worktree

readonly worktree: string & Brand<"WorktreePath">

CheckoutRequest

The repository, revision, and Agent task assigned to a Worker for one Attempt’s checkout.

Extends

Schema.Class

Constructors

Constructor

new CheckoutRequest(…args): CheckoutRequest

Parameters

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

Returns

CheckoutRequest

Properties

agent

readonly agent: Agent

attemptId

readonly attemptId: string & Brand<"AttemptId">

maxAttemptMinutes

readonly maxAttemptMinutes: Option<number>

Maximum minutes of live Attempt execution, or none for no timer; preparation and resource cleanup are outside this budget.

maxAttemptTokens

readonly maxAttemptTokens: Option<number>

Maximum consumed tokens across the parent and every child, or none for no token ceiling; operator Holds never pause this ceiling.

maxChildren

readonly maxChildren: number & Brand<"ChildSessionBudget">

parentEffort

readonly parentEffort: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"

parentModel

readonly parentModel: Option<string & Brand<"ModelId">>

payload

readonly payload: Json

reattach

readonly reattach: boolean

The Attempt outlived an orchestrator restart and its parent task is still live: preparation takes over the checkout it already has instead of creating one, and launch reattaches to the running parent.

repository

readonly repository: string & Brand<"RepositoryName">

resume

readonly resume: Option<SalvagePushed>

The previous Attempt’s pushed salvage to check out instead of the bare revision.

revision

readonly revision: string & Brand<"RepositoryRevision">

salvageRef

readonly salvageRef: string & Brand<"SalvageRef">

Where the Worker pushes this Attempt’s unfinished work if the Attempt ends without success.

task

readonly task: string & Brand<"AttemptTask">

worker

readonly worker: string & Brand<"WorkerName">

CredentialProvider

Mints renewable repository-scoped credentials for an Attempt.

Extends

Context.ServiceClass

Properties

Service

readonly Service: object

The service’s operations: what yield* CredentialProvider returns.

issue

readonly issue: (repository, attemptId) => Effect.Effect<WorkerCredential, CredentialUnavailableError>

Parameters

Parameter	Type
`repository`	`RepositoryName`
`attemptId`	`AttemptId`

Returns

Effect.Effect<WorkerCredential, CredentialUnavailableError>

CredentialUnavailableError

A Worker could not obtain access to the repository assigned to an Attempt.

Extends

Schema.Class

Constructors

Constructor

new CredentialUnavailableError(…args): CredentialUnavailableError

Parameters

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

Returns

CredentialUnavailableError

Properties

cause

readonly cause: unknown

message

readonly message: string

repository

readonly repository: string & Brand<"RepositoryName">

Executor

Prepares isolated checkouts, runs Attempts on a Worker, and releases their resources (ADR 0006).

Extends

Context.ServiceClass

Properties

Service

readonly Service: object

The service’s operations: what yield* Executor returns.

cancel

readonly cancel: (attemptId) => Effect.Effect<void, ExecutorError>

Stops preparation and releases partial resources, or cancels the live parent task with a grace period before forced termination. A canceled prepared Attempt cannot launch. Repeated cancellation after release is a no-op.

Parameters

Parameter	Type
`attemptId`	`AttemptId`

Returns

Effect.Effect<void, ExecutorError>

intervene

readonly intervene: (attemptId, intervention) => Effect.Effect<void, AttemptFailure>

Delivers an attributed operator action to the active Attempt’s live session.

Parameters

Parameter	Type
`attemptId`	`AttemptId`
`intervention`	`Intervention`

Returns

Effect.Effect<void, AttemptFailure>

isLive

readonly isLive: (attemptId) => Effect.Effect<boolean, AttemptFailure>

Whether the Attempt’s parent task survived an orchestrator restart and can be reattached: it still runs, or it reported success before its checkout was harvested.

Parameters

Parameter	Type
`attemptId`	`AttemptId`

Returns

Effect.Effect<boolean, AttemptFailure>

kind

readonly kind: WorkerKind

outcome

readonly outcome: (attemptId) => Effect.Effect<Option.Option<Result.Result<StepResult, AttemptFailure>>, AttemptFailure>

The result an Attempt’s finished parent task left in durable storage before an orchestrator restart: the harvested result, or the parent’s failure. None when nothing was stored, or when isLive says the Attempt is reattached instead.

Parameters

Parameter	Type
`attemptId`	`AttemptId`

Returns

Effect.Effect<Option.Option<Result.Result<StepResult, AttemptFailure>>, AttemptFailure>

preflight

readonly preflight: (worker, brains) => Effect.Effect<void, ExecutorError>

Verifies Git and each rostered brain where the Worker runs children; never installs tools or logs in.

Parameters

Parameter	Type
`worker`	`WorkerName`
`brains`	`ReadonlyArray`<`BrainSpec`>

Returns

Effect.Effect<void, ExecutorError>

prepare

readonly prepare: (request) => Effect.Effect<PreparedAttempt, ExecutorError, Scope.Scope>

Verifies the assigned brain before acquiring the Attempt in the caller’s scope. Clone, fetch, and lock waits remain interruptible; partial preparation releases everything already acquired before reporting failure. Each request identifies a fresh Attempt, or a live one to reattach when reattach is set.

Parameters

Parameter	Type
`request`	`CheckoutRequest`

Returns

Effect.Effect<PreparedAttempt, ExecutorError, Scope.Scope>

recover

readonly recover: <E>(attempt, record) => Effect.Effect<void, E | ExecutorError>

Reconciles an old checkout before new Attempts start; records its salvage before releasing any work.

Type Parameters

Type Parameter
`E`

Parameters

Parameter	Type
`attempt`	`AttemptRecovery`
`record`	(`salvage`) => `Effect.Effect`<`void`, `E`>

Returns

Effect.Effect<void, E | ExecutorError>

ExecutorOperationError

A Worker operation failed before its requested work completed.

Extends

Schema.Class

Constructors

Constructor

new ExecutorOperationError(…args): ExecutorOperationError

Parameters

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

Returns

ExecutorOperationError

Properties

cause

readonly cause: unknown

message

readonly message: string

operation

readonly operation: "launch" | "preflight" | "prepare" | "cancel" | "cleanup"

WorkerCapabilityError

A verify-only preflight found a Worker capability missing or incompatible.

Extends

Schema.Class

Constructors

Constructor

new WorkerCapabilityError(…args): WorkerCapabilityError

Parameters

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

Returns

WorkerCapabilityError

Properties

capability

readonly capability: "gateway" | "machine" | "toolchain" | "harness-login" | "credentials"

cause

readonly cause: unknown

message

readonly message: string

worker

readonly worker: string & Brand<"WorkerName">

WorkerCredential

A repository-scoped Worker credential and the instant at which it stops authorizing requests.

Extends

Schema.Class

Constructors

Constructor

new WorkerCredential(…args): WorkerCredential

Parameters

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

Returns

WorkerCredential

Properties

expiresAt

readonly expiresAt: Utc

value

readonly value: Redacted<string>

Interfaces

PreparedAttempt

One prepared Attempt with a scoped checkout and repository access. Use it within the scope that prepared it. Closing that scope stops any active session before removing the checkout and releasing credentials, including when launch never starts.

Properties

launch

readonly launch: (io) => Effect<StepResult, InfraFailure | DefectFailure | AgentFailure | RunawayFailure | ChildSessionBudgetFailure>

Runs this Attempt once, recording channel activity through io. Completion, failure, or interruption releases its resources before returning. Cleanup failures are logged without replacing the agent’s outcome or retrying its work. Reusing an Attempt after launch or release fails with an infrastructure error.

Parameters

Parameter	Type
`io`	`Sink`

Returns

Effect<StepResult, InfraFailure | DefectFailure | AgentFailure | RunawayFailure | ChildSessionBudgetFailure>

workspace

readonly workspace: AttemptWorkspace

Checkout metadata suitable for inspection or serialization; contains no credentials.

Type Aliases

ExecutorError

ExecutorError = typeof ExecutorError.Type

A readiness, access, or lifecycle failure reported by a Worker operation.

ExecutorOperation

ExecutorOperation = typeof ExecutorOperation.Type

The Worker operation that failed during readiness checks or an Attempt’s lifecycle.

WorkerCapability

WorkerCapability = typeof WorkerCapability.Type

A prerequisite a Worker must satisfy before it can accept Attempts. gateway is the Gateway in front of the Worker’s machine: its admin API answers the orchestrator, and the machine reaches it.

WorktreePath

WorktreePath = typeof WorktreePath.Type

One Attempt’s disposable checkout directory.

Variables

ExecutorError

const ExecutorError: Schema.Union<readonly [typeof ExecutorOperationError, typeof CredentialUnavailableError, typeof WorkerCapabilityError]>

A readiness, access, or lifecycle failure reported by a Worker operation.

ExecutorOperation

const ExecutorOperation: Schema.Literals<readonly ["preflight", "prepare", "launch", "cancel", "cleanup"]>

The Worker operation that failed during readiness checks or an Attempt’s lifecycle.

logPreflightFailure

const logPreflightFailure: <A, R>(effect) => Effect.Effect<A, ExecutorError, R>

Logs every preflight refusal so a missing capability is explainable from logs alone.

Type Parameters

Type Parameter
`A`
`R`

Parameters

Parameter	Type
`effect`	`Effect.Effect`<`A`, `ExecutorError`, `R`>

Returns

Effect.Effect<A, ExecutorError, R>

WorkerCapability

const WorkerCapability: Schema.Literals<readonly ["machine", "toolchain", "harness-login", "credentials", "gateway"]>

A prerequisite a Worker must satisfy before it can accept Attempts. gateway is the Gateway in front of the Worker’s machine: its admin API answers the orchestrator, and the machine reaches it.

WorktreePath

const WorktreePath: Schema.brand<Schema.NonEmptyString, "WorktreePath">

One Attempt’s disposable checkout directory.