runtime

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

type AgentClient interface {
	// Run starts one sessionful workflow and blocks until completion.
	//
	// Run is request/response oriented: it is equivalent to Start followed by
	// handle.Wait on the returned workflow handle.
	Run(ctx context.Context, sessionID string, messages []*model.Message, opts ...RunOption) (*RunOutput, error)

	// Start starts one sessionful workflow and returns immediately with a
	// workflow handle for asynchronous coordination.
	//
	// Callers use the handle to wait, signal, or cancel. Start does not block
	// on workflow completion.
	Start(ctx context.Context, sessionID string, messages []*model.Message, opts ...RunOption) (engine.WorkflowHandle, error)

	// OneShotRun starts one sessionless workflow and blocks until completion.
	//
	// One-shot runs do not participate in session lifecycle and do not emit
	// session-scoped stream events. They still append canonical lifecycle and
	// prompt/tool events to the run log.
	OneShotRun(ctx context.Context, messages []*model.Message, opts ...RunOption) (*RunOutput, error)
}

type AgentRegistration struct {
	// ID is the unique agent identifier (service.agent).
	ID agent.Ident
	// Planner is the concrete planner implementation for the agent.
	Planner planner.Planner
	// Workflow describes the durable workflow registered with the engine.
	Workflow engine.WorkflowDefinition
	// Toolsets enumerates tool registrations exposed by this agent package.
	Toolsets []ToolsetRegistration
	// PlanActivityName names the activity used for PlanStart.
	PlanActivityName string
	// PlanActivityOptions describes retry/timeout behavior for the PlanStart activity.
	PlanActivityOptions engine.ActivityOptions
	// ResumeActivityName names the activity used for PlanResume.
	ResumeActivityName string
	// ResumeActivityOptions describes retry/timeout behavior for the PlanResume activity.
	ResumeActivityOptions engine.ActivityOptions
	// ExecuteToolActivity is the logical name of the registered ExecuteTool activity.
	ExecuteToolActivity string
	// ExecuteToolActivityOptions describes retry/timeout/queue for the ExecuteTool activity.
	// When set, these options are applied to all service-backed tool activities
	// scheduled by this agent. Agent-as-tool executions run as child workflows.
	ExecuteToolActivityOptions engine.ActivityOptions
	// Specs provides JSON codecs for every tool declared in the agent design.
	Specs []tools.ToolSpec
	// Policy configures caps/time budget/interrupt settings for the agent.
	Policy RunPolicy
}

type AgentRoute struct {
	// ID is the canonical agent identifier.
	// It must match the identifier used by worker-side registration.
	ID agent.Ident

	// WorkflowName is the engine-registered workflow definition name.
	// It must match the workflow name workers register with the engine.
	WorkflowName string

	// DefaultTaskQueue is the default queue workers use for this agent.
	// Per-run overrides may replace this queue via WithTaskQueue.
	DefaultTaskQueue string
}

type AgentToolConfig struct {
	AgentID             agent.Ident
	Route               AgentRoute
	PlanActivityName    string
	ResumeActivityName  string
	ExecuteToolActivity string
	SystemPrompt        string
	AgentToolContent
	PreChildValidator AgentToolValidator
	Name              string
	Description       string
	TaskQueue         string
	Aliases           map[tools.Ident]tools.Ident
}

type AgentToolContent struct {
	Templates   map[tools.Ident]*template.Template
	Texts       map[tools.Ident]string
	PromptSpecs map[tools.Ident]prompt.Ident
	Prompt      PromptBuilder
}

type AgentToolOption func(*AgentToolConfig)

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

type AgentToolValidationInput struct {
	Call      *planner.ToolRequest
	Payload   any
	Messages  []*model.Message
	ParentRun *run.Context
}

type AgentToolValidator func(ctx context.Context, input *AgentToolValidationInput) *AgentToolValidationError

type AggregationChild struct {
	Tool   tools.Ident `json:"tool"`
	Status string      `json:"status"`
	Result any         `json:"result,omitempty"`
	Error  string      `json:"error,omitempty"`
}

type AggregationSummary struct {
	Method     tools.Ident        `json:"method"`
	ToolCallID string             `json:"tool_call_id,omitempty"`
	Payload    any                `json:"payload,omitempty"`
	Children   []AggregationChild `json:"children"`
}

type BedrockConfig struct {
	DefaultModel   string
	HighModel      string
	SmallModel     string
	MaxTokens      int
	ThinkingBudget int
	Temperature    float32
}

type CachePolicy struct {
	// AfterSystem places a checkpoint after all system messages.
	AfterSystem bool

	// AfterTools places a checkpoint after tool definitions. Not all
	// providers support tool-level checkpoints (e.g., Nova does not).
	AfterTools bool
}

type CompressOption func(*compressConfig)

type HintOverrideFunc func(ctx context.Context, tool tools.Ident, payload any) (hint string, ok bool)

type HistoryPolicy func(ctx context.Context, msgs []*model.Message) ([]*model.Message, error)

type HookActivityInput = api.HookActivityInput

type MissingFieldsAction string

type OneShotRunInput struct {
	// AgentID identifies the logical agent identity for hook and run-log events.
	AgentID agent.Ident

	// RunID is the durable run identifier used by run-log storage.
	RunID string

	// TurnID identifies the logical turn for event grouping.
	TurnID string

	// Labels attaches optional metadata to the run context.
	Labels map[string]string

	// Metadata carries caller-provided structured metadata.
	Metadata map[string]any
}

type Options struct {
	// Engine is the workflow backend adapter (Temporal by default).
	Engine engine.Engine
	// MemoryStore persists run transcripts and annotations.
	MemoryStore memory.Store
	// PromptStore resolves scoped prompt overrides. When nil, prompt rendering
	// uses baseline registered PromptSpecs only.
	PromptStore prompt.Store
	// SessionStore persists session lifecycle state and run metadata.
	SessionStore session.Store
	// Policy evaluates allowlists and caps per planner turn.
	Policy policy.Engine
	// RunEventStore is the canonical append-only run event log.
	RunEventStore runlog.Store
	// Hooks is the Pulse-backed bus used for streaming runtime events.
	Hooks hooks.Bus
	// Stream publishes planner/tool/assistant events to the caller.
	Stream stream.Sink
	// Logger emits structured logs (usually backed by Clue).
	Logger telemetry.Logger
	// Metrics records counters/histograms for runtime operations.
	Metrics telemetry.Metrics
	// Tracer emits spans for planner/tool execution.
	Tracer telemetry.Tracer

	// HookActivityTimeout overrides the StartToClose timeout for the
	// hook publishing activity (`runtime.publish_hook`). Zero means use the
	// runtime default.
	HookActivityTimeout time.Duration

	// Workers provides per-agent worker configuration. If an agent lacks
	// an entry, the runtime uses a default worker configuration. Engines
	// that do not poll (in-memory) ignore this map.
	Workers map[agent.Ident]WorkerConfig

	// ToolConfirmation configures runtime-enforced confirmation overrides for selected
	// tools (for example, requiring explicit operator approval before executing
	// additional tools that are not marked with design-time Confirmation).
	ToolConfirmation *ToolConfirmationConfig

	// HintOverrides optionally overrides DSL-authored call hints for specific tools
	// when streaming tool_start events.
	HintOverrides map[tools.Ident]HintOverrideFunc
}

type PlanActivityInput = api.PlanActivityInput

type PlanActivityOutput = api.PlanActivityOutput

type PolicyOverrides = api.PolicyOverrides

type PromptBuilder func(id tools.Ident, payload any) string

type PromptRenderHookContext struct {
	RunID     string
	AgentID   agent.Ident
	SessionID string
	TurnID    string
}

type ResultMaterializer func(ctx context.Context, meta ToolCallMeta, call *planner.ToolRequest, result *planner.ToolResult) error

type RunInput = api.RunInput

type RunNotAwaitableError struct {
	// RunID identifies the rejected run.
	RunID string
	// Reason describes why the run rejected await-resume input.
	Reason RunNotAwaitableReason
	// Cause stores the underlying engine-level error.
	Cause error
}

type RunNotAwaitableReason string

type RunOption func(*RunInput)

type RunOutput = api.RunOutput

type RunPolicy struct {
	// MaxToolCalls caps the total number of tool invocations per run (0 = unlimited).
	MaxToolCalls int

	// MaxConsecutiveFailedToolCalls caps sequential failures before aborting (0 = unlimited).
	MaxConsecutiveFailedToolCalls int

	// TimeBudget is the semantic wall-clock budget for planner and tool work
	// within the run (0 = unlimited). The runtime derives the engine run timeout
	// from this budget plus finalizer reserve and a small engine headroom.
	TimeBudget time.Duration

	// FinalizerGrace reserves time to produce a last assistant message after the
	// budget is exhausted. When set, the runtime stops scheduling new work once
	// the remaining time is less than or equal to this value and requests a final
	// response from the planner. Zero means no reserved window; defaults may apply.
	FinalizerGrace time.Duration

	// InterruptsAllowed indicates whether the workflow can be paused and resumed.
	InterruptsAllowed bool

	// OnMissingFields controls behavior when validation indicates missing fields:
	// "finalize" | "await_clarification" | "resume"
	OnMissingFields MissingFieldsAction

	// History, when non-nil, transforms the message history before each planner
	// invocation (PlanStart and PlanResume). It can truncate or compress history
	// while preserving system prompts and logical turn boundaries.
	History HistoryPolicy

	// Cache configures automatic prompt cache checkpoint placement.
	Cache CachePolicy
}

type Runtime struct {
	// Engine is the workflow backend adapter (Temporal by default).
	Engine engine.Engine
	// MemoryStore persists run transcripts and annotations.
	Memory memory.Store
	// PromptRegistry resolves prompt specs and optional scoped overrides.
	PromptRegistry *prompt.Registry
	// SessionStore persists session lifecycle state and run metadata.
	SessionStore session.Store
	// Policy evaluates allowlists and caps per planner turn.
	Policy policy.Engine
	// RunEventStore is the canonical append-only run event log.
	RunEventStore runlog.Store
	// Bus is the bus used for streaming runtime events.
	Bus hooks.Bus
	// Stream publishes planner/tool/assistant events to the caller.
	Stream stream.Sink
	// contains filtered or unexported fields
}

type RuntimeOption func(*Options)

type Timing struct {
	// Budget sets the total wall-clock budget for this run.
	Budget time.Duration
	// Plan sets the Plan/Resume activity timeout for this run.
	Plan time.Duration
	// Tools sets the default ExecuteTool activity timeout for this run.
	Tools time.Duration
	// PerToolTimeout allows targeting specific tools with custom timeouts.
	PerToolTimeout map[tools.Ident]time.Duration
}

type ToolActivityExecutor interface {
	// Execute runs the tool with the given input and returns the result.
	// The workflow context is provided for workflow-level operations (activities,
	// timers, etc.). Input and output use the ToolInput/ToolOutput envelope.
	Execute(ctx context.Context, wfCtx engine.WorkflowContext, input *ToolInput) (*ToolOutput, error)
}

type ToolCallExecutor interface {
	Execute(ctx context.Context, meta *ToolCallMeta, call *planner.ToolRequest) (*planner.ToolResult, error)
}

type ToolCallExecutorFunc func(ctx context.Context, meta *ToolCallMeta, call *planner.ToolRequest) (*planner.ToolResult, error)

type ToolCallMeta struct {
	// RunID is the durable workflow execution identifier of the run that
	// owns this tool call. It remains stable across retries and is used to
	// correlate runtime records and telemetry.
	RunID string

	// SessionID logically groups related runs (for example a chat
	// conversation). Services typically index memory and search attributes
	// by session.
	SessionID string

	// TurnID identifies the conversational turn that produced this tool
	// call. When set, event streams use it to order and group events.
	TurnID string

	// ToolCallID uniquely identifies this tool invocation. It is used to
	// correlate start/update/end events and parent/child relationships.
	ToolCallID string

	// ParentToolCallID is the identifier of the parent tool call when this
	// invocation is a child (for example a tool launched by an agent-tool).
	// UIs and subscribers use it to reconstruct the call tree.
	ParentToolCallID string
}

type ToolConfirmation struct {
	// Prompt returns the deterministic prompt shown to the user for this call.
	Prompt func(ctx context.Context, call *planner.ToolRequest) (string, error)
	// DeniedResult constructs a schema-compatible tool result value representing
	// a user denial. The runtime attaches it to the original tool_call_id with
	// Error unset.
	DeniedResult func(ctx context.Context, call *planner.ToolRequest) (any, error)
}

type ToolConfirmationConfig struct {
	// Confirm maps tool IDs to confirmation handlers.
	//
	// These handlers are an override mechanism used to:
	// - require confirmation for tools that do not declare design-time Confirmation
	// - override prompt/denied-result rendering for specific tool IDs
	Confirm map[tools.Ident]*ToolConfirmation
}

type ToolInput = api.ToolInput

type ToolOutput = api.ToolOutput

type ToolsetRegistration struct {
	// Name is the qualified toolset name (e.g., "service.toolset_name").
	Name string

	// Description provides human-readable context for tooling.
	Description string

	// Metadata captures structured policy metadata about the toolset.
	Metadata policy.ToolMetadata

	// Execute invokes the concrete tool implementation for a given tool call.
	// Returns a ToolResult containing the payload, telemetry, errors, and retry hints.
	//
	// For service-based tools, codegen generates this function to call service clients.
	// For agent-tools (Exports), generated registrations set Inline=true and
	// populate AgentTool so the workflow runtime can start nested agents as child
	// workflows and adapt their RunOutput into a ToolResult.
	// For custom/server-side tools, users provide their own implementation.
	Execute func(ctx context.Context, call *planner.ToolRequest) (*planner.ToolResult, error)

	// Specs enumerates the codecs associated with each tool in the set.
	// Used by the runtime for JSON marshaling/unmarshaling and schema validation.
	Specs []tools.ToolSpec

	// TaskQueue optionally overrides the queue used when scheduling this toolset's activities.
	TaskQueue string

	// Inline indicates that tools in this toolset execute inside the workflow
	// context (not as activities). For agent-as-tool, the executor needs a
	// WorkflowContext to start the provider as a child workflow. Service-backed
	// toolsets should leave this false so calls run as activities (isolation/retries).
	Inline bool

	// CallHints optionally provides precompiled templates for call display hints
	// keyed by tool ident. When present, RegisterToolset installs these in the
	// global hints registry so sinks can render concise, domain-authored labels.
	CallHints map[tools.Ident]*template.Template

	// ResultHints optionally provides precompiled templates for result previews
	// keyed by tool ident. Templates receive the runtime-owned preview wrapper
	// where semantic data is available under `.Result` and bounded metadata
	// under `.Bounds`. When present, RegisterToolset installs these in the
	// global hints registry so sinks can render concise result previews.
	ResultHints map[tools.Ident]*template.Template

	// PayloadAdapter normalizes or enriches raw JSON payloads prior to decoding.
	// The adapter is applied exactly once at the activity boundary, or before
	// inline execution for Inline toolsets. When nil, no adaptation is applied.
	PayloadAdapter func(ctx context.Context, meta ToolCallMeta, tool tools.Ident, raw json.RawMessage) (json.RawMessage, error)

	// ResultMaterializer enriches typed tool results before the runtime encodes
	// them for hooks, workflow boundaries, or callers. When nil, the runtime
	// publishes the tool result exactly as produced by the executor.
	ResultMaterializer ResultMaterializer

	// DecodeInExecutor instructs the runtime to pass raw JSON payloads through to
	// the executor without pre-decoding. The executor must decode using generated
	// codecs. Defaults to false.
	DecodeInExecutor bool

	// TelemetryBuilder can be provided to build or enrich telemetry consistently
	// across transports. When set, the runtime may invoke it with timing/context.
	TelemetryBuilder func(ctx context.Context, meta ToolCallMeta, tool tools.Ident, start, end time.Time, extras map[string]any) *telemetry.ToolTelemetry

	// AgentTool, when non-nil, carries configuration for agent-as-tool toolsets.
	// It is populated by NewAgentToolsetRegistration so the workflow runtime can
	// start nested agent runs directly (fan-out/fan-in) without relying on the
	// synchronous Execute callback.
	AgentTool *AgentToolConfig
}

type WorkerConfig struct {
	// Queue overrides the default task queue for this agent's workflow and
	// activities. When set, the runtime rebases workflow, planner, and tool
	// activities onto this queue. Engine-specific liveness and queue-wait tuning
	// belongs in the engine adapter, not the generic runtime surface.
	Queue string
}

type WorkerOption func(*WorkerConfig)

type WorkflowOptions = api.WorkflowOptions