🤖 Agent Spawner V2

Type-Driven Architecture with Railway Oriented Programming

A universal AI agent spawner built with verifiable type system that makes invalid states mathematically impossible. This implementation follows Domain-Driven Design (DDD), Type-Driven Development (TyDD), and Railway Oriented Programming (ROP) principles.

---

🧠 ARCHITECTURAL PHILOSOPHY

$3

This codebase is designed with constructive correctness where the compiler prevents runtime errors through:

- Algebraic Data Types (ADTs): Sum and Product types eliminate invalid states
- Parse, Don't Validate: Trust types after boundary validation
- Railway Oriented Programming: Explicit error handling with Result monads
- Branded Types: Prevent primitive obsession

$3

``typescript
// ❌ Invalid states are impossible:
type AgentState =
| { _tag: 'Created'; sessionId: SessionId; createdAt: Date }
| { _tag: 'Running'; sessionId: SessionId; processId: ProcessId; startedAt: Date }
| { _tag: 'Completed'; sessionId: SessionId; output: string; completedAt: Date };

// You cannot accidentally:
// - Complete a non-running agent
// - Pass a wrong session ID type
// - Forget to handle a state
`

---

📁 PROJECT STRUCTURE

`
agent-spawner-v2/
├── 📁 src/ # Source code
│ ├── 🧠 domain/ # Domain logic (pure functions)
│ ├── 🎯 application/ # Application orchestration
│ ├── 🏗️ infrastructure/ # Side effects (I/O, processes)
│ └── 🚀 cli/ # CLI interface
├── 📁 tests/ # Test suite
│ ├── 🧪 unit/ # Unit tests
│ ├── 🔗 integration/ # Integration tests
│ └── 🛠️ utils/ # Test utilities
├── 📁 docs/ # Documentation
├── 📁 dist/ # Built JavaScript
└── ⚙️ Config files # TypeScript, Jest, etc.
`

---

🏗️ ARCHITECTURE

$3


`
┌─────────────────────────────────────────┐
│ CLI INTERFACE │ ← User Interface
├─────────────────────────────────────────┤
│ APPLICATION LAYER │ ← Orchestration
├─────────────────────────────────────────┤
│ DOMAIN LAYER │ ← Business Logic
├─────────────────────────────────────────┤
│ INFRASTRUCTURE LAYER │ ← Side Effects
└─────────────────────────────────────────┘
`

$3

- 🧠 Domain Types: Immutable, verifiable data structures
- ⚡ Domain Services: Pure business logic functions
- 🎯 Application Service: Orchestrates workflows
- 🏗️ Infrastructure: File system, process management
- 🚀 CLI: Type-safe command interface

---

📦 INSTALLATION

`bash


Clone the repository

git clone
cd agent-spawner-v2

Install dependencies

npm install

Build the project

npm run build

Install globally for CLI usage

npm install -g .
`

---

🚀 USAGE

$3

`bash


Spawn an agent with Anthropic Claude

agent-spawner spawn -p "Explain quantum computing" -r anthropic

Use Z.AI provider with specific model

agent-spawner spawn -p "Write Python code" -r zai -m glm-4.6

Terminal mode for interactive sessions

agent-spawner spawn -p "Debug this issue" -e terminal

Background execution with timeout

agent-spawner spawn -p "Long running task" -e background -t 600

Load configuration from file

agent-spawner spawn -c config.json -p "Custom prompt"

Save output to file

agent-spawner spawn -p "Generate report" -o report.txt

List active sessions

agent-spawner list

Cancel a running session

agent-spawner cancel
`

$3

`typescript
import { createAgentService, parseAgentConfig } from 'agent-spawner-v2';

// Create service instance
const service = createAgentService();

// Parse configuration
const config = parseAgentConfig({
prompt: "Explain TypeScript",
provider: { _tag: 'Anthropic' },
executionMode: { _tag: 'Inline', timeout: 300 }
});

// Spawn agent
if (config._tag === 'Success') {
const result = await service.spawnAgent(config.value);

if (result._tag === 'Success') {
console.log('Agent spawned:', result.value.sessionId);
}
}
`

---

🔧 CONFIGURATION

$3


`json
{
"prompt": "Your agent prompt here",
"provider": "anthropic",
"model": "claude-3-sonnet",
"mode": "inline",
"timeout": 300,
"environment": {
"CUSTOM_VAR": "value"
}
}
`

$3

| Provider | Models | Environment Variables |
|----------|--------|----------------------|
| Anthropic | claude-3-sonnet, claude-3-opus, claude-3-haiku | ANTHROPIC_API_KEY |
| Z.AI | glm-4.6 | ZAI_API_KEY |
| OpenAI | gpt-4, gpt-3.5-turbo | OPENAI_API_KEY |

$3

- inline: Run synchronously and return output
- terminal: Open in terminal for interactive sessions
- background: Run asynchronously with auto-cleanup

---

🧪 DEVELOPMENT

$3

`typescript
// ✅ Branded types prevent confusion
type SessionId = Branded;
type AgentPrompt = Branded;

// ✅ Sum types ensure exhaustive handling
type AgentState =
| { _tag: 'Created' }
| { _tag: 'Running' }
| { _tag: 'Completed' };

// ✅ Result types make errors explicit
type Result =
| { _tag: 'Success'; value: T }
| { _tag: 'Failure'; error: E };
`

$3

`bash


Type checking (no compilation)

npm run type-check

Build project

npm run build

Run tests

npm test

Watch tests

npm run test:watch

Coverage report

npm run test:coverage

Lint code

npm run lint
`

$3

- Property-Based Testing: Verify invariants with random data
- Type-Driven Tests: Test every branch of discriminated unions
- Integration Tests: Verify complete workflows
- Mock-Free Testing: Test pure functions directly

---

🏛️ ARCHITECTURAL PATTERNS

$3

`typescript
// 🎯 Linear error handling, no try/catch
const result = await pipe(
parseAgentConfig(input),
chain(validateConfig),
chain(createSession),
chain(spawnAgent),
chain(monitorExecution)
);

// 🎯 Explicit error handling
match(result, {
Success: (value) => console.log('Success:', value),
Failure: (error) => console.error('Error:', error)
});
`

$3

`typescript
// ❌ Validation everywhere
function validateUser(user: any): boolean {
return user.email && user.age > 0;
}

// ✅ Parse once, trust everywhere
const parseUser = (input: unknown): Result => {
// Parse and validate at boundary
return Success(validatedUser);
};

// Now we can trust User type everywhere
function processUser(user: User): Result {
// No validation needed - User is always valid
}
`

---

📊 PERFORMANCE

$3

- Immutable Data: Prevents accidental mutations
- Resource Cleanup: Automatic process and file cleanup
- Event-Driven: Non-blocking async operations

$3

- Process Isolation: Each agent runs in separate process
- Concurrent Execution: Multiple agents can run simultaneously
- Resource Limits: Configurable timeouts and auto-cleanup

---

🔒 SAFETY & SECURITY

$3

- No Runtime Type Errors: All data validated at boundaries
- Exhaustive Pattern Matching: All states handled explicitly
- Immutable by Default: Prevents unintended side effects

$3

- Environment Variable Sanitization: Secure API key handling
- Script Generation Safety: No eval or code injection
- Process Isolation: Agents run in isolated processes
- Resource Cleanup: Prevents resource leaks

---

🤝 CONTRIBUTING

$3

1. Type-Driven Development: Start with types, not code
2. Railway Oriented Programming: Make errors explicit
3. Pure Functions: Separate business logic from side effects
4. Immutability: All data structures must be immutable
5. Exhaustiveness: Handle every possible state

$3

- [ ] All functions are total and pure
- [ ] Error handling uses Result monads
- [ ] No any` types or type assertions
- [ ] All discriminated unions are exhaustive
- [ ] All data structures are immutable
- [ ] No try/catch in business logic

---

📄 LICENSE

MIT License - see LICENSE file for details.

---

🙏 ACKNOWLEDGMENTS

This architecture is inspired by:

- Domain-Driven Design (Eric Evans)
- Type-Driven Development (Edwin Brady)
- Functional Programming (Scott Wlaschin)
- Railway Oriented Programming (Scott Wlaschin)

Built with ❤️ using TypeScript, Functional Programming, and Type-Driven Development.