## Summary
Introduces a configurable workflow state machine that replaces all hardcoded
state labels. The default workflow matches current behavior exactly, ensuring
backward compatibility.
## Architecture
### lib/workflow.ts — Core workflow engine
XState-style statechart configuration:
```typescript
type StateConfig = {
type: 'queue' | 'active' | 'hold' | 'terminal';
role?: 'dev' | 'qa';
label: string;
color: string;
priority?: number;
on?: Record<string, TransitionTarget>;
};
```
All behavior is derived from the config:
- Queue states: `type: 'queue'`, grouped by role, ordered by priority
- Active states: `type: 'active'` — worker occupied
- Transitions: defined with optional actions (gitPull, detectPr, closeIssue, reopenIssue)
- Labels and colors: derived from state.label and state.color
### Derivation functions
- `getStateLabels()` — all labels for issue tracker sync
- `getLabelColors()` — label → color mapping
- `getQueueLabels(role)` — queue labels for a role, ordered by priority
- `getActiveLabel(role)` — the active/in-progress label for a role
- `getRevertLabel(role)` — queue label to revert to on failure
- `detectRoleFromLabel()` — detect role from a queue label
- `getCompletionRule(role, result)` — derive transition rule from config
## Files Changed
- **lib/workflow.ts** — NEW: workflow engine and default config
- **lib/providers/provider.ts** — deprecate STATE_LABELS, LABEL_COLORS; derive from workflow
- **lib/providers/github.ts** — use workflow config for label operations
- **lib/providers/gitlab.ts** — use workflow config for label operations
- **lib/services/pipeline.ts** — use getCompletionRule() from workflow
- **lib/services/tick.ts** — use workflow for queue/active labels
- **lib/services/health.ts** — use workflow for active/revert labels
- **lib/tools/work-start.ts** — use workflow for target label
## Backward Compatibility
- DEFAULT_WORKFLOW matches current hardcoded behavior exactly
- Deprecated exports kept for any external consumers
- No breaking changes to tool interfaces or project state
## Future Work
- Load per-project workflow overrides from projects.json
- User-facing config in projects/workflow.json
- Tool schema generation from workflow states
This commit is contained in:
Lauren ten Hoor
GitHub
@@ -3,18 +3,18 @@
|
||||
*
|
||||
* Triangulates THREE sources of truth:
|
||||
* 1. projects.json — worker state (active, issueId, level, sessions)
|
||||
* 2. Issue label — current GitHub/GitLab label (Doing, Testing, To Do, etc.)
|
||||
* 2. Issue label — current GitHub/GitLab label (from workflow config)
|
||||
* 3. Session state — whether the OpenClaw session exists via gateway status
|
||||
*
|
||||
* Detection matrix:
|
||||
* | projects.json | Issue label | Session | Action |
|
||||
* |---------------|-------------------|--------------|-------------------------------------------|
|
||||
* | active | Doing/Testing ✅ | dead/missing | Deactivate worker, revert to To Do/To Test |
|
||||
* | active | NOT Doing/Testing | any | Deactivate worker (moved externally) |
|
||||
* | active | Doing/Testing ✅ | alive | Healthy (flag if stale >2h) |
|
||||
* | inactive | Doing/Testing | any | Revert issue to To Do/To Test (label stuck)|
|
||||
* | inactive | issueId set | any | Clear issueId (warning) |
|
||||
* | active | issue deleted | any | Deactivate worker, clear state |
|
||||
* | active | Active label ✅ | dead/missing | Deactivate worker, revert to queue |
|
||||
* | active | NOT Active label | any | Deactivate worker (moved externally) |
|
||||
* | active | Active label ✅ | alive | Healthy (flag if stale >2h) |
|
||||
* | inactive | Active label | any | Revert issue to queue (label stuck) |
|
||||
* | inactive | issueId set | any | Clear issueId (warning) |
|
||||
* | active | issue deleted | any | Deactivate worker, clear state |
|
||||
*/
|
||||
import type { StateLabel, IssueProvider, Issue } from "../providers/provider.js";
|
||||
import {
|
||||
@@ -24,6 +24,13 @@ import {
|
||||
type Project,
|
||||
} from "../projects.js";
|
||||
import { runCommand } from "../run-command.js";
|
||||
import {
|
||||
DEFAULT_WORKFLOW,
|
||||
getActiveLabel,
|
||||
getRevertLabel,
|
||||
type WorkflowConfig,
|
||||
type Role,
|
||||
} from "../workflow.js";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Types
|
||||
@@ -32,15 +39,15 @@ import { runCommand } from "../run-command.js";
|
||||
export type HealthIssue = {
|
||||
type:
|
||||
| "session_dead" // Case 1: active worker but session missing/dead
|
||||
| "label_mismatch" // Case 2: active worker but issue not in Doing/Testing
|
||||
| "label_mismatch" // Case 2: active worker but issue not in active label
|
||||
| "stale_worker" // Case 3: active for >2h
|
||||
| "stuck_label" // Case 4: inactive but issue still has Doing/Testing
|
||||
| "stuck_label" // Case 4: inactive but issue still has active label
|
||||
| "orphan_issue_id" // Case 5: inactive but issueId set
|
||||
| "issue_gone"; // Case 6: active but issue deleted/closed
|
||||
severity: "critical" | "warning";
|
||||
project: string;
|
||||
groupId: string;
|
||||
role: "dev" | "qa";
|
||||
role: Role;
|
||||
message: string;
|
||||
level?: string | null;
|
||||
sessionKey?: string | null;
|
||||
@@ -130,38 +137,29 @@ async function fetchIssue(
|
||||
// Health check logic
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Expected in-progress labels for each role.
|
||||
*/
|
||||
const ACTIVE_LABELS: Record<"dev" | "qa", StateLabel> = {
|
||||
dev: "Doing",
|
||||
qa: "Testing",
|
||||
};
|
||||
|
||||
/**
|
||||
* Queue labels to revert to when clearing stuck state.
|
||||
*/
|
||||
const QUEUE_LABELS: Record<"dev" | "qa", StateLabel> = {
|
||||
dev: "To Do",
|
||||
qa: "To Test",
|
||||
};
|
||||
|
||||
export async function checkWorkerHealth(opts: {
|
||||
workspaceDir: string;
|
||||
groupId: string;
|
||||
project: Project;
|
||||
role: "dev" | "qa";
|
||||
role: Role;
|
||||
autoFix: boolean;
|
||||
provider: IssueProvider;
|
||||
sessions: SessionLookup;
|
||||
/** Workflow config (defaults to DEFAULT_WORKFLOW) */
|
||||
workflow?: WorkflowConfig;
|
||||
}): Promise<HealthFix[]> {
|
||||
const { workspaceDir, groupId, project, role, autoFix, provider, sessions } = opts;
|
||||
const {
|
||||
workspaceDir, groupId, project, role, autoFix, provider, sessions,
|
||||
workflow = DEFAULT_WORKFLOW,
|
||||
} = opts;
|
||||
|
||||
const fixes: HealthFix[] = [];
|
||||
const worker = getWorker(project, role);
|
||||
const sessionKey = worker.level ? getSessionForLevel(worker, worker.level) : null;
|
||||
|
||||
const expectedLabel = ACTIVE_LABELS[role];
|
||||
const queueLabel = QUEUE_LABELS[role];
|
||||
// Get labels from workflow config
|
||||
const expectedLabel = getActiveLabel(workflow, role);
|
||||
const queueLabel = getRevertLabel(workflow, role);
|
||||
|
||||
// Parse issueId (may be comma-separated for batch, take first)
|
||||
const issueIdNum = worker.issueId ? Number(worker.issueId.split(",")[0]) : null;
|
||||
@@ -339,7 +337,7 @@ export async function checkWorkerHealth(opts: {
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Case 4: Inactive but issue has stuck Doing/Testing label
|
||||
// Case 4: Inactive but issue has stuck active label
|
||||
// ---------------------------------------------------------------------------
|
||||
if (!worker.active && issue && currentLabel === expectedLabel) {
|
||||
const fix: HealthFix = {
|
||||
|
||||
@@ -1,23 +1,30 @@
|
||||
/**
|
||||
* Pipeline service — declarative completion rules.
|
||||
*
|
||||
* Replaces 7 if-blocks with a data-driven lookup table.
|
||||
* Uses workflow config to determine transitions and side effects.
|
||||
*/
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk";
|
||||
import type { StateLabel, IssueProvider } from "../providers/provider.js";
|
||||
import { deactivateWorker } from "../projects.js";
|
||||
import { runCommand } from "../run-command.js";
|
||||
import { notify, getNotificationConfig } from "../notify.js";
|
||||
import {
|
||||
DEFAULT_WORKFLOW,
|
||||
getCompletionRule,
|
||||
getNextStateDescription,
|
||||
getCompletionEmoji,
|
||||
type CompletionRule,
|
||||
type WorkflowConfig,
|
||||
} from "../workflow.js";
|
||||
|
||||
export type CompletionRule = {
|
||||
from: StateLabel;
|
||||
to: StateLabel;
|
||||
gitPull?: boolean;
|
||||
detectPr?: boolean;
|
||||
closeIssue?: boolean;
|
||||
reopenIssue?: boolean;
|
||||
};
|
||||
// ---------------------------------------------------------------------------
|
||||
// Backward compatibility exports
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* @deprecated Use getCompletionRule() from workflow.ts instead.
|
||||
* Kept for backward compatibility.
|
||||
*/
|
||||
export const COMPLETION_RULES: Record<string, CompletionRule> = {
|
||||
"dev:done": { from: "Doing", to: "To Test", gitPull: true, detectPr: true },
|
||||
"qa:pass": { from: "Testing", to: "Done", closeIssue: true },
|
||||
@@ -27,6 +34,9 @@ export const COMPLETION_RULES: Record<string, CompletionRule> = {
|
||||
"qa:blocked": { from: "Testing", to: "Refining" },
|
||||
};
|
||||
|
||||
/**
|
||||
* @deprecated Use getNextStateDescription() from workflow.ts instead.
|
||||
*/
|
||||
export const NEXT_STATE: Record<string, string> = {
|
||||
"dev:done": "QA queue",
|
||||
"dev:blocked": "moved to Refining - needs human input",
|
||||
@@ -36,14 +46,8 @@ export const NEXT_STATE: Record<string, string> = {
|
||||
"qa:blocked": "moved to Refining - needs human input",
|
||||
};
|
||||
|
||||
const EMOJI: Record<string, string> = {
|
||||
"dev:done": "✅",
|
||||
"qa:pass": "🎉",
|
||||
"qa:fail": "❌",
|
||||
"qa:refine": "🤔",
|
||||
"dev:blocked": "🚫",
|
||||
"qa:blocked": "🚫",
|
||||
};
|
||||
// Re-export CompletionRule type for backward compatibility
|
||||
export type { CompletionRule };
|
||||
|
||||
export type CompletionOutput = {
|
||||
labelTransition: string;
|
||||
@@ -55,8 +59,16 @@ export type CompletionOutput = {
|
||||
issueReopened?: boolean;
|
||||
};
|
||||
|
||||
export function getRule(role: string, result: string): CompletionRule | undefined {
|
||||
return COMPLETION_RULES[`${role}:${result}`];
|
||||
/**
|
||||
* Get completion rule for a role:result pair.
|
||||
* Uses workflow config when available.
|
||||
*/
|
||||
export function getRule(
|
||||
role: string,
|
||||
result: string,
|
||||
workflow: WorkflowConfig = DEFAULT_WORKFLOW,
|
||||
): CompletionRule | undefined {
|
||||
return getCompletionRule(workflow, role as "dev" | "qa", result) ?? undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -77,10 +89,17 @@ export async function executeCompletion(opts: {
|
||||
pluginConfig?: Record<string, unknown>;
|
||||
/** Plugin runtime for direct API access (avoids CLI subprocess timeouts) */
|
||||
runtime?: PluginRuntime;
|
||||
/** Workflow config (defaults to DEFAULT_WORKFLOW) */
|
||||
workflow?: WorkflowConfig;
|
||||
}): Promise<CompletionOutput> {
|
||||
const { workspaceDir, groupId, role, result, issueId, summary, provider, repoPath, projectName, channel, pluginConfig, runtime } = opts;
|
||||
const {
|
||||
workspaceDir, groupId, role, result, issueId, summary, provider,
|
||||
repoPath, projectName, channel, pluginConfig, runtime,
|
||||
workflow = DEFAULT_WORKFLOW,
|
||||
} = opts;
|
||||
|
||||
const key = `${role}:${result}`;
|
||||
const rule = COMPLETION_RULES[key];
|
||||
const rule = getCompletionRule(workflow, role, result);
|
||||
if (!rule) throw new Error(`No completion rule for ${key}`);
|
||||
|
||||
let prUrl = opts.prUrl;
|
||||
@@ -100,8 +119,10 @@ export async function executeCompletion(opts: {
|
||||
// Get issue early (for URL in notification)
|
||||
const issue = await provider.getIssue(issueId);
|
||||
|
||||
// Get next state description from workflow
|
||||
const nextState = getNextStateDescription(workflow, role, result);
|
||||
|
||||
// Send notification early (before deactivation and label transition which can fail)
|
||||
// This ensures users see the notification even if subsequent steps have issues
|
||||
const notifyConfig = getNotificationConfig(pluginConfig);
|
||||
notify(
|
||||
{
|
||||
@@ -113,7 +134,7 @@ export async function executeCompletion(opts: {
|
||||
role,
|
||||
result: result as "done" | "pass" | "fail" | "refine" | "blocked",
|
||||
summary,
|
||||
nextState: NEXT_STATE[key],
|
||||
nextState,
|
||||
},
|
||||
{
|
||||
workspaceDir,
|
||||
@@ -126,25 +147,25 @@ export async function executeCompletion(opts: {
|
||||
|
||||
// Deactivate worker + transition label
|
||||
await deactivateWorker(workspaceDir, groupId, role);
|
||||
await provider.transitionLabel(issueId, rule.from, rule.to);
|
||||
await provider.transitionLabel(issueId, rule.from as StateLabel, rule.to as StateLabel);
|
||||
|
||||
// Close/reopen
|
||||
if (rule.closeIssue) await provider.closeIssue(issueId);
|
||||
if (rule.reopenIssue) await provider.reopenIssue(issueId);
|
||||
|
||||
// Build announcement
|
||||
const emoji = EMOJI[key] ?? "📋";
|
||||
// Build announcement using workflow-derived emoji
|
||||
const emoji = getCompletionEmoji(role, result);
|
||||
const label = key.replace(":", " ").toUpperCase();
|
||||
let announcement = `${emoji} ${label} #${issueId}`;
|
||||
if (summary) announcement += ` — ${summary}`;
|
||||
announcement += `\n📋 Issue: ${issue.web_url}`;
|
||||
if (prUrl) announcement += `\n🔗 PR: ${prUrl}`;
|
||||
announcement += `\n${NEXT_STATE[key]}.`;
|
||||
announcement += `\n${nextState}.`;
|
||||
|
||||
return {
|
||||
labelTransition: `${rule.from} → ${rule.to}`,
|
||||
announcement,
|
||||
nextState: NEXT_STATE[key],
|
||||
nextState,
|
||||
prUrl,
|
||||
issueUrl: issue.web_url,
|
||||
issueClosed: rule.closeIssue,
|
||||
|
||||
@@ -12,14 +12,38 @@ import { selectLevel } from "../model-selector.js";
|
||||
import { getWorker, getSessionForLevel, readProjects } from "../projects.js";
|
||||
import { dispatchTask } from "../dispatch.js";
|
||||
import { DEV_LEVELS, QA_LEVELS, isDevLevel } from "../tiers.js";
|
||||
import {
|
||||
DEFAULT_WORKFLOW,
|
||||
getQueueLabels,
|
||||
getAllQueueLabels,
|
||||
getActiveLabel,
|
||||
detectRoleFromLabel as workflowDetectRole,
|
||||
type WorkflowConfig,
|
||||
type Role,
|
||||
} from "../workflow.js";
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Shared constants + helpers (used by tick, work-start, auto-pickup)
|
||||
// Backward compatibility exports (deprecated)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export const DEV_LABELS: StateLabel[] = ["To Do", "To Improve"];
|
||||
export const QA_LABELS: StateLabel[] = ["To Test"];
|
||||
export const PRIORITY_ORDER: StateLabel[] = ["To Improve", "To Test", "To Do"];
|
||||
/**
|
||||
* @deprecated Use getQueueLabels(workflow, "dev") instead.
|
||||
*/
|
||||
export const DEV_LABELS: StateLabel[] = getQueueLabels(DEFAULT_WORKFLOW, "dev");
|
||||
|
||||
/**
|
||||
* @deprecated Use getQueueLabels(workflow, "qa") instead.
|
||||
*/
|
||||
export const QA_LABELS: StateLabel[] = getQueueLabels(DEFAULT_WORKFLOW, "qa");
|
||||
|
||||
/**
|
||||
* @deprecated Use getAllQueueLabels(workflow) instead.
|
||||
*/
|
||||
export const PRIORITY_ORDER: StateLabel[] = getAllQueueLabels(DEFAULT_WORKFLOW);
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Shared helpers (used by tick, work-start, auto-pickup)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export function detectLevelFromLabels(labels: string[]): string | null {
|
||||
const lower = labels.map((l) => l.toLowerCase());
|
||||
@@ -39,19 +63,22 @@ export function detectLevelFromLabels(labels: string[]): string | null {
|
||||
return all.find((l) => lower.includes(l)) ?? null;
|
||||
}
|
||||
|
||||
export function detectRoleFromLabel(label: StateLabel): "dev" | "qa" | null {
|
||||
if (DEV_LABELS.includes(label)) return "dev";
|
||||
if (QA_LABELS.includes(label)) return "qa";
|
||||
return null;
|
||||
/**
|
||||
* Detect role from a label using workflow config.
|
||||
*/
|
||||
export function detectRoleFromLabel(
|
||||
label: StateLabel,
|
||||
workflow: WorkflowConfig = DEFAULT_WORKFLOW,
|
||||
): Role | null {
|
||||
return workflowDetectRole(workflow, label);
|
||||
}
|
||||
|
||||
export async function findNextIssueForRole(
|
||||
provider: Pick<IssueProvider, "listIssuesByLabel">,
|
||||
role: "dev" | "qa",
|
||||
role: Role,
|
||||
workflow: WorkflowConfig = DEFAULT_WORKFLOW,
|
||||
): Promise<{ issue: Issue; label: StateLabel } | null> {
|
||||
const labels = role === "dev"
|
||||
? PRIORITY_ORDER.filter((l) => DEV_LABELS.includes(l))
|
||||
: PRIORITY_ORDER.filter((l) => QA_LABELS.includes(l));
|
||||
const labels = getQueueLabels(workflow, role);
|
||||
for (const label of labels) {
|
||||
try {
|
||||
const issues = await provider.listIssuesByLabel(label);
|
||||
@@ -66,11 +93,13 @@ export async function findNextIssueForRole(
|
||||
*/
|
||||
export async function findNextIssue(
|
||||
provider: Pick<IssueProvider, "listIssuesByLabel">,
|
||||
role?: "dev" | "qa",
|
||||
role?: Role,
|
||||
workflow: WorkflowConfig = DEFAULT_WORKFLOW,
|
||||
): Promise<{ issue: Issue; label: StateLabel } | null> {
|
||||
const labels = role === "dev" ? PRIORITY_ORDER.filter((l) => DEV_LABELS.includes(l))
|
||||
: role === "qa" ? PRIORITY_ORDER.filter((l) => QA_LABELS.includes(l))
|
||||
: PRIORITY_ORDER;
|
||||
const labels = role
|
||||
? getQueueLabels(workflow, role)
|
||||
: getAllQueueLabels(workflow);
|
||||
|
||||
for (const label of labels) {
|
||||
try {
|
||||
const issues = await provider.listIssuesByLabel(label);
|
||||
@@ -90,7 +119,7 @@ export type TickAction = {
|
||||
issueId: number;
|
||||
issueTitle: string;
|
||||
issueUrl: string;
|
||||
role: "dev" | "qa";
|
||||
role: Role;
|
||||
level: string;
|
||||
sessionAction: "spawn" | "send";
|
||||
announcement: string;
|
||||
@@ -116,20 +145,26 @@ export async function projectTick(opts: {
|
||||
dryRun?: boolean;
|
||||
maxPickups?: number;
|
||||
/** Only attempt this role. Used by work_start to fill the other slot. */
|
||||
targetRole?: "dev" | "qa";
|
||||
targetRole?: Role;
|
||||
/** Optional provider override (for testing). Uses createProvider if omitted. */
|
||||
provider?: Pick<IssueProvider, "listIssuesByLabel" | "transitionLabel" | "listComments">;
|
||||
/** Plugin runtime for direct API access (avoids CLI subprocess timeouts) */
|
||||
runtime?: PluginRuntime;
|
||||
/** Workflow config (defaults to DEFAULT_WORKFLOW) */
|
||||
workflow?: WorkflowConfig;
|
||||
}): Promise<TickResult> {
|
||||
const { workspaceDir, groupId, agentId, sessionKey, pluginConfig, dryRun, maxPickups, targetRole, runtime } = opts;
|
||||
const {
|
||||
workspaceDir, groupId, agentId, sessionKey, pluginConfig, dryRun,
|
||||
maxPickups, targetRole, runtime,
|
||||
workflow = DEFAULT_WORKFLOW,
|
||||
} = opts;
|
||||
|
||||
const project = (await readProjects(workspaceDir)).projects[groupId];
|
||||
if (!project) return { pickups: [], skipped: [{ reason: `Project not found: ${groupId}` }] };
|
||||
|
||||
const provider = opts.provider ?? (await createProvider({ repo: project.repo })).provider;
|
||||
const roleExecution = project.roleExecution ?? "parallel";
|
||||
const roles: Array<"dev" | "qa"> = targetRole ? [targetRole] : ["dev", "qa"];
|
||||
const roles: Role[] = targetRole ? [targetRole] : ["dev", "qa"];
|
||||
|
||||
const pickups: TickAction[] = [];
|
||||
const skipped: TickResult["skipped"] = [];
|
||||
@@ -155,11 +190,11 @@ export async function projectTick(opts: {
|
||||
continue;
|
||||
}
|
||||
|
||||
const next = await findNextIssueForRole(provider, role);
|
||||
const next = await findNextIssueForRole(provider, role, workflow);
|
||||
if (!next) continue;
|
||||
|
||||
const { issue, label: currentLabel } = next;
|
||||
const targetLabel: StateLabel = role === "dev" ? "Doing" : "Testing";
|
||||
const targetLabel = getActiveLabel(workflow, role);
|
||||
|
||||
// Level selection: label → heuristic
|
||||
const selectedLevel = resolveLevelForIssue(issue, role);
|
||||
@@ -206,7 +241,7 @@ export async function projectTick(opts: {
|
||||
/**
|
||||
* Determine the level for an issue based on labels, role overrides, and heuristic fallback.
|
||||
*/
|
||||
function resolveLevelForIssue(issue: Issue, role: "dev" | "qa"): string {
|
||||
function resolveLevelForIssue(issue: Issue, role: Role): string {
|
||||
const labelLevel = detectLevelFromLabels(issue.labels);
|
||||
if (labelLevel) {
|
||||
// QA role but label specifies a dev level → heuristic picks the right QA level
|
||||
|
||||
Reference in New Issue
Block a user