harnesses

type Adapter interface {
	// DescribeCapabilities reports tools, streaming, recovery, interruption
	// and checkpoint modes. It must not require Prepare.
	DescribeCapabilities() Capabilities
	// Prepare validates the pinned runtime, generates startup configuration
	// and attaches platform-owned resources.
	Prepare(ctx context.Context, env Environment) error
	// StartOrResume starts the seat from a recovery descriptor. It reports
	// whether the native session was resumed or a portable handoff was used.
	StartOrResume(ctx context.Context, rec RecoveryDescriptor) (ResumeResult, error)
	// Deliver processes one platform message and blocks until the turn is
	// technically complete. Cancelling ctx interrupts the turn. All events for
	// the turn are emitted on Events before Deliver returns.
	Deliver(ctx context.Context, d Delivery) (TurnResult, error)
	// Events returns the adapter's event stream. The same channel is returned
	// on every call; it is closed by Stop. Consumers must drain it.
	Events() <-chan Event
	// Quiesce stops accepting deliveries and waits for the current turn to
	// reach a safe point. When ctx expires first the turn is interrupted.
	Quiesce(ctx context.Context) (QuiesceResult, error)
	// Checkpoint persists the recovery descriptor and reports its guarantee.
	Checkpoint(ctx context.Context) (runtimeapi.Checkpoint, error)
	// Stop terminates execution without deleting durable seat data. An
	// already-expired ctx means kill immediately.
	Stop(ctx context.Context) error
}

type Capabilities struct {
	Adapter string `json:"adapter"`
	// Version is the pinned runtime version, when known before Prepare.
	Version string `json:"version,omitempty"`
	// ToolTransports lists how platform tools reach the harness: mcp, cli.
	ToolTransports []string `json:"tool_transports"`
	EventStreaming bool     `json:"event_streaming"`
	// Interruption is how a running turn can be interrupted: signal, cooperative or none.
	Interruption string `json:"interruption"`
	// RecoveryModes lists supported recovery modes (Recovery* constants).
	RecoveryModes []string `json:"recovery_modes"`
	// CheckpointGuarantees lists the guarantees Checkpoint can report.
	CheckpointGuarantees []string `json:"checkpoint_guarantees"`
	// GracefulSuspension reports whether a live process can be suspended and
	// resumed. False means Quiesce only reaches a turn boundary.
	GracefulSuspension bool `json:"graceful_suspension"`
	// SessionFormat identifies the native session format family.
	SessionFormat string `json:"session_format,omitempty"`
}

type Claim struct {
	Kind string `json:"kind"` // e.g. task_done
	Text string `json:"text"`
}

type Delivery struct {
	DeliveryID  int64
	ExecutionID string
	Attempt     int
	Message     runtimeapi.Envelope
	// Passive are queued messages (sent with wake=false) handed over with
	// this turn. They are context, not separate requests to answer.
	Passive []runtimeapi.Envelope
}

type Descriptor struct {
	// Name is the harness profile adapter value.
	Name string
	// Aliases are accepted alternative names.
	Aliases []string
	// APIs are the model APIs the harness can speak, in order of preference.
	APIs []string
	// NeedsModel means a harness profile must select a model.
	NeedsModel bool
	// Settings are the model.settings keys the harness understands.
	Settings map[string]Setting
	// Capabilities are values a profile's required_capabilities may name.
	Capabilities []string
	// New returns an unprepared adapter.
	New func() Adapter
}

type Environment struct {
	OrganizationID string
	SeatID         string
	SeatKey        string
	DisplayName    string
	ConfigRevision string
	// Generation is the execution lease generation (fencing token).
	Generation int64

	// PlatformURL is the platform base URL; TokenFile is the projected token.
	PlatformURL string
	TokenFile   string

	// WorkspaceDir is the harness working directory (/seat/workspace),
	// HomeDir is HOME (/seat/home), RunnerDir holds runner and adapter state
	// (/seat/runner), TmpDir is scratch space (/tmp).
	WorkspaceDir string
	HomeDir      string
	RunnerDir    string
	TmpDir       string

	// Instructions is the rendered instruction text from
	// /etc/steadmesh/manifest/instructions.md (Bootstrap.Instructions only
	// lists the ordered refs).
	Instructions string
	// Bootstrap is the platform bootstrap (identity, guidance, recovery).
	Bootstrap runtimeapi.Bootstrap

	// ToolCommand is the steadmesh-tools binary.
	ToolCommand string
	// Model is the seat's model selection; nil when the profile has none.
	Model *ModelEndpoint

	// SandboxEnv is added to the environment of harness processes by access
	// plugins: proxy settings for the egress gateway (HTTPS_PROXY, NO_PROXY).
	SandboxEnv []string
	// MCPServers are extra stdio MCP servers access plugins provide (the
	// browser). Harnesses expose them next to the platform tools.
	MCPServers []MCPServer

	// HarnessConfig is the harness profile's free-form config.
	HarnessConfig map[string]string
	// ExtraEnv is passed to harness subprocesses (e.g. STEADMESH_* for tools).
	ExtraEnv []string
}

type Event struct {
	Kind string `json:"kind"`
	// ExecutionID and MessageID correlate the event to its delivery.
	ExecutionID string `json:"execution_id"`
	MessageID   string `json:"message_id"`
	// CorrelationID links related events, e.g. a tool_use id.
	CorrelationID string          `json:"correlation_id,omitempty"`
	Data          json.RawMessage `json:"data,omitempty"`
	Time          time.Time       `json:"time"`
}

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

type MCPServer struct {
	Name    string
	Command string
	Args    []string
	Env     map[string]string
}

type ModelEndpoint struct {
	// Connection is the model connection key.
	Connection string
	// ID is the model the harness must request; the proxy rejects others.
	ID string
	// API is the protocol to speak (API* constants).
	API string
	// Settings are validated model.settings (Descriptor.Settings).
	Settings map[string]string
	// BaseURL is the forwarder base for the connection, without /v1. The API
	// paths sit below it: /v1/messages, /v1/responses, /v1/chat/completions.
	BaseURL string
	// APIKey is a placeholder for harnesses that insist on a key. The
	// forwarder replaces whatever credential the harness sends.
	APIKey string
}

type QuiesceResult struct {
	// Interrupted is true when the in-flight turn had to be interrupted.
	Interrupted bool `json:"interrupted"`
	// SafePoint describes the boundary reached, e.g. turn_boundary.
	SafePoint string `json:"safe_point"`
	// SuspensionSupported is false for adapters that cannot suspend a live process.
	SuspensionSupported bool `json:"suspension_supported"`
}

type RecoveryDescriptor struct {
	// Session is the last harness checkpoint recorded by the platform.
	Session           *runtimeapi.Checkpoint
	Handoff           *runtimeapi.Handoff
	PendingMessages   int
	UnknownOperations []runtimeapi.Operation
	// Note is the platform's recovery note, if any.
	Note string
}

type ResumeResult struct {
	Mode      string `json:"mode"`
	SessionID string `json:"session_id,omitempty"`
	// Note is a visible recovery note, e.g. why native resume was not used.
	// It never claims byte-for-byte continuation of a lost session.
	Note string `json:"note,omitempty"`
}

type Setting struct {
	Description string
	// Values are the allowed values; empty means any non-empty string.
	Values []string
}

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

type TurnResult struct {
	MessageID string `json:"message_id"`
	Status    string `json:"status"`
	Error     string `json:"error,omitempty"`
	SessionID string `json:"session_id,omitempty"`
	// Output is the harness's final text for the turn. It is not delivered to
	// anyone; agents reply through the messages tools.
	Output   string        `json:"output,omitempty"`
	Duration time.Duration `json:"duration"`
	// Claim is the agent's own statement about business completion, if the
	// adapter can identify one. It is informational and agent-owned.
	Claim *Claim `json:"claim,omitempty"`
	// Recovery is set when this turn started a new session in place of a
	// native resume.
	Recovery *ResumeResult `json:"recovery,omitempty"`
}