@agenticprimitives/home

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 carries AuthorityRef pointers 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).