TypeScript API Overview

Introduction to Conway Automaton’s TypeScript API for building and extending sovereign AI agents

The Conway Automaton TypeScript API provides programmatic access to the core runtime, state management, and configuration systems. Use these APIs to build custom tools, extend agent capabilities, and integrate with the automaton’s lifecycle.

Installation

The TypeScript API is bundled with the Conway Automaton runtime:

npx conway init

Core Modules

The API is organized into three primary modules:

Configuration

Load, save, and manage automaton configuration

Database

SQLite-backed state management and persistence

Types

TypeScript interfaces and type definitions

Quick Start

Import Core APIs

import { loadConfig, saveConfig } from "./config.js";
import { createDatabase } from "./state/database.js";
import type { AutomatonConfig, AutomatonDatabase } from "./types.js";

Load Configuration

const config = loadConfig();
if (!config) {
  console.error("No configuration found. Run 'conway init' first.");
  process.exit(1);
}

Access Database

const db = createDatabase(config.dbPath);
const recentTurns = db.getRecentTurns(10);
console.log(`Last 10 turns:`, recentTurns);

Architecture

The TypeScript API follows these design principles:

Type Safety

All public APIs are fully typed with TypeScript interfaces. The runtime enforces type checking at compile time and validation at runtime.

interface AutomatonConfig {
  name: string;
  genesisPrompt: string;
  walletAddress: Address;
  inferenceModel: string;
  // ... 20+ additional fields
}

Immutable Configuration

Configuration is loaded from ~/.automaton/automaton.json and merged with defaults. Changes must be explicitly saved:

const config = loadConfig();
config.maxTokensPerTurn = 8192;
saveConfig(config); // Persists to disk

SQLite-Backed State

All runtime state is stored in a SQLite database with automatic schema migrations:

• Turns: Agent reasoning and tool execution history
• Transactions: Financial state and credit balance
• Skills: Installed capabilities and instructions
• Children: Spawned child automatons and their lifecycle
• Memory: Working, episodic, semantic, and procedural memory

Transaction Support

Database operations support atomic transactions:

db.runTransaction(() => {
  db.insertTurn(turn);
  db.insertTransaction(txn);
  db.setAgentState("running");
});

Common Patterns

Reading Recent History

const turns = db.getRecentTurns(5);
for (const turn of turns) {
  console.log(`[${turn.timestamp}] ${turn.thinking}`);
  for (const call of turn.toolCalls) {
    console.log(`  Tool: ${call.name}`);
  }
}

Managing Financial State

const txns = db.getRecentTransactions(10);
const latestBalance = txns[txns.length - 1]?.balanceAfterCents ?? 0;
console.log(`Current balance: ${latestBalance / 100} USD`);

Tracking Children

const children = db.getChildren();
for (const child of children) {
  console.log(`${child.name} (${child.status}): ${child.address}`);
}

API Stability

The TypeScript API follows semantic versioning:

• Breaking changes: Major version bump (v1 → v2)
• New features: Minor version bump (v1.0 → v1.1)
• Bug fixes: Patch version bump (v1.0.0 → v1.0.1)

Current version: v0.2.1 (pre-1.0, API subject to change)

Next Steps

Configuration API

Load and manage automaton configuration

Database API

Access persistent state and memory