gh-hgeldenhuys-claude-agent-lifecycle/.claude/skills/managing-agent-lifecycles/api-reference.md

API Reference

Complete API documentation for claude-agent-lifecycle.

Table of Contents

1. AgentRegistry
2. Methods
3. Types
4. Storage Backends

---

AgentRegistry

Main class for managing agent lifecycles.

import { AgentRegistry } from 'claude-agent-lifecycle';

const registry = new AgentRegistry(options?: RegistryOptions);

RegistryOptions

Property	Type	Default	Description
storagePath	string	.agent/agents	Base path for file storage
debug	boolean	false	Enable debug logging

---

Methods

create(config)

Creates a new agent or resumes an existing one.

const { agent, isNew } = await registry.create({
  lifespan: 'session',
  name: 'my-agent',
  sessionId?: string,    // Auto-detected if not provided
  model?: string,        // 'haiku', 'sonnet', 'opus'
  metadata?: Record<string, unknown>,
});

Returns: { agent: Agent, isNew: boolean }

Behavior:

• If agent with same name exists in scope, resumes it
• If not, creates new agent
• isNew indicates whether agent was created or resumed

resume(name, scope?)

Resumes an existing agent by name.

const agent = await registry.resume('my-agent');
const agent = await registry.resume('my-agent', 'session-123');

Returns: Agent | null

Throws: If agent not found and no scope provided

dispose(agentId)

Disposes a specific agent by ID.

await registry.dispose('agent-uuid-here');

Returns: void

disposeByLifespan(lifespan)

Disposes all agents of a specific lifespan type.

const count = await registry.disposeByLifespan('turn');

Returns: number - Count of disposed agents

disposeByScope(scope)

Disposes all agents in a specific scope.

const count = await registry.disposeByScope('session-123');

Returns: number - Count of disposed agents

list(filter?)

Lists agents matching optional filter criteria.

// List all agents
const all = await registry.list();

// Filter by lifespan
const sessionAgents = await registry.list({ lifespan: 'session' });

// Filter by scope
const workflowAgents = await registry.list({ scope: 'FEAT-001' });

Returns: Agent[]

startWorkflow(config)

Starts a workflow-scoped agent.

const agent = await registry.startWorkflow({
  lifespan: 'workflow',
  workflowId: 'FEAT-001',
  name: 'executor',
  workflowType?: string,  // e.g., 'loom-story'
  model?: string,
  metadata?: Record<string, unknown>,
});

Returns: Agent

completeWorkflow(workflowId)

Completes a workflow and disposes all its agents.

const disposed = await registry.completeWorkflow('FEAT-001');

Returns: number - Count of disposed agents

getWorkflowAgents(workflowId)

Gets all agents for a specific workflow.

const agents = await registry.getWorkflowAgents('FEAT-001');

Returns: Agent[]

---

Types

Agent

interface Agent {
  agentId: string;           // Unique identifier (UUID)
  name: string;              // Human-readable name
  lifespan: Lifespan;        // One of 6 lifespans
  scope: string;             // Scope identifier
  model?: string;            // Model preference
  turnCount: number;         // Interaction count
  metadata?: Record<string, unknown>;
  createdAt: string;         // ISO timestamp
  lastActiveAt: string;      // ISO timestamp
}

Lifespan

type Lifespan =
  | 'ephemeral'  // Single use
  | 'turn'       // Until Stop event
  | 'context'    // Until context reset
  | 'session'    // Until SessionEnd event
  | 'workflow'   // Until workflow completes
  | 'project';   // Until manually disposed

CreateConfig

interface CreateConfig {
  lifespan: Lifespan;
  name: string;
  sessionId?: string;
  model?: string;
  metadata?: Record<string, unknown>;
}

WorkflowConfig

interface WorkflowConfig {
  lifespan: 'workflow';
  workflowId: string;
  name: string;
  workflowType?: string;
  model?: string;
  metadata?: Record<string, unknown>;
}

ListFilter

interface ListFilter {
  lifespan?: Lifespan;
  scope?: string;
  name?: string;
}

---

Storage Backends

MemoryStorage

Used for ephemeral, turn, and context lifespans.

• Data stored in memory
• Lost on process restart
• Fast access, no I/O

FileStorage

Used for session, workflow, and project lifespans.

• Data persisted to JSON files
• Survives process restarts
• Structure:

.agent/agents/
├── lifecycle.log           # Debug logs (when enabled)
├── session/
│   └── {session-id}/
│       └── {agent-name}.json
├── workflow/
│   └── {workflow-id}/
│       └── {agent-name}.json
└── project/
    └── {agent-name}.json

Agent JSON Format

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "shadow-advisor",
  "lifespan": "session",
  "scope": "abc-123",
  "model": "haiku",
  "turnCount": 5,
  "metadata": {
    "role": "knowledge-retrieval",
    "preloadedKnowledge": ["patterns", "pain-points"]
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "lastActiveAt": "2025-01-15T11:45:00Z"
}