Files
kandev/apps/backend/internal/workflow/adapters/adapters.go
T
Henry 750b23a745 feat(orchestrator): surface stalled Office tasks without reclaiming them (#3279)
Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
2026-09-02 19:44:20 +00:00

278 lines
10 KiB
Go

// Package adapters implements the workflow engine's participant, decision,
// and primary-agent adapter interfaces against the workflow repository.
//
// The engine declares the interfaces in internal/workflow/engine/adapters.go
// and internal/workflow/engine/phase2_callbacks.go; this package wires them
// to the workflow_step_participants, workflow_step_decisions, and
// workflow_steps tables so callers (cmd/kandev/main.go) can compose an
// office-grade engine without leaking model imports into the engine package.
package adapters
import (
"context"
"fmt"
"github.com/kandev/kandev/internal/workflow/engine"
"github.com/kandev/kandev/internal/workflow/models"
"github.com/kandev/kandev/internal/workflow/repository"
)
// WorkflowRepo captures the subset of *repository.Repository methods the
// adapters need. Defined as an interface so tests can swap in fakes.
type WorkflowRepo interface {
ListStepParticipantsForTask(ctx context.Context, stepID, taskID string) ([]*models.WorkflowStepParticipant, error)
ListParticipantsForTaskAnyStep(ctx context.Context, taskID string) ([]*models.WorkflowStepParticipant, error)
ListStepDecisions(ctx context.Context, taskID, stepID string) ([]*models.WorkflowStepDecision, error)
RecordStepDecision(ctx context.Context, d *models.WorkflowStepDecision) error
ClearStepDecisions(ctx context.Context, taskID, stepID string) (int64, error)
ResolveCurrentRunner(ctx context.Context, stepID, taskID string) (string, error)
GetTaskWorkflowStepID(ctx context.Context, taskID string) (string, error)
HasRoleSeatForTaskWorkflow(ctx context.Context, workflowID, taskID, role string) (bool, error)
EnsureRoleSeat(ctx context.Context, workflowID, stepID, taskID, role, agentProfileID string) (*models.WorkflowStepParticipant, bool, error)
}
type workflowScopedParticipantRepo interface {
ListParticipantsForTaskWorkflow(ctx context.Context, taskID, workflowID string) ([]*models.WorkflowStepParticipant, error)
}
// Compile-time check that *repository.Repository satisfies WorkflowRepo.
var _ WorkflowRepo = (*repository.Repository)(nil)
// ParticipantAdapter implements engine.ParticipantStore.
type ParticipantAdapter struct {
Repo WorkflowRepo
}
// NewParticipantAdapter builds a ParticipantAdapter wrapping the workflow repo.
func NewParticipantAdapter(repo WorkflowRepo) *ParticipantAdapter {
return &ParticipantAdapter{Repo: repo}
}
// ListStepParticipants satisfies engine.ParticipantStore. The Wave 8 (ADR-0004)
// dual-scoped table — template-level rows (task_id=”) merged with per-task
// overrides — is resolved by the repository's ListStepParticipantsForTask.
func (a *ParticipantAdapter) ListStepParticipants(
ctx context.Context, stepID, taskID string,
) ([]engine.ParticipantInfo, error) {
rows, err := a.Repo.ListStepParticipantsForTask(ctx, stepID, taskID)
if err != nil {
return nil, fmt.Errorf("list step participants: %w", err)
}
out := make([]engine.ParticipantInfo, 0, len(rows))
for _, p := range rows {
out = append(out, engine.ParticipantInfo{
ID: p.ID,
StepID: p.StepID,
TaskID: p.TaskID,
Role: string(p.Role),
AgentProfileID: p.AgentProfileID,
DecisionRequired: p.DecisionRequired,
Position: p.Position,
})
}
return out, nil
}
// ListTaskParticipants satisfies engine.ParticipantStore. It returns every
// per-task participant row for the task regardless of step_id, unmerged
// with template-level rows — the AC-49 port the quorum engine's
// requiredSeats uses to count participation that persists across steps.
func (a *ParticipantAdapter) ListTaskParticipants(
ctx context.Context, taskID string,
) ([]engine.ParticipantInfo, error) {
rows, err := a.Repo.ListParticipantsForTaskAnyStep(ctx, taskID)
if err != nil {
return nil, fmt.Errorf("list task participants: %w", err)
}
out := make([]engine.ParticipantInfo, 0, len(rows))
for _, p := range rows {
out = append(out, engine.ParticipantInfo{
ID: p.ID,
StepID: p.StepID,
TaskID: p.TaskID,
Role: string(p.Role),
AgentProfileID: p.AgentProfileID,
DecisionRequired: p.DecisionRequired,
Position: p.Position,
})
}
return out, nil
}
// ListTaskParticipantsForWorkflow satisfies engine.WorkflowScopedParticipantStore
// when the repository can filter durable task overrides by active workflow.
func (a *ParticipantAdapter) ListTaskParticipantsForWorkflow(
ctx context.Context, taskID, workflowID string,
) ([]engine.ParticipantInfo, error) {
repo, ok := a.Repo.(workflowScopedParticipantRepo)
if !ok {
return a.ListTaskParticipants(ctx, taskID)
}
rows, err := repo.ListParticipantsForTaskWorkflow(ctx, taskID, workflowID)
if err != nil {
return nil, fmt.Errorf("list task participants for workflow: %w", err)
}
out := make([]engine.ParticipantInfo, 0, len(rows))
for _, p := range rows {
out = append(out, engine.ParticipantInfo{
ID: p.ID,
StepID: p.StepID,
TaskID: p.TaskID,
Role: string(p.Role),
AgentProfileID: p.AgentProfileID,
DecisionRequired: p.DecisionRequired,
Position: p.Position,
})
}
return out, nil
}
// WorkflowStepIDForTask satisfies engine.TargetTaskStepResolver.
func (a *ParticipantAdapter) WorkflowStepIDForTask(ctx context.Context, taskID string) (string, error) {
return a.Repo.GetTaskWorkflowStepID(ctx, taskID)
}
// DecisionAdapter implements engine.DecisionStore.
type DecisionAdapter struct {
Repo WorkflowRepo
}
// NewDecisionAdapter builds a DecisionAdapter wrapping the workflow repo.
func NewDecisionAdapter(repo WorkflowRepo) *DecisionAdapter {
return &DecisionAdapter{Repo: repo}
}
// ListStepDecisions satisfies engine.DecisionStore.
func (a *DecisionAdapter) ListStepDecisions(
ctx context.Context, taskID, stepID string,
) ([]engine.DecisionInfo, error) {
rows, err := a.Repo.ListStepDecisions(ctx, taskID, stepID)
if err != nil {
return nil, fmt.Errorf("list step decisions: %w", err)
}
out := make([]engine.DecisionInfo, 0, len(rows))
for _, d := range rows {
out = append(out, engine.DecisionInfo{
ID: d.ID,
TaskID: d.TaskID,
StepID: d.StepID,
ParticipantID: d.ParticipantID,
Decision: d.Decision,
Note: d.Note,
DecidedAt: d.DecidedAt,
DeciderType: d.DeciderType,
DeciderID: d.DeciderID,
Role: d.Role,
Comment: d.Comment,
SupersededAt: d.SupersededAt,
})
}
return out, nil
}
// RecordStepDecision satisfies engine.DecisionStore.
func (a *DecisionAdapter) RecordStepDecision(
ctx context.Context, d engine.DecisionInfo,
) error {
row := &models.WorkflowStepDecision{
ID: d.ID,
TaskID: d.TaskID,
StepID: d.StepID,
ParticipantID: d.ParticipantID,
Decision: d.Decision,
Note: d.Note,
DecidedAt: d.DecidedAt,
DeciderType: d.DeciderType,
DeciderID: d.DeciderID,
Role: d.Role,
Comment: d.Comment,
}
return a.Repo.RecordStepDecision(ctx, row)
}
// ClearStepDecisions satisfies engine.DecisionStore.
func (a *DecisionAdapter) ClearStepDecisions(
ctx context.Context, taskID, stepID string,
) (int64, error) {
return a.Repo.ClearStepDecisions(ctx, taskID, stepID)
}
// ParticipantSeatWriterAdapter implements engine.ParticipantSeatWriter.
type ParticipantSeatWriterAdapter struct {
Repo WorkflowRepo
}
// NewParticipantSeatWriterAdapter builds a ParticipantSeatWriterAdapter
// wrapping the workflow repo.
func NewParticipantSeatWriterAdapter(repo WorkflowRepo) *ParticipantSeatWriterAdapter {
return &ParticipantSeatWriterAdapter{Repo: repo}
}
// HasRoleSeatForTaskWorkflow satisfies engine.ParticipantSeatWriter.
func (a *ParticipantSeatWriterAdapter) HasRoleSeatForTaskWorkflow(
ctx context.Context, workflowID, taskID, role string,
) (bool, error) {
seated, err := a.Repo.HasRoleSeatForTaskWorkflow(ctx, workflowID, taskID, role)
if err != nil {
return false, fmt.Errorf("check existing role seat: %w", err)
}
return seated, nil
}
// EnsureRoleSeat satisfies engine.ParticipantSeatWriter.
func (a *ParticipantSeatWriterAdapter) EnsureRoleSeat(
ctx context.Context, workflowID, stepID, taskID, role, agentProfileID string,
) (engine.ParticipantInfo, error) {
seat, _, err := a.Repo.EnsureRoleSeat(ctx, workflowID, stepID, taskID, role, agentProfileID)
if err != nil {
return engine.ParticipantInfo{}, fmt.Errorf("ensure role seat: %w", err)
}
return engine.ParticipantInfo{
ID: seat.ID,
StepID: seat.StepID,
TaskID: seat.TaskID,
Role: string(seat.Role),
AgentProfileID: seat.AgentProfileID,
DecisionRequired: seat.DecisionRequired,
Position: seat.Position,
}, nil
}
// PrimaryAgentAdapter implements engine.PrimaryAgentResolver. The "primary"
// agent for a task is its current runner participant, falling back to the
// workflow step's agent_profile_id when no task-specific runner exists.
type PrimaryAgentAdapter struct {
Repo WorkflowRepo
}
// NewPrimaryAgentAdapter builds a PrimaryAgentAdapter wrapping the workflow repo.
func NewPrimaryAgentAdapter(repo WorkflowRepo) *PrimaryAgentAdapter {
return &PrimaryAgentAdapter{Repo: repo}
}
// PrimaryAgentProfileID satisfies engine.PrimaryAgentResolver.
func (a *PrimaryAgentAdapter) PrimaryAgentProfileID(
ctx context.Context, stepID, taskID string,
) (string, error) {
agentID, err := a.Repo.ResolveCurrentRunner(ctx, stepID, taskID)
if err != nil {
return "", fmt.Errorf("resolve current runner for step %s task %s: %w", stepID, taskID, err)
}
return agentID, nil
}
// WorkflowStepIDForTask satisfies engine.TargetTaskStepResolver.
func (a *PrimaryAgentAdapter) WorkflowStepIDForTask(ctx context.Context, taskID string) (string, error) {
return a.Repo.GetTaskWorkflowStepID(ctx, taskID)
}
// Compile-time interface assertions.
var (
_ engine.ParticipantStore = (*ParticipantAdapter)(nil)
_ engine.TargetTaskStepResolver = (*ParticipantAdapter)(nil)
_ engine.DecisionStore = (*DecisionAdapter)(nil)
_ engine.PrimaryAgentResolver = (*PrimaryAgentAdapter)(nil)
_ engine.TargetTaskStepResolver = (*PrimaryAgentAdapter)(nil)
_ engine.ParticipantSeatWriter = (*ParticipantSeatWriterAdapter)(nil)
)