chatsync

type AgentOrigin struct {
	Task string `json:"task,omitempty"`
	Name string `json:"name,omitempty"`
	// Depth carries NO omitempty, deliberately. omitempty omits the zero
	// value, so a depth of 0 - the root agent - vanished from the wire and an
	// attributed root event became indistinguishable from a subagent event
	// whose depth simply had not been stamped. Consumers split the main
	// transcript from the subagent lanes on exactly this field, so the web
	// viewer filed the root agent's own prose and reasoning under a lane and
	// showed a transcript of tool cards with nothing between them. When an
	// origin is present at all, its depth is now always stated.
	Depth int `json:"depth"`
	// ParentTask is the Task of the subagent that dispatched this one, empty
	// when the root loop did. Depth reports how deep a run sits; this reports
	// under WHICH run, which two runs at the same depth do not share.
	ParentTask string `json:"parent_task,omitempty"`
}

type AppendResult struct {
	LastSeq       int64 `json:"lastSeq"`
	InsertedCount int   `json:"insertedCount"`
}

type AssistantDeltaPayload struct {
	Envelope
	Text  string `json:"text"`
	Index int    `json:"index"`
}

type AssistantMessagePayload struct {
	Envelope
	Fragments int    `json:"fragments"`
	Bytes     int    `json:"bytes"`
	Status    string `json:"status"`
	Text      string `json:"text,omitempty"`
}

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

type AuthorUserIDProvider func(ctx context.Context) (string, error)

type BadRequestError struct {
	StatusCode int
	Message    string
	Code       string
}

type BlockGrammar struct {
	Prose                  string   `json:"prose"`
	Streams                []string `json:"streams"`
	ToolBlockField         string   `json:"toolBlockField"`
	ResetBlockIsStreamOnly bool     `json:"resetBlockIsStreamOnly"`
	StepIsDense            bool     `json:"stepIsDense"`
	StepReuse              string   `json:"stepReuse"`
}

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

type ClientOptions struct {
	BaseURL    string
	HTTPClient *http.Client
	Timeout    time.Duration
}

type ConflictError struct {
	StatusCode int
	Message    string
	Code       string
}

type ContextCompactedPayload struct {
	Envelope
	Compaction   any    `json:"compaction,omitempty"`
	Message      string `json:"message,omitempty"`
	BetweenTurns bool   `json:"between_turns,omitempty"`
}

type CreateSessionParams struct {
	Title     string `json:"title"`
	CwdLabel  string `json:"cwdLabel,omitempty"`
	HostLabel string `json:"hostLabel,omitempty"`
	// ForkedFromSessionID names the session this one continues, set only by
	// recovery. omitempty: an API that predates the field runs
	// forbidNonWhitelisted and would 400 a create that sent it empty.
	ForkedFromSessionID string `json:"forkedFromSessionId,omitempty"`
}

type Cursor struct {
	FlushedSeq int64     `json:"flushed_seq"`
	FlushedAt  time.Time `json:"flushed_at"`
}

type Endpoint struct {
	URL string
	// Source names what supplied URL: "[sync] api_url", the env var with the
	// file or process that set it, or "default".
	Source string
}

type Envelope struct {
	V            int          `json:"v"`
	At           time.Time    `json:"at"`
	Turn         string       `json:"turn"`
	Block        string       `json:"block,omitempty"`
	Agent        *AgentOrigin `json:"agent,omitempty"`
	Trunc        *Truncation  `json:"trunc,omitempty"`
	Redacted     []string     `json:"redacted,omitempty"`
	SourceTurnID string       `json:"source_turn_id,omitempty"`
	WriterID     string       `json:"writer_id,omitempty"`
}

type ErrorEnvelope struct {
	StatusCode int             `json:"statusCode"`
	Error      string          `json:"error"`
	Message    json.RawMessage `json:"message"`
	Path       string          `json:"path"`
}

type EventItem struct {
	Seq     int64           `json:"seq"`
	Type    string          `json:"type"`
	Payload json.RawMessage `json:"payload"`
}

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

type HookRanPayload struct {
	Envelope
	// Phase is PreToolUse, PostToolUse or Stop.
	Phase string `json:"phase"`
	// Program is the script's NAME, never its path. A path describes the
	// operator's machine and this payload leaves it.
	Program string `json:"program"`
	// Tool is the call the hook ran for; empty for a Stop hook.
	Tool       string `json:"tool,omitempty"`
	ToolCallID string `json:"tool_call_id,omitempty"`
	// Blocked is true for the run that refused the call. A reader must not
	// have to infer this from the absence of a later event.
	Blocked bool `json:"blocked"`
	// OutputBytes always reports the real size, even when Output is withheld,
	// so a reader can tell "the hook said nothing" from "the hook said
	// something you are not being shown".
	OutputBytes int `json:"output_bytes"`
	// Output is what the hook printed - for a blocking hook, the reason. It
	// rides the same include-tool-io gate as tool output, because it is the
	// same class of thing: text a local program produced.
	Output string `json:"output,omitempty"`
}

type IdentityRef struct {
	Dir string
	Key string
}

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

type LocalHandle string

type NextInput struct {
	Input *SessionInput `json:"input"`
}

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

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

type ProjectorOptions struct {
	StreamAssistant bool
	IncludeToolIO   bool
	IncludeThinking bool
	WriterID        string

	// RedactToolArgs is the host's tool-argument redaction decision, passed
	// in as a value. It composes with IncludeToolIO as an AND: tool IO ships
	// only when IncludeToolIO is true AND RedactToolArgs is false.
	RedactToolArgs bool

	// ErrorMessage classifies a turn error into redaction-safe text for the
	// wire. Nil selects defaultErrorMessage, which is content-free by
	// construction. Provider and tool error text can quote the request that
	// produced it (DC-14), so err.Error() must never reach this wire.
	ErrorMessage func(error) string
}

type RemoteInput struct {
	ID        string
	SessionID string
	Kind      string
	Body      string
	Received  time.Time
}

type Session struct {
	ID              string  `json:"id"`
	OrganizationID  string  `json:"organizationId"`
	UserID          string  `json:"userId"`
	Title           string  `json:"title"`
	CwdLabel        *string `json:"cwdLabel"`
	HostLabel       *string `json:"hostLabel"`
	Status          string  `json:"status"`
	LastSeq         int64   `json:"lastSeq"`
	LastEventAt     string  `json:"lastEventAt"`
	LastHeartbeatAt string  `json:"lastHeartbeatAt"`
	EndedAt         *string `json:"endedAt"`
	CreatedAt       string  `json:"createdAt"`
}

type SessionAttachment struct {
	SessionID  string
	ServerSeq  int64
	FlushedSeq int64
	ForkedFrom string
}

type SessionInput struct {
	ID           string  `json:"id"`
	SessionID    string  `json:"sessionId"`
	AuthorUserID string  `json:"authorUserId"`
	Kind         string  `json:"kind"`
	Body         string  `json:"body"`
	CreatedAt    string  `json:"createdAt"`
	ConsumedAt   *string `json:"consumedAt"`
}

type SessionOptions struct {
	// TokenProvider is required. OpenSession refuses to start without it.
	TokenProvider    TokenProvider
	ClientOptions    ClientOptions
	ProjectorOptions ProjectorOptions
	OutboxDir        string
	// RemoteSessionID is the server-assigned session to re-attach to, read
	// from the persisted identity. Empty creates a fresh remote session. It is
	// the ONLY value that may appear in a request URL, and it is deliberately
	// NOT the chat session id OpenSession filters the bus on.
	RemoteSessionID string
	// LocalHandle is the local-only handle that names OutboxDir. It is carried
	// here so the identity write-back can rewrite the record without re-reading
	// (and possibly re-minting) it.
	LocalHandle LocalHandle
	// Identity names the file the resolved remote session id is written back
	// to. Zero disables the write-back: the session then works exactly as
	// before, but the next run cannot find the remote session it created.
	Identity        IdentityRef
	MaxUnflushed    int
	PollWaitSeconds int
	HeartbeatPeriod time.Duration
	Telemetry       *SyncTelemetry
	CreateTitle     string
	CwdLabel        string
	HostLabel       string
	EnablePolling   bool
	// AuthorUserIDProvider resolves the CLI's own authenticated principal id
	// for verifying who queued a remote input. Required for EnablePolling to
	// deliver anything: nil verifies nothing, so InputPoller refuses every
	// input closed. See chatsync.AuthorUserIDProvider.
	AuthorUserIDProvider AuthorUserIDProvider
	// OnInputRejected, when set, is called for every remote input
	// InputPoller refuses (session id mismatch, unsupported kind, malformed
	// body, unverifiable or mismatched author). Nil means refusals stay
	// silent to the host.
	OnInputRejected func(id, sessionID, reason string)
	// EventBufSize bounds the handler-to-worker channel. Zero means
	// defaultEventBufSize. Overflow here is real loss and is counted into the
	// sync.dropped marker, exactly like loss on the bus.
	EventBufSize int

	// OnStop is called exactly once, with the same string StopReason returns,
	// when sync latches a terminal stop: a fatal auth failure, a poison 400,
	// or a recovery bound. It is never called for an orderly Stop, and never
	// for a 409 or 404 on their own - those recover onto a new session.
	//
	// It exists because the contract's poison rule is "stop syncing and SAY
	// SO", and a reason only a getter can reach says nothing: no host polls
	// SyncSession, so a silent stop looks exactly like a healthy idle
	// session. Nil is valid and means the host does not surface stops.
	//
	// It runs on a detached goroutine, NOT on the worker: the worker still has
	// a drain and a final flush to finish, and a host callback that blocks
	// (writing to a terminal, or sending on a full UI channel) must not be
	// able to hold that up.
	OnStop func(reason string)

	// OnDegraded is called once when pushes stop landing - three consecutive
	// failures, or a failure a minute after the last success - and
	// OnRecovered once when they land again. Neither is a stop: the outbox
	// keeps the backlog and the retry schedule keeps trying. They exist
	// because a transient failure that never ends is otherwise silent for the
	// whole session (flushNow's default branch retries forever and says
	// nothing), and the same fact is written to status.json in OutboxDir so
	// it outlives the process. Both run on a detached goroutine, like OnStop.
	OnDegraded  func(reason string)
	OnRecovered func()
}

type StoredEvent struct {
	SessionID string          `json:"sessionId"`
	Seq       int64           `json:"seq"`
	Type      string          `json:"type"`
	Payload   json.RawMessage `json:"payload"`
	CreatedAt string          `json:"createdAt"`
}

type SubagentAssistantDeltaPayload struct {
	Envelope
	Text  string `json:"text"`
	Index int    `json:"index"`
}

type SubagentAssistantMessagePayload struct {
	Envelope
	Fragments int    `json:"fragments"`
	Bytes     int    `json:"bytes"`
	Status    string `json:"status"`
	Text      string `json:"text,omitempty"`
}

type SubagentEndedPayload struct {
	Envelope
	Name   string `json:"name,omitempty"`
	Status string `json:"status,omitempty"`
}

type SubagentProgressPayload struct {
	Envelope
	Detail string `json:"detail,omitempty"`
}

type SubagentStartedPayload struct {
	Envelope
	Name string `json:"name,omitempty"`
	Task string `json:"task,omitempty"`
}

type SubagentThinkingDeltaPayload struct {
	Envelope
	Bytes int    `json:"bytes"`
	Index int    `json:"index"`
	Text  string `json:"text,omitempty"`
}

type SubagentThinkingMessagePayload struct {
	Envelope
	Fragments int    `json:"fragments"`
	Bytes     int    `json:"bytes"`
	Status    string `json:"status"`
	Text      string `json:"text,omitempty"`
}

type SubagentToolEndedPayload struct {
	Envelope
	ToolCallID  string `json:"tool_call_id"`
	Name        string `json:"name"`
	Status      string `json:"status"`
	OutputBytes int    `json:"output_bytes"`
	Detail      string `json:"detail,omitempty"`
	Output      string `json:"output,omitempty"`
}

type SubagentToolStartedPayload struct {
	Envelope
	ToolCallID string `json:"tool_call_id"`
	Name       string `json:"name"`
	InputBytes int    `json:"input_bytes"`
	Phase      string `json:"phase,omitempty"`
	Input      string `json:"input,omitempty"`
}

type SyncDroppedPayload struct {
	Envelope
	Dropped      uint64 `json:"dropped"`
	TotalDropped uint64 `json:"total_dropped"`
}

type SyncForkedPayload struct {
	Envelope
	NewSessionID string `json:"new_session_id"`
	// ForkedFrom names the session that was abandoned, so the new session's
	// stream self-describes its ancestor. Empty on markers older producers
	// wrote.
	ForkedFrom string `json:"forked_from,omitempty"`
}

type SyncIdentity struct {
	LocalHandle     LocalHandle `json:"local_handle"`
	RemoteSessionID string      `json:"remote_session_id,omitempty"`
	WriterID        string      `json:"writer_id"`
}

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

type SyncStatus struct {
	State                string     `json:"state"`
	Reason               string     `json:"reason"`
	Unflushed            int        `json:"unflushed"`
	LastSuccessAt        *time.Time `json:"last_success_at"`
	ConsecutiveFailures  int        `json:"consecutive_failures"`
	Recoveries           int        `json:"recoveries"`
	CreateFailures       int        `json:"create_failures"`
	CreateThrottledUntil *time.Time `json:"create_throttled_until"`
	At                   time.Time  `json:"at"`
}

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

type SyncTelemetrySnapshot struct {
	Produced       uint64
	Projected      uint64
	Appended       uint64
	Uploaded       uint64
	UploadFailures uint64
	LastAckSeq     int64
	LastSuccessAt  time.Time
	OutboxDepth    int64
}

type ThinkingDeltaPayload struct {
	Envelope
	Bytes int    `json:"bytes"`
	Index int    `json:"index"`
	Text  string `json:"text,omitempty"`
}

type ThinkingMessagePayload struct {
	Envelope
	Fragments int    `json:"fragments"`
	Bytes     int    `json:"bytes"`
	Status    string `json:"status"`
	Text      string `json:"text,omitempty"`
}

type TokenEnsurer interface {
	Ensure(ctx context.Context) (string, error)
}

type TokenProvider func(ctx context.Context, forceRefresh bool) (string, error)

type ToolEndedPayload struct {
	Envelope
	ToolCallID  string `json:"tool_call_id"`
	Name        string `json:"name"`
	Status      string `json:"status"`
	OutputBytes int    `json:"output_bytes"`
	Detail      string `json:"detail,omitempty"`
	Output      string `json:"output,omitempty"`
}

type ToolStartedPayload struct {
	Envelope
	ToolCallID string `json:"tool_call_id"`
	Name       string `json:"name"`
	InputBytes int    `json:"input_bytes"`
	Phase      string `json:"phase,omitempty"`
	Input      string `json:"input,omitempty"`
}

type TruncField struct {
	Kept  int `json:"kept"`
	Total int `json:"total"`
}

type Truncation struct {
	Fields map[string]TruncField `json:"fields"`
}

type TurnEndedPayload struct {
	Envelope
	Reason string `json:"reason"`
}

type TurnFailedPayload struct {
	Envelope
	Message string `json:"message"`
}

type TurnStartedPayload struct {
	Envelope
	Text       string `json:"text,omitempty"`
	SessionRef string `json:"session_ref,omitempty"`
	Synthetic  bool   `json:"synthetic,omitempty"`
}

type WireEvent struct {
	Seq     int64  `json:"seq"`
	Type    string `json:"type"`
	Payload any    `json:"payload"`
}

type WireEventSpec struct {
	// Type is the mivia.chat.v1.* type string. The API names each SSE frame
	// after this exact string, so a browser client must register a listener
	// per entry: EventSource.onmessage never fires for these events. This is
	// confirmed live by live_sse_test.go's "names the frame after the event
	// type" subtest (build tag livechat) and is intentional, documented
	// behavior per api/contracts/chat-sessions.v1.json's notes array; see
	// docs/development/agent-workflow.md's "Live chat-session probe" section
	// for the forward-compatibility trade-off this implies.
	Type string
	// Payload is a zero value of the struct that models this type's payload.
	Payload any
}