Skip to content
v9.1.1
Français

Workspace

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

Parameters and properties

Section titled “Parameters and properties”
  • dispatchRequired
    <T = undefined>(options: Omit<SandboxOptions, Exclude<keyof WorkspaceOptions, "hooks" | "label"> | "workspace"> & DispatchOptions<T> & { readonly agent: DispatchAgent; }) => Promise<DispatchResult<T>>
    Run a dispatch in a new sandbox on this workspace. On success it merges an integrate branch, then closes the sandbox and leaves the workspace open. Fails with code configuration while another sandbox holds the workspace or after close().
  • sandboxRequired
    (options?: Omit<SandboxOptions, Exclude<keyof WorkspaceOptions, "hooks" | "label"> | "workspace">) => Promise<Sandbox>
    Allocate a reusable sandbox on this workspace. Hooks passed to it replace the workspace’s hostReady and sandboxReady; closing it leaves the workspace open and never merges. A second open sandbox fails with code configuration.
  • attachRequired
    (options: Omit<SandboxOptions, Exclude<keyof WorkspaceOptions, "hooks" | "label"> | "workspace"> & AttachOptions & { readonly agent: Agent; }) => Promise<AttachResult>
    Open an interactive agent terminal in a new sandbox on this workspace. When the terminal exits with status 0 it merges an integrate branch; the sandbox closes and the workspace stays open.
  • closeRequired
    (options?: { readonly preserve?: boolean; }) => Promise<Disposal>
    Release the lock and remove a clean managed worktree; an integrate branch is deleted once merged, a named branch is kept. With preserve: true, a detached HEAD or uncommitted, untracked or ignored files, the worktree stays and is returned as retainedDirectory. Fails with code configuration while a sandbox is open; later calls return the first result.
  • integrateRequired
    () => Promise<void>
    Merge the integrate branch into the base branch with git merge —no-edit in the host checkout; does nothing in current and named modes. Fails with code conflict when the host checkout switched branches, another integration holds the merge lock or the merge fails; the work branch stays.
  • [Symbol.asyncDispose]Required
    () => Promise<void>
    Close the workspace like close() without options, for await using.
  • repositoryRequired
    string
    Real path of the host checkout’s top-level directory.
  • directoryRequired
    string
    Host directory the agent works in: the worktree under .outpost/workspaces, or the checkout itself in current mode.
  • branchRequired
    string
    Work branch name. In current mode, the checked-out branch, or HEAD when detached.
  • baseBranchRequired
    string
    Branch checked out in the host checkout when the workspace opened, and the target of integrate(). Empty when HEAD was detached.
  • baselineRequired
    string
    Commit checked out in the workspace when it opened. Each dispatch lists commits from its own starting commit, not from this one.
  • gitDirectoriesRequired
    readonly string[]
    Host paths of the worktree’s Git directory and the repository’s common Git directory. Container providers mount them unless repositoryMode is isolated.
  • policyRequired
    BranchPolicy
    Branch policy in effect, { mode: “current” } when none was given.

Signature

Section titled “Signature”
export interface Workspace extends WorkspaceRecord {
  dispatch<T = undefined>(
    options: Omit<
      SandboxOptions,
      Exclude<keyof WorkspaceOptions, "hooks" | "label"> | "workspace"
    > &
      DispatchOptions<T> & {
        readonly agent: DispatchAgent;
      },
  ): Promise<DispatchResult<T>>;
  sandbox(
    options?: Omit<
      SandboxOptions,
      Exclude<keyof WorkspaceOptions, "hooks" | "label"> | "workspace"
    >,
  ): Promise<Sandbox>;
  attach(
    options: Omit<
      SandboxOptions,
      Exclude<keyof WorkspaceOptions, "hooks" | "label"> | "workspace"
    > &
      AttachOptions & {
        readonly agent: Agent;
      },
  ): Promise<AttachResult>;
  close(options?: { readonly preserve?: boolean }): Promise<Disposal>;
  integrate(): Promise<void>;
  [Symbol.asyncDispose](): Promise<void>;
}
Section titled “Related contracts”