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
}

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
	// ModelProxyURL is the Anthropic-compatible base URL
	// (<platform>/v1/model/<connection>); empty without a model connection.
	ModelProxyURL   string
	ModelConnection string
	Model           string

	// 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 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 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"`
}