Skip to main content

​
Execution API

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

​
Methods

​
start

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

​
complete

Mark execution as complete. 
await db.execution.complete(executionId, {
  summary: "Feature implemented successfully",
  output: result,
});

​
fail

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

​
cancel

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

​
current

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

​
get

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

​
list

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

​
findIncomplete

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

​
Usage Patterns

​
Resume on Startup

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

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

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

  // ... run workflow ...

  await db.execution.complete(executionId);
  await db.close();
}

​
Track Multiple Executions

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

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

​
Types

interface Execution {
  id: string;
  name: string;
  filePath: string;
  status: "pending" | "running" | "complete" | "failed" | "cancelled";
  config?: Record<string, any>;
  result?: Record<string, any>;
  error?: string;
  startedAt: Date;
  completedAt?: Date;
}

Agents API

Track agents

VCS API

Version control