API Documentation

LumenFlow provides TypeScript API documentation generated from source code using TypeDoc.

Package APIs

@lumenflow/core

WU lifecycle, state machine, validators, configuration

@lumenflow/cli

Command implementations, argument parsing

@lumenflow/memory

Session tracking, checkpoints, signals

@lumenflow/agent

Skill loading, agent definitions, verification

Core Package API

WU Lifecycle

import {
  createWu,
  claimWu,
  completeWu,
  blockWu,
  unblockWu,
  type WuSpec,
  type WuStatus,
} from '@lumenflow/core';

// Create a new WU
const wu = await createWu({
  id: 'WU-042',
  title: 'Add email validation',
  lane: 'Framework: Core',
  description: 'Add validation for email fields',
  acceptance: ['Email validates on blur', 'Unit tests pass'],
  codePaths: ['src/validation/email.ts'],
});

// Claim for work
await claimWu({
  wuId: 'WU-042',
  lane: 'Framework: Core',
});

// Complete when done
await completeWu({
  wuId: 'WU-042',
  skipGates: false,
});

State Machine

import { WuStateMachine, WuStatus, WuTransition, canTransition } from '@lumenflow/core';

// Check if transition is valid
const canClaim = canTransition(WuStatus.READY, WuStatus.IN_PROGRESS);
// true

// Get valid transitions
const machine = new WuStateMachine();
const validTransitions = machine.getValidTransitions(WuStatus.IN_PROGRESS);
// [WuStatus.BLOCKED, WuStatus.WAITING, WuStatus.DONE]

Configuration

import { loadConfig, validateConfig, type LumenFlowConfig } from '@lumenflow/core';

// Load config from file
const config = await loadConfig('/path/to/workspace.yaml');

// Validate config
const issues = validateConfig(config);
if (issues.length > 0) {
  console.error('Config issues:', issues);
}

Cost Telemetry

import { emitCostEvent, syncNdjsonTelemetryToCloud } from '@lumenflow/core/telemetry';
import type { CostEvent, CostSummary } from '@lumenflow/metrics';

const event: CostEvent = {
  timestamp: new Date().toISOString(),
  sourceType: 'cost',
  operation: 'llm.classification',
  model: 'gpt-4o-mini',
  inputTokens: 1200,
  outputTokens: 320,
  costUsd: 0.0421,
  wuId: 'WU-2316',
  agentId: 'agent-1',
  sessionId: 'session-abc',
};

emitCostEvent({
  timestamp: event.timestamp,
  operation: event.operation,
  model: event.model,
  input_tokens: event.inputTokens,
  output_tokens: event.outputTokens,
  cost_usd: event.costUsd,
  wu_id: event.wuId,
  agent_id: event.agentId,
  session_id: event.sessionId,
});

// Later: include costs.ndjson alongside other telemetry sources in cloud sync
await syncNdjsonTelemetryToCloud();

Local operator summary command:

pnpm cost:summary
pnpm cost:summary --json

Control-Plane Heartbeats

import type { HeartbeatInput, HeartbeatResult } from '@lumenflow/control-plane-sdk';

const heartbeatRequest: HeartbeatInput = {
  workspace_id: 'workspace-a',
  session_id: 'session-a',
  agent_id: 'agent-1',
  wu_id: 'WU-2317',
  health: {
    busy: false,
    stalled: false,
    last_progress_at: new Date().toISOString(),
  },
};

const heartbeatResponse: HeartbeatResult = {
  status: 'ok',
  server_time: new Date().toISOString(),
  next_heartbeat_ms: 30000,
  assignment: {
    wu_id: 'WU-2317',
    action: 'continue',
    hint: 'server-directed cadence',
  },
  budget_remaining_usd: 42.5,
  coalesced_signals: 2,
};

Session Metadata Contracts

import type { RegisterSessionInput, SessionSummary } from '@lumenflow/control-plane-sdk';

const registerSessionInput: RegisterSessionInput = {
  workspace_id: 'workspace-a',
  session_id: 'session-a',
  agent_id: 'agent-1',
  started_at: new Date().toISOString(),
  lane: 'Framework: Core Lifecycle',
  wu_id: 'WU-2318',
  client_type: 'claude-code',
  capabilities: ['session_lifecycle', 'heartbeat'],
  agent_version: '3.10.0',
  host_id: 'host-01',
  metadata: {
    client_type: 'claude-code',
    capabilities: ['session_lifecycle', 'heartbeat'],
    agent_version: '3.10.0',
    host_id: 'host-01',
  },
};

const sessionSummary: SessionSummary = {
  workspace_id: 'workspace-a',
  session_id: 'session-a',
  agent_id: 'agent-1',
  started_at: new Date().toISOString(),
  active: true,
  client_type: 'claude-code',
  capabilities: ['session_lifecycle', 'heartbeat'],
  agent_version: '3.10.0',
  host_id: 'host-01',
  metadata: {
    client_type: 'claude-code',
    capabilities: ['session_lifecycle', 'heartbeat'],
    agent_version: '3.10.0',
    host_id: 'host-01',
  },
};

Context Validation

import {
  resolveLocation,
  readGitState,
  readWuState,
  validateContext,
  LocationType,
} from '@lumenflow/core';

// Resolve current location
const location = await resolveLocation();
if (location.type === LocationType.WORKTREE) {
  console.log(`In worktree: ${location.worktreeName}`);
}

// Read git state
const gitState = await readGitState();
if (gitState.isDirty) {
  console.log('Uncommitted changes present');
}

// Full context validation
const result = await validateContext({
  command: 'wu:done',
  wuId: 'WU-042',
});

Agent Branch Detection

import { isAgentBranch, isAgentBranchWithDetails, resolveAgentPatterns } from '@lumenflow/core';

// Check if branch is an agent branch
const isAgent = await isAgentBranch('claude/session-12345');
// true

// Get detailed result
const result = await isAgentBranchWithDetails('claude/session-12345');
console.log(result.patternResult.source);
// 'registry' | 'merged' | 'override' | 'config' | 'defaults'

Memory Package API

Session Tracking

import { startSession, endSession, getActiveSession, type AgentSession } from '@lumenflow/memory';

// Start a session
const session = await startSession({
  wuId: 'WU-042',
  agentType: 'claude-code', // example; use your project's configured client
});

// Get active session
const active = await getActiveSession('WU-042');

// End session
await endSession(session.id);

Checkpoints

import { createCheckpoint, loadCheckpoint, listCheckpoints } from '@lumenflow/memory';

// Create checkpoint
await createCheckpoint({
  wuId: 'WU-042',
  message: 'Tests passing, starting implementation',
  context: {
    filesModified: ['src/validation/email.ts'],
    testsAdded: ['src/__tests__/email.test.ts'],
  },
});

// Load latest checkpoint
const checkpoint = await loadCheckpoint('WU-042');

// List all checkpoints
const checkpoints = await listCheckpoints({ wuId: 'WU-042' });

Signals

import { sendSignal, getInbox, type Signal } from '@lumenflow/memory';

// Send progress signal
await sendSignal({
  wuId: 'WU-042',
  message: 'Implementation complete',
  type: 'progress',
});

// Check inbox
const signals = await getInbox({
  since: '1h',
  lane: 'Framework: Core',
});

Agent Package API

Skill Loading

import { loadSkill, listSkills, validateSkill, type Skill } from '@lumenflow/agent';

// Load a skill
const skill = await loadSkill('wu-lifecycle');
console.log(skill.name);
console.log(skill.allowedTools);

// List available skills
const skills = await listSkills();

// Validate skill definition
const issues = await validateSkill('.claude/skills/my-skill/SKILL.md');

Agent Verification

import { verifyCompletion, type VerificationResult } from '@lumenflow/agent';

// Verify WU completion
const result = await verifyCompletion('WU-042');
if (result.passed) {
  console.log('All acceptance criteria met');
} else {
  console.log('Failed:', result.failures);
}

CLI Package API

The CLI package is primarily used via commands, but exports some utilities:

import { parseArgs, formatOutput, printTable } from '@lumenflow/cli';

// Parse command arguments
const args = parseArgs(['--id', 'WU-042', '--lane', 'Core']);

// Format output for display
const output = formatOutput({
  status: 'success',
  message: 'WU completed',
});

// Print formatted table
printTable([
  { id: 'WU-042', status: 'done' },
  { id: 'WU-043', status: 'ready' },
]);

Type Definitions

WuSpec

interface WuSpec {
  id: string;
  title: string;
  lane: string;
  type: 'feature' | 'bug' | 'documentation' | 'refactor';
  status: WuStatus;
  priority: 'P0' | 'P1' | 'P2' | 'P3';
  description: string;
  acceptance: string[];
  code_paths: string[];
  test_paths?: {
    unit?: string[];
    integration?: string[];
    e2e?: string[];
  };
  dependencies?: string[];
  blocked_by?: string[];
  created: string;
  assigned_to?: string;
  notes?: string;
}

WuStatus

enum WuStatus {
  READY = 'ready',
  IN_PROGRESS = 'in_progress',
  BLOCKED = 'blocked',
  WAITING = 'waiting',
  DONE = 'done',
}

LocationContext

interface LocationContext {
  type: LocationType;
  cwd: string;
  gitRoot: string;
  mainCheckout: string;
  worktreeName: string | null;
  worktreeWuId: string | null;
}

enum LocationType {
  MAIN = 'main',
  WORKTREE = 'worktree',
  DETACHED = 'detached',
  UNKNOWN = 'unknown',
}

GitState

interface GitState {
  branch: string | null;
  isDetached: boolean;
  isDirty: boolean;
  hasStaged: boolean;
  ahead: number;
  behind: number;
  tracking: string | null;
  modifiedFiles: string[];
  hasError: boolean;
  errorMessage: string | null;
}

Generating Documentation

To generate TypeDoc documentation locally:

# Install TypeDoc (if not already)
pnpm add -D typedoc typedoc-plugin-markdown

# Generate docs
pnpm typedoc --out docs/api packages/@lumenflow/*/src/index.ts