@aroha-sdk/orchestrator

Saga engine for multi-agent workflows — orchestrates the mandate delegation chain across distributed agent calls.

Install

npm install @aroha-sdk/orchestrator

Quick example

import { SagaEngine } from "@aroha-sdk/orchestrator";
import { issueIntentMandate, attenuateToPayment } from "@aroha-sdk/credentials";

const saga = new SagaEngine({ did: orchestratorDID, privateKey: orchestratorPrivateKey });

// Issue the root mandate and run the saga
const { mandate: rootMandate } = await issueIntentMandate(
  humanDID, orchestratorDID,
  { spendLimitUsd: 500, allowedActions: ["book-flights", "book-hotels"] },
  humanPrivateKey, 3_600_000,
);

const result = await saga.run([
  {
    agentUrl: "http://flight-agent/v1/run",
    // Attenuate scope before each step
    mandate: await attenuateToPayment(rootMandate, flightAgentDID, { spendLimitUsd: 300 }, orchestratorPrivateKey),
    message: "Book a flight from AKL to NRT on 2026-08-01",
    compensate: async () => saga.cancel("flight-agent"),
  },
  {
    agentUrl: "http://hotel-agent/v1/run",
    mandate: await attenuateToPayment(rootMandate, hotelAgentDID, { spendLimitUsd: 200 }, orchestratorPrivateKey),
    message: "Book a hotel in Tokyo for 5 nights",
    compensate: async () => saga.cancel("hotel-agent"),
  },
]);
// If any step fails, compensations run in reverse order

Why this exists in the mandate chain

The orchestrator is where scope attenuation happens in practice. At each step in the saga, the orchestrator holds its own mandate and issues a narrower one to each sub-agent — so a hotel booking agent can never spend flight budget, and no agent can exceed what the human originally authorized.

API

• SagaEngine — manages a sequence of agent calls with attenuation, rollback, and compensation.
  • saga.run(steps) — execute steps in order, running compensations on failure.
  • saga.cancel(agentId) — trigger a compensation call to the named agent.
• selectAgent(capability, registry) — discover an agent by capability from the registry.
• fanOut(steps) — execute saga steps in parallel and await all results.

License

MIT