model

type ActivatePluginInput struct {
	TeamID     string
	PluginName string
	Version    string
	Digest     string
	Origin     PluginActivationOrigin
	ActorID    string
}

type Agent struct {
	ID           string `json:"id"`
	UserID       string `json:"user_id"`
	TeamID       string `json:"team_id,omitempty"`
	Name         string `json:"name"`
	Description  string `json:"description"`
	Instructions string `json:"instructions"`
	// Plugins names the catalog plugins this agent loads for a background run.
	// Nothing is inherited from the team's activations: an agent that names
	// none loads none. See docs/design/plugin-team-distribution.md §5.3.
	Plugins []string `json:"plugins,omitempty"`
	// Revision numbers the agent_revision row holding this content. It starts
	// at 1 and advances every time the definition changes.
	Revision int `json:"revision"`
	// DeletedAt is set when the agent was deleted. The row stays because work
	// that already refers to it — a task's agent, a step run's target, a
	// revision's subject — would otherwise point at nothing. A deleted agent is
	// invisible to every path that would start new work with it.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
}

type AgentDefinition struct {
	Name         string
	Description  string
	Instructions string
	// Plugins names catalog plugins, never releases. The version and digest
	// come from the team's activation, so moving a plugin to a new release
	// stays one edit in one place.
	Plugins []string
}

type AgentRevision struct {
	AgentID      string `json:"agent_id"`
	Revision     int    `json:"revision"`
	Name         string `json:"name"`
	Description  string `json:"description"`
	Instructions string `json:"instructions"`
	// Plugins is the selection this revision recorded. It versions with the
	// rest of the definition, so an old revision still answers what that agent
	// named.
	Plugins []string `json:"plugins,omitempty"`
	// CreatedBy is the user who wrote this revision, which is not necessarily
	// the agent's owner.
	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
}

type AgentStore interface {
	ListAgentsByUser(ctx context.Context, userID string) ([]Agent, error)
	ListAgentsByTeam(ctx context.Context, teamID string) ([]Agent, error)
	// GetAgent returns a live agent. A deleted one reads as not found, so no
	// caller can start new work with it by forgetting to check.
	GetAgent(ctx context.Context, agentID string) (*Agent, error)
	// GetAgentIncludingDeleted resolves an agent a record already refers to,
	// deleted or not. Use it to finish or describe work that named the agent
	// before it was deleted, never to start work with it.
	GetAgentIncludingDeleted(ctx context.Context, agentID string) (*Agent, error)
	CreateAgentInTeam(ctx context.Context, in CreateAgentInput) (*Agent, error)
	UpdateAgentInTeam(ctx context.Context, in UpdateAgentInput) (*Agent, error)
	// DeleteAgent and DeleteAgentInTeam mark the agent deleted rather than
	// removing the row. Deleting an agent a published workflow still names is
	// refused above this layer; see the delete handler.
	// Both return ErrNotFound when there is no such live agent for that owner.
	DeleteAgent(ctx context.Context, agentID, userID string) error
	DeleteAgentInTeam(ctx context.Context, agentID, teamID string) error
	// ListAgentRevisions returns an agent's revisions, newest first, with the
	// total count.
	ListAgentRevisions(ctx context.Context, agentID string, limit, offset int) ([]AgentRevision, int, error)
	// GetAgentRevision returns one revision, or nil when the agent has no such
	// revision number.
	GetAgentRevision(ctx context.Context, agentID string, revision int) (*AgentRevision, error)
}

type AppendMessageInput struct {
	ConversationID string
	Role           string
	Content        string
	Channel        *string
	ToolCallID     *string
	ToolCallsJSON  *string
	// ProviderStateJSON is set only for an assistant message from a protocol
	// that produced reasoning state.
	ProviderStateJSON *string
	// PartsJSON is set when the message carries non-text content.
	PartsJSON *string
}

type Artifact struct {
	ID        string `json:"id"`
	TeamID    string `json:"team_id"`
	Filename  string `json:"filename"`
	MediaType string `json:"media_type"`
	SizeBytes int64  `json:"size_bytes"`
	SHA256    string `json:"sha256"`
	// StorageKey is where the object store put the bytes. It is never
	// serialized: an API response, tool output, trace, or audit event that
	// carried it would leak deployment layout and outlive the layout's freedom
	// to change.
	StorageKey    string `json:"-"`
	CreatedByType string `json:"created_by_type"`
	CreatedByID   string `json:"created_by_id"`
	SourceType    string `json:"source_type"`
	SourceID      string `json:"source_id,omitempty"`
	Title         string `json:"title,omitempty"`
	// DeletedAt tombstones the artifact. Metadata and content stop being
	// served the moment it is set; removing the object itself is a later,
	// separate step under retention policy.
	DeletedAt *time.Time `json:"deleted_at,omitempty"`
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
}

type ArtifactStore interface {
	CreateArtifact(ctx context.Context, in CreateArtifactInput) (*Artifact, error)
	// GetArtifact returns the artifact by its ar_ ID, or (nil, nil) when there
	// is none. A tombstoned artifact is returned, not hidden: the caller has to
	// tell "never existed" from "deleted" to answer either one correctly.
	GetArtifact(ctx context.Context, artifactID string) (*Artifact, error)
	// ListArtifactsByTeam returns live artifacts newest first, with the total.
	ListArtifactsByTeam(ctx context.Context, teamID string, limit, offset int) ([]Artifact, int, error)
	// ListArtifactsBySource returns live artifacts produced by any of the given
	// operations, newest first, keyed by source ID. It is how a work object
	// finds what its runs published without owning them.
	ListArtifactsBySource(ctx context.Context, sourceIDs []string) (map[string][]Artifact, error)
	// SoftDeleteArtifact tombstones the artifact and reports whether it changed
	// anything, so a repeat delete is distinguishable from a first one.
	SoftDeleteArtifact(ctx context.Context, artifactID string, deletedAt time.Time) (bool, error)
}

type ArtifactWithTask struct {
	ArtifactID       string    `json:"artifact_id"`
	TaskID           string    `json:"task_id"`
	TaskRunID        string    `json:"task_run_id"`
	ConversationID   string    `json:"conversation_id"`
	UserID           string    `json:"user_id"`
	CreatedAt        time.Time `json:"created_at"`
	TaskInputSnippet string    `json:"task_input_snippet"`
}

type AuditCursor struct {
	CreatedAt time.Time
	ID        string
}

type AuditEvent struct {
	ID string `json:"id"`
	// TeamID is empty for actions that are not team-scoped, such as a login.
	TeamID     string `json:"team_id,omitempty"`
	ActorType  string `json:"actor_type"`
	ActorID    string `json:"actor_id"`
	Action     string `json:"action"`
	TargetType string `json:"target_type,omitempty"`
	TargetID   string `json:"target_id,omitempty"`
	// Detail is a short, non-sensitive note — a role name, a model alias. It
	// is not a place for request bodies.
	Detail    string    `json:"detail,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type AuditFilter struct {
	// TeamID matches events scoped to one team. It does not match the events
	// that have no team, such as a login or a grant — see WithoutTeam.
	TeamID string
	// WithoutTeam matches only the deployment-scoped events. It exists because
	// an empty TeamID already means "any team", so there would otherwise be no
	// way to ask for the ones a team-scoped reader can never see.
	WithoutTeam bool
	ActorID     string
	Action      string
	// Since and Until bound created_at, inclusive and exclusive respectively.
	// Zero means unbounded.
	Since time.Time
	Until time.Time
}

type AuditPruneStore interface {
	// PruneAuditEvents deletes events recorded before the cutoff, at most
	// limit of them, and returns how many went. A bounded delete keeps one
	// sweep from holding the table while a backlog of an old deployment's
	// events is removed; the caller repeats until it returns fewer than limit.
	PruneAuditEvents(ctx context.Context, before time.Time, limit int) (int64, error)
	// OldestAuditEventAt reports the timestamp of the oldest event, or zero
	// when the table is empty. The sweep uses it to say what a prune actually
	// removed rather than only what it was allowed to.
	OldestAuditEventAt(ctx context.Context) (time.Time, error)
}

type AuditStore interface {
	AuditWriter
	// ListAuditEvents returns a team's events, newest first.
	//
	// It stays alongside SearchAuditEvents rather than being replaced by it:
	// a team owner asks a narrower question, and giving that reader the wider
	// method is how a team-scoped route acquires a deployment-scoped answer.
	ListAuditEvents(ctx context.Context, teamID string, limit, offset int) ([]AuditEvent, int, error)
	// SearchAuditEvents returns events across every team, newest first. It is
	// the deployment-scoped read, and only /api/admin routes may reach it.
	SearchAuditEvents(ctx context.Context, filter AuditFilter, limit, offset int) ([]AuditEvent, int, error)
	// ExportTeamAuditEvents returns one page of a team's events, newest first,
	// continuing from after. It answers the same question as ListAuditEvents
	// and differs only in how it pages, because an export walks the whole
	// trail rather than showing the first screen of it.
	ExportTeamAuditEvents(ctx context.Context, teamID string, after AuditCursor, limit int) ([]AuditEvent, error)
	// ExportAuditEvents is the deployment-scoped counterpart, and the same rule
	// applies as for SearchAuditEvents: only /api/admin routes may reach it.
	// The pair stays split for the reason ListAuditEvents gives — a team-scoped
	// route that can name its own filter is a route that can widen it.
	ExportAuditEvents(ctx context.Context, filter AuditFilter, after AuditCursor, limit int) ([]AuditEvent, error)
}

type AuditWriter interface {
	// RecordAuditEvent appends one event. Events are append-only; nothing here
	// updates or deletes one, because a record that can be edited is not
	// evidence.
	RecordAuditEvent(ctx context.Context, in AuditEvent) error
}

type ClaimTaskInput struct {
	TaskID         string
	ExpectedStatus string
	NewStatus      string
	StartedAt      *time.Time
	EndedAt        *time.Time
	Output         *string
	ErrorMessage   *string
	SessionID      *string
}

type ClaimTaskRunInput struct {
	TaskRunID      string
	ExpectedStatus RunStatus
	NewStatus      RunStatus
	StartedAt      *time.Time
	EndedAt        *time.Time
	Output         *string
	ErrorMessage   *string
	SessionID      *string
}

type Conversation struct {
	ID        string    `json:"id"`
	UserID    string    `json:"user_id"`
	TeamID    string    `json:"team_id,omitempty"`
	Channel   string    `json:"channel"`
	Title     string    `json:"title,omitempty"`
	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
}

type ConversationMessage struct {
	ID             string  `json:"id"`
	ConversationID string  `json:"conversation_id"`
	Role           string  `json:"role"`
	Content        string  `json:"content"`
	Channel        *string `json:"channel,omitempty"`
	ToolCallID     *string `json:"tool_call_id,omitempty"`
	ToolCallsJSON  *string `json:"tool_calls,omitempty"`
	// ProviderStateJSON is opaque reasoning state for an assistant message,
	// stored and replayed but never read here. See core/llm.ProviderState.
	ProviderStateJSON *string `json:"provider_state,omitempty"`
	// PartsJSON is non-text content on the message, stored as the canonical
	// part list. Content remains the text describing it.
	PartsJSON *string   `json:"parts,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type ConversationMessageStore interface {
	AppendMessage(ctx context.Context, in AppendMessageInput) (*ConversationMessage, error)
	ListMessages(ctx context.Context, conversationID string) ([]ConversationMessage, error)
	// GetMessage returns one message by handle, or (nil, nil) when there is no
	// such row. It exists because a run names the message that asked for it,
	// and reading a whole transcript to resolve one handle is the wrong shape
	// for a question about one run.
	GetMessage(ctx context.Context, messageID string) (*ConversationMessage, error)
}

type ConversationStore interface {
	CreateConversation(ctx context.Context, userID, channel, createdBy string) (*Conversation, error)
	CreateConversationInTeam(ctx context.Context, teamID, userID, channel, createdBy string) (*Conversation, error)
	GetConversation(ctx context.Context, conversationID string) (*Conversation, error)
	ListConversationsByUser(ctx context.Context, userID string, limit, offset int) ([]Conversation, int, error)
	ListConversationsByTeam(ctx context.Context, teamID string, limit, offset int) ([]Conversation, int, error)
	UpdateConversationTitle(ctx context.Context, conversationID, title string) error
}

type CreateAgentInput struct {
	TeamID string
	UserID string
	Def    AgentDefinition
}

type CreateArtifactInput struct {
	TeamID        string
	ArtifactID    string
	Filename      string
	MediaType     string
	SizeBytes     int64
	SHA256        string
	StorageKey    string
	CreatedByType string
	CreatedByID   string
	SourceType    string
	SourceID      string
	Title         string
	ExpiresAt     *time.Time
}

type CreateIssueCommentInput struct {
	IssueID         string
	AuthorKind      string
	AuthorID        string
	Body            string
	SourceTaskID    *string
	SourceTaskRunID *string
}

type CreateIssueInput struct {
	Title         string
	Description   string
	ParentIssueID *string
}

type CreateLLMModelInput struct {
	Name              string
	ProviderType      string
	APIURL            string
	APIKey            string
	Model             string
	ContextWindow     int
	CallTimeout       int
	MaxTokens         int
	Reasoning         string
	CacheMode         string
	CacheTTL          string
	Vision            bool
	Currency          string
	InputPerMTok      int64
	CacheReadPerMTok  int64
	CacheWritePerMTok int64
	OutputPerMTok     int64
	Capabilities      []string
}

type CreatePluginInput struct {
	Name        string
	DisplayName string
	Description string
	CreatedBy   string
}

type CreatePluginReleaseInput struct {
	PluginName         string
	Version            string
	MinBuildmaxVersion string
	Digest             string
	ObjectKey          string
	SizeBytes          int64
	Inspection         PluginInspection
	Source             PluginReleaseSource
	PublishedBy        string
}

type CreateTaskInput struct {
	ConversationID          string
	TeamID                  string
	Input                   string
	Title                   string
	CreatedBy               string
	InitialRunCreatedBy     string
	InitialRunCreatedByType string
	InitialRunTriggerSource string
	// InitialRunSourceMessageID names the message that asked for this task.
	InitialRunSourceMessageID *string
	TitlePromptTokens         int
	TitleCompletionTokens     int
	AgentID                   *string
	IssueID                   *string
}

type CreateTaskRunInput struct {
	TaskID        string
	Input         string
	CreatedBy     string
	CreatedByType string
	TriggerSource string
	// RetryOfTaskRunID names the run this one repeats, when it repeats one.
	RetryOfTaskRunID *string
	// SourceMessageID names the conversation message that asked for this run.
	SourceMessageID *string
}

type CreateWorkflowRunInput struct {
	WorkflowID       string
	WorkflowRevision int
	IssueID          *string
	ConversationID   string
	Status           string
	CreatedBy        string
	StartedAt        *time.Time
}

type CreateWorkflowStepRunInput struct {
	StepID            string
	StepIndex         int
	StepType          string
	TargetAgentID     *string
	AgentName         string
	AgentDescription  string
	AgentInstructions string
	AgentRevision     int
	Prompt            string
	Status            string
}

type Issue struct {
	ID            string    `json:"id"`
	UserID        string    `json:"user_id"`
	TeamID        string    `json:"team_id,omitempty"`
	ParentIssueID *string   `json:"parent_issue_id,omitempty"`
	Title         string    `json:"title"`
	Description   string    `json:"description"`
	Status        string    `json:"status"`
	AssigneeKind  *string   `json:"assignee_kind,omitempty"`
	AssigneeID    *string   `json:"assignee_id,omitempty"`
	CreatedBy     string    `json:"created_by"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

type IssueChildStats struct {
	Total int `json:"total"`
	Done  int `json:"done"`
}

type IssueComment struct {
	ID              string    `json:"id"`
	IssueID         string    `json:"issue_id"`
	AuthorKind      string    `json:"author_kind"`
	AuthorID        string    `json:"author_id"`
	Body            string    `json:"body"`
	SourceTaskID    *string   `json:"source_task_id,omitempty"`
	SourceTaskRunID *string   `json:"source_task_run_id,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
	// EditedAt is nil until the body is changed. Its absence is meaningful:
	// it means the text is as first written.
	EditedAt *time.Time `json:"edited_at,omitempty"`
}

type IssueCommentStore interface {
	CreateIssueComment(ctx context.Context, in CreateIssueCommentInput) (*IssueComment, error)
	// ListIssueComments returns comments oldest first — a thread reads in the
	// order it was written.
	ListIssueComments(ctx context.Context, issueID string, limit, offset int) ([]IssueComment, int, error)
	GetIssueComment(ctx context.Context, commentID string) (*IssueComment, error)
	UpdateIssueComment(ctx context.Context, commentID, body string) (*IssueComment, error)
	DeleteIssueComment(ctx context.Context, commentID string) error
	// CountIssueComments returns comment totals keyed by issue ID. Issues with
	// no comments are absent from the map.
	CountIssueComments(ctx context.Context, issueIDs []string) (map[string]int, error)
}

type IssueStore interface {
	CreateIssue(ctx context.Context, userID string, in CreateIssueInput) (*Issue, error)
	CreateIssueInTeam(ctx context.Context, teamID, createdBy string, in CreateIssueInput) (*Issue, error)
	ListIssuesByUser(ctx context.Context, userID string, limit, offset int) ([]Issue, int, error)
	ListIssuesByTeam(ctx context.Context, teamID string, filter ListIssuesFilter, limit, offset int) ([]Issue, int, error)
	ListIssueChildren(ctx context.Context, parentIssueID string) ([]Issue, error)
	// ChildStatsForIssues returns sub-issue progress keyed by parent issue ID.
	// Parents with no children are absent from the map rather than present with
	// a zero value, so callers must treat a miss as "no sub-issues".
	ChildStatsForIssues(ctx context.Context, issueIDs []string) (map[string]IssueChildStats, error)
	GetIssue(ctx context.Context, issueID string) (*Issue, error)
	UpdateIssue(ctx context.Context, issueID, userID string, in UpdateIssueInput) (*Issue, error)
	UpdateIssueInTeam(ctx context.Context, issueID, teamID string, in UpdateIssueInput) (*Issue, error)
}

type LLMCall struct {
	ID string `json:"id"`
	// ClientCallID is the caller's idempotency key, unique within one user's
	// calls. It is absent for calls the server makes on its own behalf.
	ClientCallID *string `json:"client_call_id,omitempty"`

	// Identity — derived from authentication, never from the request body.
	//
	// A call is attributed to a person. There is no team column: a foreground
	// call belongs to no team, and a run's team is reached through TaskRunID.
	// See docs/design/client-modes.md section 9.
	UserID    *string `json:"user_id,omitempty"`
	TaskRunID *string `json:"task_run_id,omitempty"`

	// Correlation — context for investigation, not authorization input.
	Surface   string  `json:"surface,omitempty"`
	SessionID *string `json:"session_id,omitempty"`
	TaskID    *string `json:"task_id,omitempty"`

	// Model — what the caller asked for and what it resolved to.
	Model         string `json:"model,omitempty"`
	TargetID      string `json:"target_id"`
	ProviderType  string `json:"provider_type"`
	UpstreamModel string `json:"upstream_model"`
	Streaming     bool   `json:"streaming"`

	// Timing, in unix seconds like every other table.
	AcceptedAt        time.Time  `json:"accepted_at"`
	UpstreamStartedAt *time.Time `json:"upstream_started_at,omitempty"`
	FirstDeltaAt      *time.Time `json:"first_delta_at,omitempty"`
	CompletedAt       *time.Time `json:"completed_at,omitempty"`

	// Outcome.
	Status string `json:"status"`
	// ErrorClass is the stable BuildMax error classification, never an upstream
	// error body.
	ErrorClass *string `json:"error_class,omitempty"`
	// Attempts counts upstream attempts, so a retry does not read as two calls.
	Attempts int `json:"attempts,omitempty"`

	// Usage.
	PromptTokens     *int   `json:"prompt_tokens,omitempty"`
	CompletionTokens *int   `json:"completion_tokens,omitempty"`
	TotalTokens      *int   `json:"total_tokens,omitempty"`
	CacheReadTokens  *int   `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens *int   `json:"cache_write_tokens,omitempty"`
	UsageSource      string `json:"usage_source,omitempty"`

	// Pricing is the rate snapshot taken when the call was accepted, in
	// nano-currency-units per million tokens. It is a snapshot rather than a
	// reference: a model's price changes, and recomputing an old call from the
	// new rates would rewrite what a team already spent. An empty Currency
	// means the model was unpriced then, which is not the same fact as a call
	// that cost nothing.
	Currency              string `json:"currency,omitempty"`
	RateInputPerMTok      *int64 `json:"rate_input_per_mtok,omitempty"`
	RateCacheReadPerMTok  *int64 `json:"rate_cache_read_per_mtok,omitempty"`
	RateCacheWritePerMTok *int64 `json:"rate_cache_write_per_mtok,omitempty"`
	RateOutputPerMTok     *int64 `json:"rate_output_per_mtok,omitempty"`
}

type LLMCallOutcome struct {
	Status            string
	ErrorClass        *string
	Attempts          int
	UpstreamStartedAt *time.Time
	FirstDeltaAt      *time.Time
	CompletedAt       time.Time
	// Usage is nil when the provider reported none; the record then keeps
	// LLMUsageSourceUnavailable rather than zero counts.
	Usage *LLMCallUsage
}

type LLMCallStore interface {
	// OpenLLMCall records an accepted call before the upstream request starts.
	// It assigns the call ID and returns the stored record.
	OpenLLMCall(ctx context.Context, call *LLMCall) (*LLMCall, error)
	// CompleteLLMCall writes the terminal outcome of an open call.
	CompleteLLMCall(ctx context.Context, llmCallID string, outcome LLMCallOutcome) error
	// GetLLMCall returns one call by ID, or (nil, nil) when not found.
	GetLLMCall(ctx context.Context, llmCallID string) (*LLMCall, error)
	// GetLLMCallByClientID returns one user's call by their idempotency key, or
	// (nil, nil) when not found. The key is scoped to the user who sent it, so
	// one caller's key can never resolve another's call.
	GetLLMCallByClientID(ctx context.Context, userID, clientCallID string) (*LLMCall, error)
	// ListLLMCallsByTaskRun returns a run's calls, oldest first, so a reader
	// follows the run in the order it happened.
	//
	// A run belongs to exactly one team, so authorizing the run authorizes its
	// ledger; the caller must have established that before asking.
	ListLLMCallsByTaskRun(ctx context.Context, taskRunID string) ([]LLMCall, error)
}

type LLMCallUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
	// CacheReadTokens and CacheWriteTokens are the cached parts of the prompt.
	// They break PromptTokens down rather than adding to it, so a spend report
	// must not sum them alongside it.
	CacheReadTokens  int    `json:"cache_read_tokens"`
	CacheWriteTokens int    `json:"cache_write_tokens"`
	Source           string `json:"source"`
}

type LLMModel struct {
	ID string `json:"id"`
	// Name is the operator-facing name, unique within a deployment.
	Name string `json:"name"`
	// ProviderType selects the client implementation.
	ProviderType string `json:"provider_type"`
	// APIURL is the upstream base URL.
	APIURL string `json:"api_url"`
	// Model is the provider's own model identifier.
	Model string `json:"model"`
	// ContextWindow is the usable context size; 0 uses the client default.
	ContextWindow int `json:"context_window,omitempty"`
	// CallTimeout bounds one upstream call in seconds; 0 uses the client default.
	CallTimeout int `json:"call_timeout,omitempty"`
	// MaxTokens caps one response; 0 uses the client default. The Anthropic
	// protocol requires the field, so a target speaking it always sends one.
	MaxTokens int `json:"max_tokens,omitempty"`
	// Reasoning is the effort level the upstream is asked for; empty means off.
	Reasoning string `json:"reasoning,omitempty"`
	// CacheMode and CacheTTL are the prompt-cache policy: which calls ask the
	// upstream to cache the stable prefix of a request, and for how long. Empty
	// means unset, which takes the default policy.
	CacheMode string `json:"cache_mode,omitempty"`
	CacheTTL  string `json:"cache_ttl,omitempty"`
	// Pricing is what this upstream charges, in nano-currency-units per
	// million tokens. The four rates are separate because caching prices them
	// differently; an empty currency means the model is unpriced and its calls
	// report cost as unavailable rather than as zero.
	//
	// These are the *current* rates. What a past call cost is not recomputed
	// from them — the ledger row keeps the rates that applied when it ran, so
	// a price change does not rewrite history.
	Currency          string `json:"currency,omitempty"`
	InputPerMTok      int64  `json:"input_per_mtok,omitempty"`
	CacheReadPerMTok  int64  `json:"cache_read_per_mtok,omitempty"`
	CacheWritePerMTok int64  `json:"cache_write_per_mtok,omitempty"`
	OutputPerMTok     int64  `json:"output_per_mtok,omitempty"`
	// Vision says the upstream accepts image input.
	Vision bool `json:"vision,omitempty"`
	// Capabilities is what this model supports, e.g. "text_chat".
	Capabilities []string `json:"capabilities,omitempty"`
	// Enabled lets an operator retire a model without deleting it.
	Enabled   bool      `json:"enabled"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type LLMModelStore interface {
	// CreateLLMModel stores a new model and returns it without its credential.
	CreateLLMModel(ctx context.Context, in CreateLLMModelInput) (*LLMModel, error)
	// GetLLMModel returns one model by ID, or (nil, nil) when not found.
	GetLLMModel(ctx context.Context, llmModelID string) (*LLMModel, error)
	// GetLLMModelByName returns one model by its operator-facing name, or
	// (nil, nil) when not found. Name is unique across the deployment and is
	// what a client names a model by, so this is the lookup on the call path.
	GetLLMModelByName(ctx context.Context, name string) (*LLMModel, error)
	// ListLLMModels returns every model, enabled or not, oldest first.
	ListLLMModels(ctx context.Context) ([]LLMModel, error)
	// SetLLMModelEnabled retires or restores a model.
	SetLLMModelEnabled(ctx context.Context, llmModelID string, enabled bool) error
	// LLMModelCredential returns the upstream key for a model. It is the only
	// way a credential leaves the store.
	LLMModelCredential(ctx context.Context, llmModelID string) (string, error)
}

type ListIssuesFilter struct {
	// TopLevelOnly restricts the listing to issues with no parent.
	TopLevelOnly bool
	// ParentIssueID restricts the listing to one parent's children. It is
	// ignored when TopLevelOnly is set.
	ParentIssueID string
}

type LoginCodeStore interface {
	// CreateLoginCode issues a single-use code for userID and returns the
	// plaintext, which is never stored and cannot be recovered afterwards.
	CreateLoginCode(ctx context.Context, userID string, ttl time.Duration) (plaintext string, expiresAt time.Time, err error)

	// ConsumeLoginCode redeems a code that was issued to userID. A code that
	// is unknown, already used, expired, or issued to somebody else returns
	// (false, nil) — the caller cannot tell which, and neither can an
	// attacker. Redemption is atomic: concurrent calls with the same code
	// produce exactly one winner.
	//
	// The account is named by the caller rather than reported back, so that a
	// code submitted with the wrong address is left untouched. A redemption
	// that spent the code first and checked the account afterwards burned it
	// on a typo, and the person retrying with the right address was then
	// refused for a reason nobody could see.
	ConsumeLoginCode(ctx context.Context, plaintext, userID string, now time.Time) (redeemed bool, err error)
}

type MovePluginActivationPinInput struct {
	TeamID     string
	PluginName string
	Version    string
	Digest     string
	ActorID    string
}

type NewRefreshToken struct {
	UserID string
	// SessionID names one login chain. Every rotation keeps it, so revoking a
	// session retires the whole chain rather than one link of it.
	SessionID string
	// Platform records which surface logged in ("portal", "cli", "desktop").
	// It is a label for the operator reading the session list, not something
	// the server enforces.
	Platform string
	TTL      time.Duration
}

type PasswordStore interface {
	// PasswordHash returns the stored hash for userID, or "" when the account
	// has no password and can only sign in with a login code.
	PasswordHash(ctx context.Context, userID string) (string, error)
	// SetPassword stores an already-hashed password. Hashing belongs to the
	// caller — this interface must not be a place where a plaintext password
	// can be passed by mistake.
	SetPassword(ctx context.Context, userID, encodedHash string, setAt time.Time) error
}

type Plugin struct {
	// Name is the manifest name, unique in the deployment, and the slug every
	// route addresses the plugin by.
	Name        string `json:"name"`
	DisplayName string `json:"display_name,omitempty"`
	Description string `json:"description,omitempty"`
	// ArchivedAt hides the entry from the default catalog and refuses new
	// releases. It never deletes anything: a local copy someone installed keeps
	// working, and the record still explains where that copy came from.
	ArchivedAt *time.Time `json:"archived_at,omitempty"`
	CreatedBy  string     `json:"created_by"`
	CreatedAt  time.Time  `json:"created_at"`
	UpdatedAt  time.Time  `json:"updated_at"`
}

type PluginActivation struct {
	ID         string `json:"id"`
	TeamID     string `json:"team_id"`
	PluginName string `json:"plugin_name"`
	Version    string `json:"version"`
	Digest     string `json:"digest"`
	// Enabled false suspends the activation without losing the pin. A suspended
	// activation fails the runs of the agents that name it rather than quietly
	// dropping the plugin from them.
	Enabled bool                   `json:"enabled"`
	Origin  PluginActivationOrigin `json:"origin"`

	ActivatedBy string    `json:"activated_by"`
	ActivatedAt time.Time `json:"activated_at"`
	UpdatedBy   string    `json:"updated_by,omitempty"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type PluginActivationOrigin string

type PluginActivationStore interface {
	// ActivatePlugin records a new activation, or returns
	// ErrPluginAlreadyActivated when the team has one for that plugin.
	ActivatePlugin(ctx context.Context, in ActivatePluginInput) (*PluginActivation, error)
	// GetPluginActivation returns one team's activation of one plugin, or
	// (nil, nil) when there is none.
	GetPluginActivation(ctx context.Context, teamID, pluginName string) (*PluginActivation, error)
	// ListPluginActivations returns a team's activations, oldest first,
	// suspended ones included: a suspended activation still explains why a run
	// failed.
	ListPluginActivations(ctx context.Context, teamID string) ([]PluginActivation, error)
	// MovePluginActivationPin repoints an activation, or returns ErrNotFound.
	MovePluginActivationPin(ctx context.Context, in MovePluginActivationPinInput) (*PluginActivation, error)
	// SetPluginActivationEnabled suspends or resumes an activation without
	// losing the pin, or returns ErrNotFound.
	SetPluginActivationEnabled(ctx context.Context, teamID, pluginName string, enabled bool, actorID string) (*PluginActivation, error)
}

type PluginCuration string

type PluginInspection struct {
	Skills      []string            `json:"skills,omitempty"`
	Subagents   []inspect.Subagent  `json:"subagents,omitempty"`
	MCP         []inspect.MCPServer `json:"mcp,omitempty"`
	Hooks       []inspect.Hook      `json:"hooks,omitempty"`
	EnvRefs     []string            `json:"env_refs,omitempty"`
	PluginPaths []string            `json:"plugin_paths,omitempty"`
	// Warnings are the findings that did not stop publication, kept so an
	// installer can show what a publisher chose to accept.
	Warnings []string `json:"warnings,omitempty"`
}

type PluginPin struct {
	PluginName string `json:"plugin_name"`
	Version    string `json:"version"`
	Digest     string `json:"digest"`
}

type PluginRelease struct {
	// PluginName is denormalised so a release can be reported without a second
	// read; the catalog entry remains the owner of the name.
	PluginName string `json:"plugin_name"`
	Version    string `json:"version"`
	// MinBuildmaxVersion is the release's own lower bound, kept as a column
	// because default install selection filters on it.
	MinBuildmaxVersion string `json:"min_buildmax_version,omitempty"`

	// Digest is the labelled SHA-256 of the stored bytes, calculated by the
	// server rather than accepted from the publisher.
	Digest    string `json:"digest"`
	ObjectKey string `json:"object_key"`
	SizeBytes int64  `json:"size_bytes"`

	// Inspection is the sanitized capability report shown before an install.
	Inspection PluginInspection `json:"inspection"`
	// Source is where the publisher says the bytes came from. Unlike the
	// digest, the server cannot verify it, so it is presented as a claim.
	Source PluginReleaseSource `json:"source"`

	PublishedBy string    `json:"published_by"`
	PublishedAt time.Time `json:"published_at"`

	// YankedAt removes the release from default selection without deleting it.
	// An existing local copy keeps working, and an exact version can still be
	// recovered by someone who acknowledges the state.
	YankedAt     *time.Time `json:"yanked_at,omitempty"`
	YankedBy     string     `json:"yanked_by,omitempty"`
	YankedReason string     `json:"yanked_reason,omitempty"`
}

type PluginReleaseSource struct {
	RemoteURL string `json:"remote_url,omitempty"`
	Commit    string `json:"commit,omitempty"`
	Branch    string `json:"branch,omitempty"`
	// Dirty says the working tree held uncommitted changes when it was packed,
	// which means the commit above does not describe these bytes.
	Dirty bool `json:"dirty,omitempty"`
}

type PluginStore interface {
	// CreatePlugin adds a catalog entry, or returns ErrPluginNameTaken.
	CreatePlugin(ctx context.Context, in CreatePluginInput) (*Plugin, error)
	// GetPlugin returns one entry by name, or (nil, nil) when there is none.
	GetPlugin(ctx context.Context, name string) (*Plugin, error)
	// ListPlugins returns entries oldest first, archived ones only when asked.
	ListPlugins(ctx context.Context, includeArchived bool) ([]Plugin, error)
	// UpdatePlugin changes display metadata, or returns ErrNotFound.
	UpdatePlugin(ctx context.Context, name string, in UpdatePluginInput) (*Plugin, error)
	// SetPluginArchived retires or restores an entry, or returns ErrNotFound.
	SetPluginArchived(ctx context.Context, name string, archived bool) error

	// CreatePluginRelease publishes one version. It returns
	// ErrPluginVersionExists when that version is already published,
	// ErrPluginArchived when the entry is retired, and ErrNotFound when there
	// is no such entry.
	CreatePluginRelease(ctx context.Context, in CreatePluginReleaseInput) (*PluginRelease, error)
	// GetPluginRelease returns one version, or (nil, nil) when there is none.
	GetPluginRelease(ctx context.Context, name, version string) (*PluginRelease, error)
	// ListPluginReleases returns every release of one plugin, oldest first,
	// including yanked ones: choosing between them is the caller's job.
	ListPluginReleases(ctx context.Context, name string) ([]PluginRelease, error)
	// YankPluginRelease withdraws a release from default selection, or returns
	// ErrNotFound.
	YankPluginRelease(ctx context.Context, name, version, actor, reason string) error
}

type QuotaTier struct {
	TierName           string `json:"tier_name"`
	MaxRunsPerPeriod   int    `json:"max_runs_per_period"`
	MaxTokensPerPeriod int    `json:"max_tokens_per_period"`
	PeriodDays         int    `json:"period_days"`
}

type QuotaTierStore interface {
	// GetQuotaTier returns the tier limits by tier name, or (nil, nil) when not found.
	GetQuotaTier(ctx context.Context, tierName string) (*QuotaTier, error)
}

type RefreshTokenStore interface {
	// CreateRefreshToken issues a token and returns the plaintext, which is
	// never stored — the row holds a hash, so a database backup yields no
	// usable credentials.
	CreateRefreshToken(ctx context.Context, in NewRefreshToken) (plaintext string, expiresAt time.Time, err error)

	// RotateRefreshToken exchanges plaintext for a fresh token in the same
	// session, spending the presented one.
	//
	// Within grace of having been spent, a token may be exchanged again. That
	// window is not a concession to sloppy clients: BuildMax's CLI and Desktop
	// share one credentials file across independent processes, and two of them
	// refreshing at the same moment is normal rather than suspicious. Both
	// receive a usable token; both stay in the same session.
	//
	// Past the grace window a spent token means ErrRefreshTokenReused, and the
	// whole session is revoked first — logging out the legitimate holder is the
	// correct response when a credential may be in two hands. That error comes
	// back with UserID and SessionID populated and Plaintext empty, so the
	// caller can record what was revoked.
	RotateRefreshToken(ctx context.Context, plaintext string, now time.Time, ttl, grace time.Duration) (RotatedRefreshToken, error)

	// RevokeRefreshTokenSession revokes the session the token belongs to and
	// reports whose it was. An unknown token is not an error: logging out
	// something already gone is a success.
	RevokeRefreshTokenSession(ctx context.Context, plaintext string, now time.Time) (userID, sessionID string, err error)

	// RevokeSession revokes every live token in one session and returns how
	// many it retired.
	RevokeSession(ctx context.Context, sessionID string, now time.Time) (int64, error)

	// RevokeUserSessions revokes every live session the user has and returns
	// how many tokens it retired. This is what "sign them out everywhere"
	// means, and it is the strongest thing disabling an account can do to a
	// credential the server actually stores.
	RevokeUserSessions(ctx context.Context, userID string, now time.Time) (int64, error)

	// CountUserSessions counts the user's live sessions — distinct login
	// chains, not tokens, since a chain is what a person would recognise as
	// "signed in on my laptop".
	CountUserSessions(ctx context.Context, userID string, now time.Time) (int, error)

	// DeleteExpiredRefreshTokens removes rows that can no longer be exchanged.
	DeleteExpiredRefreshTokens(ctx context.Context, before time.Time) (int64, error)
}

type RotatedRefreshToken struct {
	UserID    string
	SessionID string
	Plaintext string
	ExpiresAt time.Time
}

type RunStatus string

type SchemaMigration struct {
	ID        string    `json:"id"`
	AppliedAt time.Time `json:"applied_at"`
}

type SchemaStore interface {
	// AppliedMigrations returns applied migrations, oldest first.
	AppliedMigrations(ctx context.Context) ([]SchemaMigration, error)
}

type SystemGrant struct {
	ID     string `json:"id"`
	UserID string `json:"user_id"`
	Role   string `json:"role"`
	// GrantedBy is the user_id of the admin who made the grant, or
	// AuditActorOperator when it came from the operator command, which runs
	// with database credentials and no signed-in identity. It is deliberately
	// the same string the matching audit event carries in ActorID: one act
	// should not have two names across two tables.
	GrantedBy string    `json:"granted_by"`
	GrantedAt time.Time `json:"granted_at"`
	// RevokedAt is nil while the grant is active. Revoking sets it rather than
	// deleting the row: who held authority and when is the question an
	// investigation asks, and a deleted row cannot answer it.
	RevokedAt *time.Time `json:"revoked_at,omitempty"`
}

type SystemGrantStore interface {
	// ActiveSystemRoles returns the roles userID currently holds, empty for
	// almost every caller. It is on the path of every authenticated admin
	// request, so it must stay a single indexed read.
	ActiveSystemRoles(ctx context.Context, userID string) ([]string, error)
	// ListSystemGrants returns grants newest first. includeRevoked adds the
	// retired ones, which is how the trail of who held authority is read.
	ListSystemGrants(ctx context.Context, includeRevoked bool) ([]SystemGrant, error)
	// GrantSystemRole grants role to userID. It returns ErrSystemGrantExists
	// when an active grant is already there, so a caller can report "already
	// an admin" rather than silently creating a second row.
	GrantSystemRole(ctx context.Context, userID, role, grantedBy string, now time.Time) (*SystemGrant, error)
	// RevokeSystemRole revokes the active grant and reports whether one was
	// found. Revoking an absent grant is not an error: the end state is what
	// was asked for.
	RevokeSystemRole(ctx context.Context, userID, role string, now time.Time) (bool, error)
	// CountActiveSystemGrants counts live grants for role. It is what the API
	// checks before revoking the last one — see
	// docs/design/system-administration.md section 6.
	CountActiveSystemGrants(ctx context.Context, role string) (int, error)
}

type Task struct {
	ID                    string     `json:"id"`
	ConversationID        string     `json:"conversation_id"`
	TeamID                string     `json:"team_id,omitempty"`
	IssueID               *string    `json:"issue_id,omitempty"`
	Status                string     `json:"status"`
	Input                 string     `json:"input"`
	Title                 string     `json:"title,omitempty"`
	TitlePromptTokens     int        `json:"title_prompt_tokens,omitempty"`
	TitleCompletionTokens int        `json:"title_completion_tokens,omitempty"`
	Output                *string    `json:"output,omitempty"`
	CreatedBy             string     `json:"created_by"`
	CreatedAt             time.Time  `json:"created_at"`
	StartedAt             *time.Time `json:"started_at,omitempty"`
	EndedAt               *time.Time `json:"ended_at,omitempty"`
	ErrorMessage          *string    `json:"error_message,omitempty"`
	SessionID             *string    `json:"session_id,omitempty"`
	LastRunID             *string    `json:"last_run_id,omitempty"`
	AgentID               *string    `json:"agent_id,omitempty"`
}

type TaskResultDelivery struct {
	TaskRunID      string
	ConversationID string
	Status         string
	// Attempts counts claims, not successes. It is incremented when a delivery
	// is claimed rather than when one fails, so an attempt that dies mid-flight
	// still counts against the cap.
	Attempts  int
	LastError *string
	// NextAttemptAt is both the backoff and the lease: claiming pushes it out,
	// so a second sweeper does not pick up a delivery already in flight.
	NextAttemptAt time.Time
	CreatedAt     time.Time
}

type TaskResultDeliveryStore interface {
	// EnqueueTaskResultDelivery records that a run's outcome is owed to a
	// conversation. It is idempotent per run: a run reported twice — by its
	// worker and then by the reaper that gave up on it — owes one report.
	EnqueueTaskResultDelivery(ctx context.Context, taskRunID, conversationID string, now time.Time) error
	// ListDueTaskResultDeliveries returns pending reports whose next attempt is
	// due, oldest first.
	ListDueTaskResultDeliveries(ctx context.Context, now time.Time, limit int) ([]TaskResultDelivery, error)
	// ClaimTaskResultDelivery takes one pending delivery that is due, counting
	// the attempt and pushing its next one to nextAttemptAt. It returns nil
	// when the delivery is not pending, not due, or was claimed by someone
	// else — which is what keeps one run from being reported twice.
	ClaimTaskResultDelivery(ctx context.Context, taskRunID string, now, nextAttemptAt time.Time) (*TaskResultDelivery, error)
	// FinishTaskResultDelivery closes a delivery as DELIVERED or ABANDONED.
	FinishTaskResultDelivery(ctx context.Context, taskRunID, status string, lastError *string) error
	// RecordTaskResultDeliveryFailure keeps a delivery pending, records why the
	// last attempt did not succeed, and brings its next attempt forward. The
	// claim pushed that time out far enough to protect a turn still running;
	// an attempt that has already failed no longer needs protecting.
	RecordTaskResultDeliveryFailure(ctx context.Context, taskRunID, lastError string, nextAttemptAt time.Time) error
}

type TaskRun struct {
	ID               string     `json:"id"`
	TaskID           string     `json:"task_id"`
	Input            string     `json:"input"`
	CreatedBy        string     `json:"created_by,omitempty"`
	CreatedByType    string     `json:"created_by_type,omitempty"`
	TriggerSource    string     `json:"trigger_source,omitempty"`
	Status           string     `json:"status"`
	Output           *string    `json:"output,omitempty"`
	ErrorMessage     *string    `json:"error_message,omitempty"`
	StartedAt        *time.Time `json:"started_at,omitempty"`
	EndedAt          *time.Time `json:"ended_at,omitempty"`
	SessionID        *string    `json:"session_id,omitempty"`
	WorkerType       string     `json:"worker_type,omitempty"`
	K8sJobName       *string    `json:"k8s_job_name,omitempty"`
	K8sJobCreatedAt  *time.Time `json:"k8s_job_created_at,omitempty"`
	PromptTokens     *int       `json:"prompt_tokens,omitempty"`
	CompletionTokens *int       `json:"completion_tokens,omitempty"`
	// TracePath locates this run's durable trace inside run-global storage,
	// e.g. "traces/<session>/rt_….jsonl". Nil when no trace was written — the
	// run failed before an agent started, or tracing was disabled.
	TracePath *string `json:"trace_path,omitempty"`
	// CancelRequestedAt is when someone asked this run to stop. A cancel is
	// recorded rather than applied because the only thing that can stop a
	// started run is its own worker: the server states the intent, the worker
	// honors it and reports CANCELED. Nil means nobody has asked.
	CancelRequestedAt *time.Time `json:"cancel_requested_at,omitempty"`
	// CancelRequestedBy is the user who asked. A team's runs can be stopped by
	// anyone on the team, so "why did this stop" needs a name to answer.
	CancelRequestedBy *string `json:"cancel_requested_by,omitempty"`
	// RetryOfTaskRunID names the run this one repeats. Nil for every run that
	// carries its own instructions. The lineage is one level deep by record but
	// unbounded by use: retrying a retry points at the run it repeated, not at
	// the first of the chain.
	RetryOfTaskRunID *string `json:"retry_of_task_run_id,omitempty"`
	// AgentRevision numbers the agent definition this run was actually given.
	//
	// The definition is resolved when a worker asks for its run, not when the
	// task was created, so an edit takes effect on the next run. That is what
	// someone editing the field expects and it is also why this is recorded: a
	// run's instructions are otherwise whatever the agent says today, and no
	// record says which text produced this outcome. Nil for a run with no agent
	// and for runs that predate the column.
	AgentRevision *int `json:"agent_revision,omitempty"`
	// PluginPins are the releases this run was given, resolved when its worker
	// claimed it and fixed from that moment.
	//
	// Recorded for the reason AgentRevision is: afterwards nothing else can say
	// which versions this run actually had. The trace says so too, but a trace
	// is fail-open and lives in run-global storage, while this is the queryable
	// fact and what a retry reads. Nil for a run that resolved no plugins.
	PluginPins []PluginPin `json:"plugin_pins,omitempty"`
	// SourceMessageID names the conversation message this run was asked for in.
	//
	// Input is what Tier 1 decided to send a worker; this is what the person
	// actually said. They are not the same text and the difference is the point:
	// without it, nobody can tell a constraint the model dropped from one the
	// user never gave. Nil for a run with no message behind it — a workflow
	// step, an issue agent run, a retry, or a task created straight from the API.
	SourceMessageID *string   `json:"source_message_id,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
}

type TaskRunArtifact struct {
	TaskRunID    string `json:"task_run_id"`
	RelativePath string `json:"relative_path"`
}

type TaskRunStore interface {
	// CreateTaskRun creates a new run (PENDING). Returns ErrRunInProgress if the task has any run in PENDING/SCHEDULED/RUNNING.
	CreateTaskRun(ctx context.Context, in CreateTaskRunInput) (*TaskRun, error)
	// CountTaskRunsByStatus returns how many runs are in each status. It is
	// the one number that answers "is work flowing through this deployment",
	// and it carries no team, input, or output — only counts.
	CountTaskRunsByStatus(ctx context.Context) (map[string]int, error)
	// GetNextPendingTaskRun returns the oldest run with status PENDING (by created_at), or (nil, nil) if none.
	GetNextPendingTaskRun(ctx context.Context) (*TaskRun, error)
	GetTaskRun(ctx context.Context, taskRunID string) (*TaskRun, error)
	// GetTaskRunWithTask returns the run and its task, or (nil, nil, nil) if run not found.
	GetTaskRunWithTask(ctx context.Context, taskRunID string) (*TaskRun, *Task, error)
	// ListTaskRunIDsByTasks returns each task's run IDs, newest first, keyed by
	// task ID. Tasks with no runs are absent from the map.
	//
	// It exists because a task's last run is not its only run: a retried task
	// has earlier ones, and what those produced did not stop existing.
	ListTaskRunIDsByTasks(ctx context.Context, taskIDs []string) (map[string][]string, error)
	// GetActiveTaskRunByTask returns the task's run in PENDING, SCHEDULED, or
	// RUNNING, or (nil, nil) when the task has none. A task holds at most one.
	GetActiveTaskRunByTask(ctx context.Context, taskID string) (*TaskRun, error)
	// RequestTaskRunCancel records who asked a run to stop, and when, on a run
	// that has not reached a terminal status. Returns false when the run is
	// already terminal or already carries a request, so a second cancel
	// neither resets the clock the backstop measures nor overwrites the name
	// of whoever asked first.
	RequestTaskRunCancel(ctx context.Context, taskRunID, requestedBy string, requestedAt time.Time) (bool, error)
	// ClaimTaskRun atomically updates a run when current status matches ExpectedStatus.
	ClaimTaskRun(ctx context.Context, in ClaimTaskRunInput) (bool, error)
	// UpdateRun updates a run's status and optional fields.
	UpdateRun(ctx context.Context, in UpdateTaskRunInput) error
	UpdateTaskRunWorkerInfo(ctx context.Context, taskRunID, workerType string, k8sJobName *string, k8sJobCreatedAt *time.Time) error
	// RecordTaskRunAgentRevision stores which agent definition a run was given.
	// The first write wins: a run executes under the instructions it was handed
	// at dispatch, and a later edit does not retroactively change what ran.
	RecordTaskRunAgentRevision(ctx context.Context, taskRunID string, revision int) error
	// RecordTaskRunPluginPins stores the releases a run was given. Like the
	// agent revision, the first write wins: a worker polls its run, and a
	// team's activation edited mid-run must not rewrite what actually ran.
	RecordTaskRunPluginPins(ctx context.Context, taskRunID string, pins []PluginPin) error
	// OnRunComplete creates task_run_artifact rows (one per relativePath) and updates task denormalized fields. Use for SUCCEEDED runs.
	OnRunComplete(ctx context.Context, taskRunID string, relativePaths []string) error
	// SyncTaskFromRun updates task denormalized fields and last_run_id from the run (no output). Use for FAILED runs.
	SyncTaskFromRun(ctx context.Context, taskRunID string) error
}

type TaskRunTerminalInfo struct {
	TaskRunID      string
	TaskID         string
	ConversationID string
	// TeamID is the team that owns the task. Empty on a task created before
	// tasks carried one, which is why UserID is still here to fall back to.
	TeamID       string
	UserID       string
	Status       string
	Output       *string
	ErrorMessage *string
}

type TaskStore interface {
	// ListTasksByConversation returns tasks in the conversation. order is "asc" (oldest first) or "desc" (latest first); default "desc".
	ListTasksByConversation(ctx context.Context, conversationID string, order string) ([]Task, error)
	// ListTasksByConversationPaginated returns tasks with optional executed_only filter, ordered by created_at DESC. total is total matching count.
	ListTasksByConversationPaginated(ctx context.Context, conversationID string, executedOnly bool, limit, offset int) ([]Task, int, error)
	ListTasksByIssue(ctx context.Context, issueID string, limit, offset int) ([]Task, int, error)
	GetTask(ctx context.Context, taskID string) (*Task, error)
	GetTaskBySessionID(ctx context.Context, sessionID string) (*Task, error)
	// CreateTask creates a new task and its first TaskRun (input, title, PENDING). Returns the task with last_run_id set.
	CreateTask(ctx context.Context, in *CreateTaskInput) (*Task, error)
	UpdateTask(ctx context.Context, in UpdateTaskInput) error
	ClaimTask(ctx context.Context, in ClaimTaskInput) (updated bool, err error)
}

type Team struct {
	ID                string  `json:"id"`
	Name              string  `json:"name"`
	PersonalForUserID *string `json:"personal_for_user_id,omitempty"`
	QuotaTier         string  `json:"quota_tier,omitempty"`
	// PluginCuration is who fills this team's plugin activation list; empty
	// reads as PluginCurationOpen. See plugin_activation.go.
	PluginCuration PluginCuration `json:"plugin_curation,omitempty"`
	CreatedBy      string         `json:"created_by"`
	CreatedAt      time.Time      `json:"created_at"`
	UpdatedAt      time.Time      `json:"updated_at"`
}

type TeamMember struct {
	TeamID    string    `json:"team_id"`
	UserID    string    `json:"user_id"`
	Role      string    `json:"role"`
	CreatedAt time.Time `json:"created_at"`
}

type TeamStore interface {
	// GetTeam returns the team by team_id, or (nil, nil) when not found.
	GetTeam(ctx context.Context, teamID string) (*Team, error)
	// GetPersonalTeamByUser returns the default personal team for the user, or (nil, nil) when not found.
	GetPersonalTeamByUser(ctx context.Context, userID string) (*Team, error)
	// ListTeamsByUser returns all teams the user belongs to, ordered by created_at ASC.
	ListTeamsByUser(ctx context.Context, userID string) ([]Team, error)
	// CreateTeam creates a new team and owner membership.
	CreateTeam(ctx context.Context, name, createdBy, quotaTier string) (*Team, error)
	// AddTeamMember adds or updates a team membership.
	AddTeamMember(ctx context.Context, teamID, userID, role string) (*TeamMember, error)
	// RemoveTeamMember removes one membership from a team.
	RemoveTeamMember(ctx context.Context, teamID, userID string) error
	// ListTeamMembers returns members of the team ordered by created_at ASC.
	ListTeamMembers(ctx context.Context, teamID string) ([]TeamMember, error)
	// ListAllTeams returns every team newest first, with the total count. A
	// non-empty query filters on name as a substring.
	//
	// It is the one method here that ignores membership, so only
	// deployment-scoped callers may reach it. It returns teams, never their
	// contents: an administrator learns that a team exists and how large it is,
	// not what is in it.
	ListAllTeams(ctx context.Context, query string, limit, offset int) ([]Team, int, error)
	// CountTeamMembers returns member counts for the given teams, keyed by
	// team id. It exists so listing teams is two queries rather than one per
	// row.
	CountTeamMembers(ctx context.Context, teamIDs []string) (map[string]int, error)
	// SetTeamPluginCuration records who fills the team's plugin activation
	// list, or returns ErrNotFound. The value is validated above this layer.
	SetTeamPluginCuration(ctx context.Context, teamID string, mode PluginCuration) error
}

type UpdateAgentInput struct {
	AgentID string
	TeamID  string
	// UpdatedBy is taken because a team agent is edited by whoever holds the
	// permission, not only by its owner, and a revision that cannot name its
	// author is not much of a record.
	UpdatedBy string
	Def       AgentDefinition
}

type UpdateIssueInput struct {
	Title         *string
	Description   *string
	Status        *string
	AssigneeKind  *string
	AssigneeID    *string
	ParentIssueID *string
}

type UpdatePluginInput struct {
	DisplayName string
	Description string
}

type UpdateTaskInput struct {
	TaskID       string
	Status       string
	StartedAt    *time.Time
	EndedAt      *time.Time
	Output       *string
	ErrorMessage *string
	SessionID    *string
}

type UpdateTaskRunInput struct {
	TaskRunID        string
	Status           RunStatus
	StartedAt        *time.Time
	EndedAt          *time.Time
	Output           *string
	ErrorMessage     *string
	SessionID        *string
	PromptTokens     *int
	CompletionTokens *int
	TracePath        *string
}

type UpdateWorkflowInput struct {
	Name        *string
	Description *string
	Definition  *string
	Status      *string
	// UpdatedBy is recorded as the author of the revision this update appends.
	UpdatedBy string
}

type UpdateWorkflowRunInput struct {
	Status       string
	StartedAt    *time.Time
	EndedAt      *time.Time
	ErrorMessage *string
}

type UpdateWorkflowStepRunInput struct {
	Status        *string
	TaskID        *string
	TaskRunID     *string
	OutputSummary *string
	ErrorMessage  *string
	StartedAt     *time.Time
	EndedAt       *time.Time
}

type UsageInWindowReader interface {
	// TeamUsageInWindow returns run count and total tokens for the team in [sinceUnix, untilUnix].
	TeamUsageInWindow(ctx context.Context, teamID string, since, until time.Time) (runCount, totalTokens int, err error)
}

type User struct {
	ID                string     `json:"id"`
	Email             string     `json:"email"`
	Name              string     `json:"name"`
	QuotaTier         string     `json:"quota_tier,omitempty"`
	LastLoginAt       *time.Time `json:"last_login_at,omitempty"`
	LastLoginPlatform *string    `json:"last_login_platform,omitempty"`
	CreatedAt         time.Time  `json:"created_at"`
	// HasPassword reports whether this account can sign in with a password. The
	// hash itself never travels on this struct — see PasswordStore — so that no
	// handler can serialize it into a response by accident.
	HasPassword bool `json:"has_password"`
	// DisabledAt is nil for an ordinary account. Non-nil means every credential
	// this account holds is refused: password, login code, refresh token, the
	// access token it already has, and its webhook keys. Disabling is not
	// deletion — nothing is removed, and enabling reverses the state and
	// nothing else. See docs/design/system-administration.md section 8.
	DisabledAt *time.Time `json:"disabled_at,omitempty"`
}

type UserStore interface {
	// UserByEmail matches the address without regard to case, and returns
	// (nil, nil) when nobody has it. Login resolves the account this way and
	// compares nothing afterwards, so a case-sensitive implementation would
	// refuse people whose address is stored in another case.
	UserByEmail(ctx context.Context, email string) (*User, error)
	// GetUser returns the user by user_id, or (nil, nil) when not found.
	GetUser(ctx context.Context, userID string) (*User, error)
	// CreateUser creates a user with the given email. defaultQuotaTier is applied when non-empty. Returns ErrEmailExists if the email is already registered.
	CreateUser(ctx context.Context, email string, defaultQuotaTier string) (*User, error)
	// UpdateLoginMeta records the last login timestamp and platform for the user.
	UpdateLoginMeta(ctx context.Context, userID string, loginAt time.Time, platform string) error
	// ListUsers returns accounts newest first with the total count. A non-empty
	// query filters on email as a substring.
	ListUsers(ctx context.Context, query string, limit, offset int) ([]User, int, error)
	// SetUserDisabled disables the account at the given time, or enables it
	// when disabledAt is nil. Returns ErrUserNotFound when there is no such
	// account.
	SetUserDisabled(ctx context.Context, userID string, disabledAt *time.Time) error
}

type UserWebhookKey struct {
	ID        string    `json:"id"`
	UserID    string    `json:"user_id"`
	KeyHash   string    `json:"-"` // SHA256 hex of plaintext key
	Name      string    `json:"name,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type UserWebhookKeyStore interface {
	// CreateKey creates a new webhook key for the user. Returns plaintext key (e.g. whsec_...) and key_id. Caller must store plaintext securely; it is not persisted.
	CreateKey(ctx context.Context, userID, name string) (plaintextKey, keyID string, err error)
	// GetUserIDByKey looks up the user_id for the given plaintext key. Returns empty string if not found.
	GetUserIDByKey(ctx context.Context, plaintextKey string) (userID string, err error)
	// ListKeys returns key metadata for the user (no plaintext).
	ListKeys(ctx context.Context, userID string) ([]WebhookKeyMeta, error)
	// RevokeKey deletes the key by keyID if it belongs to the user.
	RevokeKey(ctx context.Context, userID, keyID string) error
}

type WebhookKeyMeta struct {
	KeyID     string    `json:"key_id"`
	Name      string    `json:"name,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type Workflow struct {
	ID          string `json:"id"`
	TeamID      string `json:"team_id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Definition  string `json:"definition"`
	Status      string `json:"status"`
	// Revision numbers the workflow_revision row holding this content. It
	// starts at 1 and advances every time the name, description, definition,
	// or status changes.
	Revision  int       `json:"revision"`
	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type WorkflowDefinition struct {
	Steps []WorkflowDefinitionStep `json:"steps"`
}

type WorkflowDefinitionStep struct {
	StepID        string `json:"step_id"`
	Type          string `json:"type"`
	TargetAgentID string `json:"target_agent_id"`
	Prompt        string `json:"prompt"`
}

type WorkflowRevision struct {
	WorkflowID  string    `json:"workflow_id"`
	Revision    int       `json:"revision"`
	Name        string    `json:"name"`
	Description string    `json:"description"`
	Definition  string    `json:"definition"`
	Status      string    `json:"status"`
	CreatedBy   string    `json:"created_by"`
	CreatedAt   time.Time `json:"created_at"`
}

type WorkflowRun struct {
	ID         string `json:"id"`
	WorkflowID string `json:"workflow_id"`
	// WorkflowRevision is the workflow revision this run expanded. It is 0 for
	// runs started before workflows recorded revisions.
	WorkflowRevision int        `json:"workflow_revision,omitempty"`
	IssueID          *string    `json:"issue_id,omitempty"`
	ConversationID   string     `json:"conversation_id"`
	Status           string     `json:"status"`
	CreatedBy        string     `json:"created_by"`
	CreatedAt        time.Time  `json:"created_at"`
	StartedAt        *time.Time `json:"started_at,omitempty"`
	EndedAt          *time.Time `json:"ended_at,omitempty"`
	ErrorMessage     *string    `json:"error_message,omitempty"`
}

type WorkflowStepRun struct {
	ID            string  `json:"id"`
	WorkflowRunID string  `json:"workflow_run_id"`
	StepID        string  `json:"step_id"`
	StepIndex     int     `json:"step_index"`
	StepType      string  `json:"step_type"`
	TargetAgentID *string `json:"target_agent_id,omitempty"`
	// AgentName, AgentDescription, and AgentInstructions capture the target agent
	// definition as it was when the run started, so later edits to the agent cannot
	// change what a step in flight sends to the model.
	AgentName         string     `json:"agent_name,omitempty"`
	AgentDescription  string     `json:"agent_description,omitempty"`
	AgentInstructions string     `json:"agent_instructions,omitempty"`
	AgentRevision     int        `json:"agent_revision,omitempty"`
	Prompt            string     `json:"prompt"`
	Status            string     `json:"status"`
	TaskID            *string    `json:"task_id,omitempty"`
	TaskRunID         *string    `json:"task_run_id,omitempty"`
	OutputSummary     *string    `json:"output_summary,omitempty"`
	ErrorMessage      *string    `json:"error_message,omitempty"`
	CreatedAt         time.Time  `json:"created_at"`
	StartedAt         *time.Time `json:"started_at,omitempty"`
	EndedAt           *time.Time `json:"ended_at,omitempty"`
}

type WorkflowStore interface {
	ListWorkflowsByTeam(ctx context.Context, teamID string) ([]Workflow, error)
	CreateWorkflow(ctx context.Context, teamID, createdBy, name, description, definition string) (*Workflow, error)
	GetWorkflow(ctx context.Context, workflowID string) (*Workflow, error)
	UpdateWorkflow(ctx context.Context, workflowID, teamID string, in UpdateWorkflowInput) (*Workflow, error)
	CreateWorkflowRun(ctx context.Context, in CreateWorkflowRunInput) (*WorkflowRun, error)
	ListWorkflowRunsByWorkflow(ctx context.Context, workflowID string, limit, offset int) ([]WorkflowRun, int, error)
	ListWorkflowRunsByIssue(ctx context.Context, issueID string, limit, offset int) ([]WorkflowRun, int, error)
	GetWorkflowRun(ctx context.Context, workflowRunID string) (*WorkflowRun, error)
	ListWorkflowStepRuns(ctx context.Context, workflowRunID string) ([]WorkflowStepRun, error)
	CreateWorkflowStepRuns(ctx context.Context, workflowRunID string, steps []CreateWorkflowStepRunInput) ([]WorkflowStepRun, error)
	UpdateWorkflowRun(ctx context.Context, workflowRunID string, in UpdateWorkflowRunInput) (*WorkflowRun, error)
	UpdateWorkflowStepRun(ctx context.Context, stepRunID string, in UpdateWorkflowStepRunInput) (*WorkflowStepRun, error)
	GetWorkflowStepRunByTaskID(ctx context.Context, taskID string) (*WorkflowStepRun, error)
	GetWorkflowStepRunByTaskRunID(ctx context.Context, taskRunID string) (*WorkflowStepRun, error)
	// ListWorkflowRevisions returns a workflow's revisions, newest first, with
	// the total count.
	ListWorkflowRevisions(ctx context.Context, workflowID string, limit, offset int) ([]WorkflowRevision, int, error)
	// GetWorkflowRevision returns one revision, or nil when the workflow has no
	// such revision number.
	GetWorkflowRevision(ctx context.Context, workflowID string, revision int) (*WorkflowRevision, error)
}