graph

type AgentBindingLeaseResolver interface {
	ValidateAgentBindingWithLease(ctx context.Context, binding model.AgentRuntimeBinding) (func(), error)
}

type AgentSessionLeaseResolver interface {
	ValidateSessionAgentWithLease(ctx context.Context, sessionID string) (func(), error)
}

type AgentSnapshotLeaseResolver interface {
	ResolveAgentSnapshotWithLease(ctx context.Context, identifier string) (model.GraphAgentSnapshot, func(), error)
}

type AgentSnapshotResolver interface {
	ResolveAgentSnapshot(ctx context.Context, identifier string) (model.GraphAgentSnapshot, error)
}

type CondBinary struct {
	Op    string // "且" or "或"
	Left  ConditionExpr
	Right ConditionExpr
}

type CondCompare struct {
	Left        CondOperand
	Op          string
	Right       CondOperand
	IgnoreCase  bool
	IgnoreSpace bool
}

type CondEvalError struct {
	Expr        string
	Op          string
	IgnoreCase  bool
	IgnoreSpace bool
	Message     string
}

type CondEvalInput struct {
	// Variables is the instance's visible variable snapshot (named outputs,
	// _last_assistant_msg, aliases and initial variables already merged).
	Variables map[string]string
	// Disabled holds variable names toggled off. A disabled variable
	// participates in comparisons as the empty string (§3), regardless of any
	// value it might still carry in Variables.
	Disabled map[string]struct{}
}

type CondNot struct {
	X ConditionExpr
}

type CondOperand struct {
	IsVar bool
	Var   string // variable name when IsVar
	Lit   string // literal value (already unescaped) otherwise
}

type ConditionExpr interface {
	// contains filtered or unexported methods
}

type GraphBufferStats struct {
	Events           int
	Readers          int
	HeadSeq          uint64
	NextSeq          uint64
	MaxLagSeq        uint64
	GCRunCount       uint64
	GCReleasedEvents uint64
	Terminal         bool
	Closed           bool
}

type GraphEventReader interface {
	// ReadWithTimeout returns up to maxN buffered events after the cursor, or a
	// timeout/closed status. See graphReader.ReadWithTimeout.
	ReadWithTimeout(ctx context.Context, timeout time.Duration, maxN int) ([]GraphReadEntry, GraphReadStatus)
	// Ack advances the cursor past seq (forward only) and triggers GC.
	Ack(seq uint64)
	// Close detaches the reader from its buffer.
	Close()
}

type GraphReadEntry struct {
	Seq   uint64
	Event *model.GraphEvent
}

type GraphReadStatus int

type JobStateSink interface {
	SetGraphRunState(ctx context.Context, jobID, graphRunID string, status model.JobStatus, graphStatus model.GraphRunStatus, startedAt, finishedAt int64, graphSessionID string) error
	// ClearGraphRunLinkage detaches a Job from a deleted GraphRun, but only if
	// the Job is still bound to that exact run (it may have been re-bound to a
	// newer run since).
	ClearGraphRunLinkage(ctx context.Context, jobID, graphRunID string) error
	// AttachGraphSession records an Agent node's session on the job's
	// GraphSessionIDs whitelist (de-duplicated) so an interactive message may
	// later target it — letting a user keep chatting in a finished node's
	// session after the run stops. Best-effort and idempotent; kept off
	// SessionIDs to preserve that field's linear-iteration semantics.
	AttachGraphSession(ctx context.Context, jobID, sessionID string) error
	// JobTitle returns the bound Job's display title for hook env injection
	// ($QUARTET_JOB_TITLE). Best-effort: an unknown job (or any lookup miss)
	// returns "" rather than an error, since hooks only log-and-continue.
	JobTitle(ctx context.Context, jobID string) string
}

type LegacyAgentBindingResolver interface {
	ResolveLegacyAgentBinding(ctx context.Context, identifier string) (*model.AgentRuntimeBinding, error)
}

type OutputParseResult struct {
	Variables map[string]string
}

type OutputProtocolError struct {
	Variable string
	Message  string
}

type PromptUserMessageRecorder interface {
	RecordPromptUserMessage(ctx context.Context, jobID, sessionID, content string, startedAt int64) error
}

type Runner interface {
	InitSession(ctx context.Context, jobID string, overrides *model.SessionOverrides) (sessionID string, err error)
	RunIteration(ctx context.Context, sessionID string, messages []*schema.Message, handler agui.EventHandler) error
	SessionModelID(sessionID string) string
	// ResolveModelSnapshot returns the display form of the model bound to
	// modelID, so a GraphRun can freeze it into its snapshot. The numeric eino
	// model-config store is gone; a graph node's ModelID is now the ACP model
	// identifier, which is already display-ready and snapshotted as-is.
	// ok=false when modelID is empty — the caller treats this as a degraded
	// (best-effort) snapshot rather than a start failure.
	ResolveModelSnapshot(ctx context.Context, modelID string) (string, bool)
}

type Service interface {
	CreateWorkflow(ctx context.Context, req *model.CreateGraphWorkflowRequest) (*model.GraphWorkflow, error)
	GetWorkflow(ctx context.Context, id string) (*model.GraphWorkflow, error)
	ListWorkflows(ctx context.Context) ([]*model.GraphWorkflow, []model.GraphWorkflowWarning, error)
	UpdateWorkflow(ctx context.Context, id string, req *model.UpdateGraphWorkflowRequest) (*model.GraphWorkflow, error)
	DeleteWorkflow(ctx context.Context, id string, expectedUpdatedAt *time.Time) error
	CreateRunJob(ctx context.Context, req *model.StartGraphRunRequest, jobs jobsvc.Service, workspaces workspacesvc.Service) (*model.Job, error)
	CreateScheduledRunJob(ctx context.Context, task *model.ScheduledTask, jobs jobsvc.Service, workspaces workspacesvc.Service) (*model.Job, error)
	// ValidateConfig runs the full static legality check without persisting.
	ValidateConfig(ctx context.Context, cfg *model.GraphConfig) []model.GraphValidationError
	StartRun(ctx context.Context, req *model.StartGraphRunRequest, runner Runner, jobs JobStateSink) (*model.GraphRun, error)
	RegisterRunLocation(ctx context.Context, runID, workspaceID, jobID string) error
	GetRunStatus(ctx context.Context, runID string) (*model.GraphRunStatusResponse, error)
	ListRunEvents(ctx context.Context, runID string, startLine int, count *int) (*model.GraphRunEventsResponse, error)
	// ListReplayEvents reads at most limit persistable structural events from
	// startLine for SSE disk-replay (a run with no live buffer in this process).
	// It bounds the read so a pathologically large event log can't be streamed in
	// full, and filters out any agent streaming deltas that may linger in legacy
	// logs. The canvas is rebuilt from the run snapshot, so this stream is only a
	// best-effort structural backfill.
	ListReplayEvents(ctx context.Context, runID string, startLine, limit int) (*model.GraphRunEventsResponse, error)
	// ListHookResults projects a run's persisted hook (completed/failed) events
	// into per-node results for the run-view node-detail panel, keeping the latest
	// result per node.
	ListHookResults(ctx context.Context, runID string) (*model.GraphHookResultsResponse, error)
	// SubscribeRunEvents attaches an SSE reader to a live run's in-memory event
	// buffer, resuming after startSeq. live=false means no buffer exists in this
	// process (run not active here, e.g. after a restart) — the caller degrades
	// to replaying persisted structural events from disk. A non-nil error means
	// the resume point has been GC'd (caller maps to HTTP 410). The returned
	// reader must be Closed by the caller.
	SubscribeRunEvents(runID string, startSeq uint64) (reader GraphEventReader, live bool, err error)
	// RunEventSnapshotSeq returns the seq a fresh subscriber should resume from
	// for a live run, and ok=false when no live buffer exists.
	RunEventSnapshotSeq(runID string) (seq uint64, ok bool)
	// StopRun hard-stops a running GraphRun: in-flight instances are cancelled
	// and marked interrupted, the run becomes "stopped" and stays resumable.
	StopRun(ctx context.Context, runID, reason string) (*model.GraphRun, error)
	// StopRunAndWait is the lifecycle-safe hard-stop used before destructive
	// follow-up work. It is idempotent for settled runs, repairs schedulerless
	// in-flight runs, and for a live scheduler waits until all run persistence,
	// Job sink updates, and asynchronous hooks have completed.
	StopRunAndWait(ctx context.Context, runID, reason string) (*model.GraphRun, error)
	// StepStopRun freezes the current ready batch and stops after its members
	// reach a terminal state; the run becomes "stepStopped" and stays resumable.
	StepStopRun(ctx context.Context, runID, reason string) (*model.GraphRun, error)
	// SessionStopRun continues inherited Agent turns and stops before dispatching
	// an Agent node that needs a new session. The run stays resumable.
	SessionStopRun(ctx context.Context, runID, reason string) (*model.GraphRun, error)
	// CancelStopRun cancels a pending step/session stop, releases the held
	// dispatch frontier, and returns the run to "running".
	CancelStopRun(ctx context.Context, runID, reason string) (*model.GraphRun, error)
	// ResumeRun re-launches a resumable GraphRun (failed/stepStopped/sessionStopped/stopped/
	// timedOut/recovering): succeeded/skipped instances are kept,
	// failed/interrupted ones are reset and rescheduled.
	ResumeRun(ctx context.Context, runID string, runner Runner, jobs JobStateSink) (*model.GraphRun, error)
	// ContinueRun continues a GraphRun parked at awaitingInput (§ 交互澄清结点): it
	// finalizes the clarify instances (capturing each session's discussion 结论
	// into their output variables), resolves their held out-edges, and resumes the
	// DAG. Rejected unless the run is in awaitingInput.
	ContinueRun(ctx context.Context, runID string, runner Runner, jobs JobStateSink) (*model.GraphRun, error)
	// DeleteRun deletes a non-in-flight GraphRun, cascading all of its run
	// artifacts and clearing the bound Job's GraphRunID linkage.
	DeleteRun(ctx context.Context, runID string, jobs JobStateSink) error
	// UpdateRunVersion appends a new graph version to a GraphRun after validating
	// the edit against the persisted run state (already-running/succeeded/skipped
	// instances and their config are immutable; paths/edges depended on by
	// completed instances may not be removed). The new version's referenced
	// Agent/model config content is frozen into the run. On a live run the
	// scheduler refreshes its effective topology, so not-yet-started instances
	// use the new version while in-flight and completed instances keep their
	// execution-time version.
	UpdateRunVersion(ctx context.Context, runID string, req *model.UpdateGraphRunVersionRequest, src Runner) (*model.GraphRun, error)
	// SetUsageRecorder wires the optional usage-stats sink for Agent-class graph
	// nodes. Passing nil disables recording (used by tests).
	SetUsageRecorder(r usagestats.Recorder)
	// SetEndHookScriptProvider wires the getter for the global default End-node
	// hook script (settings.EndHookScript). Read at hook time so a mid-run
	// edit takes effect; nil (or returning "") disables the "default" End hook.
	SetEndHookScriptProvider(fn func() string)
	// SetJobStateSink wires the persistent Job state sink used by the
	// orphan-reconcile paths (StopRun's no-scheduler fallback and
	// ReconcileInterruptedRun) that run without a live scheduler. Set once at
	// startup, before serving.
	SetJobStateSink(jobs JobStateSink)
	// ReconcileInterruptedRun repairs a run left in an in-flight status by a
	// crash/restart: no live scheduler can exist for it after boot, so its
	// still-running instances are marked interrupted and the run is moved to
	// `recovering` (a static, resumable state) with the bound Job set to a
	// non-running status. No-op for runs already in a settled status. Called
	// once per graph job at startup.
	ReconcileInterruptedRun(ctx context.Context, runID string) error
}

type SessionLastAssistantReader interface {
	SessionLastAssistantMessage(ctx context.Context, jobID, sessionID string) (content string, ok bool, err error)
}

type ShellControlError struct {
	Variable string
	Message  string
}

type ShellControlResult struct {
	Variables    map[string]string
	StopLoop     bool
	StopWorkflow bool
}

type ShellSessionRecorder interface {
	BeginShellSession(ctx context.Context, jobID, script string, startedAt int64) (sessionID string, err error)
	FinishShellSession(ctx context.Context, jobID, sessionID, output string, startedAt, finishedAt int64) error
}

type TitleInput struct {
	// Summary 是按执行顺序整理出的提示词列表（含少量结构信息），作为标题模型的
	// 用户消息。
	Summary string
	// FallbackSeed 是第一个提示词节点的开头内容，模型失败时用它派生标题。
	FallbackSeed string
}

type UpstreamSnapshot struct {
	// NodeID is the upstream node's stable ID. Used to break ties for
	// _last_assistant_msg deterministically (ascending node ID, last wins).
	NodeID string
	// Variables is the upstream instance's visible variable snapshot, including
	// any named outputs and aliases it wrote.
	Variables map[string]string
	// Writers identifies variables written by a concrete node ID. Variables not
	// present here are still inherited from the run's initial variable table.
	Writers map[string]string
	// LastAssistantMsg is the upstream instance's raw final output
	// (_last_assistant_msg). Empty string is a valid value.
	LastAssistantMsg string
	// SessionID is the upstream instance's outflow session (§3 会话血缘): the
	// session an inheriting downstream Agent forks from. Empty when the upstream
	// chain has not yet created any session (e.g. before the first Agent node).
	SessionID string
}

type ValidationError struct {
	Errors []model.GraphValidationError
}