@ouro.bot/friends 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/store-file.js

@@ -190,30 +190,43 @@ class FileFriendStore {
         const meta = raw;
         if (typeof meta.bundleName !== "string")
             return undefined;
+        // Mailbox is top-level on AgentMeta since the phase-8 demote. Read the
+        // top-level `meta.mailbox` first; if absent, MIGRATE-ON-READ from a legacy
+        // alpha.4 record that nested it under `a2a.mailbox`. schemaVersion stays 1;
+        // every legacy record reads clean.
+        const a2aRaw = meta.a2a && typeof meta.a2a === "object" && !Array.isArray(meta.a2a)
+            ? meta.a2a
+            : undefined;
+        const mailbox = this.normalizeMailbox(meta.mailbox) ??
+            (a2aRaw ? this.normalizeMailbox(a2aRaw.mailbox) : undefined);
+        const a2a = this.normalizeA2AMeta(meta.a2a);
         return {
             bundleName: meta.bundleName,
             familiarity: typeof meta.familiarity === "number" ? meta.familiarity : 0,
             sharedMissions: Array.isArray(meta.sharedMissions) ? meta.sharedMissions : [],
             outcomes: Array.isArray(meta.outcomes) ? meta.outcomes : [],
-            ...(this.normalizeA2AMeta(meta.a2a) ? { a2a: this.normalizeA2AMeta(meta.a2a) } : {}),
+            ...(a2a ? { a2a } : {}),
+            ...(mailbox ? { mailbox } : {}),
         };
     }
     normalizeA2AMeta(raw) {
         if (!raw || typeof raw !== "object" || Array.isArray(raw))
             return undefined;
         const meta = raw;
-        const mailbox = this.normalizeMailbox(meta.mailbox);
+        const relay = this.normalizeRelay(meta.relay);
         const a2a = {
             ...(typeof meta.cardUrl === "string" ? { cardUrl: meta.cardUrl } : {}),
             ...(typeof meta.endpointUrl === "string" ? { endpointUrl: meta.endpointUrl } : {}),
             ...(typeof meta.agentId === "string" ? { agentId: meta.agentId } : {}),
             ...(typeof meta.protocolVersion === "string" ? { protocolVersion: meta.protocolVersion } : {}),
-            ...(mailbox ? { mailbox } : {}),
+            ...(relay ? { relay } : {}),
+            ...(typeof meta.did === "string" ? { did: meta.did } : {}),
         };
         return Object.keys(a2a).length > 0 ? a2a : undefined;
     }
-    /** Preserve an additive a2a.mailbox coord only when both fields are strings;
-     * otherwise drop it (absent ⇒ unchanged — the additive guarantee). */
+    /** Preserve the top-level mailbox coord only when both fields are strings;
+     * otherwise drop it (absent ⇒ unchanged — the additive guarantee). Also used to
+     * migrate a legacy nested `a2a.mailbox`. */
     normalizeMailbox(raw) {
         if (!raw || typeof raw !== "object" || Array.isArray(raw))
             return undefined;
@@ -222,6 +235,16 @@ class FileFriendStore {
             return undefined;
         return { repo: m.repo, selfOutboxAgentId: m.selfOutboxAgentId };
     }
+    /** Preserve an additive a2a.relay coord only when both fields are strings;
+     * otherwise drop it (absent ⇒ unchanged — the additive guarantee). */
+    normalizeRelay(raw) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return undefined;
+        const r = raw;
+        if (typeof r.url !== "string" || typeof r.handle !== "string")
+            return undefined;
+        return { url: r.url, handle: r.handle };
+    }
     async readJson(filePath) {
         try {
             const raw = await fsPromises.readFile(filePath, "utf-8");

package/dist/trust-explanation.d.ts

@@ -1,5 +1,5 @@
 import type { Channel, FriendRecord, TrustLevel } from "./types";
-export type TrustBasis = "direct" | "shared_group" | "unknown";
+export type TrustBasis = "direct" | "shared_group" | "unknown" | "same_account";
 export interface TrustExplanation {
     level: TrustLevel;
     basis: TrustBasis;
@@ -13,4 +13,10 @@ export declare function describeTrustContext(input: {
     friend: FriendRecord;
     channel: Channel;
     isGroupChat?: boolean;
+    /** When the relationship is `family` AND this hint is `"same_account"`, the
+     * explanation attributes the family trust to the signed account roster
+     * (`basis: "same_account"`) instead of the generic `direct`. Ignored for any
+     * non-family level. Absent ⇒ existing behavior byte-for-byte. (Unit 3a stub:
+     * accepted but not yet honored — implemented GREEN in Unit 3b.) */
+    basisHint?: TrustBasis;
 }): TrustExplanation;

package/dist/trust-explanation.js

@@ -11,14 +11,17 @@ function resolveLevel(friend) {
 function describeTrustContext(input) {
     const level = resolveLevel(input.friend);
     const relatedGroupId = findRelatedGroupId(input.friend);
-    const explanation = level === "family" || level === "friend"
+    // The same-account variant only applies where the relationship is actually
+    // account-derived family: level === "family" AND the caller hints same_account
+    // (the roster path seats it). It keeps the family tier's permits/constraints but
+    // attributes the trust to the signed account roster, not generic direct trust.
+    const isSameAccountFamily = level === "family" && input.basisHint === "same_account";
+    const explanation = isSameAccountFamily
         ? {
             level,
-            basis: "direct",
-            summary: level === "family"
-                ? "direct family trust"
-                : "direct trusted relationship",
-            why: "this relationship is directly trusted rather than inferred through a shared group or cold first contact.",
+            basis: "same_account",
+            summary: "same-account family (signed account roster)",
+            why: "this agent is recognized as the same owner's agent via the signed account roster, not through a shared group or cold first contact.",
             permits: [
                 "local operations when appropriate",
                 "proactive follow-through",
@@ -26,39 +29,54 @@ function describeTrustContext(input) {
             ],
             constraints: [],
         }
-        : level === "acquaintance"
+        : level === "family" || level === "friend"
             ? {
                 level,
-                basis: "shared_group",
-                summary: relatedGroupId
-                    ? "known through the shared project group"
-                    : "known through a shared group context",
-                why: relatedGroupId
-                    ? `this trust comes from the shared group context ${relatedGroupId}, not from direct endorsement.`
-                    : "this trust comes from shared group context rather than direct endorsement.",
+                basis: "direct",
+                summary: level === "family"
+                    ? "direct family trust"
+                    : "direct trusted relationship",
+                why: "this relationship is directly trusted rather than inferred through a shared group or cold first contact.",
                 permits: [
-                    "group-safe coordination",
-                    "normal conversation inside the shared context",
+                    "local operations when appropriate",
+                    "proactive follow-through",
+                    "full collaborative problem solving",
                 ],
-                constraints: [
-                    "guarded local actions",
-                    "do not assume broad private authority",
-                ],
-                relatedGroupId,
+                constraints: [],
             }
-            : {
-                level,
-                basis: "unknown",
-                summary: "truly unknown first-contact context",
-                why: "this person is not known through direct trust or a shared group context.",
-                permits: [
-                    "safe first-contact orientation only",
-                ],
-                constraints: [
-                    "first contact does not reach the full model on open channels",
-                    "no local or privileged actions",
-                ],
-            };
+            : level === "acquaintance"
+                ? {
+                    level,
+                    basis: "shared_group",
+                    summary: relatedGroupId
+                        ? "known through the shared project group"
+                        : "known through a shared group context",
+                    why: relatedGroupId
+                        ? `this trust comes from the shared group context ${relatedGroupId}, not from direct endorsement.`
+                        : "this trust comes from shared group context rather than direct endorsement.",
+                    permits: [
+                        "group-safe coordination",
+                        "normal conversation inside the shared context",
+                    ],
+                    constraints: [
+                        "guarded local actions",
+                        "do not assume broad private authority",
+                    ],
+                    relatedGroupId,
+                }
+                : {
+                    level,
+                    basis: "unknown",
+                    summary: "truly unknown first-contact context",
+                    why: "this person is not known through direct trust or a shared group context.",
+                    permits: [
+                        "safe first-contact orientation only",
+                    ],
+                    constraints: [
+                        "first contact does not reach the full model on open channels",
+                        "no local or privileged actions",
+                    ],
+                };
     (0, observability_1.emitNervesEvent)({
         component: "friends",
         event: "friends.trust_explained",

package/dist/trust-mutation.d.ts

@@ -1,4 +1,16 @@
 import type { FriendStore } from "./store";
 import type { TrustLevel } from "./types";
 import type { FriendOpResult } from "./results";
-export declare function setFriendTrust(store: FriendStore, friendId: string, level: TrustLevel): Promise<FriendOpResult>;
+import type { AuditSink } from "./audit";
+import type { TrustBasis } from "./trust-explanation";
+/** Optional control-plane context for a trust mutation (Bug B). When a `sink` is
+ * supplied, a successful mutation appends one append-only control-plane audit
+ * record carrying WHO (`actor`), the `basis` and `originSense`, and WHEN. All
+ * fields are optional so the existing 3-arg callers are unaffected. */
+export interface SetFriendTrustContext {
+    actor?: string;
+    originSense?: string;
+    basis?: TrustBasis;
+    sink?: AuditSink;
+}
+export declare function setFriendTrust(store: FriendStore, friendId: string, level: TrustLevel, ctx?: SetFriendTrustContext): Promise<FriendOpResult>;

package/dist/trust-mutation.js

@@ -7,7 +7,8 @@ exports.setFriendTrust = setFriendTrust;
 // `trustLevel` and `role` to the same level (so the record's coarse role tracks
 // its trust). A missing friend is a normal `not_found` result, never a throw.
 const observability_1 = require("./observability");
-async function setFriendTrust(store, friendId, level) {
+const identity_1 = require("./identity");
+async function setFriendTrust(store, friendId, level, ctx) {
     (0, observability_1.emitNervesEvent)({
         component: "friends",
         event: "friends.trust_set",
@@ -16,14 +17,42 @@ async function setFriendTrust(store, friendId, level) {
     });
     const current = await store.get(friendId);
     if (!current) {
+        // not_found is an early return BEFORE any mutation — and so writes NO audit
+        // record. The control-plane log captures actual standing changes only.
         return { ok: false, status: "not_found", message: "friend record not found" };
     }
+    const updatedAt = new Date().toISOString();
     const updated = {
         ...current,
         trustLevel: level,
         role: level,
-        updatedAt: new Date().toISOString(),
+        updatedAt,
     };
     await store.put(friendId, updated);
+    // Bug B — append one control-plane audit record on the successful mutation. The
+    // `targetDid` is the record's durable identity DID (identity.did, falling back to
+    // the migrated a2a.did via resolveAgentIdentity). `actor` defaults to the literal
+    // "unknown" when the caller threads no context. No sink ⇒ a clean no-op.
+    //
+    // NOTE (finding 6-B): the append runs AFTER store.put, so it is best-effort with
+    // respect to the mutation — if the sink append throws/crashes, the trust change is
+    // already persisted but the audit line may be missing. We keep this ordering on
+    // purpose (the mutation is the source of truth; the audit is an observability log,
+    // not a 2-phase-commit participant). A throwing sink rejects this call so the caller
+    // still sees the failure; it does not roll back the already-applied mutation.
+    if (ctx?.sink) {
+        const targetDid = (0, identity_1.resolveAgentIdentity)(current.agentMeta).did;
+        const record = {
+            action: "set_trust",
+            targetId: friendId,
+            ...(targetDid !== undefined ? { targetDid } : {}),
+            level,
+            ...(ctx.basis !== undefined ? { basis: ctx.basis } : {}),
+            actor: ctx.actor ?? "unknown",
+            ...(ctx.originSense !== undefined ? { originSense: ctx.originSense } : {}),
+            ts: updatedAt,
+        };
+        await ctx.sink.append(record);
+    }
     return { ok: true, status: "updated", record: updated };
 }

package/dist/types.d.ts

@@ -108,19 +108,45 @@ export interface AgentMeta {
     familiarity: number;
     sharedMissions: string[];
     outcomes: RelationshipOutcome[];
+    /** The durable identity home (p11 Item 2 — the DID re-key). `did` is the
+     * cross-agent primary key; `pinnedKey` is its TOFU-pinned Ed25519 public key.
+     * Additive + optional: legacy records carry only `a2a.did` (or nothing) and
+     * migrate-on-read into this shape via `resolveAgentIdentity`. schemaVersion
+     * stays 1. */
+    identity?: {
+        did: string;
+        pinnedKey?: string;
+        handle?: string;
+        pinnedAt?: string;
+    };
     a2a?: {
         cardUrl?: string;
         endpointUrl?: string;
         agentId?: string;
         protocolVersion?: string;
-        /** Optional A2A git-mailbox coordinates (brick two). The mailbox is a
-         * dedicated PRIVATE repo holding only in-flight envelopes; `selfOutboxAgentId`
-         * is the dir THIS peer writes its outbox under. Absent on records that don't
-         * use the git-mailbox transport. */
-        mailbox?: {
-            repo: string;
-            selfOutboxAgentId: string;
+        /** Optional friends-relay coordinates (phase 8). When a peer has no directly
+         * reachable A2A `endpointUrl`, the host delivers via the UNTRUSTED relay at
+         * `url`, addressing the peer by its opaque `handle`. The relay carries only
+         * ciphertext (the E2E sign-then-seal overlay) — it never sees content. Absent
+         * on peers reachable directly or only via the git-mailbox fallback. */
+        relay?: {
+            url: string;
+            handle: string;
         };
+        /** The peer's pinned DID (phase 8 — `did:key:…` or `did:web:…`). `agentId ===
+         * did` (the DID is the cross-agent identity primary key); pinned on first
+         * contact (TOFU) and verified on every use thereafter. Absent until the peer
+         * presents a DID-bearing proof. */
+        did?: string;
+    };
+    /** Optional git-mailbox FALLBACK coordinates (the demoted no-endpoint transport;
+     * see src/mailbox/). The mailbox is a dedicated PRIVATE repo holding only
+     * in-flight envelopes; `selfOutboxAgentId` is the dir THIS peer writes its outbox
+     * under. Top-level since phase 8's demote (was nested under `a2a` in alpha.4 —
+     * legacy records migrate-on-read). Absent on peers that don't use the fallback. */
+    mailbox?: {
+        repo: string;
+        selfOutboxAgentId: string;
     };
 }
 export interface FriendRecord {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/friends",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "description": "The who's-who / identity / relationship substrate for agents — trust ladder (family/friend/acquaintance/stranger), multi-party and multi-agent, consumed via the FriendStore interface + FriendResolver.",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -14,9 +14,13 @@
       "types": "./dist/mcp/index.d.ts",
       "default": "./dist/mcp/index.js"
     },
-    "./a2a": {
-      "types": "./dist/a2a/index.d.ts",
-      "default": "./dist/a2a/index.js"
+    "./mailbox": {
+      "types": "./dist/mailbox/index.d.ts",
+      "default": "./dist/mailbox/index.js"
+    },
+    "./a2a-client": {
+      "types": "./dist/a2a-client/index.d.ts",
+      "default": "./dist/a2a-client/index.js"
     }
   },
   "bin": {
@@ -29,6 +33,7 @@
   "type": "commonjs",
   "scripts": {
     "build": "tsc",
+    "postbuild": "node -e \"require('fs').chmodSync('dist/mcp/bin.js', 0o755)\"",
     "prepare": "npm run build",
     "pretest": "npm run build",
     "pretest:coverage": "npm run build",
@@ -37,10 +42,11 @@
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
     "example:cross-agent-moat": "npm run build && tsx examples/cross-agent-moat.ts",
-    "example:a2a-git-mailbox": "npm run build && tsx examples/a2a-git-mailbox.ts",
+    "example:mailbox-fallback": "npm run build && tsx examples/mailbox-fallback.ts",
     "example:cross-agent-mission-memory": "npm run build && tsx examples/cross-agent-mission-memory.ts",
     "example:cross-agent-standing": "npm run build && tsx examples/cross-agent-standing.ts",
     "example:cross-agent-coordination": "npm run build && tsx examples/cross-agent-coordination.ts",
+    "example:cross-agent-a2a-relay": "npm run build && tsx examples/cross-agent-a2a-relay.ts",
     "release:bump": "node scripts/release-bump.cjs",
     "release:preflight": "node scripts/release-preflight.cjs",
     "release:trust:check": "node scripts/npm-trusted-publishers.cjs check",
@@ -54,8 +60,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {},
+  "dependencies": {
+    "libsodium-wrappers": "0.8.4"
+  },
   "devDependencies": {
+    "@types/libsodium-wrappers": "0.8.2",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^10.0.2",