agentd

type AgentzResponse struct {
	OK                 bool   `json:"ok"`
	State              string `json:"state"`
	EpisodeSeconds     int    `json:"episodeSeconds,omitempty"`
	SustainSeconds     int    `json:"sustainSeconds,omitempty"`
	ConsecutiveHealthy int    `json:"consecutiveHealthy,omitempty"`
	LastError          string `json:"lastError,omitempty"`
}

type CPUUsage struct {
	// UsageMicros is cumulative CPU microseconds consumed (cpu.stat usage_usec).
	// Monotonically increasing — callers compute delta between polls for rate.
	UsageMicros int64 `json:"usage_micros"`
	// LimitMicrosPerSec is the CPU quota in µs/s from cpu.max (quota/period×1e6).
	// 0 means no quota (unlimited).
	LimitMicrosPerSec int64 `json:"limit_micros_per_sec,omitempty"`
}

type ContextUsage struct {
	UsedTokens  int64 `json:"used_tokens"`
	TotalTokens int64 `json:"total_tokens"`
}

type DiskUsage struct {
	UsedBytes  int64 `json:"used_bytes"`
	TotalBytes int64 `json:"total_bytes"`
}

type FileUploadResponse struct {
	Path string `json:"path"`
	Name string `json:"name"`
	Size int64  `json:"size"`
}

type HealthzResponse struct {
	Healthy       bool   `json:"healthy"`
	Version       string `json:"version"`
	UptimeSeconds int    `json:"uptime_seconds"`
	// Delivery is the build's delivery capability marker
	// (DeliveryCapability; absent on pre-US-70.2 runtimes).
	Delivery string `json:"delivery,omitempty"`
	// CommitSHA is the git commit this agentd binary was built from
	// (pkg/version, -ldflags injected; buildinfo vcs fallback). Surfaced
	// so a deployed agentd can be traced to source without binary
	// forensics — a devel hash build reporting a clean release Version
	// (incident 2026-08-15) must be distinguishable from the real tag.
	// "unknown" means neither ldflags nor vcs buildinfo could supply it.
	CommitSHA string `json:"commit_sha,omitempty"`
	// BuildTime is the UTC build timestamp (pkg/version). Same purpose
	// as CommitSHA; "unknown" when not stamped via ldflags (unstamped
	// builds never emit an empty string, so the omitempty tags on both
	// fields are inert by design — kept for forward-compatibility if the
	// defaults ever change).
	BuildTime string `json:"build_time,omitempty"`
	// Warnings are boot-time degradation notices (e.g. the persisted
	// default model could not be resolved — ModelResolutionWarningPath).
	// Observability only: never affects Healthy, never gates liveness.
	// The controller relays them into the AgentHealthy condition message
	// so users see why their selected model is not in use.
	Warnings []string `json:"warnings,omitempty"`
	// SpawnEnv (US-70.1, design 0057) is the supervisor's
	// terminal-verified spawn-env state: the revision of the secrets
	// delta the agent process actually spawned with, plus a
	// machine-readable degrade reason when delivery is incomplete.
	// Nil when the reporter has no supervisor evidence yet
	// (single-container mode, or before the first status poll) — no
	// evidence is not a degrade. Observability only, like Warnings.
	SpawnEnv *SpawnEnvHealth `json:"spawnEnv,omitempty"`
	// PendingApply (#1342, L11) is the deferred-credential-apply state:
	// a restart-worthy credential change staged on the pod but its
	// applying restart is riding a maintenance window behind busy
	// sessions. Nil when nothing is pending (the credential applied, or
	// no restart-worthy change arrived). The controller mirrors it into
	// the Workspace CRD's CredentialsApplyPending condition.
	PendingApply *PendingApplyHealth `json:"pendingApply,omitempty"`
	// Relay (US-72.4, design 0058 §4.5) is the relay-only liveness
	// slice: cached monitor state over the batch's relay-fronted
	// providers. Nil when the monitor is not wired (tests); a non-nil
	// RelayHealth with Present=false is a flag-off pod. Observability
	// only — a relay degrade never flips Healthy (it must not cascade to
	// a liveness-probe kill; the §4.8 remedy is bounded re-arm).
	Relay *RelayHealth `json:"relay,omitempty"`
	// LegacyScrub (US-72.6, design 0058 §8) is the one-time legacy-key
	// migration scrub's outcome. Since the run-36135708380 fix the scrub
	// fires UNCONDITIONALLY at boot (the #1537 first-relay-Present hook
	// alone was starved by design 0061 M2's migration-mode fail-open
	// fallback, which can deliver a raw batch — no relay-fronted entries
	// — on any unconverged boot, exactly when the residue migration must
	// run), so the report is non-nil on EVERY posture once boot completes
	// (flag-off and raw-batch pods included; AlreadyClean on clean roots).
	// Nil only before the boot call lands (early boot) or in topologies
	// that never construct the tracker. Observability only.
	LegacyScrub *LegacyScrubHealth `json:"legacyScrub,omitempty"`
}

type LegacyScrubHealth struct {
	RanAt             int64  `json:"ranAt"`
	AuthKeysRemoved   int    `json:"authKeysRemoved"`
	ConfigKeysRemoved int    `json:"configKeysRemoved"`
	Error             string `json:"error,omitempty"`
}

type MemoryUsage struct {
	UsedBytes  int64 `json:"used_bytes"`
	TotalBytes int64 `json:"total_bytes"`
}

type PendingApplyHealth struct {
	Reason         string `json:"reason,omitempty"`
	WaitingSeconds int    `json:"waitingSeconds"`
	BusySessions   int    `json:"busySessions"`
}

type ReadyzResponse struct {
	Ready               bool     `json:"ready"`
	ProvidersConnected  []string `json:"providers_connected"`
	ProvidersConfigured int      `json:"providers_configured"`
	AgentVersion        string   `json:"agent_version"`
	AgentType           string   `json:"agent_type"`
	// RelayInjected is true when the writer holds relay state — i.e. the
	// relay config block has been applied (via pre-boot injection, a
	// successful injector run, or a successful #910 re-arm cycle
	// mid-pod-life; evaluated live per request, not latched at boot).
	// The opencode restart that LOADS the config may still be pending:
	// session-aware deferral holds it until sessions idle, and the
	// re-arm path skips its own kill entirely when another deferred
	// restart is outstanding. False before any apply, when skipped
	// (personal opencode key), or while every attempt keeps failing.
	// Known corner (pre-existing, documented): a terminal auth.json
	// write failure after a successful config apply leaves this true
	// with the opencode-relay auth entry missing. Included here (readyz)
	// rather than statusz: readyz is cache-based and lightweight (no
	// synchronous opencode calls), and the API server needs this flag
	// on every ListModels cache miss — using statusz (which has no
	// latency upper bound) would be unsafe.
	RelayInjected bool `json:"relay_injected"`
	// Relay (US-72.4): the relay-only liveness degrade codes
	// (relay_unreachable / token_expired / router reject reasons).
	// Observability only — NEVER gates Ready: a relay outage must not
	// drop the pod from Service endpoints (that would compound the
	// outage); the remedy is the bounded re-arm + conditions.
	Relay *RelayHealth `json:"relay,omitempty"`
}

type RelayHealth struct {
	// Present reports whether relay-fronted providers were observed in
	// the applied batch (the entry metadata the US-72.4 builder emits).
	// False on flag-off pods: nothing to watch, never a degrade.
	Present bool `json:"present"`
	// Reachable reports the last credential-level probe outcome (GET
	// {baseURL}/models with the scoped token — served from the router's
	// staged catalog, zero upstream).
	Reachable bool `json:"reachable"`
	// DegradedReason is the active degrade code ("" healthy):
	// relay_unreachable | token_expired — plus the router's
	// machine-readable reject reasons when a probe was rejected
	// (credential_stale, scope_violation, sanitization_refused,
	// quota_exceeded) — the CredentialRejected/CredentialStale feeds.
	DegradedReason string `json:"degradedReason,omitempty"`
	// RouterURL is the router origin the monitor probes (no path, no
	// token material).
	RouterURL string `json:"routerUrl,omitempty"`
	// TokenExpiresAt is the earliest RFC3339 expiry across the batch's
	// relay tokens ("" when unknown).
	TokenExpiresAt string `json:"tokenExpiresAt,omitempty"`
	// AppliedRevision is the staged relay revision of the applied batch
	// (the entry metadata's relayRevision) — the controller compares it
	// against the workspace's staged-revision annotation (the lineage
	// conjunct of the §4.2 terminator).
	AppliedRevision string `json:"appliedRevision,omitempty"`
	// LastProbeAt is the last probe's unix seconds (0 before the first).
	LastProbeAt int64 `json:"lastProbeAt,omitempty"`
}

type SessionInfo struct {
	ID          string         `json:"id"`
	Title       string         `json:"title,omitempty"`
	Status      string         `json:"status"` // "idle" | "busy"
	Tokens      *SessionTokens `json:"tokens,omitempty"`
	Model       string         `json:"model,omitempty"` // model ID, e.g. "claude-sonnet-4-20250514"
	ContextUsed int64          `json:"contextUsed"`
}

type SessionTokens struct {
	Input      int64 `json:"input"`
	Output     int64 `json:"output"`
	Reasoning  int64 `json:"reasoning"`
	CacheRead  int64 `json:"cache_read"`
	CacheWrite int64 `json:"cache_write"`
}

type SpawnEnvHealth struct {
	SpawnedRev string `json:"spawnedRev,omitempty"`
	Degraded   bool   `json:"degraded"`
	Reason     string `json:"reason,omitempty"`
	// FilesRev / FilesDegraded / FilesReason (R2b, #1165): the file-class
	// delivery slice — the terminal revision over the files the uid-1000
	// supervisor actually wrote, and its machine-readable degrade reason
	// ("" healthy).
	FilesRev      string `json:"filesRev,omitempty"`
	FilesDegraded bool   `json:"filesDegraded,omitempty"`
	FilesReason   string `json:"filesReason,omitempty"`
}

type StatuszResponse struct {
	Healthy             bool          `json:"healthy"`
	Ready               bool          `json:"ready"`
	Connected           []string      `json:"connected"`
	ProvidersConfigured int           `json:"providers_configured"`
	Sessions            []SessionInfo `json:"sessions"`
	SessionsActive      int           `json:"sessions_active"`
	SessionsError       int           `json:"sessions_error"`
	LastError           string        `json:"last_error"`
	AgentType           string        `json:"agent_type"`
	AgentVersion        string        `json:"agent_version"`
	UptimeSeconds       int           `json:"uptime_seconds"`
	Disk                *DiskUsage    `json:"disk,omitempty"`
	Memory              *MemoryUsage  `json:"memory,omitempty"`
	CPU                 *CPUUsage     `json:"cpu,omitempty"`
	// RelayFreeModels: 0 unknown, 1 ok, 2 degraded (terminal fetch
	// failure this attempt — free-tier routing degraded until a re-arm
	// cycle applies, bounded by the 5m→30m backoff; #901 G8, #910).
	RelayFreeModels int32 `json:"relay_free_models"`
	// InFlightDeliveries: the ledger's unresolved delivery count pod-wide
	// (ledgered + admitted + stalled — the flip gate's drain signal,
	// design 0055 M4; 0 when the authority is not mounted).
	InFlightDeliveries int64 `json:"ledger_in_flight"`
	// OldestBusySeconds: age of the longest-busy session, 0 when idle
	// (D6/#998: unattended-escalation detection input — a session busy
	// this long with sustained watchdog flat-suppressions is likely
	// hung-and-alive; the API escalates to the owner, never executes).
	OldestBusySeconds int            `json:"oldest_busy_seconds"`
	BusyAges          map[string]int `json:"busy_ages,omitempty"`
	Context           *ContextUsage  `json:"context,omitempty"`
	// MemoryPressure is true when memory usage exceeds the warning
	// threshold (85% of cgroup limit). Set by agentd's periodic memory
	// check (US-44.5). The controller reads this to set the
	// WorkspaceConditionMemoryPressure condition.
	MemoryPressure bool `json:"memory_pressure,omitempty"`
	// Warnings mirrors HealthzResponse.Warnings: boot-time degradation
	// notices (ModelResolutionWarningPath). The deep-status scrape feeds
	// the controller's AgentHealthy condition message, so the warning
	// must appear here too or it would be erased between scrapes.
	Warnings []string `json:"warnings,omitempty"`
	// SpawnedRev (US-70.1 / design 0057 I4): the env revision the agent
	// child ACTUALLY spawned with — terminal verification at the point
	// of consumption, relayed from the supervisor's control socket.
	SpawnedRev string `json:"spawned_rev,omitempty"`
	// Degraded (US-70.1 / design 0057 I10): active machine-readable
	// degrade reason ("" healthy). First value of the family:
	// spawn_env_unavailable — the child spawned platform-env-only from
	// the last-good cache because the pull missed its bound.
	Degraded string `json:"degraded,omitempty"`
	// Relay (US-72.4): the relay-only liveness slice (cached monitor
	// state; nil when not wired). Mirrors healthz's field on the deep
	// status endpoint so a relay degrade is visible between scrapes.
	Relay *RelayHealth `json:"relay,omitempty"`
}