SoulForge (Empryo) Documentation

SoulForge is licensed under the Business Source License 1.1. This means usage is free for personal, internal, and educational purposes, but requires a commercial license for any form of commercial distribution or service offering.

Free Usage

You can use SoulForge for:

• Personal projects
• Internal use within your organization (including employees and contractors)
• Education and research
• Forking, modifying, and contributing back to the project
• Building plugins, MCP servers, and integrations for non-commercial use

Commercial License Requirements

A commercial license is required if you are:

• Offering SoulForge (or a modified version) to third parties as a paid product
• Offering SoulForge as a hosted or managed service
• Embedding SoulForge as a component in any product or service sold to third parties
• Engaging in any commercial distribution (standalone, bundled, or wrapped)
• Using SoulForge to build and sell a product that provides similar functionality, even if features are added or removed.

SoulForge provides several advanced features for AI-driven development:

• Live Soul Map: A SQLite-based graph of every file, symbol, and import, updated as you work. It uses PageRank and git co-change to rank importance and provides 'blast-radius' tags to show the impact of edits.
• Full LSP Support: Access definitions, references, diagnostics, and code actions. You can install language servers directly from the TUI using /lsp install via the Mason registry.
• V2 Compaction: Automatically extracts structured state (files touched, decisions, tool results) during a session. When context limits are reached, it serializes this state to keep the conversation efficient, often without requiring an LLM pass.
• Parallel Agents: Dispatches specialized agents (explore, code, web-search) in parallel. Agents share a cache, so one agent's file reads are available to others.
• Task Router: Allows using different models for different roles (e.g., 'spark' for exploration, 'ember' for code, 'verify' for review) to optimize cost and speed.
• Sessions and Checkpoints: Every turn is a checkpoint. You can use git tags for file rollback and resume sessions using a short-id prefix.

The telemetry system is designed to be private and resilient against data exfiltration and noise:

• Anonymity: No prompts, paths, keys, IPs, or PII are recorded. Model strings are collapsed to other if they do not match known public-model patterns to prevent leaking secrets or project names.
• Strict Validation: The worker uses an allow-list for fields like os, arch, surface, event, install, and family. It also validates version (semver) and id (UUIDv4). Invalid pings are silently dropped (returning 204) without error messages to prevent leaking validation logic.
• Rate Limiting: A per-IP rate limit is enforced (60 requests per 60 seconds) using Cloudflare's native rate-limiting binding. The IP is used only as a limiter key and is never stored.
• User-Agent Filtering: Requests lacking the soulforge/<version> marker are ignored to reduce scanner noise.
• Write-Only Architecture: Data is written directly to the Analytics Engine. There is no database that can be read back or corrupted to exfiltrate data.

Concept: AST-native editing

ast_edit is an AI coding tool that edits TypeScript and JavaScript files by manipulating their Abstract Syntax Tree (AST) rather than using text matching or string manipulation.

Key Characteristics:

• Symbol-based: It addresses code elements by their kind (e.g., function, class) and name, rather than line numbers or text snippets.
• Structural Mutation: It mutates the code structure directly, making it immune to whitespace changes or formatting shifts.
• Atomic Batches: When using the operations array, edits are all-or-nothing. If any single operation in a batch fails, the entire batch is rejected.
• Safety & Diagnostics: Files are snapshotted before editing to prevent mid-flight conflicts. After an edit, type diagnostics (errors) are immediately returned to the agent to ensure the mutation didn't break the codebase.

// Example of an atomic batch operation
ast_edit({
  path: "src/api.ts",
  operations: [
    { action: "set_async", target: "function", name: "fetchUser", value: "true" },
    { action: "add_parameter", target: "function", name: "fetchUser", value: "cache: boolean" },
    { action: "add_named_import", value: "./types", newCode: "User" },
  ],
})