transcript

type AgentRun struct {
	ID    string `json:"id"`
	Index int    `json:"index"` // 1-based ordinal of the human intent (RoundNav's #N SSOT)

	// UserIntent is the human's own input that opened this run. Nil only for a system
	// run (runtime activity/notification with no human line — Diagnostic.NoIntent).
	UserIntent *RunIntent `json:"user_intent,omitempty"`
	// Amendments are human inputs that steered THIS run while it was still working.
	// They are not rounds (the adapter, not the projector, decides this — Turn.InputKind).
	Amendments []RunIntent `json:"amendments,omitempty"`

	// Segments is the agent's PROCESS, in strict transcript order: narration, thinking,
	// tools, subagents, compaction, errors. Collapsing it in the UI is a visibility state
	// only — segment ids/count/order/content never change.
	Segments []Block `json:"segments"`
	// FinalAnswer is the run's RESULT — the text of the terminal (yielding) iteration.
	// It is a separate field, not a segment, precisely so that collapsing the process can
	// never hide the answer. Empty = this run produced no answer (interrupted, tool-only,
	// crashed): the UI then says so honestly instead of rendering an empty bubble.
	FinalAnswer []Block `json:"final_answer,omitempty"`

	// Usage is the run's single aggregate (the footer consumes only this one).
	Usage *RunUsage `json:"usage,omitempty"`

	Status    string     `json:"status"`
	StartedAt *time.Time `json:"started_at,omitempty"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`

	Diagnostic RunDiagnostic `json:"diagnostic"`
}

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

type Block struct {
	Type string `json:"type"`

	// EventID is a STABLE identity for this content unit, derived from the source event
	// (claude message.id + ordinal / codex call_id / line ordinal) — never a render-time
	// counter. The UI keys expansion state and list diffing on it, so a reload or a
	// re-fetch must produce the same ids or the user's open/closed choices re-bind to the
	// wrong segments.
	EventID string `json:"event_id,omitempty"`

	// text / thinking
	Text string `json:"text,omitempty"`

	// Final marks the text that belongs to the run's TERMINAL (yielding) iteration — the
	// answer, as opposed to mid-run narration. The projector lifts these out of the
	// process trace into AgentRun.FinalAnswer, which is why it can never be swallowed by
	// a collapse. It is a DOMAIN fact (claude stop_reason=end_turn / codex the message
	// that precedes task_complete), not a position: "the last text block" would let an
	// aborted run's narration impersonate an answer, and would push a real answer back
	// into the trace whenever a notification happened to follow it.
	Final bool `json:"-"`

	// tool / agent (a tool_use)
	ToolName   string                 `json:"tool_name,omitempty"`
	ToolUseID  string                 `json:"tool_use_id,omitempty"`
	ToolInput  map[string]interface{} `json:"tool_input,omitempty"`
	ToolResult string                 `json:"tool_result,omitempty"`
	IsError    bool                   `json:"is_error,omitempty"`
	// ResultSeen: a tool_result actually arrived for this call. false = the tool never
	// completed (the run was interrupted / the session died mid-call). The UI must render
	// it as stopped, NOT as done — stamping "done" on every replayed tool (the old
	// behavior) fabricates success for work that never finished.
	ResultSeen bool `json:"result_seen,omitempty"`
	// Orphan: a tool_result with no matching call in this transcript. Kept (never dropped)
	// + counted in RunDiagnostic, so a lossy source degrades visibly.
	Orphan bool `json:"orphan,omitempty"`

	// agent (Agent tool_use → subagent). SubagentType is the dispatched agent
	// kind; Description is the human-readable task; the inner subflow blocks are
	// in Children (P1: empty — sidechain transcript stitching deferred to P2).
	SubagentType string  `json:"subagent_type,omitempty"`
	Description  string  `json:"description,omitempty"`
	Children     []Block `json:"children,omitempty"`

	// agent usage/timing (CHG-014 P3b — Gap-4). DurationMs is the wall-clock
	// delta between the Agent tool_use line and its tool_result line — the only
	// honest end-to-end subagent timing available from the parent jsonl (claude
	// does not inline the subagent's own usage; sidechain transcripts are absent
	// in practice). InTokens/OutTokens stay 0 (→ omitted → frontend "—") unless a
	// future source supplies the subagent's own usage. Honest-degradation rule:
	// never fabricate token counts (SPEC-UX-ROUND3 §5).
	DurationMs int `json:"duration_ms,omitempty"`
	InTokens   int `json:"in_tokens,omitempty"`
	OutTokens  int `json:"out_tokens,omitempty"`

	// task-notification (CHG-014 P3b — Gap-4). NotifyStatus = completed|failed|
	// killed; Text carries the human-readable <summary>; TaskID is the runtime
	// task id (debug/round-trip). Parsed from a claude `<task-notification>` user
	// line — see claude.go.
	NotifyStatus string `json:"notify_status,omitempty"`
	TaskID       string `json:"task_id,omitempty"`

	// usage
	Usage map[string]interface{} `json:"usage,omitempty"`
}

type ClaudeSource struct {
	// Root is the projects base dir; defaults to ~/.claude/projects.
	Root string
}

type CodexModelUsage struct {
	At              time.Time
	Model           string
	InputTokens     int
	OutputTokens    int
	CacheReadTokens int
}

type CodexSource struct {
	Root string // defaults to ~/.codex
	// contains filtered or unexported fields
}

type DeepworkSessionMeta struct {
	ID        int64
	Title     string
	CreatedAt time.Time
	UpdatedAt time.Time
	TurnCount int
}

type DeepworkSessionProvider interface {
	// ListWorkspaceSessions returns the deepwork-owned sessions for a workspace.
	ListWorkspaceSessions(ctx context.Context, workspaceID int64) ([]DeepworkSessionMeta, error)
	// KnownSessionIDs returns the set of ALL deepwork session ids the DB knows about
	// (any workspace, any source) as decimal strings. Directory-as-index recovery uses
	// it to recover ONLY genuine orphans: a transcript file whose id is globally known
	// but absent from THIS workspace's rows belongs to another workspace/source and must
	// not be re-surfaced (CHG-016 R3 cross-workspace session leak). A nil map (provider
	// error / DB gone) degrades to recover-all, preserving the "delete DB still lists".
	KnownSessionIDs(ctx context.Context) (map[string]struct{}, error)
	// LoadSessionTurns returns the typed turns for one deepwork session (DB
	// fallback only — the jsonl file is the primary read source).
	LoadSessionTurns(ctx context.Context, sessionID int64) ([]DeepworkTurn, error)
}

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

type DeepworkTurn struct {
	UserInput string
	AIOutput  string
	At        time.Time
}

type DirCounter interface {
	// CountSessionsByDir returns a map of project dir (cwd) → session count for
	// every session this source stored, in one sweep. Hidden/soft-delete is NOT
	// applied here (the panel hint counts SSOT sessions; the aggregator applies
	// the overlay filter only on the detailed List path).
	CountSessionsByDir(ctx context.Context) (map[string]int, error)
}

type HiddenStore interface {
	// IsHidden reports whether (source, ssotKey) is soft-deleted.
	IsHidden(ctx context.Context, source, ssotKey string) (bool, error)
	// HiddenSet returns the set of hidden ssot keys for a source (batch filter).
	HiddenSet(ctx context.Context, source string) (map[string]bool, error)
	// Overlays returns the full overlay state (hidden + friendly_name) per ssot
	// key for a source, in one batch read (used by the aggregator).
	Overlays(ctx context.Context, source string) (map[string]SessionOverlay, error)
	// SetHidden marks/unmarks a session as hidden (idempotent). Preserves any
	// existing friendly_name.
	SetHidden(ctx context.Context, source, ssotKey string, hidden bool) error
	// SetFriendlyName sets/clears the soft-rename (idempotent). Preserves the
	// existing hidden flag. Empty name clears the rename.
	SetFriendlyName(ctx context.Context, source, ssotKey, name string) error
}

type ListResult struct {
	Sessions []SessionMeta
	Degraded []string // source kinds that failed
	Wired    int      // number of wired sources
	Failed   int      // number that errored
}

type NativeContentBlock struct {
	Type      string          `json:"type"` // text | thinking | tool_use | tool_result
	Text      string          `json:"text,omitempty"`
	Thinking  string          `json:"thinking,omitempty"`
	ID        string          `json:"id,omitempty"`
	Name      string          `json:"name,omitempty"`
	Input     json.RawMessage `json:"input,omitempty"`
	ToolUseID string          `json:"tool_use_id,omitempty"`
	Content   json.RawMessage `json:"content,omitempty"`
	IsError   bool            `json:"is_error,omitempty"`
}

type NativeEntry struct {
	Format            string          `json:"format,omitempty"`
	Runtime           string          `json:"runtime,omitempty"`
	Type              string          `json:"type"` // user | assistant | result | progress
	UUID              string          `json:"uuid,omitempty"`
	ParentUUID        *string         `json:"parentUuid"`
	SessionID         string          `json:"sessionId"`
	Timestamp         string          `json:"timestamp"`
	Message           *NativeMessage  `json:"message,omitempty"`
	Subtype           string          `json:"subtype,omitempty"`
	DurationMs        int             `json:"duration_ms,omitempty"`
	NumTurns          int             `json:"num_turns,omitempty"`
	DeepworkSessionID int64           `json:"deepworkSessionId,omitempty"`
	DeepworkTurnID    int64           `json:"deepworkTurnId,omitempty"`
	Workstream        json.RawMessage `json:"workstream,omitempty"`
	// Metrics (v1.1) inlines per-turn ttft/usage on the turn-closing `result`
	// entry so the transcript carries the round's metrics without the DB. nil on
	// non-result entries and on legacy (v1) files.
	Metrics *NativeMetrics `json:"metrics,omitempty"`

	// CWD / GitBranch / Version make a line SELF-DESCRIBING — the same three claude
	// stamps on every entry. Without them a transcript cannot say which checkout it
	// describes, and replay/attribution has to reach outside the file for context.
	CWD       string `json:"cwd,omitempty"`
	GitBranch string `json:"gitBranch,omitempty"`
	Version   string `json:"version,omitempty"`

	// RequestID pairs with NativeMessage.ID as the DEDUP KEY for token accounting —
	// the pair kit/usage keys claude usage on. Deepwork turns carried neither, which
	// is precisely why deepwork-native sessions contribute nothing to the cost report
	// today: there is no stable identity to dedup a re-read line by.
	RequestID string `json:"requestId,omitempty"`

	// IsSidechain / AgentID model a SUBAGENT branch, exactly as claude does: a
	// sidechain entry belongs to a spawned agent's own conversation rather than the
	// main thread, and AgentID names which one. The agent-tree projection is built
	// from these two fields.
	//
	// RESERVED — the deepwork agent runtime does not spawn subagents yet, so nothing
	// sets these. They exist now so the wire format does not need a breaking bump the
	// day it does, and so the reader/tree code can be written against a stable shape.
	IsSidechain bool   `json:"isSidechain,omitempty"`
	AgentID     string `json:"agentId,omitempty"`

	// UserType mirrors claude ("external" for a human turn, "internal" for one the
	// runtime synthesised, e.g. a tool_result fed back in). Empty = unspecified.
	UserType string `json:"userType,omitempty"`
}

type NativeMessage struct {
	// ID (v1.2) is the provider's message id (claude: "msg_…"). With NativeEntry.RequestID
	// it forms the dedup key token accounting uses — see RequestID's note.
	ID   string `json:"id,omitempty"`
	Role string `json:"role"`
	// Model (v1.1) is the real model id that produced this assistant turn,
	// mirroring claude's `message.model`. Empty = path did not report.
	Model   string               `json:"model,omitempty"`
	Content []NativeContentBlock `json:"content"`
	// StopReason (v1.2) is why the assistant stopped: "end_turn" | "tool_use" |
	// "max_tokens" | "stop_sequence". This is the signal agent-status detection reads
	// to tell "the agent finished its turn and is waiting for you" apart from "it
	// paused mid-turn to run a tool" — without it, a deepwork session cannot express
	// the running→waiting transition that drives the turn-end notification.
	// Empty = the path did not report one (honest unknown, never guessed).
	StopReason string `json:"stop_reason,omitempty"`
	// Usage (v1.1) inlines the round's token accounting on the assistant message,
	// mirroring claude's `message.usage`. nil = path reported no usage (honest
	// unknown, never fabricated). Self-sufficient: deleting the DB does not lose it.
	Usage *NativeUsage `json:"usage,omitempty"`
}

type NativeMetrics struct {
	TTFTMs     *int `json:"ttft_ms,omitempty"`
	DurationMs int  `json:"duration_ms,omitempty"`
}

type NativeUsage struct {
	InputTokens  *int `json:"input_tokens,omitempty"`
	OutputTokens *int `json:"output_tokens,omitempty"`
	// ThinkingTokens — reasoning token 单列 (CHG-016). Inlined on the assistant
	// line so the deepwork replay footer shows the SAME thinking token the live
	// stream did (nil = unknown → 「—」, distinct from the thinking duration).
	ThinkingTokens    *int `json:"thinking_tokens,omitempty"`
	CacheReadTokens   *int `json:"cache_read_tokens,omitempty"`
	CacheCreateTokens *int `json:"cache_creation_tokens,omitempty"`
	// TTFTMs — first-content latency, inlined on the assistant line's usage so the
	// per-turn replay footer renders TTFT without chasing the separate `result`
	// line (which the unified reader skips). nil = unknown → 「—」.
	TTFTMs *int `json:"ttft_ms,omitempty"`
}

type RunDiagnostic struct {
	RawTurns      int  `json:"raw_turns"`                // adapter turns folded into this run
	SegmentCount  int  `json:"segment_count"`            //
	UsageBlocks   int  `json:"usage_blocks,omitempty"`   // usage deltas summed into Usage
	OrphanResults int  `json:"orphan_results,omitempty"` // tool results with no matching call
	PendingTools  int  `json:"pending_tools,omitempty"`  // tool calls whose result never arrived
	NoIntent      bool `json:"no_intent,omitempty"`      // runtime activity with no human line
	Unterminated  bool `json:"unterminated,omitempty"`   // the runtime never yielded
}

type RunIntent struct {
	Text string     `json:"text"`
	At   *time.Time `json:"at,omitempty"`
}

type RunUsage struct {
	InputTokens       int      `json:"input_tokens,omitempty"`
	OutputTokens      int      `json:"output_tokens,omitempty"`
	ThinkingTokens    int      `json:"thinking_tokens,omitempty"`
	CacheReadTokens   int      `json:"cache_read_tokens,omitempty"`
	CacheCreateTokens int      `json:"cache_create_tokens,omitempty"`
	TTFTMs            *int     `json:"ttft_ms,omitempty"`
	DurationMs        *int     `json:"duration_ms,omitempty"`
	CostUSD           *float64 `json:"cost_usd,omitempty"`
	Model             string   `json:"model,omitempty"`
	Models            []string `json:"models,omitempty"`
}

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

type SessionMeta struct {
	// ID is a stable, source-scoped identifier used to round-trip back to the
	// SSOT for a transcript load. For claude it is the jsonl basename (uuid);
	// for deepwork it is the numeric session id as a string.
	ID     string `json:"id"`
	Source string `json:"source"` // claude | codex | deepwork
	// SsotPath is the on-disk transcript path (claude jsonl / codex jsonl) or
	// the deepwork session id. Surfaced to the UI for the "源自 …" tooltip.
	SsotPath  string    `json:"ssot_path"`
	Title     string    `json:"title"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	TurnCount int       `json:"turn_count"`
	// Hidden is the deepwork soft-delete flag (virtual delete). The SSOT is
	// never removed; hidden rows are filtered out of the default list.
	Hidden bool `json:"hidden"`
	// FriendlyName is the deepwork-owned soft-rename. When non-empty it has
	// already been applied onto Title by the aggregator; it is surfaced here so
	// the UI can distinguish a renamed session from its SSOT title. The runtime
	// transcript title is never modified (SSOT protection).
	FriendlyName string `json:"friendly_name,omitempty"`
	// Activity / Attention / Owned are the WLS-8b live activity state, derived at
	// list time (NOT stored): Activity = LIVE|OBSERVED|QUIET, Attention =
	// working|waiting|error|idle, Owned = this MuxHost holds a live REPL for it.
	// Empty Activity means the list route did not derive it (no deriver wired) —
	// the frontend treats absent state as QUIET/idle. These drive the two-axis tab
	// + tree badge and the OBSERVED「在另一会话中活跃·观测中」banner/composer-lock.
	Activity  string `json:"activity,omitempty"`
	Attention string `json:"attention,omitempty"`
	Owned     bool   `json:"owned,omitempty"`
	// SessionExecution is orthogonal to the root liveness/write-authority axes above.
	// A quiet root may still have running child AgentExecutions.
	ExecutionActivity   string `json:"execution_activity,omitempty"` // running | idle
	RootAgentState      string `json:"root_agent_state,omitempty"`   // running | waiting | idle | error
	InteractionMode     string `json:"interaction_mode,omitempty"`   // owned | observed | history
	RunningAgents       int    `json:"running_agents,omitempty"`
	ExecutionObservedAt int64  `json:"execution_observed_at,omitempty"`
	AgentSourceStatus   string `json:"agent_source_status,omitempty"` // complete | partial | unknown
}

type SessionOverlay struct {
	Hidden       bool
	FriendlyName string
}

type SessionRef struct {
	ProjectDir string // the project root_dir the session belongs to
	ID         string // source-scoped id (claude jsonl basename / deepwork session id)
}

type SessionRuntimeResolver interface {
	// SessionRuntimeInfo returns the session's runtime ("claude"/"codex"/…) and the
	// upstream CLI-owned conversation id (empty for a native deepwork_api session).
	SessionRuntimeInfo(ctx context.Context, sessionID int64) (runtime, runtimeSessionID string, err error)
}

type SessionSource interface {
	// Kind returns the SSOT origin tag (claude | codex | deepwork).
	Kind() string
	// ListSessions enumerates the sessions this runtime stored for projectDir.
	ListSessions(ctx context.Context, projectDir string) ([]SessionMeta, error)
	// LoadTranscript parses one session's body from the SSOT into turns/blocks.
	LoadTranscript(ctx context.Context, ref SessionRef) (*Transcript, error)
}

type TouchedFile struct {
	Name      string `json:"name"`
	Path      string `json:"path"` // relative to rootDir
	IsDir     bool   `json:"is_dir"`
	Size      int64  `json:"size"`
	TouchedAt int64  `json:"touched_at,omitempty"` // unix ms of the tool_use that touched it
	Tool      string `json:"tool,omitempty"`       // the edit tool (Write/Edit/…)
}

type Transcript struct {
	Source string                 `json:"source"`
	Ref    string                 `json:"ref"`
	Title  string                 `json:"title"`
	Turns  []Turn                 `json:"-"`              // adapter fact, server-side only
	Runs   []AgentRun             `json:"runs"`           // ← the wire contract (ProjectAgentRuns)
	Meta   map[string]interface{} `json:"meta,omitempty"` // usage totals etc.
}

type Turn struct {
	Index  int     `json:"index"`
	Role   string  `json:"role"` // user | assistant
	Blocks []Block `json:"blocks"`
	// Timestamp of the underlying jsonl line, when available.
	At *time.Time `json:"at,omitempty"`
	// Terminal is the ADAPTER-supplied, runtime-agnostic "this assistant turn
	// yielded control back to the human" fact. Empty = the runtime is still working
	// (a tool loop continues).
	//
	// Derivation per runtime (verified against real transcripts):
	//   claude   message.stop_reason: end_turn → TerminalEndTurn; tool_use → "" ;
	//            a `[Request interrupted by user]` line → TerminalAborted.
	//   codex    event_msg: task_complete → TerminalEndTurn; turn_aborted → TerminalAborted.
	//   deepwork native: every assistant entry closes its exchange → TerminalEndTurn.
	Terminal string `json:"terminal,omitempty"`

	// InputKind classifies a USER turn. The projector must never GUESS whether a human
	// line opens a new round or steers the running one ("is a run currently open?" is
	// not a decidable contract — a runtime that dies mid-loop would silently swallow the
	// next independent request into the previous round). So each adapter states it, from
	// the runtime's own facts:
	//
	//   codex   `event_msg/task_started` opens a task → the message that drives it is an
	//           intent; a user_message arriving inside an already-started task is a steer.
	//           (Real rollout: task_started × 10, user_message × 16 → 10 intents, 6 steers.)
	//   claude  a user line while the model is still in a tool loop (no end_turn yet) is
	//           queued — the runtime records it as `queue-operation/enqueue` (72 in the
	//           real transcript). Yielded → the next human line is a new intent.
	//   system  runtime notifications (task-notification, interrupt markers) — never a round.
	InputKind string `json:"input_kind,omitempty"`
}

type WindowRequest struct {
	Before     *int64
	Limit      int
	Generation string
}

type WindowResult struct {
	Transcript  *Transcript
	Before      int64
	HasMore     bool
	Version     string
	Generation  string
	Reset       bool
	BytesParsed int64
}

type WindowSource interface {
	LoadTranscriptWindow(ctx context.Context, ref SessionRef, req WindowRequest) (*WindowResult, error)
}