better-symphony 1.0.0

package/src/orchestrator/scheduler.ts

@@ -0,0 +1,195 @@
+/**
+ * Scheduler
+ * Issue sorting and dispatch eligibility
+ */
+
+import type { Issue, ServiceConfig, OrchestratorState } from "../config/types.js";
+import * as state from "./state.js";
+
+// ── Candidate Filtering ─────────────────────────────────────────
+
+export interface CandidateResult {
+  eligible: Issue[];
+  skipped: Array<{
+    issue: Issue;
+    reason: string;
+  }>;
+}
+
+/**
+ * Filter and sort candidate issues for dispatch
+ */
+export function selectCandidates(
+  issues: Issue[],
+  orchState: OrchestratorState,
+  config: ServiceConfig
+): CandidateResult {
+  const eligible: Issue[] = [];
+  const skipped: Array<{ issue: Issue; reason: string }> = [];
+
+  const activeStates = new Set(config.tracker.active_states.map((s) => s.trim().toLowerCase()));
+  const terminalStates = new Set(config.tracker.terminal_states.map((s) => s.trim().toLowerCase()));
+
+  for (const issue of issues) {
+    const result = checkEligibility(issue, orchState, config, activeStates, terminalStates);
+    if (result.eligible) {
+      eligible.push(issue);
+    } else {
+      skipped.push({ issue, reason: result.reason });
+    }
+  }
+
+  // Sort by priority
+  sortByDispatchPriority(eligible);
+
+  return { eligible, skipped };
+}
+
+interface EligibilityResult {
+  eligible: boolean;
+  reason: string;
+}
+
+function checkEligibility(
+  issue: Issue,
+  orchState: OrchestratorState,
+  config: ServiceConfig,
+  activeStates: Set<string>,
+  terminalStates: Set<string>
+): EligibilityResult {
+  // Required fields
+  if (!issue.id || !issue.identifier || !issue.title || !issue.state) {
+    return { eligible: false, reason: "missing required fields" };
+  }
+
+  const normalizedState = issue.state.trim().toLowerCase();
+
+  // State checks
+  if (!activeStates.has(normalizedState)) {
+    return { eligible: false, reason: `state "${issue.state}" not in active states` };
+  }
+
+  if (terminalStates.has(normalizedState)) {
+    return { eligible: false, reason: `state "${issue.state}" is terminal` };
+  }
+
+  // Already running check
+  if (state.isIssueRunning(orchState, issue.id)) {
+    return { eligible: false, reason: "already running" };
+  }
+
+  // Already claimed check
+  if (state.isIssueClaimed(orchState, issue.id)) {
+    return { eligible: false, reason: "already claimed" };
+  }
+
+  // Global concurrency check
+  const runningCount = state.getRunningCount(orchState);
+  if (runningCount >= config.agent.max_concurrent_agents) {
+    return { eligible: false, reason: "global concurrency limit reached" };
+  }
+
+  // Per-state concurrency check
+  const stateLimit = config.agent.max_concurrent_agents_by_state.get(normalizedState);
+  if (stateLimit !== undefined) {
+    const stateCount = state.getRunningByState(orchState, normalizedState);
+    if (stateCount >= stateLimit) {
+      return { eligible: false, reason: `per-state concurrency limit reached for "${issue.state}"` };
+    }
+  }
+
+  // Blocker check for Todo state
+  if (normalizedState === "todo" && issue.blocked_by.length > 0) {
+    for (const blocker of issue.blocked_by) {
+      if (blocker.state) {
+        const blockerState = blocker.state.trim().toLowerCase();
+        if (!terminalStates.has(blockerState)) {
+          return {
+            eligible: false,
+            reason: `blocked by ${blocker.identifier || blocker.id} (state: ${blocker.state})`,
+          };
+        }
+      }
+    }
+  }
+
+  // Required labels check
+  const issueLabels = new Set(issue.labels.map((l) => l.toLowerCase()));
+  if (config.tracker.required_labels.length > 0) {
+    for (const requiredLabel of config.tracker.required_labels) {
+      if (!issueLabels.has(requiredLabel.toLowerCase())) {
+        return {
+          eligible: false,
+          reason: `missing required label "${requiredLabel}"`,
+        };
+      }
+    }
+  }
+
+  // Excluded labels check
+  if (config.tracker.excluded_labels.length > 0) {
+    for (const excludedLabel of config.tracker.excluded_labels) {
+      if (issueLabels.has(excludedLabel.toLowerCase())) {
+        return {
+          eligible: false,
+          reason: `has excluded label "${excludedLabel}"`,
+        };
+      }
+    }
+  }
+
+  return { eligible: true, reason: "" };
+}
+
+/**
+ * Sort issues by dispatch priority (in-place)
+ * 1. priority ascending (1..4 preferred, null last)
+ * 2. created_at oldest first
+ * 3. identifier lexicographic tie-breaker
+ */
+export function sortByDispatchPriority(issues: Issue[]): void {
+  issues.sort((a, b) => {
+    // Priority: lower is better, null sorts last
+    const aPrio = a.priority ?? 999;
+    const bPrio = b.priority ?? 999;
+    if (aPrio !== bPrio) {
+      return aPrio - bPrio;
+    }
+
+    // Created at: older is better
+    const aTime = a.created_at?.getTime() ?? Date.now();
+    const bTime = b.created_at?.getTime() ?? Date.now();
+    if (aTime !== bTime) {
+      return aTime - bTime;
+    }
+
+    // Identifier: lexicographic
+    return a.identifier.localeCompare(b.identifier);
+  });
+}
+
+// ── Concurrency Helpers ─────────────────────────────────────────
+
+/**
+ * Get available global slots
+ */
+export function getAvailableSlots(
+  orchState: OrchestratorState,
+  config: ServiceConfig
+): number {
+  return Math.max(0, config.agent.max_concurrent_agents - state.getRunningCount(orchState));
+}
+
+/**
+ * Calculate backoff delay for retry
+ */
+export function calculateBackoffDelay(attempt: number, maxBackoffMs: number): number {
+  // delay = min(10000 * 2^(attempt - 1), max_retry_backoff_ms)
+  const delay = 10000 * Math.pow(2, attempt - 1);
+  return Math.min(delay, maxBackoffMs);
+}
+
+/**
+ * Continuation retry delay (after successful completion)
+ */
+export const CONTINUATION_RETRY_DELAY_MS = 1000;

package/src/orchestrator/state.ts

@@ -0,0 +1,201 @@
+/**
+ * Orchestrator State Management
+ */
+
+import type {
+  OrchestratorState,
+  RunningEntry,
+  RetryEntry,
+  Issue,
+  TokenTotals,
+  RateLimitInfo,
+} from "../config/types.js";
+import { createEmptyTotals } from "../agent/session.js";
+
+export function createOrchestratorState(
+  pollIntervalMs: number,
+  maxConcurrentAgents: number
+): OrchestratorState {
+  return {
+    poll_interval_ms: pollIntervalMs,
+    max_concurrent_agents: maxConcurrentAgents,
+    running: new Map(),
+    claimed: new Set(),
+    retry_attempts: new Map(),
+    completed: new Set(),
+    token_totals: createEmptyTotals(),
+    rate_limits: null,
+    ended_seconds: 0,
+  };
+}
+
+// ── Claim Management ────────────────────────────────────────────
+
+export function claimIssue(state: OrchestratorState, issueId: string): boolean {
+  if (state.claimed.has(issueId)) {
+    return false;
+  }
+  state.claimed.add(issueId);
+  return true;
+}
+
+export function releaseClaim(state: OrchestratorState, issueId: string): void {
+  state.claimed.delete(issueId);
+}
+
+export function isIssueClaimed(state: OrchestratorState, issueId: string): boolean {
+  return state.claimed.has(issueId);
+}
+
+// ── Running Management ──────────────────────────────────────────
+
+export function addRunning(state: OrchestratorState, entry: RunningEntry): void {
+  state.running.set(entry.issue.id, entry);
+}
+
+export function removeRunning(state: OrchestratorState, issueId: string): RunningEntry | undefined {
+  const entry = state.running.get(issueId);
+  if (entry) {
+    state.running.delete(issueId);
+
+    // Add runtime to ended seconds
+    const runtimeMs = Date.now() - entry.attempt.started_at.getTime();
+    state.ended_seconds += runtimeMs / 1000;
+  }
+  return entry;
+}
+
+export function getRunning(state: OrchestratorState, issueId: string): RunningEntry | undefined {
+  return state.running.get(issueId);
+}
+
+export function isIssueRunning(state: OrchestratorState, issueId: string): boolean {
+  return state.running.has(issueId);
+}
+
+export function getRunningCount(state: OrchestratorState): number {
+  return state.running.size;
+}
+
+export function getRunningByState(state: OrchestratorState, stateName: string): number {
+  const normalized = stateName.trim().toLowerCase();
+  let count = 0;
+  for (const entry of state.running.values()) {
+    if (entry.issue.state.trim().toLowerCase() === normalized) {
+      count++;
+    }
+  }
+  return count;
+}
+
+// ── Retry Management ────────────────────────────────────────────
+
+export function addRetry(state: OrchestratorState, entry: RetryEntry): void {
+  // Cancel existing retry if any
+  const existing = state.retry_attempts.get(entry.issue_id);
+  if (existing) {
+    clearTimeout(existing.timer_handle);
+  }
+  state.retry_attempts.set(entry.issue_id, entry);
+}
+
+export function removeRetry(state: OrchestratorState, issueId: string): RetryEntry | undefined {
+  const entry = state.retry_attempts.get(issueId);
+  if (entry) {
+    clearTimeout(entry.timer_handle);
+    state.retry_attempts.delete(issueId);
+  }
+  return entry;
+}
+
+export function getRetry(state: OrchestratorState, issueId: string): RetryEntry | undefined {
+  return state.retry_attempts.get(issueId);
+}
+
+// ── Token/Rate Limit Updates ────────────────────────────────────
+
+export function updateTotals(
+  state: OrchestratorState,
+  deltas: { delta_input: number; delta_output: number; delta_total: number }
+): void {
+  state.token_totals.input_tokens += deltas.delta_input;
+  state.token_totals.output_tokens += deltas.delta_output;
+  state.token_totals.total_tokens += deltas.delta_total;
+}
+
+export function updateRateLimits(state: OrchestratorState, limits: RateLimitInfo): void {
+  state.rate_limits = limits;
+}
+
+// ── Snapshot for Observability ──────────────────────────────────
+
+export interface RuntimeSnapshot {
+  running: Array<{
+    issue_id: string;
+    issue_identifier: string;
+    state: string;
+    started_at: Date;
+    turn_count: number;
+    session_id: string | null;
+    workflow: string | null;
+  }>;
+  retrying: Array<{
+    issue_id: string;
+    identifier: string;
+    attempt: number;
+    due_at: Date;
+    error: string | null;
+    workflow: string | null;
+  }>;
+  workflows: Array<{
+    name: string;
+    max_concurrent_agents: number;
+    running_count: number;
+  }>;
+  token_totals: TokenTotals;
+  rate_limits: RateLimitInfo | null;
+}
+
+export function createSnapshot(state: OrchestratorState, workflowName: string | null = null): RuntimeSnapshot {
+  const now = Date.now();
+
+  // Calculate live seconds_running including active sessions
+  let activeSeconds = 0;
+  for (const entry of state.running.values()) {
+    activeSeconds += (now - entry.attempt.started_at.getTime()) / 1000;
+  }
+
+  const running = Array.from(state.running.values()).map((entry) => ({
+    issue_id: entry.issue.id,
+    issue_identifier: entry.issue.identifier,
+    state: entry.issue.state,
+    started_at: entry.attempt.started_at,
+    turn_count: entry.session?.turn_count ?? 0,
+    session_id: entry.session?.session_id ?? null,
+    workflow: workflowName,
+  }));
+
+  const retrying = Array.from(state.retry_attempts.values()).map((entry) => ({
+    issue_id: entry.issue_id,
+    identifier: entry.identifier,
+    attempt: entry.attempt,
+    due_at: new Date(entry.due_at_ms),
+    error: entry.error,
+    workflow: workflowName,
+  }));
+
+  return {
+    running,
+    retrying,
+    workflows: [{
+      name: workflowName ?? "default",
+      max_concurrent_agents: state.max_concurrent_agents,
+      running_count: running.length,
+    }],
+    token_totals: {
+      ...state.token_totals,
+      seconds_running: state.ended_seconds + activeSeconds,
+    },
+    rate_limits: state.rate_limits,
+  };
+}

package/src/prompts/github-system-prompt.md

@@ -0,0 +1,51 @@
+## GitHub CLI
+
+You have access to the GitHub CLI (`gh`) for working with issues.
+
+### Common Commands
+
+```
+gh issue view <NUMBER> --json number,title,body,author,labels,state,assignees,milestone,createdAt,updatedAt,comments
+gh issue create --title "..." [--body "..."] [--label "..."] [--assignee "..."]
+gh issue edit <NUMBER> [--title "..."] [--body "..."]
+gh issue comment <NUMBER> --body "comment body"
+gh issue edit <NUMBER> --add-label "label-name"
+gh issue edit <NUMBER> --remove-label "label-name"
+gh issue close <NUMBER>
+gh issue reopen <NUMBER>
+```
+
+### Notes
+- `<NUMBER>` is the issue number (e.g., 123)
+- Labels and assignees can be specified multiple times (e.g., `--label "bug" --label "priority:high"`)
+- The `GH_REPO` environment variable is set automatically by Symphony
+- Use labels to track workflow stages (e.g., `agent:dev` -> `agent:dev:progress` -> `agent:dev:done`)
+
+### Error Handling
+If you encounter an unrecoverable error (e.g. missing dependencies, broken build that you cannot fix, unclear requirements), add an "error" label so that the orchestrator can retry later:
+```
+gh issue edit <NUMBER> --add-label "error"
+```
+
+### Examples
+
+```bash
+# Get issue details
+gh issue view 42 --json number,title,body,author,labels,state,assignees,milestone,createdAt,updatedAt,comments
+
+# Create a new issue
+gh issue create --title "Fix login bug" --body "Users can't login" --label "bug"
+
+# Add a progress label
+gh issue edit 42 --add-label "agent:dev:progress"
+
+# Post a status comment
+gh issue comment 42 --body "Started working on the fix"
+
+# Remove old label and add completion label
+gh issue edit 42 --remove-label "agent:dev"
+gh issue edit 42 --add-label "agent:dev:done"
+
+# Close the issue when done
+gh issue close 42
+```

package/src/prompts/linear-system-prompt.md

@@ -0,0 +1,44 @@
+## Linear CLI
+
+You have access to a Linear project management CLI via `bun $SYMPHONY_LINEAR <command>`.
+
+### Available Commands
+
+```
+bun $SYMPHONY_LINEAR get-issue <IDENTIFIER>                        # Get issue details (JSON)
+bun $SYMPHONY_LINEAR get-comments <IDENTIFIER>                     # Get issue comments (JSON)
+bun $SYMPHONY_LINEAR create-issue --parent <ID> --title "..."      # Create a child issue
+    [--description "..."] [--priority N]
+bun $SYMPHONY_LINEAR update-issue <IDENTIFIER>                     # Update an issue
+    [--title "..."] [--description "..."] [--state "..."]
+bun $SYMPHONY_LINEAR create-comment <IDENTIFIER> "body"            # Post a comment
+bun $SYMPHONY_LINEAR add-label <IDENTIFIER> "label-name"           # Add a label
+bun $SYMPHONY_LINEAR remove-label <IDENTIFIER> "label-name"        # Remove a label
+bun $SYMPHONY_LINEAR swap-label <IDENTIFIER>                       # Swap labels atomically
+    --remove "old-label" --add "new-label"
+```
+
+### Downloading Attachments
+
+If an issue description or comments contain images (screenshots, diagrams, mockups, etc.), download them so you can view them:
+
+```
+bun $SYMPHONY_LINEAR download-attachments <IDENTIFIER> --output ./attachments
+```
+
+This extracts all image URLs from the issue description, comments, and Linear attachments, then downloads them to the specified directory. Output is a JSON manifest mapping original URLs to local file paths.
+
+**When to use:** Always download attachments before starting work on an issue that references visual content (UI mockups, screenshots of bugs, design specs, diagrams). The downloaded files can then be read directly to understand the visual context.
+
+### Error Handling
+If you encounter an unrecoverable error (e.g. missing dependencies, broken build that you cannot fix, unclear requirements), set the issue state to "Error" so that the orchestrator can retry later:
+```
+bun $SYMPHONY_LINEAR update-issue <IDENTIFIER> --state "Error"
+```
+
+### Notes
+- `<IDENTIFIER>` is the issue identifier (e.g. SYM-123) or UUID
+- Priority values: 1=urgent, 2=high, 3=medium, 4=low
+- For `create-issue`, `--parent` takes an identifier and resolves team/project automatically
+- All commands output JSON on success
+- Use `swap-label` when transitioning between workflow stages (e.g. `agent:prd` -> `agent:prd:progress`)