dispatch

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

Purpose and behavior

Run a brief in a sandbox allocated for this call, integrate the branch on success, then close the sandbox. On failure the sandbox closes, the worktree is kept and the error’s recovery names the branch and directory. With passes above 1, each pass is a separate dispatch that stops once a completion marker matches.

Complete example and detailed rules.

Parameters and properties

optionsRequired
DispatchRequest<T>
Sandbox settings (repository, branch, provider, hooks) combined with the agent, brief, response contract and limits.
options.includeUncommittedOptional
boolean | undefined
Remote providers only: also send the managed worktree’s uncommitted changes and untracked, non-ignored files, default false. Without it, synchronization fails with code workspace when the sandbox touches one of those files, which includes any copies entry not ignored by a committed .gitignore.
options.agentOptional
CliAgent | CustomAgent | ReplayAgent | FallbackAgent
Default agent for dispatch(), resume(), fork() and attach() on this sandbox; an operation’s own agent replaces it. On a remote provider with bootstrap on, its first candidate is installed during allocation; attach() rejects a fallback agent on every provider.
options.sandboxProviderOptional
SandboxProvider | undefined
Provider that allocates the environment, default createDockerSandboxProvider(). A remote provider requires a named or integrate branch and defaults branch to integrate.
options.workspaceOptional
Workspace | undefined
Open workspace to run in, from openWorkspace(); close() leaves it open. Combining it with repository, branch, copies or storageQuota, or passing a workspace already bound to an open sandbox, fails with code configuration.
options.hooksOptional
LifecycleHooks | undefined
Setup commands, each required to exit 0 within its deadlineMs, default 600000 (10 minutes): workspaceReady on the host once a new worktree exists, then hostReady (host, in order) and sandboxReady (sandbox, all at once) concurrently; a nonzero exit fails setup with code process. With a supplied workspace, workspaceReady does not run and hooks given here replace the workspace’s hostReady and sandboxReady.
options.signalOptional
AbortSignal | undefined
Aborting it cancels sandbox setup: allocation, repository seeding, agent installation and setup hooks. createSandbox() stops watching it once the sandbox is returned.
options.loggingOptional
Logging | undefined
Journal of each dispatch on this sandbox, default a local journal under .outpost/storage; stdout prints progress instead, false disables it, and an object sets transporter, verbose and replayable. A dispatch’s own logging replaces it.
options.bootstrapOptional
boolean | undefined
Install a built-in CLI agent missing from a remote sandbox, at its pinned version, before its first use; default true. Mounted and host providers never install: the CLI must be in the image or on the host.
options.conversationHomeOptional
string | undefined
Host directory used in place of your home directory to store and find captured native conversations. Default: your home directory for Claude and Codex transcripts, the repository for Copilot and Kimi session bundles.
options.recoveryTransportOptional
Transport | undefined
Remote providers only: before pulled changes are applied, archive the host backup to this transport as well as to .outpost/recovery. Archives outlive the sandbox.
options.activityTransportOptional
Transport | undefined
Transport for this sandbox’s resource activity record, default local storage under .outpost/storage. The record is deleted after a clean close and kept with a failure phase when cleanup fails.
options.observationOptional
ObservationHub | undefined
Hub that receives this workspace’s Git, copy, hook, integration and cleanup operations. The caller keeps ownership; the workspace never closes it.
options.storageQuotaOptional
Omit<StorageReservationOptions, "signal"> | undefined
Storage admission checked before the workspace opens: reserves reserveBytes and fails with code configuration when usage under .outpost plus active reservations would exceed maxBytes. The reservation is released when the workspace closes.
options.repositoryOptional
string | undefined
Path inside the host Git checkout, default the process working directory. Outpost works from the checkout’s top-level directory; an unavailable directory fails with code workspace.
options.branchOptional
BranchPolicy | undefined
Branch policy: current, named or integrate. Default { mode: “current” }; createSandbox() and dispatch() on a remote provider default to integrate.
options.copiesOptional
readonly string[] | undefined
Repository-relative files or directories copied from the host checkout into the new worktree before workspaceReady; missing entries are skipped. Requires named or integrate, and absolute, .. or .git paths fail with code configuration. An untracked or ignored copy keeps the worktree when it closes. On a remote provider without includeUncommitted, a copy not ignored by a committed .gitignore makes the first synchronization fail with code workspace.
options.limitsOptional
StageLimits | undefined
Deadlines in milliseconds for copying, Git preparation, commit collection and integration. Past a deadline the stage fails with code timeout, or conflict for integration.
options.labelOptional
string | undefined
Name used in the integrate branch (outpost/<label>-<id>), the worktree directory under .outpost/workspaces and the startup-failure journal; lowercased, other characters replaced by -, cut to 48.
options.briefRequired
Brief
Task given to the agent: literal text or a file brief.
options.passesOptional
number | undefined
Maximum passes, default 1. Each pass reruns the brief in a new conversation and the dispatch stops at the first pass whose text contains a completion marker. Must be 1 with response or continuation.
options.untilOptional
string | readonly string[] | undefined
Completion marker or markers searched in the last turn’s text, default <outpost>done</outpost>. An empty list disables matching, so every pass runs; empty strings are rejected.
options.idleMsOptional
number | undefined
Longest silence allowed from the agent, default 600000 (10 minutes). Past it the turn stops with code timeout.
options.idleWarningMsOptional
number | undefined
Silence after which a warning event is emitted, then repeated at the same interval; default 60000.
options.settleMsOptional
number | undefined
Wait after a completion marker before stopping an agent that is still running, default 60000. The turn still succeeds.
options.deadlineMsOptional
number | undefined
Maximum duration of each agent process, default 3600000 (one hour). Past it the turn fails with code timeout.
options.expansionMsOptional
number | undefined
Deadline for each shell expansion in a file brief, default 30000. Past it the dispatch fails with code timeout.
options.steeringOptional
Steering | undefined
Controller from createSteering(), attached for the whole dispatch and released when it ends. resume() and fork() do not reuse it.
options.continuationOptional
{ readonly id: string; readonly fork?: boolean; } | undefined
Native conversation to continue, by id; fork: true continues a copy and leaves the original unchanged. Requires one pass and an agent that supports resume.
options.responseOptional
ResponseSpec<T> | undefined
Typed response contract: the tagged answer is parsed and validated, and an invalid answer gets up to repairs correction turns. Requires one pass.
options.telemetryOptional
DispatchTelemetry | undefined
Instrumentation spanning the whole dispatch, including preparation, synchronization and cleanup. Its failures do not change the outcome.
options.observeOptional
((event: AgentObservation) => void) | undefined
Receives each normalized agent event with its pass number and timestamp. An exception thrown here is collected in observerErrors and does not change the outcome.
options.warnOptional
((message: string) => void) | undefined
Receives nonfatal warnings, such as an idle agent or a conversation storage problem.
options.diagnosticOptional
((message: string) => void) | undefined
Receives diagnostic messages, such as the estimated token size of each expanded brief command.

Returns

Promise<DispatchResult<T>>

Signature

export declare function dispatch<T = undefined>(
  options: DispatchRequest<T>,
): Promise<DispatchResult<T>>;

Purpose and behavior

Parameters and properties

Returns

Signature

Related contracts