coding

type Dispatcher struct {
	Sessions  Sessions
	Tracker   Tracker
	Runner    Runner
	CloneURL  func(org, repo string) string
	VerifyRef func(ctx context.Context, org, repo, branch string) (string, bool)
	// Log is an optional structured log seam for best-effort mirror failures; nil
	// is fine (mirror failures are non-fatal and simply dropped).
	Log func(msg string, kv ...any)
	// Route enqueues a routed run on the durable engine (the tasks-engine binding
	// in routed.go). Nil disables routing — a run with a TargetID then fails
	// closed rather than silently running in the sandbox.
	Route func(ctx context.Context, run RoutedRun) error
	// TargetGate is the fail-closed liveness+existence check for a routed run's
	// target (agents.TargetDispatchable): the target exists in this org, is
	// online, and has a live runner. Nil disables routing.
	TargetGate func(ctx context.Context, org, targetID string) error
}

type PRInput struct {
	Org      string
	Project  string
	Repo     string
	Base     string
	Head     string
	Title    string
	Body     string
	Assignee string
}

type PRRef struct {
	Identifier string
	ProjectKey string
	Number     int
}

type Req struct {
	Org            string
	UserID         string // linked Hanzo subject — session attribution + X-User-Id
	AgentRef       string // agent label (e.g. "hanzo")
	Repo           string
	Project        string // IAM project slug (tracker + git scope); "" = org default
	Base           string // base branch; "" = repo default
	Prompt         string
	CredUser       string
	CredToken      string
	TimeoutSeconds int
	TargetID       string // when set, route to this registered machine instead of the sandbox
}

type Result struct {
	SessionID string
	Repo      string
	Branch    string
	CommitSha string
	Diffstat  string
	Changed   bool
	OK        bool
	Verified  bool // pushed branch confirmed present in native git
	PR        PRRef
	LogTail   string
	Error     string
	// Routed reports that the run was ENQUEUED to a target machine rather than run
	// in the cloud sandbox. When true, OK means "accepted + queued" (not
	// "completed"): the terminal outcome flows through the session stream as the
	// machine executes. TargetID is the machine it was routed to.
	Routed   bool
	TargetID string
}

type RoutedRun struct {
	Org            string
	TargetID       string
	SessionID      string
	Repo           string
	Project        string
	Base           string
	Branch         string
	Prompt         string
	CloneURL       string
	TimeoutSeconds int
}

type RunRequest struct {
	CloneURL          string
	BaseBranch        string
	Branch            string
	Prompt            string
	SessionID         string
	RunTimeoutSeconds int
	CredUser          string
	CredToken         string // write-only secret — never logged
}

type RunResult struct {
	Branch    string
	CommitSha string
	Diffstat  string
	Changed   bool
	OK        bool
	LogTail   string
	Error     string
}

type Runner interface {
	Run(ctx context.Context, org, userID string, req RunRequest, onStep func(Step)) (RunResult, error)
}

type Sessions interface {
	Open(ctx context.Context, org, actor, agent, title string) (string, error)
	// OpenOn opens a session tagged with the run's dispatch TARGET, so a routed
	// run shows in mission-control on the machine it was sent to. An empty target
	// behaves exactly like Open.
	OpenOn(ctx context.Context, org, actor, agent, title, target string) (string, error)
	Log(ctx context.Context, org, sessionID, kind, actor string, payload []byte) error
	Close(ctx context.Context, org, sessionID, status string) error
}

type Step struct {
	Type    string
	Step    string
	Message string
	Status  string
}

type Tracker interface {
	CreatePR(ctx context.Context, in PRInput) (PRRef, error)
}