sdk

type AIGoalSection struct {
	// Goal is the goal definition this part's actor loop ran — verbatim,
	// not converted to plain strings the way Report's fields are, since a
	// player needs the full Goal (task dependencies, constraints, budgets)
	// to render it, not just the outcome Report already summarises.
	Goal Goal `json:"goal"`

	// ActorID references the Run.Actors entry that ran this part's loop.
	ActorID string `json:"actorId"`

	// Events is every LoopEvent the loop recorded for this part, in the
	// loop's own order (Index-ascending, across every task the loop ran).
	Events []LoopEvent `json:"events"`

	// Observations is every Observation the loop retained, ordered
	// ascending by Sequence — not the raw map[int64]Observation the
	// runtime's loop returns, so this section's JSON stays chronologically
	// readable regardless of encoding/json's own (string-lexicographic, not
	// numeric) map-key ordering for an integer-keyed map.
	Observations []RetainedObservation `json:"observations"`

	// Report is this part's assembled campaign Report — see Report.
	Report Report `json:"report"`

	// Evidence is the DataStateEvidence any data-state assertions produced
	// during this part, in the order they were run. Optional: a part with
	// no data-state assertions attached carries none.
	Evidence []DataStateEvidence `json:"evidence,omitempty"`
}

type Action struct {
	Label string `json:"label"` // user-visible text (Telegram button text / WhatsApp reply title)
	ID    string `json:"id"`    // stable identifier (Telegram callback_data / WhatsApp reply id)
	URL   string `json:"url"`   // set for link actions
}

type ActionOutcome struct {
	Kind ActionOutcomeKind `json:"kind"`
	// Detail is a human-readable explanation, set for
	// ActionSkippedInvalid/ActionResolutionFailed (why), empty otherwise.
	Detail string `json:"detail"`
}

type ActionOutcomeKind string

type Actor struct {
	// ID is this Bundle's own stable identity for the actor — referenced by
	// Part's aiGoal.actorId and resolvable against a JournalEntry.FromID
	// through PlatformIdentities.
	ID string `json:"id"`

	// Type classifies this actor's origin — see ActorType.
	Type ActorType `json:"type"`

	// Name is an optional human-readable display name.
	Name string `json:"name,omitempty"`

	// PlatformIdentities maps a platform name (e.g. "telegram", matching
	// Run.Platform) to this actor's platform-native identity on that
	// platform. A map, not a single field, so a future actor active across
	// more than one platform needs no schema change — only a new key.
	PlatformIdentities map[string]PlatformIdentity `json:"platformIdentities,omitempty"`

	// Provider names the model/provider that proposed this actor's actions.
	// Only meaningful for ActorAIAgent and ActorReplay actors (a scripted or
	// human actor proposes nothing a "provider" describes); nil otherwise.
	Provider *ActorProvider `json:"provider,omitempty"`
}

type ActorProvider struct {
	// Name is the provider's short identifier (e.g. "anthropic").
	Name string `json:"name,omitempty"`

	// ModelIDs is the aggregated set of Usage.Model ids that actually
	// proposed an action for this actor during the run — see
	// AggregateModelIDs, the canonical way to compute it.
	ModelIDs []string `json:"modelIds,omitempty"`
}

type ActorType string

type AggregateUsage struct {
	InputTokens  int     `json:"inputTokens"`
	OutputTokens int     `json:"outputTokens"`
	Cost         float64 `json:"cost,omitempty"`
	// CallCount is the number of provider calls the campaign made — i.e.
	// the number of LoopEvents.
	CallCount int `json:"callCount"`
}

type Anchor struct {
	// ChatID names the Run.Chats entry this anchor points into.
	ChatID int64 `json:"chatId"`
	// EntryIndex is the index into that ChatJournal.Entries this anchor
	// points at.
	EntryIndex int `json:"entryIndex"`
	// MessageID optionally pins the logical message (JournalEntry.MessageID)
	// this anchor is about, when it is more specific than "this journal
	// entry" — e.g. an Annotation about a message that was later edited,
	// anchored to the message rather than to one particular edit.
	MessageID int `json:"messageId,omitempty"`
	// Version optionally pins the exact edit (JournalEntry.Version)
	// MessageID was at, so an Annotation about "this specific wording"
	// survives a later edit instead of silently retargeting to the
	// message's newest version.
	Version int `json:"version,omitempty"`
}

type Annotation struct {
	// ID is caller-supplied and only needs to be unique within its Run.
	ID string `json:"id"`
	// Anchor locates the annotated moment in the run's journal — see Anchor.
	Anchor Anchor `json:"anchor"`
	// Author optionally attributes this Annotation — see Author's own doc
	// comment (never auto-populated).
	Author *Author `json:"author,omitempty"`
	// CreatedAt is when this Annotation was authored, supplied by the
	// caller — see Metadata.CreatedAt's own doc comment on why this package
	// never stamps a time itself.
	CreatedAt time.Time `json:"createdAt"`
	// Text is the annotation's own comment body.
	Text string `json:"text"`
	// ReplyTo optionally names another Annotation.ID in this Run that this
	// one replies to, threading both into one conversation about a message.
	// Empty for a root Annotation.
	ReplyTo string `json:"replyTo,omitempty"`
}

type AttachmentPoint string

type Author struct {
	Name  string `json:"name,omitempty"`
	Email string `json:"email,omitempty"`
}

type AvailableAction struct {
	ID     string `json:"id"`     // opaque, stable Chatwright action identity
	Label  string `json:"label"`  // user-visible text
	SeenAt int64  `json:"seenAt"` // the Observation.Sequence this action was (re)issued at
}

type Bookmark struct {
	// ID is caller-supplied and only needs to be unique within its Run.
	ID string `json:"id"`
	// Title is the human-readable label a player shows for this marker.
	Title string `json:"title"`
	// Anchor locates the marker in the run's journal — see Anchor.
	Anchor Anchor `json:"anchor"`
}

type Budgets struct {
	// MaxSteps caps the number of steps the runtime's campaign state counts.
	// Zero means unlimited.
	MaxSteps int `json:"maxSteps"`

	// MaxDuration caps wall-clock time elapsed since the campaign started,
	// measured by the runtime's injected clock. Zero means unlimited.
	MaxDuration time.Duration `json:"maxDurationNanoseconds"`

	// MaxRepeatedFailures caps how many times a single task may fail before
	// the campaign stops. Zero means unlimited.
	MaxRepeatedFailures int `json:"maxRepeatedFailures"`

	// MaxCost optionally caps spend against the campaign (tokens, currency
	// or another caller-defined unit — whatever unit the runtime accrues).
	// Nil means cost is not budgeted.
	MaxCost *float64 `json:"maxCost"`
}

type Bundle struct {
	// Format is always FormatV1 for a Bundle this package produced. See Read.
	Format string `json:"format"`

	// Metadata carries this Bundle's caller-supplied provenance — see
	// Metadata.
	Metadata Metadata `json:"metadata"`

	// Runs is every run this Bundle carries, in the order the caller
	// assembled them. Today's writers always produce exactly one; the shape
	// accommodates a future multi-run file (e.g. several campaigns bundled
	// for one delivery) without a schema change.
	Runs []Run `json:"runs"`
}

type Change struct {
	Kind      ChangeKind   `json:"kind"`
	MessageID string       `json:"messageId"`
	Actor     MessageActor `json:"actor"`
	// PreviousVersion is set for ChangeMessageEdited: the message's Version
	// before this change.
	PreviousVersion int `json:"previousVersion"`
	// Version is the message's Version after this change (ChangeNewMessage,
	// ChangeMessageEdited) or its current, unchanged Version
	// (ChangeActionsChanged).
	Version int `json:"version"`
}

type ChangeKind string

type ChatBoundary struct {
	ChatID int64 `json:"chatId"`
	// FirstEntry is the index, into the matching ChatJournal.Entries, of
	// this Part's first entry for this chat.
	FirstEntry int `json:"firstEntry"`
	// EntryCount is how many consecutive entries, starting at FirstEntry,
	// belong to this Part.
	EntryCount int `json:"entryCount"`
}

type ChatJournal struct {
	ChatID  int64          `json:"chatId"`
	Entries []JournalEntry `json:"entries"`
}

type ChatRef struct {
	ChatID int64 `json:"chatId"`
}

type DataStateEvidence struct {
	// Name is the triggering assertion's stable identity, correlating this
	// evidence to the message, checkpoint or branch that attached it.
	Name string `json:"name"`
	// AttachmentPoint is where in the scenario this assertion ran.
	AttachmentPoint AttachmentPoint `json:"attachmentPoint"`
	// Holder is the resolved holder name the query ran against (even an
	// unresolved request records the name that was asked for).
	Holder string `json:"holder"`
	// Query is the concrete DTQL text executed.
	Query string `json:"query"`
	// Params is a detached copy of the query's named parameters.
	Params map[string]any `json:"params"`
	// Outcome is OutcomePassed or OutcomeFailed.
	Outcome Outcome `json:"outcome"`
	// FailureMessage is set when Outcome is OutcomeFailed: holder
	// resolution, query execution or the expectation's failure message.
	FailureMessage string `json:"failureMessage"`
	// TotalRows is how many rows the query returned before any preview
	// bound was applied.
	TotalRows int `json:"totalRows"`
	// ReturnedRows is how many rows are present in Preview.
	ReturnedRows int `json:"returnedRows"`
	// Truncated is true when Preview omits rows (TotalRows > ReturnedRows)
	// or drops fields from at least one previewed row.
	Truncated bool `json:"truncated"`
	// Preview is the bounded, redacted, normalised recordset. Redacted
	// fields are present with their value replaced by the runtime's
	// redaction placeholder rather than omitted, so evidence still declares
	// which fields exist.
	Preview []Row `json:"preview"`
	// RedactedFields lists the field names configured for redaction (the
	// declared policy), regardless of whether any previewed row contained
	// them.
	RedactedFields []string `json:"redactedFields"`
	// ExcludedFields lists the field names normalisation removed from the
	// comparison basis. They remain visible in Preview: exclusion only
	// means "not part of the assertion", never "hidden from evidence".
	ExcludedFields []string `json:"excludedFields"`
}

type Direction string

type Finding struct {
	Kind    FindingKind `json:"kind"`
	TaskID  string      `json:"taskId"`
	Summary string      `json:"summary"`

	Evidence FindingEvidence `json:"evidence"`

	// Confidence distinguishes how the Finding was derived: "mechanical"
	// for the deterministic rules the runtime's report assembly applies
	// itself, or a caller's own label (e.g. "dtql-verified") for
	// caller-supplied findings.
	Confidence string `json:"confidence,omitempty"`
}

type FindingEvidence struct {
	// ObservationSequences are Observation.Sequence values.
	ObservationSequences []int64 `json:"observationSequences,omitempty"`
	// LoopEventIndexes are LoopEvent.Index values.
	LoopEventIndexes []int `json:"loopEventIndexes,omitempty"`
}

type FindingKind string

type Freshness string

type Goal struct {
	ID          string   `json:"id"`
	Title       string   `json:"title"`
	Description string   `json:"description"`
	Tasks       []Task   `json:"tasks"`
	Constraints []string `json:"constraints"`
	Budgets     Budgets  `json:"budgets"`
}

type JournalBoundary struct {
	Chats []ChatBoundary `json:"chats"`
}

type JournalEntry struct {
	Direction    Direction        `json:"direction"`
	Kind         JournalEntryKind `json:"kind"`
	MessageID    int              `json:"messageId"`    // logical message identity, shared by inbound/outbound entries in this chat; 0 when Kind has no message identity of its own
	RefMessageID int              `json:"refMessageId"` // JournalEntryAction only: the message the action targeted
	Version      int              `json:"version"`      // JournalEntryMessage only: 0 = original send/inbound, N = the Nth edit
	Text         string           `json:"text"`
	Actions      [][]Action       `json:"actions"` // JournalEntryMessage only: actions attached to this entry, in platform row/col layout
	Method       string           `json:"method"`  // JournalEntryUncaptured only: the Bot API method name that was called
	At           time.Time        `json:"at"`

	// FromID is the platform-native identity of this entry's originator:
	// the Telegram user id of the client actor for a client-originated
	// entry, or the bot's own id for a bot-originated entry. It is 0 when
	// no identity is available (e.g. a pure method-call record with no
	// resolvable sender) — a platform never invents an identity it does not
	// actually know. This is what lets a run-bundle roster (see
	// Actor.PlatformIdentities) attribute every journal entry to whoever
	// produced it.
	FromID int64 `json:"fromId"`
}

type JournalEntryKind string

type LoopEvent struct {
	// Index is 0-based and monotonic across one loop's lifetime (not just
	// one task), so it is stable to reference from a Finding.
	Index int `json:"index"`
	// At is stamped from the loop's injected clock, never time.Now, so a
	// run's timeline is reproducible.
	At time.Time `json:"at"`
	// TaskID is the task this iteration was attempting.
	TaskID string `json:"taskId"`

	// ObservationSequence is the Observation.Sequence this iteration
	// observed before proposing — the same value a Finding's evidence links
	// back to.
	ObservationSequence int64 `json:"observationSequence"`

	Proposal Proposal `json:"proposal"`
	Usage    Usage    `json:"usage"`

	// Validation is the loop's validate-step outcome for Proposal. It is
	// only Checked for ProposeClick — the loop has nothing to validate
	// against an observation for a send-text, task-done or give-up proposal.
	Validation ValidationOutcome `json:"validation"`

	// Action is what actually happened when the loop tried to act on
	// Proposal (or why it did not).
	Action ActionOutcome `json:"action"`

	// ProposeError is set exactly when this iteration's call to the AI
	// provider's Propose failed: it carries the returned error's own
	// message (error.Error()), and Proposal, Usage, Validation and Action
	// are all their zero value — there was nothing to validate or act on.
	// Empty for every iteration that got as far as a Proposal, which is
	// most of them; this field exists so a failed Propose call still leaves
	// a LoopEvent behind (index, timestamp, task, the observation it was
	// attempting to act from) instead of vanishing from the record with
	// only a returned Go error nobody downstream of the loop ever sees
	// (github.com/chatwright/runtime-go issue #4).
	ProposeError string `json:"proposeError,omitempty"`
}

type MessageActor string

type Metadata struct {
	// CreatedAt is when this Bundle was assembled, supplied by the caller
	// (never time.Now internally — see Chatwright's broader injected-clock
	// convention) so assembling a Bundle is itself deterministic and
	// testable.
	CreatedAt time.Time `json:"createdAt"`

	// ChatwrightVersion is the sdk module's own resolved version — see
	// ModuleVersion — left empty when it cannot be determined (e.g. a
	// `go test` run inside this repository itself, which always reports
	// "(devel)"; see ModuleVersion's doc comment). "If available" is
	// load-bearing: a Bundle is still valid and complete without it.
	ChatwrightVersion string `json:"chatwrightVersion,omitempty"`

	// Author optionally attributes this Bundle to whoever assembled it.
	// Never populated automatically from git config, the OS user or any
	// other ambient environment — a caller must supply it explicitly, or
	// leave it nil. Bundles get emailed and committed to public
	// repositories, so silently harvesting an identity into one is not this
	// package's call to make.
	Author *Author `json:"author,omitempty"`
}

type Observation struct {
	// Sequence is monotonic per engine, starting at 1.
	Sequence int64 `json:"sequence"`
	// PreviousSequence is the Sequence of the Observation this one
	// supersedes; 0 for an engine's first Observation.
	PreviousSequence int64   `json:"previousSequence"`
	Chat             ChatRef `json:"chat"`
	// Messages is chronological, oldest to newest: one entry per currently
	// visible logical message, at its current (possibly-edited) version.
	Messages []VisibleMessage `json:"messages"`
	// Changes is empty for an engine's first Observation; otherwise the
	// explicit differences since PreviousSequence.
	Changes []Change `json:"changes"`
}

type Outcome string

type Part struct {
	// ID is caller-supplied and only needs to be unique within its Run.
	ID string `json:"id"`

	// Title is an optional human-readable label (e.g. "Shopping-list
	// exploration") for a player to show as a chapter heading.
	Title string `json:"title,omitempty"`

	// Kind discriminates which kind-scoped section below is populated — see
	// PartKind.
	Kind PartKind `json:"kind"`

	// JournalBoundary slices the run-level journal (Run.Chats) into the
	// entries this Part covers — see JournalBoundary.
	JournalBoundary JournalBoundary `json:"journalBoundary"`

	// AIGoal is populated when Kind is PartKindAIGoal, nil otherwise — see
	// AIGoalSection. Read returns ErrMissingAIGoalSection for an
	// PartKindAIGoal part with this unset, rather than silently returning a
	// half-decoded Part.
	AIGoal *AIGoalSection `json:"aiGoal,omitempty"`
}

type PartKind string

type PlatformIdentity struct {
	UserID    int64  `json:"userId"`
	Username  string `json:"username,omitempty"`
	FirstName string `json:"firstName,omitempty"`
}

type Proposal struct {
	Kind ProposalKind `json:"kind"`

	// Text is set for ProposeSendText: the text to send as the user.
	Text string `json:"text"`

	// ActionID is set for ProposeClick: an AvailableAction.ID drawn from the
	// observation the proposal was made against.
	ActionID string `json:"actionId"`
	// ObservationSequence is the Observation.Sequence the proposal was
	// chosen from. Required for ProposeClick (the runtime validates the
	// click against it); ignored otherwise.
	ObservationSequence int64 `json:"observationSequence"`

	// Rationale is free text explaining the choice — never private
	// chain-of-thought, just enough for a developer or the campaign report
	// to understand why the actor did this.
	Rationale string `json:"rationale"`
}

type ProposalKind string

type Report struct {
	// SchemaVersion is always ReportSchemaVersion for a Report the runtime
	// produced; a consumer reading an older or newer value should not
	// assume today's field meanings.
	SchemaVersion int `json:"schemaVersion"`

	GoalID    string `json:"goalId"`
	GoalTitle string `json:"goalTitle"`

	// StopReason is why the campaign stopped (e.g. "goal-complete",
	// "budget-steps"), carried as a plain string so Report never imports
	// the runtime's Go type into its own JSON contract.
	StopReason string        `json:"stopReason"`
	Steps      int           `json:"steps"`
	Cost       float64       `json:"cost,omitempty"`
	Elapsed    time.Duration `json:"elapsedNanoseconds"`

	Tasks    []TaskOutcome `json:"tasks"`
	Findings []Finding     `json:"findings"`

	Usage AggregateUsage `json:"usage"`
}

type RetainedObservation struct {
	Sequence    int64       `json:"sequence"`
	Observation Observation `json:"observation"`
}

type Row map[string]any

type Run struct {
	// ID is caller-supplied and only needs to be unique within this Bundle.
	ID string `json:"id"`

	// Platform is the platform name this run drove (e.g. "telegram").
	Platform string `json:"platform"`

	// EndpointProfile is this run's declared endpoint profile (the standard
	// repository's decision 0008; docs/glossary.md's "endpoint profile"
	// entry) — e.g. EndpointProfilePlatformEmulated. Evidence is never
	// interchangeable across profiles, so a player must always have this
	// label, never infer it.
	EndpointProfile string `json:"endpointProfile"`

	// Actors is the roster of everyone who took part in this run — every
	// AI agent, human, scripted or replay actor that acted, plus the
	// bot-under-test itself — so a player can attribute every journal entry
	// to whoever produced it (see JournalEntry.FromID and Actor's own doc
	// comment).
	Actors []Actor `json:"actors"`

	// Chats is the run's continuous, per-chat journal: one entry per
	// distinct chat ID, in the order the caller assembled them, each
	// carrying that chat's entire JournalEntry history for the whole run —
	// never re-split or duplicated per Part. A Part slices this journal by
	// reference (see Part.JournalBoundary) rather than embedding its own
	// copy.
	Chats []ChatJournal `json:"chats"`

	// Parts is this run's ordered sequence of passages — see Part. Today's
	// writers always produce exactly one ai-goal Part; the ordered-list
	// shape is what a future hybrid run (deterministic passages interleaved
	// with ai-goal exploration) composes without any schema change.
	Parts []Part `json:"parts"`

	// Bookmarks is an optional list of manual fast-forward markers a player
	// can offer alongside this run's own derived markers — part boundaries,
	// task completions, findings and the like need no schema entry here,
	// since a player derives them directly from Parts/AIGoalSection; a
	// Bookmark is only for a marker no derivation already produces. Today's
	// writers emit none unless the caller supplies them.
	Bookmarks []Bookmark `json:"bookmarks,omitempty"`

	// Annotations is an optional list of comments attached to moments in
	// this run's conversation — see Annotation. Today's writers emit none
	// unless the caller supplies them.
	Annotations []Annotation `json:"annotations,omitempty"`
}

type Task struct {
	ID              string   `json:"id"`
	Title           string   `json:"title"`
	DependsOn       []string `json:"dependsOn"`
	SuccessCriteria string   `json:"successCriteria"`
	Milestones      []string `json:"milestones"`
}

type TaskOutcome struct {
	TaskID          string `json:"taskId"`
	Title           string `json:"title,omitempty"`
	SuccessCriteria string `json:"successCriteria,omitempty"`
	// Status is the task's lifecycle status (e.g. "pending", "completed"),
	// carried as a plain string for the same reason as Report.StopReason.
	Status string `json:"status"`
	// Attempted is true once at least one LoopEvent was recorded for this
	// task.
	Attempted bool `json:"attempted"`
	// FailureCount is how many times the campaign recorded a failure for
	// this task.
	FailureCount int `json:"failureCount"`
}

type Usage struct {
	Model        string        `json:"model"`
	InputTokens  int           `json:"inputTokens"`
	OutputTokens int           `json:"outputTokens"`
	Latency      time.Duration `json:"latencyNanoseconds"`
	Cost         *float64      `json:"cost,omitempty"`
}

type ValidationOutcome struct {
	// Checked is false for proposal kinds validation does not apply to
	// (ProposeSendText, ProposeTaskDone, ProposeGiveUp); Freshness and
	// Reason are meaningless when Checked is false.
	Checked   bool      `json:"checked"`
	Freshness Freshness `json:"freshness"`
	Reason    string    `json:"reason"`
}

type VisibleMessage struct {
	ID      string            `json:"id"`      // stable synthetic Chatwright identity for this logical message, e.g. "msg7"
	Version int               `json:"version"` // monotonic version of this logical message; 0 for the original send
	Edited  bool              `json:"edited"`  // true once Version has advanced past 0
	Actor   MessageActor      `json:"actor"`   // who produced the message
	Text    string            `json:"text"`
	Actions []AvailableAction `json:"actions"` // interactions currently attached to this message
}