@agenticprimitives/service-agent

Status: experimental (spec 283 PR1).

A generic framework for building service agents — agents that expose a catalog of capabilities (skills) and execute them under layered authority. It is provider-neutral and Ring-0 pure: it depends only on @agenticprimitives/types and imports no wallet, exchange, RPC, MCP, delegation, or policy code. The concrete providers and authority evaluators are injected by the host.

Domain catalogs — e.g. @agenticprimitives/treasury — are separate packages that supply skill definitions

• a provider-neutral plan; this package runs the lifecycle.

The lifecycle

define  →  assert  →  entitle / delegate  →  primitive-plan  →  execute  →  receipt

• define — a SkillDefinition states a skill's meaning: id, version, effect (read|sign|spend|trade|admin), default exposure, the logical capabilities it requires, optional I/O schemas, and a compile() that emits a primitive plan. A definition does NOT claim the host can run it.
• assert — assertSkills resolves each definition's requires against the PrimitiveRegistry. A skill asserts only when every non-optional requirement binds to an installed Primitive whose constraints cover the requirement (monotonic). The result is an AssertionReport (asserted / unavailable / rejected). The optional publishAssertion hook is the seam for public disclosure (spec 282: vault claim → atl:skills → discovery + A2A card).
• entitle / delegate / guard — the plan's .authorize('entitlement', …), .authorize('delegation', …) and .guard(…) steps call the injected evaluators (mapping to tool-policy/entitlements, delegation, and tool-policy at the host). Every gate must ALLOW; the first denial throws the typed error and nothing further runs (fail-closed).
• primitive-plan / execute — runPlan resolves ref()s, calls registered primitives for .steps (plus built-in ledger.reserve/ledger.finalize), and collects .output.
• receipt — invoke returns a normalized ExecutionReceipt (authority decisions + primitive bindings
  • outputs); the host sinks/signs it via audit.

Example

import { ServiceAgent, defineSkill, createPrimitiveRegistry, primitivePlan, ref } from '@agenticprimitives/service-agent';

const balance = defineSkill<{ accountId: string }, { balance: string }>({
  id: 'treasury.account.balance', version: '1.0.0', name: 'Read balance',
  effect: 'read', defaultExposure: 'authenticated',
  requires: [{ capability: 'account.balance' }],
  compile: ({ input }) =>
    primitivePlan('plan.balance')
      .step('bal', 'account.balance', { accountId: input.accountId })
      .output({ balance: ref('bal', 'balance') }),
});

const registry = createPrimitiveRegistry();
registry.register(myAccountProvider); // advertises { id: 'account.balance', version, constraints }

const agent = new ServiceAgent({ descriptor: { id: '0x…', name: 'Treasury', version: '1.0.0' }, primitives: registry });
agent.define(balance);
await agent.assert();
const receipt = await agent.invoke({ skillId: 'treasury.account.balance', input: { accountId: 'acct-1' } });

For a spend skill, add .authorize('entitlement', …), .authorize('delegation', …), .guard(…), and the ledger reserve/finalize steps; wire entitlements / delegations / policies / ledger into ServiceAgentOptions. See test/conformance.test.ts for the full lifecycle with fakes.

What lives elsewhere

• Providers (EVM transfer, swap venue, RPC, KMS signer) — EXTERNAL (ADR-0037); they register as Primitives. Demos ship fakes.
• Authority logic — delegation, tool-policy, entitlements; injected as evaluators.
• The treasury catalog — @agenticprimitives/treasury. Public disclosure — the app, via publishAssertion (spec 282).