@weldr/runr 0.3.0

package/dist/workers/codex.js

@@ -0,0 +1,162 @@
+import { execa } from 'execa';
+/**
+ * Extract assistant text from Codex JSONL output.
+ *
+ * Codex emits various event types. We look for text in priority order:
+ * 1. agent_message / message items (the canonical final response)
+ * 2. Any item.completed with text content
+ * 3. turn.completed or response events with content
+ *
+ * Returns concatenated text from all matching events.
+ */
+function extractTextFromCodexJsonl(output) {
+    const lines = output.trim().split('\n').filter(Boolean);
+    const texts = [];
+    for (const line of lines) {
+        try {
+            const event = JSON.parse(line);
+            // Priority 1: agent_message or message items
+            if (event.type === 'item.completed' && event.item) {
+                const itemType = event.item.type;
+                if (itemType === 'agent_message' || itemType === 'message') {
+                    const text = event.item.text || event.item.content;
+                    if (text)
+                        texts.push(text);
+                    continue;
+                }
+            }
+            // Priority 2: Any item.completed with text (reasoning, etc.)
+            if (event.type === 'item.completed' && event.item?.text) {
+                texts.push(event.item.text);
+                continue;
+            }
+            // Priority 3: Top-level message/response events
+            if ((event.type === 'response' || event.type === 'turn.completed') && event.message) {
+                const text = event.message.content || event.message.text;
+                if (text)
+                    texts.push(text);
+                continue;
+            }
+            // Priority 4: Direct content on event
+            if (event.type === 'response' && (event.content || event.text)) {
+                texts.push(event.content || event.text || '');
+            }
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return texts.join('\n');
+}
+export async function runCodex(input) {
+    const { bin, args } = input.worker;
+    // Build argv: base args + repo path via -C
+    const argv = [...args, '-C', input.repo_path];
+    try {
+        const result = await execa(bin, argv, {
+            cwd: input.repo_path,
+            input: input.prompt,
+            stdout: 'pipe',
+            stderr: 'pipe',
+            timeout: 300000 // 5 min timeout
+        });
+        const rawOutput = result.stdout;
+        const text = input.worker.output === 'jsonl'
+            ? extractTextFromCodexJsonl(rawOutput)
+            : rawOutput;
+        return {
+            status: result.exitCode === 0 ? 'ok' : 'failed',
+            commands_run: [`${bin} ${argv.join(' ')}`],
+            observations: [text || rawOutput]
+        };
+    }
+    catch (error) {
+        const err = error;
+        const output = err.stdout || err.stderr || err.message || 'Codex command failed';
+        return {
+            status: 'failed',
+            commands_run: [`${bin} ${argv.join(' ')}`],
+            observations: [output]
+        };
+    }
+}
+/**
+ * Classify error output into categories for preflight reporting.
+ */
+function classifyError(output) {
+    const lower = output.toLowerCase();
+    // Auth errors
+    if (lower.includes('oauth') || lower.includes('token expired') ||
+        lower.includes('authentication') || lower.includes('login') ||
+        lower.includes('401') || lower.includes('unauthorized') ||
+        lower.includes('not authenticated') || lower.includes('sign in')) {
+        return 'auth';
+    }
+    // Network errors
+    if (lower.includes('enotfound') || lower.includes('econnrefused') ||
+        lower.includes('network') || lower.includes('timeout') ||
+        lower.includes('econnreset') || lower.includes('socket')) {
+        return 'network';
+    }
+    // Rate limit errors
+    if (lower.includes('rate limit') || lower.includes('429') ||
+        lower.includes('too many requests') || lower.includes('quota')) {
+        return 'rate_limit';
+    }
+    return 'unknown';
+}
+/**
+ * Ping Codex to verify auth and connectivity.
+ * Success = process exits 0 within timeout.
+ */
+export async function pingCodex(worker) {
+    const { bin, args } = worker;
+    const start = Date.now();
+    const pingPrompt = 'Respond with exactly: ok';
+    // Build minimal argv (no -C repo path for ping)
+    const argv = [...args];
+    try {
+        const result = await execa(bin, argv, {
+            input: pingPrompt,
+            stdout: 'pipe',
+            stderr: 'pipe',
+            timeout: 15000 // 15s timeout for ping
+        });
+        const ms = Date.now() - start;
+        // Success = exit code 0
+        if (result.exitCode === 0) {
+            return { ok: true, worker: 'codex', ms };
+        }
+        // Non-zero exit
+        const output = result.stderr || result.stdout || '';
+        return {
+            ok: false,
+            worker: 'codex',
+            ms,
+            category: classifyError(output),
+            message: output.slice(0, 200)
+        };
+    }
+    catch (error) {
+        const ms = Date.now() - start;
+        const err = error;
+        const output = err.stderr || err.stdout || err.message || 'Ping failed';
+        // Check for timeout
+        if (err.code === 'ETIMEDOUT' || (err.message && err.message.includes('timed out'))) {
+            return {
+                ok: false,
+                worker: 'codex',
+                ms,
+                category: 'network',
+                message: 'Ping timed out'
+            };
+        }
+        return {
+            ok: false,
+            worker: 'codex',
+            ms,
+            category: classifyError(output),
+            message: output.slice(0, 200)
+        };
+    }
+}

package/dist/workers/json.js

@@ -0,0 +1,22 @@
+export function extractJsonBlock(output) {
+    const start = output.indexOf('BEGIN_JSON');
+    const end = output.indexOf('END_JSON');
+    if (start === -1 || end === -1 || end <= start) {
+        return null;
+    }
+    return output.slice(start + 'BEGIN_JSON'.length, end).trim();
+}
+export function parseJsonWithSchema(output, schema) {
+    const block = extractJsonBlock(output) ?? output.trim();
+    try {
+        const parsed = JSON.parse(block);
+        const result = schema.safeParse(parsed);
+        if (!result.success) {
+            return { error: result.error.message };
+        }
+        return { data: result.data };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : 'Invalid JSON' };
+    }
+}

package/dist/workers/mock.js

@@ -0,0 +1,193 @@
+/**
+ * Mock worker for testing auto-resume and stall detection.
+ *
+ * Controlled via AGENT_MOCK_WORKER env var:
+ * - "hang": Never resolves (simulates hung worker)
+ * - "hang_once": First call hangs, subsequent calls succeed
+ * - "delay_5s": Resolves after 5 seconds with valid output
+ * - "timeout_once_then_ok": First call times out (triggers worker_call_timeout), then succeeds
+ * - "no_changes_no_evidence": Returns no_changes_needed without evidence (triggers insufficient_evidence)
+ * - unset/other: Not used (real workers are used)
+ *
+ * The mock worker returns valid JSON output for the stage being tested.
+ */
+// Track call count for hang_once mode
+let callCount = 0;
+/** Valid mock worker modes */
+const MOCK_WORKER_MODES = [
+    'hang',
+    'hang_once',
+    'delay_5s',
+    'timeout_once_then_ok',
+    'no_changes_no_evidence',
+    'review_always_request_changes'
+];
+/**
+ * Check if mock worker mode is enabled.
+ */
+export function isMockWorkerEnabled() {
+    const mode = process.env.AGENT_MOCK_WORKER;
+    return MOCK_WORKER_MODES.includes(mode);
+}
+/**
+ * Get mock worker mode.
+ */
+export function getMockWorkerMode() {
+    return process.env.AGENT_MOCK_WORKER;
+}
+/**
+ * Reset mock worker state (for tests).
+ */
+export function resetMockWorker() {
+    callCount = 0;
+}
+/**
+ * Generate valid JSON output based on stage.
+ * This ensures the mock can produce parseable responses.
+ * Uses specific prompt template markers to avoid false matches in task content.
+ */
+function generateValidOutput(prompt) {
+    // Detect stage from prompt template headers (avoids matching task content)
+    if (prompt.includes('# Planner Prompt') || prompt.includes('You are the planning model')) {
+        return JSON.stringify({
+            milestones: [
+                {
+                    goal: 'Mock milestone for testing',
+                    files_expected: ['src/test.ts'],
+                    done_checks: ['Build passes', 'Tests pass'],
+                    risk_level: 'low'
+                }
+            ]
+        });
+    }
+    if (prompt.includes('# Implementer Prompt') || prompt.includes('You are the implementer')) {
+        return JSON.stringify({
+            status: 'ok',
+            handoff_memo: 'Mock implementation complete.'
+        });
+    }
+    if (prompt.includes('# Reviewer Prompt') || prompt.includes('You are the reviewer model')) {
+        return JSON.stringify({
+            status: 'approve',
+            changes: []
+        });
+    }
+    // Default response
+    return JSON.stringify({ result: 'ok' });
+}
+/**
+ * Run mock worker with configured behavior.
+ */
+export async function runMockWorker(input) {
+    const mode = getMockWorkerMode();
+    callCount++;
+    console.log(`[mock-worker] Mode: ${mode}, Call: ${callCount}`);
+    switch (mode) {
+        case 'hang':
+            // Hang for 20 seconds then fail - allows watchdog (10s intervals) to catch the 12s cap
+            console.log('[mock-worker] Hanging for 20 seconds...');
+            await new Promise(resolve => setTimeout(resolve, 20000));
+            return {
+                status: 'failed',
+                commands_run: ['mock-worker'],
+                observations: ['Worker timed out (mock)']
+            };
+        case 'hang_once':
+            // First call hangs (20s), subsequent calls succeed
+            if (callCount === 1) {
+                console.log('[mock-worker] First call - hanging for 20 seconds...');
+                await new Promise(resolve => setTimeout(resolve, 20000));
+                return {
+                    status: 'failed',
+                    commands_run: ['mock-worker'],
+                    observations: ['Worker timed out (mock hang_once first call)']
+                };
+            }
+            console.log('[mock-worker] Subsequent call - returning success');
+            return {
+                status: 'ok',
+                commands_run: ['mock-worker'],
+                observations: [generateValidOutput(input.prompt)]
+            };
+        case 'delay_5s':
+            // Delay 5 seconds then succeed
+            console.log('[mock-worker] Delaying 5 seconds...');
+            await new Promise(resolve => setTimeout(resolve, 5000));
+            return {
+                status: 'ok',
+                commands_run: ['mock-worker'],
+                observations: [generateValidOutput(input.prompt)]
+            };
+        case 'timeout_once_then_ok':
+            // First call times out (for auto-resume testing), subsequent calls succeed
+            if (callCount === 1) {
+                // Use AGENT_MOCK_TIMEOUT_MS for fast testing, default to 65s for compatibility
+                const timeoutMs = Number.parseInt(process.env.AGENT_MOCK_TIMEOUT_MS ?? '', 10) || 65000;
+                console.log(`[mock-worker] First call - sleeping ${timeoutMs}ms to trigger stall timeout...`);
+                await new Promise(resolve => setTimeout(resolve, timeoutMs));
+                return {
+                    status: 'failed',
+                    commands_run: ['mock-worker'],
+                    observations: ['Worker stall timeout (mock timeout_once_then_ok)']
+                };
+            }
+            console.log('[mock-worker] Subsequent call - returning success');
+            return {
+                status: 'ok',
+                commands_run: ['mock-worker'],
+                observations: [generateValidOutput(input.prompt)]
+            };
+        case 'no_changes_no_evidence':
+            // Returns no_changes_needed without evidence (triggers insufficient_evidence)
+            console.log('[mock-worker] Returning no_changes_needed without evidence');
+            if (input.prompt.includes('IMPLEMENT') || input.prompt.includes('implement')) {
+                return {
+                    status: 'ok',
+                    commands_run: ['mock-worker'],
+                    observations: [JSON.stringify({
+                            status: 'no_changes_needed',
+                            handoff_memo: 'No changes needed (mock)',
+                            evidence: null // Missing evidence triggers insufficient_evidence
+                        })]
+                };
+            }
+            // For other phases, return normal success
+            return {
+                status: 'ok',
+                commands_run: ['mock-worker'],
+                observations: [generateValidOutput(input.prompt)]
+            };
+        case 'review_always_request_changes':
+            // Review always returns request_changes with identical message (triggers review_loop_detected)
+            // Use more specific phase detection to avoid false matches in task content
+            console.log('[mock-worker] review_always_request_changes mode');
+            if (input.prompt.includes('# Reviewer Prompt') || input.prompt.includes('You are the reviewer model')) {
+                console.log('[mock-worker] Returning request_changes for REVIEW phase');
+                return {
+                    status: 'ok',
+                    commands_run: ['mock-worker'],
+                    observations: [JSON.stringify({
+                            status: 'request_changes',
+                            changes: [
+                                'The done checks require testing the actual CLI behavior.',
+                                'Please run the CLI commands to confirm the implementation works.'
+                            ]
+                        })]
+                };
+            }
+            // For PLAN and IMPLEMENT, return normal success
+            console.log('[mock-worker] Returning success for non-REVIEW phase');
+            return {
+                status: 'ok',
+                commands_run: ['mock-worker'],
+                observations: [generateValidOutput(input.prompt)]
+            };
+        default:
+            // Should not reach here if isMockWorkerEnabled() is checked first
+            return {
+                status: 'failed',
+                commands_run: ['mock-worker'],
+                observations: ['Mock worker called but not configured']
+            };
+    }
+}

package/dist/workers/prompts.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Get the directory of this module (works in ESM)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function loadTemplate(name) {
+    // Resolve relative to the agent-framework's templates directory, not CWD
+    const target = path.resolve(__dirname, '..', '..', 'templates', 'prompts', name);
+    return fs.readFileSync(target, 'utf-8');
+}
+export function buildPlanPrompt(input) {
+    const template = loadTemplate('planner.md');
+    return [
+        template,
+        '',
+        `Scope allowlist: ${input.scopeAllowlist.join(', ')}`,
+        '(All files_expected paths must match one of these patterns)',
+        '',
+        'Task:',
+        input.taskText,
+        '',
+        'Output JSON between markers:',
+        'BEGIN_JSON',
+        '{"milestones": [{"goal": "...", "files_expected": ["..."], "done_checks": ["..."], "risk_level": "medium"}], "risk_map": ["..."], "do_not_touch": ["..."]}',
+        'END_JSON'
+    ].join('\n');
+}
+export function buildImplementPrompt(input) {
+    const template = loadTemplate('implementer.md');
+    const filesExpected = input.milestone.files_expected ?? [];
+    const lines = [];
+    // Context pack goes first so agent sees verification bar + patterns before acting
+    if (input.contextPack) {
+        lines.push('## CONTEXT PACK (read first)', '', input.contextPack, '', '## END CONTEXT PACK', '');
+    }
+    lines.push(template, '', `Milestone goal: ${input.milestone.goal}`, `Files to create/modify: ${filesExpected.length > 0 ? filesExpected.join(', ') : '(infer from goal)'}`, `Done checks: ${input.milestone.done_checks.join('; ')}`, `Scope allowlist: ${input.scopeAllowlist.join(', ') || 'none'}`, `Scope denylist: ${input.scopeDenylist.join(', ') || 'none'}`, `Allow deps: ${input.allowDeps ? 'yes' : 'no'}`);
+    if (input.fixInstructions) {
+        lines.push('', '## FIX REQUIRED (Attempt ' + input.fixInstructions.attemptNumber + ')', '', 'The previous implementation failed verification. Fix the error below.', '', `Failed command: ${input.fixInstructions.failedCommand}`, '', 'Error output:', '```', input.fixInstructions.errorOutput.slice(0, 2000), '```', '', `Changed files: ${input.fixInstructions.changedFiles.join(', ') || 'none'}`, '', 'Fix the error and ensure all done_checks pass.');
+    }
+    lines.push('', 'Output JSON between markers:', 'BEGIN_JSON', '{"status": "ok", "handoff_memo": "...", "commands_run": [], "observations": []}', 'END_JSON');
+    return lines.join('\n');
+}
+export function buildReviewPrompt(input) {
+    const template = loadTemplate('reviewer.md');
+    const filesExpected = input.milestone.files_expected ?? [];
+    // Build verification summary section
+    let verificationSummaryText = '';
+    if (input.verificationSummary) {
+        verificationSummaryText = [
+            '',
+            '## Verification Summary (MUST CHECK)',
+            '',
+            '```json',
+            JSON.stringify(input.verificationSummary, null, 2),
+            '```',
+            ''
+        ].join('\n');
+    }
+    else {
+        // No summary provided - reviewer must request_changes
+        verificationSummaryText = [
+            '',
+            '## Verification Summary (MUST CHECK)',
+            '',
+            '```json',
+            JSON.stringify({
+                commands_required: ['(not provided)'],
+                commands_run: [],
+                commands_missing: ['(verification summary not available)'],
+                files_expected: filesExpected,
+                files_exist: filesExpected.map(f => ({ path: f, exists: '(not checked)' }))
+            }, null, 2),
+            '```',
+            '',
+            '⚠️ WARNING: Verification summary not available. You MUST request_changes.',
+            ''
+        ].join('\n');
+    }
+    return [
+        template,
+        verificationSummaryText,
+        `Milestone goal: ${input.milestone.goal}`,
+        `Files expected: ${filesExpected.length > 0 ? filesExpected.join(', ') : '(infer from goal)'}`,
+        `Done checks: ${input.milestone.done_checks.join('; ')}`,
+        '',
+        'Diff summary (includes untracked new files):',
+        input.diffSummary || '(no diff)',
+        '',
+        'Verification output:',
+        input.verificationOutput || '(none)',
+        '',
+        'Output JSON between markers:',
+        'BEGIN_JSON',
+        '{"status": "approve", "changes": []}',
+        'END_JSON'
+    ].join('\n');
+}

package/dist/workers/schemas.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+export const milestoneSchema = z.object({
+    goal: z.string().min(1),
+    files_expected: z.array(z.string()).optional(),
+    done_checks: z.array(z.string()).min(1),
+    risk_level: z.enum(['low', 'medium', 'high'])
+});
+export const planOutputSchema = z.object({
+    milestones: z.array(milestoneSchema).min(1),
+    risk_map: z.array(z.string()).optional(),
+    do_not_touch: z.array(z.string()).optional()
+});
+export const reviewOutputSchema = z.object({
+    status: z.enum(['approve', 'request_changes', 'reject']),
+    changes: z
+        .array(z.union([z.string(), z.object({}).passthrough()]))
+        .default([])
+        .transform((arr) => arr.map((item) => (typeof item === 'string' ? item : JSON.stringify(item))))
+});
+/**
+ * Evidence required when implementer claims "no_changes_needed".
+ * At least one of files_checked, grep_output, or commands_run must be populated.
+ */
+export const noChangesEvidenceSchema = z.object({
+    files_checked: z.array(z.string()).optional(),
+    grep_output: z.string().max(8192).optional(),
+    reason: z.string().optional(),
+    commands_run: z.array(z.object({
+        command: z.string(),
+        exit_code: z.number()
+    })).optional()
+});
+export const implementerOutputSchema = z.object({
+    status: z.enum(['ok', 'blocked', 'failed', 'no_changes_needed']),
+    handoff_memo: z.string().min(1),
+    commands_run: z.array(z.string()).default([]),
+    observations: z.array(z.string()).default([]),
+    evidence: noChangesEvidenceSchema.optional()
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@weldr/runr",
+  "version": "0.3.0",
+  "description": "Phase-gated orchestration for agent tasks",
+  "type": "module",
+  "bin": {
+    "runr": "dist/cli.js",
+    "agent": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "templates/prompts/",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "dev": "node --loader ts-node/esm src/cli.ts",
+    "start": "node dist/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "bench": "npx ts-node scripts/bench.ts",
+    "bench:dry": "npx ts-node scripts/bench.ts --dry-run",
+    "bench:minimal": "npx ts-node scripts/bench.ts --preset minimal",
+    "bench:context": "npx ts-node scripts/bench.ts --preset context",
+    "bench:stress": "npx ts-node scripts/bench.ts --preset stress",
+    "bench:full": "npx ts-node scripts/bench.ts --preset full"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "execa": "^8.0.1",
+    "picomatch": "^4.0.2",
+    "pino": "^9.3.2",
+    "yaml": "^2.8.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "@types/picomatch": "^4.0.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.4",
+    "vitest": "^4.0.16"
+  }
+}

package/templates/prompts/implementer.md

@@ -0,0 +1,70 @@
+# Implementer Prompt
+
+You are the execution model. Implement the smallest viable change for the current milestone.
+Follow scope lock. Do not edit lockfiles unless explicitly allowed.
+
+**Important**: Scope patterns (allowlist/denylist) are **repo-relative paths**, not absolute paths.
+Ignore any `.agent` substrings in your absolute working directory path - they do not affect scope compliance.
+Only the relative path from the repo root matters (e.g., `src/foo.ts` not `/path/to/.agent-worktrees/123/src/foo.ts`).
+
+## Output Format
+
+Return ONLY machine-readable JSON between BEGIN_JSON and END_JSON markers:
+
+```
+BEGIN_JSON
+{
+  "status": "ok" | "blocked" | "failed",
+  "handoff_memo": "Description of what was done or why blocked",
+  "commands_run": ["list", "of", "commands"],
+  "observations": ["notable", "findings"]
+}
+END_JSON
+```
+
+## Status Values
+
+| Status | When to use | Effect |
+|--------|-------------|--------|
+| `ok` | Implementation complete, ready for verification | Proceeds to VERIFY phase |
+| `blocked` | Cannot proceed without external input | Run stops with stop memo |
+| `failed` | Unrecoverable error occurred | Run stops with stop memo |
+
+## Block Protocol
+
+When you cannot complete a milestone (`status: "blocked"` or `status: "failed"`), structure your `handoff_memo` using this format:
+
+```
+## What broke
+<Specific error or blocking issue>
+
+## Hypothesis A
+<First theory about the cause>
+
+## Hypothesis B
+<Alternative theory>
+
+## Experiment
+<What you tried to diagnose>
+
+## Decision
+<Conclusion based on experiments>
+
+## Next action
+<What a human or future run should do>
+```
+
+This structured format helps:
+- Humans understand exactly what went wrong
+- Future runs can learn from the diagnosis
+- The stop memo captures actionable next steps
+
+## Fix Instructions
+
+When retrying after verification failure, you receive `fixInstructions`:
+- `failedCommand` - The command that failed
+- `errorOutput` - Captured error output
+- `changedFiles` - Files you modified
+- `attemptNumber` - Current retry (1-3)
+
+Use this to fix the specific issue that caused verification to fail.