adapter

package
v0.0.36 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 28, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const ListItemReviewArtifactsMetadataKey = "review_artifacts"

Variables

View Source 
var (
	// ErrBrowseNotSupported is returned when ListSelectable is called
	// on an adapter that doesn't support browsing.
	ErrBrowseNotSupported = error(browseNotSupported{})

	// ErrWatchNotSupported is returned when Watch is called
	// on an adapter that doesn't support watching.
	ErrWatchNotSupported = error(watchNotSupported{})

	// ErrMutateNotSupported is returned when mutation methods are called
	// on an adapter that doesn't support mutations.
	ErrMutateNotSupported = error(mutateNotSupported{})

	// ErrSteerNotSupported is returned when Steer is called
	// on a harness that doesn't support mid-stream steering.
	ErrSteerNotSupported = error(steerNotSupported{})

	// ErrSendAnswerNotSupported is returned when SendAnswer is called
	// on a harness that doesn't support answering foreman questions.
	ErrSendAnswerNotSupported = error(sendAnswerNotSupported{})

	// ErrCompactNotSupported is returned when Compact is called
	// on a harness that doesn't support manual compaction.
	ErrCompactNotSupported = error(compactNotSupported{})
)

Adapter errors.

Functions

func PersistGithubPR 

func PersistGithubPR(
	ctx context.Context,
	repos ReviewArtifactRepos,
	workspaceID, workItemID string,
	artifact domain.ReviewArtifact,
	owner, repo string,
	number int,
) error

PersistGithubPR dual-writes a GitHub PR: event (audit trail) + provider table + link table.

func PersistGitlabMR 

func PersistGitlabMR(
	ctx context.Context,
	repos ReviewArtifactRepos,
	workspaceID, workItemID string,
	artifact domain.ReviewArtifact,
	projectPath string,
	iid int,
) error

PersistGitlabMR dual-writes a GitLab MR: event (audit trail) + provider table + link table.

func PersistReviewArtifact 

func PersistReviewArtifact(ctx context.Context, eventSvc *service.EventService, workspaceID, workItemID string, artifact domain.ReviewArtifact) error

func SummaryExcerpt 

func SummaryExcerpt(text string) string

SummaryExcerpt normalises whitespace and truncates text to a short summary.

Types

type AdapterCapabilities 

type AdapterCapabilities struct {
	CanWatch      bool                                               // Supports Watch for reactive auto-assignment
	CanBrowse     bool                                               // Supports ListSelectable/Resolve for interactive selection
	CanMutate     bool                                               // Supports UpdateState/AddComment
	BrowseScopes  []domain.SelectionScope                            // Available scopes for browsing
	BrowseFilters map[domain.SelectionScope]BrowseFilterCapabilities // Available filters by scope
}

AdapterCapabilities describes what an adapter can do.

type AgentEvent 

type AgentEvent struct {
	Type string // e.g. started, input, text_delta, tool_start, tool_output,
	// tool_result, done, error, question, foreman_proposed, retry_wait, retry_resumed, retry_exhausted
	Timestamp time.Time
	Payload   string // text payload for the event type
	Metadata  map[string]any
	Question  *AgentQuestion
	Answer    *AgentQuestionAnswer
}

AgentEvent represents an event from a running agent session.

type AgentHarness 

type AgentHarness interface {
	// Name returns the harness identifier (e.g., "omp", "mock").
	Name() string

	// StartSession spawns a new agent session with the given options.
	// Returns an AgentSession for interacting with the running agent.
	StartSession(ctx context.Context, opts SessionOpts) (AgentSession, error)

	// SupportsCompact reports whether the harness supports manual compaction.
	// Used by the orchestrator to decide whether to resume a native session
	// (with compact) or start a fresh session for reimplementation.
	SupportsCompact() bool
}

AgentHarness manages agent session lifecycle. Implementations wrap external agent systems like oh-my-pi.

type AgentQuestion added in v0.0.33 

type AgentQuestion struct {
	ID                  string
	SessionID           string
	Stage               SessionMode
	Source              AgentQuestionSource
	FreeText            string
	Context             string
	Structured          *StructuredQuestionSet
	PendingAnswerHandle string
	Metadata            map[string]any
}

AgentQuestion is the normalized adapter payload for any live agent question.

type AgentQuestionAnnotation added in v0.0.33 

type AgentQuestionAnnotation struct {
	Preview string `json:"preview,omitempty"`
	Notes   string `json:"notes,omitempty"`
}

type AgentQuestionAnswer added in v0.0.33 

type AgentQuestionAnswer struct {
	Text              string                             `json:"text,omitempty"`
	StructuredAnswers []StructuredQuestionAnswer         `json:"structured_answers,omitempty"`
	Annotations       map[string]AgentQuestionAnnotation `json:"annotations,omitempty"`
}

type AgentQuestionSource added in v0.0.33 

type AgentQuestionSource string

AgentQuestionSource identifies the harness mechanism that produced a question event. 

const (
	AgentQuestionSourceAskForeman            AgentQuestionSource = "ask_foreman"
	AgentQuestionSourceClaudeAsk             AgentQuestionSource = "claude_ask"
	AgentQuestionSourceOMPAsk                AgentQuestionSource = "omp_ask"
	AgentQuestionSourceOpenCodeQuestion      AgentQuestionSource = "opencode_question"
	AgentQuestionSourceFutureHarnessQuestion AgentQuestionSource = "future_harness_question"
)

type AgentSession 

type AgentSession interface {
	// ID returns the unique identifier for this session.
	ID() string

	// Wait blocks until the session completes (done or error).
	// Returns nil on successful completion, or the error that caused failure.
	Wait(ctx context.Context) error

	// Events returns a channel emitting agent events.
	// The channel closes when the session ends.
	Events() <-chan AgentEvent

	// SendMessage sends a message to the running agent.
	// Used for foreman iteration and critique feedback.
	SendMessage(ctx context.Context, msg string) error

	// Steer sends a steering prompt that interrupts the agent's active streaming turn.
	// Returns ErrSteerNotSupported if the harness does not support mid-stream steering.
	Steer(ctx context.Context, msg string) error

	// SendAnswer sends an answer to resolve a pending ask_foreman tool call.
	// The answer is delivered to the bridge subprocess via stdin.
	SendAnswer(ctx context.Context, answer string) error

	// Abort terminates the agent session gracefully.
	// Returns an error if the session cannot be aborted.
	Abort(ctx context.Context) error

	// ResumeInfo returns harness-specific resume data to persist after session completion.
	// Returns nil if the harness does not support or produce resume data.
	ResumeInfo() map[string]string

	// Compact requests manual context compaction to free up context window space.
	// Returns ErrCompactNotSupported if the harness does not support compaction.
	Compact(ctx context.Context) error
}

AgentSession represents a running agent interaction.

type BrowseFilterCapabilities 

type BrowseFilterCapabilities struct {
	Views          []string
	States         []string
	SupportsLabels bool
	SupportsSearch bool
	SupportsCursor bool
	SupportsOffset bool
	SupportsOwner  bool
	SupportsRepo   bool
	SupportsGroup  bool
	SupportsTeam   bool
}

BrowseFilterCapabilities describes which shared browse filters a provider/scope can honor.

type CommitConfig 

type CommitConfig struct {
	Strategy        string // "granular", "semi-regular", "single"
	MessageFormat   string // "ai-generated", "conventional", "custom"
	MessageTemplate string // Required when MessageFormat = "custom"
}

CommitConfig contains commit strategy settings.

type HarnessActionRequest 

type HarnessActionRequest struct {
	Action      string            // e.g. "login_provider", "check_auth"
	Provider    string            // github, gitlab, linear, etc.
	HarnessName string            // selected harness name
	Inputs      map[string]string // optional scoped inputs / env-like values
}

HarnessActionRequest describes a short-lived control-plane action executed by a harness.

type HarnessActionResult 

type HarnessActionResult struct {
	Success      bool
	Message      string
	Identity     string
	Credentials  map[string]string // redacted only in UI; caller decides persistence
	Metadata     map[string]string
	NeedsConfirm bool
}

HarnessActionResult is the structured result of a harness-side action.

type HarnessActionRunner 

type HarnessActionRunner interface {
	RunAction(ctx context.Context, req HarnessActionRequest) (HarnessActionResult, error)
}

HarnessActionRunner executes structured harness control-plane actions such as login or auth checks.

type HarnessCapabilities 

type HarnessCapabilities struct {
	SupportsStreaming    bool     // Supports real-time event streaming
	SupportsMessaging    bool     // Supports SendMessage for iteration
	SupportsNativeResume bool     // Supports resuming completed sessions natively
	SupportedTools       []string // List of supported tool names
}

HarnessCapabilities describes what an agent harness supports.

type ListItem 

type ListItem struct {
	ID           string
	Title        string
	Description  string
	State        string
	Labels       []string
	Provider     string
	Identifier   string
	ContainerRef string
	URL          string
	Metadata     map[string]any
	ParentRef    *ParentRef // Optional: parent project/initiative reference
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

ListItem represents a single selectable item in browse results.

type ListOpts 

type ListOpts struct {
	WorkspaceID string
	Provider    string
	Scope       domain.SelectionScope
	TeamID      string // Optional: filter by team (for Linear)
	Search      string // Optional: server-side search query
	Limit       int    // Optional: max results (0 = default)
	Offset      int    // Optional: pagination offset
	View        string // Optional: assigned_to_me, created_by_me, mentioned, subscribed, all
	State       string // Optional: provider-native state filter
	Owner       string // Optional: GitHub owner filter
	Repo        string // Optional: GitHub repo or GitLab project-path filter
	Group       string // Optional: GitLab group filter
	Labels      []string
	Metadata    map[string]any
	Cursor      string
	HasMoreHint bool
	Sort        string
	Direction   string
}

ListOpts controls ListSelectable behavior.

type ListResult 

type ListResult struct {
	Items      []ListItem
	TotalCount int
	HasMore    bool
	NextCursor string
}

ListResult contains paginated results from ListSelectable.

type ManualInput 

type ManualInput struct {
	Title       string
	Description string
}

ManualInput contains user-provided work item data for manual adapter.

type ParentRef 

type ParentRef struct {
	ID    string
	Type  string // "project" or "initiative"
	Title string
}

ParentRef references a parent entity (project or initiative).

type PermissionError 

type PermissionError struct {
	Adapter    string // e.g. "github", "gitlab", "linear"
	StatusCode int    // 401 or 403
	Body       string // raw API response body, for logging only
}

PermissionError is returned by an adapter's HTTP layer when the server responds with 401 Unauthorized or 403 Forbidden. These responses are permanent — retrying will not help — and require the user to fix their credentials or token scopes. Callers that drive a retry loop MUST check for this type and skip retries immediately.

func (*PermissionError) Error 

func (e *PermissionError) Error() string

type QuestionOption added in v0.0.33 

type QuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
	Preview     string `json:"preview,omitempty"`
}

type RepoItem 

type RepoItem struct {
	Name          string // e.g., "substrate"
	FullName      string // e.g., "beeemT/substrate"
	Description   string
	URL           string // clone URL (HTTPS)
	SSHURL        string // clone URL (SSH)
	DefaultBranch string
	IsPrivate     bool
	Source        string // provider name ("github", "gitlab")
	Owner         string // org/user name
}

RepoItem describes a single repository from a remote source.

type RepoLifecycleAdapter 

type RepoLifecycleAdapter interface {
	// Name returns the adapter's identifier (e.g., "glab", "github").
	Name() string

	// OnEvent handles system events for repository lifecycle management.
	// Typically reacts to WorktreeCreated to create MRs/PRs.
	OnEvent(ctx context.Context, event domain.SystemEvent) error
}

RepoLifecycleAdapter handles repository-level events like worktree creation. Implementations include glab for MR creation, GitHub for PRs, etc.

type RepoListOpts 

type RepoListOpts struct {
	Search    string // text filter -- when non-empty, repo sources use their provider's search API
	Limit     int    // max results per page
	Page      int    // 1-indexed page number
	OwnedOnly bool   // when true, restrict to projects owned by the authenticated user (GitLab only; other sources ignore this)
}

RepoListOpts controls repository listing behavior.

type RepoListResult 

type RepoListResult struct {
	Repos   []RepoItem
	HasMore bool
}

RepoListResult holds a page of repository results.

type RepoSource 

type RepoSource interface {
	// Name returns the source identifier (e.g., "github", "gitlab", "manual").
	Name() string

	// ListRepos returns repositories available for cloning.
	ListRepos(ctx context.Context, opts RepoListOpts) (*RepoListResult, error)
}

RepoSource provides remote repository listing for the Add Repo overlay.

type ReviewArtifactRepos 

type ReviewArtifactRepos struct {
	Events           *service.EventService
	GithubPRs        *service.GithubPRService
	GitlabMRs        *service.GitlabMRService
	SessionArtifacts *service.SessionReviewArtifactService
	Sessions         *service.SessionService
	GithubPRReviews  *service.GithubPRReviewService
	GitlabMRReviews  *service.GitlabMRReviewService
	GithubPRChecks   *service.GithubPRCheckService
	GitlabMRChecks   *service.GitlabMRCheckService
	Bus              *event.Bus
}

ReviewArtifactRepos bundles the services needed for dual-write of review artifacts.

type ReviewComment added in v0.0.30 

type ReviewComment struct {
	ID            string // provider-specific stable identifier (string form)
	ReviewerLogin string
	Body          string
	Path          string // empty for top-level comments
	Line          int    // 0 for top-level
	URL           string // direct link to the comment
	CreatedAt     time.Time
}

ReviewComment is a normalized PR/MR review comment.

type ReviewCommentDispatcher added in v0.0.30 

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

ReviewCommentDispatcher routes review-comment fetches to a per-provider fetcher implementation.

func NewReviewCommentDispatcher added in v0.0.30 

func NewReviewCommentDispatcher(fetchers map[string]ReviewCommentFetcher) *ReviewCommentDispatcher

NewReviewCommentDispatcher constructs a dispatcher from the given fetcher map. A nil map yields a dispatcher that always reports 'no fetcher registered'.

func (*ReviewCommentDispatcher) FetchReviewComments added in v0.0.30 

func (d *ReviewCommentDispatcher) FetchReviewComments(ctx context.Context, provider, repoIdentifier string, number int) ([]ReviewComment, error)

FetchReviewComments looks up the fetcher for the given provider and delegates. Returns an error when no fetcher is registered, including when the dispatcher or its fetcher map is nil.

type ReviewCommentFetcher added in v0.0.30 

type ReviewCommentFetcher interface {
	Provider() string
	FetchReviewComments(ctx context.Context, repoIdentifier string, number int) ([]ReviewComment, error)
}

ReviewCommentFetcher fetches unresolved review comments for one PR/MR. repoIdentifier is provider-specific:

  • GitHub: "owner/repo"
  • GitLab: project path (URL-escaped by adapter)

number is the PR number / MR IID. Implementations MUST filter out resolved comments before returning.

type Selection 

type Selection struct {
	Scope    domain.SelectionScope
	ItemIDs  []string       // For issues/projects: one or more selected IDs
	Manual   *ManualInput   // For manual scope: user-provided input
	Metadata map[string]any // Scope-specific metadata
}

Selection represents a user's selection from ListSelectable results.

type SessionMode 

type SessionMode string

SessionMode determines the behavior of an agent session. 

const (
	// SessionModeAgent is a coding sub-agent with full tool set.
	SessionModeAgent SessionMode = "agent"
	// SessionModeForeman is a question-answering session with read-only tools.
	SessionModeForeman SessionMode = "foreman"
)

type SessionOpts 

type SessionOpts struct {
	SessionID            string      // Substrate-generated ULID; used for DB record and session directory
	Mode                 SessionMode // Agent or Foreman; defaults to Agent
	WorkspaceID          string
	SubPlanID            string
	Repository           string
	WorktreePath         string // Empty for foreman sessions (uses workspace root)
	DraftPath            string // Absolute path to plan-draft.md; set for planning sessions
	CrossRepoPlan        string // Full cross-repo orchestration plan
	DocumentationContext string // Concatenated documentation for the session
	SystemPrompt         string
	UserPrompt           string
	SessionLogDir        string // Directory for session output logs
	CommitConfig         CommitConfig
	AllowPush            bool              // Whether agent is allowed to push to remote
	ResumeFromSessionID  string            // Substrate session ID; harness resumes if it can
	ResumeInfo           map[string]string // Resolved resume data; harness reads its own keys
	// AnswerTimeoutMs controls how long the bridge waits for a foreman answer before
	// falling back to a placeholder. 0 means no timeout (wait indefinitely).
	AnswerTimeoutMs int64
}

SessionOpts configures a new agent session.

type StructuredQuestion added in v0.0.33 

type StructuredQuestion struct {
	ID               string           `json:"id,omitempty"`
	Question         string           `json:"question"`
	Header           string           `json:"header,omitempty"`
	Options          []QuestionOption `json:"options,omitempty"`
	MultiSelect      bool             `json:"multi_select"`
	RecommendedIndex *int             `json:"recommended_index,omitempty"`
}

type StructuredQuestionAnswer added in v0.0.33 

type StructuredQuestionAnswer struct {
	QuestionID      string   `json:"question_id,omitempty"`
	Question        string   `json:"question"`
	SelectedOptions []string `json:"selected_options,omitempty"`
	CustomAnswer    string   `json:"custom_answer,omitempty"`
}

type StructuredQuestionSet added in v0.0.33 

type StructuredQuestionSet struct {
	Questions            []StructuredQuestion `json:"questions"`
	SupportsCustomAnswer bool                 `json:"supports_custom_answer"`
	SupportsAnnotations  bool                 `json:"supports_annotations"`
	NativeResponseFormat string               `json:"native_response_format,omitempty"`
}

type WorkItemAdapter 

type WorkItemAdapter interface {
	// Name returns the adapter's identifier (e.g., "linear", "manual").
	Name() string

	// Capabilities describes what this adapter supports.
	Capabilities() AdapterCapabilities

	// ListSelectable returns items available for interactive selection.
	// Used by the New Session wizard to browse available work items.
	// Returns ErrBrowseNotSupported if CanBrowse is false.
	ListSelectable(ctx context.Context, opts ListOpts) (*ListResult, error)

	// Resolve converts a user's selection into a WorkItem.
	// For multi-item selections (e.g., multiple issues), this aggregates
	// them into a single comprehensive WorkItem.
	Resolve(ctx context.Context, selection Selection) (domain.Session, error)

	// Watch returns a channel that emits work item changes.
	// Used for reactive auto-assignment when new work appears.
	// Returns ErrWatchNotSupported if CanWatch is false.
	// The returned channel is closed when the context is canceled.
	Watch(ctx context.Context, filter WorkItemFilter) (<-chan WorkItemEvent, error)
	// Fetch retrieves a work item by its external ID.
	Fetch(ctx context.Context, externalID string) (domain.Session, error)

	// UpdateState updates the work item's state in the external tracker.
	// Maps TrackerState to the tracker's native states.
	// Returns ErrMutateNotSupported if CanMutate is false.
	UpdateState(ctx context.Context, externalID string, state domain.TrackerState) error
	// AddComment adds a comment to the work item in the external tracker.
	// Returns ErrMutateNotSupported if CanMutate is false.
	AddComment(ctx context.Context, externalID string, body string) error
	// OnEvent handles system events, allowing the adapter to react to
	// state changes (e.g., update Linear when PlanApproved fires).
	OnEvent(ctx context.Context, event domain.SystemEvent) error
}

WorkItemAdapter provides access to external work item tracking systems. Implementations include Linear, GitHub Issues, and manual input.

type WorkItemEvent 

type WorkItemEvent struct {
	Type      string // "created", "updated", "deleted"
	WorkItem  domain.Session
	Timestamp time.Time
}

WorkItemEvent represents a change detected by Watch.

type WorkItemFilter 

type WorkItemFilter struct {
	WorkspaceID string
	TeamID      string
	States      []string // Filter by external tracker states
	Labels      []string // Filter by labels
}

WorkItemFilter constrains Watch event filtering.

Source Files

View all Source files

Directories

Path Synopsis
Package bridge provides shared infrastructure for JSON-line bridge harnesses.
 Package bridge provides shared infrastructure for JSON-line bridge harnesses.
Package claudeagent implements the Claude Agent SDK harness.
 Package claudeagent implements the Claude Agent SDK harness.
Package glab implements the glab CLI wrapper adapter.
 Package glab implements the glab CLI wrapper adapter.
harness
omp
Package omp implements the oh-my-pi agent harness.
 Package omp implements the oh-my-pi agent harness.
Package linear implements the Linear GraphQL adapter.
 Package linear implements the Linear GraphQL adapter.
Package manual implements the manual work item input adapter.
 Package manual implements the manual work item input adapter.
Package omp implements the oh-my-pi agent harness.
 Package omp implements the oh-my-pi agent harness.
Package sentry implements the Sentry work item adapter, including browse/fetch support and polling-based issue watch events.
 Package sentry implements the Sentry work item adapter, including browse/fetch support and polling-based issue watch events.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.