Agent Health & Shutdown

Production agents need graceful shutdown — draining in-flight submissions before stopping — and health endpoints for load balancers and Kubernetes probes. txfence builds both into the agent interface.

health()

Returns a snapshot of agent state:


const health = agent.health()
 
console.log(health.status)    // 'healthy' | 'shutting_down'
console.log(health.inFlight)  // number of submissions currently in progress
console.log(health.uptime)    // ms since agent creation

Suitable for Kubernetes liveness probes:


app.get('/healthz', (req, res) => {
  const health = agent.health()
  if (health.status === 'healthy') {
    res.json(health)
  } else {
    res.status(503).json(health)
  }
})

shutdown()

Sets the shutting-down flag immediately, then polls every 50ms until in-flight submissions complete or the timeout expires:


const result = await agent.shutdown(30_000)  // 30 second timeout
 
console.log(result.completed)        // submissions that finished cleanly
console.log(result.abandoned)        // submissions that exceeded timeout
console.log(result.capLocksReleased) // number of cap locks released by shutdown

submit() throws when called after shutdown() — no new submissions accepted during drain.

AgentShutdownResult


type AgentShutdownResult = {
  completed:        number
  abandoned:        number
  capLocksReleased: number
}

Submissions that exceed the timeout are counted as abandoned. They may or may not have executed on-chain — check the monitor for unrecorded transactions.

capLocksReleased reports how many cap locks were released by shutdown. The pipeline holds lock IDs internally and does not expose them at the agent level — in v1 this counter is best-effort and may be 0 even when locks remain. Restart the cap lock provider, or wait for the rolling window, to clear any stragglers.

isShuttingDown()


if (agent.isShuttingDown()) {
  console.log('Agent is draining — no new submissions accepted')
}

Cap lock inspection on shutdown

Pass capLockConfigs to createAgent to enable cap lock inspection during shutdown:


const agent = createAgent(
  config, adapters, rpcUrls, executor,
  capLockProvider,    // 5:  capLockProvider
  undefined,          // 6:  metadataVerifier
  approvalProvider,   // 7:  approvalProvider
  receiptStore,       // 8:  receiptStore
  undefined,          // 9:  auditLog
  undefined,          // 10: telemetryProvider
  capLockConfigs,     // 11: capLockConfigs — required for inspection on shutdown
)

shutdown() inspects cap locks via capLockProvider.inspect() and logs a warning if active locks remain after drain. Individual lock release requires lock IDs held inside the pipeline — documented as a known limitation.

SIGTERM handling


process.on('SIGTERM', async () => {
  console.log('SIGTERM received — draining agent')
  const result = await agent.shutdown(30_000)
  console.log(`Shutdown complete: ${result.completed} completed, ${result.abandoned} abandoned`)
  process.exit(0)
})