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(", ")}`)
console.log(`Direct group context: ${task.groupContext ?? "(none)"}`)
console.log(`Effective group context: ${task.effectiveGroupContext ?? "(none)"}`)

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

await tx.tasks.setGroupContext("tx-root001", "Shared auth rollout context")

await tx.tasks.clearGroupContext("tx-root001")

// 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

const recent = await tx.runs.list({
  limit: 20,
  status: ["failed", "running"],
})

const detail = await tx.runs.get("run-abc12345")
console.log(detail.run.status)
console.log(detail.messages.length)

const messages = await tx.runs.transcript("run-abc12345")
const toolCalls = messages.filter((message) => message.type === "tool_use")

const stderr = await tx.runs.stderr("run-abc12345", { tail: 50 })
console.log(stderr.content)

const errors = await tx.runs.errors({ hours: 24, limit: 10 })

await tx.runs.heartbeat("run-abc12345", {
  transcriptBytes: 2048,
  deltaBytes: 256,
})

const stalled = await tx.runs.stalled({
  transcriptIdleSeconds: 300,
  heartbeatLagSeconds: 180,
})

const reaped = await tx.runs.reap({
  transcriptIdleSeconds: 300,
  dryRun: false,
})

const discover = await tx.spec.discover({
  doc: "PRD-033-spec-test-traceability",
})

await tx.spec.link(
  "INV-EARS-FL-001",
  "test/integration/flow.test.ts",
  "flow stays unblocked",
  "vitest"
)

const status = await tx.spec.status({
  doc: "PRD-033-spec-test-traceability",
})

const matrix = await tx.spec.matrix({
  doc: "PRD-033-spec-test-traceability",
})

await tx.spec.run(
  "test/integration/flow.test.ts::flow stays unblocked",
  true,
  { durationMs: 42 }
)

await tx.spec.batch({
  from: "junit",
  raw: "<testsuites>...</testsuites>",
})

await tx.spec.complete({
  doc: "PRD-033-spec-test-traceability",
  signedOffBy: "james",
})

// 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}`)
}

await tx.guards.set({
  maxPending: 50,
  maxChildren: 10,
  maxDepth: 4,
  enforce: true,
})

const guards = await tx.guards.show()
for (const g of guards) {
  console.log(`${g.scope}: maxPending=${g.maxPending}, enforce=${g.enforce}`)
}

const result = await tx.guards.check({ parentId: 'tx-abc123' })
if (!result.passed) {
  console.log('Warnings:', result.warnings)
}

await tx.guards.clear()               // clear all
await tx.guards.clear('global')       // clear global only
await tx.guards.clear('parent:tx-abc123')  // clear specific parent scope

await tx.verify.set('tx-abc123', 'bun run test:auth')

// With structured output schema
await tx.verify.set('tx-abc123', 'bun run test:json', 'verify-schema.json')

const info = await tx.verify.show('tx-abc123')
// { cmd: 'bun run test:auth', schema: null }

const result = await tx.verify.run('tx-abc123')
// { taskId: 'tx-abc123', exitCode: 0, passed: true, stdout: '...', stderr: '', durationMs: 1234 }

// With timeout
const result = await tx.verify.run('tx-abc123', { timeout: 60 })

await tx.verify.clear('tx-abc123')

// Data tier (no LLM, instant)
const result = await tx.reflect.run({ sessions: 5 })
console.log(result.throughput)    // { created: 20, completed: 8, net: 12, completionRate: 0.4 }
console.log(result.signals)       // [{ type: 'HIGH_PROLIFERATION', ... }]
console.log(result.stuckTasks)    // [{ id: 'tx-abc123', title: '...', attempts: 4 }]

// Enable analysis when an LLM backend is available
const analyzed = await tx.reflect.run({ sessions: 5, analyze: true })
console.log(analyzed.analysis)    // "Proliferation driven by..."

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()