workspaceagent

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 21, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package workspaceagent defines the stable workspace.orka.ai/v1 data-plane protocol and its transport-safe HTTP client. The package is public so out-of-tree provider adapters can pin a tagged Orka module without importing internal implementation packages. Secured agents require a full reset using the current binding generation before the first attachment after every agent process start or restart.

Index

Constants

View Source 
const (
	// ProtocolVersion is carried by every versioned workspace-agent DTO.
	ProtocolVersion = "workspace.orka.ai/v1"

	HealthPath              = "/v1/health"
	LegacyHealthPath        = "/healthz"
	CapabilitiesPath        = "/v1/capabilities"
	AttachmentControlPath   = "/v1/control/attachment"
	AttachmentControlPrefix = AttachmentControlPath + "/"
	ExecPath                = "/v1/exec"
	ExecStatusPrefix        = ExecPath + "/"
	FilesPath               = "/v1/files"
	FilesDownloadPath       = "/v1/files/download"
	ScrubPath               = "/v1/scrub"
	ResetPath               = "/v1/reset"

	WorkspaceUIDHeader    = "X-Orka-Workspace-UID"
	AttachmentEpochHeader = "X-Orka-Workspace-Epoch"
)

Variables

This section is empty.

Functions

func AttachmentRevocationPath 

func AttachmentRevocationPath(epoch string) string

AttachmentRevocationPath returns the escaped revocation endpoint for epoch.

func ExecCancelPath 

func ExecCancelPath(operationID string) string

ExecCancelPath returns the escaped cancellation endpoint for operationID.

func ExecStatusPath 

func ExecStatusPath(operationID string) string

ExecStatusPath returns the escaped status endpoint for operationID.

Types

type Artifact 

type Artifact struct {
	Path    string    `json:"path"`
	Size    int64     `json:"size"`
	Digest  string    `json:"digest"`
	Mode    uint32    `json:"mode"`
	ModTime time.Time `json:"modTime"`
}

Artifact is safe metadata for one workspace file.

type AttachmentControlRequest 

type AttachmentControlRequest struct {
	Versioned
	WorkspaceUID      string    `json:"workspaceUID"`
	BindingGeneration string    `json:"bindingGeneration"`
	TaskUID           string    `json:"taskUID"`
	Epoch             int64     `json:"epoch"`
	TokenSHA256       string    `json:"tokenSHA256"`
	ExpiresAt         time.Time `json:"expiresAt"`
}

AttachmentControlRequest activates one exclusive attachment epoch. TokenSHA256 is the digest of the bearer token; the raw token is never sent on this endpoint.

func (*AttachmentControlRequest) SetTokenDigest 

func (r *AttachmentControlRequest) SetTokenDigest(value string)

SetTokenDigest sets the SHA-256 attachment bearer digest without exposing the raw bearer on the privileged control request.

type AttachmentControlResponse 

type AttachmentControlResponse struct {
	Versioned
	WorkspaceUID      string `json:"workspaceUID,omitempty"`
	BindingGeneration string `json:"bindingGeneration"`
	ActiveEpoch       int64  `json:"activeEpoch,omitempty"`
	Active            bool   `json:"active"`
}

AttachmentControlResponse reports the active epoch after activation or revocation.

type AttachmentCredentials 

type AttachmentCredentials struct {
	WorkspaceUID string
	Epoch        int64
	Bearer       string
}

AttachmentCredentials are supplied by a Task worker for data-plane requests.

type AttachmentRevocationRequest 

type AttachmentRevocationRequest struct {
	Versioned
	WorkspaceUID      string `json:"workspaceUID"`
	BindingGeneration string `json:"bindingGeneration"`
}

AttachmentRevocationRequest identifies the exact workspace binding being revoked.

type CancelResponse 

type CancelResponse struct {
	Versioned
	OperationID string         `json:"operationID"`
	State       OperationState `json:"state"`
}

CancelResponse reports the operation state after a cancellation request.

type CapabilitiesResponse 

type CapabilitiesResponse struct {
	Versioned
	Features                []string `json:"features"`
	MaxRequestBytes         int64    `json:"maxRequestBytes"`
	MaxOutputBytes          int64    `json:"maxOutputBytes"`
	MaxDownloadBytes        int64    `json:"maxDownloadBytes"`
	OperationRetentionSec   int64    `json:"operationRetentionSeconds"`
	MaxRetainedOperations   int      `json:"maxRetainedOperations"`
	MaxOperationIDsPerEpoch int      `json:"maxOperationIDsPerEpoch"`
	BindingGeneration       string   `json:"bindingGeneration"`
}

CapabilitiesResponse advertises bounded protocol capabilities.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client calls one workspace-agent endpoint. It is safe for concurrent use.

func NewClient 

func NewClient(config ClientConfig) (*Client, error)

NewClient validates transport policy and constructs a workspace-agent client.

func (*Client) ActivateAttachment 

func (c *Client) ActivateAttachment(
	ctx context.Context,
	request AttachmentControlRequest,
) (*AttachmentControlResponse, error)

ActivateAttachment activates one epoch through the privileged control endpoint.

func (*Client) Cancel 

func (c *Client) Cancel(
	ctx context.Context,
	credentials AttachmentCredentials,
	operationID string,
) (*CancelResponse, error)

Cancel requests cancellation of a running operation.

func (*Client) Capabilities 

func (c *Client) Capabilities(ctx context.Context) (*CapabilitiesResponse, error)

Capabilities returns bounded workspace-agent capabilities.

func (*Client) Download 

func (c *Client) Download(
	ctx context.Context,
	credentials AttachmentCredentials,
	request DownloadRequest,
) (*DownloadResponse, error)

Download reads selected workspace files.

func (*Client) Exec 

func (c *Client) Exec(
	ctx context.Context,
	credentials AttachmentCredentials,
	request ExecRequest,
) (*ExecResponse, error)

Exec starts or returns the existing state of an idempotent operation.

func (*Client) ExecStatus 

func (c *Client) ExecStatus(
	ctx context.Context,
	credentials AttachmentCredentials,
	operationID string,
) (*ExecResponse, error)

ExecStatus returns retained operation state/result.

func (*Client) Health 

func (c *Client) Health(ctx context.Context) (*HealthResponse, error)

Health checks liveness and validates the protocol version.

func (*Client) Reset 

func (c *Client) Reset(ctx context.Context, request ResetRequest) (*ResetResponse, error)

Reset runs a privileged idempotent reset after attachment revocation.

func (*Client) RevokeAttachment 

func (c *Client) RevokeAttachment(
	ctx context.Context,
	workspaceUID string,
	bindingGeneration string,
	epoch int64,
) (*AttachmentControlResponse, error)

RevokeAttachment clears epoch before cleanup or Task terminalization.

func (*Client) Scrub 

func (c *Client) Scrub(ctx context.Context, request ScrubRequest) (*ScrubResponse, error)

Scrub runs privileged idempotent cleanup after attachment revocation.

func (*Client) Upload 

func (c *Client) Upload(
	ctx context.Context,
	credentials AttachmentCredentials,
	request UploadRequest,
) (*UploadResponse, error)

Upload writes files with path+digest idempotency.

type ClientConfig 

type ClientConfig struct {
	Endpoint      string
	CAData        []byte
	AllowInsecure bool
	HTTPClient    *http.Client
	HostHeader    string
	ControlAuth   string
	Timeout       time.Duration
}

ClientConfig configures a direct or provider-routed workspace-agent client.

type DownloadRequest 

type DownloadRequest struct {
	Versioned
	Paths []string `json:"paths,omitempty"`
}

DownloadRequest reads selected files; an empty list requests the workspace tree.

type DownloadResponse 

type DownloadResponse struct {
	Versioned
	Artifacts []DownloadedArtifact `json:"artifacts"`
}

DownloadResponse contains requested file bytes and metadata.

type DownloadedArtifact 

type DownloadedArtifact struct {
	Artifact
	Data []byte `json:"data"`
}

DownloadedArtifact includes file bytes.

type Error 

type Error struct {
	Reason     ErrorReason
	Message    string
	StatusCode int
	Retryable  bool
	Cause      error
}

Error is a sanitized client failure. It never contains bearer or control tokens.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type ErrorReason 

type ErrorReason string

ErrorReason is a bounded transport/protocol failure reason suitable for metrics. 

const (
	ErrorReasonEncodeRequest   ErrorReason = "encode_request"
	ErrorReasonInvalidEndpoint ErrorReason = "invalid_endpoint"
	ErrorReasonCreateRequest   ErrorReason = "create_request"
	ErrorReasonRequestFailed   ErrorReason = "request_failed"
	ErrorReasonStatus          ErrorReason = "status"
	ErrorReasonDecodeResponse  ErrorReason = "decode_response"
	ErrorReasonVersion         ErrorReason = "protocol_version"
)

type ExecRequest 

type ExecRequest struct {
	Versioned
	OperationID    string            `json:"operationID,omitempty"`
	Command        []string          `json:"command"`
	Env            map[string]string `json:"env,omitempty"`
	WorkDir        string            `json:"workDir,omitempty"`
	Stdin          []byte            `json:"stdin,omitempty"`
	TimeoutSeconds int64             `json:"timeoutSeconds,omitempty"`
	MaxOutputBytes int64             `json:"maxOutputBytes,omitempty"`

	// Detach is retained for legacy callers. New callers use OperationID and poll.
	Detach      bool   `json:"detach,omitempty"`
	Resident    bool   `json:"resident,omitempty"`
	ResidentKey string `json:"residentKey,omitempty"`
}

ExecRequest starts an idempotent command operation. OperationID is caller-supplied.

type ExecResponse 

type ExecResponse struct {
	Versioned
	OperationID     string         `json:"operationID,omitempty"`
	State           OperationState `json:"state,omitempty"`
	Stdout          string         `json:"stdout"`
	Stderr          string         `json:"stderr"`
	ExitCode        int            `json:"exitCode"`
	StdoutTruncated bool           `json:"stdoutTruncated"`
	StderrTruncated bool           `json:"stderrTruncated"`
	// IsolationFailed reports that post-command process isolation cleanup failed.
	// The command State and ExitCode remain the workload outcome so callers never
	// replay a successful command because finalization degraded.
	IsolationFailed bool      `json:"isolationFailed,omitempty"`
	StartedAt       time.Time `json:"startedAt"`
	FinishedAt      time.Time `json:"finishedAt,omitempty"`

	// ExecID and Running retain wire compatibility with the legacy private protocol.
	ExecID  string `json:"execId,omitempty"`
	Running bool   `json:"running,omitempty"`
}

ExecResponse is retained for the bounded operation result window.

type HealthResponse 

type HealthResponse struct {
	Versioned
	Status string `json:"status"`
}

HealthResponse reports basic liveness without secret data.

type OperationState 

type OperationState string

OperationState is the durable state of an idempotent exec operation. 

const (
	OperationStateRunning   OperationState = "Running"
	OperationStateSucceeded OperationState = "Succeeded"
	OperationStateFailed    OperationState = "Failed"
	OperationStateCancelled OperationState = "Cancelled"
)

type ResetRequest 

type ResetRequest struct {
	Versioned
	OperationID       string   `json:"operationID"`
	WorkspaceUID      string   `json:"workspaceUID"`
	BindingGeneration string   `json:"bindingGeneration"`
	Paths             []string `json:"paths,omitempty"`
}

ResetRequest idempotently resets the workspace roots selected by the provider.

type ResetResponse 

type ResetResponse struct {
	Versioned
	Reset             bool   `json:"reset"`
	BindingGeneration string `json:"bindingGeneration"`
}

ResetResponse acknowledges an idempotent reset.

type ScrubRequest 

type ScrubRequest struct {
	Versioned
	WorkspaceUID      string   `json:"workspaceUID"`
	BindingGeneration string   `json:"bindingGeneration"`
	Paths             []string `json:"paths"`
}

ScrubRequest idempotently removes selected paths.

type ScrubResponse 

type ScrubResponse struct {
	Versioned
	Scrubbed bool `json:"scrubbed"`
}

ScrubResponse acknowledges an idempotent scrub.

type UploadFile 

type UploadFile struct {
	Path    string    `json:"path"`
	Data    []byte    `json:"data"`
	Digest  string    `json:"digest,omitempty"`
	Mode    uint32    `json:"mode,omitempty"`
	ModTime time.Time `json:"modTime,omitempty"`
}

UploadFile is one requested file write.

type UploadRequest 

type UploadRequest struct {
	Versioned
	Files []UploadFile `json:"files"`
}

UploadRequest writes bounded files. Repeating the same path and digest is idempotent.

type UploadResponse 

type UploadResponse struct {
	Versioned
	Artifacts []Artifact `json:"artifacts"`
}

UploadResponse reports safe artifact metadata.

type Versioned 

type Versioned struct {
	ProtocolVersion string `json:"protocolVersion"`
}

Versioned is embedded in all request and response bodies.

func NewVersioned 

func NewVersioned() Versioned

NewVersioned returns a protocol marker for new requests.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.