Documentation
¶
Overview ¶
Package worker is the BYOC (bring-your-own-compute) consumer of the work queue: the customer-hosted twin of internal/executor. Where the executor runs inside the platform with direct database access, a worker runs in the customer's own network and reaches the control plane only over the wire — authenticating with its environment key, reading a session's suspended tool calls through the session events API, running the built-in toolset in a local sandbox, and posting the results back as user.tool_result events. Platform executor and BYOC worker are the same pull protocol at two deployment points; this is the self_hosted one.
This package is the tool-exec driver only (slice 8, PR C2a): given a session id, run its outstanding tools once. The lease loop that polls the work queue, acknowledges, heartbeats, and drives this driver — plus the cmd/worker binary that wires it to configuration — is a later increment.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewClient ¶
NewClient builds the SDK client a worker uses to reach the control plane's session API. The worker authenticates with its environment key as a Bearer token — the wire's worker credential, scoped to one environment's work queue and distinct from the management x-api-key. The control plane routes a session-events request to its environment-key lane only when a Bearer is present and no x-api-key is; WithoutEnvironmentDefaults guarantees the latter by keeping the SDK from autoloading an ambient ANTHROPIC_API_KEY (which it would otherwise send as x-api-key) underneath the explicit options.
baseURL points at the control plane (e.g. an on-prem deployment's URL), never a hard-coded api.anthropic.com — a worker talks to the platform it belongs to.
func RunSessionTools ¶
func RunSessionTools(ctx context.Context, client sdk.Client, provider sandbox.Provider, sessionID string, cfg ToolExecConfig) error
RunSessionTools is the BYOC worker's tool-exec driver: given a session whose turn has suspended for built-in tool calls, it runs every unanswered tool in the session's sandbox and posts a user.tool_result for each back through the session events API. It is the self_hosted twin of the platform executor's per-item processing, with two deployment differences: the transport is HTTP (the worker has no database), and the result event is user.tool_result, not agent.tool_result — the control plane resumes the brain when a result completes the outstanding set, so the worker never enqueues a turn itself.
Results are posted per tool as each completes, so a backend fault partway through leaves the tools that did run answered on the log; a reclaiming pass re-derives only the still-unanswered ones. This matches the executor's partial-commit-on-fault: a tool-level failure (missing file, nonzero exit) still yields a result the model must see, and only a backend fault (sandbox gone) stops the set with the rest left for the reclaim.
The sandbox is provisioned only when there is unanswered work, so a call against an already-answered session (a redundant reclaim) is a cheap couple of reads with nothing to run.
Session liveness is the caller's gate, not this driver's. The platform executor refuses to run a stale session's tools by loading its status under the session row lock (executor.sessionForRun) before provisioning — but it does so in its per-item orchestration, not in its runTools core, which this driver is the analog of. The BYOC caller (the lease loop, PR C2b) owns the same session load: it must read the session (for the same reason it must load the egress policy this cfg.Networking carries) and skip a session that is not running or is archived, mirroring sessionForRun. The control plane is only a partial backstop here — a post to an archived session is refused (400), but a post to a merely not-running one appends without resuming — so the complete gate belongs in the caller, not in a reliance on the append being rejected.
Types ¶
type Config ¶
type Config struct {
EnvironmentID string
// WorkerID identifies this worker for the control plane's poll metrics
// (Anthropic-Worker-ID). Auto-generated as "<hostname>-<random>" when empty,
// as the reference does.
WorkerID string
Image string
Workdir string
Networking domain.Networking
// EmptyPollSleep is the wait between empty polls (default 1s). Our poll is
// non-blocking, so this — not block_ms — spaces reconnections.
EmptyPollSleep time.Duration
// HeartbeatInterval, when > 0, fixes the heartbeat cadence; otherwise it is
// derived from each heartbeat response's ttl (ttl/2, clamped to
// [heartbeatFloor, heartbeatCap]) as the reference does. Tests set a small
// value; production leaves it 0.
HeartbeatInterval time.Duration
}
Config configures the BYOC worker lease loop. The worker owns its sandbox shape (Image/Workdir/Networking) rather than loading a per-session egress policy — a self_hosted worker runs on the customer's own compute and the wire exposes no per-session networking to it, so this mirrors the platform executor's Config, whose sandbox settings are likewise a deployment choice.
type ToolExecConfig ¶
type ToolExecConfig struct {
Image string
Workdir string
Networking domain.Networking
}
ToolExecConfig is the sandbox shape a worker provisions for a session's tools. A self_hosted environment's wire config carries no image (the sandbox image is a deployment choice, not part of the domain model), so Image and Workdir come from the worker's own configuration — mirroring the platform executor's Config. Networking is the session's egress policy, read from the session's environment and threaded in by the caller.
type Worker ¶
type Worker struct {
// contains filtered or unexported fields
}
Worker is the BYOC lease loop, the self_hosted twin of the platform executor. It polls the control plane's self_hosted work queue over HTTP, acknowledges an item, keeps its lease alive with heartbeats while the C2a tool-exec driver runs the session's tools in a local sandbox, and force-stops the item when the run ends. One session at a time, mirroring the reference `ant beta:worker`.
func NewWorker ¶
NewWorker builds a worker over an SDK client (see NewClient) and a local sandbox provider (the customer's Docker/K8s).
func (*Worker) Run ¶
Run polls until ctx is cancelled, handling one work item at a time. A poll that fails with an auth error (a bad environment key) is fatal and returns the error; any other poll error backs off and retries, so a transient network blip does not kill the worker. Cancellation (SIGINT/SIGTERM via the caller's signal context) ends the loop with a nil error.
Source Files