@renseiai/agentfactory-cli 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rensei AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @renseiai/agentfactory-cli
+
+CLI tools for [AgentFactory](https://github.com/renseiai/agentfactory). Run a local orchestrator, remote workers, worker fleets, and queue management.
+
+## Installation
+
+```bash
+# Global (CLI commands)
+npm install -g @renseiai/agentfactory-cli
+
+# Local (programmatic runner functions)
+npm install @renseiai/agentfactory-cli
+```
+
+## CLI Commands
+
+```bash
+# Spawn agents on backlog issues
+af-orchestrator --project MyProject --max 3
+
+# Process a single issue
+af-orchestrator --single PROJ-123
+
+# Dry run — preview what would be processed
+af-orchestrator --project MyProject --dry-run
+
+# Start the Workflow Governor (event-driven + poll sweep)
+af-governor --project MyProject --project OtherProject
+
+# Governor: single scan and exit (for cron jobs)
+af-governor --project MyProject --once
+
+# Governor: poll-only mode (no event bus)
+af-governor --project MyProject --mode poll-only
+
+# Start a remote worker
+af-worker --api-url https://your-app.vercel.app --api-key your-key
+
+# Start a worker fleet (auto-detects CPU cores)
+af-worker-fleet --api-url https://your-app.vercel.app --api-key your-key
+
+# Clean up orphaned git worktrees
+af-cleanup
+
+# Queue management
+af-queue-admin list
+af-queue-admin drain
+
+# Analyze agent session logs
+af-analyze-logs --follow
+```
+
+### Governor
+
+The Workflow Governor scans projects and decides what work to dispatch based on issue status, active sessions, cooldowns, and human overrides.
+
+**Modes:**
+- `event-driven` (default) — Listens to a GovernorEventBus for real-time webhook events, with a periodic poll sweep as safety net
+- `poll-only` — Periodic scan loop only
+
+**Options:**
+```
+--project <name>            Project to scan (repeatable)
+--scan-interval <ms>        Poll interval (default: 60000 for poll-only, 300000 for event-driven)
+--max-dispatches <n>        Max concurrent dispatches per scan (default: 3)
+--mode <mode>               poll-only or event-driven (default: event-driven)
+--once                      Single scan pass and exit
+--no-auto-research          Disable Icebox → research
+--no-auto-backlog-creation  Disable Icebox → backlog-creation
+--no-auto-development       Disable Backlog → development
+--no-auto-qa                Disable Finished → QA
+--no-auto-acceptance        Disable Delivered → acceptance
+```
+
+When `LINEAR_API_KEY` and `REDIS_URL` are set, the governor uses real dependencies (Linear SDK + Redis). Without them, it falls back to stub dependencies for testing.
+
+## Programmatic Usage
+
+All CLI tools are available as importable functions via subpath exports:
+
+```typescript
+import { runOrchestrator } from '@renseiai/agentfactory-cli/orchestrator'
+
+await runOrchestrator({
+  project: 'MyProject',
+  max: 3,
+  dryRun: false,
+})
+```
+
+### Available Runner Functions
+
+```typescript
+import { runOrchestrator } from '@renseiai/agentfactory-cli/orchestrator'
+import { runWorker } from '@renseiai/agentfactory-cli/worker'
+import { runWorkerFleet } from '@renseiai/agentfactory-cli/worker-fleet'
+import { runCleanup } from '@renseiai/agentfactory-cli/cleanup'
+import { runQueueAdmin } from '@renseiai/agentfactory-cli/queue-admin'
+import { runLogAnalyzer } from '@renseiai/agentfactory-cli/analyze-logs'
+```
+
+Each function accepts a config object and returns a Promise — use them to build thin wrappers with your own env loading and argument parsing.
+
+## Environment Variables
+
+| Variable | Used By | Description |
+|----------|---------|-------------|
+| `LINEAR_API_KEY` | orchestrator, governor | Linear API key |
+| `REDIS_URL` | governor, queue-admin | Redis connection URL |
+| `WORKER_API_URL` | worker, fleet | Webhook server URL |
+| `WORKER_API_KEY` | worker, fleet | API key for authentication |
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [@renseiai/agentfactory](https://www.npmjs.com/package/@renseiai/agentfactory) | Core orchestrator |
+| [@renseiai/agentfactory-server](https://www.npmjs.com/package/@renseiai/agentfactory-server) | Redis work queue |
+| [@renseiai/agentfactory-nextjs](https://www.npmjs.com/package/@renseiai/agentfactory-nextjs) | Next.js webhook server |
+
+## License
+
+MIT

package/dist/src/agent.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * AgentFactory Agent CLI
+ *
+ * Manage running agent sessions: list, stop, send messages, check status,
+ * or reconnect a disconnected Linear session.
+ *
+ * Usage:
+ *   af-agent list [--all]                     List active sessions
+ *   af-agent stop <issue-id>                  Stop a running agent
+ *   af-agent chat <issue-id> <message>        Send a message to a running agent
+ *   af-agent status <issue-id>                Show session details
+ *   af-agent reconnect <issue-id>             Re-establish Linear agent session
+ *
+ * Environment (loaded from .env.local in CWD):
+ *   REDIS_URL          Required for all commands
+ *   LINEAR_API_KEY     Required for reconnect
+ */
+export {};
+//# sourceMappingURL=agent.d.ts.map

package/dist/src/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/src/agent.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * AgentFactory Agent CLI
+ *
+ * Manage running agent sessions: list, stop, send messages, check status,
+ * or reconnect a disconnected Linear session.
+ *
+ * Usage:
+ *   af-agent list [--all]                     List active sessions
+ *   af-agent stop <issue-id>                  Stop a running agent
+ *   af-agent chat <issue-id> <message>        Send a message to a running agent
+ *   af-agent status <issue-id>                Show session details
+ *   af-agent reconnect <issue-id>             Re-establish Linear agent session
+ *
+ * Environment (loaded from .env.local in CWD):
+ *   REDIS_URL          Required for all commands
+ *   LINEAR_API_KEY     Required for reconnect
+ */
+import path from 'path';
+import { config } from 'dotenv';
+// Load environment variables from .env.local in CWD
+config({ path: path.resolve(process.cwd(), '.env.local') });
+import { runAgent, C } from './lib/agent-runner.js';
+// ---------------------------------------------------------------------------
+// Usage
+// ---------------------------------------------------------------------------
+function printUsage() {
+    console.log(`
+${C.cyan}AgentFactory Agent${C.reset} - Manage running agent sessions
+
+${C.yellow}Usage:${C.reset}
+  af-agent <command> [issue-id] [args]
+
+${C.yellow}Commands:${C.reset}
+  list [--all]                     List active sessions (--all includes completed/failed)
+  ls [--all]                       Alias for list
+  stop <issue-id>                  Stop a running agent (worker aborts within ~5s)
+  chat <issue-id> <message>        Send a message to a running agent session
+  status <issue-id>                Show detailed session information
+  reconnect <issue-id>             Create new Linear session and re-associate
+
+${C.yellow}Arguments:${C.reset}
+  <issue-id>    Issue identifier (e.g., SUP-674) or partial session ID
+
+${C.yellow}Examples:${C.reset}
+  af-agent ls
+  af-agent list --all
+  af-agent stop SUP-674
+  af-agent chat SUP-674 "use the existing test fixtures instead"
+  af-agent status SUP-674
+  af-agent reconnect SUP-674
+
+${C.yellow}Environment:${C.reset}
+  REDIS_URL          Required for all commands
+  LINEAR_API_KEY     Required for reconnect
+`);
+}
+// ---------------------------------------------------------------------------
+// Valid commands
+// ---------------------------------------------------------------------------
+const VALID_COMMANDS = new Set(['stop', 'chat', 'status', 'reconnect', 'list']);
+const COMMAND_ALIASES = { ls: 'list' };
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    let command = process.argv[2];
+    if (!command || command === 'help' || command === '--help' || command === '-h') {
+        printUsage();
+        return;
+    }
+    // Resolve aliases
+    command = COMMAND_ALIASES[command] ?? command;
+    if (!VALID_COMMANDS.has(command)) {
+        console.error(`Unknown command: ${command}`);
+        printUsage();
+        process.exit(1);
+    }
+    // list/ls doesn't require an issue ID
+    if (command === 'list') {
+        const showAll = process.argv.includes('--all') || process.argv.includes('-a');
+        await runAgent({ command: 'list', all: showAll });
+        return;
+    }
+    const issueId = process.argv[3];
+    if (!issueId) {
+        console.error(`Usage: af-agent ${command} <issue-id>`);
+        process.exit(1);
+    }
+    // For chat, join remaining args as the message
+    let message;
+    if (command === 'chat') {
+        const messageArgs = process.argv.slice(4);
+        if (messageArgs.length === 0) {
+            console.error('Usage: af-agent chat <issue-id> <message>');
+            process.exit(1);
+        }
+        message = messageArgs.join(' ');
+    }
+    await runAgent({
+        command: command,
+        issueId,
+        message,
+    });
+}
+main().catch((error) => {
+    console.error('Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/src/analyze-logs.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * AgentFactory Log Analyzer CLI
+ *
+ * Thin wrapper around the analyze-logs runner. Handles dotenv, arg parsing,
+ * SIGINT, and process.exit so the runner stays process-agnostic.
+ *
+ * Usage:
+ *   af-analyze-logs [options]
+ *
+ * Options:
+ *   --session <id>      Analyze a specific session
+ *   --follow, -f        Watch for new sessions and analyze as they complete
+ *   --interval <ms>     Poll interval in milliseconds (default: 5000)
+ *   --dry-run           Show what would be created without creating issues
+ *   --cleanup           Cleanup old logs based on retention policy
+ *   --verbose           Show detailed analysis output
+ *   --help, -h          Show this help message
+ *
+ * Environment (loaded from .env.local in CWD):
+ *   LINEAR_API_KEY                    Required for issue creation
+ *   AGENT_LOG_RETENTION_DAYS          Days before cleanup (default: 7)
+ *   AGENT_LOGS_DIR                    Base directory for logs (default: .agent-logs)
+ */
+export {};
+//# sourceMappingURL=analyze-logs.d.ts.map

package/dist/src/analyze-logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-logs.d.ts","sourceRoot":"","sources":["../../src/analyze-logs.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/src/analyze-logs.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * AgentFactory Log Analyzer CLI
+ *
+ * Thin wrapper around the analyze-logs runner. Handles dotenv, arg parsing,
+ * SIGINT, and process.exit so the runner stays process-agnostic.
+ *
+ * Usage:
+ *   af-analyze-logs [options]
+ *
+ * Options:
+ *   --session <id>      Analyze a specific session
+ *   --follow, -f        Watch for new sessions and analyze as they complete
+ *   --interval <ms>     Poll interval in milliseconds (default: 5000)
+ *   --dry-run           Show what would be created without creating issues
+ *   --cleanup           Cleanup old logs based on retention policy
+ *   --verbose           Show detailed analysis output
+ *   --help, -h          Show this help message
+ *
+ * Environment (loaded from .env.local in CWD):
+ *   LINEAR_API_KEY                    Required for issue creation
+ *   AGENT_LOG_RETENTION_DAYS          Days before cleanup (default: 7)
+ *   AGENT_LOGS_DIR                    Base directory for logs (default: .agent-logs)
+ */
+import path from 'path';
+import { config } from 'dotenv';
+// Load environment variables from .env.local in CWD
+config({ path: path.resolve(process.cwd(), '.env.local') });
+import { runLogAnalyzer, printSummary } from './lib/analyze-logs-runner.js';
+import { getVersion, checkForUpdate, printUpdateNotification } from './lib/version.js';
+const DEFAULT_POLL_INTERVAL = 5000;
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {
+        follow: false,
+        interval: DEFAULT_POLL_INTERVAL,
+        dryRun: false,
+        cleanup: false,
+        verbose: false,
+        showHelp: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--session':
+                result.sessionId = args[++i];
+                break;
+            case '--follow':
+            case '-f':
+                result.follow = true;
+                break;
+            case '--interval':
+                result.interval = parseInt(args[++i], 10) || DEFAULT_POLL_INTERVAL;
+                break;
+            case '--dry-run':
+                result.dryRun = true;
+                break;
+            case '--cleanup':
+                result.cleanup = true;
+                break;
+            case '--verbose':
+                result.verbose = true;
+                break;
+            case '--help':
+            case '-h':
+                result.showHelp = true;
+                break;
+        }
+    }
+    return result;
+}
+function printHelp() {
+    console.log(`
+AgentFactory Log Analyzer - Analyze agent session logs for errors and improvements
+
+Usage:
+  af-analyze-logs [options]
+
+Options:
+  --session <id>      Analyze a specific session
+  --follow, -f        Watch for new sessions and analyze as they complete
+  --interval <ms>     Poll interval in milliseconds (default: 5000)
+  --dry-run           Show what would be created without creating issues
+  --cleanup           Cleanup old logs based on retention policy
+  --verbose           Show detailed analysis output
+  --help, -h          Show this help message
+
+Environment Variables:
+  LINEAR_API_KEY                    Required for creating Linear issues
+  AGENT_LOG_RETENTION_DAYS          Days before log cleanup (default: 7)
+  AGENT_LOGS_DIR                    Base directory for logs (default: .agent-logs)
+
+Examples:
+  # Analyze all unprocessed sessions
+  af-analyze-logs
+
+  # Analyze a specific session
+  af-analyze-logs --session abc123
+
+  # Watch for new sessions and analyze continuously
+  af-analyze-logs --follow
+
+  # Watch with custom poll interval (10 seconds)
+  af-analyze-logs -f --interval 10000
+
+  # Preview what issues would be created (no actual changes)
+  af-analyze-logs --dry-run
+
+  # Clean up logs older than retention period
+  af-analyze-logs --cleanup
+
+  # Show detailed output during analysis
+  af-analyze-logs --verbose
+`);
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    const options = parseArgs();
+    if (options.showHelp) {
+        printHelp();
+        process.exit(0);
+    }
+    const version = getVersion();
+    console.log(`AgentFactory Log Analyzer \x1b[2mv${version}\x1b[0m\n`);
+    // Update check (non-blocking)
+    const updateCheck = await checkForUpdate();
+    printUpdateNotification(updateCheck);
+    // Create AbortController for SIGINT handling in follow mode
+    const controller = new AbortController();
+    if (options.follow) {
+        const shutdown = () => {
+            controller.abort();
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    }
+    const result = await runLogAnalyzer({
+        sessionId: options.sessionId,
+        follow: options.follow,
+        interval: options.interval,
+        dryRun: options.dryRun,
+        cleanup: options.cleanup,
+        verbose: options.verbose,
+    }, controller.signal);
+    printSummary(result, options.dryRun);
+}
+main().catch((error) => {
+    console.error('Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/src/cleanup.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * AgentFactory Worktree Cleanup CLI
+ *
+ * Thin wrapper around the cleanup runner.
+ *
+ * Usage:
+ *   af-cleanup [options]
+ *
+ * Options:
+ *   --dry-run           Show what would be cleaned up without removing anything
+ *   --force             Force removal even if worktree appears active
+ *   --path <dir>        Custom worktrees directory (default: .worktrees)
+ *   --help, -h          Show this help message
+ */
+export {};
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/src/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/cleanup.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG"}

package/dist/src/cleanup.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * AgentFactory Worktree Cleanup CLI
+ *
+ * Thin wrapper around the cleanup runner.
+ *
+ * Usage:
+ *   af-cleanup [options]
+ *
+ * Options:
+ *   --dry-run           Show what would be cleaned up without removing anything
+ *   --force             Force removal even if worktree appears active
+ *   --path <dir>        Custom worktrees directory (default: .worktrees)
+ *   --help, -h          Show this help message
+ */
+import { basename } from 'path';
+import { runCleanup, getGitRoot } from './lib/cleanup-runner.js';
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {
+        dryRun: false,
+        force: false,
+        worktreePath: undefined,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '--dry-run':
+                result.dryRun = true;
+                break;
+            case '--force':
+                result.force = true;
+                break;
+            case '--path':
+                result.worktreePath = args[++i];
+                break;
+            case '--help':
+            case '-h':
+                printHelp();
+                process.exit(0);
+        }
+    }
+    return result;
+}
+function printHelp() {
+    console.log(`
+AgentFactory Worktree Cleanup - Remove orphaned git worktrees
+
+Usage:
+  af-cleanup [options]
+
+Options:
+  --dry-run           Show what would be cleaned up without removing
+  --force             Force removal even if worktree appears active
+  --path <dir>        Custom worktrees directory (default: .worktrees)
+  --help, -h          Show this help message
+
+Orphaned worktrees are identified by:
+  - Branch no longer exists (merged/deleted)
+  - Not listed in 'git worktree list' (stale directory)
+  - Lock file exists but is stale
+
+Examples:
+  # Preview what would be cleaned up
+  af-cleanup --dry-run
+
+  # Clean up orphaned worktrees
+  af-cleanup
+
+  # Force cleanup all worktrees (use with caution)
+  af-cleanup --force
+`);
+}
+function printSummary(result) {
+    console.log('=== Summary ===\n');
+    console.log(`  Scanned:  ${result.scanned} worktree(s)`);
+    console.log(`  Orphaned: ${result.orphaned}`);
+    console.log(`  Cleaned:  ${result.cleaned}`);
+    if (result.skipped > 0) {
+        console.log(`  Skipped:  ${result.skipped} (IDE/process still open — use --force)`);
+    }
+    if (result.errors.length > 0) {
+        console.log(`  Errors:   ${result.errors.length}`);
+        for (const err of result.errors) {
+            console.log(`    - ${basename(err.path)}: ${err.error}`);
+        }
+    }
+    console.log('');
+}
+// Main execution
+function main() {
+    const args = parseArgs();
+    console.log('\n=== AgentFactory Worktree Cleanup ===\n');
+    if (args.dryRun) {
+        console.log('[DRY RUN MODE - No changes will be made]\n');
+    }
+    if (args.force) {
+        console.log('[FORCE MODE - All worktrees will be removed]\n');
+    }
+    const result = runCleanup({
+        dryRun: args.dryRun,
+        force: args.force,
+        worktreePath: args.worktreePath,
+        gitRoot: getGitRoot(),
+    });
+    printSummary(result);
+    if (result.errors.length > 0) {
+        process.exit(1);
+    }
+}
+main();

package/dist/src/governor.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * AgentFactory Governor CLI
+ *
+ * Thin wrapper around the governor runner.
+ *
+ * Usage:
+ *   af-governor [options]
+ *
+ * Options:
+ *   --project <name>            Project to scan (can be repeated)
+ *   --scan-interval <ms>        Scan interval in milliseconds (default: 60000)
+ *   --max-dispatches <n>        Maximum concurrent dispatches per scan (default: 3)
+ *   --no-auto-research          Disable auto-research from Icebox
+ *   --no-auto-backlog-creation  Disable auto-backlog-creation from Icebox
+ *   --no-auto-development       Disable auto-development from Backlog
+ *   --no-auto-qa                Disable auto-QA from Finished
+ *   --no-auto-acceptance        Disable auto-acceptance from Delivered
+ *   --once                      Run a single scan pass and exit
+ *
+ * Environment:
+ *   LINEAR_API_KEY              Required API key for Linear authentication
+ *   GOVERNOR_PROJECTS           Comma-separated project names (fallback for --project)
+ */
+export {};
+//# sourceMappingURL=governor.d.ts.map

package/dist/src/governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governor.d.ts","sourceRoot":"","sources":["../../src/governor.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}