Skip to main content

VCS API

The VCS API tracks commits, snapshots, reviews, and reports for the current execution.

Contract

  • Sync: All methods are synchronous.
  • Return shape: snake_case fields with Date timestamps.
  • Scope: Lists are scoped to the current execution.

Commits

logCommit

Log a git/jj commit.
const commitId = db.vcs.logCommit({
  vcs_type: "git",
  commit_hash: "abc123def",
  change_id: "CABC123",
  message: "feat: Add user authentication",
  author: "claude",
  files_changed: ["src/auth.ts"],
  insertions: 150,
  deletions: 20,
  smithers_metadata: { phase: "implementation" },
});

getCommits

List recent commits (current execution).
const commits = db.vcs.getCommits(10);

getCommit

Get a specific commit by hash.
const commit = db.vcs.getCommit("abc123def", "git");

Snapshots

logSnapshot

Log a jj snapshot.
const snapshotId = db.vcs.logSnapshot({
  change_id: "CXYZ789",
  description: "Before refactoring auth module",
  commit_hash: "abc123def",
  files_modified: ["src/auth.ts"],
  files_added: ["src/auth.test.ts"],
  files_deleted: [],
  has_conflicts: false,
});

getSnapshots

List snapshots for the current execution.
const snapshots = db.vcs.getSnapshots(10);

Reviews

logReview

Log a code review.
const reviewId = db.vcs.logReview({
  target_type: "commit",
  target_ref: "abc123def",
  approved: false,
  summary: "Security issues found",
  issues: [
    {
      severity: "critical",
      file: "src/auth.ts",
      line: 42,
      message: "SQL injection vulnerability",
      suggestion: "Use parameterized queries",
    },
  ],
  reviewer_model: "sonnet",
  blocking: true,
});

updateReview

Update review publish flags.
db.vcs.updateReview(reviewId, {
  posted_to_github: true,
  posted_to_git_notes: true,
});

getReviews

List reviews.
const reviews = db.vcs.getReviews(10);

getBlockingReviews

Get blocking reviews.
const blocking = db.vcs.getBlockingReviews();
if (blocking.length > 0) {
  console.log("Cannot proceed - blocking reviews exist");
}

Reports

addReport

Add a workflow report.
db.vcs.addReport({
  type: "progress",
  severity: "info",
  title: "Phase Complete",
  content: "Research phase completed successfully",
  data: { phase: "research", duration_ms: 5000 },
});

db.vcs.addReport({
  type: "finding",
  severity: "warning",
  title: "Potential Issue",
  content: "Found deprecated API usage",
  agent_id: agentId,
});

db.vcs.addReport({
  type: "error",
  severity: "critical",
  title: "Build Failed",
  content: "TypeScript compilation errors",
});

getReports

List reports.
// All reports
const reports = db.vcs.getReports();

// By type
const errors = db.vcs.getReports("error", 10);

getCriticalReports

Get critical severity reports.
const critical = db.vcs.getCriticalReports();
if (critical.length > 0) {
  console.error("Critical issues detected!");
}

Types

interface Commit {
  id: string;
  execution_id: string;
  agent_id?: string;
  vcs_type: "git" | "jj";
  commit_hash: string;
  change_id?: string;
  message: string;
  author?: string;
  files_changed?: string[];
  insertions?: number;
  deletions?: number;
  smithers_metadata?: Record<string, any>;
  created_at: Date;
}

interface Snapshot {
  id: string;
  execution_id: string;
  change_id: string;
  commit_hash?: string;
  description?: string;
  files_modified?: string[];
  files_added?: string[];
  files_deleted?: string[];
  has_conflicts: boolean;
  created_at: Date;
}

interface Review {
  id: string;
  execution_id: string;
  agent_id?: string;
  target_type: "commit" | "diff" | "pr" | "files";
  target_ref?: string;
  approved: boolean;
  summary: string;
  issues: ReviewIssue[];
  approvals?: ReviewApproval[];
  reviewer_model?: string;
  blocking: boolean;
  posted_to_github: boolean;
  posted_to_git_notes: boolean;
  created_at: Date;
}

interface ReviewIssue {
  severity: "critical" | "major" | "minor" | "suggestion";
  file?: string;
  line?: number;
  message: string;
  suggestion?: string;
}

interface ReviewApproval {
  aspect: string;
  reason: string;
}

interface Report {
  id: string;
  execution_id: string;
  agent_id?: string;
  type: "progress" | "finding" | "warning" | "error" | "metric" | "decision";
  title: string;
  content: string;
  data?: Record<string, any>;
  severity: "info" | "warning" | "critical";
  created_at: Date;
}