Skip to main content

Execution API

The execution API tracks workflow runs, enabling resume and observability.

Contract

  • Sync: All methods are synchronous.
  • Return shape: snake_case fields with Date objects for timestamps.
  • Status: pending | running | completed | failed | cancelled.

Methods

start

Start a new execution.
const executionId = db.execution.start(
  "Feature Implementation",  // name
  "scripts/feature.tsx",     // file path
  { timeout: 3600000 }       // optional config
);

complete

Mark execution as complete.
db.execution.complete(executionId);

// Optional result payload (stored as JSON)
db.execution.complete(executionId, { summary: "Feature implemented successfully" });
Result payload is optional. If omitted, executions.result is stored as null.

fail

Mark execution as failed.
db.execution.fail(executionId, "Tests failed");

cancel

Cancel an execution.
db.execution.cancel(executionId);

current

Get the current execution.
const current = db.execution.current();
if (current) {
  console.log(`Running: ${current.name}`);
}

get

Get a specific execution.
const execution = db.execution.get(executionId);

list

List recent executions.
const recent = db.execution.list(10);

findIncomplete

Find an incomplete execution (for resume).
const incomplete = db.execution.findIncomplete();
if (incomplete) {
  console.log("Resuming:", incomplete.id);
}

Completion and <End>

  • db.execution.complete() updates status, result, and completed_at.
  • <End> writes end_summary, end_reason, and exit_code to the executions table.
// Read End summary via raw query
const row = db.db.queryOne<{ end_summary: string | null }>(
  "SELECT end_summary FROM executions WHERE id = ?",
  [executionId]
);
const endSummary = row?.end_summary ? JSON.parse(row.end_summary) : null;

Usage Patterns

Resume on Startup

function main() {
  const db = createSmithersDB({ path: ".smithers/data" });

  // Check for interrupted execution
  let executionId: string;
  const incomplete = db.execution.findIncomplete();

  if (incomplete) {
    executionId = incomplete.id;
    console.log(`Resuming execution: ${executionId}`);
  } else {
    executionId = db.execution.start("New Task", "task.tsx");
  }

  try {
    // ... run workflow ...

    db.execution.complete(executionId);
  } catch (err) {
    const error = err instanceof Error ? err : new Error(String(err));
    db.execution.fail(executionId, error.message);
    throw error;
  } finally {
    db.close();
  }
}

Track Multiple Executions

// List recent executions
const executions = db.execution.list(10);

for (const exec of executions) {
  console.log(`${exec.name}: ${exec.status}`);
  console.log(`  Started: ${exec.started_at}`);
  if (exec.completed_at) {
    console.log(`  Completed: ${exec.completed_at}`);
  }
}

Types

interface Execution {
  id: string;
  name?: string;
  file_path: string;
  status: "pending" | "running" | "completed" | "failed" | "cancelled";
  config: Record<string, any>;
  result?: Record<string, any>;
  error?: string;
  started_at?: Date;
  completed_at?: Date;
  created_at: Date;
  total_iterations: number;
  total_agents: number;
  total_tool_calls: number;
  total_tokens_used: number;
}