serve

type ActivityFilter struct {
	// Query is a substring matched against type, agent_name, data,
	// result, and error (case-insensitive LIKE). Empty means no text
	// filter.
	Query string
	// Type narrows to one event type (e.g. "process.failed").
	Type string
	// Agent narrows to one agent_name.
	Agent string
	// From and To bound the timestamp range. Zero values are unbounded.
	From time.Time
	To   time.Time
	// Limit caps the number of events returned. Defaults to 100; max 500.
	Limit int
	// Offset skips that many matching events (paginate alongside Limit).
	Offset int
}

type ActivityLogResponse struct {
	Events []StoreEvent `json:"events"`
	Total  int          `json:"total"`
	Limit  int          `json:"limit"`
	Offset int          `json:"offset"`
}

type AddTaskCommentRequest struct {
	Author  string `json:"author,omitempty"`
	Content string `json:"content"`
}

type AgentBrainFile struct {
	ID        string    `json:"id"`
	AgentName string    `json:"agent_id"` // FE calls this agent_id
	Name      string    `json:"name"`
	MimeType  string    `json:"mime_type,omitempty"`
	SizeBytes int64     `json:"size_bytes"`
	CreatedAt time.Time `json:"created_at"`
	// Content is never JSON-serialized — only used internally for upload/download.
	Content []byte `json:"-"`
}

type AgentBudget struct {
	AgentName          string    `json:"agent"`
	BudgetCap          *float64  `json:"budget_cap"`
	SoftAlertThreshold float64   `json:"soft_alert_threshold"`
	Enabled            bool      `json:"enabled"`
	CreatedAt          time.Time `json:"created_at"`
	UpdatedAt          time.Time `json:"updated_at"`
}

type AgentBudgetResponse struct {
	Agent              string    `json:"agent"`
	BudgetCap          *float64  `json:"budget_cap"`
	SoftAlertThreshold float64   `json:"soft_alert_threshold"`
	Enabled            bool      `json:"enabled"`
	ObservedSpend      float64   `json:"observed_spend"`
	PeriodStart        time.Time `json:"period_start"`
	PeriodEnd          time.Time `json:"period_end"`
}

type AgentHealth string

type AgentIdentity struct {
	ID          string `json:"id"`
	DisplayName string `json:"display_name"`
	Title       string `json:"title,omitempty"`
}

type AgentResponse struct {
	Name        string `json:"name"`
	DisplayName string `json:"display_name,omitempty"`
	Title       string `json:"title,omitempty"`
	// Description is a short paragraph of body text describing the agent's
	// purpose. User-facing — distinct from `system` (the LLM-facing prompt).
	Description string `json:"description,omitempty"`
	Avatar      string `json:"avatar,omitempty"`
	// Icon is a Lucide icon name; pairs with AvatarGradient for the
	// frontend's circular agent badge.
	Icon string `json:"icon,omitempty"`
	// AvatarGradient is a 2-stop CSS color array, e.g. ["#EF4444", "#DC2626"].
	AvatarGradient []string `json:"avatar_gradient,omitempty"`
	// IsOrchestrator is true when this agent is the tenant's configured
	// orchestrator (the "main agent" — Iris by default, renamable per
	// tenant). Lets frontends mark the orchestrator with special
	// affordances ("talk to your orchestrator" surface) without
	// hardcoding the name.
	IsOrchestrator bool `json:"is_orchestrator,omitempty"`
	// IsBuilder is true when this agent is the tenant's configured
	// builder (Hera by default; in Apex tenants this is always "apex").
	// Internal meta-agent — typically filtered out of public listings.
	IsBuilder bool             `json:"is_builder,omitempty"`
	Model     string           `json:"model,omitempty"`
	System    string           `json:"system,omitempty"`
	Tools     []string         `json:"tools,omitempty"`
	Team      []string         `json:"team,omitempty"`
	Triggers  []dsl.TriggerDef `json:"triggers,omitempty"`
	ProcessID string           `json:"process_id,omitempty"`
	// Status is the high-level agent lifecycle state. Always present.
	Status AgentStatus `json:"status"`
	// Health is the orthogonal "is anything wrong?" signal. Always present.
	Health    AgentHealth `json:"health"`
	Streaming bool        `json:"streaming,omitempty"`
	Source    string      `json:"source,omitempty"`
	// CreatedAt is when the agent was first persisted (composed agents) or
	// the server start time (YAML agents). Pointer so untracked agents omit.
	CreatedAt *time.Time `json:"created_at,omitempty"`
	// UpdatedAt is the last time the agent definition changed.
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
	// LastActivity is the most recent moment the agent's running process
	// did work (last token, last tool call). Nil if the agent has never run.
	LastActivity *time.Time `json:"last_activity,omitempty"`
	// Stats is the per-agent kanban task summary. Always present; zero
	// values mean "no tasks" rather than "not implemented."
	Stats AgentStatsResponse `json:"stats"`
	// ReportsTo lists the agents whose `team` includes this agent — i.e.
	// the agent's supervisors. Inverse direction of `team`. Computed from
	// the document at request time.
	ReportsTo []string `json:"reports_to,omitempty"`
}

type AgentRoutineResponse struct {
	ID           string   `json:"id"`
	Agent        string   `json:"agent"`
	Title        string   `json:"title"`
	Instructions string   `json:"instructions"`
	Schedule     Schedule `json:"schedule"`
	// Cron is the derived expression — exposed for FE debugging and for
	// jobs created via DSL/legacy paths where the structured Schedule
	// can't be reconstructed.
	Cron      string     `json:"cron"`
	Enabled   bool       `json:"enabled"`
	LastRunAt *time.Time `json:"last_run_at"`
	NextRunAt *time.Time `json:"next_run_at"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
}

type AgentSpendResponse struct {
	Agent         string    `json:"agent"`
	ObservedSpend float64   `json:"observed_spend"`
	Period        string    `json:"period"`
	PeriodStart   time.Time `json:"period_start"`
	PeriodEnd     time.Time `json:"period_end"`
}

type AgentStatsResponse struct {
	AssignedTasks  int      `json:"assigned_tasks"`
	CompletedTasks int      `json:"completed_tasks"`
	SuccessRate    *float64 `json:"success_rate"`
}

type AgentStatus string

type AgentTemplateResponse struct {
	Version        string   `json:"version"`
	Name           string   `json:"name"`
	DisplayName    string   `json:"display_name,omitempty"`
	Title          string   `json:"title,omitempty"`
	Description    string   `json:"description,omitempty"`
	Avatar         string   `json:"avatar,omitempty"`
	Icon           string   `json:"icon,omitempty"`
	AvatarGradient []string `json:"avatar_gradient,omitempty"`
	Model          string   `json:"model"`
	System         string   `json:"system"`
	Tools          []string `json:"tools,omitempty"`
	Team           []string `json:"team,omitempty"`
	ExportedBy     string   `json:"exported_by,omitempty"`
	ExportedAt     string   `json:"exported_at,omitempty"`
}

type AgentToolsResponse struct {
	Name  string   `json:"name"`
	Tools []string `json:"tools"`
}

type AuthClaims struct {
	UserID   string
	TenantID string
	Scopes   []string
}

type AuthConfig struct {
	// Issuer is the expected `iss` claim (WorkOS issuer URL in production).
	Issuer string
	// TenantID is the expected `aud` claim. Empty disables auth (self-hosted).
	TenantID string
	// Keyfunc supplies the public key for signature verification. In
	// production this is a JWKS-backed Keyfunc; in tests it can return a
	// fixed *rsa.PublicKey.
	Keyfunc jwt.Keyfunc
}

type BackfillReport struct {
	JustApplied    bool
	AlreadyApplied bool
	PagesWritten   int
	UsersTouched   int
}

type BlobStore interface {
	// Put writes content under key, overwriting any existing value.
	Put(key string, content []byte) error
	// Get returns the content stored at key, or os.ErrNotExist when
	// the key has no value.
	Get(key string) ([]byte, error)
	// Delete removes the value at key. Returns nil whether the key
	// existed or not — idempotent.
	Delete(key string) error
}

type BrokerEvent struct {
	Type      string    `json:"type"`
	ProcessID string    `json:"process_id,omitempty"`
	Agent     string    `json:"agent,omitempty"`
	Data      any       `json:"data,omitempty"`
	Timestamp time.Time `json:"timestamp"`
}

type CallerResolver func(ctx context.Context, userID string) context.Context

type Channel struct {
	ID           string    `json:"id"`
	Name         string    `json:"name"`
	Description  string    `json:"description"`
	Team         []string  `json:"team"`
	Mode         string    `json:"mode,omitempty"` // "" = default (team-lead responds), "social" = all members respond
	CreatedBy    string    `json:"created_by"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
	MessageCount int       `json:"message_count"`
	UnreadCount  int       `json:"unread_count"`
}

type ChannelEvent struct {
	Type      string `json:"type"`
	Channel   string `json:"channel"`
	MessageID int64  `json:"message_id,omitempty"`
	ThreadID  *int64 `json:"thread_id,omitempty"`
	Agent     string `json:"agent,omitempty"`
	Sender    string `json:"sender,omitempty"`
	Role      string `json:"role,omitempty"`
	Content   string `json:"content,omitempty"`
	Delta     string `json:"delta,omitempty"`
	// Tool-call fields — parity with ChatStreamEvent. Already on the wire
	// in the channel stream; documenting them on the schema (refs #55).
	ToolCallID string         `json:"tool_call_id,omitempty"`
	ToolName   string         `json:"tool_name,omitempty"`
	Arguments  map[string]any `json:"arguments,omitempty"`
	Result     string         `json:"result,omitempty"`
	DurationMs int64          `json:"duration_ms,omitempty"`
	Error      string         `json:"error,omitempty"`
	Metrics    any            `json:"metrics,omitempty"`
}

type ChannelMessage struct {
	ID        int64     `json:"id"`
	ChannelID string    `json:"channel_id"`
	ThreadID  *int64    `json:"thread_id,omitempty"`
	Agent     string    `json:"agent,omitempty"`
	Sender    string    `json:"sender,omitempty"`
	Role      string    `json:"role"`
	Content   string    `json:"content"`
	Metadata  string    `json:"metadata,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	// Icon / AvatarGradient are echoed from the sending agent so channel
	// UIs don't need a separate /api/v1/agents lookup to render identity.
	Icon           string   `json:"icon,omitempty"`
	AvatarGradient []string `json:"avatar_gradient,omitempty"`
	// Thread summary fields — populated for top-level messages (ThreadID nil).
	ReplyCount    int        `json:"reply_count,omitempty"`
	LatestReplyAt *time.Time `json:"latest_reply_at,omitempty"`
	// ReplySenders is the distinct list of sender names across all replies
	// in the thread. Lets the channel list show "Riley and Alex replied"
	// without a follow-up fetch per thread.
	ReplySenders []string `json:"reply_senders,omitempty"`
	// ToolActivities captures completed tool calls from the assistant
	// turn that produced this message. Empty for user messages.
	ToolActivities []vega.ToolActivity `json:"tool_activities,omitempty"`
}

type ChannelPostRequest struct {
	Message  string `json:"message"`
	ThreadID *int64 `json:"thread_id,omitempty"`
	Agent    string `json:"agent,omitempty"`
}

type ChatMessage struct {
	ID        int64     `json:"id"`
	Role      string    `json:"role"`
	Content   string    `json:"content"`
	CreatedAt time.Time `json:"created_at"`
	// ToolActivities captures completed tool calls from the assistant
	// turn that produced this message. Empty for user messages; populated
	// for assistant messages that invoked tools during streaming.
	ToolActivities []vega.ToolActivity `json:"tool_activities,omitempty"`
}

type ChatResponseReviewer func(ctx context.Context, agentName, baseAgent, userID, response string) string

type ChatStatusResponse struct {
	Streaming bool `json:"streaming"`
}

type CompanyResponse struct {
	ID          string                   `json:"id"`
	Name        string                   `json:"name"`
	LogoURL     string                   `json:"logo_url,omitempty"`
	AccentColor string                   `json:"accent_color,omitempty"`
	Siblings    []CompanySiblingResponse `json:"siblings,omitempty"`
}

type CompanySiblingResponse struct {
	Name string `json:"name"`
	URL  string `json:"url"`
	Icon string `json:"icon,omitempty"`
}

type ComposedAgent struct {
	Name           string           `json:"name"`
	DisplayName    string           `json:"display_name,omitempty"`
	Title          string           `json:"title,omitempty"`
	Description    string           `json:"description,omitempty"`
	Avatar         string           `json:"avatar,omitempty"`
	Icon           string           `json:"icon,omitempty"`
	AvatarGradient []string         `json:"avatar_gradient,omitempty"`
	Model          string           `json:"model"`
	Persona        string           `json:"persona,omitempty"`
	Skills         []string         `json:"skills,omitempty"`
	Tools          []string         `json:"tools,omitempty"`
	Team           []string         `json:"team,omitempty"`
	System         string           `json:"system,omitempty"`
	Temperature    *float64         `json:"temperature,omitempty"`
	Triggers       []dsl.TriggerDef `json:"triggers,omitempty"`
	CreatedAt      time.Time        `json:"created_at"`
	UpdatedAt      time.Time        `json:"updated_at"`
}

type Config struct {
	// Version is the govega build version (e.g. "v0.7.15"), surfaced to
	// the UI via GET /api/v1/tenant/config. Set by the CLI from the
	// ldflags-injected main.version; empty ("dev") when unset.
	Version string
	Addr    string
	DBPath  string
	// DBKind picks the persistence backend. Defaults to SQLite when empty.
	DBKind DBKind
	// DBURL is the Postgres connection URL when DBKind == "postgres"
	// (e.g. postgres://user:pass@host:5432/db?sslmode=require). Ignored
	// for SQLite.
	DBURL string
	// BlobDir, when non-empty, enables the FilesystemBlobStore at the
	// supplied path (refs govega#61 phase 5). When empty, blob-bearing
	// resources (agent brain files) keep their content inline in the
	// relational DB — preserving the zero-config default. Set this on
	// hosted Postgres deployments so brain content stays out of the
	// DB and on the filesystem (or, future, an S3-compatible store).
	BlobDir       string
	TelegramToken string       // TELEGRAM_BOT_TOKEN; leave empty to disable
	TelegramAgent string       // TELEGRAM_AGENT; defaults to first agent if empty
	DiscordToken  string       // DISCORD_BOT_TOKEN; leave empty to disable
	DiscordAgent  string       // DISCORD_AGENT; defaults to orchestrator if empty
	Company       *dsl.Company // optional company identity (env var overrides)

	// PublicURL is the externally-reachable base URL of this server (no
	// trailing slash), used to build OAuth redirect URIs that match what
	// operators register in their identity-provider consoles, and the
	// workspace deliverable links agents hand to users. When empty, the
	// PUBLIC_URL env var is honored so embedders that don't wire this
	// field still report reachable links on hosted instances; the OAuth
	// redirect URI is otherwise inferred from the incoming request's Host
	// header and X-Forwarded-Proto — which works for laptops but not
	// behind some reverse proxies. Set this on any deployed instance.
	PublicURL string

	// Orchestrator/Builder identify the meta-agents used for routing,
	// scheduling, and UI affordances. Default to "iris"/"hera" — apps
	// embedding govega can override to rebrand.
	Orchestrator dsl.IrisConfig
	Builder      dsl.HeraConfig

	// FrontendFS lets a downstream consumer embed its own React build
	// instead of govega's bundled UI. When nil, the bundled frontend is
	// served from serve/builtinui.
	FrontendFS fs.FS

	// Store, when non-nil, is used as the persistence layer instead of
	// opening a SQLite database from DBPath. Useful for tests (in-memory
	// or temp-file stores) and for embedding products that want to
	// supply a different backend.
	Store Store

	// Middleware is applied between govega's authMiddleware and the mux
	// (i.e. as the innermost layer before route handlers run). Embedding
	// products use this to inject identity from non-JWT sources via
	// WithClaims, enforce shared-secret headers from trusted proxies,
	// stash request-scoped data in the context, etc.
	//
	// The slice is composed left-to-right: Middleware[0] wraps everything
	// inside it, so the first entry runs outermost relative to the rest.
	Middleware []func(http.Handler) http.Handler

	// SessionedAgents names agents that should get per-session isolation. For
	// such an agent, a chat URL of the form "<agent>:<session>" spawns a
	// per-session clone with its own process and chat thread (and, when the
	// product sets per-request claims, its own memory namespace) instead of
	// collapsing to the base agent. Products set this for a guest-facing agent
	// so each guest link is an isolated conversation. Nil/empty preserves the
	// single-thread-per-agent behavior for every agent.
	SessionedAgents map[string]bool

	// ExtraSystemProvider, when non-nil, supplies additional system-prompt
	// content on every chat turn — appended after the standard
	// memory/project/company blocks. Use this to inject per-session
	// context that the agent's static configuration can't express,
	// e.g. looking up a per-book writing norm from an external service
	// based on the cloned agent name. Return "" for a no-op.
	//
	// The callback runs on the chat hot path: keep it fast and cache
	// where appropriate.
	ExtraSystemProvider ExtraSystemProvider

	// ChatResponseReviewer, when non-nil, receives the final assistant reply
	// for a NON-STREAMING chat turn and returns the text actually delivered to
	// (and persisted for) the user — unchanged if safe, or rewritten/redacted.
	// Embedding products use this as a second-pass disclosure screen on
	// guest-facing agents. It runs only on the non-streaming /chat path, so an
	// agent that must be reviewed should be reachable only via /chat (not
	// /chat/stream). Return "" for a no-op (keep the original).
	//
	// Runs on the chat hot path after generation: keep it reasonably fast.
	ChatResponseReviewer ChatResponseReviewer

	// WrapPeeringDispatcher, when non-nil, wraps the peering Dispatcher
	// before it is wired to the AIRE node. Embedding products use this to
	// add subject-keyed authorization (e.g. a LYRA gate verifying
	// on-behalf-of credentials via peering.CallerAwareDispatcher) around
	// the standard interpreter-backed dispatch. Applied only when peering
	// is enabled (VEGA_PEERING_ADDR).
	WrapPeeringDispatcher func(peering.Dispatcher) peering.Dispatcher

	// OrchestratorExtraTools are additional tool names granted to the
	// orchestrator's allow-list, on top of the built-in extras. Embedding
	// products use this to expose a host-registered tool (e.g. a
	// search_my_memory tool over an external memory store) to the agent the
	// user actually chats with — registering the tool on the interpreter is
	// not enough on its own, since a custom tool must also be in the agent's
	// allow-list to be callable. The names must already be registered on the
	// interpreter before Start.
	OrchestratorExtraTools []string
}

type ConfigAgentInfo struct {
	Name        string   `json:"name"`
	DisplayName string   `json:"display_name,omitempty"`
	Model       string   `json:"model"`
	Tools       []string `json:"tools,omitempty"`
	Team        []string `json:"team,omitempty"`
	Source      string   `json:"source"` // "yaml", "composed", or "builtin"
}

type ConfigMCPInfo struct {
	Name      string `json:"name"`
	Connected bool   `json:"connected"`
	Transport string `json:"transport,omitempty"`
}

type ConfigResponse struct {
	Name        string              `json:"name"`
	Description string              `json:"description,omitempty"`
	Agents      []ConfigAgentInfo   `json:"agents"`
	MCPServers  []ConfigMCPInfo     `json:"mcp_servers"`
	Settings    *ConfigSettingsInfo `json:"settings,omitempty"`
}

type ConfigSettingsInfo struct {
	DefaultModel string `json:"default_model,omitempty"`
}

type ConfigUploadResult struct {
	Name          string   `json:"name,omitempty"`
	AgentsCreated []string `json:"agents_created,omitempty"`
	AgentsUpdated []string `json:"agents_updated,omitempty"`
	AgentsSkipped []string `json:"agents_skipped,omitempty"`
	MCPConnected  []string `json:"mcp_connected,omitempty"`
	MCPFailed     []string `json:"mcp_failed,omitempty"`
	Errors        []string `json:"errors,omitempty"`
}

type ConnectMCPRequest struct {
	Name      string            `json:"name"`
	Env       map[string]string `json:"env,omitempty"`
	Transport string            `json:"transport,omitempty"`
	Command   string            `json:"command,omitempty"`
	Args      []string          `json:"args,omitempty"`
	URL       string            `json:"url,omitempty"`
	Headers   map[string]string `json:"headers,omitempty"`
	Timeout   int               `json:"timeout,omitempty"`
}

type ConnectMCPResponse struct {
	Name      string   `json:"name"`
	Connected bool     `json:"connected"`
	Tools     []string `json:"tools,omitempty"`
	Error     string   `json:"error,omitempty"`
}

type CreateAgentRequest struct {
	Name           string           `json:"name"`
	DisplayName    string           `json:"display_name,omitempty"`
	Title          string           `json:"title,omitempty"`
	Description    string           `json:"description,omitempty"`
	Avatar         string           `json:"avatar,omitempty"`
	Icon           string           `json:"icon,omitempty"`
	AvatarGradient []string         `json:"avatar_gradient,omitempty"`
	Model          string           `json:"model"`
	Persona        string           `json:"persona,omitempty"`
	Skills         []string         `json:"skills,omitempty"`
	Team           []string         `json:"team,omitempty"`
	System         string           `json:"system,omitempty"`
	Temperature    *float64         `json:"temperature,omitempty"`
	Triggers       []dsl.TriggerDef `json:"triggers,omitempty"`
}

type CreateAgentResponse struct {
	Name      string   `json:"name"`
	Model     string   `json:"model"`
	Tools     []string `json:"tools,omitempty"`
	ProcessID string   `json:"process_id,omitempty"`
}

type CreateChannelRequest struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Team        []string `json:"team"`
	// Mode: "" (default — team-lead responds), "social" (all members
	// respond to every message), or "reactive" (members respond when
	// work-relevant). Defaults to "" if omitted.
	Mode string `json:"mode,omitempty"`
}

type CreateRoutineRequest struct {
	Title        string   `json:"title"`
	Instructions string   `json:"instructions"`
	Schedule     Schedule `json:"schedule"`
	// Enabled defaults to true when omitted.
	Enabled *bool `json:"enabled,omitempty"`
}

type CreateTaskRequest struct {
	Title       string     `json:"title"`
	Description string     `json:"description,omitempty"`
	Status      string     `json:"status,omitempty"`
	Priority    string     `json:"priority,omitempty"`
	Assignee    string     `json:"assignee,omitempty"`
	Tags        string     `json:"tags,omitempty"`
	CreatedBy   string     `json:"created_by,omitempty"`
	DueAt       *time.Time `json:"due_at,omitempty"`
}

type DBKind string

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

type DiscordBotConfig struct {
	ID    string `json:"id"`
	Token string `json:"token"`
	Agent string `json:"agent"`
	Label string `json:"label,omitempty"`
	// AllowedUsers restricts which Discord user IDs may talk to the bot.
	// Empty means open access (backward compatible). Set it to lock the bot
	// to its owner so strangers in shared guilds can't share the owner's
	// conversation.
	AllowedUsers []string `json:"allowed_users,omitempty"`
}

type DiscordBotStatus struct {
	ID      string `json:"id"`
	Label   string `json:"label,omitempty"`
	Agent   string `json:"agent"`
	Running bool   `json:"running"`
}

type ErrorResponse struct {
	Error   string `json:"error"`
	Details string `json:"details,omitempty"`
}

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

type ExtraSystemProvider func(ctx context.Context, agentName, baseAgent, userID string) string

type FileContentResponse struct {
	Path        string `json:"path"`
	ContentType string `json:"content_type"`
	Content     string `json:"content"`
	Encoding    string `json:"encoding"`
	Size        int64  `json:"size"`
}

type FileEntry struct {
	Name        string `json:"name"`
	Path        string `json:"path"`
	IsDir       bool   `json:"is_dir"`
	Size        int64  `json:"size"`
	ModTime     string `json:"mod_time"`
	ContentType string `json:"content_type,omitempty"`
}

type FileMetadataResponse struct {
	Files  []WorkspaceFile `json:"files"`
	Agents []string        `json:"agents"`
}

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

type GmailStatus struct {
	Connected       bool `json:"connected"`
	HasClientID     bool `json:"has_client_id"`
	HasClientSecret bool `json:"has_client_secret"`
	HasRefreshToken bool `json:"has_refresh_token"`
}

type IdentityResponse struct {
	Orchestrator AgentIdentity `json:"orchestrator"`
	Builder      AgentIdentity `json:"builder"`
	ProductName  string        `json:"product_name"`
}

type InboxItem struct {
	ID            int64      `json:"id"`
	FromAgent     string     `json:"from_agent"`
	Subject       string     `json:"subject"`
	Body          string     `json:"body,omitempty"`
	Priority      string     `json:"priority"`
	Status        string     `json:"status"`
	Resolution    string     `json:"resolution,omitempty"`
	CreatedAt     time.Time  `json:"created_at"`
	ResolvedAt    *time.Time `json:"resolved_at,omitempty"`
	TriageCount   int        `json:"triage_count"`
	LastTriagedAt *time.Time `json:"last_triaged_at,omitempty"`
}

type InputResponse struct {
	Type        string   `json:"type,omitempty"`
	Description string   `json:"description,omitempty"`
	Required    bool     `json:"required"`
	Default     any      `json:"default,omitempty"`
	Enum        []string `json:"enum,omitempty"`
}

type InviteDTO struct {
	NodeID       string `json:"node_id"`
	Endpoint     string `json:"endpoint"`
	SharedSecret string `json:"shared_secret"`
}

type LinkTaskProcessRequest struct {
	ProcessID string `json:"process_id"`
}

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

type MCPRegistryEntryResponse struct {
	Name             string            `json:"name"`
	Description      string            `json:"description"`
	RequiredEnv      []string          `json:"required_env,omitempty"`
	OptionalEnv      []string          `json:"optional_env,omitempty"`
	BuiltinGo        bool              `json:"builtin_go,omitempty"`
	Connected        bool              `json:"connected"`
	ExistingSettings map[string]string `json:"existing_settings,omitempty"`
	// Icon is a Lucide icon name for the FE's integrations grid
	// (refs govega#44). Empty for entries that haven't been tagged.
	Icon string `json:"icon,omitempty"`
	// Category groups integrations on the FE. Suggested taxonomy:
	// communication, dev_tools, crm, project_mgmt, cloud, data,
	// productivity, web. Empty for uncategorized.
	Category string `json:"category,omitempty"`
}

type MCPServerConfig struct {
	Name       string `json:"name"`
	ConfigJSON string `json:"config"`   // JSON-serialized ConnectMCPRequest
	Disabled   bool   `json:"disabled"` // true = persisted but not connected
}

type MCPServerConfigResponse struct {
	Name             string            `json:"name"`
	Transport        string            `json:"transport,omitempty"`
	Command          string            `json:"command,omitempty"`
	Args             []string          `json:"args,omitempty"`
	URL              string            `json:"url,omitempty"`
	Headers          map[string]string `json:"headers,omitempty"`
	Timeout          int               `json:"timeout,omitempty"`
	EnvKeys          []string          `json:"env_keys,omitempty"`
	ExistingSettings map[string]string `json:"existing_settings,omitempty"`
	IsRegistry       bool              `json:"is_registry"`
}

type MCPServerResponse struct {
	Name      string   `json:"name"`
	Connected bool     `json:"connected"`
	Disabled  bool     `json:"disabled,omitempty"`
	Transport string   `json:"transport,omitempty"`
	URL       string   `json:"url,omitempty"`
	Command   string   `json:"command,omitempty"`
	Tools     []string `json:"tools"`
	// Editable is true only when the server has a stored config row (i.e. it
	// was added via the UI/API). Servers auto-connected from the built-in
	// registry via env vars have no editable config; the FE hides Edit for
	// them and shows they're configured via the environment instead.
	Editable bool `json:"editable"`
}

type MemoryItem struct {
	ID        int64      `json:"id"`
	UserID    string     `json:"user_id"`
	Agent     string     `json:"agent"`
	Type      MemoryType `json:"type"`
	Topic     string     `json:"topic"`
	Content   string     `json:"content"`
	Tags      string     `json:"tags"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt time.Time  `json:"updated_at"`
}

type MemoryLink struct {
	Scope    MemoryScope `json:"scope"`
	ScopeID  string      `json:"scope_id"`
	UserID   string      `json:"user_id"`
	FromPath string      `json:"from_path"`
	ToPath   string      `json:"to_path"`
}

type MemoryPage struct {
	Scope       MemoryScope `json:"scope"`
	ScopeID     string      `json:"scope_id"`
	UserID      string      `json:"user_id"`
	Path        string      `json:"path"`
	Content     string      `json:"content"`
	Frontmatter string      `json:"frontmatter,omitempty"`
	CreatedAt   time.Time   `json:"created_at"`
	UpdatedAt   time.Time   `json:"updated_at"`
}

type MemoryResponse struct {
	UserID string       `json:"user_id"`
	Agent  string       `json:"agent"`
	Layers []UserMemory `json:"layers"`
}

type MemoryScope string

type MemoryType string

type MessageResponse struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type MetricsResponse struct {
	Iterations   int       `json:"iterations"`
	InputTokens  int       `json:"input_tokens"`
	OutputTokens int       `json:"output_tokens"`
	CostUSD      float64   `json:"cost_usd"`
	ToolCalls    int       `json:"tool_calls"`
	Errors       int       `json:"errors"`
	LastActiveAt time.Time `json:"last_active_at,omitempty"`
}

type MigrationReport struct {
	JustApplied    bool
	AlreadyApplied bool
	PagesWritten   int
	Users          int
	AgentsTouched  int
}

type MiraConfig struct {
	Name          string
	DisplayName   string
	Title         string
	Model         string
	FallbackModel string
}

type PeeringStatusResponse struct {
	Enabled    bool   `json:"enabled"`
	NodeID     string `json:"node_id"`
	ListenAddr string `json:"listen_addr"`
	PeerCount  int    `json:"peer_count"`
}

type PopulationInfoResponse struct {
	Kind              string   `json:"kind"`
	Name              string   `json:"name"`
	Version           string   `json:"version,omitempty"`
	Description       string   `json:"description,omitempty"`
	Author            string   `json:"author,omitempty"`
	Tags              []string `json:"tags,omitempty"`
	Persona           string   `json:"persona,omitempty"`
	Skills            []string `json:"skills,omitempty"`
	RecommendedSkills []string `json:"recommended_skills,omitempty"`
	SystemPrompt      string   `json:"system_prompt,omitempty"`
	Installed         bool     `json:"installed"`
	InstalledPath     string   `json:"installed_path,omitempty"`
}

type PopulationInstallRequest struct {
	Name string `json:"name"`
}

type PopulationInstalledItem struct {
	Kind    string `json:"kind"`
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
	Path    string `json:"path,omitempty"`
}

type PopulationSearchResult struct {
	Kind        string   `json:"kind"`
	Name        string   `json:"name"`
	Version     string   `json:"version,omitempty"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	Score       float64  `json:"score,omitempty"`
}

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

type ProcessDetailResponse struct {
	ProcessResponse
	Messages []MessageResponse `json:"messages"`
}

type ProcessResponse struct {
	ID          string          `json:"id"`
	Agent       string          `json:"agent"`
	Task        string          `json:"task,omitempty"`
	Status      string          `json:"status"`
	StartedAt   time.Time       `json:"started_at"`
	CompletedAt *time.Time      `json:"completed_at,omitempty"`
	ParentID    string          `json:"parent_id,omitempty"`
	SpawnDepth  int             `json:"spawn_depth"`
	SpawnReason string          `json:"spawn_reason,omitempty"`
	Metrics     MetricsResponse `json:"metrics"`
}

type ProcessSnapshot struct {
	ID           int64      `json:"id"`
	ProcessID    string     `json:"process_id"`
	AgentName    string     `json:"agent_name"`
	Status       string     `json:"status"`
	ParentID     string     `json:"parent_id,omitempty"`
	InputTokens  int        `json:"input_tokens"`
	OutputTokens int        `json:"output_tokens"`
	CostUSD      float64    `json:"cost_usd"`
	StartedAt    time.Time  `json:"started_at"`
	CompletedAt  *time.Time `json:"completed_at,omitempty"`
	SnapshotAt   time.Time  `json:"snapshot_at"`
}

type PromptHistoryItem struct {
	ID        int64     `json:"id"`
	Prompt    string    `json:"prompt"`
	CreatedAt time.Time `json:"created_at"`
}

type RecallEntry struct {
	Scope  MemoryScope  `json:"scope"`
	Path   string       `json:"path"`
	Source RecallSource `json:"source"`
	At     time.Time    `json:"at"`
}

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

type RecallSource string

type RetentionPolicy struct {
	Events       time.Duration
	Snapshots    time.Duration
	ChatMessages time.Duration
}

type RetentionSweepResult struct {
	Events       int64
	Snapshots    int64
	ChatMessages int64
}

type RoutineFrequency string

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

type Schedule struct {
	Frequency  RoutineFrequency `json:"frequency"`
	Time       string           `json:"time"`     // HH:mm 24h
	Timezone   string           `json:"timezone"` // IANA, e.g. America/New_York
	DaysOfWeek []int            `json:"days_of_week,omitempty"`
	DayOfMonth *int             `json:"day_of_month,omitempty"`
	// Cron is set when Frequency == custom; otherwise it's the derived
	// expression returned on read for debugging.
	Cron string `json:"cron,omitempty"`
}

type ScheduledJob struct {
	// ID is the server-generated stable identifier. For rows created
	// before the routines migration, ID == Name (backfilled by the
	// migration).
	ID string `json:"id"`
	// Name is the cron-runner key + DSL lookup key. For new routines the
	// API sets Name == ID; legacy rows keep their original slug.
	Name string `json:"name"`
	// Title is the user-facing display label (e.g. "Daily standup
	// reminder"). Empty for legacy rows; falls back to Name in API
	// responses.
	Title string `json:"title,omitempty"`
	Cron  string `json:"cron"`
	// ScheduleJSON is the marshalled Schedule struct as supplied by the
	// FE. Empty when the row was created via the DSL or the legacy flat
	// API; in that case responses synthesize a `Custom` schedule that
	// echoes Cron.
	ScheduleJSON string     `json:"-"`
	AgentName    string     `json:"agent"`
	Message      string     `json:"message"`
	Enabled      bool       `json:"enabled"`
	LastRunAt    *time.Time `json:"last_run_at,omitempty"`
	CreatedAt    time.Time  `json:"created_at"`
	UpdatedAt    time.Time  `json:"updated_at"`
}

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

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

type Setting struct {
	Key       string    `json:"key"`
	Value     string    `json:"value"`
	Sensitive bool      `json:"sensitive"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type SpawnTreeNodeResponse struct {
	ProcessID   string                  `json:"process_id"`
	AgentName   string                  `json:"agent_name"`
	Task        string                  `json:"task,omitempty"`
	Status      string                  `json:"status"`
	SpawnDepth  int                     `json:"spawn_depth"`
	SpawnReason string                  `json:"spawn_reason,omitempty"`
	StartedAt   time.Time               `json:"started_at"`
	Children    []SpawnTreeNodeResponse `json:"children,omitempty"`
}

type StatsResponse struct {
	TotalProcesses           int     `json:"total_processes"`
	RunningProcesses         int     `json:"running_processes"`
	CompletedProcesses       int     `json:"completed_processes"`
	FailedProcesses          int     `json:"failed_processes"`
	TotalInputTokens         int     `json:"total_input_tokens"`
	TotalOutputTokens        int     `json:"total_output_tokens"`
	TotalCacheCreationTokens int     `json:"total_cache_creation_tokens"`
	TotalCacheReadTokens     int     `json:"total_cache_read_tokens"`
	TotalCostUSD             float64 `json:"total_cost_usd"`
	TotalToolCalls           int     `json:"total_tool_calls"`
	TotalErrors              int     `json:"total_errors"`
	Uptime                   string  `json:"uptime"`
}

type Store interface {
	// Init creates tables if they don't exist.
	Init() error

	// Close closes the store.
	Close() error

	// InsertEvent records an orchestration event.
	InsertEvent(e StoreEvent) error

	// InsertProcessSnapshot records a process state snapshot.
	InsertProcessSnapshot(s ProcessSnapshot) error

	// InsertWorkflowRun records a workflow execution.
	InsertWorkflowRun(r WorkflowRun) error

	// UpdateWorkflowRun updates a workflow run status.
	UpdateWorkflowRun(runID string, status string, result string) error

	// UpdateWorkflowRunSteps replaces the per-step checkpoint JSON on a
	// workflow run so interrupted runs show where they died.
	UpdateWorkflowRunSteps(runID string, stepsJSON string) error

	// ReconcileOrphanedWorkflowRuns marks runs stuck at status='running'
	// as 'interrupted'. Called at boot: runs execute in-process, so any
	// 'running' row at startup died with the previous server. Returns
	// the number of runs reconciled.
	ReconcileOrphanedWorkflowRuns() (int64, error)

	// ListEvents returns recent events, newest first.
	ListEvents(limit int) ([]StoreEvent, error)

	// SearchEvents returns events matching the filter, newest first.
	// Used by the activity log endpoint (refs govega#33). totalCount is
	// the unpaginated match count so the FE can render a hit total
	// without re-querying.
	SearchEvents(filter ActivityFilter) (events []StoreEvent, totalCount int, err error)

	// ListProcessSnapshots returns the latest snapshot per process.
	ListProcessSnapshots() ([]ProcessSnapshot, error)

	// ListWorkflowRuns returns recent workflow runs.
	ListWorkflowRuns(limit int) ([]WorkflowRun, error)

	// InsertComposedAgent persists a composed agent definition.
	InsertComposedAgent(a ComposedAgent) error

	// ListComposedAgents returns all composed agents.
	ListComposedAgents() ([]ComposedAgent, error)

	// DeleteComposedAgent removes a composed agent by name.
	DeleteComposedAgent(name string) error

	// InsertChatMessage persists a chat message. `activities` is the
	// list of completed tool calls captured during the streaming turn
	// that produced this message; pass nil for user messages or any
	// message without tool calls.
	InsertChatMessage(agent, role, content string, activities []vega.ToolActivity) error

	// ListChatMessages returns chat history for an agent.
	ListChatMessages(agent string) ([]ChatMessage, error)

	// DeleteChatMessages removes all chat messages for an agent.
	DeleteChatMessages(agent string) error

	// SweepRetention deletes rows older than the per-table retention
	// windows. A zero duration keeps that table's rows forever. Returns
	// the number of rows deleted per table.
	SweepRetention(policy RetentionPolicy) (RetentionSweepResult, error)

	// UpsertMCPServer persists an MCP server connection config so it
	// auto-reconnects on restart.
	UpsertMCPServer(name, configJSON string) error

	// DeleteMCPServer removes a persisted MCP server connection.
	DeleteMCPServer(name string) error

	// ListMCPServers returns all persisted MCP server configs.
	ListMCPServers() ([]MCPServerConfig, error)

	// SetMCPServerDisabled enables or disables a persisted MCP server.
	// Errors when no server with that name exists.
	SetMCPServerDisabled(name string, disabled bool) error

	// UpsertMemoryPage creates a page if absent, or overwrites Content +
	// Frontmatter + advances UpdatedAt on conflict (PK = scope, scope_id,
	// user_id, path). CreatedAt is preserved across updates. Refs govega#71.
	UpsertMemoryPage(p MemoryPage) error

	// GetMemoryPage returns one page, or nil when not found.
	GetMemoryPage(scope MemoryScope, scopeID, userID, path string) (*MemoryPage, error)

	// ListMemoryPages returns every page under (scope, scopeID, userID).
	// When pathPrefix is non-empty, results are filtered to paths that
	// start with the prefix. Ordered by updated_at DESC.
	ListMemoryPages(scope MemoryScope, scopeID, userID, pathPrefix string) ([]MemoryPage, error)

	// DeleteMemoryPage removes one page. Also clears any link rows where
	// the page appears as from_path or to_path.
	DeleteMemoryPage(scope MemoryScope, scopeID, userID, path string) error

	// RenameMemoryPage moves a page from oldPath to newPath, and rewrites
	// every link row that referenced oldPath (as from_path or to_path) to
	// point at newPath. Atomic: either both succeed or neither does.
	RenameMemoryPage(scope MemoryScope, scopeID, userID, oldPath, newPath string) error

	// SearchMemoryPages does a case-insensitive substring search across
	// path and content, ranked by updated_at DESC. Limit defaults to 25.
	SearchMemoryPages(scope MemoryScope, scopeID, userID, query string, limit int) ([]MemoryPage, error)

	// ReplaceMemoryLinks replaces the set of out-edges from fromPath
	// atomically: removes existing rows where from_path = fromPath,
	// inserts one row per (fromPath, to) in toPaths. Empty toPaths just
	// clears the out-edges. Refs govega#71.
	ReplaceMemoryLinks(scope MemoryScope, scopeID, userID, fromPath string, toPaths []string) error

	// ListMemoryLinks returns every link under (scope, scopeID, userID).
	ListMemoryLinks(scope MemoryScope, scopeID, userID string) ([]MemoryLink, error)

	// ListMemoryScopeIDs returns every distinct scope_id that has at least
	// one page under (scope, userID). Used by the graph endpoint to
	// enumerate per-agent wikis when scope=all.
	ListMemoryScopeIDs(scope MemoryScope, userID string) ([]string, error)

	// UpsertUserMemory creates or updates a memory layer for a user+agent.
	UpsertUserMemory(userID, agent, layer, content string) error

	// GetUserMemory returns all memory layers for a user+agent.
	GetUserMemory(userID, agent string) ([]UserMemory, error)

	// DeleteUserMemory removes all memory for a user+agent.
	DeleteUserMemory(userID, agent string) error

	// InsertMemoryItem saves a memory item. If an item already exists with the
	// same (user_id, agent, type, content), its tags are merged and updated_at
	// advances rather than inserting a duplicate row. Items missing a Type are
	// stored as MemoryTypeReference.
	InsertMemoryItem(item MemoryItem) (int64, error)

	// SearchMemoryItems searches memory items by keyword across topic, content, and tags.
	SearchMemoryItems(userID, agent, query string, limit int) ([]MemoryItem, error)

	// SearchMemoryItemsByType is like SearchMemoryItems but additionally
	// filters to a single MemoryType.
	SearchMemoryItemsByType(userID, agent, query string, typ MemoryType, limit int) ([]MemoryItem, error)

	// DeleteMemoryItem removes a memory item by ID.
	DeleteMemoryItem(id int64) error

	// ListAllUserMemory returns every row in user_memory. Bulk-load helper
	// used by the wiki-memory migration (govega#71). Removed once the
	// legacy user_memory table is dropped.
	ListAllUserMemory() ([]UserMemory, error)

	// ListAllMemoryItems returns every row in memory_items. Bulk-load
	// helper for the wiki-memory migration. Removed alongside the table.
	ListAllMemoryItems() ([]MemoryItem, error)

	// ListMemoryItemsByTopic returns memory items for a given user+agent+topic.
	ListMemoryItemsByTopic(userID, agent, topic string) ([]MemoryItem, error)

	// UpsertScheduledJob creates or replaces a scheduled job.
	UpsertScheduledJob(job ScheduledJob) error

	// DeleteScheduledJob removes a scheduled job by name.
	DeleteScheduledJob(name string) error

	// ListScheduledJobs returns all scheduled jobs.
	ListScheduledJobs() ([]ScheduledJob, error)

	// GetScheduledJobByID returns one job by its server-generated id.
	// Returns nil, nil when not found.
	GetScheduledJobByID(id string) (*ScheduledJob, error)

	// MarkScheduledJobRun stamps the supplied time on last_run_at.
	MarkScheduledJobRun(name string, at time.Time) error

	// GetAgentBudget returns the persisted budget record for agentName,
	// or nil when the agent has no row yet (i.e. budget is implicitly
	// "no cap, soft-alert threshold default, disabled"). Refs govega#47.
	GetAgentBudget(agentName string) (*AgentBudget, error)

	// UpsertAgentBudget creates or replaces a per-agent budget row.
	// CreatedAt is preserved on update; UpdatedAt advances. Refs govega#47.
	UpsertAgentBudget(b AgentBudget) error

	// AgentSpendInPeriod returns the sum of cost_usd across the latest
	// snapshot of every process for agentName whose started_at falls
	// inside [from, to). When from/to are zero, the bound is treated
	// as unbounded on that side.
	AgentSpendInPeriod(agentName string, from, to time.Time) (float64, error)

	// InsertAgentBrainFile persists an attachment for the given agent.
	// content is read in-memory; callers must enforce size limits.
	InsertAgentBrainFile(f AgentBrainFile) error

	// ListAgentBrainFiles returns the metadata for every brain file
	// attached to agentName. Content is not loaded.
	ListAgentBrainFiles(agentName string) ([]AgentBrainFile, error)

	// GetAgentBrainFile returns one brain file, content included.
	// Returns nil, nil when the file doesn't exist or doesn't belong to
	// the agent.
	GetAgentBrainFile(agentName, id string) (*AgentBrainFile, error)

	// DeleteAgentBrainFile removes a brain file. Returns an error if the
	// file doesn't exist on the given agent.
	DeleteAgentBrainFile(agentName, id string) error

	// InsertWorkspaceFile records a file write by an agent.
	InsertWorkspaceFile(f WorkspaceFile) error

	// ListWorkspaceFiles returns workspace file records, optionally filtered by agent.
	ListWorkspaceFiles(agent string) ([]WorkspaceFile, error)

	// ListWorkspaceFileAgents returns distinct agent names that have written files.
	ListWorkspaceFileAgents() ([]string, error)

	// UpsertSetting creates or updates a setting.
	UpsertSetting(s Setting) error

	// GetSetting returns a setting by key.
	GetSetting(key string) (*Setting, error)

	// ListSettings returns all settings.
	ListSettings() ([]Setting, error)

	// DeleteSetting removes a setting by key.
	DeleteSetting(key string) error

	// CreateChannel creates a new channel.
	CreateChannel(id, name, description, createdBy string, team []string, mode string) error

	// GetChannel returns a channel by name.
	GetChannel(name string) (*Channel, error)

	// GetChannelByName returns minimal channel info for the dsl.ChannelBackend interface.
	GetChannelByName(name string) (*dsl.ChannelInfo, error)

	// ListAllChannels returns all channels as ChannelInfo.
	ListAllChannels() ([]dsl.ChannelInfo, error)

	// ListChannelsForAgent returns channels where the agent is a team member.
	ListChannelsForAgent(agent string) ([]dsl.ChannelInfo, error)

	// ListChannels returns all channels with unread counts for the given user.
	ListChannels(userID string) ([]Channel, error)

	// DeleteChannel removes a channel by name.
	DeleteChannel(name string) error

	// UpdateChannelTeam updates the team members of a channel.
	UpdateChannelTeam(name string, team []string) error

	// UpdateChannelMeta partially updates a channel's display fields.
	// Pass nil to leave a field unchanged; empty-string pointer clears.
	// Returns sql.ErrNoRows if the channel doesn't exist.
	UpdateChannelMeta(currentName string, newName, newDescription *string) error

	// FindChannelForAgents returns the channel where both agents are team members.
	FindChannelForAgents(agent1, agent2 string) (channelID string, channelName string, err error)

	// InsertInboxItem creates a new inbox item.
	InsertInboxItem(fromAgent, subject, body, priority string) (int64, error)

	// InsertResolvedInboxItem creates an inbox item that is already resolved.
	// Used by the success path of classifyDispatchOutcome so "Task
	// completed by X" entries skip the pending queue and land directly in
	// Done — keeps the orchestrator's working set focused on items that
	// actually need a decision. The resolution string is required and
	// surfaces in the UI's Done column.
	InsertResolvedInboxItem(fromAgent, subject, body, resolution string) (int64, error)

	// ListInboxItems returns inbox items filtered by status.
	ListInboxItems(status string, limit int) ([]InboxItem, error)

	// GetInboxItem returns a single inbox item by ID.
	GetInboxItem(id int64) (*InboxItem, error)

	// ResolveInboxItem marks an inbox item as resolved.
	ResolveInboxItem(id int64, resolution string) error

	// DeleteResolvedInboxItems removes all resolved inbox items and their replies.
	DeleteResolvedInboxItems() (int64, error)

	// DeleteInboxItem removes a single inbox item (and its replies) by id,
	// regardless of status. Returns sql.ErrNoRows if no item matches.
	DeleteInboxItem(id int64) error

	// TriageInboxItems increments triage_count + stamps last_triaged_at
	// for each pending id, then auto-resolves any whose post-increment
	// count is >= threshold. Returns the ids that were auto-aged on
	// this call so callers can log/report. Already-resolved items and
	// unknown ids are silently ignored. The threshold guard is what
	// stops the orchestrator burning tokens re-reading items it can't
	// decide every heartbeat.
	TriageInboxItems(ids []int64, threshold int) ([]int64, error)

	// InsertChannelMessage inserts a message into a channel.
	InsertChannelMessage(channelID, agent, role, content string, threadID *int64, metadata, sender string, activities []vega.ToolActivity) (int64, error)

	// ListChannelMessages returns top-level messages for a channel with reply counts.
	ListChannelMessages(channelID string, limit int) ([]ChannelMessage, error)

	// RecentChannelMessages returns the last N messages (lightweight, for status checks).
	RecentChannelMessages(channelID string, limit int) ([]dsl.ChannelMessage, error)

	// ListThreadMessages returns all replies in a thread.
	ListThreadMessages(channelID string, threadID int64) ([]ChannelMessage, error)

	// MarkChannelRead updates the read cursor for a channel.
	MarkChannelRead(channelID, userID string) error

	// MarkChatRead updates the read cursor for a DM conversation.
	MarkChatRead(agent, userID string) error

	// ChatUnreadCounts returns agent → unread message count for DMs.
	ChatUnreadCounts(userID string) (map[string]int, error)

	// ResetData clears all transient data (chat, memory, agents, files, etc.)
	// but preserves settings and prompt history.
	ResetData() error

	// InsertPromptHistory records an original user prompt to iris.
	InsertPromptHistory(prompt string) (int64, error)

	// ListPromptHistory returns prompt history entries, newest first.
	ListPromptHistory(limit int) ([]PromptHistoryItem, error)

	// SearchPromptHistory searches prompt history by keyword.
	SearchPromptHistory(query string, limit int) ([]PromptHistoryItem, error)

	// DeletePromptHistory removes a prompt history entry by ID.
	DeletePromptHistory(id int64) error

	// InsertTask creates a new task.
	InsertTask(t Task) error

	// GetTask returns a task by id, or (nil, nil) if not found.
	GetTask(id string) (*Task, error)

	// ListTasks returns tasks matching the filter, newest-updated first.
	ListTasks(f TaskFilter) ([]Task, error)

	// UpdateTask applies a partial update.
	UpdateTask(id string, u TaskUpdate) error

	// DeleteTask removes a task and its comments / process links.
	DeleteTask(id string) error

	// AddTaskComment appends a comment and bumps the task's updated_at.
	AddTaskComment(taskID, author, content string) (int64, error)

	// ListTaskComments returns comments oldest-first.
	ListTaskComments(taskID string) ([]TaskComment, error)

	// LinkTaskProcess associates a process with a task (idempotent).
	LinkTaskProcess(taskID, processID string) error

	// ListTaskProcesses returns process IDs linked to a task.
	ListTaskProcesses(taskID string) ([]string, error)

	// ListMyTasks returns tasks assigned to a specific agent.
	ListMyTasks(assignee string, status []string, limit int) ([]Task, error)

	// ListUnassignedTasks returns tasks with empty assignee.
	ListUnassignedTasks(limit int) ([]Task, error)

	// UpdateTaskStatus is a focused setter for the agent tool layer.
	UpdateTaskStatus(id, status string) error

	// AssignTask sets the assignee without changing status.
	AssignTask(id, assignee string) error

	// ClaimTask atomically sets assignee to caller and status to 'doing'.
	ClaimTask(id, assignee string) error

	// TaskStatsByAssignee returns per-assignee kanban task counters in a
	// single query. Used by the agents API to surface "how productive is
	// this agent" stats. Empty assignees are excluded.
	TaskStatsByAssignee() (map[string]AgentStatsResponse, error)
}