@agenticprimitives/types 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Trust Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @agenticprimitives/types
+
+Cross-cutting branded types and chain primitives shared across `@agenticprimitives/*` packages. Types-only; no runtime code.
+
+## Install
+
+```bash
+pnpm add @agenticprimitives/types
+```
+
+## Exports
+
+```ts
+import type { Address, Hex, ChainId, BrandedId } from '@agenticprimitives/types';
+
+type SessionId = BrandedId<'SessionId'>;
+const chain: ChainId = 1 as ChainId;
+const account: Address = '0x...';
+```
+
+## Status
+
+Pre-alpha. Minimal by design. Adding a type here requires ≥2 consuming packages.

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+export type Address = `0x${string}`;
+export type Hex = `0x${string}`;
+export type ChainId = number & {
+    readonly __chainId: unique symbol;
+};
+export type BrandedId<T extends string> = string & {
+    readonly __brand: T;
+};
+/**
+ * The canonical identity of every agent IS its ERC-4337 Smart Agent
+ * address ([ADR-0010](../../docs/architecture/decisions/0010-smart-agent-canonical-identifier.md)).
+ * This alias names that role: a value typed `CanonicalAgentIdentity` is
+ * THE identity — never a name, profile, EOA, or passkey (those are
+ * facets that point AT it and rotate without changing it; see ADR-0011).
+ * It is a plain `Address`, so it composes with every viem/`Address` API
+ * without a cast — the name is the contract, the brand is doctrinal.
+ */
+export type CanonicalAgentIdentity = Address;
+/**
+ * Branded CAIP-10 account identifier — `<namespace>:<reference>:<address>`
+ * (e.g. `eip155:8453:0x…`, `hedera:mainnet:0.0.x`). Constructed only via
+ * `buildCaip10Address` (runtime helper in `@agenticprimitives/agent-profile`)
+ * so callers can't bypass the namespace allowlist (ADR-0008).
+ */
+export type Caip10Address = string & {
+    readonly __brand: 'caip10';
+};
+/**
+ * Semantic alias of {@link Caip10Address} for the SSO-subject / directory-key
+ * role ([ADR-0016](../../docs/architecture/decisions/0016-canonical-agent-id-is-the-sso-subject.md)).
+ * One brand, one builder. Cross-chain by construction. Distinct from
+ * {@link CanonicalAgentIdentity} — that is the within-chain EVM `Address`
+ * handle; THIS is the chain-qualified portable identifier.
+ */
+export type CanonicalAgentId = Caip10Address;
+/** The three CAIP-10 parts; input to `agent-profile`'s `buildCaip10Address`. */
+export interface Caip10Parts {
+    namespace: string;
+    reference: string;
+    address: string;
+}
+/** Assurance ladder, ordered low→high. Threads into SSO step-up (ADR-0017). */
+export type Assurance = 'unverified' | 'asserted' | 'onchain-read' | 'onchain-confirmed';
+/** Credential facet kinds that can authenticate a session. */
+export type CredentialKind = 'passkey' | 'siwe-eoa' | 'hardware' | 'oidc';
+/** What a credential is trusted for. login-grade ≠ custody-grade (ADR-0017). */
+export type CredentialRole = 'login-grade' | 'custody-grade';
+/** The credential that authenticated a session — a facet key, NOT the identity. */
+export interface CredentialPrincipal {
+    kind: CredentialKind;
+    /** credentialId / EOA address / "iss#sub" — a facet key, not the identity. */
+    id: string;
+    assurance: Assurance;
+    /** Optional: whether this credential is custody-grade (step-up) or login-grade. */
+    role?: CredentialRole;
+}
+/**
+ * The cross-origin SSO token a relying site receives from the Connect
+ * broker (spec 224 §3). `sub` is the canonical subject; there is NO
+ * `owner` field (ADR-0016). `BrokerSession` (the broker's own same-origin
+ * session) is a different, connect-internal shape.
+ */
+export interface AgentSession {
+    /** Canonical subject (CAIP-10). NEVER a name, NEVER a bare Address. */
+    sub: CanonicalAgentId;
+    /** The credential that authenticated this session. */
+    principal: CredentialPrincipal;
+    /** Effective assurance of the session (≤ `principal.assurance`). */
+    assurance: Assurance;
+    /** Relying-site `client_id` this token is bound to (exact-match). */
+    aud: string;
+    /** The Connect origin that issued it. */
+    iss: string;
+    /** Issued-at (epoch seconds). */
+    iat: number;
+    /** Expiry (epoch seconds). Short-lived. */
+    exp: number;
+    /** Replay id. */
+    jti: string;
+    /**
+     * Optional per-subject derivation rotation (Google custody; spec 235 §5b). Bumping it derives a
+     * fresh per-subject custodian → a fresh agent ("a new home from the same Google account"). The
+     * broker mints it; the custody gate reads it to derive the matching key. Absent / 0 for every
+     * non-rotated session. NOT an authority field — purely a derivation input.
+     */
+    rotation?: number;
+}
+/**
+ * Discriminator for the KIND of Smart Agent a name points to.
+ *
+ * Three kinds only. `treasury` is NOT an agent kind — it is a kind of SERVICE
+ * (`agentKind: 'service'` + a profile `serviceType` / `ProfileType: 'treasury'`
+ * subtype; specs 217/225 §6). Do not re-add it here.
+ */
+export type AgentType = 'person' | 'org' | 'service';
+/**
+ * Optional naming context other packages accept as injected
+ * parameter. Apps that don't use naming pass nothing; apps that do
+ * resolve names via @agenticprimitives/agent-naming and populate
+ * this shape before invoking downstream packages.
+ *
+ * Invariants every consumer MUST respect:
+ *   - `agentName` is a DISPLAY field. Policy decisions / signature
+ *     bindings MUST be derivable from address; name can never be
+ *     the sole authority.
+ *   - Missing fields are not a security failure — name is optional.
+ *   - Consumers MUST NOT treat name as a stable identifier across
+ *     transfers. The address is the stable identifier.
+ */
+export interface NameContext {
+    /** Resolved name of the subject (e.g. 'alice.agent'). */
+    agentName?: string;
+    /** Discriminator for branching: person vs org vs service (treasury ⊂ service — not branched here). */
+    agentType?: AgentType;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,GAAG,KAAK,MAAM,EAAE,CAAC;AACpC,MAAM,MAAM,GAAG,GAAG,KAAK,MAAM,EAAE,CAAC;AAChC,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AACrE,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,MAAM,IAAI,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAQ7C;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAE7C,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AASD,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,UAAU,GAAG,cAAc,GAAG,mBAAmB,CAAC;AAEzF,8DAA8D;AAC9D,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAE1E,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,eAAe,CAAC;AAE7D,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,cAAc,CAAC;IACrB,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,SAAS,CAAC;IACrB,mFAAmF;IACnF,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,GAAG,EAAE,gBAAgB,CAAC;IACtB,sDAAsD;IACtD,SAAS,EAAE,mBAAmB,CAAC;IAC/B,oEAAoE;IACpE,SAAS,EAAE,SAAS,CAAC;IACrB,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAYD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sGAAsG;IACtG,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB"}

package/dist/index.js

@@ -0,0 +1,3 @@
+// @agenticprimitives/types — cross-cutting branded primitives. Types-only.
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@agenticprimitives/types",
+  "version": "0.1.0-alpha.2",
+  "description": "Cross-cutting branded types and chain primitives shared across @agenticprimitives/* packages.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "spec.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "echo 'no tests yet' && exit 0",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "types",
+    "agentic"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/spec.md

@@ -0,0 +1,5 @@
+# @agenticprimitives/types — spec
+
+This package is intentionally minimal; its rationale lives in [`../../specs/101-v0-package-proposal.md`](../../specs/101-v0-package-proposal.md) §2 (Package 7) and [`../../specs/100-package-boundary-doctrine.md`](../../specs/100-package-boundary-doctrine.md) §S3.
+
+Do not edit a divergent copy here — edit the canonical proposal.