@agenticprimitives/orchestration

The Ring-0 agentic orchestration core: the intent → plan → execute → observe loop, the Planner and ToolInvoker ports, and a deterministic rule-based planner. A first-party app expresses a goal; this package plans which tools compose to satisfy it and runs them through an injected invoker — the web never names a tool (ADR-0044). Pure leaf: no transport, no LLM SDK, no chain. The concrete LLM binding lives behind the Planner port in @agenticprimitives/orchestration-anthropic.

Install

pnpm add @agenticprimitives/orchestration

Quick start

import { runIntent, createRuleBasedPlanner, type ToolSpec } from '@agenticprimitives/orchestration';

const tools: ToolSpec[] = [
  { id: 'get_vault_record', description: 'Read one of the principal’s vault records by recordType.' },
  { id: 'get_pii', description: 'Read the principal’s PII (high sensitivity).' },
];

// Deterministic default planner — goal → tool. No model, no creds.
const planner = createRuleBasedPlanner([
  { match: /profile/, toolId: 'get_vault_record', args: { recordType: 'impact-profile' } },
  { match: /pii|personal/, toolId: 'get_pii' },
]);

const result = await runIntent(
  { goal: 'read my profile' },
  {
    planner,
    tools,
    // The invoker is where authority lives — the a2a skill binds this to the task's delegation.
    invoke: async (toolId, args) => myMcpCall(toolId, args),
  },
);

if (result.outcome === 'completed') console.log(result.result);

Concepts

• Intent — a declarative goal ({ goal, constraints?, context? }), never a tool name or call sequence.
• Planner — the injected port that turns a goal + the exposed ToolSpec[] into a Plan. Swap the deterministic createRuleBasedPlanner for the LLM adapter without touching the loop.
• ToolInvoker — the injected port that executes one step. The orchestration core never holds a token, key, or chain client; the invoker carries the on-chain authority (delegation).
• runIntent — the loop: plan → execute (with { $ref } result threading) → observe → bounded re-plan on failure. Fail-closed: every error path returns a failed RunResult.

Boundaries

Pure leaf. Forbidden imports: a2a, mcp-runtime, mcp-protocol, delegation, service-agent, and any LLM SDK. See spec.md + capability.manifest.json.

License

MIT