Skip to content

Client and run handle

Async Python SDK for submitting and observing Zeroshot runs.

Client(*, target: Target | None = None, preset: Preset | None = None, runtime: _Runtime | None = None, environment: Mapping[str, str] | None = None, forward_github_token: bool = False)

Submit and observe Zeroshot graph runs and hosted stacks.

Parameters:

  • target (Target | None, default: None ) –

    Local target by default, an unauthenticated direct target, or a named hosted target.

  • preset (Preset | None, default: None ) –

    Default executable-owned graph preset. None selects software-change.

  • runtime (_Runtime | None, default: None ) –

    Default runtime. None requires a runtime on each string submission.

  • environment (Mapping[str, str] | None, default: None ) –

    Submission environment values. None reads the ambient environment; an explicit mapping replaces ambient credential variables. Native saved connections and local harness login still apply.

  • forward_github_token (bool, default: False ) –

    Send the submission environment's GH_TOKEN to a direct or hosted target. Without it, the target resolves GitHub access from its own stored connection and GH_TOKEN is not sent. Requires GH_TOKEN in the submission environment.

Raises:

The SDK never guesses a harness, provider, or model. Closing the client detaches observation and never stops runs.

__aenter__() -> Client async

Open the client and capture a default working folder.

Returns:

Raises:

__aexit__(exc_type: type[BaseException] | None, exc: BaseException | None, traceback: object) -> None async

Close client-owned routing state without stopping durable runs.

aclose() -> None async

Release client-owned routing state without stopping submitted runs.

run(task: str | RunRequest, **options: Unpack[_RunOptions]) -> RunResult async

run(task: str, **options: Unpack[_RunOptions]) -> RunResult
run(
    task: RunRequest, *, wait_timeout: float | None = None
) -> RunResult

Submit one graph run and wait for its terminal result.

Parameters:

  • task (str | RunRequest) –

    Task text for a built-in preset, or a complete RunRequest.

  • options (Unpack[_RunOptions], default: {} ) –

    Typed keyword options. title, preset, runtime, cwd, worktree, worktree_base, repository, source_connection, branch, revision, and submission_key apply to string submissions. worktree defaults to False; worktree_base accepts local or remote. See RunRequest for local-only worktree and cleanup semantics. wait_timeout is a non-negative observation deadline in seconds; omit it to wait indefinitely.

Returns:

  • RunResult –

    The terminal result. Graph failure remains data until raise_for_failure() is called.

Raises:

  • InvalidRequestError –

    If a string submission has no effective preset or runtime, or Zeroshot rejects the request.

  • RunWaitTimeout –

    If observation expires; its run attribute can resume waiting.

  • RunSuspendedError –

    If the attempt suspends; carries its run handle and status.

  • TargetError –

    If the sidecar or selected target is unavailable.

  • ProtocolError –

    If native output is malformed or incompatible.

Cancellation detaches observation and leaves the durable run active.

submit(task: str | RunRequest, **options: Unpack[_SubmitOptions]) -> Run async

submit(task: str, **options: Unpack[_SubmitOptions]) -> Run
submit(task: RunRequest) -> Run

Preflight in Zeroshot, submit one durable run, and return its handle.

Parameters:

  • task (str | RunRequest) –

    Task text for a built-in preset, or a complete RunRequest.

  • options (Unpack[_SubmitOptions], default: {} ) –

    Typed keyword options for string submissions: title, preset, runtime, cwd, worktree, worktree_base, repository, source_connection, branch, revision, and submission_key. worktree defaults to False; worktree_base accepts local or remote. See RunRequest for local-only worktree and cleanup semantics.

Returns:

  • Run –

    A durable run handle bound to this client's target.

Raises:

Exact RunRequest values cannot be combined with string-submission overrides. Preflight completes before local controller startup or direct-target contact.

submit_stack(request: StackRequest) -> Stack async

Validate and atomically submit one stack of runs to a hosted target.

Parameters:

  • request (StackRequest) –

    Immutable stack metadata, profile selector, delivery mode, and static run DAG.

Returns:

  • Stack –

    A durable stack handle bound to this client's hosted target.

Raises:

get_stack(stack_id: str) -> Stack

Reconstruct a durable hosted stack handle without target I/O.

Parameters:

  • stack_id (str) –

    Opaque server-assigned stack identity.

Returns:

  • Stack –

    A handle resolved lazily against this client's named hosted target.

Raises:

get_run(run_id: str) -> Run

Reconstruct a durable handle without target I/O.

Parameters:

  • run_id (str) –

    Opaque public run identity.

Returns:

  • Run –

    A handle resolved lazily against this client's target.

Raises:

list_runs() -> tuple[RunSummary, ...] async

Return summaries for runs retained by this client's target.

list_presets() -> tuple[str, ...] async

Return built-in preset names read dynamically from the bundled executable.

list_targets() -> tuple[NamedTarget, ...] async

List local registrations, including platform, without contacting any target.

This reads the user's registry independently of this client's run target.

remove_target(name: str) -> TargetRemoveResult async

Remove a local registration, its stored login and resume permissions.

Parameters:

  • name (str) –

    Exact local target name.

Returns:

Raises:

get_preset(name: str, *, delivery: str | None = None) -> GraphSpec async

Read one built-in preset from the bundled executable.

Parameters:

  • name (str) –

    Exact native preset name.

  • delivery (str | None, default: None ) –

    Native delivery selector. None uses the executable-owned template default.

Returns:

  • GraphSpec –

    The GraphSpec emitted by Zeroshot, copied without changes.

Raises:

inbox(after: str | None = None, limit: int = 50) -> InboxPage async

Read requests still holding their runs suspended without applying expiry.

Parameters:

  • after (str | None, default: None ) –

    Exclusive run ID cursor, or None for the first page.

  • limit (int, default: 50 ) –

    Maximum entries, from 1 through 100.

Returns:

  • InboxPage –

    The request page and its next cursor.

Raises:

  • ValueError –

    If limit is outside 1 through 100.

Run(client: Client, run_id: str)

Durable public run handle bound to one Client target.

id: str property

Return the opaque public Zeroshot run identity.

status() -> RunStatus async

Read the current durable run status.

Returns:

  • RunStatus –

    The latest target projection.

Raises:

watch(*, after: str | None = None) -> AsyncIterator[RunStatus]

Open a durable status stream strictly after an optional cursor.

Parameters:

  • after (str | None, default: None ) –

    Last consumed opaque status cursor. None replays retained history.

Returns:

  • AsyncIterator[RunStatus] –

    An async iterator of immutable status snapshots.

Cancelling or closing the iterator detaches observation and does not stop the run.

logs(*, after: str | None = None, execution: str | None = None) -> AsyncIterator[LogEvent]

Open the durable redacted log stream with resume and execution filters.

Parameters:

  • after (str | None, default: None ) –

    Last consumed opaque log cursor. None replays retained logs.

  • execution (str | None, default: None ) –

    Opaque execution selector from RunStatus, or None for all records.

Returns:

  • AsyncIterator[LogEvent] –

    An async iterator of safe native log records.

Cancelling or closing the iterator detaches observation and does not stop the run.

wait(*, wait_timeout: float | None = None) -> RunResult async

Wait for the durable terminal result without controlling run lifetime.

Parameters:

  • wait_timeout (float | None, default: None ) –

    Non-negative observation deadline in seconds. None waits indefinitely.

Returns:

  • RunResult –

    The successful or failed terminal result.

Raises:

  • ValueError –

    If wait_timeout is negative.

  • RunWaitTimeout –

    If the deadline expires. The exception carries this run handle.

  • RunSuspendedError –

    If the attempt suspends; carries this handle and its status.

  • RunNotFoundError –

    If the target no longer retains this run.

  • TargetError –

    If observation fails.

  • ProtocolError –

    If native output is malformed.

Python task cancellation remains asyncio.CancelledError and leaves the run active.

suspend() -> RunStatus async

Request suspension and return the status immediately.

Returns:

  • RunStatus –

    The current durable status with the suspension request recorded.

resume() -> Run async

Continue this attempt in a successor with fresh native sessions.

Returns:

  • Run –

    The successor run handle.

request() -> InboxRequest async

Read the request this run made, including its state and successor.

Returns:

  • InboxRequest –

    The complete inbox request. Inherited requests are excluded.

answer(answer: JsonValue) -> Run async

Answer this run's request and start one successor on the retained workspace.

Parameters:

  • answer (JsonValue) –

    Complete verifier result with signals and output matching the request.

Returns:

  • Run –

    The successor run handle. Invalid, repeated and late answers raise the CLI error.

steer(text: str, *, mode: Literal['once', 'standing'] = 'standing') -> RunSteer async

Record direction without continuing a suspended run.

Parameters:

  • text (str) –

    Nonblank UTF-8 direction, at most 262,144 bytes. Do not include secrets.

  • mode (Literal['once', 'standing'], default: 'standing' ) –

    Standing once per provider conversation, or once per node instance.

Returns:

  • RunSteer –

    The recorded steer, including its vector identity and receipt summary.

Raises:

  • ValueError –

    If mode is neither once nor standing.

  • RunNotFoundError –

    If the run is no longer retained.

  • TargetError –

    If the run refuses steering or transport fails.

  • ProtocolError –

    If native output is malformed.

vectors(*, after: str | None = None, limit: int = 50) -> RunVectorsPage async

Read one ordered page of the vector record.

Parameters:

  • after (str | None, default: None ) –

    Opaque entry cursor, or None for the first page.

  • limit (int, default: 50 ) –

    Number of entries, from 1 through 100.

Returns:

Raises:

  • ValueError –

    If limit is outside 1 through 100.

vector(id: str) -> RunVector async

Read a vector entry with its complete content.

Parameters:

  • id (str) –

    Opaque entry identity.

Returns:

force_stop() -> RunResult async

Force-stop this run and wait for its durable terminal result.

Returns:

  • RunResult –

    The existing terminal result, or a failed result whose reason is force_stopped.

Raises:

discard_workspace() -> bool async

Delete this run's retained workspace or local recovery-lineage checkpoints.

Local runs keep their checkout, ledger, logs and delivery recovery state. Running or resuming lineage members refuse deletion; an uncontinued suspension must be force-stopped first, and an interrupted restore must be completed. A plain local resume still uses the current checkout.

Returns:

  • bool –

    Whether retained workspace or checkpoint data was deleted.

Raises:

Stack(client: Client, stack_id: str)

Durable hosted stack handle bound to one Client target.

A "stacked_pull_requests" stack is complete once every pull request is open; Zeroshot never merges, retargets, or restacks them. Merge them from the bottom up: GitHub moves a child pull request onto the base branch when its merged parent's branch is deleted. A squash-merged parent leaves the child to rebase onto the base branch, and changes pushed to a parent pull request during review are not restacked, so rebase the pull requests above it by hand.

id: str property

Return the opaque server-assigned stack identity.

status() -> StackStatus async

Read the stack's current aggregate status.

watch() -> AsyncIterator[StackStatus]

Poll and yield changed aggregate snapshots until the stack is terminal.

Cancelling or closing the iterator detaches observation and leaves runs active.

wait(*, wait_timeout: float | None = None) -> StackStatus async

Wait for a terminal aggregate status without controlling stack lifetime.

Parameters:

  • wait_timeout (float | None, default: None ) –

    Non-negative observation deadline in seconds. None waits indefinitely.

Raises:

  • ValueError –

    If wait_timeout is negative.

  • StackWaitTimeout –

    If observation expires; it carries this durable handle.

  • TargetError –

    If the selected target is unavailable.

  • ProtocolError –

    If native output is malformed.

force_stop() -> StackStatus async

Force every nonterminal run to stop and wait for aggregate termination.

await run.steer(text) returns a RunSteer receipt for standing direction. It follows the handle's local or named-target route, leaves suspended runs suspended and uses the existing typed errors. Pass mode="once" to deliver once per node instance; mode="standing" remains the default. Read complete text through Run.vector(receipt.id).