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

package/README.md

@@ -39,12 +39,12 @@ narrow:
 - **Bring your own storage.** The library never decides *where* or *how* your data lives — you
   pass a path (or a connection string) and, if you want, your own storage backend.
 
-It is built as **five additive capability layers**. Each is a minimal primitive on the one before
+It is built as **six additive capability layers**. Each is a minimal primitive on the one before
 it; none is a workflow engine; removing any layer leaves the ones beneath it unchanged.
 
 ---
 
-## What it does — the five capabilities
+## What it does — the six capabilities
 
 ### 1. Identity + the cross-agent moat
 
@@ -158,9 +158,29 @@ an assignee onto anyone (the receiver's own `accept` confirms it — non-transit
 advisory metadata rather than a granted capability, and conflicts resolve last-writer-wins by
 timestamp. No queue, no DAG, no workflow DSL.
 
+### 6. Own-fleet delegation — link your own agents, then delegate work end-to-end
+
+The control-plane thread: the owner can **link two of their own agents** and have one **delegate a
+task** to the other, get it done, and **receive the result back** — over the same consent-gated,
+trust-capped, first-party-inviolable machinery.
+
+`connect_to` is a first-class **management-sense** capability — the owner introduces a peer into an
+agent's fleet, but **only from a trusted control surface**: a `local` (owner-only) sense commits
+inline; an `open` sense never does (it downgrades to a confirm-prompt); a `closed` sense is gated by
+a **signed account-roster membership check** (same-account `family` via `same_account`), never a
+blanket allow. The link is recorded as an `action:"connect"` control-plane audit. A bare name with
+no resolvable handle is answered honestly (`needs_handle_or_introduction`) rather than invented.
+
+Delegation then rides the layers already here: a **task-spec** travels on a coordination `request`
+(correlated by a minted `requestId`), and the **result-return** (`send_result` / `import_result`)
+carries the actual produced **deliverable** back — attributed to the doer, correlated to the original
+delegation, landing **quarantined** in a separate namespace on import. A result for work you never
+delegated is rejected (`no_delegation`); a stranger's result is refused at the trust cap; first-party
+knowledge is never touched. It is a deliverable channel, **not a remote-exec grant**.
+
 > The stack, in one line: agents **recognize** each other (1), **reach** each other (2),
-> **remember** shared work (3), **assess** each other (4), and **negotiate** who does what (5) —
-> each a minimal primitive on the last.
+> **remember** shared work (3), **assess** each other (4), **negotiate** who does what (5), and the
+> owner **links their own agents to delegate end-to-end** (6) — each a minimal primitive on the last.
 
 ---
 
@@ -252,7 +272,7 @@ You can also `npm pack` then
 Content-Length and newline-delimited JSON — auto-detected from the first message, so it works with
 harnesses on either convention.
 
-#### The tool surface — 29 tools
+#### The tool surface — 32 tools
 
 A thin 1:1 mapping over the library (no domain logic in the server):
 
@@ -269,6 +289,7 @@ A thin 1:1 mapping over the library (no domain logic in the server):
 | `link_identity` | Link an external identity, merging any orphan record that holds it. |
 | `unlink_identity` | Remove an external identity from a friend. |
 | `onboard_agent` | Upsert an agent-peer record from resolved coordinates (no HTTP fetch). |
+| `connect_to` | **Control plane** — the owner links one of their OWN agents into the fleet (introduce a peer by agentId/did/name at a trust level, default `family`). Authority-gated to a management sense (`local` commits; an `open` sense downgrades to a confirm-prompt; `closed` is gated by a roster/membership check); a bare name with no resolvable handle/DID returns `needs_handle_or_introduction` (never fabricates). Writes an `action:"connect"` control-plane audit. |
 | `whoami` | Resolve the machine owner and which record represents the self. |
 | `channel_caps` | Return a channel's capabilities. |
 | `resolve_room` | Resolve a room (a group's external id) into its members, each with trust context and `knownVia`. |
@@ -287,13 +308,17 @@ A thin 1:1 mapping over the library (no domain logic in the server):
 | `coordinate` | **Producer** — prepare a coordination message (`request` / `offer` / `accept` / `decline` / `handoff`) that negotiates **who** does a mission. |
 | `import_coordination` | **Consumer** — import a coordination message (appends to the mission's coordination log; only a self-`accept` sets the assignee; a `handoff` never forces one). |
 | `get_coordination` | Read a mission's coordination state — its current assignee + the append-only negotiation log. |
+| `send_result` | **Producer** — return B's DELIVERABLE for a delegation, attributed to B + correlated to A's task-spec by `requestId`, named by the mission's `missionKey` (consent-gated via the `coordinate` scope). |
+| `import_result` | **Consumer** — import a result-return; lands B's deliverable quarantined + attributed under `importedResults`, trust-capped; a result whose `requestId` matches no prior first-party delegation is rejected (`no_delegation`); never recomputes status. |
 
 The consent tools (`share_profile` / `import_profile` / `grant_share` / `revoke_share` /
-`list_shares`) need a **grant store**; the mission and coordination tools need a **mission store**.
-The `friends-mcp` binary wires both automatically at sibling `_grants/` and `_missions/` directories
-under `--dir`. An embedded server gets them by passing `grants` / `missions` to
-`createFriendsMcpServer`. Without the relevant store, those tools report
-`{ ok: false, status: "unsupported" }` and everything else works store-only.
+`list_shares`) need a **grant store**; the mission, coordination, and result-return tools
+(`send_result` consumes both) need a **mission store**. The `friends-mcp` binary wires both
+automatically at sibling `_grants/` and `_missions/` directories under `--dir` (plus the
+`_audit/` control-plane log `connect_to` / `set_trust` write through). An embedded server gets
+them by passing `grants` / `missions` / `audit` to `createFriendsMcpServer`. Without the
+relevant store, those tools report `{ ok: false, status: "unsupported" }` and everything else
+works store-only.
 
 The server module is consumed in code from the `@ouro.bot/friends/mcp` subpath, exporting
 `createFriendsMcpServer`, `getToolSchemas`, and `runMain`.
@@ -470,6 +495,10 @@ npm run example:cross-agent-standing        # earned standing: first-party-only,
                                             #   inert on trust
 npm run example:cross-agent-coordination    # the five coordination verbs end-to-end: assignment,
                                             #   non-transitive handoff, last-writer-wins, seeding gate
+npm run example:cross-agent-delegation      # own-fleet delegation: two of the owner's agents,
+                                            #   same-account family (signed roster), connect_to link,
+                                            #   A delegates → B performs → B returns the result → A
+                                            #   imports it — every invariant hard-asserted
 ```
 
 Read them as the honest spec of what the package promises: if a guarantee weren't real, the
@@ -501,7 +530,7 @@ setNervesEmitter((event) => {
 
 ## Design notes & status
 
-- **Store-only, transport-agnostic, additive.** The five layers were each built as a minimal
+- **Store-only, transport-agnostic, additive.** The six layers were each built as a minimal
   primitive that does not modify the layers beneath it. The cross-agent envelopes are plain data; the
   wire is always the caller's job (the `./mailbox` git-mailbox is one optional, host-driven fallback). A
   CI-enforced dependency rule keeps the core from ever importing the transport.
@@ -510,8 +539,9 @@ setNervesEmitter((event) => {
   clean.
 - **Not a workflow engine.** Each layer deliberately refuses the larger machine it brushes against:
   the mission ledger is not a knowledge base, standing is not a reputation engine, coordination is not
-  a scheduler. The discipline is the point.
-- **Alpha.** The surface is feature-complete across the five layers but pre-1.0 — expect additive
+  a scheduler, and the delegation channel is a deliverable return — not a remote-exec grant. The
+  discipline is the point.
+- **Alpha.** The surface is feature-complete across the six layers but pre-1.0 — expect additive
   changes, and pin a version. Feedback and issues are welcome.
 
 ### Public API
@@ -538,10 +568,17 @@ setNervesEmitter((event) => {
 `ImportCoordinationStatus`, `SetFriendTrustContext`, `AuditSink`, `ControlPlaneAuditRecord`,
 `ResolvedAgentIdentity`, `RosterStore`, `AccountRoster`, `RosterPin`, `RosterVerifier`,
 `AccountMembershipDecision`, `AccountMembershipResult`, `EvaluateAccountMembershipInput`,
-`FriendResolverRosterContext`. (`TrustBasis` additively gains the `"same_account"` member — the basis
-for family granted via the signed account roster — and `AgentMeta` additively gains an optional
-`identity { did, pinnedKey?, handle?, pinnedAt? }` durable-identity home; both are schemaVersion-1
-additive, and a legacy `a2a.did` migrates-on-read into `identity.did`.)
+`FriendResolverRosterContext`, `ConnectPeer`, `ConnectAgentsInput`, `ConnectAgentsDeps`,
+`ConnectResult`, `ConnectStatus`, `AuthorizeConnectInput`, `ConnectAuthorization`, `MissionTaskSpec`,
+`MissionResult`, `MissionResultEnvelope`, `PrepareMissionResultInput`, `PrepareMissionResultResult`,
+`PrepareMissionResultStatus`, `ImportMissionResultInput`, `ImportMissionResultOptions`,
+`ImportMissionResultResult`, `ImportMissionResultStatus`. (`TrustBasis` additively gains the
+`"same_account"` member — the basis for family granted via the signed account roster — and `AgentMeta`
+additively gains an optional `identity { did, pinnedKey?, handle?, pinnedAt? }` durable-identity home;
+both are schemaVersion-1 additive, and a legacy `a2a.did` migrates-on-read into `identity.did`.
+`MissionRecord` additively gains the own-fleet delegation namespaces `delegations` / `importedDelegations`
+(gap-1) and `results` / `importedResults` (gap-2), and `ControlPlaneAuditRecord.action` widens additively
+to `"set_trust" | "connect"`.)
 
 **Values:** `TRUSTED_LEVELS`, `IDENTITY_SCOPES`, `isTrustedLevel`, `isIdentityProvider`,
 `isIntegration`, `isShareScope`, `isCoordinationIntent`, `FileFriendStore`, `FileGrantStore`,
@@ -557,7 +594,8 @@ additive, and a legacy `a2a.did` migrates-on-read into `identity.did`.)
 `listShares`, `isGrantEffective`, `setNervesEmitter`, `emitNervesEvent`, `resolveAgentIdentity`,
 `withMigratedIdentity`, `findFriendByDid`, `MemoryAuditSink`, `FileAuditSink`, `auditPathFor`,
 `FileRosterStore`, `rostersDirFor`, `MemoryRosterStore`, `identityRosterVerifier`,
-`DEFAULT_ROSTER_VERIFIER`, `evaluateAccountMembership`.
+`DEFAULT_ROSTER_VERIFIER`, `evaluateAccountMembership`, `connectAgents`, `authorizeConnect`,
+`prepareMissionResult`, `importMissionResult`.
 
 **From `@ouro.bot/friends/mcp`:** `createFriendsMcpServer`, `getToolSchemas`, `runMain` (plus the
 `McpToolSchema`, `FriendsMcpServer`, and `RunMainIo` types).

package/changelog.json

@@ -1,5 +1,11 @@
 {
   "versions": [
+    {
+      "version": "0.1.0-alpha.7",
+      "changes": [
+        "p11 increment 2 — own-fleet delegation: connect_to control plane + the LOCAL delegate->perform->return proof (task-spec + result-return). Brick 8 (greenfield): connectAgents + a NEW management-sense authority predicate (authorizeConnect) — the owner links one of their own agents into the fleet, gated to a management sense (local commits inline; an open sense downgrades to a confirm-prompt; closed is gated by a signed account-roster membership check, NEVER a blanket allow), with disambiguation honesty (a bare name with no resolvable handle/DID returns needs_handle_or_introduction, never fabricated). connect_to is a library fn + an MCP tool, writes an action:\"connect\" control-plane audit (ControlPlaneAuditRecord.action widens additively to \"set_trust\" | \"connect\"), and the MCP boundary maps the stdio origin to a local management senseType (a network transport passes its real senseType + a pre-computed roster membership). gap-1 (the task-spec): CoordinationEnvelope gains an optional task? (MissionTaskSpec with a minted requestId) on the delegation request — recorded first-party under MissionRecord.delegations[requestId], imported quarantined under importedDelegations[agentId][requestId] (trust-capped, non-transitive, first-party-inviolable). gap-2 (the result-return): a NEW prepareMissionResult/importMissionResult envelope (twin of mission-share, NOT a reuse) carries B's actual DELIVERABLE back to A — attributed to B, correlated by missionKey + requestId, consent-gated via the existing \"coordinate\" scope (no new ShareScope); on import it lands quarantined + attributed under importedResults, rejects a result whose requestId matches no prior first-party delegation (no_delegation — correlation honesty), rejects a result whose source is not the agent the work was delegated TO (assignee_mismatch — assignee honesty; the delegation now persists its assignee and the import enforces source === assignee, failing closed on a legacy assignee-less record), never seeds a mission (no_mission), is trust-capped (untrusted_source before correlation), non-transitive, idempotent on replay. The mailbox kind union widens additively to carry kind:\"mission_result\". 3 new MCP tools (connect_to, send_result, import_result) — 29 -> 32; the coordinate tool now threads the task-spec. FileMissionStore.normalize round-trips the four new additive MissionRecord namespaces (delegations/importedDelegations/results/importedResults). A LOCAL hermetic proof (examples/cross-agent-delegation.ts): two own-fleet agents on separate stores, recognized as same-account family via a signed roster (real ed25519) on both sides, linked by the owner via connect_to, then A delegates a task -> B performs it -> B returns the deliverable -> A imports it — every invariant hard-asserted (missionKey-not-UUID, first-party-inviolable, non-transitive, trust cap, orphan-reject, trusted-non-assignee-reject, replay-inert, no third-party leak); exit 0, with a negative control that bites. Security review (inc-2): finding 1 (MEDIUM, cross-delegation result injection) FIXED as above — a trusted peer that is not the assignee can no longer inject a forged result for a requestId delegated to a different agent; findings 2-3 (LOW, dormant networking pre-conditions) DOCUMENTED at the connect_to authority gate + introduce-default site (before any non-local/networked controlContext is wired, the connect commit must add target-side roster verification and validate the caller-supplied trustLevel against the authority decision); findings 4-5 (existence oracle, vestigial envelope.fromAgentId) accepted by-design (finding 5 noted at its site). Core stays transport-free (the core⊥a2a-client + mailbox⊥mcp CI rules unmodified); 100% coverage maintained."
+      ]
+    },
     {
       "version": "0.1.0-alpha.6",
       "changes": [

package/dist/audit.d.ts

@@ -1,10 +1,14 @@
 import type { TrustBasis } from "./trust-explanation";
 import type { TrustLevel } from "./types";
-/** One append-only control-plane audit record. Captures a single trust mutation:
- * WHO (`actor`), to WHOM (`targetId` / optional `targetDid`), the new `level`, the
- * `basis` it was granted on, the `originSense` it came through, and WHEN (`ts`). */
+/** One append-only control-plane audit record. Captures a single control-plane
+ * mutation: WHO (`actor`), to WHOM (`targetId` / optional `targetDid`), the resulting
+ * `level`, the `basis` it was granted on, the `originSense` it came through, and WHEN
+ * (`ts`). The `action` discriminates the mutation kind: `"set_trust"` (a trust-level
+ * change — the `setFriendTrust` mutation + the `onboard_agent` trust seat) or
+ * `"connect"` (an owner linking one of their own agents into the fleet via `connect_to`
+ * — p11 inc2; additive, the JSONL append is value-agnostic so only the type widened). */
 export interface ControlPlaneAuditRecord {
-    action: "set_trust";
+    action: "set_trust" | "connect";
     targetId: string;
     targetDid?: string;
     level: TrustLevel;

package/dist/connect-authority.d.ts

@@ -0,0 +1,43 @@
+import type { SenseType } from "./types";
+import type { AccountMembershipResult } from "./account-roster";
+/** Input to the management-sense authority predicate. `senseType` is the sense the
+ * `connect_to` arrived through (the MCP boundary supplies `local` for the owner-only
+ * stdio path; a network transport passes its real senseType). `membership` is the
+ * PRE-COMPUTED account-roster decision for the `closed` branch — the caller runs
+ * evaluateAccountMembership and passes its result; absent ⇒ no membership proven. */
+export interface AuthorizeConnectInput {
+    senseType: SenseType;
+    membership?: AccountMembershipResult;
+}
+/** The authority decision (PINNED discriminated union). `commit` ⇒ the `connect_to`
+ * may link inline + audit. `downgrade` ⇒ it must NOT commit; the caller raises a
+ * confirm-prompt instead. The `reason` names exactly why the inline commit was
+ * withheld, so the prompt copy + the audit/no-audit branch are unambiguous. */
+export type ConnectAuthorization = {
+    decision: "commit";
+} | {
+    decision: "downgrade";
+    reason: "open_sense_needs_confirmation" | "closed_sense_not_member" | "internal_sense_not_management";
+};
+/** Decide whether a `connect_to` may COMMIT inline from the given management sense.
+ *
+ * `local` is the owner-only management sense (stdio/CLI — the user who launched the
+ * process). `closed` is org-gated but NOT inherently the owner, so it commits ONLY
+ * when the peer is proven same-account family via the signed roster (the caller's
+ * pre-computed `membership`); any other decision — or no membership at all — downgrades
+ * (NEVER a blanket allow on `closed`). An `open` sense (anyone can reach it) never
+ * commits inline regardless of membership. `internal` is the agent's inner dialog —
+ * not a management surface at all. Every non-commit is a structured downgrade RETURN.
+ *
+ * ┌─ PRE-CONDITION before any non-local / networked `controlContext` is ever wired ──────┐
+ * │ (security review inc-2 findings 2-3): this gate authenticates the CALLER's           │
+ * │ sense/membership but places NO constraint on the TARGET, and connectAgents defaults  │
+ * │ the introduce trust to `family`. Both are correct + safe ONLY because the path is     │
+ * │ owner-only stdio today (every wire supplies `senseType: "local"`; no wire constructs  │
+ * │ a non-`local` controlContext). The `connect` commit MUST add target-side roster      │
+ * │ verification (the target did must ALSO be roster-checked, not just TOFU-upserted)     │
+ * │ AND validate the caller-supplied `trustLevel` against the authority decision BEFORE   │
+ * │ any non-`local`/networked controlContext is wired. The current `family` default +     │
+ * │ unconstrained target are safe only for the owner-only-stdio path.                     │
+ * └──────────────────────────────────────────────────────────────────────────────────────┘ */
+export declare function authorizeConnect(input: AuthorizeConnectInput): ConnectAuthorization;

package/dist/connect-authority.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorizeConnect = authorizeConnect;
+// authorizeConnect — the management-sense authority predicate (brick 8, greenfield).
+//
+// The control-plane gate for `connect_to`: a PURE function that decides whether the
+// owner introducing one of their own agents into the calling agent's fleet may
+// COMMIT inline, or must DOWNGRADE to a confirm-prompt. Brick 8 is genuinely
+// greenfield in friends — there is NO trust-gate.ts / handleStranger to patch (those
+// live in ouroboros); this predicate is the management-sense authority from scratch.
+//
+// CORE-CLEAN by construction: the `closed`-branch membership decision arrives
+// PRE-COMPUTED via the injected seam. The CALLER runs evaluateAccountMembership
+// against the increment-1 roster surface and passes the `AccountMembershipResult` in;
+// this module never calls it, so it imports NO a2a-client / libsodium (the lint
+// enforces the direction). It is a pure value→value map with one observability emit.
+//
+// The contract (every branch — see connect-authority.test.ts):
+//   - local                                  → commit  (owner-only stdio/CLI — the management sense)
+//   - closed + membership family_same_account → commit  (org-gated AND a roster-verified same-account peer)
+//   - closed + any other / absent membership  → downgrade closed_sense_not_member  (NEVER a blanket allow)
+//   - open (a2a/mail/bluebubbles)             → downgrade open_sense_needs_confirmation  (regardless of membership)
+//   - internal                               → downgrade internal_sense_not_management
+// A downgrade is ALWAYS a structured RETURN value, never a throw — the caller turns it
+// into a confirm-prompt and writes no audit / makes no link.
+const observability_1 = require("./observability");
+/** Decide whether a `connect_to` may COMMIT inline from the given management sense.
+ *
+ * `local` is the owner-only management sense (stdio/CLI — the user who launched the
+ * process). `closed` is org-gated but NOT inherently the owner, so it commits ONLY
+ * when the peer is proven same-account family via the signed roster (the caller's
+ * pre-computed `membership`); any other decision — or no membership at all — downgrades
+ * (NEVER a blanket allow on `closed`). An `open` sense (anyone can reach it) never
+ * commits inline regardless of membership. `internal` is the agent's inner dialog —
+ * not a management surface at all. Every non-commit is a structured downgrade RETURN.
+ *
+ * ┌─ PRE-CONDITION before any non-local / networked `controlContext` is ever wired ──────┐
+ * │ (security review inc-2 findings 2-3): this gate authenticates the CALLER's           │
+ * │ sense/membership but places NO constraint on the TARGET, and connectAgents defaults  │
+ * │ the introduce trust to `family`. Both are correct + safe ONLY because the path is     │
+ * │ owner-only stdio today (every wire supplies `senseType: "local"`; no wire constructs  │
+ * │ a non-`local` controlContext). The `connect` commit MUST add target-side roster      │
+ * │ verification (the target did must ALSO be roster-checked, not just TOFU-upserted)     │
+ * │ AND validate the caller-supplied `trustLevel` against the authority decision BEFORE   │
+ * │ any non-`local`/networked controlContext is wired. The current `family` default +     │
+ * │ unconstrained target are safe only for the owner-only-stdio path.                     │
+ * └──────────────────────────────────────────────────────────────────────────────────────┘ */
+function authorizeConnect(input) {
+    const result = decide(input);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.connect_authorized",
+        message: "evaluated connect_to management-sense authority",
+        meta: {
+            senseType: input.senseType,
+            decision: result.decision,
+            ...(result.decision === "downgrade" ? { reason: result.reason } : {}),
+        },
+    });
+    return result;
+}
+/** The pure decision, factored out so the single observability emit wraps every
+ * branch (the one return path keeps the emit DRY and fully covered). */
+function decide(input) {
+    switch (input.senseType) {
+        case "local":
+            // Owner-only management sense — the user who launched the process. Commit.
+            return { decision: "commit" };
+        case "closed":
+            // Org-gated but not inherently the owner: commit ONLY for a roster-verified
+            // same-account peer. Anything else (incl. absent membership) downgrades — there
+            // is NO blanket allow on `closed`.
+            return input.membership?.decision === "family_same_account"
+                ? { decision: "commit" }
+                : { decision: "downgrade", reason: "closed_sense_not_member" };
+        case "open":
+            // Anyone can reach an open sense — it can NEVER commit a control-plane link
+            // inline, regardless of any membership claim.
+            return { decision: "downgrade", reason: "open_sense_needs_confirmation" };
+        case "internal":
+            // The agent's inner dialog — not a management surface.
+            return { decision: "downgrade", reason: "internal_sense_not_management" };
+    }
+}

package/dist/connect.d.ts

@@ -0,0 +1,55 @@
+import type { FriendStore } from "./store";
+import type { AuditSink } from "./audit";
+import type { ConnectAuthorization } from "./connect-authority";
+import type { AccountMembershipResult } from "./account-roster";
+import type { FriendRecord, SenseType, TrustLevel } from "./types";
+/** The named peer to link, by any of the three handles the owner might supply. An
+ * `agentId` or `did` is a resolvable handle on its own; a bare `name` resolves ONLY by
+ * hitting an existing record (§3.3 — never fabricated). */
+export interface ConnectPeer {
+    agentId?: string;
+    did?: string;
+    name?: string;
+}
+export interface ConnectAgentsInput {
+    peer: ConnectPeer;
+    /** The management sense the connect_to arrived through (the MCP boundary supplies
+     * `local` for the owner-only stdio path; a network transport its real senseType). */
+    senseType: SenseType;
+    /** The PRE-COMPUTED account-roster membership for the `closed` branch (the caller
+     * runs evaluateAccountMembership). Absent ⇒ no membership proven. */
+    membership?: AccountMembershipResult;
+    /** The trust to link the peer at. Own-fleet linked agents default to `family`. */
+    trustLevel?: TrustLevel;
+}
+export interface ConnectAgentsDeps {
+    /** The control-plane audit sink. Absent ⇒ the link is made but no audit is appended
+     * (no-sink no-op, mirroring setFriendTrust / the onboard_agent seat). */
+    audit?: AuditSink;
+    /** WHO performed the connect (e.g. "owner:stdio"). */
+    actor: string;
+    /** WHENCE — the origin sense string stamped on the audit (e.g. "stdio"). */
+    originSense: string;
+}
+export type ConnectStatus = "connected" | "needs_handle_or_introduction" | "downgraded";
+export type ConnectResult = {
+    ok: true;
+    status: "connected";
+    record: FriendRecord;
+} | {
+    ok: false;
+    status: "needs_handle_or_introduction";
+} | {
+    ok: false;
+    status: "downgraded";
+    downgrade: ConnectAuthorization;
+};
+/**
+ * Link a named peer into the calling agent's store from the owner's vantage. Composes:
+ * authority gate (authorizeConnect) → disambiguation (resolvePeer, never fabricates) →
+ * the introduce effect (upsertAgentPeer at the linked trust, default family) → the
+ * action:"connect" control-plane audit (mirroring the onboard_agent seat). A downgrade
+ * authorization makes NO link and writes NO audit (mirrors setFriendTrust's no-audit
+ * early return); an unresolvable bare name returns needs_handle_or_introduction.
+ */
+export declare function connectAgents(store: FriendStore, input: ConnectAgentsInput, deps: ConnectAgentsDeps): Promise<ConnectResult>;

package/dist/connect.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectAgents = connectAgents;
+// connectAgents — the `connect_to` library fn (brick 8, greenfield).
+//
+// The owner's first-class capability to link one of their OWN agents into the calling
+// agent's fleet (introduce a target peer INTO this store). It is the single entry point
+// for "go connect to @peer" (spec §3.2), gated to a management sense (§3.1) and audited
+// (§3.4). Brick 8 is greenfield in friends — there is NO trust-gate.ts to patch (that
+// lives in ouroboros); this composes the new authority predicate (connect-authority.ts)
+// with the increment-1 roster-pre-computed membership + the increment-1 control-plane
+// audit (AuditSink / action:"connect").
+//
+// MENTAL MODEL (resolves "A↔B on separate stores"): A and B live in SEPARATE
+// stores/processes (own-fleet on two machines), so a single connectAgents call operates
+// on ONE store — it upserts the named peer as an agent-peer at the linked trust + audits
+// action:"connect". The bidirectional A↔B link is the owner running the introduction on
+// EACH side (the LOCAL proof drives both). The fn does NOT reach across stores.
+//
+// CORE-CLEAN: the `membership` arrives PRE-COMPUTED via `input` (the caller runs
+// evaluateAccountMembership against the increment-1 roster surface), so this module
+// imports NO a2a-client / libsodium. The lint enforces the direction.
+//
+// DISAMBIGUATION HONESTY (spec §3.3): given a bare name with no resolvable handle/DID
+// and no record hit, connectAgents returns a structured "need a handle or an
+// introduction" result rather than FABRICATING a target. An agentId or a did IS an
+// owner-supplied/resolved handle; a bare name resolves ONLY by matching an existing
+// record (the BUILT FileFriendStore name-fallback scan) — never invented.
+const observability_1 = require("./observability");
+const connect_authority_1 = require("./connect-authority");
+const agent_peer_1 = require("./agent-peer");
+const friend_lookup_1 = require("./friend-lookup");
+const identity_1 = require("./identity");
+/** Read an agent record's join-key agentId — the durable `a2a.agentId`, falling back
+ * to the `a2a-agent` externalId. Returns undefined when the record names no agentId
+ * (e.g. a human record), so it can never be linked as an agent target. */
+function agentIdOf(record) {
+    return record.agentMeta?.a2a?.agentId ?? record.externalIds.find((e) => e.provider === "a2a-agent")?.externalId;
+}
+/** Resolve the peer to a usable handle WITHOUT fabricating one (§3.3):
+ *  - `agentId` present → it IS the handle; enrich from any existing record by it.
+ *  - else `did` present → resolve an existing record by did (the did is the handle);
+ *    a did with no matching record does NOT resolve (needs a handle/introduction).
+ *  - else `name` present → match an existing record by case-insensitive name (the
+ *    FileFriendStore name-fallback semantics, made store-agnostic via listAll); a bare
+ *    name with no hit does NOT resolve.
+ *  - else (nothing) → does not resolve.
+ * Returns null when the peer cannot be resolved to a real handle. */
+async function resolvePeer(store, peer) {
+    if (peer.agentId) {
+        const existing = await store.findByExternalId("a2a-agent", peer.agentId);
+        return { agentId: peer.agentId, existing: existing ?? undefined, name: peer.name ?? existing?.name ?? peer.agentId };
+    }
+    if (peer.did) {
+        const existing = await (0, friend_lookup_1.findFriendByDid)(store, peer.did);
+        if (!existing)
+            return null;
+        const agentId = agentIdOf(existing);
+        if (!agentId)
+            return null;
+        return { agentId, existing, name: peer.name ?? existing.name };
+    }
+    if (peer.name) {
+        const existing = await findByName(store, peer.name);
+        if (!existing)
+            return null;
+        const agentId = agentIdOf(existing);
+        if (!agentId)
+            return null;
+        return { agentId, existing, name: peer.name };
+    }
+    return null;
+}
+/** Case-insensitive name match over the store's records (the §3.3 name-fallback scan,
+ * made store-agnostic by using listAll). Returns the first match, or null. A store with
+ * no listAll yields null (best-effort, never a throw). */
+async function findByName(store, name) {
+    if (typeof store.listAll !== "function")
+        return null;
+    const all = await store.listAll();
+    const lower = name.toLowerCase();
+    return all.find((f) => f.name.toLowerCase() === lower) ?? null;
+}
+/**
+ * Link a named peer into the calling agent's store from the owner's vantage. Composes:
+ * authority gate (authorizeConnect) → disambiguation (resolvePeer, never fabricates) →
+ * the introduce effect (upsertAgentPeer at the linked trust, default family) → the
+ * action:"connect" control-plane audit (mirroring the onboard_agent seat). A downgrade
+ * authorization makes NO link and writes NO audit (mirrors setFriendTrust's no-audit
+ * early return); an unresolvable bare name returns needs_handle_or_introduction.
+ */
+async function connectAgents(store, input, deps) {
+    // 1) Authority FIRST. A downgrade never commits inline (no link, no audit).
+    const authorization = (0, connect_authority_1.authorizeConnect)({ senseType: input.senseType, membership: input.membership });
+    if (authorization.decision === "downgrade") {
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.connect_downgraded",
+            message: "connect_to downgraded to confirm-prompt (not committed inline)",
+            meta: { senseType: input.senseType, reason: authorization.reason },
+        });
+        return { ok: false, status: "downgraded", downgrade: authorization };
+    }
+    // 2) Disambiguation honesty — resolve the peer to a real handle, never fabricate.
+    const resolved = await resolvePeer(store, input.peer);
+    if (!resolved) {
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.connect_needs_handle",
+            message: "connect_to could not resolve the peer to a handle — needs a handle or an introduction",
+            meta: {},
+        });
+        return { ok: false, status: "needs_handle_or_introduction" };
+    }
+    // 3) The introduce effect — upsert the peer as an agent-peer at the linked trust.
+    // Own-fleet linked agents default to family; the level is overridable. Pass any
+    // existing a2a coords through so the upsert preserves them (incl. a legacy a2a.did).
+    //
+    // ┌─ PRE-CONDITION before any non-local / networked `controlContext` is ever wired ──────┐
+    // │ (security review inc-2 findings 2-3): the `family` DEFAULT here, and the fact that    │
+    // │ the TARGET is upserted with no roster constraint (TOFU — see resolvePeer above),      │
+    // │ are correct + safe ONLY because the authority gate (authorizeConnect) only COMMITs    │
+    // │ on the owner-only `local` stdio sense today (no wire constructs a non-`local`         │
+    // │ controlContext). BEFORE any non-`local`/networked controlContext is ever wired, the   │
+    // │ `connect` commit MUST add target-side roster verification (the target did must ALSO   │
+    // │ be roster-checked, not just TOFU-upserted) AND validate the caller-supplied           │
+    // │ `trustLevel` against the authority decision. The current `family` default +           │
+    // │ unconstrained target are safe only for the owner-only-stdio path.                     │
+    // └──────────────────────────────────────────────────────────────────────────────────────┘
+    const trustLevel = input.trustLevel ?? "family";
+    const a2a = resolved.existing?.agentMeta?.a2a;
+    const record = await (0, agent_peer_1.upsertAgentPeer)(store, {
+        name: resolved.name,
+        agentId: resolved.agentId,
+        trustLevel,
+        ...(a2a ? { a2a } : {}),
+    });
+    // 4) The control-plane audit — ONE action:"connect" record through the wired sink
+    // (mirrors the onboard_agent seat writer). No sink ⇒ a clean no-op.
+    if (deps.audit) {
+        const targetDid = (0, identity_1.resolveAgentIdentity)(record.agentMeta).did;
+        const auditRecord = {
+            action: "connect",
+            targetId: record.id,
+            ...(targetDid !== undefined ? { targetDid } : {}),
+            level: trustLevel,
+            actor: deps.actor,
+            originSense: deps.originSense,
+            ts: record.updatedAt,
+        };
+        await deps.audit.append(auditRecord);
+    }
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.connect_linked",
+        message: "connect_to linked an own-fleet agent peer",
+        meta: { targetId: record.id, level: trustLevel },
+    });
+    return { ok: true, status: "connected", record };
+}

package/dist/coordination.d.ts

@@ -1,7 +1,7 @@
 import type { MissionStore } from "./mission-store";
 import type { FriendStore } from "./store";
 import type { GrantStore } from "./grant-store";
-import type { AgentAttribution, CoordinationIntent, MissionRecord, TrustLevel } from "./types";
+import type { AgentAttribution, CoordinationIntent, MissionRecord, MissionTaskSpec, TrustLevel } from "./types";
 import type { ConsentPolicy } from "./consent";
 import type { AgentVerifier } from "./verifier";
 /** The cross-agent coordination envelope (brick 5). Names the subject by JOIN KEY
@@ -25,6 +25,12 @@ export interface CoordinationEnvelope {
      * PROPOSES as the new assignee (named by join-key agentId). The receiver's own
      * accept is what actually sets it — a handoff never forces an assignment. */
     proposedAssignee?: AgentAttribution;
+    /** The delegation task-spec, meaningful ONLY on intent:"request" (gap-1, p11 inc2):
+     * the structured "what B is being asked to do", carrying the minted `requestId` the
+     * result-return correlates against. Present only when the producer was given a task on
+     * a request; a plain coordination request omits it (back-compat). Mirrors how
+     * `proposedAssignee` rides only `handoff`. */
+    task?: MissionTaskSpec;
     /** Opaque, verifier-specific proof slot. The TOFU verifier ignores it. */
     proof?: string;
     issuedAt: string;
@@ -43,6 +49,16 @@ export interface PrepareCoordinationInput {
     /** This agent's own join-key agentId — the asserter of the first-party log entry
      * (and, on an `accept`, the assignee it claims for itself). */
     selfAgentId: string;
+    /** Optional delegation task-spec (gap-1, p11 inc2), meaningful ONLY on
+     * intent:"request". When provided on a request, the producer MINTS a `requestId`,
+     * stamps the full `MissionTaskSpec` on the envelope's `task`, and records it first-party
+     * under the mission's `delegations[requestId]`. Ignored on any non-request intent.
+     * Absent ⇒ a plain coordination request, byte-identical to today (back-compat). */
+    task?: {
+        summary: string;
+        details?: string;
+        inputs?: Record<string, string>;
+    };
     /** Optional proof to stamp on the envelope (for a non-TOFU recipient verifier). */
     proof?: string;
 }