agentapp

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

type AppConfig struct {
	WorkspaceDir string
	EnableMCP    bool
	// ModelEntries overrides settings.yaml models for this AgentApp. It is how a
	// surface in managed mode supplies what the deployment offers, and how a
	// worker receives the server's resolved model without writing credentials to
	// a run directory that is later persisted as an artifact.
	ModelEntries []config.ModelEntry
	// DefaultModel names the entry in ModelEntries a new session starts with.
	// Read only when ModelEntries is set; otherwise settings.yaml says.
	DefaultModel string
	// ManagedServerURL says these models are served by that deployment rather
	// than called from this machine. Empty means direct: the models are the ones
	// in settings.yaml and each carries its own provider credential.
	//
	// It is a property of the app rather than of an entry because a list has one
	// source. A surface is in one mode or the other, and the mode decides where
	// every prompt goes. See docs/design/client-modes.md section 4.
	ManagedServerURL string
	// Policy sets the tool permission policy for all runs in this AgentApp.
	// Nil defaults to AllowAllPolicy for backward compatibility.
	Policy agent.ToolPolicy
	// SandboxSurface picks the per-surface default sandbox baseline (see
	// config.SandboxSurfaceCLI / SandboxSurfaceWorker). Empty means
	// SandboxSurfaceCLI.
	SandboxSurface config.SandboxSurface
	// ManagedToken supplies the BuildMax credential for models configured with
	// transport "buildmax". Leaving it nil means this surface offers no managed
	// inference, and such an entry fails with a clear error instead of falling
	// back to a direct provider call.
	ManagedToken ManagedTokenFunc
	// ManagedTaskRunID makes managed calls from this app run-scoped: they go to
	// the worker route, carrying a run token instead of a login, and the server
	// derives user and team from it. Empty means managed calls are team-scoped,
	// which is what CLI, TUI, and Desktop do.
	ManagedTaskRunID string
	// Surface labels managed calls for correlation, e.g. "cli" or "desktop".
	Surface string
	// AdditionalSystemPrompt is free text appended to the system prompt as its last stable
	// layer: the user-authored identity and constraints for this run. It holds the prompt text
	// itself, not the name of anything. It is additive and never replaces the runtime prompt,
	// because replacing that would strip the tool-usage conventions the agent depends on and
	// the failure would look like a bad model rather than a bad configuration.
	//
	// Whoever assembles the run resolves it — a CLI flag, a named definition file, or the
	// agent record a task run names — and the last writer wins. It is bounded because it
	// lives in the system prompt, which is re-sent in full on every call and never trimmed.
	AdditionalSystemPrompt string
	// ArtifactPublisher gives this surface the artifact capability. Nil means it
	// has none — a session running straight against a model provider, with no
	// BuildMax server — and no artifact tool is registered at all.
	ArtifactPublisher tools.ArtifactPublisher
	// EnableBackgroundJobs turns on local background jobs: Bash gains
	// run_in_background and the Job tools are registered. Only interactive
	// surfaces (TUI, Desktop) set it — print mode has no host process to own
	// a job, and eval and workers have no unattended lifecycle for one, per
	// docs/design/local-background-jobs.md.
	EnableBackgroundJobs bool
}

type BackgroundEvent struct {
	// Source is one of the llm.MessageSource* values.
	Source string
	JobID  string
	// Title is the short human label — the command or the delegation
	// description.
	Title string
	// Payload is the observed text: result summary, reply, or line.
	Payload string
}

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

type HookStatus struct {
	EventCounts map[string]int `json:"event_counts"`
	Types       []string       `json:"types"`
	TotalHooks  int            `json:"total_hooks"`
}

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

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

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

type MCPStatus struct {
	LoadError string
	Servers   []mcp.MCPServerStatus
}

type ManagedTokenFunc func(serverURL string) (string, error)

type ModelConfig struct {
	Name          string
	ProviderModel string
	BaseURL       string
	APIKey        string
	ContextWindow int // 0 = no windowing; from settings.yaml model entry
	CallTimeout   int // seconds; 0 = uses DefaultCallTimeoutSecs
	MaxTokens     int // 0 = the adapter's own default
	// Reasoning is the effort level (config.Reasoning*); off means none.
	Reasoning string
	// CacheControl is the resolved prompt-cache policy: which calls ask the
	// provider to cache the stable prefix, and for how long. Resolved here
	// rather than in the client so one place folds the deprecated
	// prompt_cache shorthand.
	CacheControl config.CacheControl
	// Pricing is what this model charges. Zero means the entry configured no
	// prices, and a run against it reports its cost as unavailable rather than
	// as zero — BuildMax does not know what any provider charges.
	Pricing cllm.Pricing
	// PricingErr is why an entry's prices could not be read, empty when they
	// could. Carried rather than returned because a malformed price must not
	// stop a model from answering: the run still works, it just cannot be
	// costed, and the surface says so instead of failing the turn.
	PricingErr string
	// Integration names a qualified OpenAI-compatible gateway; empty is the
	// normal case.
	Integration string
	// Vision says this model accepts image input.
	Vision bool
	// KeepAlive is how long a local runtime keeps the model loaded between
	// calls. Only a local provider has one to keep.
	KeepAlive string
	// Provider is the wire protocol this model speaks. Empty means
	// config.LLMProviderOpenAICompatible. In managed mode it is ignored: the
	// operator's catalog decides which protocol serves the call.
	//
	// There is no transport here. Where a prompt goes is a property of the app's
	// mode, not of one model — see AppConfig.ManagedServerURL.
	Provider string
}

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

type PluginSnapshot struct {
	Discovery config.PluginDiscovery

	// Findings gathers every problem, from the directory scan and from
	// resolving each kind of content. A collision names the plugins involved,
	// so the messages stay meaningful once they are mixed together.
	Findings []plugin.Finding

	// Shadowed lists plugin definitions a higher layer replaced, so a plugin is
	// not shown as fully active when part of it never loads.
	Shadowed []plugin.Shadowed
	// contains filtered or unexported fields
}

type PromptCapabilities struct {
	// Artifacts is true when this surface registered the artifact tool.
	Artifacts bool
}

type RunPromptOpts struct {
	// Stream receives content deltas. Nil runs the LLM in blocking mode.
	Stream cllm.StreamSink
	// Approval resolves tool calls the policy sends to "ask". Nil collapses ask
	// to deny, which is what a surface with nobody to ask should do.
	Approval agent.ApprovalHandler
	// EventSink receives runtime events. Nil disables the caller's leg only — the
	// durable trace records the run either way.
	EventSink func(agent.Event)
	// Pending carries messages the user submits while this run is working. They
	// are appended to the history at the next iteration boundary instead of
	// waiting for the run to finish. Nil disables mid-run injection, leaving the
	// surface to drain its own queue between runs.
	Pending agent.PendingInput
}

type RunResult struct {
	Reply                 string
	Duration              time.Duration
	ToolCalls             int
	PromptTokens          int
	CompletionTokens      int
	TotalPromptTokens     int
	TotalCompletionTokens int
	// Cache counts are the provider-reported cached parts of the prompt totals
	// beside them, not extra tokens. Zero means the provider reported none,
	// which is not the same fact as a cache miss.
	CacheReadTokens       int
	CacheWriteTokens      int
	TotalCacheReadTokens  int
	TotalCacheWriteTokens int
	// Cost is the session's estimated spend so far, nil when nothing in it
	// could be priced. It is the session total rather than this turn's,
	// because that is what the session file accumulates: a per-turn figure
	// would need rates that may have changed since the turn ran.
	Cost *cllm.Cost
	// CostIncomplete says part of the session could not be priced, so the
	// total above understates it.
	CostIncomplete bool
	ContextTokens  int
	ContextWindow  int
	SessionID      string
	Workspace      string
	ModelName      string
	// TraceID identifies the durable run trace written for this run, or "" when
	// tracing is disabled or failed to start. Points at
	// <DataDir>/traces/<session_id>/<trace_id>.jsonl.
	TraceID string
	// TracePath is that file's path on disk, or "" when no trace was written.
	// Callers that persist a reference to the trace use this instead of
	// rebuilding the layout from TraceID, so the stored path and the written
	// file cannot disagree.
	TracePath string
}

type RunStatus struct {
	ContextTokens         int `json:"context_tokens"`
	ContextWindow         int `json:"context_window"`
	PromptTokens          int `json:"prompt_tokens"`
	CompletionTokens      int `json:"completion_tokens"`
	TotalPromptTokens     int `json:"total_prompt_tokens"`
	TotalCompletionTokens int `json:"total_completion_tokens"`
	// Cache counts break the prompt counts beside them down; summing them with
	// the prompt total counts the same tokens twice.
	CacheReadTokens       int `json:"cache_read_tokens"`
	CacheWriteTokens      int `json:"cache_write_tokens"`
	TotalCacheReadTokens  int `json:"total_cache_read_tokens"`
	TotalCacheWriteTokens int `json:"total_cache_write_tokens"`
	// Cost is the session's estimated spend, absent when nothing could be
	// priced. CostIncomplete says the figure is missing part of the session.
	Cost           *cllm.Cost `json:"cost,omitempty"`
	CostIncomplete bool       `json:"cost_incomplete,omitempty"`
}

type SandboxStatus struct {
	Resolution   config.SandboxResolution
	Deps         sandbox.DepsReport
	Backend      string              // backend currently active ("bwrap", "seatbelt", "none")
	Enabled      bool                // SandboxView.Enabled() — false when backend unavailable
	Mode         string              // "auto_allow" | "regular" | "" when disabled
	ProxyAddress string              // in-process HTTP proxy address ("" when not running)
	ProxyAllows  uint64              // cumulative allow decisions since proxy start
	ProxyDenies  uint64              // cumulative deny decisions since proxy start
	Recent       []sandbox.Violation // latest entries from the violation store
}

type SessionContext struct {
	*session.Session
	// contains filtered or unexported fields
}

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

type SessionStats struct {
	ID        string    `json:"id"`
	Title     string    `json:"title,omitempty"`
	Workspace string    `json:"workspace,omitempty"`
	CreatedAt time.Time `json:"created_at"`

	// Usage and Cost are the session's own accumulated totals.
	Usage llm.Usage `json:"usage"`
	Cost  *llm.Cost `json:"cost,omitempty"`
	// CostIncomplete says part of the session could not be priced, so Cost
	// understates it rather than covering it.
	CostIncomplete bool `json:"cost_incomplete,omitempty"`

	// Conversation is the shape of the stored history.
	Conversation session.ConversationStats `json:"conversation"`
	// Runs is the fold over this session's traces. Runs.Runs == 0 means no
	// trace was found, which is not the same as a session that never ran.
	Runs trace.SessionSummary `json:"runs"`
}

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

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

type ToolEntry struct {
	Name        string
	Description string
	// Access is what the tool says the call does: "read-only" or "write".
	Access string
	// Action is what the call resolves to with no arguments and a human
	// present: "allow", "ask", or "deny". Argument-dependent tools can resolve
	// differently for a real call — Bash asks only for a risky command — so
	// this is the category answer, not a promise about every invocation.
	Action string
	// Source names where Action came from: "settings" or "derived".
	Source string
}

type TurnFinalizeResult struct {
	Title            string
	PromptTokens     int
	CompletionTokens int
	CacheReadTokens  int
	CacheWriteTokens int
}