serve

type APIError struct {
	Error APIErrorBody `json:"error"`
}

type APIErrorBody struct {
	Message string `json:"message" example:"streaming is not supported"`
	Type    string `json:"type" example:"invalid_request_error"`
	Code    string `json:"code,omitempty" example:"streaming_unsupported"`
}

type AnthropicClient interface {
	FetchModels() ([]ModelInfo, error)
}

type Cell struct {
	ID         string
	Title      string
	Host       string
	Port       int
	Type       string // "Desktop" or "RemoteApp"
	AppProgram string // RemoteApp program alias (e.g. "||xterm")
}

type CellEnumerator interface {
	ListCells() []Cell
}

type ChatChoice struct {
	// Index of this choice (always 0 — single-choice responses).
	Index int `json:"index" example:"0"`
	// The assistant's response message.
	Message ChatMessage `json:"message"`
	// Finish reason: "stop" on success, "error" if the agent exited non-zero.
	FinishReason string `json:"finish_reason" example:"stop"`
}

type ChatMessage struct {
	// Role of the message author: "system", "user", or "assistant".
	Role string `json:"role" example:"user"`
	// The message content (prompt text for user, response text for assistant).
	Content string `json:"content" example:"Explain the main function in this repo"`
}

type ChatRequest struct {
	// Model selects the agent. Use "claude", "anthropic", or "opencode" as a prefix.
	// Append a sub-model with a slash: "claude/claude-sonnet-4-5".
	Model string `json:"model" example:"claude"`
	// Messages is the conversation history. The last user message is used as the prompt.
	Messages []ChatMessage `json:"messages"`
	// ReasoningEffort, when set, controls Claude's thinking budget for this request.
	// Valid values: "low", "medium", "high". Other values are silently dropped.
	// Maps to the `claude --effort` CLI flag. Has no effect on the opencode agent.
	ReasoningEffort string `json:"reasoning_effort,omitempty" example:"high"`
	// Stream, when true, emits Server-Sent Events with token-level deltas.
	// Supported only for the claude agent (opencode falls back to buffered).
	Stream bool `json:"stream,omitempty" example:"false"`
	// StreamOptions configures streaming behavior. Honored only when Stream is true.
	StreamOptions *ChatStreamOptions `json:"stream_options,omitempty"`
}

type ChatResponse struct {
	// Unique completion ID (format: chatcmpl-<hex>).
	ID string `json:"id" example:"chatcmpl-a1b2c3d4e5f6"`
	// Object type (always "chat.completion").
	Object string `json:"object" example:"chat.completion"`
	// Unix timestamp of when the response was created.
	Created int64 `json:"created" example:"1714000000"`
	// The model that was requested.
	Model string `json:"model" example:"claude"`
	// Response choices (always a single element).
	Choices []ChatChoice `json:"choices"`
	// Token usage (stubbed, reserved for future use).
	Usage ChatUsage `json:"usage"`
}

type ChatStreamChoice struct {
	Index        int             `json:"index"`
	Delta        ChatStreamDelta `json:"delta"`
	FinishReason *string         `json:"finish_reason"`
}

type ChatStreamChunk struct {
	ID      string             `json:"id"`
	Object  string             `json:"object"` // always "chat.completion.chunk"
	Created int64              `json:"created"`
	Model   string             `json:"model"`
	Choices []ChatStreamChoice `json:"choices"`
	Usage   *ChatUsage         `json:"usage,omitempty"`
}

type ChatStreamDelta struct {
	Role    string `json:"role,omitempty"`
	Content string `json:"content,omitempty"`
}

type ChatStreamOptions struct {
	// IncludeUsage, when true, embeds the token-usage object in the
	// final SSE chunk. Off by default to match OpenAI's contract.
	IncludeUsage bool `json:"include_usage,omitempty" example:"true"`
}

type ChatUsage struct {
	PromptTokens     int `json:"prompt_tokens" example:"42"`
	CompletionTokens int `json:"completion_tokens" example:"7"`
	TotalTokens      int `json:"total_tokens" example:"49"`
}

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

type DockerAPIClient interface {
	ContainerList(ctx context.Context, options container.ListOptions) ([]container.Summary, error)
}

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

type ExecOpts struct {
	// Agent is the binary name ("claude" or "opencode").
	Agent string
	// Prompt is the assembled prompt string passed via -p / positional arg.
	Prompt string
	// Model is the optional sub-model (e.g. "sonnet" or "claude-sonnet-4-5"). Empty = agent default.
	Model string
	// Effort, when set, is passed as --effort to the claude CLI.
	// Valid values: "low", "medium", "high". Empty = CLI default.
	Effort string
	// SystemPrompt, when set, is passed as --append-system-prompt to claude.
	// Operator-level baseline (set on `cell serve` startup), composes with
	// any per-request `instructions` / `system` role from the OpenAI body —
	// it does NOT override them. Ignored for opencode (no equivalent flag).
	SystemPrompt string
}

type ExecResult struct {
	Stdout   string
	Stderr   string
	ExitCode int
	// Usage carries token-and-cost telemetry parsed from the agent's
	// machine-readable output (claude --output-format=json today).
	// Zero-valued when the agent doesn't emit usage data (opencode) or
	// when JSON parsing falls back to raw stdout.
	Usage Usage
}

type Executor interface {
	Run(opts ExecOpts) ExecResult
}

type Folder struct {
	Name string `xml:"Name,attr"`
}

type Folders struct {
	Folder []Folder `xml:"Folder"`
}

type HealthResponse struct {
	// Server status — "ok" when the server is running and ready to accept requests.
	Status string `json:"status" example:"ok"`
	// Composite version string matching `cell --version` output.
	// Format: `<version>-<build_date>-<commit>`.
	Version string `json:"version" example:"v0.1.0-2026-04-26-abc1234"`
	// Semantic version tag from the build (e.g. "v0.1.0").
	VersionTag string `json:"version_tag" example:"v0.1.0"`
	// Git commit hash this binary was built from.
	Commit string `json:"commit" example:"abc1234"`
	// Build date (UTC).
	BuildDate string `json:"build_date" example:"2026-04-26"`
}

type HostingTerminalServer struct {
	ResourceFile      ResourceFile      `xml:"ResourceFile"`
	TerminalServerRef TerminalServerRef `xml:"TerminalServerRef"`
}

type HostingTerminalServers struct {
	HTS []HostingTerminalServer `xml:"HostingTerminalServer"`
}

type IconElement struct {
	Dimensions string `xml:"Dimensions,attr,omitempty"`
	FileType   string `xml:"FileType,attr"`
	FileURL    string `xml:"FileURL,attr"`
}

type Icons struct {
	IconRaw *IconElement `xml:"IconRaw,omitempty"`
	Icon32  *IconElement `xml:"Icon32,omitempty"`
	Icon256 *IconElement `xml:"Icon256,omitempty"`
}

type Job struct {
	ID         string
	Status     string // "in_progress" | "completed" | "failed" | "cancelled"
	Result     *ResponsesObject
	Cancel     context.CancelFunc
	CreatedAt  time.Time
	FinishedAt time.Time
}

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

type LookPathFunc func(name string) (string, error)

type MockEnumerator struct{}

type ModelInfo struct {
	// Model identifier — use this value in the chat completions "model" field.
	ID string `json:"id" example:"anthropic/claude-sonnet-4-5-20250514"`
	// Object type (always "model").
	Object string `json:"object" example:"model"`
	// Unix timestamp when the model was discovered.
	Created int64 `json:"created" example:"1714000000"`
	// Owner of the model: "anthropic" for API-discovered models, "devcell" for local agents.
	OwnedBy string `json:"owned_by" example:"anthropic"`
}

type ModelsResponse struct {
	// Object type (always "list").
	Object string `json:"object" example:"list"`
	// Available models discovered from installed agents and the Anthropic API.
	Data []ModelInfo `json:"data"`
}

type Publisher struct {
	LastUpdated     string          `xml:"LastUpdated,attr"`
	Name            string          `xml:"Name,attr"`
	ID              string          `xml:"ID,attr"`
	Description     string          `xml:"Description,attr"`
	Resources       Resources       `xml:"Resources"`
	TerminalServers TerminalServers `xml:"TerminalServers"`
}

type RealAnthropicClient struct {
	CredentialsPath string // path to .credentials.json
	APIURL          string // override for testing; defaults to AnthropicAPIURL
}

type Resource struct {
	ID                     string                 `xml:"ID,attr"`
	Alias                  string                 `xml:"Alias,attr"`
	Title                  string                 `xml:"Title,attr"`
	LastUpdated            string                 `xml:"LastUpdated,attr"`
	Type                   string                 `xml:"Type,attr"`
	ShowByDefault          string                 `xml:"ShowByDefault,attr"`
	Icons                  Icons                  `xml:"Icons"`
	FileExtensions         string                 `xml:"FileExtensions"`
	Folders                Folders                `xml:"Folders"`
	HostingTerminalServers HostingTerminalServers `xml:"HostingTerminalServers"`
}

type ResourceCollection struct {
	XMLName           xml.Name  `xml:"http://schemas.microsoft.com/ts/2007/05/tswf ResourceCollection"`
	PubDate           string    `xml:"PubDate,attr"`
	SchemaVersion     string    `xml:"SchemaVersion,attr"`
	SupportsReconnect string    `xml:"SupportsReconnect,attr,omitempty"`
	Publisher         Publisher `xml:"Publisher"`
}

type ResourceFile struct {
	FileExtension string `xml:"FileExtension,attr"`
	URL           string `xml:"URL,attr"`
}

type Resources struct {
	Resource []Resource `xml:"Resource"`
}

type ResponsesError struct {
	// Short error code, e.g. "server_error".
	Code string `json:"code,omitempty" example:"server_error"`
	// Human-readable message — typically the agent's stderr.
	Message string `json:"message" example:"agent failed"`
}

type ResponsesIncompleteDetails struct {
	Reason string `json:"reason,omitempty"`
}

type ResponsesInputTokensDetails struct {
	CachedTokens int `json:"cached_tokens" example:"0"`
}

type ResponsesObject struct {
	// Unique response ID (format: resp_<hex>).
	ID string `json:"id" example:"resp_a1b2c3d4e5f6"`
	// Object type — always "response".
	Object string `json:"object" example:"response"`
	// Unix timestamp (seconds) when the response was created.
	CreatedAt int64 `json:"created_at" example:"1714000000"`
	// Status: "completed" on success, "failed" if the agent exited non-zero.
	Status string `json:"status" example:"completed"`
	// Model echo of the requested model string.
	Model string `json:"model" example:"anthropic/sonnet"`
	// Output items generated by the model.
	Output []ResponsesOutputItem `json:"output"`
	// Convenience field: concatenation of all output_text parts in Output.
	// Most clients (n8n, simple scripts) read this directly.
	OutputText string `json:"output_text" example:"Hello, world!"`
	// Token usage (stubbed at zero — reserved for future use).
	Usage ResponsesUsage `json:"usage"`
	// Error populated when Status == "failed", null otherwise.
	Error *ResponsesError `json:"error"`
	// IncompleteDetails is reserved — always null.
	IncompleteDetails *ResponsesIncompleteDetails `json:"incomplete_details"`
	// Echo of the input instructions, or null if not set.
	Instructions *string `json:"instructions"`
	// Echo of input metadata, or null.
	Metadata map[string]string `json:"metadata"`
	// ParallelToolCalls — echo of input or default true.
	ParallelToolCalls bool `json:"parallel_tool_calls" example:"true"`
	// PreviousResponseID — always null (stateless).
	PreviousResponseID *string `json:"previous_response_id"`
	// Reasoning config — echoes the input reasoning object (with normalized
	// effort if it was applied), or null if no reasoning was sent.
	Reasoning *ResponsesReasoningConfig `json:"reasoning"`
	// Store flag — echo of input or default true.
	Store bool `json:"store" example:"true"`
	// Sampling temperature — echo of input or default 1.0 (devcell ignores it).
	Temperature float64 `json:"temperature" example:"1.0"`
	// ToolChoice — always "auto".
	ToolChoice string `json:"tool_choice" example:"auto"`
	// Tools — always empty array (no tools bridged).
	Tools []any `json:"tools"`
	// Top-p — echo of input or default 1.0 (devcell ignores it).
	TopP float64 `json:"top_p" example:"1.0"`
	// Truncation — "disabled" by default.
	Truncation string `json:"truncation" example:"disabled"`
	// User — echo of input or empty.
	User string `json:"user,omitempty"`
}

type ResponsesOutputContentPart struct {
	// Always "output_text" for text responses.
	Type string `json:"type" example:"output_text"`
	// The actual text.
	Text string `json:"text" example:"Hello, world!"`
	// Annotations on the text (always empty — reserved for future use).
	Annotations []any `json:"annotations"`
}

type ResponsesOutputItem struct {
	// Item type — always "message".
	Type string `json:"type" example:"message"`
	// Unique item ID (format: msg_<hex>).
	ID string `json:"id" example:"msg_a1b2c3d4e5f6"`
	// Status of this item — "completed" on success.
	Status string `json:"status" example:"completed"`
	// Role of the message author — always "assistant".
	Role string `json:"role" example:"assistant"`
	// Content parts of the message.
	Content []ResponsesOutputContentPart `json:"content"`
}

type ResponsesOutputTokensDetails struct {
	ReasoningTokens int `json:"reasoning_tokens" example:"0"`
}

type ResponsesReasoningConfig struct {
	// Effort: "low", "medium", or "high". Other values are silently dropped.
	Effort string `json:"effort,omitempty" example:"high"`
	// Summary controls reasoning summary verbosity. Accepted, ignored.
	Summary string `json:"summary,omitempty"`
	// GenerateSummary is a deprecated alias of Summary. Accepted, ignored.
	GenerateSummary string `json:"generate_summary,omitempty"`
}

type ResponsesRequest struct {
	// Model selects the agent. Use "claude", "anthropic", or "opencode" as a prefix.
	// Append a sub-model with a slash: "anthropic/sonnet" or "anthropic/claude-sonnet-4-5".
	Model string `json:"model" example:"anthropic/sonnet"`

	// Input is either a string OR an array of input items.
	// String form: a single user message.
	// Array form: a multi-turn conversation; each item has role + content.
	Input json.RawMessage `json:"input" swaggertype:"string" example:"hello"`

	// Instructions is an optional system prompt prepended to the conversation.
	Instructions string `json:"instructions,omitempty" example:"be brief"`

	// Stream, if true, returns 400 — streaming is not supported.
	Stream bool `json:"stream,omitempty"`

	// Reasoning carries reasoning-model controls. Only `reasoning.effort`
	// (low|medium|high) is honored — it maps to `claude --effort`. Other
	// fields (summary, generate_summary) are accepted and ignored.
	Reasoning *ResponsesReasoningConfig `json:"reasoning,omitempty"`

	// Accepted, ignored — kept for client compatibility.
	PreviousResponseID string          `json:"previous_response_id,omitempty"`
	Tools              json.RawMessage `json:"tools,omitempty" swaggerignore:"true"`
	ToolChoice         json.RawMessage `json:"tool_choice,omitempty" swaggerignore:"true"`
	ResponseFormat     json.RawMessage `json:"response_format,omitempty" swaggerignore:"true"`
	Text               json.RawMessage `json:"text,omitempty" swaggerignore:"true"`
	Temperature        *float64        `json:"temperature,omitempty"`
	TopP               *float64        `json:"top_p,omitempty"`
	MaxOutputTokens    *int            `json:"max_output_tokens,omitempty"`
	Metadata           json.RawMessage `json:"metadata,omitempty" swaggerignore:"true"`
	Store              *bool           `json:"store,omitempty"`
	ParallelToolCalls  *bool           `json:"parallel_tool_calls,omitempty"`
	Truncation         string          `json:"truncation,omitempty"`
	User               string          `json:"user,omitempty"`
	Background         *bool           `json:"background,omitempty"`
	Include            []string        `json:"include,omitempty"`
}

type ResponsesUsage struct {
	InputTokens         int                           `json:"input_tokens" example:"42"`
	InputTokensDetails  *ResponsesInputTokensDetails  `json:"input_tokens_details,omitempty"`
	OutputTokens        int                           `json:"output_tokens" example:"7"`
	OutputTokensDetails *ResponsesOutputTokensDetails `json:"output_tokens_details,omitempty"`
	TotalTokens         int                           `json:"total_tokens" example:"49"`
}

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

type ShellExecutor struct{}

type StreamEvent struct {
	Kind StreamEventKind
	// MessageID populated on MessageStart (the upstream message id).
	MessageID string
	// Model populated on MessageStart.
	Model string
	// Delta populated on TextDelta — incremental text since the previous
	// delta, not cumulative.
	Delta string
	// StopReason populated on MessageStop — "end_turn" / "max_tokens" / …
	StopReason string
	// Final populated on Result — reuses claude_json.go's typed envelope
	// for the terminal usage + cost payload.
	Final *claudeJSONResult
	// Err populated on Error — terminal; the caller should stop reading.
	Err error
}

type StreamEventKind int

type TerminalServer struct {
	ID          string `xml:"ID,attr"`
	Name        string `xml:"Name,attr"`
	LastUpdated string `xml:"LastUpdated,attr"`
}

type TerminalServerRef struct {
	Ref string `xml:"Ref,attr"`
}

type TerminalServers struct {
	TS []TerminalServer `xml:"TerminalServer"`
}

type Usage struct {
	InputTokens              int
	OutputTokens             int
	CacheCreationInputTokens int
	CacheReadInputTokens     int
	// TotalCostUSD is what claude reports; opencode doesn't surface cost.
	TotalCostUSD float64
}

type WorkspaceOpt func(*workspaceCfg)