provider

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

type CodexConfig struct {
	// SandboxMode sets --sandbox. Empty = CodexSandboxFullAccess.
	SandboxMode CodexSandboxMode
}

type CodexSandboxMode string

type ExitReason int

type HookCapability struct {
	Supported bool
	Verified  bool
	ProbedAt  time.Time
	Error     string
	Scope     string
}

type HookInstanceConfig struct {
	Enabled bool
}

type Instance struct {
	Type      Type
	Name      string
	Binary    string // override path; empty = use Type as PATH name
	ExtraArgs []string
	Env       []string
	Disabled  bool

	// Hooks holds the user's enable/disable intent per hook event
	// (PreToolUse, SessionStart, …). Spawners read this on every
	// Spawn to decide whether to install / remove the per-workspace
	// hook config.
	Hooks map[string]HookInstanceConfig

	// Storage configures credential-file syncing for this instance.
	// nil = sync disabled.
	Storage *StorageConfig

	// CodexConfig holds codex-specific spawn options. nil for non-codex instances.
	CodexConfig *CodexConfig
}

type Options struct {
	Workspace   string
	ResumeID    string
	IdleTimeout time.Duration
	// KillAfterIdle is the extra grace period after IdleTimeout fires
	// before the subprocess is actually killed. 0 = kill immediately.
	// During the grace period, new output from the subprocess resets
	// the cycle (grace is cancelled and IdleTimeout restarts).
	KillAfterIdle time.Duration
	ParserFactory func() event.Parser
	Spawner       Spawner
	Store         *store.Store
	State         *state.Machine

	OnEvent func(event.AgentEvent)
	OnExit  func(reason ExitReason)

	// Instance is the per-instance config the spawner should consult
	// every spawn (hook intent, env, …). Forwarded into SpawnOptions
	// so the spawn package is the only place that reads the registry.
	Instance *Instance
	// GateBinary is the absolute path to <app>-gate, resolved once by
	// the factory and threaded through every spawn so the spawner can
	// write hook configs without re-resolving.
	GateBinary string
	// Preset is the system prompt content forwarded to the spawner as
	// --append-system-prompt (or equivalent). Stripped from spawn logs.
	Preset string
	// ExtraEnv merges into the subprocess env on every spawn. Used by
	// per-channel transports (Slack, HTTP) that need to inject auth
	// tokens or routing keys.
	ExtraEnv []string
	// MessageEncoder formats a user message before writing to stdin.
	// nil = default Claude stream-json envelope. Ignored when RespawnOnSend=true.
	MessageEncoder func(text string) string
	// RespawnOnSend, when true, means Send() kills the current process and
	// spawns a new one with the message as InitialMessage (positional arg).
	// Used by codex which is one-shot per invocation, not long-lived.
	RespawnOnSend bool
}

type Pool interface {
	Kill(sessionID, agentName string) error
	Send(ctx context.Context, sessionID, agentName, source, role, text string) error
}

type Process interface {
	Stdout() io.Reader
	Stdin() io.WriteCloser
	Wait() error
	Kill() error
	// Pid returns the OS process id of the started subprocess, or 0 if
	// not applicable (fake spawners in tests). Used by the spawn logger
	// + Backends UI to verify a re-spawn actually got a new process and
	// not just the same one looping.
	Pid() int
	// Binary is the resolved absolute path of the launched executable
	// (e.g. "/usr/local/bin/claude"). Empty when the spawner is a test
	// fake. Logged at spawn-start so operators can debug "claude not
	// found" / wrong binary issues from the Backends UI alone.
	Binary() string
	// Argv is the argument vector handed to the subprocess (excluding
	// argv[0] = binary). Logged at spawn-start so the operator can
	// reproduce the spawn manually outside wick.
	Argv() []string
}

type SpawnEvent struct {
	Type         string    `json:"type"`
	At           time.Time `json:"at"`
	ProviderType string    `json:"provider_type,omitempty"`
	ProviderName string    `json:"provider_name,omitempty"`
	SessionID    string    `json:"session_id,omitempty"`
	AgentName    string    `json:"agent_name,omitempty"`
	Workspace    string    `json:"workspace,omitempty"`
	ResumeID     string    `json:"resume_id,omitempty"`
	Binary       string    `json:"binary,omitempty"`
	Args         []string  `json:"args,omitempty"`
	Env          []string  `json:"env,omitempty"`
	// PID is the OS pid of the started subprocess. Set on the `start`
	// event after Spawner.Spawn returns; carried on `exit` so listings
	// can verify the same pid was reaped. 0 = test fake or unknown.
	PID int `json:"pid,omitempty"`
	// Origin is the session origin that triggered the spawn (e.g. "slack",
	// "telegram", "rest", "ui"). Written once on the initial start event
	// so the Recent Spawns list can show the channel without a session
	// registry lookup.
	Origin string `json:"origin,omitempty"`
	// FirstUserMessage is a short prefix of the user input that
	// triggered the spawn (truncated). Surfaces in the Backends UI
	// "Recent Spawns" list so operators see what each spawn was for.
	FirstUserMessage string `json:"first_user_message,omitempty"`
	ExitReason       string `json:"exit_reason,omitempty"`
	DurationMs       int64  `json:"duration_ms,omitempty"`
	Error            string `json:"error,omitempty"`
	Message          string `json:"message,omitempty"`
}

type SpawnLogFile struct {
	Path             string
	ProviderType     string
	ProviderName     string
	SessionID        string
	StartedAt        time.Time
	PID              int
	Origin           string // session origin (slack/telegram/rest/ui/…)
	FirstUserMessage string
	Binary           string
	Argv             []string
	// ExitReason is "" while the spawn is still alive (no exit event
	// recorded yet), else "clean" / "idle" / "stopped" / "error".
	ExitReason string
}

type SpawnLogger struct {
	BaseDir string // <agents-base>/providers/spawns
	// contains filtered or unexported fields
}

type SpawnOptions struct {
	Workspace string
	ResumeID  string
	// ExtraEnv lets the gate (phase 3) inject hook config paths
	// without coupling the agent package to gate internals.
	ExtraEnv []string

	// Instance is the resolved per-instance config the factory looked
	// up before this spawn. Spawners read Instance.Hooks to decide
	// which hook configs to install / remove on the workspace and
	// whether to flip provider-specific bypass flags. nil = legacy
	// test paths that don't drive hook plumbing.
	Instance *Instance

	// GateBinary is the absolute path to <app>-gate the spawner should
	// reference when writing hook configs. Resolved once by the
	// factory (sibling / embed / PATH) and forwarded so each provider
	// sub-package doesn't have to repeat the resolution dance.
	GateBinary string

	// Preset is the system prompt content injected via --append-system-prompt
	// when non-empty. Each provider spawner decides how to pass it to the
	// underlying CLI. The value is never written to spawn logs — Argv() strips it.
	Preset string

	// InitialMessage is the first user prompt for providers that take the
	// prompt as a positional arg (codex) rather than via stdin after spawn.
	// Empty = no positional prompt arg appended. claude ignores this field.
	InitialMessage string
}

type Spawner interface {
	Spawn(ctx context.Context, opt SpawnOptions) (Process, error)
}

type Status struct {
	Instance   Instance
	ResolvedAt time.Time
	Path       string // result of LookPath / override
	PathFound  bool
	Version    string // first line of `<bin> --version`
	VersionErr string // error message when version probe failed

	Hooks map[string]HookCapability

	// Probing is a render-time hint set by the HTTP layer when a
	// capability probe is currently in flight for this instance. UI
	// disables the Test / Enable buttons so the user can't double-fire.
	// Not persisted — pure in-memory state.
	Probing bool
}

type StorageConfig struct {
	Mode            string // "folder" | "single"
	SyncPath        string
	IntervalSeconds int
}

type SwitchOptions struct {
	// Greeting, if non-empty, is sent as a user message to the new agent
	// immediately after the switch so it can introduce itself.
	Greeting string
	// Source is the transport label written into conversation.jsonl ("ui", "slack", etc.).
	Source string
	// UserText is the original raw message (e.g. "#codex") to record as a
	// user turn in conversation.jsonl before the switch events.
	UserText string
	// Notify, if set, is called after the system turn is written so the
	// caller can push a realtime event (e.g. SSE) to connected clients.
	// tag is the new provider tag; steps are the trace lines.
	Notify func(tag string, steps []string)
	// Reply, if set, is called with the confirmation text so every channel
	// (UI SSE, Slack postReply, REST response, etc.) can deliver it back to
	// the user without forwarding to the provider.
	Reply func(text string)
}

type Type string