scenario

type Bot struct {
	ID   string `json:"id"`
	Name string `json:"name"`

	// Transport is "http" or "iframe" — required with URL, forbidden with
	// ExampleBot (the runtime wires its own example however it likes, and
	// declares no transport in the document).
	Transport string `json:"transport,omitempty"`
	// Delivery is "webhook" or "polling" — http transport only.
	Delivery string `json:"delivery,omitempty"`
	// URL is the bot's webhook URL (http+webhook) or iframe src. Required
	// for iframe and for http+webhook; forbidden for http+polling.
	URL string `json:"url,omitempty"`
	// Headers optionally carries request headers for webhook delivery; each
	// value MUST be a secret reference — see SecretRef.
	Headers map[string]SecretRef `json:"headers,omitempty"`
	// ExampleBot names a bot the runtime itself ships (e.g. "greetbot").
	// Not an extension point — see ExampleBotRegistry.
	ExampleBot string `json:"exampleBot,omitempty"`
}

type Budgets struct {
	MaxSteps           int      `json:"maxSteps,omitempty"`
	MaxDurationSeconds int      `json:"maxDurationSeconds,omitempty"`
	MaxCost            *float64 `json:"maxCost,omitempty"`
}

type BuildOptions struct {
	// Now supplies the built run's clock — see run.Environment.Now. Nil
	// uses time.Now.
	Now func() time.Time
	// Secrets resolves a declared secret's value — see SecretResolver. Nil
	// uses EnvOnlyResolver{}; a document declaring no secrets never
	// consults it either way.
	Secrets SecretResolver
	// ExampleBots is the registry Build boots a Bot.ExampleBot from. Nil
	// uses DefaultExampleBots().
	ExampleBots ExampleBotRegistry
	// BindAddr, when set, binds the emulator to this exact address
	// (telegram.NewEmulatorAt) instead of a random local port. Needed for
	// "http"+"polling" delivery: an already-running external bot must be
	// pre-configured with the emulator's address before Build even runs —
	// see the README's "the operator points the bot's Bot API base URL at
	// the emulator". Ignored for an exampleBot document (the README: "there
	// is no authorable URL").
	BindAddr string
	// HTTPClient is the client the emulator uses to push webhook updates,
	// for "http"+"webhook" delivery. Nil uses http.DefaultClient. Ignored
	// otherwise.
	HTTPClient *http.Client
}

type Built struct {
	Run        run.Run
	Actors     []sdk.Actor
	ChatIDs    map[string]int64 // doc-local chat id -> platform chat id
	VerifySpec *VerifySpec
	Fidelity   ResolvedFidelity
	Close      func()
}

type CaseDecl struct {
	Name   string                     `json:"name"`
	Inputs map[string]json.RawMessage `json:"inputs,omitempty"`
}

type Cast struct {
	ID               string           `json:"id"`
	Type             string           `json:"type"`
	Name             string           `json:"name"`
	PlatformIdentity PlatformIdentity `json:"platformIdentity"`
	// Provider is set for an "ai-agent" cast member; nil for a "human" or
	// "scripted"/"replay" one (v1's document format has no way to author a
	// scripted actor — see the README's "scripted is deliberately not
	// expressible").
	Provider *Provider `json:"provider,omitempty"`
}

type Ceiling struct {
	MaxSteps           int      `json:"maxSteps,omitempty"`
	MaxCost            *float64 `json:"maxCost,omitempty"`
	MaxDurationSeconds int      `json:"maxDurationSeconds,omitempty"`
}

type Chat struct {
	ID             string `json:"id"`
	PlatformChatID int64  `json:"platformChatId"`
}

type Condition struct {
	Field  string          `json:"field"`
	Op     string          `json:"op"`
	Value  json.RawMessage `json:"value"`
	Negate bool            `json:"negate,omitempty"`
}

type Document struct {
	Format        string `json:"format"`
	SchemaVersion int    `json:"schemaVersion"`

	ID      string `json:"id"`
	Version string `json:"version"`
	Title   string `json:"title"`

	Description string   `json:"description,omitempty"`
	Requires    []string `json:"requires,omitempty"`

	Fidelity Fidelity `json:"fidelity"`
	Platform string   `json:"platform"`
	Chats    []Chat   `json:"chats"`
	Bot      Bot      `json:"bot"`
	Cast     []Cast   `json:"cast"`

	Secrets []Secret `json:"secrets,omitempty"`

	// Inputs and Cases are declared, but their shape beyond "a named input"
	// and "a named binding of inputs" is not pinned down by the format's
	// worked example or any acceptance criterion — see InputDecl and
	// CaseDecl's own doc comments. Neither is consulted by Build: a
	// document executed directly (no manifest) uses no case and no input
	// binding.
	Inputs []InputDecl `json:"inputs,omitempty"`
	Cases  []CaseDecl  `json:"cases,omitempty"`

	Parts []Part `json:"parts"`

	Ceiling *Ceiling `json:"ceiling,omitempty"`
	Verify  *Verify  `json:"verify,omitempty"`

	Verifies []string `json:"verifies,omitempty"`

	// SourceURL is this Document's canonical source identity — e.g.
	// "file:///abs/path/to/doc.json" for a FileScenarioProvider. Empty for
	// a Document built directly from Parse without going through a
	// ScenarioProvider (e.g. in a unit test).
	SourceURL string `json:"-"`
	// BaseDir is the directory document-relative references (a cassette
	// path today) resolve against — the same directory SourceURL names,
	// for a file-backed Document.
	BaseDir string `json:"-"`
}

type EnvOnlyResolver struct {
	// Lookup overrides how an env var is read — defaults to os.LookupEnv.
	// Tests substitute a fake here so a resolver test never actually reads
	// the process environment.
	Lookup func(varName string) (string, bool)
}

type ExampleBotFactory func() (*ExampleBotSession, error)

type ExampleBotRegistry map[string]ExampleBotFactory

type ExampleBotSession struct {
	Emulator *telegram.Emulator
	Close    func()
}

type Fidelity struct {
	EndpointProfile string `json:"endpointProfile"`
	Environment     string `json:"environment,omitempty"`
	DataSensitivity string `json:"dataSensitivity,omitempty"`
	RedactionPolicy string `json:"redactionPolicy,omitempty"`
}

type FileScenarioProvider struct {
	// Root is prepended to a relative ref. Empty resolves a relative ref
	// against the process's current working directory (os.ReadFile's own
	// behaviour).
	Root string
}

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

type InputDecl struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Default     json.RawMessage `json:"default,omitempty"`
}

type Issue struct {
	// Code is a short, stable, machine-readable rule id, e.g.
	// "inline-secret", "unsupported-capability", "ai-goal-budgets-required".
	Code string `json:"code"`
	// Pointer is an RFC 6901 JSON pointer into the document (e.g.
	// "/cast/0/provider/apiKey"), or "" for a document-level issue with no
	// single location.
	Pointer  string   `json:"pointer"`
	Message  string   `json:"message"`
	Severity Severity `json:"severity"`
}

type JournalExpectation struct {
	ID          string      `json:"id"`
	UnmetDetail string      `json:"unmetDetail"`
	All         []Condition `json:"all"`
}

type LoopConfig struct {
	HistoryWindow         int   `json:"historyWindow,omitempty"`
	NonProgressLimit      int   `json:"nonProgressLimit,omitempty"`
	ActWaitTimeoutSeconds int   `json:"actWaitTimeoutSeconds,omitempty"`
	RetainObservations    *bool `json:"retainObservations,omitempty"`
	OvershootProbe        *bool `json:"overshootProbe,omitempty"`
}

type Part struct {
	ID            string `json:"id"`
	Kind          string `json:"kind"`
	Title         string `json:"title,omitempty"`
	Chat          string `json:"chat"`
	ActorID       string `json:"actorId"`
	FailurePolicy string `json:"failurePolicy,omitempty"`

	// Goal is set for kind:"ai-goal".
	Goal *Goal `json:"goal,omitempty"`
	// Loop optionally overrides the actor.Config tunables — see LoopConfig.
	Loop *LoopConfig `json:"loop,omitempty"`

	// Steps is reserved for kind:"deterministic" (action matchers — not
	// built; see the README's "Reserved for action matchers" section). Its
	// mere presence is never inspected beyond "this document declares a
	// deterministic part", which Validate always rejects in v1.
	Steps json.RawMessage `json:"steps,omitempty"`
}

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

type Provider struct {
	Kind string `json:"kind"`

	// Model-kind fields.
	ProviderID string     `json:"providerId,omitempty"`
	Model      string     `json:"model,omitempty"`
	BaseURL    string     `json:"baseUrl,omitempty"`
	APIKey     *SecretRef `json:"apiKey,omitempty"`

	// Cassette-kind fields.
	Mode     string    `json:"mode,omitempty"`
	Cassette string    `json:"cassette,omitempty"`
	Wraps    *Provider `json:"wraps,omitempty"` // mode:"record" only, a model provider
}

type RejectionError struct {
	Report Report
}

type Report struct {
	Issues []Issue `json:"issues"`
}

type ResolvedFidelity struct {
	EndpointProfile string
	// Environment is doc.Fidelity.Environment when declared; otherwise the
	// configured host map (localHostEnvironments, the only one this
	// runtime ships) when the bot's own host is unambiguous; otherwise
	// EnvironmentUnknown — never guessed beyond that.
	Environment string
	// DataSensitivity is doc.Fidelity.DataSensitivity when declared;
	// otherwise DataSensitivityRealSubject when Environment is
	// EnvironmentProduction; otherwise DataSensitivitySynthetic.
	DataSensitivity string
}

type ScenarioProvider interface {
	// Load resolves ref, then parses and validates the result exactly as
	// Parse does — see Parse's own doc comment for what "resolves" does
	// and does not do (reading ref's bytes is the only I/O Load performs;
	// nothing about the document's own content — a secret, an example bot,
	// a cassette file — is touched). A Report with at least one
	// SeverityError Issue means Load returns a non-nil error and a nil
	// Document.
	Load(ctx context.Context, ref string) (*Document, Report, error)
}

type Secret struct {
	Name string       `json:"name"`
	From SecretSource `json:"from"`
}

type SecretRef struct {
	Name string `json:"secretRef"`
}

type SecretResolver interface {
	ResolveEnv(varName string) (string, error)
	ResolveCredential(credentialName string) (string, error)
}

type SecretSource struct {
	Env        string `json:"env,omitempty"`
	Credential string `json:"credential,omitempty"`
}

type Severity string

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

type Verify struct {
	Chat      string               `json:"chat"`
	MetDetail string               `json:"metDetail"`
	Journal   []JournalExpectation `json:"journal"`
}

type VerifyResult struct {
	Verified bool
	Detail   string
}

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