harness

package
v0.2.3 Latest Latest
Warning

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

 Go to latest Published: Jul 13, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Overview

Package harness runs Python agent code behind a local HTTP lifecycle API.

Index

Constants

View Source 
const (
	FailureCategoryTaskFailed     = "task_failed"
	FailureCategoryToolFailed     = "tool_failed"
	FailureCategorySaaSFailed     = "saas_failed"
	FailureCategoryMCPFailed      = "mcp_failed"
	FailureCategoryCodeFailed     = "code_failed"
	FailureCategoryBudgetExceeded = "budget_exceeded"
	FailureCategoryImportFailed   = "import_failed"
	FailureCategoryInvokeTimeout  = "invoke_timeout"
	FailureCategoryWorkerKilled   = "worker_killed"
	FailureCategoryMCPDenied      = "mcp_denied"

	AvailabilityAvailable   = "available"
	AvailabilityUnavailable = "unavailable"
	AvailabilityRateLimited = "rate_limited"
	AvailabilityForbidden   = "forbidden"
)
View Source 
const (
	MaxPayloadBytes = 10 * 1024 * 1024
)
View Source 
const (
	StatusBudgetExceeded = "BUDGET_EXCEEDED"
)
View Source 
const StatusGuardrailBlocked = "guardrail_blocked"

StatusGuardrailBlocked is returned when a guardrail blocks an LLM prompt or response.

Variables

View Source 
var ErrBudgetExceeded = errors.New("budget exceeded")

Functions

func DropNetAdminCapability 

func DropNetAdminCapability()

DropNetAdminCapability removes CAP_NET_ADMIN from effective, permitted, and inheritable sets on the current process so child processes (e.g. the Python worker) cannot flush or modify iptables/ip6tables rules.

func EgressFirewallEnabled 

func EgressFirewallEnabled() bool

EgressFirewallEnabled reports whether the container should apply iptables egress rules. AGENTPAAS_EGRESS_FIREWALL defaults to enabled ("1"); set "0" to disable.

func InitEgressFirewall 

func InitEgressFirewall()

InitEgressFirewall applies best-effort iptables OUTPUT rules before the Python worker starts. This firewall is defense-in-depth; the primary egress control is Docker network topology isolation (internal-only network + gateway sidecar). When iptables is unavailable or any rule fails, a warning is logged but harness startup continues. Call DropNetAdminCapability immediately after this (see cmd/harness/main.go) so the agent process cannot flush rules via inherited CAP_NET_ADMIN.

Types

type AuditAppender 

type AuditAppender interface {
	Append(record audit.AuditRecord) error
}

type BudgetConfig 

type BudgetConfig struct {
	WallClockSeconds int64 `json:"wall_clock_seconds,omitempty"`
	MaxIterations    int64 `json:"max_iterations,omitempty"`
	MaxTokens        int64 `json:"max_tokens,omitempty"`
}

type BudgetEnforcer 

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

func NewBudgetEnforcer 

func NewBudgetEnforcer(cfg BudgetConfig) *BudgetEnforcer

func (*BudgetEnforcer) Elapsed 

func (b *BudgetEnforcer) Elapsed() time.Duration

func (*BudgetEnforcer) MarkWallClockExceeded 

func (b *BudgetEnforcer) MarkWallClockExceeded(observed time.Duration) error

func (*BudgetEnforcer) RecordIteration 

func (b *BudgetEnforcer) RecordIteration() error

func (*BudgetEnforcer) RecordTokens 

func (b *BudgetEnforcer) RecordTokens(count int64) error

func (*BudgetEnforcer) Start 

func (b *BudgetEnforcer) Start()

func (*BudgetEnforcer) WallClockBudget 

func (b *BudgetEnforcer) WallClockBudget() time.Duration

type Config 

type Config struct {
	Addr            string
	AgentPath       string
	Python          string
	ImportTimeout   time.Duration
	InvokeTimeout   time.Duration
	TerminateGrace  time.Duration
	StdoutPath      string
	StderrPath      string
	Audit           AuditAppender
	CredentialsPath string // Path to credentials.json sidecar file (empty = none)
}

Config controls the harness HTTP server and Python worker.

type ErrorResponse 

type ErrorResponse struct {
	Status         string          `json:"status"`
	Reason         string          `json:"reason"`
	Detail         string          `json:"detail"`
	FailureContext *FailureContext `json:"failure_context,omitempty"`
}

ErrorResponse is the structured failure envelope returned by lifecycle APIs.

type FailureContext 

type FailureContext struct {
	RunID             string            `json:"run_id"`
	InvokeID          string            `json:"invoke_id"`
	Category          string            `json:"category"`
	Reason            string            `json:"reason"`
	PolicyDigest      string            `json:"policy_digest"`
	PolicyDecisionIDs []string          `json:"policy_decision_ids"`
	UpstreamEvidence  *UpstreamEvidence `json:"upstream_evidence,omitempty"`
	StderrRef         string            `json:"stderr_ref,omitempty"`
	StdoutRef         string            `json:"stdout_ref,omitempty"`
	RedactedDetail    string            `json:"redacted_detail"`
}

type FileAuditAppender 

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

FileAuditAppender writes hash-chained JSONL audit records to a file. Each record includes prev_hash and record_hash so the daemon can verify the chain before re-chaining into its own audit trail.

This is used by the harness binary running inside the container to record egress decisions, MCP calls, and other audit-worthy events. The daemon reads the file after (or during) the run, verifies the harness-side chain, and ingests the records into its own hash-chained audit trail.

func NewFileAuditAppender 

func NewFileAuditAppender(path string) (*FileAuditAppender, error)

NewFileAuditAppender opens (or creates) the file at path for appending. The file is created with mode 0600. If the file already contains records, prevHash is seeded from the last line's record_hash so the hash chain continues.

func (*FileAuditAppender) Append 

func (a *FileAuditAppender) Append(record audit.AuditRecord) error

Append writes a single hash-chained audit record as a JSON line. It sets the timestamp if empty and maintains prev_hash/record_hash.

func (*FileAuditAppender) Close 

func (a *FileAuditAppender) Close() error

Close closes the underlying file.

type GuardrailRule added in v0.2.0 

type GuardrailRule struct {
	Type       string
	Pattern    string
	Action     string
	Provider   string
	Credential string
	URL        string
}

GuardrailRule is the invoke-payload form of a policy.Guardrail entry. Only fields required by harness enforcement are kept.

type InvokeResponse 

type InvokeResponse struct {
	Status string         `json:"status"`
	Result map[string]any `json:"result,omitempty"`
	Stdout string         `json:"stdout"`
	Stderr string         `json:"stderr"`
}

InvokeResponse is returned by successful /invoke calls.

type Server 

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

Server exposes the harness HTTP contract.

func NewServer 

func NewServer(cfg Config) *Server

NewServer creates a harness server and performs the Python import phase.

func (*Server) Close 

func (s *Server) Close() error

Close stops the Python worker.

func (*Server) ListenAndServe 

func (s *Server) ListenAndServe(ctx context.Context) error

ListenAndServe serves the harness HTTP API on the configured localhost address.

func (*Server) ServeHTTP 

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

type UpstreamEvidence 

type UpstreamEvidence struct {
	StatusCode   int               `json:"status_code,omitempty"`
	Headers      map[string]string `json:"headers,omitempty"`
	TimingMS     int64             `json:"timing_ms,omitempty"`
	Availability string            `json:"availability"`
	Method       string            `json:"method,omitempty"`
	URL          string            `json:"url,omitempty"`
	BodyHash     string            `json:"body_hash,omitempty"`
	BodyRedacted string            `json:"body,omitempty"`
	Credential   string            `json:"credential,omitempty"`
}

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.