@agenticprimitives/home
Part of Agentic Primitives — the open-source trust substrate for agentic applications: identity that can sign, authority checked at act time, evidence the owner carries. Developer kit · All packages
Portable Agentic Trust Home contracts (spec 310): the schemas, fail-closed validators, and deterministic projections behind a personal/org trust control plane — the place an agent's owner reviews everything acting in their name.
A Home serves five surfaces: identity entry, connected apps, managed agents,
authority review, and the agentic inbox. This package defines what a Home publishes
and renders; it contains no routes, UI, branding, or deployment specifics (ADR-0021). The
reference Home app is demo-sso-next (spec 234).
Two doctrine points shape everything here:
- A Home is a facet, not the identity (ADR-0010/0011). The Smart Agent address never changes when a Home is added, rotated, or deprecated.
- A Home renders authority, never mints it. Approve/deny/issue/revoke route through
delegation/entitlements/custody packages; this package only carriesAuthorityRefpointers at their artifacts.
Surface
| Export | What it is |
|---|---|
HomeManifestV1 | Signed, portable discovery document: endpoints, surfaces, capabilities, inbox binding, validity window |
validateHomeManifest / isManifestCurrent | Fail-closed structural + currency gates; unsigned/expired/suspended ⇒ not trusted |
ManifestVerificationPort | Port for cryptographic proof verification (SA / operator-under-delegation) — wired by the consumer |
HomeInboxBindingV1 | ActivityPub-shaped inbox/outbox declaration: supported message/interaction kinds, crypto + delivery profiles |
HomeActionCardV1 + validateHomeActionCard / resolveCardAction | Declarative approval card (render half); only declared allowedActions resolve — unknown action ⇒ null ⇒ reject |
ManagedAgentEntryV1 | "Agents you manage" console row: type, relationship, control grade, status, actions |
ConnectedAppGrantV1 | Connected relying app row; grantRef REFERENCES a delegation token |
HomeControlEventV1 | Durable-audit-backed control-plane timeline row |
projectHomeInboxSummary | Pure deterministic dashboard counts over messaging + interactions projections |
Usage
import {
isManifestCurrent,
resolveCardAction,
projectHomeInboxSummary,
} from '@agenticprimitives/home';
// Trust gate before using any Home endpoint (reachable ≠ trusted):
if (!isManifestCurrent(manifest, new Date().toISOString())) throw new Error('untrusted home');
const ok = await verificationPort.verifyManifestProof(manifest); // consumer-wired crypto
// Card response handling — unknown actions are rejections, never defaults:
const action = resolveCardAction(card, submittedActionId);
if (!action) return reject('action_not_allowed');
// action.transition feeds the interactions state machine; it grants nothing.
// Dashboard badge:
const summary = projectHomeInboxSummary({ items, cases, runs });
// summary.attentionCount = pending approvals + paused runs
Boundary
Imports types, vault, messaging, interactions (types/refs only). Must not import
a2a, mcp-runtime, agent-account, Next.js, React, or anything host-specific. Status:
w1-contracts — manifest publication and the inbox/console pages land in the reference app
(spec 310 W2–W5).