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

package/dist/mission-result.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareMissionResult = prepareMissionResult;
+exports.importMissionResult = importMissionResult;
+// prepareMissionResult (producer) + importMissionResult (consumer) — the result-return
+// envelope (gap-2, p11 inc2). The honest north-star DELIVERABLE channel. Structural twin
+// of mission-share.ts, re-aimed from a SHARE (outcomes/learnings) at a RESULT (B's actual
+// produced artifact, attributed to B, correlated to A's delegation via missionKey +
+// requestId). Q1 resolved: a NEW result envelope, NOT a mission_share reuse.
+//
+// Store-only + transport-agnostic: prepareMissionResult returns an envelope,
+// importMissionResult consumes one; the WIRE is the caller's job (the result rides the
+// mailbox under kind:"mission_result"). Pure — the only node builtin is `node:crypto`,
+// mirroring mission-share.ts. Core-clean (no a2a-client import).
+//
+// Through-line invariants (every one tested in mission-result.test.ts):
+//  - the mission is named by its JOIN KEY (missionKey), NEVER the local UUID;
+//  - fromAgentId === the producing self (attributed to B);
+//  - the result correlates to A's delegation via requestId;
+//  - consent rides the "coordinate" identity-tier scope — a result is B answering A's OWN
+//    delegation request (no third-party content), so trust ≥ friend suffices, exactly like
+//    coordinate; NO new ShareScope, NO new content grant;
+//  - on import the deliverable lands QUARANTINED under importedResults[agentId][requestId],
+//    attributed to B + stamped imported, WITHOUT touching first-party;
+//  - correlation honesty: a result whose requestId matches NO prior first-party delegation
+//    on A is REJECTED (no_delegation) — A only accepts results for work it delegated;
+//  - assignee honesty (security-review inc-2 finding 1): a result whose source is NOT the
+//    agent A delegated TO (delegation.assignee.agentId !== fromAgentId) is REJECTED
+//    (assignee_mismatch), even from a trusted peer with the right requestId; a legacy
+//    delegation with no recorded assignee FAILS CLOSED;
+//  - NO seeding: an unknown mission → no_mission (a result never creates a mission);
+//  - the source agent's trust CAPS acceptance (a stranger/over-trust source writes nothing),
+//    checked BEFORE correlation;
+//  - non-transitive: status/participants are NEVER recomputed; first-party byte-untouched;
+//  - idempotent on replay (same (agentId, requestId) → no double-land).
+const observability_1 = require("./observability");
+const consent_1 = require("./consent");
+const verifier_1 = require("./verifier");
+/**
+ * Producer half of the result-return. Resolves the local mission by `missionId`; names
+ * it by its `missionKey` (NEVER the local UUID); attributes the result to `selfAgentId`
+ * (B); correlates by `requestId`. Consent-gated via the `"coordinate"` identity-tier
+ * scope (a result is B answering A's own delegation — trust ≥ friend suffices under the
+ * tiered default, ZERO new scope). Records the result first-party on B's own record under
+ * `results[requestId]`.
+ */
+async function prepareMissionResult(missions, store, grants, input, consent = consent_1.DEFAULT_CONSENT_POLICY) {
+    const record = await missions.get(input.missionId);
+    if (!record) {
+        return { ok: false, status: "not_found" };
+    }
+    // The recipient's trust is read from this agent's own knowledge of it (the a2a-agent
+    // friend record for toAgentId). An unknown recipient defaults to stranger.
+    const recipientRecord = await store.findByExternalId("a2a-agent", input.toAgentId);
+    const recipientTrust = recipientRecord?.trustLevel ?? "stranger";
+    const recipient = { agentId: input.toAgentId, trustLevel: recipientTrust };
+    // Consent rides the EXISTING "coordinate" identity-tier scope — a result is B
+    // answering A's OWN delegation, so trust ≥ friend suffices under the tiered default,
+    // with ZERO change to consent logic and NO new scope.
+    const consented = await consent.consents({
+        subjectKey: record.missionKey,
+        recipient,
+        scope: "coordinate",
+        grants,
+    });
+    if (!consented) {
+        return { ok: false, status: "no_consent" };
+    }
+    const now = new Date().toISOString();
+    const envelope = {
+        subject: { missionKey: record.missionKey, title: record.title },
+        fromAgentId: input.selfAgentId,
+        requestId: input.requestId,
+        result: {
+            requestId: input.requestId,
+            summary: input.result.summary,
+            ...(input.result.artifact !== undefined ? { artifact: input.result.artifact } : {}),
+            ...(input.result.outputs !== undefined ? { outputs: input.result.outputs } : {}),
+        },
+        issuedAt: now,
+        ...(input.proof !== undefined ? { proof: input.proof } : {}),
+    };
+    // Record the result first-party on B's own mission under results[requestId].
+    const firstPartyResult = { ...envelope.result, provenance: { origin: "first_party" } };
+    const updated = {
+        ...record,
+        results: { ...(record.results ?? {}), [input.requestId]: firstPartyResult },
+        updatedAt: now,
+    };
+    await missions.put(updated.id, updated);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.mission_result_prepared",
+        message: "prepared mission result envelope",
+        meta: { toAgentId: input.toAgentId, requestId: input.requestId, consentPolicy: consent.name },
+    });
+    return { ok: true, envelope };
+}
+// ── Consumer ──
+const TRUST_RANK = { family: 4, friend: 3, acquaintance: 2, stranger: 1 };
+/** Land B's deliverable under `importedResults[fromAgentId][requestId]`, returning a NEW
+ * namespace (never mutates the input). First-party `results` are NOT passed in and stay
+ * physically untouched. Idempotent per (agentId, requestId): an entry that already exists
+ * is preserved unchanged (never re-stamped). */
+function mergeImportedResult(record, result, fromAgentId, now) {
+    const existing = record.importedResults ?? {};
+    const forAgent = existing[fromAgentId] ?? {};
+    if (forAgent[result.requestId])
+        return existing;
+    return {
+        ...existing,
+        [fromAgentId]: {
+            ...forAgent,
+            [result.requestId]: {
+                requestId: result.requestId,
+                summary: result.summary,
+                ...(result.artifact !== undefined ? { artifact: result.artifact } : {}),
+                ...(result.outputs !== undefined ? { outputs: result.outputs } : {}),
+                provenance: { origin: "imported", assertedBy: { agentId: fromAgentId }, importedAt: now },
+            },
+        },
+    };
+}
+/**
+ * Consumer half of the result-return — the non-clobbering merge. Order (PINNED):
+ *  (1) TOFU verifier + trust cap (both must pass, else `untrusted_source`, write nothing);
+ *  (2) unknown mission (no findByMissionKey hit) → `no_mission` (NO seeding — a result
+ *      never creates a mission);
+ *  (3) the result's `requestId` not present in the record's FIRST-PARTY `delegations`
+ *      (A never delegated this) → `no_delegation` — correlation honesty;
+ *  (3b) the matched delegation's recorded `assignee` is not the result's source
+ *      (`delegation.assignee.agentId !== fromAgentId`) → `assignee_mismatch` — assignee
+ *      honesty (security-review inc-2 finding 1). FAILS CLOSED on a legacy delegation with
+ *      no recorded assignee. A mismatch writes NOTHING (not even quarantined);
+ *  (4) otherwise land under `importedResults[agentId][requestId]` (dedupe on replay),
+ *      stamped imported + attributed + importedAt, NEVER touching first-party
+ *      `learnings`/`notes`/`status`/`delegations`/`results`, NEVER recomputing
+ *      status/participants (non-transitive).
+ */
+async function importMissionResult(missions, input, options = {}) {
+    const verifier = options.verifier ?? verifier_1.DEFAULT_AGENT_VERIFIER;
+    const minTrust = options.minTrustToAccept ?? "acquaintance";
+    // (1) Authentication (caller's seam) AND authorization (trust ladder) must BOTH pass —
+    // checked BEFORE correlation, so a stranger never even learns whether the mission exists.
+    const authenticated = verifier.verify(input.fromAgentId, input.envelope.proof);
+    const trustedEnough = TRUST_RANK[input.trustOfSource] >= TRUST_RANK[minTrust];
+    if (!authenticated || !trustedEnough) {
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.mission_result_refused",
+            message: "refused mission result from untrusted source",
+            meta: { fromAgentId: input.fromAgentId, trustOfSource: input.trustOfSource, authenticated },
+        });
+        return { ok: false, status: "untrusted_source" };
+    }
+    // (2) Unknown mission → no_mission. A result NEVER seeds a mission (distinct from
+    // mission-share's friend-seed).
+    const existing = await missions.findByMissionKey(input.envelope.subject.missionKey);
+    if (!existing) {
+        return { ok: false, status: "no_mission" };
+    }
+    // (3) Correlation honesty — the requestId must name a delegation THIS agent issued
+    // first-party (A only accepts results for work it actually delegated).
+    const delegation = existing.delegations?.[input.envelope.requestId];
+    if (!delegation) {
+        return { ok: false, status: "no_delegation" };
+    }
+    // (3b) Assignee honesty (security-review inc-2 finding 1) — the result's SOURCE must be
+    // the very agent A delegated TO. The requestId being delegated is NOT enough: a peer C
+    // that A trusts (≥ the cap) who learned a requestId A delegated to a DIFFERENT agent B
+    // could otherwise inject a forged result. FAILS CLOSED on a legacy/orphan delegation with
+    // no recorded assignee (reject, never land). A mismatch writes NOTHING — not even
+    // quarantined.
+    if (delegation.assignee?.agentId !== input.fromAgentId) {
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.mission_result_refused",
+            message: "refused mission result — source is not the delegation's assignee",
+            meta: {
+                fromAgentId: input.fromAgentId,
+                requestId: input.envelope.requestId,
+                expectedAssignee: delegation.assignee?.agentId ?? null,
+            },
+        });
+        return { ok: false, status: "assignee_mismatch" };
+    }
+    // (4) Land the deliverable quarantined + attributed, never touching first-party, never
+    // recomputing status/participants (non-transitive).
+    const now = new Date().toISOString();
+    const importedResults = mergeImportedResult(existing, input.envelope.result, input.fromAgentId, now);
+    const updated = { ...existing, importedResults, updatedAt: now };
+    await missions.put(updated.id, updated);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.mission_result_imported",
+        message: "imported mission result into existing mission",
+        meta: { missionId: updated.id, fromAgentId: input.fromAgentId, requestId: input.envelope.requestId },
+    });
+    return { ok: true, status: "imported", record: updated };
+}

package/dist/mission-store-file.js

@@ -126,6 +126,14 @@ class FileMissionStore {
             // present iff the record carries one, so a legacy mission with no coordination
             // round-trips unchanged (absent ⇒ unclaimed).
             ...(raw.coordination && typeof raw.coordination === "object" ? { coordination: raw.coordination } : {}),
+            // The delegation/result namespaces (gap-1 + gap-2, p11 inc2) pass through the same
+            // way: present iff the record carries one, so a legacy mission round-trips unchanged
+            // (absent ⇒ none). Without these, a FILE-backed store would silently drop them,
+            // breaking the result-return correlation (which reads first-party `delegations`).
+            ...(raw.delegations && typeof raw.delegations === "object" ? { delegations: raw.delegations } : {}),
+            ...(raw.importedDelegations && typeof raw.importedDelegations === "object" ? { importedDelegations: raw.importedDelegations } : {}),
+            ...(raw.results && typeof raw.results === "object" ? { results: raw.results } : {}),
+            ...(raw.importedResults && typeof raw.importedResults === "object" ? { importedResults: raw.importedResults } : {}),
             createdAt: typeof raw.createdAt === "string" ? raw.createdAt : new Date().toISOString(),
             updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : new Date().toISOString(),
             schemaVersion: typeof raw.schemaVersion === "number" ? raw.schemaVersion : 1,

package/dist/types.d.ts

@@ -75,6 +75,48 @@ export interface ImportedLearning {
     assertedBy?: AgentAttribution;
     originallyAssertedBy?: AgentAttribution;
 }
+export interface MissionTaskSpec {
+    /** Correlation key the result-return matches (PINNED). Minted by the producer. */
+    requestId: string;
+    /** What B is being asked to do (the headline ask). */
+    summary: string;
+    /** Optional longer brief. */
+    details?: string;
+    /** Optional structured inputs. */
+    inputs?: Record<string, string>;
+}
+export interface MissionResult {
+    /** Correlates to the gap-1 task-spec's requestId (PINNED) — A only accepts a result
+     * for a requestId it actually delegated. */
+    requestId: string;
+    /** The headline deliverable — what B produced. */
+    summary: string;
+    /** Optional larger produced artifact body. */
+    artifact?: string;
+    /** Optional structured outputs. */
+    outputs?: Record<string, string>;
+    /** first_party on B's side; imported (attributed to B) on A's. */
+    provenance?: NoteProvenance;
+}
+export interface MissionResultEnvelope {
+    /** The mission, named by its join key — `missionKey` + a human title. */
+    subject: {
+        missionKey: string;
+        title: string;
+    };
+    /** The agent that produced this result (B's join-key agentId) — the attribution.
+     * NOTE (security review inc-2 finding 5, by-design): this is SELF-ASSERTED and is
+     * vestigial on import — importMissionResult attributes + enforces against the
+     * TRANSPORT-supplied `ImportMissionResultInput.fromAgentId` (the authenticated channel
+     * identity), never this envelope field, so a forged value here changes nothing. */
+    fromAgentId: string;
+    /** The delegation correlation key (matches the gap-1 task-spec's requestId). */
+    requestId: string;
+    result: MissionResult;
+    /** Opaque, verifier-specific proof slot. The TOFU verifier ignores it. */
+    proof?: string;
+    issuedAt: string;
+}
 export type CoordinationIntent = "request" | "offer" | "accept" | "decline" | "handoff";
 export declare function isCoordinationIntent(value: unknown): value is CoordinationIntent;
 export interface CoordinationLogEntry {
@@ -99,6 +141,17 @@ export interface MissionRecord {
     learnings: Record<string, MissionLearning>;
     importedLearnings?: Record<string, Record<string, ImportedLearning>>;
     coordination?: MissionCoordination;
+    delegations?: Record<string, {
+        task: MissionTaskSpec;
+        assignee?: AgentAttribution;
+        provenance: NoteProvenance;
+    }>;
+    importedDelegations?: Record<string, Record<string, {
+        task: MissionTaskSpec;
+        provenance: NoteProvenance;
+    }>>;
+    results?: Record<string, MissionResult>;
+    importedResults?: Record<string, Record<string, MissionResult>>;
     createdAt: string;
     updatedAt: string;
     schemaVersion: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/friends",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "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",
@@ -46,6 +46,7 @@
     "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-delegation": "npm run build && tsx examples/cross-agent-delegation.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",