SDK Reference - Overview

Stoneforge is built as a modular monorepo with six core packages that work together to provide agent orchestration, data management, and UI components.

Package Dependency Graph

Package Overview

@stoneforge/core

Foundation layer with types, errors, and ID generation

@stoneforge/storage

Multi-runtime SQLite backends (Bun, Node, Browser)

@stoneforge/quarry

Core API, services, sync, and CLI

@stoneforge/smithy

AI agent orchestration and session management

@stoneforge/ui

React 19 component library and design tokens

@stoneforge/shared-routes

Hono route factories for HTTP servers

Design Principles

Dual Storage Model

Stoneforge uses a dual storage architecture:

SQLite: Fast queries with indexes, FTS5 search, and materialized views. Acts as a cache.
JSONL: Git-tracked, append-only files. The source of truth for all durable data.

Key Principle: SQLite is the cache, JSONL is the source of truth. SQLite can be rebuilt from JSONL at any time.

Event Sourcing

Every mutation produces an immutable event, giving you:

Full audit trail
Point-in-time reconstruction
Document version history
Sync conflict resolution

Type Safety

All packages use TypeScript with strict mode and branded types:

ElementId, TaskId, EntityId, DocumentId
Type guards: isTask(), isElement(), etc.
Runtime validation at API boundaries

Installation Patterns

For End Users (CLI + Orchestration)

npm install -g @stoneforge/smithy

This installs the sf CLI and includes all dependencies.

For Library Users (Core SDK)

npm install @stoneforge/core @stoneforge/storage @stoneforge/quarry

For Custom Orchestration

npm install @stoneforge/smithy

For UI Development

npm install @stoneforge/ui react react-dom
npm install @tanstack/react-query @tanstack/react-router

Quick Start Example

import { createStorage, initializeSchema } from '@stoneforge/storage';
import { createQuarryAPI } from '@stoneforge/quarry/api';
import type { Task } from '@stoneforge/core';

// Create storage backend (auto-detects Bun/Node runtime)
const storage = createStorage({ path: '.stoneforge/db.sqlite' });
initializeSchema(storage);

// Create API instance
const api = createQuarryAPI(storage);

// Create a task
const task = await api.create<Task>({
  type: 'task',
  title: 'Implement authentication',
  priority: 2,
  createdBy: 'el-operator',
});

// Query ready work
const ready = await api.ready();
console.log(`${ready.length} tasks ready`);

Entry Points

Each package provides multiple entry points for tree-shaking and code organization:

@stoneforge/core
@stoneforge/storage
@stoneforge/quarry
@stoneforge/smithy

@stoneforge/core — All exports
@stoneforge/core/types — Type definitions only
@stoneforge/core/errors — Error classes and factories
@stoneforge/core/id — ID generation and validation
@stoneforge/core/utils — Utility functions

@stoneforge/storage — Runtime-agnostic API
@stoneforge/storage/bun — Bun-specific backend
@stoneforge/storage/node — Node.js backend
@stoneforge/storage/browser — Browser backend

@stoneforge/quarry — All exports
@stoneforge/quarry/api — QuarryAPI interface
@stoneforge/quarry/services — Business logic services
@stoneforge/quarry/sync — JSONL sync system
@stoneforge/quarry/cli — CLI commands
@stoneforge/quarry/config — Configuration management

@stoneforge/smithy — All exports
@stoneforge/smithy/types — Agent types and metadata
@stoneforge/smithy/services — Orchestration services
@stoneforge/smithy/runtime — Session management
@stoneforge/smithy/git — Git worktree utilities
@stoneforge/smithy/providers — Agent provider interface

Version Compatibility

Package	Version	Node	Bun	Browser
`@stoneforge/core`	1.13.0	≥18	✓	✓
`@stoneforge/storage`	1.13.0	≥18	✓	✓
`@stoneforge/quarry`	1.13.0	≥18	✓	—
`@stoneforge/smithy`	1.13.0	≥18	✓	—
`@stoneforge/ui`	1.13.0	≥18	✓	✓
`@stoneforge/shared-routes`	1.13.0	≥18	✓	—

All packages follow semver with changelogs. Breaking changes are always signaled with major version bumps.

Next Steps

Core Package

Learn about types, errors, and ID generation

Storage Package

Understand the SQLite backend system

Quarry API

Explore the main API and services

Smithy Orchestration

Build agent orchestration systems

Packages

API Reference

Types

SDK Reference - Overview

SDK Reference - Overview

Package Dependency Graph

Package Overview

@stoneforge/core

@stoneforge/storage

@stoneforge/quarry

@stoneforge/smithy

@stoneforge/ui

@stoneforge/shared-routes

Design Principles

Dual Storage Model

Event Sourcing

Type Safety

Installation Patterns

For End Users (CLI + Orchestration)

For Library Users (Core SDK)

For Custom Orchestration

For UI Development

Quick Start Example

Entry Points

Version Compatibility

Next Steps

Core Package

Storage Package

Quarry API

Smithy Orchestration

Build docs developers (and LLMs) love

Packages

API Reference

Types

​SDK Reference - Overview

​Package Dependency Graph

​Package Overview

@stoneforge/core

@stoneforge/storage

@stoneforge/quarry

@stoneforge/smithy

@stoneforge/ui

@stoneforge/shared-routes

​Design Principles

​Dual Storage Model

​Event Sourcing

​Type Safety

​Installation Patterns

​For End Users (CLI + Orchestration)

​For Library Users (Core SDK)

​For Custom Orchestration

​For UI Development

​Quick Start Example

​Entry Points

​Version Compatibility

​Next Steps

Core Package

Storage Package

Quarry API

Smithy Orchestration

Build docs developers (and LLMs) love

SDK Reference - Overview

Package Dependency Graph

Package Overview

Design Principles

Dual Storage Model

Event Sourcing

Type Safety

Installation Patterns

For End Users (CLI + Orchestration)

For Library Users (Core SDK)

For Custom Orchestration

For UI Development

Quick Start Example

Entry Points

Version Compatibility

Next Steps