API Documentation

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

Package APIs

@hellmai/lumenflow-cli

Command implementations, argument parsing

@hellmai/lumenflow-packs-software-delivery

WU lifecycle, initiatives, delivery metrics, and workflow memory

@hellmai/lumenflow-agent

Skill loading, agent definitions, verification

Software Delivery Pack API

WU Lifecycle

WU lifecycle operations are implemented as CLI commands:

pnpm wu:create \
  --id WU-042 \
  --title "Add email validation" \
  --lane "Framework: Core" \
  --type feature \
  --exposure backend-only \
  --description "Validate email input before persistence" \
  --acceptance "Invalid email input is rejected with a stable error" \
  --notes "Reuse the existing validation result type" \
  --code-paths "src/validation/email.ts" \
  --test-paths-unit "src/validation/__tests__/email.test.ts" \
  --test-paths-manual "Submit valid and invalid email values through the API smoke request" \
  --plan
pnpm wu:claim --id WU-042 --lane "Framework: Core"
pnpm wu:done --id WU-042

State Machine

import { assertTransition } from '@hellmai/lumenflow-packs-software-delivery/state/state-machine';

// Throws if the transition is illegal; returns void if it is valid.
assertTransition('ready', 'in_progress', 'WU-042');

Configuration

import {
  getConfig,
  validateConfigFile,
} from '@hellmai/lumenflow-packs-software-delivery/config/lumenflow-config';

// Load resolved config (workspace.yaml's software_delivery block + schema defaults)
const config = getConfig({ projectRoot: '/path/to/repository' });

// Validate a config file directly
const { valid, errors } = validateConfigFile('/path/to/workspace.yaml');
if (!valid) {
  console.error('Config issues:', errors);
}

Workspace-rooted plan references

getRepoPlansDir, getRepoPlanPath, normalizeSpecRef, validateSpecRefs, and normalizeSpecRefs require an explicit workspace root. Passing the root prevents plan lookup and validation from silently following an unrelated process working directory. The v6 compatibility imports shown below no longer resolve in v7.

Before v7:

import { normalizeSpecRef } from '@hellmai/lumenflow-core/lumenflow-home';
import { validateSpecRefs } from '@hellmai/lumenflow-core/wu-create-validators';

const planPath = normalizeSpecRef('lumenflow://plans/WU-042-plan.md');
const validation = validateSpecRefs(['lumenflow://plans/WU-042-plan.md']);

After:

import { normalizeSpecRef } from '@hellmai/lumenflow-packs-software-delivery/runtime/authoring/lumenflow-home';
import { validateSpecRefs } from '@hellmai/lumenflow-packs-software-delivery/runtime/authoring/wu-create-validators';

const workspaceRoot = '/path/to/repository';
const planPath = normalizeSpecRef('lumenflow://plans/WU-042-plan.md', workspaceRoot);
const validation = validateSpecRefs(['lumenflow://plans/WU-042-plan.md'], workspaceRoot);

The asynchronous delegation registry discovery API remains backward compatible: resolveCanonicalDelegationRegistryDir() can still be called without an argument. Code that already knows its checkout should continue to pass that directory explicitly.

Cost Telemetry

import { syncNdjsonTelemetryToCloud } from '@hellmai/lumenflow-packs-software-delivery/runtime/telemetry';
import { emitCostEvent } from '@hellmai/lumenflow-packs-software-delivery';
import type { CostEvent, CostSummary } from '@hellmai/lumenflow-packs-software-delivery/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-101',
  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 '@hellmai/lumenflow-control-plane-sdk';

const heartbeatRequest: HeartbeatInput = {
  workspace_id: 'workspace-a',
  session_id: 'session-a',
  agent_id: 'agent-1',
  wu_id: 'WU-102',
  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-102',
    action: 'continue',
    hint: 'server-directed cadence',
  },
  budget_remaining_usd: 42.5,
  coalesced_signals: 2,
};

Session Metadata Contracts

import type { RegisterSessionInput, SessionSummary } from '@hellmai/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-103',
  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 {
  computeContext,
  resolveLocation,
  readGitState,
  readWuState,
} from '@hellmai/lumenflow-packs-software-delivery/runtime/context';
import { LocationType } from '@hellmai/lumenflow-packs-software-delivery/domain';

// 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');
}

// Compute the complete WU context
const result = await computeContext({
  wuId: 'WU-042',
});

Agent Branch Detection

import {
  isAgentBranch,
  isAgentBranchWithDetails,
  resolveAgentPatterns,
} from '@hellmai/lumenflow-packs-software-delivery/runtime/authoring';

// 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'

Software Delivery Pack: Memory API

The Software Delivery pack is the canonical owner of delivery/workflow memory. The @hellmai/lumenflow-memory package remains available as a deprecated compatibility shell, but new code should use the pack subpath below.

Session Tracking

import {
  startSession,
  type StartSessionResult,
} from '@hellmai/lumenflow-packs-software-delivery/memory';

const projectRoot = '/path/to/repository';
const result: StartSessionResult = await startSession(projectRoot, {
  wuId: 'WU-042',
  agentType: 'claude-code', // example; use your project's configured client
  contextTier: 'full',
});

console.log(result.session.id);

Checkpoints

import { createCheckpoint } from '@hellmai/lumenflow-packs-software-delivery/memory';

const result = await createCheckpoint('/path/to/repository', {
  wuId: 'WU-042',
  note: 'Tests passing, starting implementation',
  progress: 'Validation tests are green',
  nextSteps: 'Wire the validator into the form',
});

console.log(result.checkpoint.id);

Signals

import {
  createSignal,
  loadInboxSignalViews,
  type Signal,
} from '@hellmai/lumenflow-packs-software-delivery/memory';

const projectRoot = '/path/to/repository';
const created = await createSignal(projectRoot, {
  wuId: 'WU-042',
  message: 'Implementation complete',
  type: 'progress',
  sender: 'codex:implementer',
});

const inbox = await loadInboxSignalViews(projectRoot, {
  wuId: 'WU-042',
  unreadOnly: true,
});

const signal: Signal = created.signal;
console.log(signal.id, inbox.length);

Agent Package API

Skill Loading

There is no loadSkill/listSkills/validateSkill API in @hellmai/lumenflow-agent. Skill definitions are validated by validateSkillFile/validateAllSkills in @hellmai/lumenflow-cli/src/validate-agent-skills.ts, an internal helper not currently exposed through the package’s public exports. Invoke it via the internal CLI entry point instead:

node tools/cli-entry.mjs validate-agent-skills

Agent Verification

import { verifyWUComplete, type VerificationResult } from '@hellmai/lumenflow-agent';

// Verify WU completion
const result: VerificationResult = verifyWUComplete('WU-042');
if (result.complete) {
  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 { printHeader, createStatusTable } from '@hellmai/lumenflow-cli';

// Print the LumenFlow CLI banner
printHeader({ version: '5.19.0' });

// Format a status table
const table = createStatusTable({
  head: ['ID', 'Status'],
  rows: [
    ['WU-042', 'done'],
    ['WU-043', 'ready'],
  ],
});
console.log(table);

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