common

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: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultServiceAccountBearerPath = "/var/run/secrets/kubernetes.io/serviceaccount/token"
)
View Source 
const (

	// MaxStructuredSummaryChars bounds agent-written summaries stored in structured
	// results. Diffs remain intact for workspace handoff, but oversized summaries
	// can otherwise blow up coordinator context windows and provider request limits.
	MaxStructuredSummaryChars = 32 * 1024
)

Variables

This section is empty.

Functions

func CloneRepo 

func CloneRepo(ctx context.Context, cfg *AgentConfig, workspaceDir string) error

CloneRepo clones the configured git repository into the workspace directory.

When the workspace already contains a git repository (e.g. a sandbox workspace reused across turns of the same session), CloneRepo skips the clone and refreshes in place. Branch workspaces are fast-forwarded only when the configured branch is still checked out; a session-created branch is preserved as part of the reused workspace state.

When ORKA_PUSH_BRANCH is set and no ORKA_GIT_REF pinned a specific commit, CloneRepo also creates and checks out a local branch with that name. This way any agent-initiated `git push origin HEAD` lands on the intended remote branch instead of the upstream default (often "main"). The post-run worker finalize step still owns the canonical commit + push.

func EnsureRequiredSecurityArtifacts 

func EnsureRequiredSecurityArtifacts(
	ctx context.Context,
	cfg *AgentConfig,
	result string,
	followUp SecurityArtifactFollowUp,
) (string, error)

EnsureRequiredSecurityArtifacts verifies that required security artifacts exist after a runtime result, attempts direct/transcript recovery when possible, and optionally runs a follow-up prompt to materialize anything still missing. 

func EnsureWorkspaceArtifactsLink(workspaceDir string) error

EnsureWorkspaceArtifactsLink exposes /tmp/artifacts inside the repo root so runtime agents can write artifacts using a workspace-relative path.

func FinalizeResult 

func FinalizeResult(workDir string, agentOutput string) ([]byte, error)

FinalizeResult builds a structured result from the agent output and any uncommitted changes in workDir. If workDir is empty, it returns the raw agent output as plain text bytes. When ORKA_PUSH_BRANCH is set, changes are committed and pushed to that branch.

func FirstNonBlank added in v0.2.0 

func FirstNonBlank(values ...string) string

FirstNonBlank returns the first value that is not blank, unmodified, so callers that must preserve provider-supplied strings exactly (model IDs, paths) still treat whitespace-only values as empty.

func FormatStructuredResult 

func FormatStructuredResult(r *StructuredResult) ([]byte, error)

FormatStructuredResult serializes a StructuredResult to JSON bytes.

func MissingArtifacts 

func MissingArtifacts(filenames []string) ([]string, error)

MissingArtifacts returns required artifact filenames that do not exist yet or are present but empty.

func PreparePullRequestReviewContext 

func PreparePullRequestReviewContext(workDir string, cfg *AgentConfig) error

PreparePullRequestReviewContext writes safe, read-only PR diff context into the workspace for reviewer agents that cannot run git commands themselves.

func PrepareSecurityReviewContext 

func PrepareSecurityReviewContext(workspaceDir string, cfg *AgentConfig) error

PrepareSecurityReviewContext materializes the deterministic review context for repository security review tasks and appends the exact bounded excerpts to the agent prompt.

func PrepareWorkspace 

func PrepareWorkspace(workDir string) error

PrepareWorkspace applies the diff from a prior task's result to the working directory. It is called after git clone and before the LLM agent starts. If ORKA_PRIOR_TASK is not set the function is a no-op.

func RecordEvent 

func RecordEvent(ctx context.Context, recorder EventRecorder, typ string, opts ...EventOption)

RecordEvent emits a best-effort worker execution event. Event recording must never change worker task behavior, so nil recorders and recorder implementation panics are ignored.

func RecordEventStrict 

func RecordEventStrict(ctx context.Context, recorder EventRecorder, typ string, opts ...EventOption) (err error)

RecordEventStrict emits an execution event through a strict recorder. Unlike RecordEvent, errors are returned so approval requests can fail closed.

func RecordEventWithTimeout 

func RecordEventWithTimeout(recorder EventRecorder, typ string, timeout time.Duration, opts ...EventOption)

RecordEventWithTimeout emits a best-effort event using a fresh bounded context. Use this for terminal events that may run after the worker's signal context is already canceled.

func RestoreSecurityReviewContextArtifact 

func RestoreSecurityReviewContextArtifact(cfg *AgentConfig) error

RestoreSecurityReviewContextArtifact rewrites the worker-generated review context manifest in case an agent deleted or replaced it while writing model-authored artifacts.

func SetupGitCredentials 

func SetupGitCredentials()

SetupGitCredentials sets git credential env vars globally so both clone and agent-initiated git operations (push, fetch) can authenticate.

func SubmitResultContext added in v0.2.0 

func SubmitResultContext(ctx context.Context, result []byte) error

SubmitResultContext sends the task result to the controller via HTTP POST. It reads ORKA_RESULT_ENDPOINT or constructs the URL from ORKA_CONTROLLER_URL. Retryable failures use bounded exponential backoff and stop when ctx is canceled.

func TruncateStructuredSummary 

func TruncateStructuredSummary(summary string) string

TruncateStructuredSummary bounds human-readable result summaries while making truncation explicit to downstream coordinators.

func TruncateSummary added in v0.2.0 

func TruncateSummary(summary string, limit int) string

TruncateSummary cuts summary to limit bytes and appends an explicit marker carrying the original length so coordinators can tell truncation happened.

func UploadArtifactsContext added in v0.2.0 

func UploadArtifactsContext(ctx context.Context) error

UploadArtifactsContext scans the artifacts directory and uploads each file using the worker lifecycle context. It returns nil when the directory does not exist or is empty.

func UploadArtifactsWithRequestAuthorizationContext added in v0.2.0 

func UploadArtifactsWithRequestAuthorizationContext(
	ctx context.Context,
	authorize func(*http.Request, []byte) error,
) error

UploadArtifactsWithRequestAuthorizationContext signs each request, including retries, and stops uploads when the worker lifecycle ends. The callback stays in the wrapper.

func WriteArtifactFile 

func WriteArtifactFile(filename string, data []byte) error

WriteArtifactFile writes an artifact file into the shared upload directory.

Types

type AgentConfig 

type AgentConfig struct {
	TaskName           string
	TaskNamespace      string
	TransactionID      string
	TransactionProfile string
	Prompt             string
	Model              string
	SystemPrompt       string
	MaxTurns           int
	AllowedTools       []string
	AllowedToolsSet    bool
	DisallowedTools    []string
	GitRepo            string
	GitBranch          string
	GitRef             string
	ShallowGitRef      bool
	PRBaseBranch       string
	PRBaseRepo         string
	PRBaseSHA          string
	SubPath            string
	TimeoutSeconds     int
	// contains filtered or unexported fields
}

AgentConfig holds worker configuration from environment variables.

func LoadConfig 

func LoadConfig(defaultMaxTurns int) (*AgentConfig, error)

LoadConfig reads and validates agent configuration from environment variables.

func LoadWorkspaceConfig 

func LoadWorkspaceConfig() (*AgentConfig, error)

LoadWorkspaceConfig reads and validates workspace configuration without requiring an agent prompt. Container workers use this for deterministic tasks.

type ArtifactRef 

type ArtifactRef struct {
	Filename    string `json:"filename"`
	ContentType string `json:"contentType,omitempty"`
	Size        int64  `json:"size,omitempty"`
	Description string `json:"description,omitempty"`
}

ArtifactRef is a safe structured reference to a task artifact. The artifact bytes remain in Orka artifact storage; this envelope carries only metadata that coordinators and remote runtimes can use to fetch or reason about it.

type EventOption 

type EventOption func(*RecordedEvent)

EventOption customizes a worker execution event before it is recorded.

func WithEventAgentName 

func WithEventAgentName(agentName string) EventOption

func WithEventContent 

func WithEventContent(content json.RawMessage) EventOption

func WithEventContentText 

func WithEventContentText(contentText string) EventOption

func WithEventSeverity 

func WithEventSeverity(severity string) EventOption

func WithEventSummary 

func WithEventSummary(summary string) EventOption

func WithEventTaskName 

func WithEventTaskName(taskName string) EventOption

func WithEventToolCallID 

func WithEventToolCallID(toolCallID string) EventOption

func WithEventToolName 

func WithEventToolName(toolName string) EventOption

type EventRecorder 

type EventRecorder interface {
	Record(ctx context.Context, typ string, opts ...EventOption)
}

EventRecorder records worker-side execution events.

func NewHTTPEventRecorder 

func NewHTTPEventRecorder(cfg HTTPEventRecorderConfig) EventRecorder

NewHTTPEventRecorder creates a controller-backed event recorder. Missing required controller/task configuration returns NoopEventRecorder.

func NewHTTPEventRecorderFromEnv 

func NewHTTPEventRecorderFromEnv() EventRecorder

NewHTTPEventRecorderFromEnv builds a controller-backed event recorder from worker env. If required env is missing or invalid, it returns a no-op recorder so event recording never blocks task execution.

type FakeEventRecorder 

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

FakeEventRecorder captures worker events in memory for tests.

func NewFakeEventRecorder 

func NewFakeEventRecorder() *FakeEventRecorder

NewFakeEventRecorder creates an empty fake event recorder.

func NewFakeEventRecorderWithClock 

func NewFakeEventRecorderWithClock(now func() time.Time) *FakeEventRecorder

NewFakeEventRecorderWithClock creates a fake event recorder with a deterministic clock.

func (*FakeEventRecorder) EventTypes 

func (r *FakeEventRecorder) EventTypes() []string

EventTypes returns recorded event types in order.

func (*FakeEventRecorder) Events 

func (r *FakeEventRecorder) Events() []RecordedEvent

Events returns a snapshot of recorded events.

func (*FakeEventRecorder) Record 

func (r *FakeEventRecorder) Record(ctx context.Context, typ string, opts ...EventOption)

Record captures the event after applying options and the shared redaction/truncation contract.

func (*FakeEventRecorder) RecordStrict 

func (r *FakeEventRecorder) RecordStrict(ctx context.Context, typ string, opts ...EventOption) error

RecordStrict captures the event synchronously and returns context errors.

func (*FakeEventRecorder) Reset 

func (r *FakeEventRecorder) Reset()

Reset clears captured events.

type HTTPEventRecorder 

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

HTTPEventRecorder posts worker execution events to the controller internal API.

func (*HTTPEventRecorder) Record 

func (r *HTTPEventRecorder) Record(ctx context.Context, typ string, opts ...EventOption)

Record implements EventRecorder. Failures are warning-only and never returned to callers.

func (*HTTPEventRecorder) RecordStrict 

func (r *HTTPEventRecorder) RecordStrict(ctx context.Context, typ string, opts ...EventOption) error

RecordStrict implements StrictEventRecorder by posting the event and returning transport or non-2xx response errors.

type HTTPEventRecorderConfig 

type HTTPEventRecorderConfig struct {
	ControllerURL string
	Namespace     string
	TaskName      string
	SessionName   string
	BearerPath    string
	Client        *http.Client
	Timeout       time.Duration
	Now           func() time.Time
}

HTTPEventRecorderConfig configures the worker HTTP event recorder.

type NoopEventRecorder 

type NoopEventRecorder struct{}

NoopEventRecorder discards worker events.

func (NoopEventRecorder) Record 

func (NoopEventRecorder) Record(context.Context, string, ...EventOption)

Record implements EventRecorder.

func (NoopEventRecorder) RecordStrict 

func (NoopEventRecorder) RecordStrict(context.Context, string, ...EventOption) error

RecordStrict implements StrictEventRecorder and fails closed because a no-op recorder cannot prove that a required event was persisted.

type RecordedEvent 

type RecordedEvent struct {
	Type        string
	Severity    string
	TaskName    string
	SessionName string
	AgentName   string
	ToolName    string
	ToolCallID  string
	Summary     string
	Content     json.RawMessage
	ContentText string
	Truncation  *events.ExecutionEventTruncation
	CreatedAt   time.Time
}

RecordedEvent is the worker-facing shape captured by fakes and future clients.

type SecurityArtifactFollowUp 

type SecurityArtifactFollowUp func(ctx context.Context, prompt string) (string, error)

SecurityArtifactFollowUp runs a focused follow-up prompt that should write any still-missing required artifacts into the shared artifact directory.

type StrictEventRecorder 

type StrictEventRecorder interface {
	RecordStrict(ctx context.Context, typ string, opts ...EventOption) error
}

StrictEventRecorder records events synchronously and returns transport or validation errors to callers that cannot safely continue without persistence.

type StructuredResult 

type StructuredResult struct {
	Version    int      `json:"version"`
	Summary    string   `json:"summary"`
	BaseSHA    string   `json:"baseSHA,omitempty"`
	HeadSHA    string   `json:"headSHA,omitempty"`
	Diff       string   `json:"diff,omitempty"`
	Verdict    string   `json:"verdict,omitempty"`
	Feedback   string   `json:"feedback,omitempty"`
	Files      []string `json:"files,omitempty"`
	PushBranch string   `json:"pushBranch,omitempty"`
	PushError  string   `json:"pushError,omitempty"`
	// Data carries generic machine-readable task output. Keep large payloads in
	// artifacts and put references here; parent/coordinator summaries may bound it.
	Data      map[string]any `json:"data,omitempty"`
	Artifacts []ArtifactRef  `json:"artifacts,omitempty"`
}

StructuredResult is an optional structured envelope for task results. Workers can use this to include diffs, verdicts, and metadata alongside the human-readable summary. Plain-text results remain backward compatible.

func ParseStructuredResult 

func ParseStructuredResult(raw string) *StructuredResult

ParseStructuredResult attempts to parse a result string as a StructuredResult. If the input is not valid JSON or doesn't have the expected structure, it returns a StructuredResult with the raw input as Summary (backward compatible).

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.