adapter

type AgentAdapter interface {
	// Invoke spawns the agent as a subprocess. It blocks until the agent exits.
	Invoke(ctx context.Context, req InvokeRequest) (*InvokeResult, error)
	// Generate performs a single contained completion. Implementations must not
	// grant the model tools, repo access, or interactivity.
	Generate(ctx context.Context, req GenerateRequest) (*GenerateResult, error)
	// Capabilities describes what the agent harness supports.
	Capabilities() Capabilities
}

type Capabilities struct {
	// MCP reports whether the harness can be given an MCP server config.
	MCP bool
	// Headless reports whether the harness has a non-interactive mode.
	Headless bool
	// Skills reports whether the harness accepts skill paths.
	Skills bool
	// SystemPrompt reports whether the harness accepts a system prompt.
	SystemPrompt bool
	// Generate reports whether the completion plane is available. For a
	// session-capable harness this is true only when the adapter can prove
	// tool containment (hard tool-disable flags asserted by contract test);
	// a harness that cannot be contained does not advertise completions.
	Generate bool
	// StructuredOutput reports whether the provider enforces a JSON schema
	// natively. When false, FormatJSON degrades to schema-in-prompt and the
	// caller parses defensively.
	StructuredOutput bool
}

type CommsAdapter interface {
	// Notify sends a structured message to the configured channel.
	Notify(ctx context.Context, msg Notification) error
	// NotifyUser sends a notification directly to a specific user by handle,
	// bypassing the channel broadcast. Adapters that cannot resolve a handle
	// to a user, or that have no per-user delivery mechanism at all, return
	// ErrRecipientUnknown so the caller can fall back to Notify. Like every
	// comms call it is best-effort and never fatal.
	NotifyUser(ctx context.Context, handle string, msg Notification) error
	// PostStandup posts a formatted standup to the standup channel.
	PostStandup(ctx context.Context, standup StandupReport) error
	// FetchMentions returns recent mentions of spec IDs in configured channels.
	FetchMentions(ctx context.Context, since time.Time) ([]Mention, error)
}

type ContextPart struct {
	Label   string
	Content string
	Weight  int
}

type DeployAdapter interface {
	// Trigger initiates a deployment for the given repos to the target environment.
	Trigger(ctx context.Context, repos []string, env string) (*DeployRun, error)
	// Status polls the deployment run for current state.
	Status(ctx context.Context, run *DeployRun) (*DeployStatus, error)
}

type DeployRun struct {
	ID     string
	Repo   string
	Env    string
	Status string
	URL    string
}

type DeployStatus struct {
	RunID   string
	Status  string // "pending", "running", "success", "failure"
	URL     string
	Message string
}

type DocsAdapter interface {
	// FetchSections retrieves the current content of the spec from the docs provider,
	// keyed by section slug.
	FetchSections(ctx context.Context, specID string) (map[string]string, error)
	// PushFull publishes the complete spec to the docs provider.
	PushFull(ctx context.Context, specID string, content string) error
	// PageURL returns the URL of the spec's page in the docs provider.
	PageURL(ctx context.Context, specID string) (string, error)
}

type GenerateRequest struct {
	// Task is the stable task id (e.g. "draft-section"), used for telemetry
	// and to scope per-task budgets.
	Task string
	// System is the task-specific system prompt.
	System string
	// Prompt is the assembled user prompt.
	Prompt string
	// Context carries labelled blocks the adapter appends verbatim. Assembly
	// and trimming happen before the adapter sees the request.
	Context []ContextPart
	// MaxTokens caps the response. Honoured by completion-API providers only;
	// headless harnesses expose no token cap and ignore it. 0 = provider
	// default.
	MaxTokens int
	// Format selects the output shape. FormatJSON is only honoured when
	// Capabilities.StructuredOutput is true; otherwise the caller is expected
	// to have embedded the schema in the prompt and to parse defensively.
	Format OutputFormat
	// Schema is the JSON schema for Format == FormatJSON. Ignored otherwise.
	Schema json.RawMessage
}

type GenerateResult struct {
	// Text is the generated content.
	Text string
	// Tokens reports usage when the provider supplies it; zero = unreported.
	Tokens TokenUsage
	// Model names what served the request, when known.
	Model string
	// Raw holds a bounded tail of provider output, populated only when
	// structured parsing yielded no text. Lets output-format drift degrade
	// into a debuggable empty result instead of an error.
	Raw string
}

type InvokeRequest struct {
	SpecID        string   // active spec id (e.g. SPEC-042)
	WorkDir       string   // working directory the agent runs in
	ContextFile   string   // consolidated markdown fallback for non-MCP agents
	MCPConfigPath string   // engine-generated; runs `spec mcp-server --spec <id>`
	SystemPrompt  string   // assembled build instructions
	SkillPaths    []string // reproducibility skill paths (may be empty)
	Prompt        string   // kickoff prompt (may be empty)
	Headless      bool     // -p mode for `spec fix --auto` / CI
}

type InvokeResult struct {
	// ExitReason is why the session ended: "completed", "error",
	// "interrupted", or "" when it could not be determined.
	ExitReason string `json:"exitReason,omitempty"`
	// ErrorClass categorises a failure (e.g. "auto_retry_exhausted",
	// "compaction_failed", "nonzero_exit"). Empty on success.
	ErrorClass string `json:"errorClass,omitempty"`
	// ErrorMessage is the harness-reported failure detail, when present.
	ErrorMessage string `json:"errorMessage,omitempty"`
	// Tokens aggregates token usage across the session, when the harness
	// reports it.
	Tokens TokenUsage `json:"tokens,omitempty"`
	// Raw holds a bounded tail of the harness output, retained for debugging
	// when structured parsing yields nothing.
	Raw string `json:"raw,omitempty"`
}

type Mention struct {
	SpecID    string
	Channel   string
	Author    string
	Preview   string
	Timestamp time.Time
}

type Notification struct {
	SpecID  string
	Title   string
	Message string
	Channel string
	Mention string // e.g., "@alice"
}

type OutputFormat int

type PMAdapter interface {
	// FindEpic returns the key of an existing PM object linked to the spec, or
	// "" when none exists. It is the idempotency guard for CreateEpic and
	// CreateTask alike: a spec that already has a PM object is linked, never
	// converted to another type.
	FindEpic(ctx context.Context, specID string) (pmKey string, err error)
	// CreateEpic creates a new epic/issue linked to a spec and returns its key.
	// Used for a standalone spec and for an initiative.
	CreateEpic(ctx context.Context, spec SpecMeta) (pmKey string, err error)
	// CreateTask creates a task under an existing epic, for a spec that is a
	// deliverable slice of an initiative. parentKey is the parent spec's PM
	// key. Implementations return ("", nil) when they cannot place the task,
	// so a PM shortfall never blocks the spec-side link.
	CreateTask(ctx context.Context, spec SpecMeta, parentKey string) (pmKey string, err error)
	// LinkEpic records a back-link from the PM issue to the spec so board
	// consumers can navigate PM -> spec. specURL may be empty.
	LinkEpic(ctx context.Context, pmKey, specID, specURL string) error
	// UpdateStatus syncs the spec's pipeline stage to the PM tool's board
	// status. A stage with no configured mapping is a clean no-op.
	UpdateStatus(ctx context.Context, pmKey string, status string) error
	// FetchUpdates returns status changes from the PM tool since last sync.
	FetchUpdates(ctx context.Context, pmKey string) (*PMUpdate, error)
	// SyncStories reconciles per-step children of a PM object, returning the
	// resulting story links. The adapter resolves the object's type from pmKey
	// and chooses the appropriate child issue type. A no-op when story sync is
	// disabled.
	SyncStories(ctx context.Context, pmKey string, stories []StorySpec) ([]StoryLink, error)
	// Validate checks credentials and configuration against the live PM tool.
	Validate(ctx context.Context) error
}

type PMUpdate struct {
	Status    string
	Assignee  string
	UpdatedAt time.Time
}

type PRDetail struct {
	PullRequest
	ReviewComments    int
	UnresolvedThreads int
}

type PullRequest struct {
	Number    int
	Title     string
	Repo      string
	Branch    string
	Author    string
	URL       string
	Status    string // "open", "merged", "closed"
	Draft     bool   // PR is a draft: opened for visibility, not yet review-ready
	Approved  bool
	CIStatus  string // "passing", "failing", "pending"
	CreatedAt time.Time
}

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

type RepoAdapter interface {
	// ListPRs returns open PRs matching a spec's branch pattern across its repos.
	ListPRs(ctx context.Context, repos []string, specID string) ([]PullRequest, error)
	// PRStatus returns the review/CI status of a specific PR.
	PRStatus(ctx context.Context, repo string, prNumber int) (*PRDetail, error)
	// SetPRDescription updates a PR's description.
	SetPRDescription(ctx context.Context, repo string, prNumber int, body string) error
	// RequestedReviews returns PRs where the current user is a requested reviewer.
	RequestedReviews(ctx context.Context, user string) ([]PullRequest, error)
	// InvolvedPRs returns open PRs that involve the user in any capacity —
	// authored, assigned, review-requested, or mentioned. Unlike
	// RequestedReviews, this includes the user's own PRs.
	InvolvedPRs(ctx context.Context, user string) ([]PullRequest, error)
	// OpenDraftPR opens a DRAFT pull request from head into base, returning its
	// number and URL. Draft-only by design: merge stays a human action, so no
	// merge call is exposed on this interface.
	OpenDraftPR(ctx context.Context, repo, head, base, title, body string) (number int, url string, err error)
	// SetPRBase retargets an open PR's base branch, used to re-chain a stack as
	// parent PRs merge.
	SetPRBase(ctx context.Context, repo string, prNumber int, base string) error
}

type SpecMeta struct {
	ID      string
	Title   string
	Status  string
	EpicKey string
	Repos   []string

	// Problem is a short excerpt of the problem statement, used to give the
	// PM epic meaningful context instead of just an id.
	Problem string
	// Labels are applied to the created issue (in addition to config labels).
	Labels []string
	// Cycle is the team cycle/iteration label.
	Cycle string
	// URL is a back-link to the canonical spec document.
	URL string
}

type StandupReport struct {
	UserName  string
	Date      string
	Yesterday []string
	Today     []string
	Blockers  []string
}

type StoryLink struct {
	StepID   string
	StoryKey string
	Status   string
}

type StorySpec struct {
	// StepID is a stable identifier for the step, used as the idempotency key.
	StepID      string
	Repo        string
	Description string
	// Status is the spec step status: pending | in-progress | complete | blocked.
	Status string
}

type TokenUsage struct {
	Input  int `json:"input,omitempty"`
	Output int `json:"output,omitempty"`
	Total  int `json:"total,omitempty"`
}