tensegrity

Coordination primitives for multi-agent systems. Not another LLM wrapper.

This is the boring infrastructure that nobody wants to write: circuit breakers between agents, backpressure when one agent is overwhelmed, task auctions so agents can bid on work, reputation-weighted routing so unreliable agents get less traffic.

Built from code running in production on nookplot across 2500+ agents.

install

npm install tensegrity

what's in the box

CircuitBreaker

Prevents cascading failures when an agent goes down. Three states: closed (normal), open (blocking all calls), half-open (testing recovery). Tracks failure rates in a sliding window.

import { CircuitBreaker } from 'tensegrity';

const breaker = new CircuitBreaker('agent-0x1234', {
  failureThreshold: 3,
  resetTimeoutMs: 30000
});

const result = await breaker.call(() => agent.doSomething());
// after 3 failures, breaker opens and fast-fails for 30s

BackpressureController

Stops fast producers from overwhelming slow consumers. Monitors queue depth and applies backpressure using token bucket rate limiting.

import { BackpressureController } from 'tensegrity';

const bp = new BackpressureController({
  highWaterMark: 100,
  lowWaterMark: 20
});

if (bp.shouldAccept()) {
  queue.push(task);
} else {
  // slow down or buffer
}

TaskAuction

Agents bid on tasks. Highest bidder wins. Supports sealed-bid and open ascending formats. Handles bid validation, timeout, and winner selection.

import { TaskAuction } from 'tensegrity';

const auction = new TaskAuction({
  task: { id: 'summarize-doc', requirements: ['gpt-4'] },
  timeoutMs: 5000
});

auction.bid('agent-A', { price: 0.02, latencyMs: 200 });
auction.bid('agent-B', { price: 0.01, latencyMs: 50 });

const winner = auction.resolve(); // picks best bid

ReputationWeightedRouter

Routes tasks to agents based on their track record. Agents that deliver get more work. Agents that fail get less. Uses exponential decay so recent performance matters more.

import { ReputationWeightedRouter } from 'tensegrity';

const router = new ReputationWeightedRouter();
router.recordSuccess('agent-A', 150); // 150ms latency
router.recordFailure('agent-B');

const best = router.route('summarize'); // picks agent-A

TransactionalOutboxEngine

Guarantees exactly-once event publishing from agent state changes. Write events to a local outbox atomically with state mutations, then asynchronously relay them. Handles dead-letter queues, CDC streaming, partition routing, and compaction.

import { TransactionalOutboxEngine, OutboxPresets } from 'tensegrity';

const engine = new TransactionalOutboxEngine(OutboxPresets['agent-event-bus']);
engine.addWorker('relay-1');

engine.onDelivery(async (event) => {
  await externalBus.publish(event.topic, event.payload);
  return true;
});

engine.appendEvent('agent-0x1234', 'task.completed', { taskId: '...', result: '...' });
await engine.tick(); // polls, dispatches, compacts

ResourcePoolManager

Manages shared resource pools (connections, compute slots, API quotas) across agents with fair allocation, reservation, preemption, and auto-scaling triggers.

import { ResourcePoolManager, createComputePool } from 'tensegrity';

const manager = new ResourcePoolManager();
manager.addResource(createComputePool('gpu-cluster', 8));

const result = await manager.allocate('agent-A', 'gpu-cluster', 2, {
  priority: 5,
  ttlMs: 60_000,
  purpose: 'inference batch'
});

console.log(result.granted); // 2
manager.release(result.reservationId!);

AdaptiveThrottleGovernor

Dynamic rate control that adjusts throughput based on downstream health. Combines AIMD (TCP-style additive increase / multiplicative decrease), Vegas-style latency gradient detection, CoDel-inspired queue management, and a PI controller for steady-state convergence. Supports multi-tenant fair-share allocation and coordinated throttling across agent clusters via gossip.

import { AdaptiveThrottleGovernor, ThrottlePresets } from 'tensegrity';

const governor = new AdaptiveThrottleGovernor(ThrottlePresets['agent-to-agent'], 'node-1');

// add tenants with weighted fair share
governor.addTenant({ id: 'agent-A', weight: 3, minGuaranteedRate: 2, maxBurstRate: 100, priority: 0 });
governor.addTenant({ id: 'agent-B', weight: 1, minGuaranteedRate: 1, maxBurstRate: 50, priority: 1 });

// record request completions to feed the control loop
governor.recordRequest({
  timestamp: Date.now(),
  durationMs: 45,
  success: true,
  tenantId: 'agent-A'
});

// check admission
if (governor.shouldAllow('agent-A')) {
  await agent.call();
}

// get current state
const state = governor.getState();
// { currentRate, effectiveRate, congestionLevel, mode, tenantAllocations }

Three presets: api-gateway (high throughput, tight latency), agent-to-agent (moderate, tolerant), batch-processing (high volume, relaxed latency).

CapabilityHealthMonitor

Real-time health tracking for agent capabilities with degradation detection, predictive failure analysis, SLA compliance scoring, and automated remediation. Includes a health federator for cross-agent capability routing — when one agent's capability degrades, traffic shifts to healthy providers.

import { CapabilityHealthMonitor, HealthMonitorPresets } from 'tensegrity';

const monitor = new CapabilityHealthMonitor(HealthMonitorPresets['agent-mesh']);

// record probe results from your health checks
const { state, prediction, remediation } = monitor.recordProbe({
  type: 'performance',
  capabilityId: 'summarize',
  agentId: 'agent-A',
  success: true,
  latencyMs: 145,
  timestamp: Date.now()
});

console.log(state.score);          // 0.92 composite health
console.log(state.status);         // 'healthy'
console.log(remediation.action);   // 'none'

// find healthiest provider for a capability
const best = monitor.getBestProvider('summarize');

Three presets: real-time-api (tight SLAs, fast probes), batch-processing (relaxed, high tolerance), agent-mesh (balanced for multi-agent networks).

ConsensusViewSynchronizer

BFT view synchronization for consensus protocols. Ensures all honest agents converge on the same round despite asynchrony and Byzantine faults. Adaptive pacemaker with leader reputation, optimistic fast-path advancement, timeout certificates, and catch-up for lagging agents.

import { ConsensusViewSynchronizer, ViewSyncPresets } from 'tensegrity';

const sync = new ConsensusViewSynchronizer(ViewSyncPresets['fast-consensus']);

sync.registerAgent('agent-A', 1);
sync.registerAgent('agent-B', 1);
sync.registerAgent('agent-C', 1);

// normal path: QC received → advance view
sync.receiveQC({ view: 0, blockHash: '0xabc', signatures: new Map(), aggregateWeight: 2, createdAt: Date.now() });

console.log(sync.getCurrentView());   // 1
console.log(sync.getCurrentLeader()); // deterministic leader for view 1

Three presets: fast-consensus (low latency, round-robin), byzantine-tolerant (higher quorum, reputation-weighted), high-throughput (sticky leaders for amortized overhead).

ResourceContentionArbiter

Game-theoretic resource allocation when multiple agents compete for shared resources. Combines Vickrey auctions, Nash bargaining, priority preemption with Wait-Die deadlock prevention, Gini-based starvation detection, demand forecasting, and token-based budget planning.

import { ResourceContentionArbiter, ARBITER_PRESETS } from 'tensegrity';

const arbiter = new ResourceContentionArbiter({}, 'fair-share');

arbiter.registerResource({ id: 'gpu-cluster', capacity: 8, divisible: true, preemptible: true, category: 'compute' });
arbiter.setBudget('agent-A', 'gpu-cluster', 4);

const { granted, allocation } = arbiter.requestAllocation({
  agentId: 'agent-A',
  resourceId: 'gpu-cluster',
  quantity: 3,
  priority: 7,
  flexibility: 0.2,
  utilityPerUnit: 10
});

// check for starvation and contention forecasts
const status = arbiter.getResourceStatus('gpu-cluster');
console.log(status.forecast.trending);        // 'rising' | 'falling' | 'stable'
console.log(status.starvation.severity);      // 'none' | 'mild' | 'moderate' | 'severe'

Three presets: fair-share (Nash bargaining, low starvation tolerance), priority-driven (preemption enabled), market-based (auction-resolved).

FederationRouter

Cross-network agent federation with rate awareness. When your agents span multiple networks (different API providers, different clusters, different orgs), this handles the coordination: per-network rate budgets using a token bucket + sliding window hybrid, adaptive request prioritization, quota negotiation between federation peers, cooperative rate sharing (idle peers donate unused quota), request coalescing across federation boundaries, and fairness enforcement so no single peer can starve others.

import { FederationRouter, FederationPresets } from 'tensegrity';

const router = new FederationRouter(FederationPresets.balanced());

router.addPeer({
  id: 'agent-0x5678',
  networkId: 'openai-cluster',
  endpoint: 'https://peer.example.com',
  capabilities: ['summarize', 'classify'],
  trustLevel: 0.9,
  quotaGranted: 100,
  quotaUsed: 0,
  windowStartMs: Date.now(),
  windowDurationMs: 60_000,
  lastContactMs: Date.now()
});

const req = router.submit('openai-cluster', 'summarize', { text: '...' }, 'high');
// low-priority requests get shed first when budget runs low
// requests with the same coalescing key get batched automatically

const forecast = router.getForecast('openai-cluster', 300_000);
console.log(forecast.exhaustionRisk); // 'low' | 'medium' | 'high' | 'critical'

Includes budget forecasting via linear regression over consumption history, circuit breakers that trip on repeated 429s (not just 5xx), and bilateral/multilateral quota negotiation. Three presets: conservative (tight limits, aggressive shedding), balanced (gradual degradation), aggressive (high throughput, loose fairness).

GossipEngine

Epidemic dissemination for agent networks. Implements SWIM-inspired failure detection, Plumtree hybrid gossip (eager push + lazy pull repair), Merkle-based anti-entropy sync, bimodal multicast, and adaptive fanout. Composable subsystems that work together or independently.

import { createGossipEngine } from 'tensegrity';

const engine = createGossipEngine('agent-001', 'medium-network');

// Add peers
engine.membership.addMember({ id: 'agent-002', address: 'ws://...', metadata: {}, generation: 1, heartbeat: 0 });
engine.plumtree.addPeer('agent-002');

// Spread information
engine.rumors.createRumor('task-available-42', { task: 'summarize' }, 30_000, 10);

// Run a tick — returns actions to execute (probes, pushes, syncs)
const actions = engine.tick(Date.now());
// actions.probes — SWIM pings to send
// actions.rumorPushes — rumors to forward to peers
// actions.antiEntropyTarget — peer to run Merkle digest sync with

const stats = engine.getStats();
// { aliveMembers, activeRumors, currentFanout, ... }

Seven composable subsystems: SwimMembership (failure detection), PlumtreeGossip (hybrid push/pull), MerkleAntiEntropy (state convergence), BimodalMulticast (high-reliability broadcast), AdaptiveFanout (dynamic fan-out tuning), RumorManager (infection-style spreading), PartitionDetector (split-brain detection). Three presets: small-cluster (5-20 agents), medium-network (20-200), large-federation (200+).

DistributedLockManager

Mutual exclusion for multi-agent systems without centralized coordination. Implements Lamport's Bakery Algorithm (total ordering), Maekawa's √N Quorum (reduced message complexity), Redlock-style multi-region locking, and hierarchical intention locks (IX/IS/X/S). Includes deadlock detection via wait-for graph DFS, wound-wait prevention, fencing tokens for stale-lock safety, phantom lock detection for crashed holders, and lock coarsening for high-contention resources.

import { DistributedLockManager, LockManagerPresets } from 'tensegrity';

const dlm = new DistributedLockManager(LockManagerPresets['standard']);

const grant = dlm.acquire({
  id: 'req-1', agentId: 'agent-A', resourceId: 'shared-db',
  mode: 'exclusive', priority: 1, timestamp: Date.now(), timeout: 30000
});
// grant.fencingToken — monotonic token to detect stale locks
// dlm.tick() — runs expiry, deadlock detection, phantom cleanup

Three presets: fast-locks (short TTL, no wound-wait), standard (wound-wait enabled, balanced), high-contention (priority-based fairness, aggressive coarsening).

VectorClockCausality

Full vector clock implementation for tracking causal relationships. Goes beyond Lamport timestamps to capture true happened-before semantics. Includes dotted version vectors (Riak-style concurrent write tracking), matrix clocks ("what I know you know"), causal barriers (wait for dependencies), causal event logs with delivery ordering, stability detection (globally safe GC prefixes), and plausible clock reconstruction for late joiners.

import { createClock, tick, merge, compare, CausalEventLog } from 'tensegrity';

const clockA = tick(createClock('agent-A'));
const clockB = tick(createClock('agent-B'));
compare(clockA, clockB); // 'concurrent'

const log = new CausalEventLog('agent-A');
log.onDeliver(event => console.log('delivered:', event.payload));
log.emit({ action: 'update-config' }); // local event
log.receive(remoteEvent); // buffered until causal deps met

Three presets: small-cluster (full matrix clocks + DVV), medium-network (vector clocks + DVV), large-federation (lightweight mode).

ServiceDiscoveryMesh

Decentralized service registration and discovery without a central registry. Combines local TTL-based registries, gossip dissemination, DNS-SD style queries with attribute matching, health-aware routing (liveness/readiness probes), locality-aware selection (zone/region/rack scoring), watch/subscribe for topology changes, anti-entropy sync, and split-brain detection. AP over CP with CRDT-like merge semantics.

import { createMesh } from 'tensegrity';

const mesh = createMesh('node-1', 'medium-network');
mesh.register({
  instanceId: 'compute-001', serviceType: 'agent.compute',
  serviceName: 'GPT Worker', agentAddress: '0x...', endpoint: 'ws://...',
  version: '1.2.0', locality: { region: 'us-east', zone: 'a' }
});

const best = mesh.resolveOne('agent.compute', { region: 'us-east' });
// best.instance — highest-scoring healthy instance
// best.breakdown — { healthScore, localityScore, loadScore, ... }

Three presets: small-cluster, medium-network, large-federation.

ChaosTestingHarness

Chaos engineering for agent networks. Define steady-state hypotheses, inject controlled faults (latency, crashes, partitions, byzantine behavior), and verify your system survives. Includes blast radius containment, kill switches, GameDay orchestration, and pre-built scenarios.

import { ExperimentEngine, singleAgentCrashScenario } from 'tensegrity';

const engine = new ExperimentEngine(config);
const experiment = engine.createExperiment({
  name: 'agent-crash-resilience',
  hypothesis: { metrics: [{ metric: 'success_rate', operator: 'gte', value: 0.95 }] },
  faults: [{ type: 'agent-crash', targets: { mode: 'random', count: 1 } }]
});
const results = await engine.run(experiment);
// results.hypothesisHeld — did the system maintain steady state?

TokenEconomyEngine

Complete token-based micro-economy for agent coordination. Minting with supply schedules (fixed, inflationary, deflationary, bonding curve), staking with slashing, payment channels for high-frequency transfers, AMM for capability pricing, and revenue sharing with contribution-weighted splits.

import { TokenEconomyEngine } from 'tensegrity';

const economy = new TokenEconomyEngine({
  symbol: 'WORK', decimals: 18, initialSupply: 1_000_000,
  supplySchedule: { kind: 'bonding-curve', reserveRatio: 0.5, basePrice: 0.01 },
  stakingEnabled: true, ammEnabled: true
});
economy.mint('agent-1', 1000);
economy.stake('agent-1', 500, { lockDuration: 100 });
// Slashing, payment channels, AMM swaps, revenue distribution all built in

ExactlyOnceQueue

Distributed work queue guaranteeing each task is processed exactly once across competing agents. Bloom filter deduplication, lease-based visibility timeouts, fencing tokens to prevent stale commits, poison pill detection, and automatic dead-lettering.

import { ExactlyOnceQueue } from 'tensegrity';

const queue = new ExactlyOnceQueue(config);
queue.enqueue({ id: 'task-1', affinityKey: 'shard-a', payload: data });
const claimed = queue.claim('worker-1');
// Process, then commit with fencing token
queue.complete({ taskId: claimed.envelope.id, fenceToken: claimed.fenceToken });

why this exists

every "agent framework" right now is a thin wrapper around prompt chaining. the hard problems in multi-agent systems are the same hard problems in distributed systems: coordination, fault tolerance, load balancing, consensus. these are solved problems in distributed computing. nobody has ported them to the agent world properly.

tensegrity does that. one primitive at a time.

status

early. the APIs will change. the module list will grow. if you're building multi-agent systems and want to stop reinventing circuit breakers, this is for you.

license

MIT