Tasks API
The db.tasks module provides task tracking for Ralph iteration management. It tracks component-level tasks within the execution lifecycle.
Contract
- Sync: All methods are synchronous except
withTask, which returns a Promise.
- Scope: Methods operate on the current execution.
Overview
import { createSmithersDB } from "smithers-orchestrator";
const db = createSmithersDB({ path: ".smithers/my-workflow" });
// Start a task
const taskId = db.tasks.start("claude", "code-analyzer");
// Complete the task
db.tasks.complete(taskId);
// Or mark as failed
db.tasks.fail(taskId);
Methods
start
Starts a new task and returns its ID.
function start(componentType: string, componentName?: string): string
The type of component (e.g., “claude”, “review”, “commit”).
Optional name for the component instance.
complete
Marks a task as completed.
function complete(id: string): void
fail
Marks a task as failed.
function fail(id: string): void
The task ID to mark as failed.
fail() marks task status only; it does not stop orchestration.
getRunningCount
Gets the count of running tasks for a specific iteration.
function getRunningCount(iteration: number): number
The Ralph iteration number.
getTotalCount
Gets the count of all tasks for a specific iteration.
function getTotalCount(iteration: number): number
list
Gets all tasks for the current execution.
getCurrentIteration
Gets the current Ralph iteration from the state table.
function getCurrentIteration(): number
withTask
Executes a function within a task lifecycle (start → complete/fail).
function withTask<T>(
componentType: string,
componentName: string | undefined,
fn: () => T | Promise<T>
): Promise<T>
Task Type
interface Task {
id: string;
execution_id: string;
iteration: number;
component_type: string;
component_name: string | null;
status: 'running' | 'completed' | 'failed';
started_at: string;
completed_at: string | null;
duration_ms: number | null;
}
Usage in Components
The Claude component automatically uses the tasks module:
// Inside Claude component (simplified)
const taskId = db.tasks.start('claude', props.model);
try {
// Execute Claude CLI...
db.tasks.complete(taskId);
} catch {
db.tasks.fail(taskId);
}
Querying Tasks
// List all tasks
const allTasks = db.tasks.list();
// Count running tasks in current iteration
const iteration = db.tasks.getCurrentIteration();
const runningCount = db.tasks.getRunningCount(iteration);
// Check if all tasks completed
const totalCount = db.tasks.getTotalCount(iteration);
if (runningCount === 0 && totalCount > 0) {
console.log("All tasks completed for this iteration");
}
