Agent SDK

npm install @jamesaphoenix/tx-agent-sdk

# pnpm
pnpm add @jamesaphoenix/tx-agent-sdk

# yarn
yarn add @jamesaphoenix/tx-agent-sdk

# bun
bun add @jamesaphoenix/tx-agent-sdk

import { TxClient } from "@jamesaphoenix/tx-agent-sdk"

// HTTP mode (connects to tx API server)
const tx = new TxClient({ apiUrl: "http://localhost:3456" })

// Get the next ready task
const ready = await tx.tasks.ready({ limit: 1 })
if (ready.length === 0) {
  console.log("No tasks ready")
  process.exit(0)
}

const task = ready[0]
console.log(`Working on: ${task.title}`)

// Get context (relevant learnings for this task)
const ctx = await tx.context.forTask(task.id)
for (const l of ctx.learnings) {
  console.log(`- ${l.content}`)
}

// ... do the work ...

// Mark complete and see what was unblocked
const { nowReady } = await tx.tasks.done(task.id)
console.log(`Unblocked ${nowReady.length} tasks`)

// Record what you learned
await tx.learnings.add({
  content: "Use retry logic for flaky network calls",
  category: "best-practices",
})

// HTTP mode
const tx = new TxClient({ apiUrl: "http://localhost:3456" })

// Direct SQLite mode (no server needed)
const tx = new TxClient({ dbPath: ".tx/tasks.db" })

// With authentication
const tx = new TxClient({
  apiUrl: "http://localhost:3456",
  apiKey: process.env.TX_API_KEY,
  timeout: 60000, // 60 second timeout
})

const task = await tx.tasks.get("tx-abc123")
console.log(task.title, task.isReady)
console.log(`Blocked by: ${task.blockedBy.join(", ")}`)
console.log(`Blocks: ${task.blocks.join(", ")}`)

await tx.tasks.update("tx-abc123", {
  status: "active",
  score: 200,
})

// Delete a single task
await tx.tasks.delete("tx-abc123")

// Delete task and all descendants
await tx.tasks.delete("tx-abc123", { cascade: true })

// List all tasks
const all = await tx.tasks.list()

// Filter by status
const active = await tx.tasks.list({ status: "active" })

// Multiple statuses
const working = await tx.tasks.list({ status: ["active", "planning"] })

// Full-text search
const results = await tx.tasks.list({ search: "auth" })

// Paginate
const page1 = await tx.tasks.list({ limit: 10 })
if (page1.hasMore) {
  const page2 = await tx.tasks.list({ limit: 10, cursor: page1.nextCursor! })
}

// "deploy" can't start until "build" is done
await tx.tasks.block("tx-deploy", "tx-build")

await tx.tasks.unblock("tx-deploy", "tx-build")

const tree = await tx.tasks.tree("tx-root")
console.log(`${tree.length} tasks in tree`)

const learning = await tx.learnings.get(42)
console.log(learning.content)

await tx.learnings.helpful(42)
await tx.learnings.helpful(42, 0.8) // partial helpfulness

// List all
const all = await tx.fileLearnings.list()

// Filter by path
const forFile = await tx.fileLearnings.list("src/auth.ts")

const notes = await tx.fileLearnings.recall("src/auth.ts")
for (const note of notes) {
  console.log(`${note.filePattern}: ${note.note}`)
}

await tx.fileLearnings.add({
  filePattern: "src/auth.ts",
  note: "JWT tokens expire after 1 hour, refresh logic is in middleware",
  taskId: "tx-abc123",
})

await tx.messages.send({
  channel: "worker-1",
  content: "Task tx-abc123 is ready for review",
  sender: "orchestrator",
  ttlSeconds: 3600,
  correlationId: "req-001",
})

const msgs = await tx.messages.inbox("agent-1", { limit: 10 })
const fromOrch = await tx.messages.inbox("agent-1", { sender: "orchestrator" })

await tx.messages.ack(42)

const { ackedCount } = await tx.messages.ackAll("agent-1")

const count = await tx.messages.pending("agent-1")

const { expired, acked } = await tx.messages.gc({ ackedOlderThanHours: 24 })

const claim = await tx.claims.claim("tx-abc123", "worker-1", 30)
console.log(`Lease expires at ${claim.leaseExpiresAt}`)

await tx.claims.release("tx-abc123", "worker-1")

const renewed = await tx.claims.renew("tx-abc123", "worker-1")
console.log(`New expiry: ${renewed.leaseExpiresAt}`)

const claim = await tx.claims.getActive("tx-abc123")
if (claim) {
  console.log(`Claimed by ${claim.workerId}`)
}

import { TxError } from "@jamesaphoenix/tx-agent-sdk"

try {
  await tx.tasks.get("tx-nonexistent")
} catch (err) {
  if (err instanceof TxError) {
    if (err.isNotFound()) {
      console.log("Task not found")
    } else if (err.isValidation()) {
      console.log("Validation error:", err.message)
    } else if (err.isCircularDependency()) {
      console.log("Circular dependency detected")
    }
    console.log("Error code:", err.code)
    console.log("HTTP status:", err.statusCode)
  }
}

import { withRetry } from "@jamesaphoenix/tx-agent-sdk"

const task = await withRetry(() => tx.tasks.get("tx-abc123"), {
  maxAttempts: 3,
  initialDelayMs: 100,
  maxDelayMs: 5000,
  backoffMultiplier: 2,
})

import {
  filterByStatus,
  filterReady,
  sortByScore,
  getNextTask,
  isValidTaskId,
  isValidTaskStatus,
  parseDate,
  wasCompletedRecently,
} from "@jamesaphoenix/tx-agent-sdk"

// Get the highest-priority ready task from a list
const tasks = (await tx.tasks.list({ limit: 100 })).items
const next = getNextTask(tasks)

// Validate IDs
isValidTaskId("tx-abc123") // true
isValidTaskStatus("active") // true

// Filter tasks client-side
const active = filterByStatus(tasks, "active")
const ready = filterReady(tasks)
const sorted = sortByScore(tasks)

// Date helpers
const recentlyDone = tasks.filter((t) => wasCompletedRecently(t, 24))

const tx = new TxClient({ dbPath: ".tx/tasks.db" })
try {
  await tx.tasks.ready()
} finally {
  await tx.dispose()
}

import { TxClient } from "@jamesaphoenix/tx-agent-sdk"

const tx = new TxClient({ apiUrl: "http://localhost:3456" })

async function agentLoop() {
  while (true) {
    // Get next task
    const ready = await tx.tasks.ready({ limit: 1 })
    if (ready.length === 0) break

    const task = ready[0]
    console.log(`Starting: ${task.title}`)

    // Get relevant context
    const ctx = await tx.context.forTask(task.id)
    const contextStr = ctx.learnings
      .map((l) => `- ${l.content}`)
      .join("\n")

    // ... pass task + context to your LLM ...

    // Record what was learned
    await tx.learnings.add({
      content: "Discovered pattern X works for problem Y",
      sourceRef: task.id,
    })

    // Complete the task
    const { nowReady } = await tx.tasks.done(task.id)
    console.log(`Done. ${nowReady.length} tasks unblocked.`)
  }

  console.log("All tasks complete!")
}

agentLoop()