Skip to main content

​
Artifacts API

The db.artifacts module tracks files and outputs generated during workflow execution.

​
Contract

  • Sync: All methods are synchronous.
  • Execution scope: add() uses the current execution (set by db.execution.start()).
  • Return shape: snake_case fields with Date timestamps; metadata defaults to {}.

​
Overview

import { createSmithersDB } from "smithers-orchestrator";

const db = createSmithersDB({ path: ".smithers/my-workflow" });

// Add an artifact
const artifactId = db.artifacts.add(
  "analysis-report",
  "document",
  "./reports/analysis.md",
  agentId,
  { format: "markdown", wordCount: 1500 }
);

​
Methods

​
add

Adds a new artifact. 
const artifactId = db.artifacts.add(
  name: string,
  type: 'file' | 'code' | 'document' | 'image' | 'data',
  filePath: string,
  agentId?: string,
  metadata?: Record<string, any>
): string
​
name
string
required
Human-readable name for the artifact.
​
type
'file' | 'code' | 'document' | 'image' | 'data'
required
The type of artifact.
​
filePath
string
required
Path to the artifact file (stored as provided).
​
agentId
string
Optional ID of the agent that created this artifact.
​
metadata
Record<string, any>
Optional metadata about the artifact. Defaults to {}.
Returns: The artifact ID.

​
list

Lists all artifacts for an execution. 
const artifacts = db.artifacts.list(executionId: string): Artifact[]

​
Artifact Type

interface Artifact {
  id: string;
  execution_id: string;
  agent_id?: string;
  name: string;
  type: 'file' | 'code' | 'document' | 'image' | 'data';
  file_path: string;
  metadata: Record<string, any>;
  git_hash?: string;
  git_commit?: string;
  summary?: string;
  line_count?: number;
  byte_size?: number;
  created_at: Date;
}

​
Artifact Types

TypeDescriptionExamples
fileGeneric file artifactAny file path
codeGenerated source code.ts, .tsx, .py files
documentReports and docs.md, .html, .txt
imageImages.png, .jpg, .svg
dataData files.json, .csv exports

​
Path Conventions

  • Paths are stored exactly as provided (no normalization).
  • Smithers does not validate file existence on add().
  • Recommended: store repo-relative paths for portability.

​
Examples

​
Tracking Generated Code

<Claude
  onFinished={async (result) => {
    // Track generated files
    for (const file of result.filesModified) {
      db.artifacts.add(
        file.name,
        "code",
        file.path,
        agentId,
        {
          linesAdded: file.insertions,
          linesRemoved: file.deletions,
        }
      );
    }
  }}
>
  Generate a new API endpoint.
</Claude>

​
Tracking Reports

<Review
  onFinished={(review) => {
    // Save review as artifact
    const reportPath = `./reports/review-${Date.now()}.md`;
    Bun.write(reportPath, JSON.stringify(review, null, 2));

    db.artifacts.add(
      "code-review",
      "document",
      reportPath,
      undefined,
      {
        approved: review.approved,
        issueCount: review.issues.length,
      }
    );
  }}
/>

​
Tracking Logs

const logPath = `./logs/agent-${agentId}.log`;

db.artifacts.add(
  "agent-output",
  "file",
  logPath,
  agentId,
  {
    tokensUsed: result.tokensUsed,
    durationMs: result.durationMs,
  }
);

​
Querying Artifacts

// Get all artifacts
const artifacts = db.artifacts.list(executionId);

// Filter by type
const reports = artifacts.filter((a) => a.type === "report");
const code = artifacts.filter((a) => a.type === "code");

// Get artifacts by agent
const agentArtifacts = artifacts.filter((a) => a.agent_id === agentId);

// Calculate total generated code
const codeArtifacts = artifacts.filter((a) => a.type === "code");
const totalLines = codeArtifacts.reduce(
  (sum, a) => sum + (a.metadata.linesAdded || 0),
  0
);

Agents API

Agent tracking

VCS API

Version control tracking