agent

type AgentInfo struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Mode        string `json:"mode"`   // "primary", "subagent", or "all"
	Hidden      bool   `json:"hidden"` // Internal agents (compaction, title, summary)
}

type AgentLister interface {
	ListAgents(ctx context.Context, projectDir string) ([]AgentInfo, error)
}

type AllSessionDiscoverer interface {
	DiscoverAllSessions(ctx context.Context) ([]SessionSnapshot, error)
}

type Attachment struct {
	ImageID  string `json:"image_id,omitempty"`
	Mime     string `json:"mime"`
	Filename string `json:"filename,omitempty"`
	// Source is where clank-host fetches the bytes from. Scheme-tagged so the
	// client picks the cheapest transport for the target host:
	//   - file://<abs>      local host, zero-copy (gated by AllowLocalFileAttachments)
	//   - data:<mime>;base64 inline bytes (rides the message)
	//   - http(s)://…       a fetchable URL, e.g. a presigned object-store GET
	Source string `json:"source"`
}

type AuthCredential struct {
	Type    string `json:"type"`
	Refresh string `json:"refresh,omitempty"`
	Access  string `json:"access,omitempty"`
	// Expires must always be serialized even when zero. OpenCode's
	// OAuth schema (packages/opencode/src/auth/index.ts) requires the
	// field; an entry without it is silently dropped at load time —
	// the credential never reaches the provider plugin and the
	// provider stops appearing in /config/providers. Copilot tokens
	// don't have a tracked TTL so 0 is the upstream-blessed value,
	// but it must be present.
	Expires int64  `json:"expires"`
	Key     string `json:"key,omitempty"`

	// EnterpriseURL carries through extra fields the github-copilot
	// plugin populates when the deployment type is "enterprise". The
	// loader uses it to compute the API base URL.
	EnterpriseURL string `json:"enterpriseUrl,omitempty"`

	// Metadata holds provider-specific extra fields for api-type
	// credentials (Azure resourceName, Cloudflare accountId/gatewayId).
	// Empty for providers that need only a key.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type BackendInvocation struct {
	// WorkDir is the resolved filesystem path where the backend should run
	// (a repo root, or a worktree path when WorktreeBranch was set).
	WorkDir string

	// ResumeExternalID is the backend's own session ID for resume; empty
	// means start a new backend session. Currently this is sourced from
	// StartRequest.SessionID (which doubles as the host-side session ID).
	// A future split may decouple the two.
	ResumeExternalID string

	// Config is the session's last-applied config (option id → value id).
	// A resumed backend re-asserts it after loading the session: agents
	// boot fresh processes with their own defaults, so without this every
	// rehydrate silently reset mode/model/effort to those defaults. Not an
	// initial config for fresh sessions — those apply config via the first
	// Send (DATA-040).
	Config map[string]string
}

type BackendManager interface {
	// Init performs eager initialization such as starting servers for known
	// project directories. Called once by the daemon on startup before any
	// other method. Long-running work (like reconciler loops) should be
	// launched as goroutines that respect ctx cancellation.
	// knownDirs returns project directories previously seen for this backend.
	Init(ctx context.Context, knownDirs func() ([]string, error)) error

	// CreateBackend creates a new SessionBackend from a host-resolved
	// invocation. The wire StartRequest is path-free; the Host resolves
	// (RepoRef, Branch) → workDir and constructs a BackendInvocation
	// before invoking this method. See §7.4 of hub_host_refactor_code_review.md.
	// The backend is not started — call Start() or Watch() on it.
	CreateBackend(ctx context.Context, inv BackendInvocation) (SessionBackend, error)

	// Shutdown cleans up all managed resources (servers, connections, etc.).
	Shutdown()
}

type BackendType string

type ClaudePermissionMode string

type ConfigOption struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Category    string `json:"category,omitempty"`
	// CurrentValue is the option's live value id — for an unset knob this
	// is the agent's own resolved default (e.g. opencode's concrete
	// default model), which is how clients display truth without clank
	// substituting anything.
	CurrentValue string              `json:"current_value"`
	Values       []ConfigOptionValue `json:"values"`
}

type ConfigOptionValue struct {
	Value       string `json:"value"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// Group is the advertised group header, when the agent groups values
	// (e.g. models by provider). Flattened: clients regroup if they care.
	Group string `json:"group,omitempty"`
}

type ConfigOptionsLister interface {
	ConfigOptions(ctx context.Context, projectDir string) ([]ConfigOption, error)
}

type ConfigOptionsReporter interface {
	ConfigOptions() []ConfigOption
}

type DeviceFlowStart struct {
	FlowID          string    `json:"flow_id"`
	DeviceCode      string    `json:"-"` // not exposed to clients; sandbox-internal
	UserCode        string    `json:"user_code"`
	VerificationURL string    `json:"verification_url"`
	ExpiresAt       time.Time `json:"expires_at"`
	Interval        int       `json:"interval"`
}

type DeviceFlowState string

type DeviceFlowStatus struct {
	State DeviceFlowState `json:"state"`
	Error string          `json:"error,omitempty"`
}

type ErrorData struct {
	Message string `json:"message"`
}

type Event struct {
	Type      EventType `json:"type"`
	SessionID string    `json:"session_id"` // hub session id (set by hub relay)
	// ExternalID carries the session-backend's native session ID. TODO rename
	ExternalID string      `json:"external_id,omitempty"`
	Timestamp  time.Time   `json:"timestamp"`
	Data       interface{} `json:"data"`
}

type EventType string

type ForkResult struct {
	ID    string // External (backend) session ID
	Title string // AI-generated title carried over from the source session
}

type GitRef struct {
	LocalPath      string `json:"local_path,omitempty"`
	WorktreeID     string `json:"worktree_id,omitempty"`
	DisplayName    string `json:"display_name,omitempty"`
	WorktreeBranch string `json:"worktree_branch,omitempty"`
	Subdir         string `json:"subdir,omitempty"`
}

type LaunchHostSpec struct {
	Provider string `json:"provider"` // "flymachines", "local-stub", ...
}

type MessageData struct {
	ID         string `json:"id,omitempty"` // Backend-assigned message ID (e.g. OpenCode message ID)
	Role       string `json:"role"`         // "user" or "assistant"
	Content    string `json:"content"`
	Parts      []Part `json:"parts,omitempty"`
	ModelID    string `json:"model_id,omitempty"`    // Model that produced this message (assistant only)
	ProviderID string `json:"provider_id,omitempty"` // Provider of the model (assistant only)
}

type MetaChangeData struct {
	Session SessionInfo `json:"session"`
}

type ModeChangeData struct {
	ModeID string `json:"mode_id"`
}

type ModeReporter interface {
	Modes() (currentID string, available []SessionMode)
}

type ModelInfo struct {
	ID           string `json:"id"`            // Model ID (e.g. "claude-opus-4-20250514")
	Name         string `json:"name"`          // Human-readable name (e.g. "Claude Opus")
	ProviderID   string `json:"provider_id"`   // Provider ID (e.g. "github-copilot")
	ProviderName string `json:"provider_name"` // Human-readable provider name
}

type ModelOverride struct {
	ModelID    string `json:"model_id"`
	ProviderID string `json:"provider_id"`
}

type ModelReporter interface {
	Models() (currentID string, available []ModelInfo)
}

type Part struct {
	ID     string         `json:"id"`
	Type   PartType       `json:"type"`
	Text   string         `json:"text,omitempty"`
	Tool   string         `json:"tool,omitempty"` // Tool name if tool call/result
	Status PartStatus     `json:"status,omitempty"`
	Input  map[string]any `json:"input,omitempty"`  // Tool call arguments (e.g. filePath, command)
	Output string         `json:"output,omitempty"` // Tool result text

	// Question is backend-appended metadata marking this tool call as an
	// interactive question prompt (Claude AskUserQuestion, OpenCode question
	// tool), normalized so clients render structured UI without parsing
	// provider-specific input. Present on both streamed part events and
	// Messages() transcripts — the tool part is the single source of truth
	// for the prompt, so a client that reopens a session recovers it from
	// the ordinary history refetch. Reply via RespondQuestion using
	// Question.RequestID.
	Question *QuestionPrompt `json:"question,omitempty"`
}

type PartStatus string

type PartType string

type PartUpdateData struct {
	MessageID string `json:"message_id,omitempty"`
	Part      Part   `json:"part"`
	// IsDelta indicates this is an incremental text chunk (append to existing
	// content). When false, Part.Text is the authoritative full snapshot and
	// should replace whatever text the TUI has accumulated for this part.
	IsDelta bool `json:"is_delta,omitempty"`
}

type PendingPermissionsReporter interface {
	// PendingPermissions returns the parked requests, oldest first.
	PendingPermissions() []PermissionData
}

type PermissionData struct {
	RequestID   string `json:"request_id"`
	Tool        string `json:"tool"`
	Description string `json:"description"`
	// ToolUseID is the id of the tool_use block this prompt is gating, when the
	// backend can determine it. It lets a client correlate the prompt with the
	// tool-call card it already rendered (whose id is the tool_use id) instead
	// of guessing by tool name. Empty when the backend can't attribute it.
	ToolUseID string `json:"tool_use_id,omitempty"`
}

type ProjectInfo struct {
	ID       string `json:"id"`
	Worktree string `json:"worktree"`
}

type ProviderAuthInfo struct {
	ProviderID  string           `json:"provider_id"`
	DisplayName string           `json:"display_name"`
	AuthType    string           `json:"auth_type"`
	Backend     BackendType      `json:"backend"`
	Connected   bool             `json:"connected"`
	Source      string           `json:"source,omitempty"` // CredentialSource* when connected
	Prompts     []ProviderPrompt `json:"prompts,omitempty"`
}

type ProviderPrompt struct {
	Key         string `json:"key"`
	Message     string `json:"message"`
	Placeholder string `json:"placeholder,omitempty"`
}

type Question struct {
	Text        string `json:"text"`                   // full question text
	Header      string `json:"header,omitempty"`       // short label (chip/tag)
	MultiSelect bool   `json:"multi_select,omitempty"` // multiple options may be selected
	// AllowCustom reports whether a free-text answer is accepted. Tri-state:
	// nil means the provider didn't say and clients treat it as allowed (the
	// universal default). A pointer rather than a bool so an explicit false —
	// opencode's custom=false — survives omitempty and reaches clients.
	AllowCustom *bool            `json:"allow_custom,omitempty"`
	Options     []QuestionOption `json:"options"`
}

type QuestionAnswer struct {
	Selected []string `json:"selected,omitempty"` // labels of the chosen options
	Custom   string   `json:"custom,omitempty"`   // free-text answer
}

type QuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
}

type QuestionPrompt struct {
	RequestID string     `json:"request_id"`
	Questions []Question `json:"questions"`
}

type ReconnectedData struct {
	Attempts   int  `json:"attempts"`    // How many attempts it took
	URLChanged bool `json:"url_changed"` // Whether the server URL changed (new port)
}

type ReconnectingData struct {
	Attempt int           `json:"attempt"` // Current retry attempt (1-based)
	Delay   time.Duration `json:"delay"`   // How long until the next retry
	Error   string        `json:"error"`   // The error that triggered the reconnect
	GaveUp  bool          `json:"gave_up"` // True if this is the final failure (no more retries)
}

type ResolvedImage = resolvedImage

type RevertChangeData struct {
	MessageID string `json:"message_id"` // The message ID from which onward is reverted; empty means unrevert
}

type SearchParams struct {
	Query      string            `json:"query,omitempty"`      // pipe-separated OR groups
	Since      time.Time         `json:"since,omitempty"`      // only sessions updated at or after this time
	Until      time.Time         `json:"until,omitempty"`      // only sessions updated before this time
	Visibility SessionVisibility `json:"visibility,omitempty"` // "" = active only, "all" = everything, "done"/"archived" = only that
}

type SendMessageOpts struct {
	Text  string         `json:"text"`
	Model *ModelOverride `json:"model,omitempty"` // Per-message model override; nil = use default
	// Config changes agent-advertised session config options before this
	// prompt dispatches: option id → value id, e.g. {"mode": "plan"}.
	// Omitted map or key means "no change" — the session keeps the state
	// it already has (sessions remember themselves). Values ride verbatim;
	// the agent skips ids it does not advertise.
	Config map[string]string `json:"config,omitempty"`
	// Attachments are images the client uploaded out-of-band; the backend
	// downloads each via its presigned GetURL and inlines it into the agent
	// (Claude base64 content block / OpenCode file part). Empty for text-only
	// messages.
	Attachments []Attachment `json:"attachments,omitempty"`
}

type ServerInfo struct {
	URL        string    `json:"url"`
	ProjectDir string    `json:"project_dir"`
	PID        int       `json:"pid"`
	StartedAt  time.Time `json:"started_at"`
}

type SessionBackend interface {
	// Open establishes (or re-attaches to) the session and begins event
	// production into Events(). Idempotent — safe to call on an
	// already-open session.
	Open(ctx context.Context) error

	// Send dispatches a prompt to an Open session. Fast-fails if the
	// session is not open. Returns once the prompt is handed off to
	// the agent runtime, NOT when the LLM finishes.
	Send(ctx context.Context, opts SendMessageOpts) error

	// OpenAndSend is the new-session convenience: Open followed by Send.
	// Backends MAY fuse the two operations when their runtime supports
	// it (e.g. dispatching the prompt as part of session creation).
	OpenAndSend(ctx context.Context, opts SendMessageOpts) error

	// Abort signals the agent to interrupt the current turn. Best-effort:
	// returns once the signal has been delivered, not when the agent has
	// actually stopped. Observe StatusChange events for completion.
	Abort(ctx context.Context) error

	// Stop performs a graceful shutdown: closes the event channel,
	// terminates child processes, and releases resources. Blocks until
	// teardown completes. Safe to call multiple times.
	Stop() error

	// Events returns the event stream for this backend. The channel is
	// closed when the backend stops. All events for a session flow
	// through this channel
	Events() <-chan Event

	// Status returns the current session status snapshot. May change
	// concurrently; treat as a hint, not authoritative.
	Status() SessionStatus

	// SessionID returns the agent-assigned native session ID, or "" if
	// not yet known. Used by HTTP handlers to serialize ExternalID and
	// by discover for deduplication. Hub code MUST NOT poll this after
	// Open to persist the ID — use Event.ExternalID instead, which is
	// the single source of truth that survives daemon restarts.
	SessionID() string

	// Messages returns the on-disk transcript for this session. Reads
	// fresh from the backend's storage on each call (no in-memory
	// accumulation fallback). Returns (nil, nil) if no transcript
	// exists yet (e.g. session ID not learned, or backend doesn't
	// support history retrieval).
	Messages(ctx context.Context) ([]MessageData, error)

	// Fork creates a new session branched from the given message.
	// Returns the new session's external ID and title. Returns a typed
	// ErrUnsupported when the backend/agent does not advertise forking.
	Fork(ctx context.Context, messageID string) (ForkResult, error)

	// RespondPermission replies to a pending permission prompt.
	// allow=true sends "once", allow=false sends "reject". denyMessage is the
	// reason shown to the model when allow=false (empty for a default reason);
	// it is ignored when allow=true and by backends whose protocol has no
	// deny-reason field.
	RespondPermission(ctx context.Context, permissionID string, allow bool, denyMessage string) error
}

type SessionDiscoverer interface {
	DiscoverSessions(ctx context.Context, seedDir string) ([]SessionSnapshot, error)
}

type SessionInfo struct {
	ID              string            `json:"id"`
	ExternalID      string            `json:"external_id,omitempty"` // Backend's native session ID (e.g. OpenCode session ID)
	Backend         BackendType       `json:"backend"`
	Status          SessionStatus     `json:"status"`
	Visibility      SessionVisibility `json:"visibility,omitempty"` // User-set: "", "done", or "archived"
	FollowUp        bool              `json:"follow_up,omitempty"`  // User-set flag to mark session for follow-up
	Hostname        string            `json:"hostname,omitempty"`   // Canonical identity: host (Phase 3); "local" by default.
	GitRef          GitRef            `json:"git_ref,omitempty"`    // Canonical identity: repo (LocalPath and/or WorktreeID; WorktreeBranch when set).
	Prompt          string            `json:"prompt"`
	Title           string            `json:"title,omitempty"` // AI-generated session title from OpenCode
	TicketID        string            `json:"ticket_id,omitempty"`
	Agent           string            `json:"agent,omitempty"`             // Current OpenCode agent (e.g. "build", "plan")
	Draft           string            `json:"draft,omitempty"`             // Unsent follow-up text the user was composing
	Config          map[string]string `json:"config,omitempty"`            // Last-applied session config (option id → value id): create/send config merged with agent-initiated mode changes. Re-asserted on rehydrate so a backend rebuild can't reset the session's mode.
	RevertMessageID string            `json:"revert_message_id,omitempty"` // When set, messages from this ID onward are reverted (hidden)
	ServerURL       string            `json:"server_url,omitempty"`        // Runtime-only: backend server URL (e.g. OpenCode serve endpoint). Not persisted.
	CurrentModeID   string            `json:"current_mode_id,omitempty"`   // Runtime-only: the agent-owned session mode currently active. Not persisted.
	AvailableModes  []SessionMode     `json:"available_modes,omitempty"`   // Runtime-only: agent-advertised modes for the picker. Not persisted.
	CurrentModelID  string            `json:"current_model_id,omitempty"`  // Runtime-only: the agent-selected model for this session. Not persisted.
	AvailableModels []ModelInfo       `json:"available_models,omitempty"`  // Runtime-only: agent-advertised models for the picker. Not persisted.
	ConfigOptions   []ConfigOption    `json:"config_options,omitempty"`    // Runtime-only: the agent's full advertised config options (mode/model/effort/…), for knob editors. Not persisted.
	IsRemote        bool              `json:"is_remote,omitempty"`         // Runtime-only: decoration stamped by the laptop daemon's session router when this session's worktree is owned by the active remote. Always false on direct host responses; populated by gateway routing.
	CreatedAt       time.Time         `json:"created_at"`
	UpdatedAt       time.Time         `json:"updated_at"`
	LastReadAt      time.Time         `json:"last_read_at,omitempty"`
}

type SessionMode struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

type SessionSnapshot struct {
	ID              string      `json:"id"`
	Backend         BackendType `json:"backend"`
	Title           string      `json:"title"`
	Directory       string      `json:"directory"`
	RevertMessageID string      `json:"revert_message_id,omitempty"`
	CreatedAt       time.Time   `json:"created_at"`
	UpdatedAt       time.Time   `json:"updated_at"`
}

type SessionStatus string

type SessionVisibility string

type SoftwareInfo struct {
	Version string `json:"version"`
}

type SoftwareManifest struct {
	OpenCode SoftwareInfo `json:"opencode"`
	Claude   SoftwareInfo `json:"claude"`
}

type StartRequest struct {
	Backend    BackendType     `json:"backend"`
	Hostname   string          `json:"hostname,omitempty"`    // Target host; empty defaults to "local" at the hub.
	LaunchHost *LaunchHostSpec `json:"launch_host,omitempty"` // When set, Hub provisions a fresh host before dispatching.
	GitRef     GitRef          `json:"git_ref"`               // Wire-canonical repo identity; required. WorktreeBranch lives inside.
	Prompt     string          `json:"prompt"`
	SessionID  string          `json:"session_id,omitempty"` // Backend-external session ID for resume; empty = new session.
	TicketID   string          `json:"ticket_id,omitempty"`  // Optional backlog ticket link
	Model      *ModelOverride  `json:"model,omitempty"`      // Per-message model override; nil = use default
	// Config sets agent-advertised session config options at creation:
	// option id → value id from that option's advertised list, e.g.
	// {"mode": "plan", "effort": "high"}. The host validates that every
	// key of the backend's built-in Default preset is present — it never
	// fills values in (no fallbacks; a missing key fails the create) —
	// and passes values through verbatim: the agent owns the vocabulary
	// and skips ids it does not advertise.
	Config map[string]string `json:"config,omitempty"`
	// Attachments are images for the first message, forwarded to the backend's
	// OpenAndSend. Same semantics as SendMessageOpts.Attachments.
	Attachments []Attachment `json:"attachments,omitempty"`
}

type StatusChangeData struct {
	OldStatus SessionStatus `json:"old_status"`
	NewStatus SessionStatus `json:"new_status"`
}

type TitleChangeData struct {
	Title string `json:"title"`
}

type VoiceStatus string

type VoiceStatusData struct {
	Status VoiceStatus `json:"status"`
}

type VoiceToolCallData struct {
	Name   string `json:"name"`             // Tool name (e.g. "list_sessions")
	Args   string `json:"args,omitempty"`   // JSON-encoded arguments
	Result string `json:"result,omitempty"` // Tool result (empty if still running)
}

type VoiceTranscriptData struct {
	Text string `json:"text"`           // Incremental or final transcript text
	Done bool   `json:"done,omitempty"` // True when transcript is final
}