feat: add Amp (Sourcegraph) as first-class agent with SDK + CLI support (#291)

* feat: add Amp (Sourcegraph) as first-class agent with SDK + CLI support

- Add 'amp' to AgentType union and AGENTS config (#235)
- Implement runAmpAgent() using @sourcegraph/amp-sdk execute() async generator
- Add CLI fallback via amp --execute --stream-json for environments without SDK
- Add --amp-mode flag (smart/rush/deep) for agent mode selection (#238)
- Wire ampMode through CLI → RunCommandOptions → LoopOptions → AgentRunOptions (#236)
- Export AmpMode type from package index for SDK consumers
- Amp ranked 2nd in agent preference (after Claude Code)
- Update tests for 6-agent detection and amp preference order

Closes #234, #235, #236, #238

Amp-Thread-ID: https://ampcode.com/threads/T-019ce298-ab61-760e-b725-803364016be5
Co-authored-by: Amp <amp@ampcode.com>

* fix: address code review — security, CLI flags, and memory guard

- Fix dangerouslyAllowAll defaulting to true → false (security)
- Register --amp-mode flag on auto and template commands
- Add maxOutputBytes truncation guard to runAmpCli

Amp-Thread-ID: https://ampcode.com/threads/T-019ce298-ab61-760e-b725-803364016be5
Co-authored-by: Amp <amp@ampcode.com>

* fix: SDK output guard, optional dep, and timeout exit code

- Add maxOutputBytes truncation guard to runAmpAgent SDK path
- Move @sourcegraph/amp-sdk to optionalDependencies to avoid bundling
  Amp CLI binary for all users and prevent false-positive agent detection
- Return exit code 124 on timeout (TimeoutError/AbortError) in SDK path,
  matching CLI path and runAgent behavior

Amp-Thread-ID: https://ampcode.com/threads/T-019ce298-ab61-760e-b725-803364016be5
Co-authored-by: Amp <amp@ampcode.com>

* fix: append output before truncation guard to prevent byte desync

Amp-Thread-ID: https://ampcode.com/threads/T-019ce298-ab61-760e-b725-803364016be5
Co-authored-by: Amp <amp@ampcode.com>

* fix: forward env to Amp SDK and use npm install hint

- Pass options.env to SDK execute() (SDK supports env natively)
- Replace curl|bash install hint with npm install -g @sourcegraph/amp

Amp-Thread-ID: https://ampcode.com/threads/T-019ce298-ab61-760e-b725-803364016be5
Co-authored-by: Amp <amp@ampcode.com>

* chore: bump version to 0.4.3

Amp-Thread-ID: https://ampcode.com/threads/T-019ce298-ab61-760e-b725-803364016be5
Co-authored-by: Amp <amp@ampcode.com>

---------

Co-authored-by: Amp <amp@ampcode.com>

Author: rubenmarcus

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-starter",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Ralph Wiggum made easy. One command to run autonomous AI coding loops with auto-commit, PRs, and Docker sandbox.",
   "main": "dist/index.js",
   "bin": {
@@ -86,6 +86,9 @@
     "yaml": "^2.7.0",
     "zod": "^4.3.6"
   },
+  "optionalDependencies": {
+    "@sourcegraph/amp-sdk": "0.1.0-20260312122132-g783443e"
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@commitlint/cli": "^20.3.1",

pnpm-lock.yaml

@@ -63,8 +63,12 @@ program
   .option('--docker', 'Run in Docker sandbox (coming soon)')
   .option('--prd <file>', 'Read tasks from a PRD markdown file')
   .option('--max-iterations <n>', 'Maximum loop iterations (auto-calculated if not specified)')
-  .option('--agent <name>', 'Specify agent (claude-code, cursor, codex, opencode, openclaw)')
+  .option('--agent <name>', 'Specify agent (claude-code, cursor, codex, opencode, openclaw, amp)')
   .option('--model <name>', 'Model to use (e.g., claude-sonnet-4-5-20250929, claude-opus-4-6)')
+  .option(
+    '--amp-mode <mode>',
+    'Amp agent mode: smart (frontier), rush (fast), deep (extended reasoning)'
+  )
   .option('--from <source>', 'Fetch spec from source (file, url, github, todoist, linear, notion)')
   .option('--project <name>', 'Project/repo name for --from integrations')
   .option('--label <name>', 'Label filter for --from integrations')
@@ -315,6 +319,10 @@ program
   .option('--dry-run', 'Preview mode - show tasks without executing')
   .option('--skip-pr', 'Skip PR creation (commit only)')
   .option('--agent <name>', 'Specify agent to use')
+  .option(
+    '--amp-mode <mode>',
+    'Amp agent mode: smart (frontier), rush (fast), deep (extended reasoning)'
+  )
   .option('--validate', 'Run validation after each task', true)
   .option('--no-validate', 'Skip validation')
   .option('--max-iterations <n>', 'Max iterations per task (default: 15)')
@@ -407,7 +415,11 @@ program
   .option('--pr', 'Create a pull request when done')
   .option('--validate', 'Run tests/lint/build after each iteration')
   .option('--max-iterations <n>', 'Maximum loop iterations')
-  .option('--agent <name>', 'Specify agent (claude-code, cursor, codex, opencode, openclaw)')
+  .option('--agent <name>', 'Specify agent (claude-code, cursor, codex, opencode, openclaw, amp)')
+  .option(
+    '--amp-mode <mode>',
+    'Amp agent mode: smart (frontier), rush (fast), deep (extended reasoning)'
+  )
   .action(async (action: string | undefined, args: string[], options) => {
     await templateCommand(action, args, options);
   });

src/cli.ts

@@ -310,6 +310,8 @@ export interface RunCommandOptions {
   // Swarm mode
   swarm?: boolean;
   strategy?: 'race' | 'consensus' | 'pipeline';
+  // Amp options
+  ampMode?: 'smart' | 'rush' | 'deep';
 }
 
 export async function runCommand(
@@ -971,6 +973,11 @@ export async function runCommand(
       console.log();
       console.log(chalk.yellow('Please install one of these:'));
       console.log(chalk.gray('  Claude Code: npm install -g @anthropic-ai/claude-code'));
+      console.log(
+        chalk.gray(
+          '  Amp:         npm install -g @sourcegraph/amp  (or see https://ampcode.com/install)'
+        )
+      );
       console.log(chalk.gray('  Cursor:      https://cursor.sh'));
       console.log(chalk.gray('  Codex:       npm install -g codex'));
       console.log(chalk.gray('  OpenCode:    npm install -g opencode'));
@@ -1426,6 +1433,7 @@ Focus on one task at a time. After completing a task, update IMPLEMENTATION_PLAN
     designImagePath,
     visualValidation,
     figmaScreenshotPaths,
+    ampMode: options.ampMode,
   };
 
   // Swarm mode: run with multiple agents in parallel

src/commands/run.ts

@@ -29,7 +29,7 @@ export type { LLMProvider } from './llm/providers.js';
 export { OPENROUTER_MODEL_ALIASES, resolveOpenRouterModel } from './llm/providers.js';
 export type { AcceptanceCriteria, AcceptanceCriterion } from './loop/acceptance-criteria.js';
 export { extractAcceptanceCriteria } from './loop/acceptance-criteria.js';
-export type { Agent, AgentType } from './loop/agents.js';
+export type { Agent, AgentType, AmpMode } from './loop/agents.js';
 export { detectAvailableAgents, detectBestAgent } from './loop/agents.js';
 export type { CircuitBreakerConfig, CircuitBreakerState } from './loop/circuit-breaker.js';
 // Loop

src/index.ts

@@ -87,11 +87,12 @@ describe('agents', () => {
         .mockRejectedValueOnce(new Error('not found')) // cursor
         .mockRejectedValueOnce(new Error('not found')) // codex
         .mockRejectedValueOnce(new Error('not found')) // opencode
-        .mockRejectedValueOnce(new Error('not found')); // openclaw
+        .mockRejectedValueOnce(new Error('not found')) // openclaw
+        .mockRejectedValueOnce(new Error('not found')); // amp
 
       const agents = await detectAvailableAgents();
 
-      expect(agents).toHaveLength(5);
+      expect(agents).toHaveLength(6);
       expect(agents.find((a) => a.type === 'claude-code')?.available).toBe(true);
       expect(agents.find((a) => a.type === 'cursor')?.available).toBe(false);
     });
@@ -121,15 +122,30 @@ describe('agents', () => {
       expect(agent?.type).toBe('claude-code');
     });
 
-    it('should fall back to cursor if claude-code is not available', async () => {
+    it('should fall back to amp if claude-code is not available', async () => {
+      mockExeca
+        .mockRejectedValueOnce(new Error('not found')) // claude-code
+        .mockRejectedValueOnce(new Error('not found')) // cursor
+        .mockRejectedValueOnce(new Error('not found')) // codex
+        .mockRejectedValueOnce(new Error('not found')) // opencode
+        .mockRejectedValueOnce(new Error('not found')) // openclaw
+        .mockResolvedValueOnce({ stdout: '1.0.0', exitCode: 0 } as any); // amp
+
+      const agent = await detectBestAgent();
+      expect(agent?.type).toBe('amp');
+    });
+
+    it('should prefer amp over cursor', async () => {
       mockExeca
         .mockRejectedValueOnce(new Error('not found')) // claude-code
         .mockResolvedValueOnce({ stdout: '1.0.0', exitCode: 0 } as any) // cursor
         .mockRejectedValueOnce(new Error('not found')) // codex
-        .mockRejectedValueOnce(new Error('not found')); // opencode
+        .mockRejectedValueOnce(new Error('not found')) // opencode
+        .mockRejectedValueOnce(new Error('not found')) // openclaw
+        .mockResolvedValueOnce({ stdout: '1.0.0', exitCode: 0 } as any); // amp
 
       const agent = await detectBestAgent();
-      expect(agent?.type).toBe('cursor');
+      expect(agent?.type).toBe('amp');
     });
   });