runner

type Adapter interface {
	// Name is the adapter's name as flags and runner.json spell it.
	Name() string
	// Binary is the CLI's executable, looked up on PATH.
	Binary() string
	// NewSessionID is the id a new session is started under, for a CLI that
	// lets its caller choose one, and empty for one that names its own
	// sessions. A chosen id is not a session until the CLI's stream says so.
	NewSessionID() string
	// Args are the arguments of one turn. The prompt is not among them: it
	// goes in on standard input, so nothing a person wrote is ever in argv.
	Args(t Turn) []string
	// Parse reads one line of the CLI's standard output. A line it does not
	// know is no events and no error: the streams grow new line types.
	Parse(line []byte) []Event
	// Guarded reports whether the CLI has guardrails of its own to run
	// unattended under. One without cannot be started under
	// PermissionsGuarded: running it wide open under that name would be
	// worse than refusing.
	Guarded() bool
}

type Config struct {
	Orchestrator Spec `json:"orchestrator,omitzero"`
	Worker       Spec `json:"worker,omitzero"`
	// Permissions is what agents may do on this computer: "full" or
	// "guarded". Empty means full. It is read again for every turn.
	Permissions Permissions `json:"permissions,omitempty"`
	// MaxWorkers is how many workers run at once. Zero means DefaultMaxWorkers.
	MaxWorkers int `json:"max_workers,omitempty"`
	// Rules are tried in order and the first that matches wins. What its
	// worker leaves out comes from the default worker.
	Rules []Rule `json:"rules,omitempty"`
}

type DispatchRequest struct {
	// EventID is the request the worker is for. Zero is work the owner asked
	// for at this computer, which no request line carries.
	EventID int64 `json:"event_id,omitempty"`
	// Repo is the directory the worker starts in; empty with NoRepo.
	Repo   string `json:"repo,omitempty"`
	NoRepo bool   `json:"no_repo,omitempty"`
	// Spec is what the dispatch itself asked for, over every rule.
	Spec Spec `json:"spec,omitzero"`
	// Handoff is everything the worker is told.
	Handoff string `json:"handoff"`
	// Again starts a new worker for an event that already has one.
	Again bool `json:"again,omitempty"`
}

type Event struct {
	Kind      EventKind
	SessionID string
	Model     string
	// Text is what was said (EventText), the turn's answer when the CLI
	// repeats it (EventResult), or the failure (EventError).
	Text string
	// Tool is the tool's name (EventTool).
	Tool string
	// Failed says the turn ended in an error (EventResult).
	Failed bool
	Usage  Usage
	// SessionCost says Usage.CostUSD is what the whole session has cost so
	// far, not what this turn did: Claude Code reports a running total.
	SessionCost bool
	// Refused names the tools whose calls the CLI refused during the turn,
	// one entry per call (EventResult), where the CLI says. Prompts are off,
	// but a rule the person wrote to deny something still holds.
	Refused []string
}

type EventKind int

type Options struct {
	// Profile is the agent's CLI profile.
	Profile string
	// Dir is the runner's own directory, inside the connector's state
	// directory and as private.
	Dir string
	// Orchestrator and Worker are what the connector was started with. Worker
	// may be partial or empty: what it leaves out comes from runner.json's
	// worker, then from Orchestrator.
	Orchestrator Spec
	Worker       Spec
	// ConfigPath is runner.json.
	ConfigPath string
	// Skill and Subagent are the basecamp-connect skill's two files.
	Skill    string
	Subagent string
	// ConnectorLog is the file the connector's output lines are kept in.
	ConnectorLog string
	// Executable is this CLI's own binary. Agents find it first on their
	// PATH as `basecamp`, so the commands the instructions name are this
	// build's.
	Executable string
	// StartLine is what the connector says of itself when it starts: the
	// profile and whether it answers Pings.
	StartLine string
	// Recordings lists a request's recording and everything above it, for
	// rules that ask what a request sits under. Nil answers with nothing.
	Recordings func(ctx context.Context, project, recordingID int64, recordingType string) []int64
	// Held reports whether the connector's hold stands. While it does, no
	// agent is started. Nil means it never does.
	Held func(ctx context.Context) (bool, error)
	// Stop ends the connector, to start again when restart is set.
	Stop   func(restart bool)
	Logger *slog.Logger

	OrchestratorTimeout time.Duration
	WorkerTimeout       time.Duration

	// Environ is the environment agents start from. Nil means os.Environ.
	Environ func() []string
	// LookPath finds an adapter's CLI. Nil means exec.LookPath.
	LookPath func(string) (string, error)
	// Now is the clock. Nil means time.Now.
	Now func() time.Time
	// Retry is the wait before a failed orchestrator turn is tried again,
	// by how many have failed in a row. Nil means retryDelay.
	Retry func(failures int) time.Duration
}

type Permissions string

type Request struct {
	Op       string          `json:"op"`
	Dispatch DispatchRequest `json:"dispatch,omitzero"`
	// Worker is the worker a send or a stop names.
	Worker string `json:"worker,omitempty"`
	// Message is what a send tells a worker, or what say tells the
	// orchestrator.
	Message string `json:"message,omitempty"`
	// Restart asks a stop to start the connector again.
	Restart bool `json:"restart,omitempty"`
}

type Response struct {
	OK    bool   `json:"ok"`
	Error string `json:"error,omitempty"`

	Worker *WorkerView `json:"worker,omitempty"`
	// Existing says a dispatch returned the worker its event already had.
	Existing bool         `json:"existing,omitempty"`
	Workers  []WorkerView `json:"workers,omitempty"`
	// Reply is the orchestrator's answer to say.
	Reply  string  `json:"reply,omitempty"`
	Status *Status `json:"status,omitempty"`
}

type Role string

type Route struct {
	// Repo is the directory the worker starts in, absolute; empty with none.
	Repo string
	// Project is the request's project; zero for a Ping or with no request.
	Project int64
	Ping    bool
	// Recordings are the request's recording and everything above it.
	Recordings []int64
}

type Rule struct {
	// Repo is the local repo the orchestrator chose, or a folder above it.
	// A leading ~ is the person's home.
	Repo string `json:"repo,omitempty"`
	// Project is the Basecamp project the request was made in.
	Project int64 `json:"project,omitempty"`
	// CardTable, Todolist and Within match a request made on, or anywhere
	// under, the recording with that id: a card in that card table, a to-do
	// in that list, a comment on either. Within takes any recording's id.
	CardTable int64 `json:"card_table,omitempty"`
	Todolist  int64 `json:"todolist,omitempty"`
	Within    int64 `json:"within,omitempty"`
	// Ping matches a request made in a Ping, which is in no project.
	Ping bool `json:"ping,omitempty"`

	Worker Spec `json:"worker"`
}

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

type Spec struct {
	Adapter string `json:"adapter,omitempty"`
	Model   string `json:"model,omitempty"`
	Effort  string `json:"effort,omitempty"`
}

type Status struct {
	Profile      string `json:"profile"`
	Orchestrator Spec   `json:"orchestrator"`
	// Session is the orchestrator's session id, once its CLI confirmed one.
	Session string `json:"session,omitempty"`
	Turns   int    `json:"turns"`
	// Worker is the agent a request runs on when no rule says otherwise.
	Worker Spec `json:"worker"`
	// Waiting counts messages the orchestrator has not handled yet.
	Waiting int `json:"waiting"`
	// SetAside counts messages it failed to handle after every retry.
	SetAside int `json:"set_aside"`
	Running  int `json:"running"`
	Queued   int `json:"queued"`
	// ConfigError says runner.json cannot be read as written, and why. The
	// worker shown is then not the one a request would get: no agent is
	// started until the file is fixed.
	ConfigError string `json:"config_error,omitempty"`
}

type Turn struct {
	Role Role
	Spec Spec
	// Resume is the id of the session to continue. Empty starts a new one,
	// under NewID where the adapter chooses ids.
	Resume string
	NewID  string
	// Dir is the directory the session runs in. A session is continued from
	// the directory it was started in.
	Dir string
	// Permissions is what the agent may do. Empty means PermissionsFull.
	Permissions Permissions
}

type TurnResult struct {
	// SessionID is the session the CLI confirmed, which is the one to resume.
	// Empty when the turn failed before the CLI opened one.
	SessionID string
	Model     string
	// Text is the agent's answer: what it said last.
	Text string
	// Usage is what the turn cost, where the CLI says so per turn.
	Usage Usage
	// SessionCostUSD is what the session has cost in all, for a CLI that
	// reports that instead; zero for one that does not.
	SessionCostUSD float64
	// Refused names the tools whose calls the CLI refused, one entry per
	// call, where the CLI says.
	Refused []string
}

type Usage struct {
	InputTokens  int64   `json:"input_tokens,omitempty"`
	OutputTokens int64   `json:"output_tokens,omitempty"`
	CostUSD      float64 `json:"cost_usd,omitempty"`
}

type WorkerView struct {
	ID      string `json:"id"`
	EventID int64  `json:"event_id,omitempty"`
	State   string `json:"state"`
	Adapter string `json:"adapter"`
	Model   string `json:"model,omitempty"`
	Effort  string `json:"effort,omitempty"`
	Repo    string `json:"repo,omitempty"`
	// Matched is the runner.json rule that chose the agent, when one did.
	Matched string `json:"matched,omitempty"`
	// Requests counts the requests it has been given: the first, and each
	// later one on the same thread.
	Requests int `json:"requests"`
	// Doing is the tool a running worker called last.
	Doing string `json:"doing,omitempty"`
	// Refused counts the tool calls its coding agent refused, by a rule of
	// its own settings.
	Refused   int        `json:"refused,omitempty"`
	Report    string     `json:"report,omitempty"`
	Error     string     `json:"error,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
	StartedAt *time.Time `json:"started_at,omitempty"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`
	CostUSD   float64    `json:"cost_usd,omitempty"`
}