ranni-mcp 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ranni-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Provider-agnostic multi-agent orchestration MCP server",
   "repository": {
     "type": "git",

package/src/config.ts

@@ -4,6 +4,13 @@ import { parse } from 'yaml';
 import { z } from 'zod';
 import type { Config } from './types.js';
 
+const GitConfigSchema = z.object({
+  auto_pr: z.boolean().default(true),
+  branch_prefix: z.string().default('ranni'),
+  base_branch: z.string().default('main'),
+  await_merge: z.boolean().default(false)
+})
+
 const ConfigSchema = z.object({
   worker: z.object({
     command: z.string(),
@@ -11,6 +18,7 @@ const ConfigSchema = z.object({
   }),
   max_workers: z.number().int().min(1).default(3),
   persist_runs: z.boolean().default(false),
+  git: GitConfigSchema.optional(),
   dirs: z.record(z.string()),
   manager_context: z.string().optional()
 })

package/src/index.ts

@@ -4,16 +4,20 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { loadConfig } from './config.js';
 import { detectConflict, handleConflict } from './conflict.js';
 import {
+    autoAcknowledge,
     cancelTask,
     complete,
     enqueue,
     getPendingResults,
     getSnapshot,
+    markAwaitingReview,
     queuePath,
     readQueue,
     resetInterrupted,
-    startNext
+    startNext,
+    writeQueue
 } from './queue.js';
+import { commitAndOpenPR, pollPRStatus, pushToPRBranch } from './pr.js';
 import { initRun } from './runs.js';
 import type { Config, Task } from './types.js';
 import { runWorker } from './worker.js';
@@ -23,7 +27,8 @@ const DEFAULT_MANAGER_CONTEXT = `ORCHESTRATOR RULES (read before every action):
 2. Each task must be self-contained: include all file paths, context, and background the worker needs.
 3. Use depends_on when task B genuinely needs task A's output to be on disk first.
 4. When a worker returns needs_help, surface the question to the user before dispatching a follow-up.
-5. When a worker returns error, decide: retry, dispatch a corrected version, or inform the user.`
+5. When a worker returns error, decide: retry, dispatch a corrected version, or inform the user.
+6. Tasks in awaiting_review are waiting for their PR to be merged — do not cancel them.`
 
 function formatFooter(managerContext: string): string {
   return `\n\n---\n${managerContext}`
@@ -38,7 +43,7 @@ async function main() {
 
   let activeCount = 0
 
-  async function tickPool() {
+  function tickPool() {
     const available = config.max_workers - activeCount
     if (available <= 0) return
 
@@ -55,6 +60,17 @@ async function main() {
 
   setInterval(tickPool, 200)
 
+  if (config.git?.auto_pr) {
+    setInterval(() => {
+      pollPRStatus(qPath, config, tasks => {
+        enqueue(qPath, tasks)
+        tickPool()
+      }).catch(err => {
+        process.stderr.write(`[ranni] Poll error: ${err}\n`)
+      })
+    }, 60_000)
+  }
+
   const server = new Server({ name: 'ranni-mcp', version: '0.1.0' }, { capabilities: { tools: {} } })
 
   const footer = formatFooter(config.manager_context ?? DEFAULT_MANAGER_CONTEXT)
@@ -105,7 +121,7 @@ async function main() {
       },
       {
         name: 'list_active_workers',
-        description: 'Snapshot of the current queue: running workers, pending tasks, and free slots.',
+        description: 'Snapshot of the current queue: running workers, pending tasks, and PRs awaiting review.',
         inputSchema: { type: 'object', properties: {} }
       },
       {
@@ -176,18 +192,22 @@ async function main() {
       case 'list_active_workers': {
         const snapshot = getSnapshot(qPath)
         const runningList = snapshot.running
-          .map(t => `  [running] ${t.id} (${t.dir}) — started ${t.started_at}`)
+          .map(t => `  [running]         ${t.id} (${t.dir}) — started ${t.started_at}`)
           .join('\n')
         const queuedList = snapshot.queued
           .map(
             t =>
-              `  [queued]  ${t.id} (${t.dir})${t.depends_on?.length ? ` — waiting on: ${t.depends_on.join(', ')}` : ''}`
+              `  [queued]          ${t.id} (${t.dir})${t.depends_on?.length ? ` — waiting on: ${t.depends_on.join(', ')}` : ''}`
           )
           .join('\n')
+        const awaitingList = snapshot.awaiting
+          .map(t => `  [awaiting_review] ${t.id} (${t.dir}) — ${t.result?.pr_url ?? 'PR pending'}`)
+          .join('\n')
         const lines = [
           `Workers: ${activeCount}/${config.max_workers} active`,
           runningList || '  (none running)',
-          queuedList || '  (queue empty)'
+          queuedList || '  (queue empty)',
+          awaitingList || '  (no PRs awaiting review)'
         ].join('\n')
         return { content: [{ type: 'text', text: lines + footer }] }
       }
@@ -207,7 +227,8 @@ async function main() {
             const summary = r ? r.summary : '(no summary)'
             const files = r?.files_changed?.length ? `\n  Files: ${r.files_changed.join(', ')}` : ''
             const msg = r?.message ? `\n  Message: ${r.message}` : ''
-            return `[${status.toUpperCase()}] ${t.id} (${t.dir})\n  ${summary}${files}${msg}`
+            const pr = r?.pr_url ? `\n  PR: ${r.pr_url}` : ''
+            return `[${status.toUpperCase()}] ${t.id} (${t.dir})\n  ${summary}${files}${msg}${pr}`
           })
           .join('\n\n')
 
@@ -247,13 +268,41 @@ async function runWorkerAsync(
 
     runLogger?.updateSummary(readQueue(qPath).tasks)
 
-    const queue = readQueue(qPath)
-    const conflict = detectConflict(result, queue, task.id)
+    const resolvedDir = config.dirs[task.dir]!
+
+    const conflict = detectConflict(result, readQueue(qPath), task.id)
     if (conflict) {
-      const resolvedDir = config.dirs[task.dir]!
       await handleConflict(qPath, task, conflict, resolvedDir)
     }
 
+    if (task.parent_task_id && result.status === 'done') {
+      // Correction worker: push changes to the parent task's existing PR branch
+      const parentTask = readQueue(qPath).tasks.find(t => t.id === task.parent_task_id)
+      if (parentTask?.pr_branch) {
+        await pushToPRBranch(task, result, resolvedDir, parentTask.pr_branch)
+      }
+      autoAcknowledge(qPath, task.id)
+    } else if (!task.parent_task_id && result.status === 'done') {
+      // Normal worker: open a PR, then either babysit it or just record the URL
+      const pr = await commitAndOpenPR(task, result, config, resolvedDir)
+      if (pr) {
+        if (config.git?.await_merge) {
+          markAwaitingReview(qPath, task.id, pr.prUrl, pr.branch)
+        } else {
+          // PR created, task stays done — store url+branch and mark unmerged so
+          // depends_on chains wait for the poll to confirm the PR landed
+          const q = readQueue(qPath)
+          const t = q.tasks.find(x => x.id === task.id)
+          if (t) {
+            t.pr_branch = pr.branch
+            t.pr_merged = false
+            if (t.result) t.result.pr_url = pr.prUrl
+            writeQueue(qPath, q)
+          }
+        }
+      }
+    }
+
     if (runLogger) {
       const stdout = result.message ?? result.summary
       runLogger.logTask(task.id, stdout)

package/src/pr.ts

@@ -0,0 +1,291 @@
+import { execSync } from 'child_process'
+import { relative } from 'path'
+import { markPRMerged, readQueue, updatePrCommentCursor, writeQueue } from './queue.js'
+import type { Config, Task, WorkerResult } from './types.js'
+
+// Promise-chain mutex: only one git operation runs at a time to avoid index corruption
+let gate: Promise<void> = Promise.resolve()
+
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, { cwd, encoding: 'utf8' }).trim()
+}
+
+function findGitRoot(dir: string): string {
+  return run('git rev-parse --show-toplevel', dir)
+}
+
+function withGateLock<T>(fn: () => Promise<T>): Promise<T> {
+  let release!: () => void
+  const next = new Promise<void>(r => { release = r })
+  const prev = gate
+  gate = next
+  return prev.then(fn).finally(release)
+}
+
+function gitPaths(resolvedDir: string, gitRoot: string, filesChanged: string[]): string[] {
+  const rel = relative(gitRoot, resolvedDir)
+  return filesChanged.map(f => (rel ? `${rel}/${f}` : f))
+}
+
+function stashAndCheckout(gitRoot: string, label: string, branch: string): { origBranch: string; stashed: boolean } {
+  const origBranch = run('git rev-parse --abbrev-ref HEAD', gitRoot)
+  const stashOut = run(`git stash push --include-untracked -m "ranni-${label}"`, gitRoot)
+  const stashed = !stashOut.includes('No local changes to save')
+  run(`git checkout ${branch}`, gitRoot)
+  return { origBranch, stashed }
+}
+
+function restoreAndReturn(gitRoot: string, origBranch: string, stashed: boolean): void {
+  run(`git checkout ${origBranch}`, gitRoot)
+  if (stashed) run('git stash pop', gitRoot)
+}
+
+function cherryPickFromStash(gitRoot: string, paths: string[]): void {
+  for (const p of paths) {
+    try {
+      run(`git checkout stash@{0} -- "${p}"`, gitRoot)
+    } catch {
+      // path may differ between resolvedDir and gitRoot — skip
+    }
+  }
+}
+
+// ──────────────────────────────────────────────
+// Create branch + PR for a finished task
+// ──────────────────────────────────────────────
+
+export async function commitAndOpenPR(
+  task: Task,
+  result: WorkerResult,
+  config: Config,
+  resolvedDir: string
+): Promise<{ prUrl: string; branch: string } | undefined> {
+  const gitCfg = config.git
+  if (!gitCfg?.auto_pr || result.status !== 'done' || result.files_changed.length === 0) {
+    return undefined
+  }
+  return withGateLock(() => doCommitAndPR(task, result, gitCfg, resolvedDir))
+}
+
+async function doCommitAndPR(
+  task: Task,
+  result: WorkerResult,
+  gitCfg: NonNullable<Config['git']>,
+  resolvedDir: string
+): Promise<{ prUrl: string; branch: string } | undefined> {
+  const branch = `${gitCfg.branch_prefix}/${task.id}`
+
+  let gitRoot: string
+  try {
+    gitRoot = findGitRoot(resolvedDir)
+  } catch {
+    process.stderr.write(`[ranni] PR skipped for ${task.id}: not in a git repository\n`)
+    return undefined
+  }
+
+  const paths = gitPaths(resolvedDir, gitRoot, result.files_changed)
+  let origBranch = gitCfg.base_branch
+  let stashed = false
+
+  try {
+    origBranch = run('git rev-parse --abbrev-ref HEAD', gitRoot)
+
+    const stashOut = run(`git stash push --include-untracked -m "ranni-temp-${task.id}"`, gitRoot)
+    stashed = !stashOut.includes('No local changes to save')
+
+    run(`git fetch origin ${gitCfg.base_branch} --quiet`, gitRoot)
+    run(`git checkout -b ${branch} origin/${gitCfg.base_branch}`, gitRoot)
+
+    if (stashed) cherryPickFromStash(gitRoot, paths)
+
+    run(`git add -- ${paths.map(p => `"${p}"`).join(' ')}`, gitRoot)
+    run(`git commit -m ${JSON.stringify(`${result.summary}\n\nTask: ${task.id}`)}`, gitRoot)
+    run(`git push -u origin ${branch}`, gitRoot)
+
+    restoreAndReturn(gitRoot, origBranch, stashed)
+
+    const prBody = buildPrBody(task, result)
+    const prUrl = run(
+      `gh pr create --title ${JSON.stringify(result.summary)} --body ${JSON.stringify(prBody)} --base ${gitCfg.base_branch} --head ${branch}`,
+      gitRoot
+    )
+
+    process.stderr.write(`[ranni] PR opened for ${task.id}: ${prUrl}\n`)
+    return { prUrl, branch }
+  } catch (err) {
+    process.stderr.write(`[ranni] PR creation failed for ${task.id}: ${err}\n`)
+    try { restoreAndReturn(gitRoot!, origBranch, stashed) } catch {}
+    return undefined
+  }
+}
+
+// ──────────────────────────────────────────────
+// Push a correction worker's changes to an existing PR branch
+// ──────────────────────────────────────────────
+
+export async function pushToPRBranch(
+  task: Task,
+  result: WorkerResult,
+  resolvedDir: string,
+  prBranch: string
+): Promise<void> {
+  return withGateLock(() => doPushToPRBranch(task, result, resolvedDir, prBranch))
+}
+
+async function doPushToPRBranch(
+  task: Task,
+  result: WorkerResult,
+  resolvedDir: string,
+  prBranch: string
+): Promise<void> {
+  let gitRoot: string
+  try {
+    gitRoot = findGitRoot(resolvedDir)
+  } catch {
+    process.stderr.write(`[ranni] Push skipped for ${task.id}: not in a git repository\n`)
+    return
+  }
+
+  const paths = gitPaths(resolvedDir, gitRoot, result.files_changed)
+  let origBranch = prBranch
+  let stashed = false
+
+  try {
+    ;({ origBranch, stashed } = stashAndCheckout(gitRoot, `correction-${task.id}`, prBranch))
+
+    if (stashed) cherryPickFromStash(gitRoot, paths)
+
+    run(`git add -- ${paths.map(p => `"${p}"`).join(' ')}`, gitRoot)
+    run(`git commit -m "Address review feedback (task ${task.id})"`, gitRoot)
+    run(`git push origin ${prBranch}`, gitRoot)
+
+    restoreAndReturn(gitRoot, origBranch, stashed)
+    process.stderr.write(`[ranni] Pushed correction for ${task.id} → ${prBranch}\n`)
+  } catch (err) {
+    process.stderr.write(`[ranni] Push correction failed for ${task.id}: ${err}\n`)
+    try { restoreAndReturn(gitRoot!, origBranch, stashed) } catch {}
+  }
+}
+
+// ──────────────────────────────────────────────
+// Poll open PRs: merge detection (always) + comment relay (await_merge only)
+// ──────────────────────────────────────────────
+
+type CorrectionTask = Omit<Task, 'status' | 'created_at' | 'started_at' | 'finished_at' | 'result' | 'acknowledged'>
+
+export async function pollPRStatus(
+  qPath: string,
+  config: Config,
+  dispatch: (tasks: CorrectionTask[]) => void
+): Promise<void> {
+  const queue = readQueue(qPath)
+  const awaitMerge = config.git?.await_merge ?? false
+
+  // Track all tasks that have an open PR not yet confirmed merged
+  const tracked = queue.tasks.filter(
+    t => t.pr_branch && t.pr_merged !== true && (t.status === 'done' || t.status === 'awaiting_review')
+  )
+  if (tracked.length === 0) return
+
+  for (const task of tracked) {
+    const prUrl = task.result?.pr_url
+    if (!prUrl) continue
+
+    try {
+      const resolvedDir = config.dirs[task.dir]
+      if (!resolvedDir) continue
+
+      let gitRoot: string
+      try {
+        gitRoot = findGitRoot(resolvedDir)
+      } catch {
+        continue
+      }
+
+      // Fetch comments only when babysitting an awaiting_review task
+      const needComments = awaitMerge && task.status === 'awaiting_review'
+      const fields = needComments ? 'state,comments' : 'state'
+      const raw = run(`gh pr view "${prUrl}" --json ${fields}`, gitRoot)
+      const data = JSON.parse(raw) as {
+        state: string
+        comments?: Array<{ body: string; createdAt: string; author: { login: string } }>
+      }
+
+      if (data.state === 'MERGED') {
+        // Works for both done and awaiting_review — markPRMerged handles both
+        markPRMerged(qPath, task.id)
+        process.stderr.write(`[ranni] PR merged — ${task.id}\n`)
+        continue
+      }
+
+      if (data.state === 'CLOSED' && task.status === 'awaiting_review') {
+        const q = readQueue(qPath)
+        const t = q.tasks.find(x => x.id === task.id)
+        if (t) {
+          t.status = 'error'
+          if (t.result) t.result.message = 'PR closed without merging'
+          writeQueue(qPath, q)
+        }
+        process.stderr.write(`[ranni] PR closed without merge — ${task.id}\n`)
+        continue
+      }
+
+      // Comment relay only when babysitting
+      if (!needComments) continue
+
+      const cursor = task.pr_comment_cursor ?? '1970-01-01T00:00:00Z'
+      const newComments = (data.comments ?? []).filter(c => c.createdAt > cursor)
+      if (newComments.length === 0) continue
+
+      const latestTime = newComments.reduce((m, c) => (c.createdAt > m ? c.createdAt : m), cursor)
+      updatePrCommentCursor(qPath, task.id, latestTime)
+
+      const existingCorrections = queue.tasks.filter(t => t.parent_task_id === task.id).length
+      const correctionId = `${task.id}-correction-${existingCorrections + 1}`
+      const commentsText = newComments.map(c => `**${c.author.login}**: ${c.body}`).join('\n\n')
+
+      dispatch([{
+        id: correctionId,
+        dir: task.dir,
+        task: buildCorrectionPrompt(task, commentsText),
+        context: task.context,
+        parent_task_id: task.id
+      }])
+
+      process.stderr.write(`[ranni] ${newComments.length} new comment(s) on ${task.id} — dispatching ${correctionId}\n`)
+    } catch (err) {
+      process.stderr.write(`[ranni] Poll error for ${task.id}: ${err}\n`)
+    }
+  }
+}
+
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+
+function buildCorrectionPrompt(task: Task, commentsText: string): string {
+  const prUrl = task.result?.pr_url ?? '(see context)'
+  return `You are addressing reviewer feedback on an open pull request.
+
+PR: ${prUrl}
+
+## Reviewer Comments
+${commentsText}
+
+## Original Task
+${task.task}
+
+Apply only the changes needed to satisfy the reviewer's comments. Do not commit, push, or open a new PR — the orchestrator handles that.`
+}
+
+function buildPrBody(task: Task, result: WorkerResult): string {
+  const sections: string[] = []
+  sections.push(`## Task\n${task.task}`)
+  if (task.context) sections.push(`## Context\n${task.context}`)
+  if (result.files_changed.length) {
+    sections.push(`## Files Changed\n${result.files_changed.map(f => `- \`${f}\``).join('\n')}`)
+  }
+  if (result.message) sections.push(`## Notes\n${result.message}`)
+  sections.push(`_Generated by [ranni](https://github.com/filfp/ranni) · task \`${task.id}\`_`)
+  return sections.join('\n\n')
+}

package/src/queue.ts

@@ -43,7 +43,12 @@ export function enqueue(
 
 export function startNext(path: string): Task | null {
   const queue = readQueue(path)
-  const doneIds = new Set(queue.tasks.filter(t => t.status === 'done').map(t => t.id))
+  // A done task with a PR only satisfies depends_on after the PR lands in base_branch
+  const doneIds = new Set(
+    queue.tasks
+      .filter(t => t.status === 'done' && (!t.pr_branch || t.pr_merged === true))
+      .map(t => t.id)
+  )
 
   const idx = queue.tasks.findIndex(t => {
     if (t.status !== 'pending') return false
@@ -85,6 +90,43 @@ export function markConflict(path: string, id: string): void {
   }
 }
 
+export function markAwaitingReview(path: string, id: string, prUrl: string, branch: string): void {
+  const queue = readQueue(path)
+  const task = queue.tasks.find(t => t.id === id)
+  if (!task) return
+  task.status = 'awaiting_review'
+  task.pr_branch = branch
+  task.pr_merged = false
+  if (task.result) task.result.pr_url = prUrl
+  writeQueue(path, queue)
+}
+
+// Called when the PR lands. Moves awaiting_review → done; for already-done tasks just sets the flag.
+export function markPRMerged(path: string, id: string): void {
+  const queue = readQueue(path)
+  const task = queue.tasks.find(t => t.id === id)
+  if (!task) return
+  task.pr_merged = true
+  if (task.status === 'awaiting_review') task.status = 'done'
+  writeQueue(path, queue)
+}
+
+export function updatePrCommentCursor(path: string, id: string, cursor: string): void {
+  const queue = readQueue(path)
+  const task = queue.tasks.find(t => t.id === id)
+  if (!task) return
+  task.pr_comment_cursor = cursor
+  writeQueue(path, queue)
+}
+
+export function autoAcknowledge(path: string, id: string): void {
+  const queue = readQueue(path)
+  const task = queue.tasks.find(t => t.id === id)
+  if (!task) return
+  task.acknowledged = true
+  writeQueue(path, queue)
+}
+
 export function resetInterrupted(path: string): void {
   const queue = readQueue(path)
   let changed = false
@@ -126,14 +168,12 @@ export function getPendingResults(path: string, drain: boolean): Task[] {
 export function getSnapshot(path: string): {
   running: Task[]
   queued: Task[]
-  slots_free: number
-  max_workers: number
+  awaiting: Task[]
 } {
   const queue = readQueue(path)
   return {
     running: queue.tasks.filter(t => t.status === 'running'),
     queued: queue.tasks.filter(t => t.status === 'pending'),
-    slots_free: 0,
-    max_workers: 0
+    awaiting: queue.tasks.filter(t => t.status === 'awaiting_review')
   }
 }

package/src/types.ts

@@ -1,4 +1,12 @@
-export type TaskStatus = 'pending' | 'running' | 'done' | 'done_with_conflict' | 'needs_help' | 'error' | 'cancelled'
+export type TaskStatus =
+  | 'pending'
+  | 'running'
+  | 'done'
+  | 'done_with_conflict'
+  | 'needs_help'
+  | 'error'
+  | 'cancelled'
+  | 'awaiting_review'
 
 export type Task = {
   id: string
@@ -14,6 +22,12 @@ export type Task = {
   finished_at: string | null
   result: WorkerResult | null
   acknowledged: boolean
+  // PR tracking fields (set when auto_pr creates a branch)
+  pr_branch?: string
+  pr_merged?: boolean         // true once the PR lands in base_branch; gates depends_on satisfaction
+  pr_comment_cursor?: string  // ISO timestamp — comments after this are unread (await_merge only)
+  // Set on correction workers dispatched in response to review comments
+  parent_task_id?: string
 }
 
 export type WorkerResult = {
@@ -22,6 +36,7 @@ export type WorkerResult = {
   files_changed: string[]
   message?: string
   exit_code: number
+  pr_url?: string
 }
 
 export type QueueFile = {
@@ -29,10 +44,18 @@ export type QueueFile = {
   touched_files: Record<string, string>
 }
 
+export type GitConfig = {
+  auto_pr: boolean
+  branch_prefix: string
+  base_branch: string
+  await_merge: boolean
+}
+
 export type Config = {
   worker: { command: string; args: string[] }
   max_workers: number
   persist_runs: boolean
+  git?: GitConfig
   dirs: Record<string, string>
   manager_context?: string
 }

package/templates/.agents.yaml

@@ -1,17 +0,0 @@
-worker:
-  command: claude
-  args: [--print, --dangerously-skip-permissions]
-
-max_workers: 3
-persist_runs: false
-
-dirs:
-  root: .
-  # Add your project directories:
-  # backend: ./backend
-  # web: ./apps/web
-  # mobile: ./apps/mobile
-
-# Optional — injected into every MCP tool response as a reminder to the manager
-# manager_context: |
-#   Always call get_pending_results() before dispatching new tasks.