runtime

type Ack struct {
	CommandID string `json:"command_id"`
	State     string `json:"state"`
	RunID     string `json:"run_id,omitempty"`
	Status    string `json:"status,omitempty"`
	Error     string `json:"error,omitempty"`
	// Reason is a finished ack's failure typed by the runtime (absent
	// from a runtime older than the field, and for any failure it does
	// not type): kind "scripted_miss", the source step, the key
	// components. CommandStatus.Reason prefers it to reading Error.
	Reason *AckReason `json:"reason,omitempty"`
}

type AckReason struct {
	Kind       string   `json:"kind"`
	Step       int      `json:"step"`
	Components []string `json:"components"`
}

type AgentDefaults struct {
	MaxSteps    int    `json:"max_steps"`
	Parallelism int    `json:"parallelism"`
	Thinking    string `json:"thinking"`
	// ThinkingBudget is the agent's default thinking budget in tokens
	// (absent: none): a budget alone sets the request's thinking.
	ThinkingBudget int64      `json:"thinking_budget,omitempty"`
	Temperature    *float64   `json:"temperature,omitempty"`
	TopP           *float64   `json:"top_p,omitempty"`
	MaxTokens      *int       `json:"max_tokens,omitempty"`
	Seed           *int64     `json:"seed,omitempty"`
	Stop           []string   `json:"stop,omitempty"`
	ToolChoice     ToolChoice `json:"tool_choice"`
}

type AgentLimits struct {
	MaxSteps    int `json:"max_steps"`
	Parallelism int `json:"parallelism"`
}

type AgentRegistration struct {
	Name     string `json:"name"`
	Manifest string `json:"manifest"`
	// ManifestHash is sha256 (lowercase hex) of Manifest's bytes as the
	// runtime registered them — the weft.manifest.hash its own runs of
	// the agent carry. A runtime older than the field sends none, and
	// Studio hashes Manifest itself (AgentView.ManifestHash).
	ManifestHash string            `json:"manifest_hash,omitempty"`
	Models       []string          `json:"models"`
	Resolver     bool              `json:"resolver"`
	Limits       AgentLimits       `json:"limits"`
	Defaults     AgentDefaults     `json:"defaults"`
	SideEffects  map[string]string `json:"side_effects"`
	Allow        []string          `json:"allow"`
}

type AgentView struct {
	Name string `json:"name"`
	// ManifestHash is the registered agent's weft.manifest.hash: what a
	// recorded run's manifest_hash is compared with to say whether the
	// run was recorded by this build of the agent (UX-C-06). "" when
	// the registration carried no manifest.
	ManifestHash string `json:"manifest_hash"`
	// ModelProvider is the agent's own model's provider as its manifest
	// names it ("" when it names none): "wefttest" says engine live
	// calls the app's test script, not a provider (UX-C-09).
	ModelProvider string   `json:"model_provider,omitempty"`
	Models        []string `json:"models"`
	Resolver      bool     `json:"resolver"`
	// Defaults are the agent's run defaults as its runtime registered
	// them; nil (absent on the wire) for a runtime older than the
	// option lab, which registers none — a client greys the new knobs
	// on that, as Studio refuses them (playground.go).
	Defaults *AgentDefaults `json:"defaults,omitempty"`
	Tools    []ToolView     `json:"tools"`
	// Instructions is the agent's registered system prompt, read from
	// its manifest: the experiment drawer pre-fills from the registered
	// config, never a guess from the trace (WEFT-PLAYGROUND §3).
	Instructions string `json:"instructions,omitempty"`
}

type ApprovalDecision struct {
	CommandID string `json:"command_id"`
	RunID     string `json:"run_id"`
	CallID    string `json:"call_id"`
	Decision  string `json:"decision"` // approve | deny | resolve
	Reason    string `json:"reason,omitempty"`
	Content   string `json:"content,omitempty"`
	// Actor names who decided (§6 rule 4's spirit); carried for the
	// record, the runtime logs it.
	Actor string `json:"actor,omitempty"`
	// PublicID is the public id the decided run is scoped to — the
	// server's bookkeeping, never on the wire. The approval's command
	// row carries it (a panel token polls its own decision) and so does
	// the resumed run its acks name. Empty takes the run's recorded
	// scope.
	PublicID string `json:"-"`
}

type Breakpoints struct {
	Tools []string `json:"tools"`
}

type Budget struct {
	MaxTokensPerExperiment int64 `json:"max_tokens_per_experiment"`
	MaxRunsPerExperiment   int64 `json:"max_runs_per_experiment"`
}

type CancelTarget struct {
	RunID     string `json:"run_id"`
	CommandID string `json:"command_id"`
	RuntimeID string `json:"runtime_id"`
}

type Command struct {
	CommandID       string           `json:"command_id"`
	Agent           string           `json:"agent"`
	Source          *SourceSpec      `json:"source"`
	Input           *string          `json:"input"`
	Overrides       Overrides        `json:"overrides"`
	TranscriptEdits []TranscriptEdit `json:"transcript_edits"`
	Engine          string           `json:"engine"`
	SideEffects     string           `json:"side_effects"`
	Thread          string           `json:"thread"`
	ExperimentID    string           `json:"experiment_id"`
	Actor           string           `json:"actor"`
	PublicID        string           `json:"public_id"`

	// Runtime is the runtime the command was enqueued to.
	Runtime string `json:"-"`
	// contains filtered or unexported fields
}

type CommandStatus struct {
	CommandID string `json:"command_id"`
	State     string `json:"state"`
	RunID     string `json:"run_id"`
	// Status is the finished run's own outcome, succeeded | failed, as
	// the runtime's finished ack named it; absent until the command is
	// finished.
	Status string `json:"status,omitempty"`
	// Error is why, when there is a why: a failed run's error text, a
	// rejection's reason, what made the command lost. Null otherwise.
	Error *string `json:"error"`
	// Reason is Error read: the scripted engine's miss with the source
	// step and the key components it names, and Studio's sentence for
	// both surfaces (ReasonOf). Absent for any other error.
	Reason  *Reason   `json:"reason,omitempty"`
	Created time.Time `json:"created"`
	Updated time.Time `json:"updated"`
}

type ManifestAgent struct {
	Name string `json:"name"`
	// ManifestHash is sha256 of the agent's own one-agent manifest —
	// the weft.manifest.hash its runs carry.
	ManifestHash string `json:"manifest_hash"`
	// Entry is the agent's object in its manifest's agents array.
	Entry json.RawMessage `json:"-"`
}

type ManifestSource struct {
	Service string `json:"service"`
	// ManifestHash is sha256 (lowercase hex) of the registration's
	// agents as one core.Manifest document — the bytes
	// weft.Manifest(agents...) writes for the same agents in the same
	// order, so a weft.json generated from them hashes the same.
	ManifestHash string `json:"manifest_hash"`
	// Live: a runtime holding a command stream now registered with
	// this manifest. False is remembered, never live.
	Live bool `json:"live"`
	// RegisteredAt is the latest registration with this manifest.
	RegisteredAt time.Time `json:"registered_at"`
	// RuntimeID is the runtime that registered it last.
	RuntimeID string          `json:"runtime_id"`
	Agents    []ManifestAgent `json:"agents"`
	// Version is the manifest documents' "weft" format version.
	Version int `json:"-"`
}

type Option func(*RuntimeServer)

type Overrides struct {
	Instructions string             `json:"instructions,omitempty"`
	ToolsEnabled []string           `json:"tools_enabled,omitempty"`
	Model        string             `json:"model,omitempty"`
	Thinking     string             `json:"thinking,omitempty"`
	Options      map[string]float64 `json:"options,omitempty"`
	Params       *Params            `json:"params,omitempty"`
	ToolChoice   *ToolChoice        `json:"tool_choice,omitempty"`
	ParkOn       []string           `json:"park_on,omitempty"`
	OnlyTools    []string           `json:"only_tools,omitempty"`
}

type Params struct {
	TopP      *float64 `json:"top_p,omitempty"`
	MaxTokens *int     `json:"max_tokens,omitempty"`
	Stop      []string `json:"stop,omitempty"`
	Seed      *int64   `json:"seed,omitempty"`
}

type Reason struct {
	Kind       string   `json:"kind"`
	Step       int      `json:"step"`
	Components []string `json:"components"`
	Message    string   `json:"message"`
}

type RegisterResponse struct {
	RuntimeID   string `json:"runtime_id"`
	CommandsURL string `json:"commands_url"`
}

type Registration struct {
	RuntimeID string `json:"runtime_id"`
	Host      string `json:"host"`
	Pid       int    `json:"pid"`
	// Cwd is the app's working directory ("" when the runtime could not
	// read it, or is older than the field): one of the inputs of its
	// stable id, and shown in GET /api/runtimes under db.path's rule.
	Cwd string `json:"cwd,omitempty"`
	// Instance tells two runtime links of one process apart (a random
	// value per link, kept across its reconnects): with host and pid it
	// is what makes a registration "the same process" — whose reconnect
	// keeps its id — rather than a second one colliding on it
	// (serveRegister). A client must send one to keep at-most-once
	// across its own restarts; one that does not is told apart by host
	// and pid alone (a restarted container reusing pid 1 would then read
	// as the old process), and Studio WARNs once.
	Instance string `json:"instance,omitempty"`
	// StudioURL is the Studio the runtime's link dialled, credentials
	// stripped ("" in-process, or a runtime older than the field): what
	// lets this Studio say where a runtime went (UX-D-01).
	StudioURL   string `json:"studio_url,omitempty"`
	Service     string `json:"service"`
	Env         string `json:"env"`
	WeftVersion string `json:"weft_version"`
	Budget      Budget `json:"budget"`
	Threads     bool   `json:"threads"`
	// Sessions says the runtime was installed with runtime.Sessions: it
	// resolves the app's own sessions by public id, so the debugger's
	// verbs on an app-owned turn of its service route to it as a
	// `session` frame (EnqueueSession) instead of being refused. A
	// runtime older than the option sends false.
	Sessions bool `json:"sessions"`
	// BreakpointsOwn says an agent the runtime exposes was built with
	// runtime.Breakpoints(): the debugger's breakpoints park tools on
	// the app's own runs of it (core.ParkSource, ADR 0030), not only on
	// the runs the runtime starts. A runtime older than the option
	// sends false.
	BreakpointsOwn bool `json:"breakpoints_own"`
	// Breakpoints is the debugger's tool set the runtime holds right
	// now (WEFT-DEVTOOLS §8.3). The set lives in the runtime's process,
	// so it outlives a Studio restart: a Studio that holds no set for
	// the runtime adopts this one (serveRegister).
	Breakpoints []string            `json:"breakpoints"`
	Agents      []AgentRegistration `json:"agents"`
	// HeartbeatMS is the cadence, in milliseconds, at which the runtime
	// re-posts a command's accepted ack while the command is in its
	// hands (waiting for a run slot, running) — its word that the
	// command is still alive. A runtime that heartbeats gets a finish
	// watch on every accepted command (serveAcks), so a lost response
	// to the accepted ack cannot leave the row accepted forever while
	// the stream stays open; one older than the heartbeat sends 0 and
	// gets the watch only when its stream ends, as before.
	HeartbeatMS int64 `json:"heartbeat_ms"`
}

type RunCommand struct {
	CommandStatus
	// Verb is decide, steer or cancel; CallID and Decision a decide's.
	Verb     string `json:"verb"`
	CallID   string `json:"call_id,omitempty"`
	Decision string `json:"decision,omitempty"`
	// PublicID is the command's scope (a panel token lists its own).
	PublicID string `json:"-"`
}

type RuntimeServer struct {
	// AckDeadline is how long a queued command may go unacked before
	// it is lost (§10.5: 30 s). A field so tests can tighten it.
	AckDeadline time.Duration
	// FinishDeadline is how long an accepted command may stay
	// unfinished with no word from its runtime before it is lost
	// (§10.5: 10 min): after its runtime's stream died, or — for a
	// runtime that heartbeats (Registration.HeartbeatMS) — since its
	// last accepted ack, stream open or not, the watch then being
	// max(FinishDeadline, three heartbeats) with the heartbeat taken at
	// most FinishDeadline. A field so tests can tighten it.
	FinishDeadline time.Duration
	// PingEvery is the SSE keep-alive cadence (15 s).
	PingEvery time.Duration
	// Retention is how long a terminal command (finished, rejected,
	// lost), a run's route and a disconnected runtime that still holds
	// a breakpoint set stay in memory (24 h). A disconnected runtime
	// with nothing pending goes after FinishDeadline: replicas and
	// services come and go, and each would otherwise leave an entry in
	// GET /api/runtimes forever (an app restarted in the same place
	// re-registers under its stable id and reclaims its entry). A field so tests can tighten
	// it.
	Retention time.Duration
	// WriteTimeout bounds one frame's write to the command stream
	// (30 s): a runtime that stopped reading without closing must not
	// hold the handler in Write forever. A field so tests can tighten
	// it.
	WriteTimeout time.Duration
	// contains filtered or unexported fields
}

type RuntimeView struct {
	ID   string `json:"id"`
	Host string `json:"host"`
	Pid  int    `json:"pid"`
	// Cwd is the registration's working directory — a filesystem path,
	// so Studio's route serves it under db.path's rule (absent to a
	// panel token).
	Cwd string `json:"cwd,omitempty"`
	// StudioURL is the Studio the runtime's link dialled (its
	// registration's; absent in-process or from a runtime older than
	// the field). An address of this machine's network, so Studio's
	// route serves it under cwd's rule.
	StudioURL string `json:"studio_url,omitempty"`
	// WeftVersion is the weft the runtime was built with, as it
	// registered ("" from a client that sends none): two links of one
	// process read the same (UX-E-56).
	WeftVersion    string    `json:"weft_version,omitempty"`
	Service        string    `json:"service"`
	Env            string    `json:"env"`
	ConnectedSince time.Time `json:"connected_since"`
	LastSeen       time.Time `json:"last_seen"`
	// Connected reports whether the runtime holds a live command stream
	// now. A runtime whose stream dropped stays listed (until its
	// commands resolve, pruneLocked) with Connected false; a reconnect
	// re-registers under the same id and reads true again.
	Connected bool `json:"connected"`
	// Restored marks a runtime listed from the command store after a
	// Studio restart that has not registered since: its stream is gone
	// with the old Studio (Connected false) until it reconnects. Absent
	// otherwise.
	Restored bool `json:"restored,omitempty"`
	// Sessions is the registration's: the runtime acts on the app's own
	// turns (runtime.Sessions) — approvals, steer and cancel on an
	// app-owned run of its service reach it.
	Sessions bool `json:"sessions"`
	// BreakpointsOwn is the registration's: the runtime's breakpoints
	// park tools on the app's own runs of an agent built with
	// runtime.Breakpoints() (plan F4.2).
	BreakpointsOwn bool        `json:"breakpoints_own"`
	Agents         []AgentView `json:"agents"`
	// Breakpoints is the debugger's stored tool set for this runtime
	// (WEFT-DEVTOOLS §8.3) — what PUT …/breakpoints last delivered, so a
	// reloaded UI shows the rule that is parking its runs. Empty, never
	// null.
	Breakpoints []string `json:"breakpoints"`
	// BreakpointsSetAt is when Studio last delivered the set (PUT
	// …/breakpoints, UX-A-33), kept in the command store (U30.2): a set
	// restored after a restart keeps it. Absent for a set adopted from a
	// registration, and for one an older Studio stored.
	BreakpointsSetAt *time.Time `json:"breakpoints_set_at,omitempty"`
	// BreakpointsSurface is the surface the set came through (U30.2,
	// UX-A-33's "set by <surface>"): the Studio page that sent it — the
	// PUT body's surface, "runtimes" from /runtimes — else "api" for a
	// PUT that named none. Kept and absent as BreakpointsSetAt is.
	BreakpointsSurface string `json:"breakpoints_surface,omitempty"`
	// BreakpointsBy says where a non-empty set came from (U20.1, "who
	// set them"): BreakpointsByStudio — PUT …/breakpoints through this
	// Studio (BreakpointsSetAt says when); BreakpointsByRuntime — the
	// runtime's own registration carried it (an earlier Studio set it,
	// the runtime kept it); BreakpointsByStore — restored from the
	// command store after a Studio restart. Absent for an empty set.
	BreakpointsBy string `json:"breakpoints_by,omitempty"`
}

type SessionCommand struct {
	CommandID string `json:"command_id"`
	Verb      string `json:"verb"` // decide | steer | cancel
	PublicID  string `json:"public_id"`
	SessionID string `json:"session_id"`
	RunID     string `json:"run_id"`
	CallID    string `json:"call_id,omitempty"`
	Decision  string `json:"decision,omitempty"`
	Reason    string `json:"reason,omitempty"`
	Content   string `json:"content,omitempty"`
	Message   string `json:"message,omitempty"`
	Actor     string `json:"actor,omitempty"`
}

type SourceSpec struct {
	RunID    string `json:"run_id"`
	FromStep int    `json:"from_step"`
}

type SteerMessage struct {
	RunID   string `json:"run_id"`
	Message string `json:"message"`
}

type ToolChoice struct {
	Mode string `json:"mode"`
	Name string `json:"name,omitempty"`
}

type ToolView struct {
	Name        string `json:"name"`
	SideEffects string `json:"side_effects"`
	Allow       bool   `json:"allow"`
	Approval    bool   `json:"approval,omitempty"`
}

type TranscriptEdit struct {
	Kind       string          `json:"kind,omitempty"`
	Step       int             `json:"step"`
	ToolResult string          `json:"tool_result,omitempty"`
	CallID     string          `json:"call_id,omitempty"`
	Content    string          `json:"content,omitempty"`
	Args       json.RawMessage `json:"args,omitempty"`
	Index      int             `json:"index,omitempty"`
}