API Reference

Public API for programmatic use of Loom

API Reference

The pkg/api package provides the public API for programmatic use of Loom.

Installation

go get github.com/uttufy/loom

Creating a Loom Instance

From Config File

import "github.com/uttufy/loom/pkg/api"

loom, err := api.NewFromConfigFile("loom.yaml")

With Explicit Config

import (
    "github.com/uttufy/loom/internal/config"
    "github.com/uttufy/loom/pkg/api"
)

cfg := config.DefaultConfig()
loom, err := api.New(cfg)

Core Operations

Run the Orchestrator

err := loom.Run(ctx)

Starts the main orchestration loop. Runs until context is cancelled or no work remains.

Stop the Orchestrator

loom.Stop()

Stops a running orchestrator gracefully.

Get Ready Tasks

tasks, err := loom.GetReadyTasks(ctx)
for _, task := range tasks {
    fmt.Printf("%s: %s (score: %d)\n", task.Issue.ID, task.Issue.Title, task.Score)
}

Returns ready tasks sorted by priority score.

Task Management

Claim a Task

err := loom.ClaimTask(ctx, "issue-123", "my-agent", []string{"src/main.go"})

Claims a task and optionally locks files for coordination.

Complete a Task

err := loom.CompleteTask(ctx, "issue-123", "Implemented feature X")

Marks a task as completed with a summary.

Record Task Failure

err := loom.FailTask(ctx, "issue-123", fmt.Errorf("tests failed"))

Records a failure and releases the task back to open status.

Hooks

Register a Hook

loom.RegisterHook(hooks.EventPreToolCall, func(ctx context.Context, hc *hooks.Context) (*hooks.Result, error) {
    // Validate tool call
    if hc.ToolCall.Name == "bash" {
        if isDestructive(hc.ToolCall.Command) {
            return &hooks.Result{
                Block:  true,
                Reason: "destructive command blocked",
            }, nil
        }
    }
    return &hooks.Result{}, nil
})

Safety

Validate Commands

err := loom.ValidateCommand("bash", "rm -rf /")
if safety.IsBlocked(err) {
    fmt.Println("Command was blocked")
}

Approve Commands

loom.ApproveCommand("git push origin main")

Coordination

Get File Locks

locks := loom.GetLocks()
for _, lock := range locks {
    fmt.Printf("%s locked by %s\n", lock.FilePath, lock.AgentID)
}

Detect Conflicts

conflicts, err := loom.DetectConflicts(ctx)
for _, c := range conflicts {
    fmt.Printf("Conflict on %s between %s and %s\n", c.File, c.Agent1, c.Agent2)
}

Learning

Get Patterns

patterns := loom.GetPatterns()
for _, p := range patterns {
    fmt.Printf("%s: %s\n", p.Name, p.Description)
}

Save Retrospective

retro := &retrospective.Retrospective{
    SessionID:  "session-123",
    AgentID:    "my-agent",
    Completed:  []string{"issue-1", "issue-2"},
    Strategies: []string{"TDD approach worked well"},
}
err := loom.SaveRetrospective(retro)

Memory

Check Memory Stats

stats := loom.GetMemoryStats()
fmt.Printf("Context usage: %.0f%%\n", stats.ContextUsage * 100)

Check if Compaction Needed

if loom.ShouldCompact(0.75) {
    loom.Compact(ctx)
}

Scoring

Score a Single Task

issue := &beadsclient.Issue{
    ID:       "issue-1",
    Title:    "Fix bug",
    Priority: 1,
}
score, err := loom.ScoreTask(ctx, issue)
fmt.Printf("Score: %d\n", score)

Low-Level Access

Get Beads Client

client := loom.GetClient()
issues, err := client.Ready(ctx, beadsclient.WorkFilter{})

Get Configuration

cfg := loom.GetConfig()
fmt.Printf("Compact threshold: %.0f%%\n", cfg.Memory.CompactThreshold * 100)

Types

ScoredIssue

type ScoredIssue struct {
    Issue *beadsclient.Issue
    Score int
}

FileLock

type FileLock struct {
    FilePath  string
    IssueID   string
    AgentID   string
    ClaimedAt time.Time
    ExpiresAt time.Time
}

Pattern

type Pattern struct {
    ID            string
    Name          string
    Description   string
    Applicability string
    SuccessRate   float64
    Examples      []string
    UseCount      int
}

Retrospective

type Retrospective struct {
    ID          string
    SessionID   string
    AgentID     string
    CreatedAt   time.Time
    Completed   []string
    Failed      []FailedTask
    Strategies  []string
    Patterns    []Pattern
}

Error Types

BlockedError

err := loom.ValidateCommand("bash", "rm -rf /")
if blocked, ok := err.(*safety.BlockedError); ok {
    fmt.Printf("Blocked: %s\n", blocked.Reason)
}

ConfirmationRequiredError

if confirm, ok := err.(*safety.ConfirmationRequiredError); ok {
    fmt.Printf("Needs confirmation: %s\n", confirm.Command)
}

ConflictError

err := loom.ClaimTask(ctx, issueID, agentID, files)
if conflict, ok := err.(*coordinator.ConflictError); ok {
    fmt.Printf("Conflict on %s with %s\n", conflict.File, conflict.AgentID)
}