Skip to content
v9.1.1
Français

Agent

import type { Agent } from "@elie-laloum/outpost";

Parameters and properties

Section titled “Parameters and properties”

The fields below cover all variants; the signature specifies their allowed combinations.

  • kindRequired
    "cli" | "custom" | "replay"
    Execution discriminator: cli, custom or replay.
  • harnessVariant-dependent
    CliHarness | Harness
    Harness the agent was composed with: a CLI preset or the built-in harness. Absent on a replay agent.
  • modelVariant-dependent
    AgentModel | undefined | AgentModel
    Normalized frozen AgentModel of the composed agent; absent when a CLI harness keeps its native default, and on a replay agent.
  • forkVariant-dependent
    ((id: string, invoke: (command: Command) => Promise<CommandResult>) => Promise<string>) | undefined
    Native fork preparation: receives the parent ID and a command executor on the borrowed sandbox, and returns a distinct child ID that Outpost then continues. Adapters with a fork flag can omit it.
  • credentialsVariant-dependent
    ((variables: Variables) => CredentialPlan) | undefined
    Plan the credentials of this CLI from the resolved workflow variables, without disk access: variables to forward, host files to copy into the private sandbox home, generated files and login commands. Called once per adapter and sandbox; the local provider receives only the variables.
  • configurationVariant-dependent
    ((variables: Variables) => AgentConfiguration) | undefined
    Plan CLI configuration from the resolved variables, without disk access: files to merge and host files to copy into the agent home once per sandbox, after authentication. Throw when a referenced variable is missing.
  • requestVariant-dependent
    (input: AgentInput) => Command
    Build the executable, arguments and environment for the supplied agent input.
  • eventsVariant-dependent
    (line: string) => readonly AgentEvent[]
    Decode one native CLI output line into normalized agent events.
  • quotaVariant-dependent
    ((text: string) => boolean) | undefined
    Recognize a terminal usage-limit or rate-limit message in a failure event or stderr line. When the process then fails, the turn rejects with OutpostError code quota instead of process; transient retry notices must not match.
  • unavailableVariant-dependent
    ((text: string) => boolean) | undefined
    Recognize a terminal service outage or connection failure in a failure event or stderr line. When the process then fails without a quota signal, the turn keeps code process and records details.unavailable, read by unavailableFault(); retry notices must not match.
  • usageCommandVariant-dependent
    ((conversation: string) => Command | undefined) | undefined
    Build a bounded read-only command to collect counters for this conversation inside the borrowed sandbox; return undefined for an unsupported identifier.
  • usageResultVariant-dependent
    ((text: string) => Usage | undefined) | undefined
    Decode the successful usage command’s stdout into session totals. Return undefined when unreadable, or complete: false for partial totals; do not return transcript content.
  • liveInputVariant-dependent
    AgentLiveInput | undefined
    Protocol for adding user messages to a running turn over stdin, used when the lease supports live input: Claude Code stream-json and Codex app-server. Otherwise steering stops the turn and resumes its conversation.
  • nameRequired
    string
    Native agent identifier used in execution events and diagnostics.
  • bootstrapOptional
    string | undefined
    Built-in agent whose pinned CLI Outpost installs on a remote sandbox when the executable is missing: an npm package, or a SHA-512-verified archive for antigravity. An unknown name fails.
  • requiresFinishedEventOptional
    boolean | undefined
    Require the native final event: without it, completion markers do not match and the turn fails with code process, even when the process exits with 0.
  • usageOptional
    "events" | "session" | "unavailable" | undefined
    How token usage is measured: events reads it from the output stream, session reads the session after the process exits, unavailable records none. Missing counters then mark usage incomplete; omitted, reported events are counted without that check.
  • variablesOptional
    Readonly<Record<string, string>> | undefined
    Environment variables added to every command of this agent, over the values from .outpost/.env. A name also set by the sandbox provider fails with code configuration.
  • storageOptional
    ConversationStore | undefined
    Conversation store that captures, locates and restores this agent’s sessions; absent when its conversations are not portable.
  • captureVariant-dependent
    boolean | undefined | boolean | boolean | undefined
    Save the conversation to storage after each turn; false skips it. Omitted, a turn is saved whenever storage is present.
  • resumableVariant-dependent
    boolean | undefined | boolean | boolean | undefined
    Whether the agent can continue a conversation, as continuation, response repairs and resume-based steering require; false rejects continuation before allocation. Cold continuation also needs storage.
  • forkableOptional
    boolean | undefined
    Whether the agent can fork a conversation; false rejects fork before allocation. Omitted, fork is attempted through request() or the fork hook.
  • transcriptUsageOptional
    ((text: string) => Usage | undefined) | undefined
    Read token usage from the transcript captured after the turn; a result replaces the usage reported by events, undefined keeps it.
  • sourceVariant-dependent
    "harness" | "agent"
    Observation source used for replayed events: harness when the journal came from the Outpost harness, otherwise agent.
  • divergenceVariant-dependent
    ReplayDivergencePolicy
    Divergence policy, fail by default: fail throws ReplayDivergence; warn reports prompt, baseline and tree differences as warnings and continues.
  • turnsVariant-dependent
    readonly ReplayTurn[]
    Recorded turns parsed from the journal, in execution order.
  • remainingTurnsVariant-dependent
    number
    Number of recorded turns not yet consumed by a dispatch; 0 after a complete replay.
  • nextTurnVariant-dependent
    () => ReplayTurn | undefined
    Consume and return the next recorded turn, or undefined when the journal is exhausted. Dispatch calls it once per turn; a replay agent is single-use.
  • pendingSteeringVariant-dependent
    () => readonly string[] | undefined
    For a replay agent, the recorded instructions that resumed the next turn, without consuming it; dispatch uses them to continue a steered pass as recorded.

Signature

Section titled “Signature”
export type Agent = CliAgent | CustomAgent | ReplayAgent;
Section titled “Related contracts”