Skip to content
usine

@usine/agents/runtime

Classes

Section titled “Classes”

AgentResultError

Section titled “AgentResultError”

The session finished and reported that the work itself failed.

Extends

Section titled “Extends”
  • Schema.Class

Constructors

Section titled “Constructors”

Constructor
Section titled “Constructor”

new AgentResultError(…args): AgentResultError

Parameters
Section titled “Parameters”
Parameter Type
…args [props: object, options?: MakeOptions]
Returns
Section titled “Returns”

AgentResultError

Properties

Section titled “Properties”

message
Section titled “message”

readonly message: string

sessionId
Section titled “sessionId”

readonly sessionId: Option<string & Brand<"AgentSessionId">>

ChildBackend

Section titled “ChildBackend”

Runs the coding work delegated by an Attempt’s parent.

Extends

Section titled “Extends”
  • Context.ServiceClass

Properties

Section titled “Properties”

Service
Section titled “Service”

readonly Service: ChildBackendService

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

ChildRequest

Section titled “ChildRequest”

Work delegated to one child, with its assigned identity and the checkout it shares with the parent.

Extends

Section titled “Extends”
  • Schema.Class

Constructors

Section titled “Constructors”

Constructor
Section titled “Constructor”

new ChildRequest(…args): ChildRequest

Parameters
Section titled “Parameters”
Parameter Type
…args [props: object, options?: MakeOptions]
Returns
Section titled “Returns”

ChildRequest

Properties

Section titled “Properties”

cwd
Section titled “cwd”

readonly cwd: string & Brand<"AgentWorkingDirectory">

The checkout, on the machine host names.

environment
Section titled “environment”

readonly environment: object

The complete environment of the child’s process and every command it runs: the Worker’s allowlisted variables plus the Attempt’s credential configuration. Nothing is inherited from the process that launches the child (ADR 0011). On a RemoteShell host they are exported on top of the remote machine’s own environment, which holds no orchestrator secret.

Index Signature
Section titled “Index Signature”

[key: string]: string

host
Section titled “host”

readonly host: LocalProcess | RemoteShell

Where the child’s process runs.

prompt
Section titled “prompt”

readonly prompt: string

session
Section titled “session”

readonly session: ChildSession

ChildSessionBudgetExceededError

Section titled “ChildSessionBudgetExceededError”

The Pi parent asked for one more child than this Attempt’s budget allows.

Extends

Section titled “Extends”
  • Schema.Class

Constructors

Section titled “Constructors”

Constructor
Section titled “Constructor”

new ChildSessionBudgetExceededError(…args): ChildSessionBudgetExceededError

Parameters
Section titled “Parameters”
Parameter Type
…args [props: object, options?: MakeOptions]
Returns
Section titled “Returns”

ChildSessionBudgetExceededError

Properties

Section titled “Properties”

attemptedChildren
Section titled “attemptedChildren”

readonly attemptedChildren: number & Brand<"ChildSessionCount">

maxChildren
Section titled “maxChildren”

readonly maxChildren: number & Brand<"ChildSessionBudget">

message
Section titled “message”

readonly message: string

ClaudeChildBackend

Section titled “ClaudeChildBackend”

Runs delegated coding work with Claude Code.

Extends

Section titled “Extends”
  • Context.ServiceClass

Properties

Section titled “Properties”

Service
Section titled “Service”

readonly Service: ChildBackendService

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

CodexChildBackend

Section titled “CodexChildBackend”

Runs delegated coding work with Codex.

Extends

Section titled “Extends”
  • Context.ServiceClass

Properties

Section titled “Properties”

Service
Section titled “Service”

readonly Service: ChildBackendService

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

PiChildBackend

Section titled “PiChildBackend”

Runs delegated coding work with Pi.

Extends

Section titled “Extends”
  • Context.ServiceClass

Properties

Section titled “Properties”

Service
Section titled “Service”

readonly Service: ChildBackendService

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

PoolUnavailableError

Section titled “PoolUnavailableError”

The credential cannot spend from the billing pool this session needs.

Extends

Section titled “Extends”
  • Schema.Class

Constructors

Section titled “Constructors”

Constructor
Section titled “Constructor”

new PoolUnavailableError(…args): PoolUnavailableError

Parameters
Section titled “Parameters”
Parameter Type
…args [props: object, options?: MakeOptions]
Returns
Section titled “Returns”

PoolUnavailableError

Properties

Section titled “Properties”

harness
Section titled “harness”

readonly harness: "claude" | "codex" | "pi"

message
Section titled “message”

readonly message: string

model
Section titled “model”

readonly model: string & Brand<"ModelId">

pool
Section titled “pool”

readonly pool: "apiKeys" | "claudePlan" | "chatgptPlan"

SessionOperationError

Section titled “SessionOperationError”

The SDK or its process failed after the model and harness were validated.

Extends

Section titled “Extends”
  • Schema.Class

Constructors

Section titled “Constructors”

Constructor
Section titled “Constructor”

new SessionOperationError(…args): SessionOperationError

Parameters
Section titled “Parameters”
Parameter Type
…args [props: object, options?: MakeOptions]
Returns
Section titled “Returns”

SessionOperationError

Properties

Section titled “Properties”

cause
Section titled “cause”

readonly cause: unknown

message
Section titled “message”

readonly message: string

operation
Section titled “operation”

readonly operation: "launch" | "stream" | "steer" | "interrupt"

sessionId
Section titled “sessionId”

readonly sessionId: Option<string & Brand<"AgentSessionId">>

SessionResult

Section titled “SessionResult”

The final message a parent or child session returns.

Extends

Section titled “Extends”
  • Schema.Class

Constructors

Section titled “Constructors”

Constructor
Section titled “Constructor”

new SessionResult(…args): SessionResult

Parameters
Section titled “Parameters”
Parameter Type
…args [props: object, options?: MakeOptions]
Returns
Section titled “Returns”

SessionResult

Properties

Section titled “Properties”

message
Section titled “message”

readonly message: string

UnknownModelError

Section titled “UnknownModelError”

The rostered model id is well-formed but the SDK’s registry does not list it.

Extends

Section titled “Extends”
  • Schema.Class

Constructors

Section titled “Constructors”

Constructor
Section titled “Constructor”

new UnknownModelError(…args): UnknownModelError

Parameters
Section titled “Parameters”
Parameter Type
…args [props: object, options?: MakeOptions]
Returns
Section titled “Returns”

UnknownModelError

Properties

Section titled “Properties”

harness
Section titled “harness”

readonly harness: "claude" | "codex" | "pi"

message
Section titled “message”

readonly message: string

model
Section titled “model”

readonly model: string & Brand<"ModelId">

UnsupportedEffortError

Section titled “UnsupportedEffortError”

The model exists but does not support the rostered reasoning effort.

Extends

Section titled “Extends”
  • Schema.Class

Constructors

Section titled “Constructors”

Constructor
Section titled “Constructor”

new UnsupportedEffortError(…args): UnsupportedEffortError

Parameters
Section titled “Parameters”
Parameter Type
…args [props: object, options?: MakeOptions]
Returns
Section titled “Returns”

UnsupportedEffortError

Properties

Section titled “Properties”

effort
Section titled “effort”

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

harness
Section titled “harness”

readonly harness: "claude" | "codex" | "pi"

message
Section titled “message”

readonly message: string

model
Section titled “model”

readonly model: string & Brand<"ModelId">

Interfaces

Section titled “Interfaces”

ChildBackendService

Section titled “ChildBackendService”

Launches coding sessions for tasks delegated by an Attempt’s parent.

Properties

Section titled “Properties”

launch
Section titled “launch”

readonly launch: (request) => Effect<RunningSession, UnknownModelError | PoolUnavailableError | UnsupportedEffortError | AgentResultError | ChildSessionBudgetExceededError | SessionOperationError, Scope>

Starts the assigned child and returns its controls; its result is awaited separately.

Parameters
Section titled “Parameters”
Parameter Type
request ChildRequest
Returns
Section titled “Returns”

Effect<RunningSession, UnknownModelError | PoolUnavailableError | UnsupportedEffortError | AgentResultError | ChildSessionBudgetExceededError | SessionOperationError, Scope>

RunningSession

Section titled “RunningSession”

A live parent or child session whose activity can be observed while its work continues.

Properties

Section titled “Properties”

events
Section titled “events”

readonly events: Stream<SessionStarted | TextOutput | ToolStarted | ToolFinished | PoolRateLimitsUpdated | SessionFinished | SessionIdle | SessionResumed | SessionTokensUpdated, UnknownModelError | PoolUnavailableError | UnsupportedEffortError | AgentResultError | ChildSessionBudgetExceededError | SessionOperationError>

Activity to record in the Attempt transcript while waiting for the result.

interrupt
Section titled “interrupt”

readonly interrupt: Effect<void, UnknownModelError | PoolUnavailableError | UnsupportedEffortError | AgentResultError | ChildSessionBudgetExceededError | SessionOperationError>

Requests that this session stop its current work.

intervene
Section titled “intervene”

readonly intervene: (action) => Effect<InterventionState, UnknownModelError | PoolUnavailableError | UnsupportedEffortError | AgentResultError | ChildSessionBudgetExceededError | SessionOperationError>

Applies a nonterminal operator action; child messages hold completion until release.

Parameters
Section titled “Parameters”
Parameter Type
action Steer | Interrupt | OperatorMessage | Release
Returns
Section titled “Returns”

Effect<InterventionState, UnknownModelError | PoolUnavailableError | UnsupportedEffortError | AgentResultError | ChildSessionBudgetExceededError | SessionOperationError>

result
Section titled “result”

readonly result: Effect<SessionResult, UnknownModelError | PoolUnavailableError | UnsupportedEffortError | AgentResultError | ChildSessionBudgetExceededError | SessionOperationError>

Waits for the final message or the failure that ends this session’s work.

session
Section titled “session”

readonly session: ChildSession | ParentSession

steer
Section titled “steer”

readonly steer: (message) => Effect<void, UnknownModelError | PoolUnavailableError | UnsupportedEffortError | AgentResultError | ChildSessionBudgetExceededError | SessionOperationError>

Adds operator guidance to the running session without creating a new Attempt.

Parameters
Section titled “Parameters”
Parameter Type
message string
Returns
Section titled “Returns”

Effect<void, UnknownModelError | PoolUnavailableError | UnsupportedEffortError | AgentResultError | ChildSessionBudgetExceededError | SessionOperationError>

Type Aliases

Section titled “Type Aliases”

AgentSessionError

Section titled “AgentSessionError”

AgentSessionError = typeof AgentSessionError.Type

A session could not start, continue, or finish its work; the failure determines whether retry needs an operator.

SessionOperation

Section titled “SessionOperation”

SessionOperation = typeof SessionOperation.Type

WorkingDirectory

Section titled “WorkingDirectory”

WorkingDirectory = typeof WorkingDirectory.Type

The checkout directory one Attempt runs in.

Variables

Section titled “Variables”

AgentSessionError

Section titled “AgentSessionError”

const AgentSessionError: Schema.Union<readonly [typeof UnknownModelError, typeof PoolUnavailableError, typeof UnsupportedEffortError, typeof AgentResultError, typeof ChildSessionBudgetExceededError, typeof SessionOperationError]>

A session could not start, continue, or finish its work; the failure determines whether retry needs an operator.

BLOCKED_MARKER

Section titled “BLOCKED_MARKER”

const BLOCKED_MARKER: "[usine:blocked]" = "[usine:blocked]"

The reserved opening of a final answer that reports an unresolved blocker. Text after the marker is the blocker; the session fails with AgentResultError.

SESSION_OPERATIONS

Section titled “SESSION_OPERATIONS”

const SESSION_OPERATIONS: readonly ["launch", "stream", "steer", "interrupt"]

SessionOperation

Section titled “SessionOperation”

const SessionOperation: Schema.Literals<readonly ["launch", "stream", "steer", "interrupt"]>

toAttemptFailure

Section titled “toAttemptFailure”

const toAttemptFailure: (error) => AttemptFailure

Maps session errors onto the retry taxonomy: an SDK or process failure is retryable infrastructure, while a bad roster spec or the agent failing its own work waits for the operator (ADR 0002).

Parameters

Section titled “Parameters”
Parameter Type
error AgentSessionError

Returns

Section titled “Returns”

AttemptFailure

WorkingDirectory

Section titled “WorkingDirectory”

const WorkingDirectory: Schema.brand<Schema.NonEmptyString, "AgentWorkingDirectory">

The checkout directory one Attempt runs in.

GuidesArchitectureReferenceGitHub

Guides

Run a factoryWrite a LoopWrite an AgentOperate RunsBounded review and fix LoopsAdd a Worker

Architecture

Architecture overviewRun lifecycleHow an Attempt runsWorkers and the GatewayStorage and configurationOperator surfacesThe dogfood instance's LoopsGaps

Reference

Overview