@nelsonlongxiang/dsh-open-a2a-net 0.6.24 → 0.6.25

package/lib/exposure-store.js

@@ -0,0 +1,82 @@
+/**
+ * #19 exposure tiers (ruling final, D3/D4): per-session visibility tier on
+ * the A2A network — 'linked' (the default floor: visible to linked callers
+ * per the W3 gate) or 'fleet' (the member's voluntary opt-UP: visible to
+ * any fleet peer). v1 carries exactly these two tiers (D5: no private
+ * residue below linked).
+ *
+ * D3: joins default to linked — existing members transfer automatically
+ * (tier absence IS linked, so no migration is needed); a member may raise
+ * itself to fleet and lower itself back (fleet is an opt-up, linked is the
+ * floor, never a ceiling decision taken from the member).
+ *
+ * D4 (成文, zero group knobs): a GROUP's visibility equals its STRICTEST
+ * member tier — one linked member keeps the group linked-level. The rule
+ * binds every future group surface (canvas listing, fleet feeds); v1 has
+ * no group-level tier API by design, so the rule needs no enforcement
+ * seam yet.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/exposure-store
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export class ExposureStore {
+    path;
+    tiers = new Map();
+    /**
+     * @param path - persistence file (`<dsh-home>/a2a/exposure.json`); empty = no persistence.
+     */
+    constructor(path) {
+        this.path = path;
+        if (this.path === '')
+            return;
+        if (!existsSync(this.path))
+            return;
+        try {
+            const snapshot = JSON.parse(readFileSync(this.path, 'utf8'));
+            const tiers = snapshot?.tiers;
+            if (tiers === undefined || typeof tiers !== 'object')
+                return;
+            for (const [id, tier] of Object.entries(tiers)) {
+                if (tier === 'fleet')
+                    this.tiers.set(id, 'fleet'); // linked is the absence default
+            }
+        }
+        catch {
+            // A corrupt store is not fatal: everyone degrades to linked (the default floor).
+        }
+    }
+    /**
+     * The session's tier — 'linked' unless explicitly raised to 'fleet'
+     * (D3: existing members transfer as linked automatically).
+     */
+    tierOf(id) {
+        return this.tiers.get(id) === 'fleet' ? 'fleet' : 'linked';
+    }
+    /**
+     * Set the session's tier. Members may opt up to fleet and back down to
+     * linked; there is no tier below linked (D5) and no group-level knob
+     * (D4 — group visibility derives from the strictest member).
+     */
+    setTier(id, tier) {
+        if (tier === 'fleet')
+            this.tiers.set(id, 'fleet');
+        else
+            this.tiers.delete(id);
+        this.persist();
+    }
+    persist() {
+        if (this.path === '')
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            const tiers = {};
+            for (const [id, tier] of this.tiers)
+                tiers[id] = tier;
+            const snapshot = { tiers };
+            writeFileSync(this.path, JSON.stringify(snapshot), { mode: 0o600 });
+        }
+        catch {
+            // An unwritable home must not break tier changes; memory-only degradation.
+        }
+    }
+}

package/lib/index.js

@@ -33,6 +33,7 @@ import { decodeSessionLog, extractTranscript, TRANSCRIPT_DEFAULT_LIMIT, TRANSCRI
 import { LayoutStore } from "./layout-store.js";
 import { fileURLToPath } from 'node:url';
 import { JoinedSessions } from "./joined-store.js";
+import { ExposureStore } from "./exposure-store.js";
 import { TeamMembershipStore } from "./team-store.js";
 import { PeerStore } from "./peer-store.js";
 import { SelfReferralFilter } from "./self-suppress.js";
@@ -125,6 +126,15 @@ export const Config = s.object({
      * the legacy whole-store basis (fleet migration window).
      */
     referralTeamResolution: s.boolean().default(false),
+    /**
+     * #19 D2 (ruling final, owner-level knob): how much of a session team's
+     * activity EXCERPT the card face publishes in sessionTeams descriptions.
+     * 'full' (default) keeps the verbatim tail excerpt; 'masked' truncates
+     * to a shape-only prefix; 'off' omits the description field entirely.
+     * Titles and team handles stay in every tier — the knob is the excerpt,
+     * not the listing.
+     */
+    exposureExcerpt: s.union(['full', 'masked', 'off']).default('full'),
     /**
      * gh#9+gh#10 OriginClaim window: absent envelopes still walk N3 during
      * the window (counted as legacyInbound); closing it rejects them like
@@ -545,6 +555,11 @@ export function apply(ctx, config) {
     // host restarts silently dropped every join. The store remounts the node
     // whenever the Agent comes back, until the user leaves.
     const joinedSessions = new JoinedSessions(join(home, 'a2a', 'joined.json'));
+    // #19 D3/D4: per-session exposure tiers — 'linked' floor (the absence
+    // default, so existing members transfer automatically) with a voluntary
+    // 'fleet' opt-up. D4 (成文): group visibility = strictest member tier;
+    // v1 ships no group-level knob by design.
+    const exposureStore = new ExposureStore(join(home, 'a2a', 'exposure.json'));
     // S2: node-declared team memberships — the roster half of the
     // team-roster iteration. Joins ride the allowlist-gated tools; the store
     // is the durable declaration the card publishes and the state face reads.
@@ -1033,6 +1048,19 @@ export function apply(ctx, config) {
         }
         return 'no activity yet';
     }
+    /**
+     * #19 D2: apply the owner-level excerpt knob to a session-team
+     * description at the card face. 'full' keeps the verbatim excerpt;
+     * 'masked' reduces to a shape-only prefix (16 chars — enough to
+     * recognize, not enough to read); 'off' omits the field entirely.
+     */
+    function exposureDescription(description) {
+        if (config.exposureExcerpt === 'off')
+            return undefined;
+        if (config.exposureExcerpt === 'masked')
+            return `${description.slice(0, 16)}${description.length > 16 ? '…' : ''}`;
+        return description;
+    }
     /**
      * Join one live top-level session: its team dispatches direct routes and
      * rides the announced card from this moment.
@@ -1388,6 +1416,9 @@ export function apply(ctx, config) {
                             joined: sessionNodes.has(String(agent.id)),
                             live: true,
                             teams: [...teamMemberships.teamsOf(String(agent.id))],
+                            // #19 D3: the session's exposure tier (linked floor /
+                            // fleet opt-up) — readable on the state face.
+                            exposure: exposureStore.tierOf(String(agent.id)),
                             ...(canvasStore.teamsOf(String(agent.id)).length > 0 ? { canvasTeams: [...canvasStore.teamsOf(String(agent.id))] } : {}),
                             ...(groupOf(String(agent.id)) !== undefined ? { group: groupOf(String(agent.id)) } : {}),
                         }));
@@ -1904,7 +1935,17 @@ export function apply(ctx, config) {
                         void named;
                     };
                     const claim = await verifyOriginClaim(req);
-                    const named = claim.ok;
+                    // W3 (#18 half-side, 0.6.25): a VERIFIED envelope proves the
+                    // caller holds a real node key — it does not prove a relationship
+                    // with THIS host. The full card (sessionTeams/rosters =
+                    // collaboration facts) additionally requires a LINK (same-host
+                    // membership, canvas remote ref, or the caller's own card seeding
+                    // us — see callerLinkedToThisHost). An unlinked-but-verified
+                    // stranger gets the MINIMAL discovery card, #18 X1's shape.
+                    // Interaction with the OriginClaim narrowing: the caller is a
+                    // bare zone; linkage judges that zone face against our canvas
+                    // remote refs, joined handles, and the caller card's peers.
+                    const named = claim.ok && callerLinkedToThisHost(claim.caller, claim.ok ? claim.callerUrl : '', claim.ok ? claim.card : undefined);
                     // gh#7 G1 (review-seat R2 ruling): the card serves two faces.
                     // A NAMED caller — ?caller_session= or the X-A2A-Caller header in
                     // the zone or zone/id8 shape — gets the FULL card. An anonymous
@@ -1943,11 +1984,19 @@ export function apply(ctx, config) {
                             return false;
                         }
                     };
+                    // #19 D2: the excerpt knob rides the served-fresh rows at the
+                    // card face — live nodes (nodeMetadataOf description) and cold
+                    // rows alike. 'off' omits the field (undefined drops out).
+                    const exposureRow = (team, meta) => {
+                        const { description, ...rest } = meta;
+                        const excerpt = exposureDescription(description ?? '');
+                        return { team, ...rest, ...(excerpt !== undefined ? { description: excerpt } : {}) };
+                    };
                     const sessionTeams = [
-                        ...[...sessionNodes.values()].filter(isJoinedNode).map(agent => ({ team: sessionTeamOf(agent), ...nodeMetadataOf(agent) })),
+                        ...[...sessionNodes.values()].filter(isJoinedNode).map(agent => exposureRow(sessionTeamOf(agent), nodeMetadataOf(agent))),
                         ...joinedSessions.list()
                             .filter(id => !liveRoots.has(id) && isArchived?.(id) !== true)
-                            .map(id => ({ team: `${config.team}/${id8(id)}`, name: `${session}-${id8(id)}`, description: 'cold — not loaded; routing here wakes the session' })),
+                            .map(id => exposureRow(`${config.team}/${id8(id)}`, { name: `${session}-${id8(id)}`, description: 'cold — not loaded; routing here wakes the session' })),
                     ];
                     const memberships = teamMemberships.list().flatMap(entry => entry.teams.map(team => ({ node: `${config.team}/${id8(entry.session)}`, team })));
                     const body = JSON.stringify({
@@ -2528,15 +2577,168 @@ ${message}`;
         if (card.team !== caller) {
             return { ok: false, reason: 'not-derivable' };
         }
-        return { ok: true, caller };
+        return { ok: true, caller, callerUrl, card };
+    }
+    /**
+     * W3 (#18 half-side): is a VERIFIED caller LINKED to this host? Key
+     * possession proves the caller is a real host; it says nothing about a
+     * relationship with US. The full card carries collaboration facts
+     * (sessionTeams/rosters), so it additionally requires a link:
+     *   1. same-host membership — the caller's card URL origin equals OUR
+     *      card URL origin (the loopback self-fetch face: true self is an
+     *      ORIGIN equality; zone-name equality carries no identity in a
+     *      single-zone fleet), or one of our session pseudo-handles;
+     *   2. a canvas remote ref — the EXACT handle only (#19 D1, ruling
+     *      final: the zone-sibling variant was a blanket fallback that any
+     *      one ref opened to a whole zone's hosts in single-zone fleets; the
+     *      operator names THAT node, that node links);
+     *   3. BILATERAL seeding (review M1 fix): our config.peers contains the
+     *      caller's URL **and** the caller's card (fetched fresh during
+     *      verification) carries our origin among its peers — both
+     *      operators made the gesture, each on their own side. The single-
+     *      sided card-claims variant was a hole the reviewer's adversarial
+     *      probe walked through (one config.peers line → full card with
+     *      zero commitment from us): peers is an unsigned served-fresh
+     *      field, exactly the self-description trust class N3/V5 abolished.
+     *      Our operator's config anchors; the card shadow corroborates.
+     */
+    function callerLinkedToThisHost(caller, callerUrl, callerCard) {
+        // Basis 1, same-host membership (review second-round M-fix): "self" is
+        // an ORIGIN equality, not a zone-name equality. `caller === config.team`
+        // granted unconditionally in a single-zone fleet (the deployment
+        // reality: every host named 'dsh') — any verified caller naming the
+        // shared zone string was "us". True self is the loopback self-fetch
+        // face: the caller's card URL origin equals OUR card URL origin.
+        try {
+            if (callerUrl !== '' && new URL(callerUrl).origin === new URL(ownCardUrl).origin)
+                return true;
+        }
+        catch { /* malformed callerUrl — falls through to the record bases */ }
+        for (const id of joinedSessions.list()) {
+            if (`${config.team}/${id8(id)}` === caller)
+                return true;
+        }
+        // #19 D1 (ruling final): canvas remote refs admit by EXACT HANDLE only.
+        // The zone-sibling variant (`refZone === zone`) was a blanket fallback —
+        // in a single-zone fleet any one ref linked the whole zone face, the
+        // exact trust shape the exposure ruling removed. Exact handle in, the
+        // operator named THAT node.
+        for (const name of canvasStore.list()) {
+            for (const ref of canvasStore.remoteMembersOf(name)) {
+                if (ref === caller)
+                    return true;
+            }
+        }
+        // Basis 3, BILATERAL (review M1 fix): OUR config.peers seeds a URL
+        // whose origin matches the caller's card URL, AND the caller's card
+        // reciprocates by carrying OUR origin among its peers — both
+        // operators made the gesture, each on their own side. The single-
+        // sided card-claims variant was a hole the reviewer's adversarial
+        // probe walked through (one config.peers line on the CALLER → full
+        // card with zero commitment from us): peers is an unsigned
+        // served-fresh field, exactly the self-description trust class
+        // N3/V5 abolished. Our operator's own config anchors; the card
+        // shadow only corroborates.
+        if (callerCard !== undefined && ownCardUrl !== '') {
+            const ourOrigin = new URL(ownCardUrl).origin;
+            const callerOrigin = new URL(callerUrl).origin;
+            const weSeedThem = config.peers.some(peer => {
+                try {
+                    return new URL(peer).origin === callerOrigin;
+                }
+                catch {
+                    return false;
+                }
+            });
+            const theySeedUs = (callerCard.peers ?? []).some(peer => {
+                try {
+                    return new URL(peer).origin === ourOrigin;
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (weSeedThem && theySeedUs)
+                return true;
+        }
+        return false;
     }
     /* ── Inbound admission shared by the peer faces (/a2a/direct,
-       /a2a/log): caller_session is the protocol contract. Anonymous is
-       refused, and admission is decided by THIS host's own records — never
-       by the caller's self-description (gh#7 N3, V3/V5): not its
-       caller_session spelling, not its own card's team claims, not
-       first-contact defaults. Returns the refusal detail, or undefined
-       when admissible. */
+       /a2a/log) and — since the boundary-hardening wave (W1) — the LOCAL
+       dispatch candidate: caller_session is the protocol contract.
+       Anonymous is refused, and admission is decided by THIS host's own
+       records — never by the caller's self-description (gh#7 N3, V3/V5).
+       Returns the refusal detail, or undefined when admissible. */
+    /**
+     * W1/W2 shared-team admission core (pure over the host's stores): a
+     * same-zone zone/id8 caller passes when it holds a team this host's
+     * records also hold. The caller's basis is its roster declarations UNION
+     * its canvas memberships (W2②: canvas teammates share a team by being in
+     * the team — the roster is not the only link record); the host's basis is
+     * the routable set (bare zone, joined handles, canvas names) union other
+     * sessions' declarations. Used by both the inbound faces and the local
+     * dispatch candidate so the two paths can never diverge.
+     */
+    function sameZoneSharedTeamRefusal(caller) {
+        const declared = new Set();
+        let callerSessionId;
+        for (const entry of teamMemberships.list()) {
+            if (`${config.team}/${id8(entry.session)}` === caller) {
+                callerSessionId = entry.session;
+                for (const t of entry.teams)
+                    declared.add(t);
+            }
+        }
+        // W2②: canvas membership is a link record too — the caller's session
+        // sitting in a canvas team declares that team as much as a roster line.
+        if (callerSessionId === undefined) {
+            for (const id of joinedSessions.list()) {
+                if (`${config.team}/${id8(id)}` === caller) {
+                    callerSessionId = id;
+                    break;
+                }
+            }
+        }
+        if (callerSessionId !== undefined) {
+            for (const name of canvasStore.teamsOf(callerSessionId))
+                declared.add(canvasTeamOf(name));
+        }
+        const routable = new Set([config.team]);
+        for (const id of joinedSessions.list())
+            routable.add(`${config.team}/${id8(id)}`);
+        for (const name of canvasStore.list())
+            routable.add(canvasTeamOf(name));
+        const otherLocalDeclarations = new Set();
+        for (const entry of teamMemberships.list()) {
+            if (`${config.team}/${id8(entry.session)}` === caller)
+                continue;
+            for (const t of entry.teams)
+                otherLocalDeclarations.add(t);
+        }
+        const shared = [...declared].some(t => routable.has(t) || otherLocalDeclarations.has(t));
+        if (shared)
+            return undefined;
+        return declared.size === 0
+            ? `caller "${caller}" declares no team membership on this host's roster — a teamless node has no network (S3 phase-3 admission). Declare a shared team on both ends, or route through a teamed member.`
+            : `caller "${caller}" declares teams [${[...declared].join(', ')}] — none is routable on this node (shared-team admission). Declare a shared team on both ends, or route through a teamed member.`;
+    }
+    /**
+     * W1: does a caller label fall under the joined-face admission gate? The
+     * zone/id8 shape with THIS zone names a joined session node — the face
+     * the boundary-hardening wave closes. The initiator face (bare node
+     * team) and foreign-zone labels are judged elsewhere (F1b host-face
+     * rules; the foreign branch below) and stay untouched.
+     */
+    const joinedFaceCallerShape = /^[a-z0-9-]+\/[0-9a-f]{8}$/i;
+    function joinedFaceAdmissionRefusal(callerSession) {
+        if (callerSession === undefined || callerSession === '')
+            return undefined;
+        if (!joinedFaceCallerShape.test(callerSession))
+            return undefined;
+        if (callerSession.slice(0, callerSession.indexOf('/')) !== config.team)
+            return undefined;
+        return sameZoneSharedTeamRefusal(callerSession);
+    }
     function a2aCallerRefusal(caller) {
         if (!config.teamScopeRouting)
             return undefined;
@@ -2551,33 +2753,10 @@ ${message}`;
         if (zoneShaped) {
             const callerZone = caller.slice(0, caller.indexOf('/'));
             if (callerZone === config.team) {
-                // Same-zone handle: judged by this host's own roster — the
-                // operator-established link record for local nodes.
-                const declared = new Set();
-                for (const entry of teamMemberships.list()) {
-                    if (`${config.team}/${id8(entry.session)}` === caller)
-                        for (const t of entry.teams)
-                            declared.add(t);
-                }
-                const routable = new Set([config.team]);
-                for (const id of joinedSessions.list())
-                    routable.add(`${config.team}/${id8(id)}`);
-                for (const name of canvasStore.list())
-                    routable.add(canvasTeamOf(name));
-                const otherLocalDeclarations = new Set();
-                for (const entry of teamMemberships.list()) {
-                    if (`${config.team}/${id8(entry.session)}` === caller)
-                        continue;
-                    for (const t of entry.teams)
-                        otherLocalDeclarations.add(t);
-                }
-                const shared = [...declared].some(t => routable.has(t) || otherLocalDeclarations.has(t));
-                if (!shared) {
-                    return declared.size === 0
-                        ? `caller "${caller}" declares no team membership on this host's roster — a teamless node has no network (S3 phase-3 admission). Declare a shared team on both ends, or route through a teamed member.`
-                        : `caller "${caller}" declares teams [${[...declared].join(', ')}] — none is routable on this node (shared-team admission). Declare a shared team on both ends, or route through a teamed member.`;
-                }
-                return undefined;
+                // Same-zone handle: the W1/W2 shared admission core — roster
+                // declarations UNION canvas memberships against this host's
+                // records (canvas names are link records too; see the helper).
+                return sameZoneSharedTeamRefusal(caller);
             }
             // Foreign-zone handle (N3/N4): admitted ONLY through this host's
             // operator-established cross-host links — a canvas remote member ref
@@ -3877,6 +4056,51 @@ ${message}`;
             return { ok: true, team, id, teams: [...teamMemberships.teamsOf(id)] };
         },
     }));
+    ctx.tools.register(defineTool({
+        name: 'a2a_exposure',
+        description: '#19 exposure tiers: set THIS session\'s network visibility. \'linked\' (the default '
+            + 'floor) — visible to linked callers per the card-face link gate; \'fleet\' — a voluntary '
+            + 'opt-UP making the session\'s team visible to any fleet peer. Members may raise and lower '
+            + 'their own tier freely; nothing exists below linked (no private tier in v1), and group '
+            + 'visibility always derives from the strictest member (no group knobs). Requires the '
+            + 'session to be joined to the network.',
+        parameters: {
+            tier: { type: 'string', enum: ['linked', 'fleet'], required: true, description: 'The exposure tier to set for this session.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ok: { type: 'boolean', required: true },
+                    id: { type: 'string' },
+                    tier: { type: 'string' },
+                    error: { type: 'string', description: 'Refusal reason when ok is false (not joined, or no agent context).' },
+                },
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: value.ok === true
+                        ? `Session ${String(value.id)} exposure tier set to ${String(value.tier)}`
+                        : `Exposure refused: ${String(value.error)}`,
+                }],
+        },
+        presentCall: () => ({ card: 'generic', title: 'A2A exposure tier', kind: 'other', rawInput: null }),
+        execute: async (args, exec) => {
+            const agent = exec.agent;
+            if (agent === undefined) {
+                return { ok: false, error: 'no agent context — the exposure tier is a per-session fact; call from a session' };
+            }
+            const id = String(agent.id);
+            if (!joinedSessions.has(id)) {
+                return { ok: false, error: 'session is not joined to the A2A network — join first (the sidebar control or the host join route)' };
+            }
+            const tier = args.tier === 'fleet' ? 'fleet' : 'linked';
+            exposureStore.setTier(id, tier);
+            logger.info(`a2a: ${id8(id)} exposure tier -> ${tier}`);
+            return { ok: true, id, tier };
+        },
+    }));
     ctx.tools.register(defineTool({
         name: 'a2a_report',
         description: 'Report a task or status to this host\'s A2A network — the ONE ingress a session WITHOUT network '
@@ -4452,6 +4676,18 @@ ${message}`;
      */
     async function dispatchLocalCandidate(team, message, callerSession, contextId, signal, asyncMode = false, taskIdFromCaller, callbackAddress) {
         const webServer = ctx.get('webServer');
+        // W1 (boundary hardening): the local in-process candidate is an
+        // admission seam like any other — a JOINED session (zone/id8 caller
+        // face) must clear the same shared-team admission /a2a/direct applies,
+        // or a teamless local node could route to any session team by riding
+        // the cheapest path. The initiator face (bare node team) and
+        // foreign-zone labels are NOT gated here (F1b host-face rules, R-C
+        // pending) — only the joined face closes.
+        const joinedRefusal = joinedFaceAdmissionRefusal(callerSession);
+        if (joinedRefusal !== undefined) {
+            recordActivity('out', team, callerSession ?? 'local', false);
+            return { ok: false, error: joinedRefusal, code: -32000 };
+        }
         const canvasName = parseCanvasTeamName(team);
         let teamIsLocal = team === config.team
             || resolveAgentForTeam(team) !== undefined

package/lib/types/exposure-store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * #19 exposure tiers (ruling final, D3/D4): per-session visibility tier on
+ * the A2A network — 'linked' (the default floor: visible to linked callers
+ * per the W3 gate) or 'fleet' (the member's voluntary opt-UP: visible to
+ * any fleet peer). v1 carries exactly these two tiers (D5: no private
+ * residue below linked).
+ *
+ * D3: joins default to linked — existing members transfer automatically
+ * (tier absence IS linked, so no migration is needed); a member may raise
+ * itself to fleet and lower itself back (fleet is an opt-up, linked is the
+ * floor, never a ceiling decision taken from the member).
+ *
+ * D4 (成文, zero group knobs): a GROUP's visibility equals its STRICTEST
+ * member tier — one linked member keeps the group linked-level. The rule
+ * binds every future group surface (canvas listing, fleet feeds); v1 has
+ * no group-level tier API by design, so the rule needs no enforcement
+ * seam yet.
+ * @module @nelsonlongxiang/dsh-open-a2a-net/exposure-store
+ */
+/** The two v1 tiers (D5: nothing below linked exists). */
+export type ExposureTier = 'linked' | 'fleet';
+/** The persisted tier document (whole-file read/write, small by design). */
+export interface ExposureSnapshot {
+    readonly tiers?: Readonly<Record<string, ExposureTier>>;
+}
+export declare class ExposureStore {
+    private readonly path;
+    private tiers;
+    /**
+     * @param path - persistence file (`<dsh-home>/a2a/exposure.json`); empty = no persistence.
+     */
+    constructor(path: string);
+    /**
+     * The session's tier — 'linked' unless explicitly raised to 'fleet'
+     * (D3: existing members transfer as linked automatically).
+     */
+    tierOf(id: string): ExposureTier;
+    /**
+     * Set the session's tier. Members may opt up to fleet and back down to
+     * linked; there is no tier below linked (D5) and no group-level knob
+     * (D4 — group visibility derives from the strictest member).
+     */
+    setTier(id: string, tier: ExposureTier): void;
+    private persist;
+}

package/lib/types/index.d.ts

@@ -103,6 +103,11 @@ export interface Config {
      * self-asserted already-linked name must not pass on shape alone).
      */
     readonly originClaimWindow: boolean;
+    /**
+     * #19 D2: card-face sessionTeams excerpt exposure — 'full' | 'masked'
+     * | 'off' (owner-level; default full). See the schema comment.
+     */
+    readonly exposureExcerpt: 'full' | 'masked' | 'off';
     /**
      * Override for the OriginClaim callerUrl anchor. Loopback-bound hosts
      * behind a pocket tunnel must name the card URL peers can actually

package/package.json

@@ -1,218 +1,218 @@
-{
-  "name": "@nelsonlongxiang/dsh-open-a2a-net",
-  "version": "0.6.24",
-  "description": "Open A2A network plugin for DeepSeek Harness: signed agent cards, decentralized peer/zone discovery, direct routing model tools, and joinable session nodes with a sidebar control",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
-    "./client": {
-      "types": "./lib/types/client/index.d.ts",
-      "default": "./lib/client.js"
-    },
-    "./card": {
-      "types": "./lib/types/card.d.ts",
-      "default": "./lib/card.js"
-    },
-    "./receipt": {
-      "types": "./lib/types/receipt.d.ts",
-      "default": "./lib/receipt.js"
-    },
-    "./transport-caps": {
-      "types": "./lib/types/transport-caps.d.ts",
-      "default": "./lib/transport-caps.js"
-    },
-    "./a2a-client": {
-      "types": "./lib/types/a2a-client.d.ts",
-      "default": "./lib/a2a-client.js"
-    },
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "assets/nexusDist",
-    "assets/stageDist",
-    "images",
-    "README_zh.md",
-    "cordis.patch.yml",
-    "README.md",
-    "nexus-stage/src",
-    "nexus-stage/scripts",
-    "nexus-stage/package.json",
-    "nexus-stage/package-lock.json",
-    "nexus-stage/tsconfig.json",
-    "nexus-stage/vite.config.ts"
-  ],
-  "packageManager": "pnpm@11.28.5",
-  "engines": {
-    "pnpm": ">=11.24 <12"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "platform": "web",
-      "inject": [
-        "@deepseek-ai/dsh-client-runtime",
-        "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-ui-slots",
-        "@deepseek-ai/dsh-client-ui-sidebar"
-      ]
-    }
-  },
-  "scripts": {
-    "prepare": "pnpm build",
-    "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && tsdown && node scripts/copy-skill.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
-    "test": "vitest run",
-    "test:unit": "vitest run tests/unit",
-    "test:wire": "vitest run tests/wire",
-    "test:mesh": "vitest run tests/mesh",
-    "test:live": "vitest run tests/live",
-    "test:build-layout": "vitest run tests/gates/build-layout.spec.ts",
-    "verify:nexus": "node scripts/verify-nexus-ci.mjs && npm --prefix nexus-stage run build && npm --prefix nexus-stage run test && git diff --exit-code -- assets/nexusDist/assets && git diff --ignore-cr-at-eol --exit-code -- assets/nexusDist/index.html",
-    "verify": "pnpm typecheck && pnpm build && pnpm test && pnpm test:build-layout && pnpm verify:nexus"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": ">=4.0.1",
-    "@deepseek-ai/cordis-plugin-loader": ">=1.0.2",
-    "@deepseek-ai/cordis-plugin-timer": ">=1.1.3",
-    "@deepseek-ai/dsh-agent": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-api-session-controller": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-client-locale": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-client-runtime": ">=0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-home-paths": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-invariants": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-llm": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-title": ">=0.1.7-alpha.2",
-    "@deepseek-ai/dsh-tools": ">=0.1.7-alpha.2",
-    "@deepseek-ai/schemastery": ">=3.18.1",
-    "react": "^18.2.0"
-  },
-  "peerDependenciesMeta": {
-    "@deepseek-ai/cordis": {
-      "optional": true
-    },
-    "@deepseek-ai/cordis-plugin-loader": {
-      "optional": true
-    },
-    "@deepseek-ai/cordis-plugin-timer": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-agent": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-client-locale": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-client-runtime": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-client-ui-primitives": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-client-ui-sidebar": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-client-ui-slots": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-api-session-controller": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-home-paths": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-host-webserver": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-invariants": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-llm": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-session": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-session-persistence": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-session-title": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-tools": {
-      "optional": true
-    },
-    "@deepseek-ai/schemastery": {
-      "optional": true
-    },
-    "react": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-client-store": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-scope": "0.0.1-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-util-code-language": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-util-workspace-path": "0.1.2-alpha.2",
-    "@shikijs/langs": "^4.5.0",
-    "@testing-library/react": "^16.3.0",
-    "@types/node": "^24.13.3",
-    "@types/react": "~18.3.1",
-    "@types/react-dom": "^18.3.7",
-    "anser": "^2.3.5",
-    "clsx": "^2.1.1",
-    "diff": "^9.0.0",
-    "jsdom": "^26.1.0",
-    "katex": "^0.19.0",
-    "lightningcss": "^1.33.0",
-    "mdast-util-from-markdown": "^2.1.0",
-    "mdast-util-gfm": "^3.1.0",
-    "mdast-util-math": "^3.0.0",
-    "micromark-core-commonmark": "^2.0.4",
-    "micromark-extension-gfm": "^3.0.0",
-    "micromark-extension-math": "^3.1.0",
-    "micromark-factory-space": "^2.1.0",
-    "micromark-util-character": "^2.1.1",
-    "micromark-util-classify-character": "^2.0.1",
-    "micromark-util-sanitize-uri": "^2.0.1",
-    "micromark-util-symbol": "^2.0.1",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "shiki": "^4.5.0",
-    "simple-icons": "^16.35.0",
-    "tsdown": "0.22.2",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.8"
-  },
-  "pnpm": {
-    "overrides": {
-      "@deepseek-ai/cordis": "4.0.5",
-      "@deepseek-ai/cordis-plugin-loader": "1.0.5"
-    }
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://gitee.com/NelsonLongXiang/dsh-open-a2a-net.git"
-  }
-}
+{
+  "name": "@nelsonlongxiang/dsh-open-a2a-net",
+  "version": "0.6.25",
+  "description": "Open A2A network plugin for DeepSeek Harness: signed agent cards, decentralized peer/zone discovery, direct routing model tools, and joinable session nodes with a sidebar control",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./card": {
+      "types": "./lib/types/card.d.ts",
+      "default": "./lib/card.js"
+    },
+    "./receipt": {
+      "types": "./lib/types/receipt.d.ts",
+      "default": "./lib/receipt.js"
+    },
+    "./transport-caps": {
+      "types": "./lib/types/transport-caps.d.ts",
+      "default": "./lib/transport-caps.js"
+    },
+    "./a2a-client": {
+      "types": "./lib/types/a2a-client.d.ts",
+      "default": "./lib/a2a-client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "assets/nexusDist",
+    "assets/stageDist",
+    "images",
+    "README_zh.md",
+    "cordis.patch.yml",
+    "README.md",
+    "nexus-stage/src",
+    "nexus-stage/scripts",
+    "nexus-stage/package.json",
+    "nexus-stage/package-lock.json",
+    "nexus-stage/tsconfig.json",
+    "nexus-stage/vite.config.ts"
+  ],
+  "packageManager": "pnpm@11.28.5",
+  "engines": {
+    "pnpm": ">=11.24 <12"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ]
+    }
+  },
+  "scripts": {
+    "prepare": "pnpm build",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && tsdown && node scripts/copy-skill.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:wire": "vitest run tests/wire",
+    "test:mesh": "vitest run tests/mesh",
+    "test:live": "vitest run tests/live",
+    "test:build-layout": "vitest run tests/gates/build-layout.spec.ts",
+    "verify:nexus": "node scripts/verify-nexus-ci.mjs && npm --prefix nexus-stage run build && npm --prefix nexus-stage run test && git diff --exit-code -- assets/nexusDist/assets && git diff --ignore-cr-at-eol --exit-code -- assets/nexusDist/index.html",
+    "verify": "pnpm typecheck && pnpm build && pnpm test && pnpm test:build-layout && pnpm verify:nexus"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.1",
+    "@deepseek-ai/cordis-plugin-loader": ">=1.0.2",
+    "@deepseek-ai/cordis-plugin-timer": ">=1.1.3",
+    "@deepseek-ai/dsh-agent": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-api-session-controller": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-runtime": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-home-paths": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-invariants": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-llm": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session-title": ">=0.1.7-alpha.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.7-alpha.2",
+    "@deepseek-ai/schemastery": ">=3.18.1",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/cordis-plugin-loader": {
+      "optional": true
+    },
+    "@deepseek-ai/cordis-plugin-timer": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-runtime": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-primitives": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-sidebar": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-api-session-controller": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-home-paths": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-invariants": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session-title": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-store": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-scope": "0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-util-code-language": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-util-workspace-path": "0.1.2-alpha.2",
+    "@shikijs/langs": "^4.5.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^24.13.3",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "^18.3.7",
+    "anser": "^2.3.5",
+    "clsx": "^2.1.1",
+    "diff": "^9.0.0",
+    "jsdom": "^26.1.0",
+    "katex": "^0.19.0",
+    "lightningcss": "^1.33.0",
+    "mdast-util-from-markdown": "^2.1.0",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-math": "^3.0.0",
+    "micromark-core-commonmark": "^2.0.4",
+    "micromark-extension-gfm": "^3.0.0",
+    "micromark-extension-math": "^3.1.0",
+    "micromark-factory-space": "^2.1.0",
+    "micromark-util-character": "^2.1.1",
+    "micromark-util-classify-character": "^2.0.1",
+    "micromark-util-sanitize-uri": "^2.0.1",
+    "micromark-util-symbol": "^2.0.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "shiki": "^4.5.0",
+    "simple-icons": "^16.35.0",
+    "tsdown": "0.22.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8"
+  },
+  "pnpm": {
+    "overrides": {
+      "@deepseek-ai/cordis": "4.0.5",
+      "@deepseek-ai/cordis-plugin-loader": "1.0.5"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/NelsonLongXiang/dsh-open-a2a-net.git"
+  }
+}

package/lib/types/client.d.ts

@@ -1,73 +0,0 @@
-/**
- * In-process decentralized A2A client: the outbound peer surface — verified
- * agent-card fetches (discovery) and direct routes to a peer's
- * `/a2a/direct` endpoint. Timing and fetch seams are constructor-injected so
- * tests drive them without a network.
- * @module @nelsonlongxiang/dsh-open-a2a-net/client
- */
-import type { A2aPeerCard, A2aRouteResult } from './types.ts';
-/** One-shot delayed callback returning its disposer. */
-export type A2aSchedule = (callback: () => void, delayMs: number) => () => void;
-/** Minimal fetch face; the first HTTP-level failure rejects. */
-export type A2aFetch = (url: string, init: {
-    readonly method: 'GET' | 'POST';
-    readonly headers: Record<string, string>;
-    readonly body?: string;
-    readonly signal?: AbortSignal;
-}) => Promise<{
-    readonly ok: boolean;
-    readonly status: number;
-    readonly text: () => Promise<string>;
-}>;
-/** Constructor facts; every seam is explicit so tests inject doubles. */
-export interface A2aClientOptions {
-    /** `X-API-Key` value sent on peer requests; empty omits the header. */
-    readonly apiKey: string;
-    /** This node's caller label stamped on outbound routes. */
-    readonly sessionId: string;
-    /** Delayed-callback seam (HTTP timeouts). */
-    readonly schedule: A2aSchedule;
-    /** HTTP seam. */
-    readonly fetch: A2aFetch;
-}
-/**
- * The A2A peer client. One instance serves the whole fiber's outbound
- * card fetches and direct routes; it owns no connection state.
- */
-export declare class A2aClient {
-    private readonly options;
-    /** @param options - resolved caller facts and injected seams. */
-    constructor(options: A2aClientOptions);
-    private headers;
-    private http;
-    /**
-     * Fetch one peer's agent card (discovery): team, session, capabilities.
-     * The card is verified at parse — unsigned, badly signed, or expired cards
-     * are rejected here, so a stale peer disappears from discovery without any
-     * background cleanup.
-     * @param baseUrl - the peer's base URL.
-     * @returns the verified card, or `undefined` when unreachable, malformed, or rejected.
-     */
-    fetchCard(baseUrl: string): Promise<A2aPeerCard | undefined>;
-    /**
-     * Extract the reply text from a route result member: the wire carries a
-     * plain string, a `{text}` object, or anything else JSON-encoded.
-     * @param inner - the raw `result` member of a route response.
-     * @param fallback - what a nullish member encodes as.
-     * @returns the reply text.
-     */
-    private replyText;
-    /**
-     * Route directly to a peer node's `/a2a/direct` endpoint. The peer steers
-     * the message into its live agent (or the named session team's agent) and
-     * answers within its own final-reply budget.
-     * @param baseUrl - the peer's base URL.
-     * @param team - target team name (the peer's own or a session team).
-     * @param message - request text.
-     * @param contextId - context id from a prior reply, for multi-turn.
-     * @param signal - caller cancellation.
-     * @param callerSession - caller label overriding the node's label (the calling session's node label).
-     * @returns the canonical route result (success or explicit failure).
-     */
-    routeDirect(baseUrl: string, team: string, message: string, contextId?: string, signal?: AbortSignal, callerSession?: string): Promise<A2aRouteResult>;
-}