orchestrator

type AwaitIntent struct {
	// SessionID is the parent agent session that is awaiting.
	SessionID string
	// TaskIDs are the awaited correlated task ids. The await tool resolves an empty
	// caller-supplied list to all currently-outstanding correlated tasks before
	// registering, so this is never empty once stored.
	TaskIDs []string
	// Policy is the join policy ("all" | "any" | "quorum").
	Policy AwaitPolicy
	// Quorum is the number of reported tasks required when Policy is quorum.
	Quorum int
	// Deadline is a safety timeout after which the supervisor flushes whatever has
	// accumulated even if the join condition is not yet satisfied. Zero means none.
	Deadline time.Time
	// CreatedAt is when the intent was registered.
	CreatedAt time.Time
}

type AwaitPolicy string

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

type BlackboardEntry struct {
	Key       string          `json:"key"`
	Value     json.RawMessage `json:"value"`
	Author    string          `json:"author"`
	TaskID    string          `json:"task_id,omitempty"`
	CreatedAt time.Time       `json:"created_at"`
}

type BlackboardOption func(*Blackboard)

type Config struct {
	StorePath string
	LogDir    string
	// EnginesDir is the directory scanned at startup for *.template.yaml custom
	// engine files. When empty the manager derives it from LogDir.
	EnginesDir string
	// MaxParallel caps how many tasks the orchestrator keeps in flight at once
	// (0 = unlimited). Tasks over the cap stay pending and are dispatched by the
	// dispatch tick as slots free up.
	MaxParallel int
	// MaxPerEngine caps in-flight tasks per engine (0 = unlimited), so a wide
	// fan-out onto one provider cannot starve the others.
	MaxPerEngine int
	// ClaimTTL bounds a dispatch claim; DispatchInterval paces the reclaim/drain
	// tick. Both fall back to the package defaults when zero.
	ClaimTTL         time.Duration
	DispatchInterval time.Duration
	// DefaultMCPConfig is an optional explicit override for the MCP config file
	// passed to subagents. When empty (the default), pando builds a dynamic
	// config at spawn time that includes pando itself as an MCP server plus all
	// configured MCP servers.
	DefaultMCPConfig string
	DefaultEngine    string
	PersonaPath      string
	AppConfig        *mesnadaconfig.Config // Full app config for passing to managers
	// MCPServers lists the MCP servers configured in pando that should be
	// forwarded to subagents. Populated from the pando application config.
	MCPServers []agent.PandoMCPServerEntry
	// GatewayExposeEnabled indicates that MCPGateway re-exports all configured
	// MCP servers through pando's own MCP server. When true, the individual
	// MCPServers entries are not forwarded separately (they are already
	// accessible via the "pando" MCP server entry).
	GatewayExposeEnabled bool
	// ModelResolver converts a model ID (possibly empty or shorthand) into the
	// full "provider.model" string expected by the pando CLI's -m flag.
	// When nil, model IDs are forwarded as-is to the pando CLI spawner.
	ModelResolver func(string) string
	// Delegation carries the conclusion-protocol options. When Delegation.Enabled
	// is false (the default) the orchestrator behaves exactly as before.
	Delegation DelegationConfig
	// ProjectResolver maps a canonical project path to its registry id and display
	// name, used by the conclusion enricher. When nil the enricher derives the
	// display name from filepath.Base(projectPath).
	ProjectResolver conclusion.ProjectResolver
	// MemoryRefValidator resolves a conclusion's memory_refs for the
	// anti-hallucination gate. When nil (the default) the gate verifies only
	// filesystem artifacts and never downgrades on a memory ref.
	MemoryRefValidator conclusion.MemoryRefValidator
	// WarmTargetResolver routes delegated tasks to warm per-project ACP instances
	// (Phase 7.3). When nil (or Delegation.ReuseWarmInstances is false) every task
	// takes the cold subprocess path, preserving today's behavior.
	WarmTargetResolver WarmTargetResolver
	// ProjectRefResolver resolves a free-form project reference supplied to the
	// spawn tool (item B1) to a registered project id/path. When nil the spawn
	// tool's optional "project" argument is rejected as unsupported.
	ProjectRefResolver ProjectRefResolver
	// ExternalDelegationRecoverer recovers interrupted external delegations after a
	// parent restart (A2). Wired only when the caller opted into external warm
	// targets (AllowExternalWarmTargets); nil (the default) keeps recoverStaleTasks
	// marking interrupted tasks failed exactly as before.
	ExternalDelegationRecoverer ExternalDelegationRecoverer
}

type DelegationConfig struct {
	// Enabled gates the whole conclusion protocol. When false the orchestrator
	// preserves today's behavior byte-for-byte: no brief is appended and the
	// enricher is not run.
	Enabled bool
	// SynthesizeFallback enables deriving a conclusion from output/error when the
	// subagent did not emit a sentinel block.
	SynthesizeFallback bool
	// ReuseWarmInstances routes a delegated task whose project is known to a warm
	// per-project ACP instance (via WarmTargetResolver) instead of cold-spawning a
	// CLI. Master switch for warm reuse (default off); requires Enabled and a wired
	// resolver. The reuse-then-autostart policy and concurrency cap are applied by
	// the resolver adapter, not here.
	ReuseWarmInstances bool
	// ConclusionGateDisabled turns off the anti-hallucination conclusion gate,
	// which downgrades a "success" conclusion to "partial" when the artifacts or
	// memory refs it cites cannot be found. Default (false) = gate active
	// whenever Enabled is true.
	ConclusionGateDisabled bool
	// BreakerDisabled turns off the circuit breaker and respawn guard, which
	// refuse a Relaunch/Retry that has hit the consecutive-failure limit, is
	// auth-blocked, or is inside a rate-limit cooldown. Unlike the rest of this
	// struct the breaker does not require Enabled: it guards the plain task
	// respawn paths too. Default (false) = breaker active.
	BreakerDisabled bool
	// MaxTaskRetries is the consecutive-failure limit before the breaker trips.
	// 0 falls back to breaker.DefaultMaxRetries.
	MaxTaskRetries int
	// RateLimitCooldown defers a respawn after a quota wall. 0 falls back to
	// breaker.DefaultRateLimitCooldown.
	RateLimitCooldown time.Duration
	// RecentSuccessWindow suppresses a redundant re-run of a task that just
	// succeeded. 0 falls back to breaker.DefaultRecentSuccessWindow.
	RecentSuccessWindow time.Duration
	// EventLogDisabled turns off the durable delegation event log. When it is on
	// (the default), every terminal outcome is appended to disk before being
	// broadcast, so a signal dropped by the non-blocking in-memory bus — or lost
	// to a restart — is still delivered from the log. Unlike the rest of this
	// struct the log does not require Enabled: it records the lifecycle of every
	// task, not just delegated ones.
	EventLogDisabled bool
	// EventLogMaxEntries bounds the retained log; 0 falls back to
	// events.DefaultMaxEntries.
	EventLogMaxEntries int
	// BlackboardMaxEntriesPerSwarm bounds one swarm's blackboard append log; 0
	// falls back to DefaultBlackboardMaxEntriesPerSwarm. Winning (last-write-wins)
	// entries are always retained, so GC only sheds superseded history.
	BlackboardMaxEntriesPerSwarm int
	// BlackboardTTL purges a swarm's board once its newest entry is older than
	// this; 0 falls back to DefaultBlackboardTTL.
	BlackboardTTL time.Duration
}

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

type DelegationMetricsSnapshot struct {
	WarmAttempts   int64 `json:"warm_attempts"`
	WarmHits       int64 `json:"warm_hits"`
	ExternalHits   int64 `json:"external_hits"`
	WarmFailures   int64 `json:"warm_failures"`
	ColdFallbacks  int64 `json:"cold_fallbacks"`
	CapRejections  int64 `json:"cap_rejections"`
	Resurrections  int64 `json:"resurrections"`
	LiveInjections int64 `json:"live_injections"`
	// ExternalReattachRecovered / ExternalReattachFailed count cross-restart
	// external delegation recovery outcomes (A2).
	ExternalReattachRecovered int64 `json:"external_reattach_recovered"`
	ExternalReattachFailed    int64 `json:"external_reattach_failed"`
	// ConclusionGateDowngrades / BreakerTrips / RespawnsRefused count the
	// integrity gate and anti-thrash outcomes.
	ConclusionGateDowngrades int64 `json:"conclusion_gate_downgrades"`
	BreakerTrips             int64 `json:"breaker_trips"`
	RespawnsRefused          int64 `json:"respawns_refused"`
	// DispatchesDeferred / ClaimsRejected / ClaimsReclaimed describe the
	// claim-lease dispatcher: how often the caps queued a ready task, how often
	// two dispatchers raced for one task, and how often a claim was stranded.
	DispatchesDeferred int64 `json:"dispatches_deferred"`
	ClaimsRejected     int64 `json:"claims_rejected"`
	ClaimsReclaimed    int64 `json:"claims_reclaimed"`
	// WarmHitRate is warmHits / warmAttempts in [0,1]; 0 when there were no
	// attempts. It is the headline "is warm reuse paying off" number.
	WarmHitRate float64 `json:"warm_hit_rate"`
}

type ExternalDelegationRecoverer interface {
	// RecoverExternalDelegation queries the peer serving the given project for the
	// state — and, when finished, the result — of the delegation identified by
	// correlationID. On RecoveryCompleted the returned *WarmRunResult carries the
	// recovered output; for RecoveryRunning/RecoveryUnknown it is nil. A non-nil
	// error means the peer was unreachable or declined (also handled as "cannot
	// recover" → mark failed).
	RecoverExternalDelegation(ctx context.Context, projectID, projectPath, correlationID string) (*WarmRunResult, ExternalRecoveryState, error)
}

type ExternalRecoveryState int

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

type ProjectRef struct {
	ID   string
	Name string
	Path string
}

type ProjectRefResolver interface {
	// ResolveProjectRef returns the registered project matching ref, or ok=false
	// when none matches.
	ResolveProjectRef(ctx context.Context, ref string) (ProjectRef, bool)
	// ListProjectRefs returns all registered projects (for error messages).
	ListProjectRefs(ctx context.Context) []ProjectRef
}

type RelaunchOptions struct {
	// Prompt overrides the original prompt when non-empty.
	Prompt string
	// Engine overrides the engine when non-zero.
	Engine models.Engine
	// Model overrides the model when non-empty.
	Model string
	// Timeout overrides the timeout when non-empty.
	Timeout string
	// Background controls whether the relaunch runs in the background.
	Background bool
	// Force bypasses the circuit breaker / respawn guard. Use it when the caller
	// has actually changed something (a new prompt, engine or model) or when a
	// human explicitly insists on re-running a guarded task.
	Force bool
}

type ResumeOptions struct {
	Prompt     string
	Model      string
	Background bool
	Timeout    string
	Tags       *[]string
}

type RetryOptions struct {
	Background bool
	// Force bypasses the circuit breaker / respawn guard (see RelaunchOptions).
	Force bool
}

type Stats struct {
	Total           int                         `json:"total"`
	Pending         int                         `json:"pending"`
	Running         int                         `json:"running"`
	Paused          int                         `json:"paused"`
	Completed       int                         `json:"completed"`
	Failed          int                         `json:"failed"`
	Cancelled       int                         `json:"cancelled"`
	RunningProgress map[string]TaskProgressInfo `json:"running_progress,omitempty"`
}

type SwarmCreated struct {
	WorkerIDs     []string `json:"worker_ids"`
	VerifierID    string   `json:"verifier_id"`
	SynthesizerID string   `json:"synthesizer_id"`
}

type SwarmRoleSpec struct {
	Engine  string
	Model   string
	Persona string
	Extra   string // appended to the built-in brief
}

type SwarmSpec struct {
	Goal        string
	Workers     []SwarmWorkerSpec
	Verifier    SwarmRoleSpec
	Synthesizer SwarmRoleSpec
	WorkDir     string
	// ParentSessionID is the calling agent session; it becomes the shared swarm id
	// so every card sees the same blackboard (P1) and inherits conclusion
	// forwarding (P2). Required — without it the swarm has no coordination scope.
	ParentSessionID string
	ProjectID       string
	ProjectPath     string
	Depth           int
	// IdempotencyKey, when set, makes CreateSwarm return the existing topology on a
	// repeated call instead of duplicating the graph (keyed within the swarm's
	// blackboard). Empty ⇒ always create fresh.
	IdempotencyKey string
}

type SwarmWorkerSpec struct {
	Prompt  string
	Engine  string
	Model   string
	Persona string
}

type TaskProgressInfo struct {
	TaskID      string    `json:"task_id"`
	Percentage  int       `json:"percentage"`
	Description string    `json:"description"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type WarmRunResult struct {
	// ChildSessionID is the ACP session id created in the warm child for this run.
	ChildSessionID string
	// Output is the agent's full streamed message text for the turn.
	Output string
	// StopReason is the ACP stop reason reported by the child (e.g. end_turn).
	StopReason string
	// External is true when the run was served by an external (editor-launched)
	// peer over the IPC bus (hot-peer delegation, B3) rather than a manager-spawned
	// warm child. Used only for metrics attribution (externalHits).
	External bool
}

type WarmTargetResolver interface {
	// RunWarm runs promptText inside a warm instance for the given project,
	// applying the reuse-then-autostart policy and the per-instance concurrency
	// cap. projectID may be empty, in which case projectPath is resolved to a
	// registered project. correlationID is the task's idempotency key, threaded
	// through for external (IPC) delegation so a cancel targets the right run; it
	// may be empty. It returns ErrNoWarmTarget when the project cannot be served by
	// a warm instance so the caller takes the cold path.
	RunWarm(ctx context.Context, projectID, projectPath, promptText, correlationID string) (*WarmRunResult, error)
}