omnigent

type APIError struct {
	// StatusCode is the HTTP status. It, not the message text, is what the
	// sentinels are matched on.
	StatusCode int

	// Code is the server's own error code — "not_found", "runner_unavailable",
	// and so on — from a {"error": {"code", "message"}} envelope. Empty when
	// the response used FastAPI's {"detail": ...} shape or was not JSON.
	Code string

	// Message is the human-readable message from either envelope. May be empty.
	Message string

	// Title is a short headline naming what went wrong, e.g. "Claude Code can't
	// run as root". The server sets it when it recognised the failure, so a
	// caller can show it instead of the raw Code. Empty when absent.
	Title string

	// Cause is a sentence or two explaining why the request failed. It is paired
	// with Title. Empty when absent.
	Cause string

	// Remediation is a concrete next step, sometimes a command to run. Empty
	// when the server has no single clear fix to name.
	Remediation string

	// Detail is the raw value of a {"detail": ...} envelope. For a 422 it is a
	// list; see [APIError.ValidationErrors]. Nil when absent.
	Detail json.RawMessage

	// Body is the response body, truncated to a bounded size. Retained because
	// an auth proxy or gateway ahead of the server may answer with something
	// that is not JSON at all, and that is exactly why [APIError.Error] does not
	// render it: what a proxy puts in a body is not this API's, and may be a
	// credential. Treat it as untrusted bytes to be looked at, not logged.
	Body []byte

	// ContentType is the response's Content-Type header, useful for telling a
	// server error apart from a proxy's HTML interstitial. Shorthand for
	// Header.Get("Content-Type").
	ContentType string

	// RequestID is the server's X-Request-Id, which its middleware stamps on
	// every response and logs alongside the failure. Quote it when reporting a
	// server-side problem: it is the only handle that ties this error to the
	// server's own record of it. Empty if the response never reached the
	// server's middleware — a proxy or gateway error, say.
	RequestID string

	// Header is the response's headers, less the ones that carry a credential:
	// see this type's doc. It is here for the correlation and rate-limit headers
	// a deployment may add beyond the two this type documents. Nil is possible; use
	// Header.Get, which tolerates it.
	Header http.Header
}

type AgentObject = api.AgentObject

type Block interface {
	// Context reports which agent produced this block, how deep that agent sits, and
	// which tool-loop iteration the block came from.
	//
	// A single-agent caller ignores it. One rendering a sub-agent tree routes on it,
	// which is why it is on the interface rather than on each variant.
	Context() BlockContext
	// contains filtered or unexported methods
}

type BlockContext struct {
	// Agent names the agent that produced the block, e.g. "coder.researcher". It is
	// the response's model, which the description defines as the agent that produced
	// it — so a root agent reports its own name rather than an empty one.
	//
	// Empty only before any response has been announced, which is where an
	// [ErrorBlock] or [RetryBlock] can arrive.
	Agent string

	// Depth is how deep that agent sits in the sub-agent tree, counted from the dots
	// in [BlockContext.Agent]: upstream derives it the same way.
	//
	// A convention rather than a declared field. The description does not say a dot
	// in an agent name means nesting, so a name that carries one for another reason
	// reports a depth it does not have. Route on Agent when that matters.
	Depth int

	// Iteration counts tool-loop passes within the turn. A loop that runs three
	// times produces blocks at iterations 0, 1 and 2.
	//
	// Named for the pass rather than the turn, because [Turn] is one prompt and
	// everything it produces — a different thing, and one word cannot be both.
	Iteration int

	// At is when the block was made, from a monotonic clock, so a renderer can
	// measure elapsed time without a wall-clock jump changing the answer.
	At time.Time
}

type BlockStream struct {
	// TextFlushThreshold is the minimum buffered characters before a [TextChunk]
	// is emitted on a word boundary. Zero means [defaultTextFlushThreshold].
	//
	// Raise it for a renderer that redraws expensively; set it to 1 to forward
	// every delta.
	TextFlushThreshold int
}

type BrowserActionRequestEvent api.BrowserActionRequestEvent

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

type ChatOptions struct {
	// Turn decides where a turn ends. Its zero value is the stricter rule; see
	// [TurnEndsOnIdleStatus].
	Turn TurnOptions

	// Tools are the tools this client will run when the agent calls them. Nil
	// means the client runs none, and a call the agent makes is answered with
	// [ErrToolNotRegistered] rather than left parked.
	Tools *ToolRegistry

	// MaxToolCalls caps how many tool calls one turn will run. Zero means the
	// default, [DefaultMaxToolCalls]; a negative value means no cap.
	//
	// The cap exists because the call id is the server's to choose, so nothing
	// else bounds how many times a turn asks this client to run privileged code.
	// Reaching it ends the turn: the server is parked on a call this package
	// declined, so its terminal never arrives.
	MaxToolCalls int

	// Hooks observe the turn. Optional.
	Hooks StreamHooks

	// Stream configures the underlying event subscription.
	Stream StreamOptions
}

type ChildSessionList = api.ChildSessionList

type ChildSessionSummary = api.ChildSessionSummary

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

type ClientTaskCancelEvent api.ClientTaskCancelEvent

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

type CompactionCompletedEvent api.CompactionCompletedEvent

type CompactionData = api.CompactionData

type CompactionFailedEvent api.CompactionFailedEvent

type CompactionInProgressEvent api.CompactionInProgressEvent

type ConversationDeleted = api.ConversationDeleted

type ConversationItem = api.ConversationItem

type ConversationRef = api.ConversationRef

type DeleteSessionOptions struct {
	// DeleteBranch also removes the server-created git worktree and its branch.
	// Ignored for sessions without one, and best-effort: a cleanup failure does
	// not fail the delete.
	DeleteBranch bool
}

type ElicitationAction string

type ElicitationCtx struct {
	SessionID     string
	ElicitationID string

	// Message is what the server is asking, e.g. a command awaiting approval.
	Message string

	// Phase and PolicyName are the server's own classification of the request,
	// empty when it sent none. A caller with a policy keys on these. Unlike
	// [ElicitationCtx.Extra] their type is enforced by the decoder, so a server
	// that sends the wrong one loses the whole event rather than the field.
	Phase      string
	PolicyName string

	// Extra carries the request's undeclared parameters, nil when it had none.
	//
	// The schema allows them and the server uses them. tool_name — the gated
	// tool's registered name, e.g. "Bash" — arrives here and nowhere else, and it
	// is the finest-grained thing the server attests about an approval, which
	// makes it what a policy allowlist keys on: a policy name covers every tool
	// that policy gates, so allowing one tool by policy name allows the rest.
	//
	// Read a value in two steps, because absent and present-but-not-a-string are
	// different answers and only one of them means the server said nothing:
	//
	//	raw, present := ctx.Extra["tool_name"]
	//	name, valid := raw.(string)
	//
	// A single assertion reports both as false and cannot tell them apart, which
	// is the whole reason this is a map rather than a named field.
	//
	// Treat either miss as unknown and fail closed. A declared field's type is
	// enforced by the decoder and a violation rejects the whole event; nothing
	// enforces a type here, so a policy that cannot see the tool it is gating
	// should decline rather than fall through to a broader rule. Present but not
	// a string is worth logging on its own: the server does not send that shape,
	// so something else did.
	//
	// A map rather than named fields because the set is the server's to change.
	// Naming one here would make the SDK's opinion about which extra matters
	// permanent, and would collapse those three answers into an empty string.
	Extra map[string]any

	// ContentPreview is a preview of what would run, empty when the server sent
	// none.
	ContentPreview string

	// Mode is how the server expects this to be answered: "form" for a schema the
	// caller fills in, "url" for an out-of-band flow at [ElicitationCtx.URL].
	// Empty when the server does not say.
	//
	// A decision made without it is a decision made blind, which is why upstream's
	// own client passes it. Note that a "form" answer needs values this package
	// cannot yet send: see [StreamHooks.OnElicitation].
	Mode string

	// URL is where a "url" mode flow happens, for example an OAuth authorize
	// endpoint. Empty in any other mode.
	//
	// Show it before approving. This package refuses an off-host redirect on the
	// unary path for the same reason a destination matters, and an approval that
	// hides the destination gives that up.
	URL string

	// RequestedSchema is the shape a "form" mode answer should take. Nil when the
	// server does not send one.
	RequestedSchema map[string]any

	// ResponseID is the response in flight when the server raised this, or empty
	// when none is. It is what correlates an approval with the work it gates.
	ResponseID string
}

type ElicitationRequestEvent api.ElicitationRequestEvent

type ElicitationRequestParams = api.ElicitationRequestParams

type ElicitationResolvedEvent api.ElicitationResolvedEvent

type ElicitationResult struct {
	// Action is the verdict. Required.
	Action ElicitationAction `json:"action"`

	// Content carries form values when Action is [ElicitationAccept] and the
	// request asked for a schema. Nil for a plain approve/reject, and for
	// decline and cancel.
	//
	// MCP restricts the values to JSON scalars and lists of strings, so a nested
	// object or a list of anything else is rejected. The Go type is wider than
	// the wire contract because map[string]any is what encoding/json gives a
	// caller building one; the server is the enforcement point.
	Content map[string]any `json:"content,omitempty"`
}

type Error interface {
	error

	// Status returns the HTTP status the server answered with.
	Status() int
}

type ErrorBlock struct {

	// Message is the server's free-form reason. Empty when the server sent
	// response.error without one, which is why Code is carried separately.
	Message string

	// Source is where the error came from, e.g. "llm".
	Source string

	// Code is the machine-readable classification, e.g. "llm_auth_failed". A
	// renderer falls back to it so a blank Message still shows the caller
	// something.
	Code string
	// contains filtered or unexported fields
}

type ErrorData = api.ErrorData

type ErrorDetail = api.ErrorDetail

type ErrorEvent api.ErrorEvent

type Event interface {
	// EventType returns the frame's wire discriminator, e.g. "session.status".
	//
	// Logging, metrics and routing want the type and nothing else. Without this
	// each of them needs a switch over every variant to reach a field they all
	// share.
	//
	// The value is the one the frame carried, not a constant per Go type, so a
	// frame decoded by this package reports what the server actually sent. On an
	// [UnknownEvent] it is the discriminator this build did not recognise.
	EventType() string
	// contains filtered or unexported methods
}

type EventAccepted struct {
	// Queued is true when the input became a conversation item, false for a
	// control input that queues nothing.
	Queued bool `json:"queued"`

	// ItemID is the queued item's identifier, present when Queued. It is the
	// same id that comes back on the stream as [SessionInputConsumedEvent],
	// which makes it the correlation key between a send and its echo.
	ItemID string `json:"item_id,omitempty"`

	// PendingID identifies a native-terminal message's optimistic placeholder,
	// which the consume event later clears. Usually empty.
	PendingID string `json:"pending_id,omitempty"`

	// Denied reports that the server handled this input synchronously by
	// refusing it, rather than queueing a turn for it. It is the difference
	// between the two reasons Queued can be false: a control input queues
	// nothing by design, while a denied one was rejected and says why in
	// [EventAccepted.Reason].
	Denied bool `json:"denied,omitempty"`

	// Reason is the server's explanation for a denial, e.g.
	// "Denied by policy". Empty unless Denied.
	//
	// Worth reading rather than discarding: without it a refused send is
	// indistinguishable from a control input, and a caller that treats every
	// unqueued send the same way reports "the server accepted this without
	// queueing it" when the server had already said exactly what was wrong.
	Reason string `json:"reason,omitempty"`
}

type FileBlock struct {
	FileID string

	// Filename is the name the server recorded, or nil when it recorded none.
	Filename *string
	// contains filtered or unexported fields
}

type FileOutputCtx struct {
	FileID   string
	Filename string
}

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

type FunctionCallData = api.FunctionCallData

type FunctionCallOutputData = api.FunctionCallOutputData

type GetSessionOptions struct {
	// IncludeItems, when false, skips the committed-items read and returns no
	// items. It is the most expensive part of building a snapshot, so set it
	// false when hydrating the transcript separately.
	//
	// Leaving it alone does not fetch the whole transcript. The server reads the
	// newest 100 items and returns them chronologically, and nothing on the
	// response separates a complete transcript from a truncated one, so a
	// session that keeps working past 100 items silently loses its oldest.
	// [Sessions.ListItems] is the paged read that reaches them.
	IncludeItems *bool

	// IncludeLiveness, when false, skips the runner and host liveness lookup.
	IncludeLiveness *bool

	// RefreshState asks the server to re-derive the session's state before
	// answering rather than serving what it has cached.
	RefreshState *bool
}

type InProgressEvent api.InProgressEvent

type IncompleteDetails = api.IncompleteDetails

type IncompleteEvent api.IncompleteEvent

type ListAgentsOptions struct {
	// Limit caps the page size. The server accepts 1 to 1000 and defaults to
	// 20; zero here sends nothing and takes that default.
	Limit int

	// After returns the agents following this cursor. Use a previous page's
	// [Page.LastID].
	After string

	// Before returns the agents preceding this cursor. Use a previous page's
	// [Page.FirstID].
	Before string

	// Order is the sort direction. Empty takes the server's default,
	// [SortDescending].
	Order SortOrder
}

type ListFilesOptions struct {
	// Limit caps one page. Zero leaves the server's default.
	Limit int

	// Order sets the direction. Empty leaves the server's default.
	Order SortOrder
}

type ListSessionsOptions struct {
	// Limit caps the page size. The server accepts 1 to 1000 and defaults to
	// 20; zero here sends nothing and takes that default.
	Limit int

	// After returns the sessions following this cursor. Use a previous page's
	// [Page.LastID].
	After string

	// Before returns the sessions preceding this cursor. Use a previous page's
	// [Page.FirstID].
	Before string

	// AgentID restricts the listing to one agent by id. This is the filter to
	// reach for when reconciling against sessions a program created earlier: it
	// is exact, where AgentName resolves through a mutable label.
	AgentID string

	// AgentName restricts the listing to one agent by name. An agent can be
	// renamed, so a program that stores a name rather than an id can start
	// matching a different agent, or none.
	AgentName string

	// Order is the sort direction. Empty takes the server's default,
	// [SortDescending].
	Order SortOrder

	// SortBy is the timestamp to order on. Empty takes the server's default,
	// [SessionSortByCreatedAt].
	SortBy SessionSortBy

	// SearchQuery restricts the listing to sessions matching a free-text
	// search. A match populates [SessionListItem.SearchSnippet].
	//
	// It travels as a query parameter, so it lands in the access log of the
	// server and of anything in front of it. Search for a title, not for
	// something that would be a problem to find written down.
	SearchQuery string

	// IncludeArchived also returns archived sessions, which are otherwise
	// omitted. [SessionListItem.Archived] tells them apart.
	IncludeArchived bool

	// Kind selects top-level, sub-agent, or all sessions. Empty takes the
	// server's default, [SessionKindDefault].
	Kind SessionKind

	// Project restricts the listing to one project by id.
	Project string

	// Pinned restricts the listing to pinned sessions.
	Pinned bool
}

type MCPServerStartup = api.MCPServerStartup

type MCPServerSummary = api.MCPServerSummary

type MessageData = api.MessageData

type ModelUsage = api.ModelUsage

type NativeModelOption = api.NativeModelOption

type NativeReasoningEffortOption = api.NativeReasoningEffortOption

type NativeToolBlock struct {

	// ToolType is the provider's own type, e.g. "web_search_call".
	ToolType string

	// Label is a short display name, e.g. "search".
	Label string

	// Data is the provider's payload, undecoded, because its shape is the
	// provider's and this package does not declare it.
	Data map[string]any
	// contains filtered or unexported fields
}

type NativeToolData = api.NativeToolData

type Option interface {
	// contains filtered or unexported methods
}

type OutputFileDoneEvent api.OutputFileDoneEvent

type OutputItemDoneEvent api.OutputItemDoneEvent

type OutputTextDeltaEvent api.OutputTextDeltaEvent

type Page[T any] struct {
	// Data is this page's items, in the requested order. Empty on the last page
	// of an exhausted listing, and empty rather than nil when the server sends
	// an empty array.
	Data []T `json:"data"`

	// FirstID is the id of Data's first item, the cursor for paging backwards.
	// Empty when Data is.
	FirstID string `json:"first_id,omitempty"`

	// LastID is the id of Data's last item, the cursor for paging forwards.
	// Empty when Data is.
	LastID string `json:"last_id,omitempty"`

	// HasMore reports whether more items exist beyond this page in the requested
	// direction — the direction is baked in, because the server applies the
	// cursor comparison and the ordering together.
	//
	// A false value is the only finished listing. A full page does not imply
	// another one: the server asks for one row more than the limit and reports
	// whether it got it, so a true value beside an empty Data is not something this
	// server produces.
	//
	// Do not treat that shape as an end anyway. It means the listing was cut short,
	// and a caller that breaks quietly on it cannot tell a truncated answer from a
	// complete one — while a caller that trusts this field alone re-reads the first
	// page for as long as a proxy or a future server keeps saying yes. [pageSeq]
	// yields [ErrListingUnbounded] instead, and so should a hand-rolled loop.
	HasMore bool `json:"has_more"`
}

type PaginatedList = api.PaginatedList

type PolicyDeniedEvent api.PolicyDeniedEvent

type PolicySummary = api.PolicySummary

type PresenceViewer = api.PresenceViewer

type QueryResult struct {
	// Text is the assistant's answer, joined across the turn's tool-loop passes.
	// Empty when the agent produced no text.
	Text string

	// Files are the artifacts the turn produced, in the order they arrived. Empty
	// when it produced none.
	//
	// Each carries the id and, when the server reported one, the name. The bytes
	// are fetched with [SessionFiles.Download]: an artifact can be any size, and a
	// fold that pulled every file's content would decide that for the caller.
	Files []FileBlock
}

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

type QueuedEvent api.QueuedEvent

type ReasoningBlock struct {
	ReasoningText string
	SummaryText   string
	// contains filtered or unexported fields
}

type ReasoningChunk struct {
	Text string
	// contains filtered or unexported fields
}

type ReasoningData = api.ReasoningData

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

type ReasoningStartCtx struct {
	ResponseID string
}

type ReasoningStartedEvent api.ReasoningStartedEvent

type ReasoningSummaryTextDeltaEvent api.ReasoningSummaryTextDeltaEvent

type ReasoningTextDeltaEvent api.ReasoningTextDeltaEvent

type ResolveOnlineRunnerOptions struct {
	// Harness is the harness the session needs, e.g. "openai-agents". Empty
	// accepts any online runner.
	Harness string

	// Canonicalize normalises a harness name on both sides of the comparison, so
	// a spec spelling that is an alias still matches a runner advertising the
	// canonical name. Nil compares the names as given.
	//
	// It is a function rather than a table because the aliases are the server's,
	// and a table here would be a second copy of them going stale.
	Canonicalize func(string) string
}

type ResourceEventData = api.ResourceEventData

type ResponseCancelledEvent api.CancelledEvent

type ResponseCompletedEvent api.CompletedEvent

type ResponseCreatedEvent api.CreatedEvent

type ResponseEndBlock struct {

	// Status is the terminal status, e.g. "completed" or "failed".
	Status string

	// Response is the response snapshot the terminal event carried.
	//
	// A pointer because the struct is large, not because it is optional: the four
	// terminal events declare it as a required value, so a block built from one
	// always has it. Nil only on a block a caller constructed itself.
	Response *ResponseObject
	// contains filtered or unexported fields
}

type ResponseEndCtx struct {
	ResponseID string
	Status     string
}

type ResponseFailedEvent api.FailedEvent

type ResponseHeartbeatEvent api.HeartbeatEvent

type ResponseObject = api.ResponseObject

type ResponseStartBlock struct {

	// Model is the agent model answering, e.g. "coder".
	Model string

	// ResponseID identifies the response this turn is reading.
	ResponseID string
	// contains filtered or unexported fields
}

type ResponseStartCtx struct {
	ResponseID string
	Model      string
}

type RetryBlock struct {

	// Source is what is being retried, e.g. "tool".
	Source string

	Attempt     int
	MaxAttempts int
	Delay       time.Duration
	// contains filtered or unexported fields
}

type RetryCtx struct {
	Source      string
	Attempt     int
	MaxAttempts int
}

type RetryErrorDetail = api.RetryErrorDetail

type RetryEvent api.RetryEvent

type RoutingDecisionData = api.RoutingDecisionData

type RunnerInfo struct {
	// RunnerID identifies the runner, e.g. "runner_abc123".
	RunnerID string `json:"runner_id"`

	// Online reports whether the runner is reachable now.
	Online bool `json:"online"`

	// Harnesses are the harnesses this runner advertises. Nil when the runner
	// reported no list, which [Sessions.ResolveOnlineRunner] treats as a fallback
	// rather than a refusal.
	Harnesses []string `json:"harnesses"`
}

type SandboxStatus = api.SandboxStatus

type ServerErrorCtx struct {
	Message string
	Source  string
	Code    string
}

type SessionAgentChangedEvent api.SessionAgentChangedEvent

type SessionChangedFilesInvalidatedEvent api.SessionChangedFilesInvalidatedEvent

type SessionChildSessionUpdatedEvent api.SessionChildSessionUpdatedEvent

type SessionCollaborationModeEvent api.SessionCollaborationModeEvent

type SessionCreateRequest struct {
	// AgentID is the durable identifier of the agent to bind, e.g. "ag_abc123".
	// Required, and matched by ID rather than by name.
	AgentID string `json:"agent_id"`

	// InitialItems seeds the session's input queue, typically with a single
	// user message. Seeding the first turn here avoids a follow-up send — and
	// with it the race against opening the stream.
	InitialItems []SessionEventInput `json:"initial_items,omitempty"`

	// Title is a human-readable session title.
	Title string `json:"title,omitempty"`

	// Labels are initial guardrail labels for the session.
	Labels map[string]string `json:"labels,omitempty"`

	// ParentSessionID makes this a sub-agent session of that parent, inheriting
	// its runner affinity.
	ParentSessionID string `json:"parent_session_id,omitempty"`

	// SubAgentName selects a sub-agent type within the parent's spec tree.
	SubAgentName string `json:"sub_agent_name,omitempty"`

	// HostType is "external" (the default: the caller manages the host) or
	// "managed" (the server provisions a sandbox, in the background — HostID
	// and Workspace must be empty, and appear on the snapshot once it
	// registers).
	HostType string `json:"host_type,omitempty"`

	// HostID launches the runner on a registered host. Requires Workspace.
	HostID string `json:"host_id,omitempty"`

	// Workspace is where the session works: an absolute path on the host when
	// HostID is set, or for a managed host optionally a repository URL to clone.
	// Tilde and relative paths are rejected server-side.
	Workspace string `json:"workspace,omitempty"`

	// Git asks the server to run the session in a git worktree it creates on the
	// host, with Workspace read as the source repository. Requires HostID.
	Git *SessionGitOptions `json:"git,omitempty"`

	// TerminalLaunchArgs are pass-through CLI arguments for a native terminal
	// harness. Count and length are bounded server-side.
	TerminalLaunchArgs []string `json:"terminal_launch_args,omitempty"`

	// ModelOverride persists a per-session model override at create time, so it
	// is on the session row before the harness launches.
	ModelOverride string `json:"model_override,omitempty"`

	// ReasoningEffort persists a per-session reasoning-effort override.
	// Provider support is enforced later, at launch.
	ReasoningEffort string `json:"reasoning_effort,omitempty"`

	// CostControlModeOverride is "on" or "off"; empty defers to the spec.
	CostControlModeOverride string `json:"cost_control_mode_override,omitempty"`

	// HarnessOverride selects a harness other than the agent spec's. Create-time
	// only — the harness process spawns on the first turn.
	HarnessOverride string `json:"harness_override,omitempty"`
}

type SessionCreatedEvent api.SessionCreatedEvent

type SessionEventInput struct {
	// Type is the input's discriminator; see the InputType constants. Required.
	Type string `json:"type"`

	// Data is the type-specific payload. The server validates its shape against
	// Type and rejects a mismatch with 422. Control inputs take an empty Data.
	Data map[string]any `json:"data,omitempty"`

	// ModelOverride substitutes for the agent spec's model on the turn this
	// input starts. Ignored when the input steers an already-running turn.
	ModelOverride string `json:"model_override,omitempty"`

	// Tools registers function tools for the turn this input starts, in
	// OpenAI's function-tool shape. Ignored when steering a running turn, whose
	// tool set is fixed at start.
	Tools []map[string]any `json:"tools,omitempty"`
}

type SessionFile struct {
	// ID identifies the file, e.g. "file_abc123".
	ID string `json:"id"`

	// Filename is the name the file was uploaded under. nil when the server did
	// not report one.
	Filename *string `json:"filename,omitempty"`

	// Bytes is the file's size. nil when the server did not report it, which a
	// zero-length file does not.
	Bytes *int64 `json:"bytes,omitempty"`

	// CreatedAt is the Unix epoch second the file was created. nil when the server
	// did not report it.
	CreatedAt *int64 `json:"created_at,omitempty"`

	// MimeType is the content type the server recorded, when it recorded one.
	MimeType *string `json:"mime_type,omitempty"`

	// Raw is the response body this file decoded from, so a caller can reach a
	// field this package does not name. The routes publish no schema, so the set
	// above is what has been observed rather than what is guaranteed.
	//
	// [SessionFile.UnmarshalJSON] fills it. Empty only when the body was empty.
	Raw map[string]any `json:"-"`
}

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

type SessionForkRequest = api.SessionForkRequest

type SessionGitOptions = api.SessionGitOptions

type SessionHeartbeatEvent api.SessionHeartbeatEvent

type SessionInputConsumedEvent api.SessionInputConsumedEvent

type SessionInputConsumedPayload = api.SessionInputConsumedPayload

type SessionInterruptedEvent api.SessionInterruptedEvent

type SessionInterruptedPayload = api.SessionInterruptedPayload

type SessionItem = map[string]any

type SessionItemsOptions struct {
	// Limit caps the page size. The server accepts 1 to 1000 and defaults to
	// 100; zero here sends nothing and takes that default.
	Limit int

	// After returns the items following this cursor. Use a previous page's
	// [Page.LastID].
	After string

	// Before returns the items preceding this cursor. Use a previous page's
	// [Page.FirstID]. Set beside After it narrows to the window between the two
	// rather than replacing it, because the server applies both comparisons.
	Before string

	// Order is the sort direction, and both cursors are read relative to it.
	// Empty takes this route's default, [SortAscending] — chronological, and
	// not the [SortDescending] the agent and session listings default to.
	Order SortOrder
}

type SessionKind string

type SessionList = api.SessionList

type SessionListItem = api.SessionListItem

type SessionMCPStartupEvent api.SessionMCPStartupEvent

type SessionModelEvent api.SessionModelEvent

type SessionModelOptionsEvent api.SessionModelOptionsEvent

type SessionPresenceEvent api.SessionPresenceEvent

type SessionReasoningEffortEvent api.SessionReasoningEffortEvent

type SessionResourceCreatedEvent api.SessionResourceCreatedEvent

type SessionResourceDeletedEvent api.SessionResourceDeletedEvent

type SessionResponse = api.SessionResponse

type SessionSandboxStatusEvent api.SessionSandboxStatusEvent

type SessionSkillsEvent api.SessionSkillsEvent

type SessionSortBy string

type SessionStatusEvent api.SessionStatusEvent

type SessionSupersededEvent api.SessionSupersededEvent

type SessionTerminalActivityEvent api.SessionTerminalActivityEvent

type SessionTerminalPendingEvent api.SessionTerminalPendingEvent

type SessionTodosEvent api.SessionTodosEvent

type SessionUsageEvent api.SessionUsageEvent

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

type SkillSummary = api.SkillSummary

type SkippedFrame struct {
	// SessionID is the session whose stream carried the frame.
	SessionID string

	// Name is the frame's event: line, empty when it carried none. Note that
	// dispatch prefers the payload's own type field, so this is not necessarily
	// what decoding was attempted against.
	Name string

	// Payload is the frame's data: lines, rejoined. It is bounded only by
	// maxFrameBytes, so bound it again before logging it.
	Payload string

	// Err is why the frame could not be decoded: [ErrStreamProtocol] for a
	// payload that is not JSON or carries no discriminator, otherwise a
	// field-level decode failure naming the event type it was decoded as.
	Err error
}

type SlashCommandData = api.SlashCommandData

type SortOrder string

type StreamHooks struct {
	// OnResponseStart fires once per response, when the server announces it.
	OnResponseStart func(ResponseStartCtx)

	// OnResponseEnd fires when a response reaches a terminal state, which is once
	// per turn: a tool loop's passes all report under the one response.
	OnResponseEnd func(ResponseEndCtx)

	// OnToolCallStart fires when the agent calls a tool, server-run or client-run.
	OnToolCallStart func(ToolCallStartCtx)

	// OnToolCallEnd fires when that call's output arrives.
	OnToolCallEnd func(ToolCallEndCtx)

	// OnReasoningStart fires when the server reports reasoning beginning.
	//
	// There is deliberately no matching end hook. A section closes when text starts
	// or the response ends, and its accumulated text lives in [BlockStream]'s fold;
	// a second copy of that state here would drift from the first. Reasoning
	// completion arrives on the block sequence as [ReasoningBlock] or the last
	// [ReasoningChunk], which is where a caller that wants the text reads it.
	//
	// A caller driving a spinner keys the stop on the next block of another kind
	// rather than on a hook that would have to guess the same thing.
	OnReasoningStart func(ReasoningStartCtx)

	// OnRetry fires when the server reports it is retrying.
	OnRetry func(RetryCtx)

	// OnServerError fires when the server reports an error mid-response. It is not
	// the end of the turn; a terminal response is.
	OnServerError func(ServerErrorCtx)

	// OnFileOutput fires when the agent produces a file.
	OnFileOutput func(FileOutputCtx)

	// OnElicitation decides an approval request the server raised.
	//
	// Return true to accept and false to decline. A nil hook declines, and so does
	// a hook that panics. That is this package's own behaviour and not a policy: it
	// cannot know what a caller would approve, and accepting authorises the pending
	// tool to run with the session owner's execution identity — which is not
	// necessarily the approver's. See [ElicitationAccept] for what the server
	// requires of an accept, and [ElicitationCtx] for what the request carries.
	OnElicitation func(ElicitationCtx) bool
}

type StreamOptions struct {
	// Idle marks this subscriber as present but inattentive, which co-viewers
	// see on their own streams as a presence edge. Flipping it means
	// reconnecting with the new value; there is no update path.
	Idle bool

	// IdleTimeout overrides the client's default tolerance for silence, which
	// means time with no bytes arriving. The server heartbeats every 15 seconds,
	// so this bounds transport death detection — not agent latency, and not how
	// long one large frame may take to arrive. Zero uses the client's setting.
	IdleTimeout time.Duration

	// OnSubscribed runs once the subscription is live, before the first event
	// reaches the caller, and is the supported way to post the input that
	// starts a turn. It runs on the caller's goroutine, so it must return
	// promptly; the idle monitor is suspended while it does.
	//
	// It exists because the acknowledgement cannot be recognised by inspecting
	// events. The server sends the identical {"type": "session.heartbeat"}
	// payload for two different things — the subscription acknowledgement, and
	// the keepalive it emits every 15 seconds while a stream sits idle — so
	// "send when I see a heartbeat" sends again on every keepalive, forever.
	// This hook is called exactly once per stream, on the first frame of any kind —
	// a keepalive comment, an empty frame or one this build cannot decode all show
	// the subscription is live. Not at all only if the stream ends before delivering
	// any frame, which a caller depending on this hook should give a deadline.
	// Returning an error ends the stream with that error wrapped.
	//
	// Seeding the first turn through a session's initial items avoids
	// needing this at all; it is the second and later turns that do.
	//
	// The second parameter is a struct rather than a growing parameter list
	// because this is the package's headline hook: its signature is the one thing
	// here that cannot be extended later without breaking every caller. What a
	// subscription is worth telling a caller about will grow; see [Subscription].
	OnSubscribed func(ctx context.Context, sub Subscription) error

	// OnSkippedFrame runs for a frame this build could not decode. The frame is
	// dropped and the subscription continues, so one unreadable frame degrades a
	// turn rather than ending it — which is also what the Python client does with
	// one. Leaving this nil still skips the frame; the hook is how a caller sees
	// that it happened.
	//
	// Nothing this server sends reaches it today. The stream route validates every
	// event against its event union before serializing it, and these types are
	// generated from that union's published schema, so a frame that made it onto
	// the wire has already been proven to fit. What reaches it is spec drift: a
	// field whose type changed under a client generated from an older schema. An
	// unrecognised event *type* is not that case — that surfaces as
	// [UnknownEvent] and is not an error at all.
	//
	// Like [StreamOptions.OnSubscribed] it runs on the caller's goroutine with
	// the idle monitor suspended, so it must return promptly. Returning an error
	// ends the stream with that error wrapped, which is how a caller opts back
	// into treating an undecodable frame as fatal.
	//
	// A transport failure is a different thing and stays terminal: this hook sees
	// frames that arrived and could not be read, never a stream that stopped
	// arriving.
	OnSkippedFrame func(ctx context.Context, frame SkippedFrame) error
}

type Subscription struct {
	// SessionID is the session this stream is subscribed to, so a hook shared
	// between streams does not need to close over it.
	SessionID string

	// Idle mirrors [StreamOptions.Idle]: whether this subscriber declared itself
	// present but inattentive.
	Idle bool
}

type TerminalCommandData = api.TerminalCommandData

type TextChunk struct {
	Text string
	// contains filtered or unexported fields
}

type TextDone struct {

	// FullText is the accumulated text of the section.
	FullText string

	// HasCodeBlocks reports a fenced code block in FullText, so a renderer can
	// choose a monospace treatment without scanning again.
	HasCodeBlocks bool
	// contains filtered or unexported fields
}

type ToolCallEndCtx struct {
	Name   string
	CallID string
	Output string

	// Err is set when this client ran the tool and it failed. Nil for a
	// server-executed call, whose failure arrives as its output.
	Err error
}

type ToolCallInfo struct {
	// Name is the tool the agent called.
	Name string

	// Arguments are the call's decoded arguments, or nil when the agent sent none
	// or they did not decode.
	Arguments map[string]any

	// CallID identifies the call, and is what the result is posted against.
	CallID string

	// ItemID is the conversation item the call arrived on, or empty when the
	// server sent none.
	ItemID string
}

type ToolCallStartCtx struct {
	Name      string
	CallID    string
	AgentName string
	Arguments map[string]any

	// ExecutedBy is "server" or "client".
	ExecutedBy string
}

type ToolExecution struct {
	// Name is the tool called, e.g. "Read".
	Name string

	// Arguments are the call's decoded arguments. Empty when the server sent none
	// or when they did not decode.
	Arguments map[string]any

	// ArgsSummary is a one-line rendering of Arguments for a compact display, e.g.
	// "test.py". See [FormatToolArgsBrief].
	ArgsSummary string

	// CallID identifies the call, and is what pairs a result to it.
	CallID string

	// AgentName is the agent that invoked the tool.
	AgentName string

	// ExecutedBy is "server" or "client". A client-executed call is one this SDK
	// ran on the caller's behalf; see [ToolRegistry].
	ExecutedBy string

	// Output is the tool's output, or nil while the call is still outstanding. A
	// pointer rather than an empty string, because a tool that legitimately returns
	// nothing is not a tool still running.
	Output *string
}

type ToolFunc func(context.Context, ToolCallInfo) (string, error)

type ToolGroup struct {

	// Executions are the calls in this group, in the order the server reported them.
	Executions []ToolExecution
	// contains filtered or unexported fields
}

type ToolOutputDeltaEvent api.ToolOutputDeltaEvent

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

type ToolResultBlock struct {
	Name        string
	CallID      string
	AgentName   string
	Output      string
	Arguments   map[string]any
	ArgsSummary string
	// contains filtered or unexported fields
}

type Transform func(iter.Seq2[Block, error]) iter.Seq2[Block, error]

type TreeNode struct {
	// Session is the summary the parent's listing carried. Zero for the root,
	// which no listing describes.
	Session ChildSessionSummary

	// ID is the session this node describes.
	ID string

	// Depth is how far below the root this node sits. Zero for the root.
	Depth int

	// Children are the nodes below this one.
	Children []*TreeNode

	// Truncated reports that this node has children the walk did not fetch,
	// because it reached [TreeOptions.MaxDepth] or the node ceiling. Raise the
	// bound and walk again to see them.
	Truncated bool

	// Repeated reports that this session already appears between here and the
	// root, so the walk stopped rather than following a cycle. Its children are
	// whatever they are at the shallower position.
	Repeated bool

	// Err is this node's own listing failure, so a caller can tell a subtree that
	// is empty from one that could not be read. The walk continues past it, and
	// [Sessions.ChildrenTree] also returns the first such error.
	Err error
}

type TreeOptions struct {
	// MaxDepth caps how far the walk descends. Zero means three levels.
	//
	// A cap rather than an option to omit: a session tree is server-shaped, so a
	// caller cannot know its depth before walking it, and an unbounded walk on a
	// deep tree is a request storm the caller did not ask for.
	MaxDepth int

	// Concurrency caps how many child-listing requests are in flight at once.
	// Requests rather than listings, so one node paging many times cannot hold a
	// slot for its whole drain. Zero means four.
	Concurrency int

	// MaxNodes caps how many sessions the walk will visit. Zero means one
	// thousand.
	//
	// The walk spawns one goroutine per node, so without this the tree's shape
	// decides the process's memory. It also bounds the one cost of per-path cycle
	// detection: a session reachable through two parents is expanded under both,
	// which is true to the topology and doubles the work for that subtree.
	MaxNodes int
}

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

type TurnCancelledEvent api.TurnCancelledEvent

type TurnCompletedEvent api.TurnCompletedEvent

type TurnEnd int

type TurnFailedEvent api.TurnFailedEvent

type TurnOptions struct {
	// End selects the signal that ends the turn. The zero value is the stricter
	// rule; see [TurnEndsOnIdleStatus].
	End TurnEnd

	// PriorResponseIDs are the responses already on the session before this turn's
	// prompt was posted.
	//
	// Supplying them is what separates this turn's end from an older one's. A
	// response that was live before the prompt goes on running server-side and can
	// reach a terminal inside this turn's window; its event is otherwise
	// indistinguishable from this turn's, and taken as this turn's it ends the read
	// early against another turn's reply.
	//
	// Read once, at the start. Build it from [Sessions.Get]:
	// [SessionResponse.ActiveResponseID] names the response in flight, which is the
	// one that can reach a terminal inside this turn's window. A session with
	// nothing in flight needs no entry.
	//
	// Only an entry whose value is true counts, so a map built with false values
	// gives no protection.
	PriorResponseIDs map[string]bool
}

type TurnStartedEvent api.TurnStartedEvent

type UnknownEvent struct {
	// Type is the frame's discriminator, e.g. "session.something.new".
	Type string

	// Raw is the frame's JSON payload, owned by the caller.
	Raw []byte
}

type UpdateSessionRequest = api.UpdateSessionRequest

type Usage = api.Usage

type UsageDetails = api.UsageDetails

type ValidationError struct {
	// Loc is the path to the offending field. Its elements are strings and
	// integers mixed, because a path crosses object keys and array indices, so
	// it is []any rather than a generated wrapper type per position.
	Loc []any `json:"loc"`

	// Msg is the human-readable problem with that field.
	Msg string `json:"msg"`

	// Type is the validator's own name for the failure, e.g. "string_type".
	Type string `json:"type"`

	// Ctx carries validator-specific context. Nil when absent.
	Ctx map[string]any `json:"ctx,omitempty"`

	// Input is the value that failed validation. Nil when absent.
	Input any `json:"input,omitempty"`
}