super-dsh 0.1.6 → 0.1.9

package/superd-hub/dist/a2a-service.js

@@ -0,0 +1,980 @@
+/**
+ * A2A conversation service (mesh P3 Task 2): the conversation registry plus
+ * create / resume / inject / completion-capture against a target agent's
+ * session plane, reached through an injected `gatewayFor(addr)` resolver
+ * (local in-process gateway or remote wire — the service cannot tell).
+ *
+ * Pure service core, no cordis dependencies: assembly (completion cb → reply
+ * delivery) is Task 3's layer. Every session-plane call is built from the
+ * Task 1 vocabulary (`wire-endpoints.ts`): endpoint constants + payload
+ * mirrors + `wireArgsOf()` — never hand-rolled payloads.
+ *
+ * Frame vocabulary for completion capture (upstream anchors,
+ * `upstream/deepseek-harness` @ dsh-v0.1.7-rc.1):
+ *   - follow frames: `SessionFollowFrame` union
+ *     packages/api/session-controller/src/types.ts:550 — opening
+ *     `{type:'snapshot', records}` then ordered `{type:'event', event}`
+ *     entries; `assistant-stream` frames are live partials (ignored — final
+ *     text comes from the durable `assistant/message` events).
+ *   - event entries: `SessionEventEntry` types.ts:424, `SessionWireEvent`
+ *     {type, seq, time, data} types.ts:436.
+ *   - turn lifecycle: `SessionEventMap` 'turn/start' | 'turn/end'
+ *     packages/core/session/src/types.ts:288–297; `turn/end.data.reason.kind`
+ *     = TurnEndReasonMap kinds (types.ts:201 — completed/aborted/blocked/
+ *     error/max-tokens/interrupted/forked).
+ *   - final text: `assistant/message` events carry `{turn, step, message,
+ *     stream, interrupted?}` (packages/core/session/src/index.ts:286,
+ *     settlement shape :675; `interrupted === true` marks a replaced attempt,
+ *     client/sessions/assistant-stream.ts:189). Text blocks of
+ *     `message.content` (`TextBlock` packages/llm/llm/src/types.ts:61) are
+ *     joined with '\n\n'.
+ *   - send correlation: `session/prompt`'s client-minted `requestId`
+ *     (`SessionPromptRequest` types.ts:331) is persisted on the accepted
+ *     user message as `data.source.rpcId` (source kind `user-rpc`,
+ *     types.ts:196–199) — the stream matcher keys on it.
+ *
+ * Controller rulings baked in (2026-09-28):
+ *   - receipt outcome: 'delivered' on EVERY successful prompt submission
+ *     (D28: end-to-end delivery complete); 'failed' carries an error body.
+ *   - completion correlation is BY TURN via the requestId arming above: one
+ *     `turn/end` fires the cb exactly once (debounce-free, order-safe on the
+ *     session log's contiguous seq space); the requestId-armed subscription
+ *     auto-disposes after its turn fires, so a send observes at most one
+ *     completion. Snapshot-replayed history never re-fires a fired turn.
+ *   - stop('session'): upstream has NO session-close RPC (Task 1 finding —
+ *     `WIRE.sessionClose === undefined`); the scope degrades to turnCancel
+ *     and the result reports `{scope:'turn-only', reason}` so callers can
+ *     notice the degradation (the upstream analogues live on the workspace
+ *     namespace and stay out of the session plane).
+ */
+import { randomUUID } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { EnvelopeError } from './envelope.js';
+import { A2aAddressError, A2A_TITLE_PLACEHOLDER, A2A_NOTICE_SUMMARY_MAX, normalizeA2aTitle, postA2aEnvelope, a2aAddressOf } from './a2a-wire.js';
+import { ensureSelf, listRemotes, mintShortId as mintMachineId } from './machines.js';
+import { cookieOf } from './mesh-link.js';
+import { WIRE, wireArgsOf } from './wire-endpoints.js';
+// compat re-export (postoffice R1): the class moved to the protocol layer
+// (a2a-wire.ts) so the wire helpers can classify with it; every existing
+// consumer importing it from this module keeps compiling unchanged.
+export { A2aAddressError };
+function conversationsPath(home) {
+    return join(home, 'superd', 'a2a-conversations.json');
+}
+function isConversationRow(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const r = v;
+    return (typeof r.shortId === 'string' && r.shortId !== '' &&
+        typeof r.machine === 'string' && r.machine !== '' &&
+        typeof r.agent === 'string' && r.agent !== '' &&
+        typeof r.sessionId === 'string' && r.sessionId !== '' &&
+        (r.title === undefined || typeof r.title === 'string') &&
+        (r.hostAgent === undefined || typeof r.hostAgent === 'string') &&
+        (r.initiatorSession === undefined || typeof r.initiatorSession === 'string') &&
+        (r.channelUsed === undefined || r.channelUsed === true) &&
+        (r.lastSentAt === undefined || typeof r.lastSentAt === 'number') &&
+        (r.lastOutput === undefined || typeof r.lastOutput === 'string') &&
+        (r.lastOutputAt === undefined || typeof r.lastOutputAt === 'number') &&
+        typeof r.createdAt === 'number' && typeof r.lastActivityAt === 'number');
+}
+/** Read the registry; a missing or unreadable/corrupt file degrades to empty (never throws). */
+export function loadConversations(home) {
+    let raw;
+    try {
+        raw = readFileSync(conversationsPath(home), 'utf8');
+    }
+    catch {
+        return { conversations: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { conversations: [] };
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return { conversations: [] };
+    const list = parsed['conversations'];
+    if (!Array.isArray(list))
+        return { conversations: [] };
+    return { conversations: list.filter(isConversationRow) };
+}
+/** Persist the registry: recursive mkdir, tmp write, chmod 0600, atomic rename (machines.ts discipline). */
+export function saveConversations(home, file) {
+    if (!Array.isArray(file.conversations)) {
+        throw new TypeError('a2a: save rejected — file must be {conversations: []}');
+    }
+    for (const r of file.conversations) {
+        if (!isConversationRow(r)) {
+            throw new TypeError('a2a: save rejected — every row needs shortId/machine/agent/sessionId/createdAt/lastActivityAt');
+        }
+    }
+    const dir = join(home, 'superd');
+    mkdirSync(dir, { recursive: true });
+    const target = conversationsPath(home);
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, target);
+}
+/** Mint core: strip the optional leading `session-`, take the first 6 chars of the
+ * base, collision-lengthen 6→8→10… (step 2). Shared by the fresh-mint path and the
+ * one-time registry migration so both produce identical ids. */
+function mintShortIdOf(sessionId, taken) {
+    const stripped = sessionId.startsWith('session-') ? sessionId.slice('session-'.length) : sessionId;
+    const base = stripped === '' ? sessionId : stripped;
+    for (let len = 6; len < base.length; len += 2) {
+        const candidate = base.slice(0, len);
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    if (!taken.has(base))
+        return base;
+    throw new Error(`a2a: short-id space exhausted for session ${sessionId}`);
+}
+/**
+ * shortId mint (D2 fix): DSH session ids are `session-<uuid>`, so slicing the
+ * raw id only ever captures the constant prefix (the live registry degenerated
+ * to "session-", "session-3", …). Strip the prefix, mint the first 6 chars of
+ * the uuid part, collision-lengthen 6→8→10… (step 2, spec §11). Ids without the
+ * prefix (older/foreign spellings) mint from the whole id the same way. A
+ * re-seen sessionId keeps its row's shortId (stable across restarts); stored
+ * shortIds are reserved as taken — DEGENERATE ones are re-minted once by
+ * {@link migrateConversations}, all others stay verbatim forever.
+ */
+export function shortIdFor(sessionId, rows) {
+    const existing = rows.find((r) => r.sessionId === sessionId);
+    if (existing)
+        return existing.shortId;
+    return mintShortIdOf(sessionId, new Set(rows.map((r) => r.shortId)));
+}
+/**
+ * Degenerate-pattern predicate (D2 migration): a stored shortId that still
+ * carries the `session-` prefix AND whose remainder is shorter than the new
+ * mint length — exactly the ids the old prefix-slicing bug produced. Such ids
+ * carry (almost) no information and teach peers to echo garbage.
+ */
+export function isDegenerateShortId(shortId) {
+    return shortId.startsWith('session-') && shortId.length < 'session-'.length + 6;
+}
+/**
+ * One-time registry migration (D2 amended, review 2026-09-28): rows matching
+ * the degenerate pattern are re-minted with the current algorithm and written
+ * back; non-degenerate rows are never touched. Peers still holding an old
+ * degenerate id in their context is accepted collateral — the registry holds
+ * test data today, which is the cheapest migration window there will ever be.
+ * @returns the re-minted rows (empty when nothing needed migrating).
+ */
+export function migrateConversations(home) {
+    const rows = loadConversations(home).conversations;
+    if (!rows.some((r) => isDegenerateShortId(r.shortId)))
+        return [];
+    const taken = new Set(rows.filter((r) => !isDegenerateShortId(r.shortId)).map((r) => r.shortId));
+    const minted = new Map();
+    for (const row of rows) {
+        if (!isDegenerateShortId(row.shortId))
+            continue;
+        const shortId = mintShortIdOf(row.sessionId, taken);
+        taken.add(shortId);
+        minted.set(row.sessionId, shortId);
+    }
+    const next = rows.map((r) => (minted.has(r.sessionId) ? { ...r, shortId: minted.get(r.sessionId) } : r));
+    saveConversations(home, { conversations: next });
+    return next.filter((r) => minted.has(r.sessionId));
+}
+// ---------------------------------------------------------------- envelopes
+/**
+ * THE teaching envelope — one template constant (D20 v3, 2026-09-29: the
+ * SINGLE merged text, no variants). Filled with the INITIATOR's identity
+ * (machine-agent address = the write-back target), the conversation title,
+ * the body, and the shortId a superd-hub tool addresses. Tail = the user's
+ * 2026-09-29 redline, four short paragraphs, each carrying one load:
+ * provenance + channel-only principle / heterogeneity disclosure (tool
+ * availability genuinely differs per runtime — this is what stops a
+ * tool-less model from hunting for one) / how+when to send (sending does
+ * not end the turn) / the fallback, phrased from the RECEIVER's operational
+ * truth ("the hub receive no hub message" — intentionally or prevented;
+ * wording per user ruling 0.1.7-h: the receiver is the hub, the message
+ * class is a hub message). The "if available" conditional is evaluated by
+ * the MODEL against its own tool
+ * list; never pre-select variants on unknowable runtime state. Never a
+ * separate user prompt (the OMP 20-tool-call incident).
+ */
+export const A2A_MESSAGE_TEMPLATE = 'A2A message from {machine}-{agent} (conversation "{title}"):\n\n{message}\n\nThis conversation is initiated through superd-hub by the sender. The sender sees only what arrives through this conversation.\n\nAs superd-hub hosts various kinds of agent runtimes, integration into each runtime and superd-hub tool availability in each runtime session might differ.\n\nTo reply, send a message back: with a superd-hub tool, if available, {action:"send", agent:"{machine}-{agent}", conversationId:"{shortId}", message:"…"}. You can send at any point, more than once — sending does not end your turn.\n\nIf the hub receive no hub message from you (intentionally or whatever situation prevents so), your last output at this turn\'s end is delivered to the sender as your reply.';
+/** Title shown when the conversation has none. */
+export const A2A_UNTITLED = '(untitled)';
+/**
+ * Render the teaching envelope for one send — a SINGLE pass over the template
+ * (injection fix, 2026-09-28): each placeholder is expanded exactly once from
+ * the fields, and user-supplied values (title, message) are never re-scanned,
+ * so a title containing the literal `{shortId}` or `{message}` lands verbatim
+ * instead of being expanded by a later replaceAll round.
+ */
+export function renderA2aEnvelope(fields) {
+    const title = fields.title === undefined || fields.title === '' || fields.title === A2A_TITLE_PLACEHOLDER ? A2A_UNTITLED : fields.title;
+    return A2A_MESSAGE_TEMPLATE.replace(/\{(machine|agent|title|shortId|message)\}/g, (_match, key) => {
+        switch (key) {
+            case 'machine': return fields.machine;
+            case 'agent': return fields.agent;
+            case 'title': return title;
+            case 'shortId': return fields.shortId;
+            default: return fields.message;
+        }
+    });
+}
+/** Bounded unread buffer size per initiator session. */
+export const A2A_BUFFER_MAX = 32;
+/** D28: the sender's synchronous receipt window. If the end-to-end wire has not settled by then the hub answers `accepted` and lets the SAME in-flight request finish in the background. */
+export const A2A_SYNC_RECEIPT_MS = 10_000;
+/** D28: the TOTAL wire budget for one send (120s). The POST timeout is set from the request start, so after the 10s synchronous window the SAME in-flight request still has ~110s left to settle; the peer may spend it bringing the runtime up (spawn OR resume — indistinguishable at the process level). */
+export const A2A_WIRE_TOTAL_BUDGET_MS = 120_000;
+/** stop('session') degradation notice — the session plane has no close RPC upstream. */
+export const A2A_NO_SESSION_CLOSE_REASON = 'no session-close endpoint upstream';
+/** stop() idle note — the honest answer when the pre-cancel liveness snapshot showed no live turn (D5). */
+export const A2A_NO_TURN_ACTIVE_NOTE = 'no turn was active';
+function a2aError(code, message, details) {
+    return new EnvelopeError(details === undefined ? { code, message } : { code, message, details });
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Map any thrown error into the receipt error body — an EnvelopeError's wire body passes verbatim. */
+function receiptErrorOf(error) {
+    if (error instanceof EnvelopeError)
+        return { ...error.wire };
+    if (error instanceof Error)
+        return { code: 'gateway/uncaught', message: error.message };
+    return { code: 'gateway/uncaught', message: String(error) };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Fresh non-aborted signal for one-shot rpc calls (T2 exposes no cancellation surface on send/stop). */
+function freshSignal() {
+    return new AbortController().signal;
+}
+/** Map one typed address failure to its wire error body (D7): the error's own
+ * message; the code keeps 'a2a/gateway-unavailable' for the unreachable branch
+ * (today's code) and names the kind otherwise. */
+export function addressErrorBody(error) {
+    return { code: error.kind === 'unreachable' ? 'a2a/gateway-unavailable' : `a2a/${error.kind}`, message: error.message };
+}
+/** (gatewayOrThrow retired in R4 — the send/stop paths route envelopes; the
+ * local resolver is consumed by subscribeCompletion and the ingest assembly.) */
+/** Bound for the stop() liveness read — a healthy session plane answers the first
+ * follow frame in well under a second, even cross-machine; the bound only fires on
+ * a wedged plane, where the cancel RPC itself would stall anyway. */
+const STOP_LIVENESS_TIMEOUT_MS = 3_000;
+/**
+ * D5 turn-liveness read: open the follow stream, replay the FIRST snapshot
+ * frame's records, and report whether a turn is still open (a turn/start not
+ * followed by its turn/end). Read manually (no for-await) and aborted BEFORE
+ * returning — closing an async generator suspended at an await must not gate
+ * the answer (the close promise can reject on abort and would eat the result).
+ * @returns true (a turn is live), false (idle), or undefined when the plane
+ * could not answer (stream death, stream end, no snapshot, read timeout) —
+ * callers treat undefined conservatively: cancel anyway, keep today's shape.
+ */
+export async function turnLivenessOf(gateway, sessionId) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), STOP_LIVENESS_TIMEOUT_MS);
+    try {
+        const request = { address: { kind: 'session', sessionId } }; // no assistantStream — liveness needs no live partials
+        const iterable = await gateway.openWireStream(WIRE.streamOpen, wireArgsOf(WIRE.streamOpen, request), controller.signal);
+        const iterator = (await iterable)[Symbol.asyncIterator]();
+        for (;;) {
+            const next = await iterator.next();
+            if (next.done)
+                return undefined;
+            const frame = next.value;
+            if (!isRecord(frame) || frame['type'] !== 'snapshot')
+                continue;
+            const records = frame['records'];
+            if (!Array.isArray(records))
+                return undefined;
+            let openTurn;
+            for (const record of records) {
+                if (!isRecord(record) || record['type'] !== 'event')
+                    continue;
+                const event = record['event'];
+                if (!isRecord(event) || typeof event['type'] !== 'string')
+                    continue;
+                const data = isRecord(event['data']) ? event['data'] : {};
+                if (event['type'] === 'turn/start' && typeof data['turn'] === 'number')
+                    openTurn = data['turn'];
+                else if (event['type'] === 'turn/end' && data['turn'] === openTurn)
+                    openTurn = undefined;
+            }
+            controller.abort(); // snapshot consumed — drop the stream now
+            return openTurn !== undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        controller.abort();
+        clearTimeout(timer);
+    }
+}
+/**
+ * One session-plane RPC through the gateway: payload via `wireArgsOf`,
+ * `{ok:false,error}` rethrown as a typed EnvelopeError (error body verbatim),
+ * transport throws pass through untouched (they are already gateway/* typed).
+ */
+export async function sessionRpc(gateway, endpoint, request) {
+    const result = await gateway.dispatchRpc(endpoint, wireArgsOf(endpoint, request), freshSignal());
+    if (!isRecord(result) || typeof result['ok'] !== 'boolean') {
+        throw a2aError('a2a/bad-result', `a2a: ${endpoint} returned a non-envelope result`);
+    }
+    if (result['ok'] === true)
+        return result['value'];
+    const err = result['error'];
+    const wire = isRecord(err) && typeof err['code'] === 'string' && typeof err['message'] === 'string'
+        ? { code: err['code'], message: err['message'], ...(err['details'] === undefined ? {} : { details: err['details'] }) }
+        : { code: 'gateway/bad-response', message: `a2a: ${endpoint} rejected with a malformed error body` };
+    throw new EnvelopeError(wire);
+}
+/** Text blocks of a message content array joined with '\n\n' ("" when none). */
+function assistantTextOf(content) {
+    if (!Array.isArray(content))
+        return '';
+    const texts = [];
+    for (const part of content) {
+        if (isRecord(part) && part['type'] === 'text' && typeof part['text'] === 'string')
+            texts.push(part['text']);
+    }
+    return texts.join('\n\n');
+}
+/**
+ * The completion watcher behind `subscribeCompletion` (extracted verbatim in
+ * postoffice R3): one follow stream over the addressed session, turn-text
+ * reduction, requestId arming, one resubscribe, snapshot-history fire.
+ * Same contract as the service method — every fired completion is one cb,
+ * armed subscriptions auto-dispose after their turn fires.
+ */
+export function subscribeSessionCompletion(source, cb, opts = {}) {
+    const controller = new AbortController();
+    const state = {
+        openTurn: undefined,
+        lastText: new Map(),
+        armedSeen: false,
+        armedTurn: undefined,
+        fired: new Set(),
+        completedHistorical: new Map(),
+    };
+    let disposed = false;
+    const dispose = () => {
+        disposed = true;
+        controller.abort();
+    };
+    const followRequest = {
+        address: { kind: 'session', sessionId: source.sessionId },
+        assistantStream: true,
+    };
+    const fire = (turn, reason) => {
+        state.fired.add(turn);
+        cb({
+            conversationId: source.conversationId,
+            sessionId: source.sessionId,
+            turn,
+            reason,
+            text: state.lastText.get(turn)?.text ?? '',
+        });
+        if (opts.requestId !== undefined)
+            dispose();
+    };
+    const applyEvent = (event, live) => {
+        if (!isRecord(event) || typeof event['type'] !== 'string')
+            return;
+        const seq = typeof event['seq'] === 'number' ? event['seq'] : Number.MAX_SAFE_INTEGER;
+        const data = isRecord(event['data']) ? event['data'] : {};
+        switch (event['type']) {
+            case 'turn/start':
+                if (typeof data['turn'] === 'number')
+                    state.openTurn = data['turn'];
+                break;
+            case 'user/message': {
+                const sourceRec = isRecord(data['source']) ? data['source'] : undefined;
+                if (opts.requestId !== undefined && !state.armedSeen && sourceRec?.['rpcId'] === opts.requestId) {
+                    state.armedSeen = true;
+                    state.armedTurn = state.openTurn;
+                }
+                break;
+            }
+            case 'assistant/message': {
+                if (data['interrupted'] === true)
+                    break; // replaced attempt — the real settlement follows
+                const turn = data['turn'];
+                if (typeof turn !== 'number')
+                    break;
+                const message = isRecord(data['message']) ? data['message'] : undefined;
+                const text = assistantTextOf(message?.['content']);
+                const prior = state.lastText.get(turn);
+                if (prior === undefined || seq >= prior.seq)
+                    state.lastText.set(turn, { text, seq });
+                break;
+            }
+            case 'turn/end': {
+                const turn = data['turn'];
+                if (typeof turn !== 'number')
+                    break;
+                if (state.openTurn === turn)
+                    state.openTurn = undefined;
+                const reason = isRecord(data['reason']) && typeof data['reason']['kind'] === 'string'
+                    ? data['reason']['kind']
+                    : 'unknown';
+                if (!live) {
+                    state.completedHistorical.set(turn, reason);
+                    break;
+                }
+                const shouldFire = opts.requestId === undefined
+                    ? !state.fired.has(turn)
+                    : state.armedSeen && !state.fired.has(turn) && (state.armedTurn === undefined || state.armedTurn === turn);
+                if (shouldFire)
+                    fire(turn, reason);
+                break;
+            }
+            default:
+                break; // merge-extensible event names are not ours to interpret
+        }
+    };
+    /** After a snapshot: an armed request whose turn already completed in history fires from history (prompt-accepted-before-subscribe race). */
+    const maybeFireFromHistory = () => {
+        if (opts.requestId === undefined)
+            return;
+        if (!state.armedSeen || state.armedTurn === undefined)
+            return;
+        if (state.fired.has(state.armedTurn) || !state.completedHistorical.has(state.armedTurn))
+            return;
+        fire(state.armedTurn, state.completedHistorical.get(state.armedTurn) ?? 'unknown');
+    };
+    const handleFrame = (frame) => {
+        if (!isRecord(frame))
+            return;
+        if (frame['type'] === 'snapshot') {
+            const records = frame['records'];
+            if (Array.isArray(records)) {
+                for (const record of records) {
+                    if (isRecord(record) && record['type'] === 'event')
+                        applyEvent(record['event'], false);
+                }
+            }
+            maybeFireFromHistory();
+        }
+        else if (frame['type'] === 'event') {
+            applyEvent(frame['event'], true);
+        }
+        // 'assistant-stream' frames are live partials — final text is durable
+    };
+    const onDeath = (error, attempt) => {
+        if (disposed || controller.signal.aborted)
+            return;
+        if (attempt === 0) {
+            open(1); // exactly one resubscribe
+            return;
+        }
+        opts.onError?.({
+            code: 'a2a/stream-dead',
+            message: `a2a: completion stream for ${source.conversationId} died twice — ${messageOf(error)}`,
+        });
+    };
+    const open = (attempt) => {
+        let iterable;
+        try {
+            iterable = source.gateway.openWireStream(WIRE.streamOpen, wireArgsOf(WIRE.streamOpen, followRequest), controller.signal);
+        }
+        catch (error) {
+            onDeath(error, attempt);
+            return;
+        }
+        void (async () => {
+            try {
+                const stream = await iterable;
+                for await (const frame of stream) {
+                    if (disposed)
+                        return;
+                    handleFrame(frame);
+                }
+                onDeath(new Error('stream ended'), attempt); // a live follow stream never ends while the session lives
+            }
+            catch (error) {
+                onDeath(error, attempt);
+            }
+        })();
+    };
+    open(0);
+    return dispose;
+}
+// ---------------------------------------------------------------- service
+export function createA2aService(deps) {
+    const now = deps.now ?? Date.now;
+    const alog = deps.log;
+    // degenerate row exists; after the first pass the registry stays clean.
+    migrateConversations(deps.home);
+    const bufferByInitiator = new Map();
+    const persist = (conversations) => {
+        saveConversations(deps.home, { conversations });
+    };
+    const findRow = (conversationId) => {
+        const rows = loadConversations(deps.home).conversations;
+        return rows.find((r) => r.shortId === conversationId || r.sessionId === conversationId);
+    };
+    /**
+     * R4: record the INITIATOR row for a conversation the envelope routing
+     * just created/receipted. One row per conversation: a row already bound to
+     * the shortId (the mirror row a SELF-hosted conversation adopted on our
+     * own ingest) covers the id — never a duplicate. Title normalized at mint
+     * (D17); the initiator's session id is persisted for peer write-backs.
+     */
+    const recordInitiatorRow = (shortId, to, sessionId, title, initiator) => {
+        const rows = loadConversations(deps.home).conversations;
+        // D20 self-route: the single MIRROR row (hostAgent set, initiator local)
+        // IS the initiator row too — backfill the write-back address instead of
+        // returning (a cross-machine mirror row never reaches here: its
+        // conversation was initiated on the peer's hub, not ours).
+        const existing = rows.find((r) => r.shortId === shortId || r.sessionId === sessionId);
+        if (existing !== undefined) {
+            if (existing.hostAgent !== undefined && existing.machine === selfM4() && existing.initiatorSession === undefined) {
+                persist(rows.map((r) => (r.sessionId === existing.sessionId ? { ...r, initiatorSession: initiator.sessionId } : r)));
+            }
+            return;
+        }
+        rows.push({
+            shortId,
+            machine: to.machine,
+            agent: to.id,
+            sessionId,
+            title,
+            initiatorSession: initiator.sessionId,
+            createdAt: now(),
+            lastActivityAt: now(),
+        });
+        persist(rows);
+    };
+    /** Bump the activity stamp; optionally backfill the initiator session on INITIATOR rows and self-route MIRROR rows (never on cross-machine mirror rows). */
+    const touchRow = (row, initiatorSession) => {
+        const rows = loadConversations(deps.home).conversations;
+        const idx = rows.findIndex((r) => r.sessionId === row.sessionId);
+        if (idx === -1)
+            return;
+        // D17: only the activity stamp moves — a later write path never touches title.
+        const backfill = initiatorSession !== undefined &&
+            (rows[idx].hostAgent === undefined || rows[idx].machine === selfM4());
+        rows[idx] = {
+            ...rows[idx],
+            lastActivityAt: now(),
+            ...(backfill ? { initiatorSession } : {}),
+        };
+        persist(rows);
+    };
+    const selfM4 = () => ensureSelf(deps.home, 'local').id;
+    /** D20: mark the hosted peer as channel-capable for this conversation — monotonic latch + send watermark. */
+    const markChannelUsed = (row) => {
+        const rows = loadConversations(deps.home).conversations;
+        const idx = rows.findIndex((r) => r.sessionId === row.sessionId);
+        if (idx === -1)
+            return;
+        rows[idx] = { ...rows[idx], channelUsed: true, lastSentAt: now() };
+        persist(rows);
+    };
+    /** Mint a fresh conversation id — random 6 over [a-z0-9], collision-checked against our registry (the initiator mints; the peer adopts verbatim). */
+    const mintConversationId = () => mintMachineId(6, loadConversations(deps.home).conversations.map((r) => r.shortId));
+    /** The wire `from` of one initiator identity (full-length session id, D6). */
+    const originOf = (initiator) => ({ machine: initiator.machine, agent: initiator.agent, sessionId: initiator.sessionId });
+    /**
+     * R4 THE ROUTER: one envelope, two legs — target machine === self → the
+     * SAME ingest handler the HTTP endpoint calls (in-process short-circuit;
+     * protocol-identical by construction); a paired remote → wire POST with
+     * its cookie riding along. Unpaired → the typed unknown-machine failure.
+     */
+    const routeEnvelope = async (envelope, timeoutMs) => {
+        const target = a2aAddressOf(envelope);
+        if (target.machine === selfM4()) {
+            const ingest = deps.ingest?.();
+            if (ingest === undefined) {
+                throw a2aError('a2a/no-ingest', `a2a: envelope for ${target.machine}-${target.id} addresses THIS machine but no ingest is wired (post-office assembly incomplete)`);
+            }
+            return ingest.ingest(envelope);
+        }
+        const machine = listRemotes(deps.home).find((r) => r.id === target.machine);
+        if (machine === undefined) {
+            throw new A2aAddressError('unknown-machine', target);
+        }
+        return postA2aEnvelope(machine.origin, envelope, {
+            cookie: cookieOf(machine.id, deps.home),
+            fetchImpl: deps.fetchImpl,
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        });
+    };
+    /** Map one wire stop receipt back onto the typed result (canonical constants; the ingest emits exactly these). */
+    const mapStopReceipt = (receipt) => {
+        if (receipt.scope === 'turn') {
+            return receipt.stopped
+                ? { scope: 'turn', cancelled: true }
+                : { scope: 'turn', cancelled: false, note: A2A_NO_TURN_ACTIVE_NOTE };
+        }
+        return receipt.stopped
+            ? { scope: 'turn-only', cancelled: true, reason: A2A_NO_SESSION_CLOSE_REASON }
+            : { scope: 'turn-only', cancelled: false, note: A2A_NO_TURN_ACTIVE_NOTE, reason: A2A_NO_SESSION_CLOSE_REASON };
+    };
+    const service = {
+        async send(req, initiator) {
+            const messageId = `a2a-${randomUUID()}`;
+            const fail = (error, sessionId = '', conversationId) => {
+                alog?.('warn', 'send.fail', { code: error.code, conversation: conversationId, message: messageId });
+                return {
+                    outcome: 'failed',
+                    messageId,
+                    ...(conversationId === undefined ? {} : { conversationId }),
+                    sessionId,
+                    error,
+                };
+            };
+            let row;
+            let to = req.to;
+            let writeBack = false;
+            if (req.conversationId !== undefined) {
+                row = findRow(req.conversationId);
+                if (row === undefined) {
+                    return fail({
+                        code: 'a2a/conversation-not-found',
+                        message: `a2a: conversation "${req.conversationId}" is not in the registry — send without conversationId (creates one) or check the id`,
+                    });
+                }
+                // D24/T3: a continuation is addressed by id alone. When the model
+                // omits `agent`, derive the route from the row kind + the caller's
+                // session (the model never states the owner/peer). When it still
+                // passes `agent`, that value is a checked assertion below.
+                // D24/T3 + F2 (0.1.8-c): the route AND the write-back decision are
+                // SESSION facts. `hosted` = this row's session lives HERE at hostAgent;
+                // `callerIsHost` = the caller IS that hosted session (the peer replying
+                // through its own channel). Deriving the write-back from ADDRESS
+                // equality breaks the self-addressed case (row.agent === row.hostAgent),
+                // where the initiator's own continuation looks identical to the host's
+                // and got mis-classified as a peer write-back (echoing the initiator's
+                // own words back at it while the responder received nothing).
+                const hosted = row.hostAgent !== undefined;
+                const callerIsHost = hosted && initiator.sessionId === row.sessionId;
+                if (to === undefined) {
+                    if (callerIsHost) {
+                        // the hosted peer itself replies → write-back to the initiator
+                        to = { machine: row.machine, id: row.agent };
+                    }
+                    else if (hosted && row.initiatorSession !== undefined && row.initiatorSession !== '' && initiator.sessionId === row.initiatorSession) {
+                        // the opener continues → self-route into the hosted session
+                        to = { machine: selfM4(), id: row.hostAgent };
+                    }
+                    else if (!hosted) {
+                        // initiator row → the session lives at the peer
+                        to = { machine: row.machine, id: row.agent };
+                    }
+                    else {
+                        return fail({
+                            code: 'a2a/not-a-party',
+                            message: `a2a: conversation "${row.shortId}" — this session is neither its initiator nor its host, so it cannot act on it`,
+                        }, row.sessionId, row.shortId);
+                    }
+                    alog?.('info', 'send.route-derived', { conversation: row.shortId, to: `${to.machine}-${to.id}` });
+                }
+                // Address consistency by row kind (R4 continuation routing):
+                // mirror rows (hostAgent) are hosted HERE and addressed as
+                // {self, hostAgent}; initiator rows keep today's peer-address check.
+                // D20 WRITE-BACK exception: on a mirror row, addressing the row's
+                // {machine, agent} (the INITIATOR) is the hosted peer using its
+                // channel — the teaching envelope's reply clause. It routes to the
+                // initiator's hub (write-back delivery there), and it SETS THE LATCH:
+                // from this send on, the completion watch never transcribes again.
+                const expected = hosted
+                    ? { machine: selfM4(), id: row.hostAgent }
+                    : { machine: row.machine, id: row.agent };
+                // F2: the write-back is decided by SESSION (only the hosted session
+                // replies), never re-derived from address equality.
+                writeBack = callerIsHost;
+                if (!writeBack && (to.machine !== expected.machine || to.id !== expected.id)) {
+                    return fail({
+                        code: 'a2a/conversation-machine-mismatch',
+                        message: `a2a: conversation "${row.shortId}" belongs to ${expected.machine}-${expected.id}, not ${to.machine}-${to.id}`,
+                    }, row.sessionId, row.shortId);
+                }
+                if (writeBack) {
+                    // The latch is the runtime TRUTH about the peer (it chose the
+                    // channel), set before routing so the completion watch can never
+                    // race it; a routing failure parks/retries without un-latching.
+                    markChannelUsed(row);
+                    alog?.('info', 'send.channel', { conversation: row.shortId, from: `${selfM4()}-${row.hostAgent}`, latch: true });
+                }
+            }
+            if (to === undefined) {
+                return fail({ code: 'a2a/no-target', message: 'a2a: send needs `agent` to open a new conversation' });
+            }
+            // Build the envelope: create mints the conversation id (initiator-side,
+            // random 6); continuation routes by row kind — mirror rows to OUR OWN
+            // ingest (the conversation is hosted here), initiator rows to the
+            // machine/agent the row points at.
+            const from = originOf(initiator);
+            let envelope;
+            // hoisted for the failed-receipt leg below: a failed WRITE-BACK must
+            // still reach the original initiator (0.1.7-h R2 send-failed notice).
+            let writeBackOrigin;
+            if (row === undefined) {
+                envelope = {
+                    kind: 'new-conversation',
+                    to: { machine: to.machine, id: to.id },
+                    conversationId: mintConversationId(),
+                    title: normalizeA2aTitle(req.title),
+                    message: req.message,
+                    from,
+                    messageId,
+                    ...(req.delivery === undefined ? {} : { delivery: req.delivery }),
+                };
+            }
+            else {
+                // (writeBack derives from the continuation block above)
+                // D20: a write-back's `from` is the HOSTED PEER itself (its own
+                // session on this row) — the initiator-side ingest attributes the
+                // reply from this origin, and the self-route ingest recognizes the
+                // shape (from.agent === row.hostAgent) to deliver, never inject.
+                const peerOrigin = writeBack && row.hostAgent !== undefined
+                    ? { machine: selfM4(), agent: row.hostAgent, sessionId: row.sessionId }
+                    : undefined;
+                writeBackOrigin = peerOrigin;
+                const to = peerOrigin !== undefined
+                    ? { machine: row.machine, id: row.agent }
+                    : row.hostAgent !== undefined
+                        ? { machine: selfM4(), id: row.hostAgent }
+                        : { machine: row.machine, id: row.agent };
+                envelope = {
+                    kind: 'message',
+                    to,
+                    conversationId: row.shortId,
+                    message: req.message,
+                    from: peerOrigin ?? from,
+                    messageId,
+                    ...(req.delivery === undefined ? {} : { delivery: req.delivery }),
+                };
+            }
+            // D28/T5: hub-to-hub is a SYNCHRONOUS POST whose response IS the
+            // completion notification — there is no poll surface. We only keep the
+            // SENDER's receipt synchronous within A2A_SYNC_RECEIPT_MS; if the wire has
+            // not settled by then answer `accepted` and let the SAME in-flight request
+            // finish in the background, delivering `delivered`/`undelivered` as a
+            // notice.
+            let syncTimer;
+            const wire = routeEnvelope(envelope, A2A_WIRE_TOTAL_BUDGET_MS).then((a) => ({ ok: true, a }), (error) => ({ ok: false, error }));
+            const raced = await Promise.race([
+                wire,
+                new Promise((resolve) => { syncTimer = setTimeout(() => resolve('sync-timeout'), deps.syncReceiptMs ?? A2A_SYNC_RECEIPT_MS); }),
+            ]);
+            if (syncTimer !== undefined)
+                clearTimeout(syncTimer);
+            if (raced === 'sync-timeout') {
+                const conversationId = envelope.conversationId;
+                void wire.then((settled) => {
+                    const a = settled.ok ? settled.a : undefined;
+                    const delivered = a?.outcome === 'delivered';
+                    if (delivered && row === undefined && a?.sessionId !== undefined && a.sessionId !== '' && a.conversationId !== undefined && a.conversationId !== '') {
+                        recordInitiatorRow(a.conversationId, to, a.sessionId, normalizeA2aTitle(req.title), initiator);
+                    }
+                    const peerMsg = a?.error?.message;
+                    const detail = delivered
+                        ? 'the message reached the peer'
+                        : peerMsg ?? (settled.ok ? 'the peer hub rejected the envelope' : receiptErrorOf(settled.error).message);
+                    const raw = `conversation ${conversationId}: ${delivered ? 'delivered' : 'undelivered'} — ${detail}`;
+                    const notice = {
+                        kind: 'notice',
+                        to: { machine: initiator.machine, agent: initiator.agent, sessionId: initiator.sessionId },
+                        conversation: conversationId,
+                        summary: raw.length > A2A_NOTICE_SUMMARY_MAX ? raw.slice(0, A2A_NOTICE_SUMMARY_MAX - 1) + '…' : raw,
+                        messageId: `a2a-notice-${randomUUID()}`,
+                        sender: { machine: to.machine, agent: to.id },
+                        reason: delivered ? 'delivered' : 'undelivered',
+                    };
+                    alog?.('info', 'send.settled', { conversation: conversationId, outcome: delivered ? 'delivered' : 'undelivered' });
+                    void routeEnvelope(notice).catch((error) => {
+                        alog?.('warn', 'send.settled-notice-fail', { conversation: conversationId, error: messageOf(error) });
+                    });
+                });
+                alog?.('info', 'send.accepted', { conversation: conversationId, message: messageId });
+                return {
+                    outcome: 'accepted',
+                    messageId,
+                    conversationId,
+                    sessionId: '',
+                    note: `the peer hub has not confirmed end-to-end delivery within ${A2A_SYNC_RECEIPT_MS / 1000}s — the SAME in-flight request keeps running (${(A2A_WIRE_TOTAL_BUDGET_MS - A2A_SYNC_RECEIPT_MS) / 1000}s left of a ${A2A_WIRE_TOTAL_BUDGET_MS / 1000}s total budget) and its outcome arrives as a notice; do not resend`,
+                };
+            }
+            let answer;
+            if (!raced.ok) {
+                // D7 layering preserved: typed address failures (unknown-machine,
+                // unreachable transport) and wire faults land as failed receipts —
+                // send never throws.
+                const body = raced.error instanceof A2aAddressError ? addressErrorBody(raced.error) : receiptErrorOf(raced.error);
+                return fail(body, row?.sessionId ?? '', row?.shortId);
+            }
+            answer = raced.a;
+            if (!('outcome' in answer)) {
+                return fail({ code: 'a2a/bad-result', message: 'a2a: envelope routed but the answer was not a send receipt' }, row?.sessionId ?? '', row?.shortId ?? envelope.conversationId);
+            }
+            if (answer.outcome !== 'delivered') {
+                // D1 hardening: a failed receipt that still carries the peer's session
+                // and conversation ids keeps the row addressable — retries resume.
+                if (row === undefined && answer.sessionId !== '' && answer.conversationId !== undefined && answer.conversationId !== '') {
+                    recordInitiatorRow(answer.conversationId, to, answer.sessionId, normalizeA2aTitle(req.title), initiator);
+                }
+                alog?.('warn', 'send.fail', { code: (answer.error ?? { code: 'a2a/remote-failed' }).code, conversation: answer.conversationId ?? row?.shortId, message: messageId });
+                // 0.1.7-h R2 live finding (r2e2eh probe): a FAILED write-back still
+                // bumps the row's send watermark (markChannelUsed ran at send time),
+                // so the peer's completion watch goes quiet — the turn's only artifact
+                // was lost and the original initiator never heard a word. The taxonomy
+                // reserved 'send-failed' for exactly this: mint the notice and route it
+                // to the original initiator (notices deliver without a registry row —
+                // deliverLocal keys off envelope.to alone; deliverNotice re-bounds the
+                // summary). Fire-and-forget: the caller still gets its failed receipt;
+                // parked sends stay silent (a parked envelope is pending, not failed —
+                // it delivers on retry).
+                if (writeBackOrigin !== undefined && row?.initiatorSession !== undefined && row.initiatorSession !== '') {
+                    const notice = {
+                        kind: 'notice',
+                        to: { machine: row.machine, agent: row.agent, sessionId: row.initiatorSession },
+                        conversation: row.shortId,
+                        // answer.error is the WIRE error shape {code, message} — messageOf it and it stringifies as [object Object].
+                        // Bound at MINT time: the receiving side's strict guard 400s an
+                        // over-max summary (0.1.7-l live finding — the long ingest error
+                        // message blew the 120 bound and the notice died as 'unreachable').
+                        summary: (() => {
+                            const raw = `conversation ${row.shortId}: the peer's reply could not be delivered — ${answer.error?.message ?? 'unknown error'}`;
+                            return raw.length > A2A_NOTICE_SUMMARY_MAX ? raw.slice(0, A2A_NOTICE_SUMMARY_MAX - 1) + '…' : raw;
+                        })(),
+                        messageId: `a2a-notice-${randomUUID()}`,
+                        sender: { machine: selfM4(), agent: row.hostAgent ?? row.agent },
+                        reason: 'send-failed',
+                    };
+                    // 0.1.7-i live lesson: a swallowed emission failure reads as "no notice"
+                    // downstream — journal it (the r2e2ej probe chased a silent strict-guard
+                    // rejection for a round because of this exact swallow).
+                    void routeEnvelope(notice).catch((error) => {
+                        alog?.('warn', 'send.notice-fail', { conversation: row.shortId, error: messageOf(error) });
+                    });
+                }
+                return {
+                    outcome: 'failed',
+                    messageId,
+                    ...(answer.conversationId === undefined ? {} : { conversationId: answer.conversationId }),
+                    sessionId: answer.sessionId,
+                    error: answer.error ?? { code: 'a2a/remote-failed', message: 'a2a: the peer ingest rejected the envelope without an error body' },
+                };
+            }
+            const conversationId = answer.conversationId ?? envelope.conversationId;
+            if (row === undefined) {
+                // SELF-hosted creates already adopted the mirror row on our ingest —
+                // recordInitiatorRow never duplicates; remote creates record ours.
+                recordInitiatorRow(conversationId, to, answer.sessionId, normalizeA2aTitle(req.title), initiator);
+                // (kept from the retired newConversation: a create leaves a distinct
+                // initiator-side journal line, not just send.ok)
+                alog?.('info', 'conversation.new', { conversation: conversationId, session: answer.sessionId, peer: `${to.machine}-${to.id}`, initiator: `${initiator.machine}-${initiator.agent}` });
+            }
+            else {
+                touchRow(row, row.hostAgent === undefined ? initiator.sessionId : undefined);
+            }
+            alog?.('info', 'send.ok', { conversation: conversationId, to: `${envelope.to.machine}-${envelope.to.id}`, message: messageId });
+            return { outcome: 'delivered', messageId, conversationId, sessionId: answer.sessionId };
+        },
+        subscribeCompletion(conv, cb, opts = {}) {
+            const row = findRow(conv.conversationId);
+            if (row === undefined) {
+                opts.onError?.({
+                    code: 'a2a/conversation-not-found',
+                    message: `a2a: conversation "${conv.conversationId}" is not in the registry`,
+                });
+                return () => { };
+            }
+            if (row.machine !== conv.to.machine || row.agent !== conv.to.id) {
+                opts.onError?.({
+                    code: 'a2a/conversation-machine-mismatch',
+                    message: `a2a: conversation "${row.shortId}" belongs to ${row.machine}-${row.agent}, not ${conv.to.machine}-${conv.to.id}`,
+                });
+                return () => { };
+            }
+            let gateway;
+            try {
+                gateway = deps.gatewayFor(conv.to);
+            }
+            catch (error) {
+                const body = error instanceof A2aAddressError ? addressErrorBody(error) : receiptErrorOf(error);
+                opts.onError?.(body);
+                return () => { };
+            }
+            if (gateway === undefined) {
+                opts.onError?.({ code: 'a2a/gateway-unavailable', message: A2aAddressError.messageOf('unreachable', conv.to) });
+                return () => { };
+            }
+            // The watcher itself is the shared session-plane primitive (postoffice
+            // R3): the ingest leg subscribes the same machinery against the LOCAL
+            // gateway without the initiator-side registry checks.
+            return subscribeSessionCompletion({ gateway, sessionId: row.sessionId, conversationId: row.shortId }, cb, opts);
+        },
+        async stop(req, scope) {
+            const row = findRow(req.conversationId);
+            if (row === undefined) {
+                throw a2aError('a2a/conversation-not-found', `a2a: conversation "${req.conversationId}" is not in the registry`);
+            }
+            const expected = row.hostAgent !== undefined
+                ? { machine: selfM4(), id: row.hostAgent }
+                : { machine: row.machine, id: row.agent };
+            // D24/T3: the session owner is derived from the row; `to` (the model's
+            // `agent`), when supplied, is only a checked assertion.
+            if (req.to !== undefined && (req.to.machine !== expected.machine || req.to.id !== expected.id)) {
+                throw a2aError('a2a/conversation-machine-mismatch', `a2a: conversation "${row.shortId}" belongs to ${expected.machine}-${expected.id}, not ${req.to.machine}-${req.to.id}`);
+            }
+            // R4: the cancel executes where the session lives — the D5 liveness
+            // read, the cancel, and the session-scope degradation are all the
+            // INGEST side's business now (same machine as the session).
+            const envelope = { kind: 'stop', to: expected, conversationId: row.shortId, scope };
+            let answer;
+            try {
+                answer = await routeEnvelope(envelope);
+            }
+            catch (error) {
+                if (error instanceof EnvelopeError)
+                    throw error;
+                if (error instanceof A2aAddressError) {
+                    const body = addressErrorBody(error);
+                    throw a2aError(body.code, body.message);
+                }
+                throw a2aError('gateway/uncaught', messageOf(error));
+            }
+            if (!('stopped' in answer)) {
+                throw a2aError('a2a/bad-result', 'a2a: stop envelope answered a non-receipt');
+            }
+            return mapStopReceipt(answer);
+        },
+        buffer(initiatorSessionId, message) {
+            const list = bufferByInitiator.get(initiatorSessionId) ?? [];
+            list.push({ ...message, initiatorSessionId, bufferedAt: now() });
+            while (list.length > A2A_BUFFER_MAX)
+                list.shift();
+            bufferByInitiator.set(initiatorSessionId, list);
+            alog?.('info', 'deliver.buffer', { session: initiatorSessionId, conversation: message.conversationId, depth: list.length });
+        },
+        read(initiatorSessionId) {
+            if (initiatorSessionId !== undefined) {
+                const list = bufferByInitiator.get(initiatorSessionId) ?? [];
+                bufferByInitiator.delete(initiatorSessionId);
+                return list;
+            }
+            const swept = [];
+            for (const list of bufferByInitiator.values())
+                swept.push(...list);
+            bufferByInitiator.clear();
+            return swept;
+        },
+        listConversations() {
+            return loadConversations(deps.home).conversations.map((r) => ({ ...r }));
+        },
+    };
+    return service;
+}