npm package: 12-factor-agents
Description: 12-factor methodology for autonomous AI agents - state management, checkpointing, resumable workflows
Author: anombyte
Latest version: 1.0.0

# 12-factor-agents

[![npm version](https://badge.fury.io/js/12-factor-agents.svg)](https://www.npmjs.com/package/12-factor-agents)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
[![npm downloads](https://img.shields.io/npm/dm/12-factor-agents.svg)](https://www.npmjs.com/package/12-factor-agents)

> 12-factor methodology for autonomous AI agents - state management, checkpointing, resumable workflows

## Overview

**12-factor-agents** brings the proven principles of [12-factor apps](https://12factor.net/) to autonomous AI agent workflows. It provides robust infrastructure for long-running, resumable, and observable agent operations.

### Core Principles

1. **Stateless Brains, Stateful System** - Agents are ephemeral, state persists
2. **Checkpointed Steps** - Every step is saved, workflows are resumable
3. **Idempotent Actions** - Steps can be safely retried
4. **Resumable Workflows** - Pick up exactly where you left off
5. **Human-in-the-Loop Batching** - Collect inputs, minimize interruptions
6. **Observable Operations** - Comprehensive logging and notifications

## Installation

```bash
npm install 12-factor-agents
```

Or globally for CLI access:

```bash
npm install -g 12-factor-agents
```

## Quick Start (5 minutes)

### 1. Initialize a Project

```bash
cd your-project
npx 12fa init
```

This creates `.12fa/` directory for state management.

### 2. Basic Workflow

```typescript
import { WorkflowRunner } from '12-factor-agents';

const runner = new WorkflowRunner({
  projectRoot: process.cwd(),
  enableGitCheckpoints: true,
  enableNtfy: false
});

await runner.runWorkflow('my-workflow', [
  {
    id: 'step-1',
    name: 'First step',
    action: async () => {
      console.log('Doing work...');
    }
  },
  {
    id: 'step-2',
    name: 'Second step',
    action: async () => {
      console.log('More work...');
    }
  }
]);
```

### 3. Run It

```bash
npx ts-node your-script.ts
# or
node your-script.js
```

If interrupted, run it again—it will resume from the last checkpoint.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    WorkflowRunner                       │
│  Orchestrates state, checkpoints, logging, and inputs   │
└────────────────┬────────────────────────────────────────┘
                 │
     ┌───────────┼───────────┬─────────────┬──────────┐
     │           │           │             │          │
┌────▼─┐  ┌─────▼──┐  ┌─────▼────┐  ┌────▼──┐  ┌───▼──┐
│State │  │Checkpoint│  │Feature  │  │Progress│  │Input │
│Mgr   │  │Manager   │  │Tracker  │  │Logger  │  │Coll  │
└──────┘  └──────────┘  └─────────┘  └────────┘  └──────┘
     │           │           │             │          │
     └───────────┼───────────┴─────────────┴──────────┘
                 │
         ┌───────▼────────┐
         │  .12fa/ State  │
         │  Persistence   │
         └────────────────┘
                 │
            ┌────▼─────┬──────────┬─────────────┐
            │  Git     │ NTFY     │  Filesystem │
            │ Commits  │ Notify   │  Logs       │
            └──────────┴──────────┴─────────────┘
```

## CLI Commands

```bash
# Project initialization
12fa init                              # Set up state directory

# Workflow management
12fa status                            # Show current workflow status
12fa checkpoints                       # List all checkpoints
12fa restore <checkpoint-id>           # Restore to checkpoint

# Feature tracking
12fa features                          # List all features
12fa add-feature "Name" [priority]     # Create feature

# Monitoring
12fa logs [session-id]                 # Show progress logs
12fa inputs                            # List pending human inputs
12fa respond <input-id> <response>     # Provide input response

# Cleanup
12fa clean                             # Remove all state (destructive)
12fa --help                            # Show help
```

## Comprehensive Guide

### Programmatic Usage

```typescript
import { WorkflowRunner } from '12-factor-agents';

const runner = new WorkflowRunner({
  projectRoot: process.cwd(),
  enableGitCheckpoints: true,
  enableNtfy: process.env.ENABLE_NTFY === 'true',
  autoCommit: false
});

await runner.runWorkflow('build-feature', [
  {
    id: 'analyze',
    name: 'Analyze requirements',
    action: async () => {
      console.log('Analyzing...');
    }
  },
  {
    id: 'implement',
    name: 'Implement feature',
    action: async () => {
      console.log('Implementing...');
    },
    idempotent: true  // Safe to retry
  },
  {
    id: 'test',
    name: 'Run tests',
    action: async () => {
      console.log('Testing...');
    },
    rollback: async () => {
      console.log('Rolling back...');
    }
  }
]);
```

## Features

### State Management

Persistent state across workflow executions:

```typescript
const stateManager = runner.getStateManager();

// Check if step was completed
if (stateManager.isStepCompleted('build')) {
  console.log('Build already done, skipping...');
}

// Update context
stateManager.updateContext({
  apiKey: 'xxx',
  deploymentUrl: 'https://example.com'
});
```

### Git Checkpointing

Automatic git commits at each step:

```typescript
const checkpointManager = runner.getCheckpointManager();

// Create manual checkpoint
checkpointManager.createCheckpoint(
  'deployment',
  'pre-deploy',
  { version: '1.2.3' },
  'Ready for deployment'
);

// List all checkpoints
const checkpoints = checkpointManager.listCheckpoints();

// Restore to previous checkpoint
checkpointManager.restoreCheckpoint('deployment-pre-deploy-1234567890');
```

### Feature Tracking

Manage features with priorities and status:

```typescript
const featureTracker = runner.getFeatureTracker();

// Add feature
const feature = featureTracker.addFeature('User authentication', 'high');

// Update status
featureTracker.updateFeatureStatus(feature.id, 'in-progress');
featureTracker.updateFeatureStatus(feature.id, 'complete');

// List features by status
const pending = featureTracker.listFeatures('pending');
```

### Progress Logging

Chronological logging of all workflow actions:

```typescript
const progressLogger = runner.getProgressLogger();

// Log action
progressLogger.log(
  sessionId,
  'build',
  'compile',
  'Compiling TypeScript',
  'success',
  'Built 42 files',
  1234 // duration in ms
);

// Get session stats
const stats = progressLogger.getSessionStats(sessionId);
console.log(`Success rate: ${stats.successful}/${stats.totalActions}`);
```

### Human Input Collection

Batch human inputs to minimize interruptions:

```typescript
const inputCollector = runner.getInputCollector();

// Request input
const inputId = inputCollector.requestInput(
  'Which API endpoint should we use?',
  { options: ['staging', 'production'] }
);

// Check pending inputs
const pending = inputCollector.getPendingInputs();

// Provide response
inputCollector.provideResponse(inputId, 'staging');

// Wait for response (async)
const response = await inputCollector.waitForResponse(inputId, 60000);
```

### NTFY Notifications

Real-time notifications to desktop/mobile:

```typescript
const ntfyClient = runner.getNtfyClient();

// Built-in notification types
ntfyClient.notifyStart('deployment', 'Starting deployment to production');
ntfyClient.notifyComplete('deployment', 'Deployment successful');
ntfyClient.notifyError('deployment', 'Deployment failed: timeout');
ntfyClient.notifyBlocked('deployment', 'Waiting for approval');
ntfyClient.notifyInputRequired('Select environment', inputId);

// Custom notification
ntfyClient.send({
  title: 'Custom Event',
  message: 'Something happened',
  priority: 'high',
  tags: ['warning', 'robot'],
  click: 'https://example.com',
  actions: [
    {
      action: 'view',
      label: 'View Details',
      url: 'https://dashboard.example.com'
    }
  ]
});
```

## CLI Usage

```bash
# Initialize project
12fa init

# Show workflow status
12fa status

# List checkpoints
12fa checkpoints

# Restore checkpoint
12fa restore <checkpoint-id>

# Feature management
12fa features
12fa add-feature "User authentication" high

# View logs
12fa logs
12fa logs <session-id>

# Human inputs
12fa inputs
12fa respond <input-id> "production"

# Clean all state (WARNING: destructive)
12fa clean
```

## Configuration

```typescript
interface WorkflowConfig {
  projectRoot: string;           // Required: project directory
  stateDir?: string;             // Default: .12fa/
  enableGitCheckpoints?: boolean; // Default: true
  enableNtfy?: boolean;          // Default: false
  ntfyUrl?: string;              // Default: http://localhost:8889
  ntfyTopic?: string;            // Default: anombyte-dev
  autoCommit?: boolean;          // Default: false
}
```

## NTFY Setup

```bash
# Auto-setup (installs + starts server)
./node_modules/12-factor-agents/scripts/setup-ntfy.sh

# Manual setup
ntfy serve --listen-http :8889 &

# Subscribe to notifications
# Web: http://localhost:8889/anombyte-dev
# Mobile: Install ntfy app, subscribe to anombyte-dev
```

## Project Structure

```
your-project/
└── .12fa/
    ├── agent-state.json          # Current workflow state
    ├── checkpoints/              # Step checkpoints
    │   └── *.json
    ├── features.json             # Feature tracking
    ├── progress.jsonl            # Chronological logs
    └── human-inputs.json         # Input requests/responses
```

## Best Practices

### 1. Design Idempotent Steps

```typescript
{
  id: 'install-deps',
  name: 'Install dependencies',
  action: async () => {
    // Check if already installed
    if (fs.existsSync('node_modules')) {
      console.log('Dependencies already installed');
      return;
    }
    await exec('npm install');
  },
  idempotent: true
}
```

### 2. Use Checkpoints for Critical Steps

```typescript
const checkpoint = checkpointManager.createCheckpoint(
  'deployment',
  'pre-deploy',
  { version, buildHash },
  'Pre-deployment checkpoint'
);
```

### 3. Batch Human Inputs

```typescript
// Collect all inputs upfront
const envInput = inputCollector.requestInput('Environment?');
const versionInput = inputCollector.requestInput('Version tag?');

// Notify once
ntfyClient.send({
  title: 'Input Required',
  message: '2 questions need answers',
  priority: 'high'
});

// Wait for all responses
const [env, version] = await Promise.all([
  inputCollector.waitForResponse(envInput),
  inputCollector.waitForResponse(versionInput)
]);
```

### 4. Log Everything

```typescript
progressLogger.log(
  sessionId,
  phase,
  step,
  action,
  result,
  details,
  duration
);
```

## Examples

See `/examples` directory for complete workflows:

- `build-pipeline.ts` - CI/CD workflow
- `data-migration.ts` - Database migration
- `feature-development.ts` - TDD workflow

## Troubleshooting

### Workflow won't resume

Check that `.12fa/agent-state.json` exists and is readable:

```bash
ls -la .12fa/
cat .12fa/agent-state.json
```

### NTFY notifications not working

Ensure ntfy server is running:

```bash
# Check if running
lsof -i :8889

# Start ntfy server
ntfy serve --listen-http :8889 &

# Subscribe to notifications
# Go to: http://localhost:8889/anombyte-dev
```

### CLI commands not found

Ensure the package is installed globally or use npx:

```bash
# Global install
npm install -g 12-factor-agents
12fa --help

# Or with npx
npx 12-factor-agents --help
```

## Contributing

Contributions welcome! Areas for enhancement:

- Test suite (Jest/Vitest)
- Example workflows
- MCP server integration
- Advanced recovery strategies
- Performance optimizations

## Roadmap

- **v1.0.0** (current) - Stable core + CLI
- **v1.1.0** - Enhanced error messages and debugging
- **v1.2.0** - Performance optimizations
- **v2.0.0** - MCP server integration + advanced patterns

## License

MIT

## Author

anombyte

---

Built for autonomous AI agents. Inspired by [12-factor apps](https://12factor.net/). Designed for production.

Perfect for CI/CD pipelines, data migrations, multi-step deployments, and human-supervised AI tasks.

[See CHANGELOG for detailed release notes.](CHANGELOG.md)