spec

type AgentConfig struct {

	// Description is the agent's role summary - REQUIRED for
	// workflow-declared agents (parsed from `agents:` block in YAML).
	// ValidateWorkflow returns *ValidationError ("agent X missing required
	// field 'description'") when empty. Programmatic per-call
	// invocations through Orchestrator.RunAgent / RunAgentAsync may
	// leave it empty since they go through the AgentRunner.Run path
	// which doesn't consult Description.
	Description     string         `json:"description,omitempty" yaml:"description,omitempty"`
	Prompt          string         `json:"prompt,omitempty" yaml:"prompt,omitempty"`
	Model           string         `json:"model,omitempty" yaml:"model,omitempty"`
	Tools           []string       `json:"tools,omitempty" yaml:"tools,omitempty"`
	DisallowedTools []string       `json:"disallowedTools,omitempty" yaml:"disallowedTools,omitempty"`
	MaxTurns        int            `json:"maxTurns,omitempty" yaml:"maxTurns,omitempty"`
	Temperature     *float64       `json:"temperature,omitempty" yaml:"temperature,omitempty"`
	TopP            *float64       `json:"topP,omitempty" yaml:"topP,omitempty"`
	ResultSchema    map[string]any `json:"resultSchema,omitempty" yaml:"resultSchema,omitempty"`

	// Name is an optional human-readable identifier for the agent
	// (e.g. "research", "reviewer"). Advisory only - used by
	// observability paths, not by the tool loop.
	Name string `json:"-" yaml:"-"`

	// CallTools, when non-empty, overrides the Orchestrator-level
	// tool set for this single call. Carries the resolved
	// []goai.Tool values (with Execute closures), not string names -
	// consumers build it from a restricted subset of their tool
	// registry. A typical consumer's task tool sets this to a
	// restricted subagent tool set so a subagent receives a read-only
	// tool slice while the primary agent retains its full toolbox.
	// When nil, RunAgent / RunAgentAsync falls back to the tools
	// registered via WithTools.
	CallTools []goai.Tool `json:"-" yaml:"-"`

	// ProgressSink, when non-nil, overrides the Orchestrator-level
	// sink for this single call. Consumers wire a per-call progress
	// bridge here so subagent events land in the primary agent's
	// inbox instead of the session's global sink.
	ProgressSink types.ProgressSink `json:"-" yaml:"-"`

	// SubagentToolSet is a logical label for the restricted tool
	// set associated with this call (e.g. "read-only", "full").
	// Purely advisory - used for logging and policy reporting. Does
	// not itself modify the tool slice; CallTools carries the
	// actual tool values.
	SubagentToolSet string `json:"-" yaml:"-"`

	// Attachments carries multimodal `provider.Part` values (text
	// snippets, image references, PDF byte payloads, etc.) the agent
	// loop concatenates onto the user message at the start of the
	// run. Forwarded verbatim to `AgentRunner.Run`'s variadic
	// attachments slot. nil / empty → text-only conversation. Used
	// by chat consumers passing files alongside the prompt and by
	// e2e tests verifying the multimodal pathway end-to-end.
	Attachments []provider.Part `json:"-" yaml:"-"`

	// SessionID identifies the consumer session that owns this call
	// (e.g. the consumer's chat session). The Orchestrator's in-memory
	// handle registry partitions active RunAgentAsync handles by
	// this key so ListAgentHandles can return only the handles
	// belonging to one session. Empty string is a valid
	// single-session key ("" bucket); consumers must populate it
	// for multi-session deployments.
	SessionID string `json:"-" yaml:"-"`

	// InitialMessages pre-loads a saved conversation transcript that
	// the agent loop prepends BEFORE the new user prompt. Empty / nil
	// → the agent starts cold from `Prompt` alone. Non-empty → the
	// agent resumes with the full prior context (resurrection: a
	// consumer respawns a finished agent with its loaded transcript
	// plus a new user message). Forwarded verbatim to the AgentRunner
	// via WithRunnerInitialMessages on the RunAgent / RunAgentAsync
	// path. Per-call only; never read from workflow YAML.
	InitialMessages []provider.Message `json:"-" yaml:"-"`
}

type ApprovalHandler interface {
	ApprovePlan(ctx context.Context, plan *Workflow) (bool, error)
}

type Duration time.Duration

type FailureStrategy string

type Loop struct {
	MaxIterations  *int     `json:"maxIterations,omitempty" yaml:"maxIterations,omitempty"`
	Until          *string  `json:"until,omitempty" yaml:"until,omitempty"`
	UntilAgent     string   `json:"untilAgent,omitempty" yaml:"untilAgent,omitempty"`
	ForEach        any      `json:"forEach,omitempty" yaml:"forEach,omitempty"`
	MaxConcurrency int      `json:"maxConcurrency,omitempty" yaml:"maxConcurrency,omitempty"`
	Delay          Duration `json:"delay,omitempty" yaml:"delay,omitempty"`
	Steps          []Step   `json:"steps,omitempty" yaml:"steps,omitempty"`
	// OutputMode controls how the loop step's returned StepResult.Content is
	// constructed for dependent steps to consume.
	// "" or "last" - (default, backward compat) Content = the LAST inner
	// step of the FINAL iteration only. Right for refine-
	// style loops where each iteration supersedes the prior
	// and downstream consumers want the polished output.
	// "cumulative" - Content = full iteration history (every iteration's
	// inner-step output concatenated, plus judge feedback
	// for untilAgent loops). Right for aggregator-style
	// loops where downstream consumers (e.g. a verdict
	// summarizer) need to see ALL rounds, not just the
	// final one.
	OutputMode LoopOutputMode `json:"outputMode,omitempty" yaml:"outputMode,omitempty"`
}

type LoopOutputMode string

type ModelResolver func(modelID string) (provider.LanguageModel, error)

type OutputTransformer interface {
	// TransformStepOutput transforms a completed step's content and result before
	// they are injected into a dependent step's prompt. stepID identifies the source
	// step, targetModel is the model that will consume the output.
	// Return the (possibly shortened) content and result.
	TransformStepOutput(stepID string, content string, result map[string]any, targetModel string) (string, map[string]any)
}

type Run struct {
	ID       string
	Workflow *Workflow
	Status   WorkflowStatus
	Steps    map[string]*StepResult
}

type RunStore interface {
	SaveRun(ctx context.Context, run *Run) error
	LoadRun(ctx context.Context, id string) (*Run, error)
}

type SchedulerStrategy string

type SharedMemoryStore interface {
	SaveSharedMemory(ctx context.Context, runID string, entries map[string]string) error
	LoadSharedMemory(ctx context.Context, runID string) (map[string]string, error)
}

type Step struct {
	ID           string   `json:"id" yaml:"id"`
	Agent        string   `json:"agent,omitempty" yaml:"agent,omitempty"`
	Instructions string   `json:"instructions,omitempty" yaml:"instructions,omitempty"`
	DependsOn    []string `json:"dependsOn,omitempty" yaml:"dependsOn,omitempty"`
	ContextFiles []string `json:"contextFiles,omitempty" yaml:"contextFiles,omitempty"`
	Model        string   `json:"model,omitempty" yaml:"model,omitempty"`
	Timeout      Duration `json:"timeout,omitempty" yaml:"timeout,omitempty"`
	Retries      int      `json:"retries,omitempty" yaml:"retries,omitempty"`
	MaxRetries   *int     `json:"maxRetries,omitempty" yaml:"maxRetries,omitempty"`
	Condition    *string  `json:"condition,omitempty" yaml:"condition,omitempty"`
	Include      string   `json:"include,omitempty" yaml:"include,omitempty"`
	Loop         *Loop    `json:"loop,omitempty" yaml:"loop,omitempty"`
	// Tool, when non-empty, skips LLM execution and invokes the named registered
	// tool directly. Input fields are provided via ToolInput. Values starting with
	// $ are evaluated as CEL expressions (returning string) using prior step outputs;
	// a literal leading $ is written as $$. Mutually exclusive with Agent,
	// Instructions, Loop, and Include.
	Tool      string         `json:"tool,omitempty" yaml:"tool,omitempty"`
	ToolInput map[string]any `json:"toolInput,omitempty" yaml:"toolInput,omitempty"`
}

type StepIsolation interface {
	Setup(ctx context.Context, runID, stepID string) (workDir string, err error)
	Cleanup(ctx context.Context, runID, stepID string) error
}

type StepResult struct {
	ID       string
	Status   StepStatus
	Content  string
	Result   map[string]any
	Tokens   provider.Usage
	Duration time.Duration
	Error    error
	// PreserveContent, when true, signals to AssemblePrompt that this
	// result's Content was intentionally aggregated (e.g. by a loop step
	// in outputMode=cumulative) and must NOT be subject to the per-dep
	// 16KB truncation cap (maxDepContentBytes). The overall maxPromptBytes
	// cap (120KB) still applies as the final safety net. Default false
	// preserves the standard truncation behavior for ordinary step outputs.
	PreserveContent bool
}

type StepResultStore interface {
	SaveStepResult(ctx context.Context, runID, stepID string, result *StepResult) error
	LoadStepResult(ctx context.Context, runID, stepID string) (*StepResult, error)
}

type StepStatus string

type Storage interface {
	RunStore
	StepResultStore
	SharedMemoryStore
}

type Tracer interface {
	StartSpan(ctx context.Context, name string, attrs map[string]string) context.Context
	EndSpan(ctx context.Context, err error)
}

type Workflow struct {
	// Name is the workflow identifier - REQUIRED. ValidateWorkflow returns
	// *MissingNameError ("workflow name is required") when empty. Used
	// by trace spans, log entries, and the human-readable banner.
	Name string `json:"name" yaml:"name"`
	// Description is optional human prose for the workflow.
	Description string                 `json:"description,omitempty" yaml:"description,omitempty"`
	Version     int                    `json:"version,omitempty" yaml:"version,omitempty"`
	Agents      map[string]AgentConfig `json:"agents,omitempty" yaml:"agents,omitempty"`
	Includes    map[string]string      `json:"includes,omitempty" yaml:"includes,omitempty"`
	// Steps is the ordered list of work units - REQUIRED, must be
	// non-empty. ValidateWorkflow returns *NoStepsError when zero-length.
	Steps   []Step          `json:"steps" yaml:"steps"`
	Options WorkflowOptions `json:"options,omitempty" yaml:"options,omitempty"`
	// BaseDir is the directory containing the workflow file, used for resolving
	// relative paths in contextFiles. Set by LoadWorkflow; empty for programmatic use.
	BaseDir string `json:"-" yaml:"-"`
}

type WorkflowOptions struct {
	MaxConcurrency int               `json:"maxConcurrency,omitempty" yaml:"maxConcurrency,omitempty"`
	MaxRetries     *int              `json:"maxRetries,omitempty" yaml:"maxRetries,omitempty"`
	OnStepFailure  FailureStrategy   `json:"onStepFailure,omitempty" yaml:"onStepFailure,omitempty"`
	Timeout        Duration          `json:"timeout,omitempty" yaml:"timeout,omitempty"`
	StepTimeout    Duration          `json:"stepTimeout,omitempty" yaml:"stepTimeout,omitempty"`
	Isolation      string            `json:"isolation,omitempty" yaml:"isolation,omitempty"`
	Scheduler      SchedulerStrategy `json:"scheduler,omitempty" yaml:"scheduler,omitempty"`
}

type WorkflowResult struct {
	RunID  string
	Status WorkflowStatus
	// Steps maps step ID to its result pointer. Held for backward
	// compatibility - new code should use Result(stepID) to obtain a
	// value copy and avoid pointer escape / representation coupling.
	Steps    map[string]*StepResult
	Duration time.Duration
	Tokens   provider.Usage
	// Summary is a human-readable summary produced by the coordinator
	// runner's finalize tool. Empty when no coord is installed or
	// the coord did not call finalize.
	Summary string
}

type WorkflowStatus string