super-dsh 0.1.5 → 0.1.9

package/cordis.patch.yml

@@ -21,6 +21,10 @@
 #                              On/off: row `disabled: true`, or config
 #                              `trustedPageAuthorities: []` (inert). Default
 #                              derives from the trusted-hosts env.
+#   - super-dsh/a2a            the agent-facing A2A tool face (mesh P3): the
+#                              single `superd-hub` model tool on ctx0's tools
+#                              service (dormant without tools; world trees
+#                              never compose this row — see a2a-row.ts).
 #
 # Profile-layer values (webserver port/host, settings path) stay in the USER's
 # profile patch layer, never here.
@@ -33,17 +37,30 @@
     - id: superd-web-trust
       name: 'super-dsh/web-trust'
     # Native UI fusion transport (plan Task 3): the ctx0 page-level state atom
-    # + five call-time patches, flag-gated (SUPERD_UI_FUSION, default off).
+    # + five call-time patches. Composing this row IS the switch — there is no
+    # environment variable in the decision (2026-09-27 user ruling: a release
+    # gate living in an env var is deployment state no patch layer can see).
     # ROW ORDER IS LOAD ORDER and the row MUST stay after superd-web-trust:
     # the trust script's non-merging `if(!window.__DSH_TRANSPORT__)` verdict
     # must be evaluated before the fusion script could own that global
     # (spec §3.4, hard; precedent world-web-server.ts renderIndex).
-    # On/off (Task 5 formalization): env `SUPERD_UI_FUSION` derives the
-    # schema default (off when unset); a profile layer may restate this row
-    # (same id, same name) with `config: {enabled: true|false}` to override.
-    # Off = the component registers nothing: no script, no flag global.
+    # To turn the fused surface off: restate this row (same id, same name) with
+    # `config: {enabled: false}` or `disabled: true`, or drop it from the
+    # composition. Off = the component registers nothing: no script, no global.
     - id: superd-fusion-transport
       name: 'super-dsh/fusion-transport'
+    # A2A tool face (mesh P3 Task 4): composes the single model-facing
+    # `superd-hub` tool onto ctx0's tools service and closes the a2a-host
+    # nativeGateway seam with the hub process's own typertGateway. Subpath row
+    # BY RULING (a2a-row.ts header): world trees provide a tools service too,
+    # so riding the bare superd-hub row would mount a mis-wired tool inside
+    # every world; this row lives only HERE, which world profiles never
+    # compose — ctx0 only, exactly the P3 initiator surface (foreign runtimes
+    # get their own injection in P5, spec §10). Dormant without tools.
+    # Off: restate with `disabled: true` or drop the row — nothing else
+    # registers the tool.
+    - id: superd-a2a
+      name: 'super-dsh/a2a'
     - id: agent-omp
       name: 'super-dsh/agents/omp'
     - id: agent-codex

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "super-dsh",
-  "version": "0.1.5",
+  "version": "0.1.9",
   "description": "Super D for the DeepSeek Harness (DSH) — one dsh plugin that mounts the superd hub (runtime selector, roster, per-runtime agents) and joins local foreign-agent runtimes (OMP, Codex, Claude, Pi, Hermes, Antigravity) into the DSH Web UI. Each runtime keeps its native home and session store; the hub only bridges.",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pgmi-builds/superd.git"
+    "url": "git+https://github.com/pgmi-builds/super-dsh.git"
   },
   "exports": {
     ".": "./superd-hub/dist/index.js",
@@ -22,7 +22,8 @@
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json",
     "./web-trust": "./superd-hub/dist/web-trust.js",
-    "./fusion-transport": "./superd-hub/dist/fusion-transport.js"
+    "./fusion-transport": "./superd-hub/dist/fusion-transport.js",
+    "./a2a": "./superd-hub/dist/a2a-row.js"
   },
   "files": [
     "cordis.patch.yml",
@@ -87,6 +88,7 @@
     "@deepseek-ai/dsh-scope": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-session": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-session-persistence": ">=0.1.5-0 <0.3.0-0",
+    "@deepseek-ai/dsh-tools": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-typert-protocol": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-user-approval": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-user-questions": ">=0.1.5-0 <0.3.0-0"
@@ -125,6 +127,9 @@
     "@deepseek-ai/dsh-session-persistence": {
       "optional": true
     },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-typert-protocol": {
       "optional": true
     },

package/superd-hub/dist/a2a-delivery.d.ts

@@ -0,0 +1,189 @@
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import { A2A_NOTICE_SUMMARY_MAX, type A2aNoticeReason } from './a2a-wire.js';
+export { A2A_NOTICE_SUMMARY_MAX, type A2aNoticeReason };
+import type { A2aConversationRef, A2aInitiator, A2aService } from './a2a-service.js';
+/** Durable attribution for one peer reply relayed into the initiator's conversation. */
+export interface A2aRelaySource {
+    readonly kind: 'a2a-relay';
+    /** A message another agent addressed to this one (`relay` context form). */
+    readonly form: 'relay';
+    /** Machine id (m4) of the replying peer. */
+    readonly senderMachine: string;
+    /** Agent id (a6) of the replying peer. */
+    readonly senderAgent: string;
+    /** Conversation shortId the reply belongs to. */
+    readonly conversationId: string;
+    /** Durable identity of this relay (minted at delivery, one per fired completion). */
+    readonly messageId: string;
+}
+/** Why a runtime-owned notice was produced — the taxonomy now lives on the
+ * protocol layer (a2a-wire.ts, imported + re-exported above): 0.1.7-h R2
+ * made it a wire fact, and the model-facing notice line renders it. */
+/**
+ * Durable attribution for the hub's own account of an A2A conversation event
+ * (a failed send, a dead completion stream, a stop) — deliberately a notice,
+ * not a relay: the hub states what became of the conversation and never
+ * credits the peer with words it did not write.
+ */
+export interface A2aNoticeSource {
+    readonly kind: 'a2a-notice';
+    /** A runtime account shown without expanding the row (`notice` context form). */
+    readonly form: 'notice';
+    /** One-line account of what happened, bounded to {@link A2A_NOTICE_SUMMARY_MAX}. */
+    readonly summary: string;
+    /** Conversation shortId the notice is about, when one is known. */
+    readonly conversationId?: string;
+    /** Which failure this notice reports. */
+    readonly reason: A2aNoticeReason;
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'a2a-relay': A2aRelaySource;
+        'a2a-notice': A2aNoticeSource;
+    }
+}
+/** Bound for a notice summary — owned by a2a-wire.ts since R1 (see the re-export above). */
+/**
+ * Bound one notice summary to {@link A2A_NOTICE_SUMMARY_MAX} — the same
+ * ellipsizing as upstream `boundContextSummary` (dsh-llm message.ts).
+ * @param summary - the producer's one-line account, of any length.
+ * @returns the account, ellipsized when it exceeds the bound.
+ */
+export declare function boundNoticeSummary(summary: string): string;
+/** Reply-routing choice over `ctx.agents`; peer semantics default to followup (spec §7.3). */
+export type A2aReplyDelivery = 'followup' | 'steer';
+/** One delivered (or buffered) reply/notice outcome. */
+export type A2aDeliveryOutcome = {
+    delivered: 'followup';
+} | {
+    delivered: 'steer';
+} | {
+    delivered: 'buffered';
+} | {
+    delivered: 'dropped';
+    reason: 'no-conversation';
+};
+/** Structural mirror of upstream `createUserMessage` output (dsh-llm message.ts) —
+ * fresh identity, role 'user', content blocks, producer source; detached and
+ * deep-frozen before publication. The id mirrors upstream's branded MessageId
+ * as a plain string (brands are compile-time only; the hub keeps zero dsh-llm
+ * runtime dependencies). */
+export interface A2aDeliveredMessage {
+    readonly id: string;
+    readonly role: 'user';
+    readonly content: readonly ContentBlock[];
+    readonly source: A2aRelaySource | A2aNoticeSource;
+}
+/**
+ * The agent-handle face this layer consumes — structural subset of upstream
+ * `Agent` (packages/core/agent/src/runtime-types.ts): lifecycle status plus
+ * the three inbox boundaries followup / steer / inject.
+ */
+export interface A2aAgentHandle {
+    /** Lifecycle state ('idle' | 'running' upstream); peer routing does NOT branch on it. */
+    readonly status: string;
+    followup(message: A2aDeliveredMessage): void;
+    steer(message: A2aDeliveredMessage): void;
+    inject(message: A2aDeliveredMessage): void;
+}
+/**
+ * The delivery context: the live-agent registry face plus Task 2's bounded
+ * unread-buffer leg (the persistence policy for initiators that are not live).
+ */
+export interface A2aDeliveryCtx {
+    /** Structural subset of `ctx.agents` (AgentRegistry): `get` → live handle or undefined. */
+    readonly agents: {
+        get(sessionId: string): A2aAgentHandle | undefined;
+    };
+    /** Task 2's `A2aService.buffer` leg — where undeliverable messages wait. */
+    readonly buffer: A2aService['buffer'];
+}
+/** Producer attribution for one relayed peer reply. */
+export interface A2aReplyMeta {
+    senderMachine: string;
+    senderAgent: string;
+    /** Conversation shortId the reply belongs to. */
+    conversationId: string;
+    /** Durable identity of this relay (one per fired completion). */
+    messageId: string;
+    /** Conversation title for the relay prefix (untitled placeholder when absent). */
+    title?: string;
+    /** D20: true = the runtime's transcription of the peer's turn-end last output (the peer never sent it through the channel) — renders the provenance prefix instead of "replied". */
+    transcribed?: boolean;
+}
+/** Producer attribution for one runtime notice. */
+export interface A2aNoticeMeta {
+    senderMachine: string;
+    senderAgent: string;
+    /** Conversation shortId the notice is about; absent notices cannot buffer. */
+    conversationId?: string;
+    reason: A2aNoticeReason;
+}
+/**
+ * The model-facing reply envelope (0.1.7-h R1 — one stable machine-readable
+ * vocabulary, replacing the v3 prose prefixes per the operator's §8 ruling:
+ * provenance the model had to recover from English sentences is now stated):
+ * a header line of `k=v` facts, a blank line, then the reply body. `form`
+ * keeps the D20 provenance split — `relay` = the peer chose to send through
+ * the channel; `transcript` = the peer never sent, the runtime is delivering
+ * its last output at turn end (the note spells out that observable fact per
+ * the user's no-jargon redline).
+ * @param meta - the reply attribution.
+ * @param content - the reply text (channel message or transcribed last output).
+ * @returns `[superd-hub:a2a] kind=reply form=… conversation=… from=… message=…[ note="…"]\n\n<body>`.
+ */
+export declare function renderA2aRelayText(meta: A2aReplyMeta, content: string): string;
+/** R2: the three model-facing cause values — one wire fact maps to exactly one
+ * model value, so the notice line and its summary can never disagree. */
+export type A2aModelNoticeReason = 'peer-silent' | 'peer-error' | 'stopped-by-initiator' | 'delivered' | 'undelivered';
+/** Map the wire cause taxonomy onto the model-facing one. */
+export declare function modelNoticeReason(reason: A2aNoticeReason): A2aModelNoticeReason;
+/**
+ * Render the model-visible notice text (0.1.7-h R1/R2): ONE line in the same
+ * envelope vocabulary as relays, plus the R2 cause and the bounded summary.
+ * Inner double quotes are sanitized to single quotes (legacy peer summaries
+ * embed `conversation "x"`) so the k=v line stays parseable; the wire/source
+ * summary keeps its verbatim text.
+ */
+export declare function renderA2aNoticeText(meta: A2aNoticeMeta, summary: string): string;
+/**
+ * Deliver one peer reply into the initiating agent's conversation.
+ * @param ctx - live-agent face + buffer leg.
+ * @param initiator - who asked (its sessionId keys the buffer).
+ * @param content - the peer's final reply text.
+ * @param meta - relay attribution (sender address, conversation, identity, title).
+ * @param opts - `delivery:'steer'` overrides the followup default.
+ * @returns where the reply landed.
+ */
+export declare function deliverReply(ctx: A2aDeliveryCtx, initiator: A2aInitiator, content: string, meta: A2aReplyMeta, opts?: {
+    delivery?: A2aReplyDelivery;
+}): A2aDeliveryOutcome;
+/**
+ * Deliver one runtime-owned notice (bounded one-line account) into the
+ * initiating agent's conversation.
+ * @param ctx - live-agent face + buffer leg.
+ * @param initiator - who asked (its sessionId keys the buffer).
+ * @param summary - the one-line account, any length (bounded here).
+ * @param meta - notice attribution; a notice without a conversation cannot buffer.
+ * @param opts - `delivery:'steer'` overrides the followup default.
+ * @returns where the notice landed.
+ */
+export declare function deliverNotice(ctx: A2aDeliveryCtx, initiator: A2aInitiator, summary: string, meta: A2aNoticeMeta, opts?: {
+    delivery?: A2aReplyDelivery;
+}): A2aDeliveryOutcome;
+/** The Task-2 service surface the glue consumes. */
+export type A2aCompletionSource = Pick<A2aService, 'subscribeCompletion' | 'listConversations'>;
+/**
+ * Wire one conversation's completion stream to the initiator's delivery face:
+ * every fired completion becomes one relayed reply (titled from the registry
+ * row); a completion-stream death becomes one bounded stream-dead notice.
+ * Wire one conversation's completion stream to the initiator's delivery face:
+ * every fired completion becomes one relayed reply (titled from the registry
+ * row) — EXCEPT a turn that ended non-completed with NO captured text, which
+ * degrades to a bounded 'aborted' notice (D3: a content-free relay is noise
+ * and can wake an idle initiator for nothing); a completion-stream death
+ * becomes one bounded stream-dead notice.
+ */
+export declare function wireCompletionToDelivery(ctx: A2aDeliveryCtx, service: A2aCompletionSource, initiator: A2aInitiator, conv: A2aConversationRef, opts?: {
+    requestId?: string;
+}): () => void;

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

@@ -0,0 +1,240 @@
+/**
+ * A2A reply-delivery face (mesh P3 Task 3): how a peer agent's reply arrives
+ * back in the INITIATING agent's conversation — the two producer source kinds
+ * for `@deepseek-ai/dsh-llm`'s MessageSourceMap, the peer-routing rules over
+ * `ctx.agents`, and the subscribe→deliver glue.
+ *
+ * Upstream anchors (`upstream/deepseek-harness` @ dsh-v0.1.7-rc.1):
+ *   - the continuation-message pattern: `packages/subagent/subagent/src/
+ *     continuation-messages.ts` — each producer declares its own kinds into
+ *     MessageSourceMap via `declare module '@deepseek-ai/dsh-llm'` with a
+ *     type-only import of the target package, and builds user-role messages
+ *     through `createUserMessage` (fresh identity, detached, deep-frozen).
+ *     That constructor is not re-exported by any package the hub may consume,
+ *     so this module constructs the SAME structural shape locally
+ *     ({@link A2aDeliveredMessage}) and keeps a zero-dependency runtime —
+ *     the type-only import below anchors the augmentation exactly like the
+ *     upstream precedent.
+ *   - the delivery routing template: `continuation-activation.ts`
+ *     notifySettlement (:871-888) — idle→queue, busy→steer, closing
+ *     teardown→inject, missing→nothing. That is the PARENT/child contract.
+ *     A2A peers are not parents (spec §7.3 ruling): a peer reply is ordinary
+ *     queued input, so idle AND busy both deliver via `followup` — never
+ *     interrupting the initiator's active turn — and `steer` exists ONLY for
+ *     explicit `delivery:'steer'` requests; a missing initiator (not live,
+ *     torn down) lands in Task 2's bounded unread buffer instead of being
+ *     injected or dropped.
+ *   - notice summaries are bounded like upstream `boundContextSummary`
+ *     (CONTEXT_SUMMARY_MAX_CHARS = 120): 119 chars + '…'.
+ */
+import { randomUUID } from 'node:crypto';
+import { A2A_NOTICE_SUMMARY_MAX } from './a2a-wire.js';
+// compat re-exports (postoffice R1 / 0.1.7-h R2): both moved to the protocol
+// layer (a2a-wire.ts) — the bound so the envelope guard enforces the same
+// number this module bounds with, the reason type because it now crosses the
+// wire; existing importers keep compiling.
+export { A2A_NOTICE_SUMMARY_MAX };
+/** Bound for a notice summary — owned by a2a-wire.ts since R1 (see the re-export above). */
+/**
+ * Bound one notice summary to {@link A2A_NOTICE_SUMMARY_MAX} — the same
+ * ellipsizing as upstream `boundContextSummary` (dsh-llm message.ts).
+ * @param summary - the producer's one-line account, of any length.
+ * @returns the account, ellipsized when it exceeds the bound.
+ */
+export function boundNoticeSummary(summary) {
+    return summary.length <= A2A_NOTICE_SUMMARY_MAX
+        ? summary
+        : `${summary.slice(0, A2A_NOTICE_SUMMARY_MAX - 1)}…`;
+}
+/** Recursive freeze, mirroring upstream `deepFreeze(structuredClone(...))` publication. */
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object') {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                deepFreeze(item);
+        }
+        else {
+            for (const key of Object.keys(value))
+                deepFreeze(value[key]);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+/**
+ * Build one identified, immutable user-role message — the local equivalent of
+ * upstream `createUserMessage`: fresh uuid identity, structuredClone-detached,
+ * deep-frozen before publication.
+ * @param content - model-visible message blocks.
+ * @param source - the producer attribution (our declared kinds).
+ * @returns the frozen user message handed to the initiator's inbox.
+ */
+function createA2aUserMessage(content, source) {
+    return deepFreeze(structuredClone({
+        id: randomUUID(),
+        role: 'user',
+        content,
+        source,
+    }));
+}
+/**
+ * The model-facing reply envelope (0.1.7-h R1 — one stable machine-readable
+ * vocabulary, replacing the v3 prose prefixes per the operator's §8 ruling:
+ * provenance the model had to recover from English sentences is now stated):
+ * a header line of `k=v` facts, a blank line, then the reply body. `form`
+ * keeps the D20 provenance split — `relay` = the peer chose to send through
+ * the channel; `transcript` = the peer never sent, the runtime is delivering
+ * its last output at turn end (the note spells out that observable fact per
+ * the user's no-jargon redline).
+ * @param meta - the reply attribution.
+ * @param content - the reply text (channel message or transcribed last output).
+ * @returns `[superd-hub:a2a] kind=reply form=… conversation=… from=… message=…[ note="…"]\n\n<body>`.
+ */
+export function renderA2aRelayText(meta, content) {
+    const header = meta.transcribed === true
+        ? `[superd-hub:a2a] kind=reply form=transcript conversation=${meta.conversationId} from=${meta.senderMachine}-${meta.senderAgent} message=${meta.messageId} note="the peer never sent through the channel — this is the runtime delivering the peer's last output at turn end"`
+        : `[superd-hub:a2a] kind=reply form=relay conversation=${meta.conversationId} from=${meta.senderMachine}-${meta.senderAgent} message=${meta.messageId}`;
+    return `${header}\n\n${content}`;
+}
+/** Map the wire cause taxonomy onto the model-facing one. */
+export function modelNoticeReason(reason) {
+    switch (reason) {
+        case 'stop': return 'stopped-by-initiator';
+        case 'peer': return 'peer-silent';
+        case 'delivered': return 'delivered';
+        case 'undelivered': return 'undelivered';
+        default: return 'peer-error'; // send-failed / stream-dead / aborted — the peer side ended abnormally
+    }
+}
+/**
+ * Render the model-visible notice text (0.1.7-h R1/R2): ONE line in the same
+ * envelope vocabulary as relays, plus the R2 cause and the bounded summary.
+ * Inner double quotes are sanitized to single quotes (legacy peer summaries
+ * embed `conversation "x"`) so the k=v line stays parseable; the wire/source
+ * summary keeps its verbatim text.
+ */
+export function renderA2aNoticeText(meta, summary) {
+    const conv = meta.conversationId === undefined ? '' : ` conversation=${meta.conversationId}`;
+    return `[superd-hub:a2a] kind=notice${conv} from=${meta.senderMachine}-${meta.senderAgent} reason=${modelNoticeReason(meta.reason)} summary="${summary.replace(/"/g, "'")}"`;
+}
+/**
+ * Route one built message to the initiator: live → followup (or steer when
+ * explicitly requested); not live → the buffer leg when the input has a
+ * conversation to anchor it, else best-effort nothing.
+ */
+function route(ctx, initiator, message, delivery, buffered) {
+    const agent = ctx.agents.get(initiator.sessionId);
+    if (agent === undefined) {
+        if (buffered === undefined)
+            return { delivered: 'dropped', reason: 'no-conversation' };
+        ctx.buffer(initiator.sessionId, buffered);
+        return { delivered: 'buffered' };
+    }
+    if (delivery === 'steer')
+        agent.steer(message);
+    else
+        agent.followup(message);
+    return { delivered: delivery };
+}
+/**
+ * Deliver one peer reply into the initiating agent's conversation.
+ * @param ctx - live-agent face + buffer leg.
+ * @param initiator - who asked (its sessionId keys the buffer).
+ * @param content - the peer's final reply text.
+ * @param meta - relay attribution (sender address, conversation, identity, title).
+ * @param opts - `delivery:'steer'` overrides the followup default.
+ * @returns where the reply landed.
+ */
+export function deliverReply(ctx, initiator, content, meta, opts = {}) {
+    const text = renderA2aRelayText(meta, content);
+    const message = createA2aUserMessage([{ type: 'text', text }], {
+        kind: 'a2a-relay',
+        form: 'relay',
+        senderMachine: meta.senderMachine,
+        senderAgent: meta.senderAgent,
+        conversationId: meta.conversationId,
+        messageId: meta.messageId,
+    });
+    return route(ctx, initiator, message, opts.delivery ?? 'followup', {
+        messageId: meta.messageId,
+        from: { machine: meta.senderMachine, id: meta.senderAgent },
+        conversationId: meta.conversationId,
+        text,
+    });
+}
+/**
+ * Deliver one runtime-owned notice (bounded one-line account) into the
+ * initiating agent's conversation.
+ * @param ctx - live-agent face + buffer leg.
+ * @param initiator - who asked (its sessionId keys the buffer).
+ * @param summary - the one-line account, any length (bounded here).
+ * @param meta - notice attribution; a notice without a conversation cannot buffer.
+ * @param opts - `delivery:'steer'` overrides the followup default.
+ * @returns where the notice landed.
+ */
+export function deliverNotice(ctx, initiator, summary, meta, opts = {}) {
+    const bounded = boundNoticeSummary(summary);
+    // R1: a notice is an injected turn like any other — its model-facing text
+    // is the envelope line (provenance + cause + summary); the buffered copy
+    // carries the same line so a later sweep injects identical text.
+    const noticeText = renderA2aNoticeText(meta, bounded);
+    const message = createA2aUserMessage([{ type: 'text', text: noticeText }], {
+        kind: 'a2a-notice',
+        form: 'notice',
+        summary: bounded,
+        ...(meta.conversationId === undefined ? {} : { conversationId: meta.conversationId }),
+        reason: meta.reason,
+    });
+    const buffered = meta.conversationId === undefined ? undefined : {
+        messageId: `a2a-notice-${randomUUID()}`,
+        from: { machine: meta.senderMachine, id: meta.senderAgent },
+        conversationId: meta.conversationId,
+        text: noticeText,
+    };
+    return route(ctx, initiator, message, opts.delivery ?? 'followup', buffered);
+}
+/**
+ * Wire one conversation's completion stream to the initiator's delivery face:
+ * every fired completion becomes one relayed reply (titled from the registry
+ * row); a completion-stream death becomes one bounded stream-dead notice.
+ * Wire one conversation's completion stream to the initiator's delivery face:
+ * every fired completion becomes one relayed reply (titled from the registry
+ * row) — EXCEPT a turn that ended non-completed with NO captured text, which
+ * degrades to a bounded 'aborted' notice (D3: a content-free relay is noise
+ * and can wake an idle initiator for nothing); a completion-stream death
+ * becomes one bounded stream-dead notice.
+ */
+export function wireCompletionToDelivery(ctx, service, initiator, conv, opts = {}) {
+    const titleOf = (conversationId) => service.listConversations().find((r) => r.shortId === conversationId || r.sessionId === conversationId)?.title;
+    return service.subscribeCompletion(conv, (completion) => {
+        // D3: a terminal turn that produced NO reply must not relay — aborted
+        // WITH captured text still relays (the words exist); only the empty
+        // non-completed end becomes a bounded notice.
+        if (completion.reason !== 'completed' && completion.text === '') {
+            deliverNotice(ctx, initiator, `conversation ${completion.conversationId}: turn aborted, no reply`, {
+                senderMachine: conv.to.machine,
+                senderAgent: conv.to.id,
+                conversationId: completion.conversationId,
+                reason: 'aborted',
+            });
+            return;
+        }
+        deliverReply(ctx, initiator, completion.text, {
+            senderMachine: conv.to.machine,
+            senderAgent: conv.to.id,
+            conversationId: completion.conversationId,
+            messageId: `a2a-relay-${randomUUID()}`,
+            title: titleOf(completion.conversationId),
+        });
+    }, {
+        requestId: opts.requestId,
+        onError: (error) => {
+            deliverNotice(ctx, initiator, `A2A completion stream from ${conv.to.machine}-${conv.to.id} (conversation "${conv.conversationId}") failed: ${error.message}`, {
+                senderMachine: conv.to.machine,
+                senderAgent: conv.to.id,
+                conversationId: conv.conversationId,
+                reason: 'stream-dead',
+            });
+        },
+    });
+}

package/superd-hub/dist/a2a-host.d.ts

@@ -0,0 +1,76 @@
+import type { A2aAddress, A2aGateway, A2aInitiator, A2aService } from './a2a-service.js';
+/** Host wiring inputs: the hub home plus the local native session-plane face. */
+export interface A2aHostOptions {
+    /** Hub home (a6 id store + machines registry live under `<home>/superd/`). */
+    home: string;
+    /**
+     * ctx0's own RAW in-process typertGateway instance — serves the LOCAL
+     * 'native' row (its a6); injected by the plugin wiring, undefined before
+     * the hub process has its own face. Bridged to T2's face by the resolver
+     * ({@link bridgeTypertGateway}).
+     */
+    nativeGateway?: RawTypertGatewayFace;
+}
+/**
+ * The RAW typertGateway service face — upstream canonical stream order
+ * `openWireStream(endpoint, payload, uplink, peer, signal, control)`
+ * (dsh-api-gateway/src/index.ts:434; the 0.1.3-j positional-misbind lesson).
+ * LOCAL worlds and ctx0's own row hand out RAW instances (world-join.ts
+ * registers `ctxW.get('typertGateway')` verbatim); FEDERATED rows hand out
+ * mesh-gateway wire adapters (dual-face, 3rd-argument dispatch).
+ */
+export interface RawTypertGatewayFace {
+    dispatchRpc(endpoint: string, payload: unknown, signal: AbortSignal): Promise<unknown>;
+    openWireStream(endpoint: string, payload: unknown, uplink: undefined, peer: undefined, signal: AbortSignal, control: AbortController): Promise<AsyncIterable<unknown>> | AsyncIterable<unknown>;
+}
+/**
+ * Bridge one RAW typertGateway instance to Task 2's 3-arg `A2aGateway` face
+ * (fix round 1, 2026-09-28 review: the positional mismatch stranded completion
+ * streams). `uplink: undefined` is the canonical NO-LANE spelling upstream —
+ * the gateway substitutes `EMPTY_ASYNC_ITERABLE` itself
+ * (dsh-api-gateway/src/index.ts:712) — and `dispatchRpc` passes through as-is.
+ *
+ * FEDERATED WIRE ADAPTERS MUST NOT BE WRAPPED: mesh-gateway's dual-face
+ * dispatch reads the THIRD argument (`isUplinkLane(undefined)` → false), so a
+ * canonical 6-arg call would take its 3-arg branch and read the abort signal
+ * from position 3 (undefined) — silently losing cancellation. The resolver
+ * therefore passes federated rows through untouched.
+ * @param real - a raw in-process typertGateway instance (ctx0's own or a local world's).
+ * @returns the gateway Task 2's service consumes.
+ */
+export declare function bridgeTypertGateway(real: RawTypertGatewayFace): A2aGateway;
+/**
+ * Build the gatewayFor resolver Task 2's service consumes: federated table
+ * first, shared target registry second, local id-map inversion third,
+ * injected native face last. LOCAL rows (runtime-key targets + the native
+ * seam) are RAW instances and get {@link bridgeTypertGateway}; FEDERATED rows
+ * (federation memo + a6-keyed registry entries) are wire adapters and pass
+ * through UNTOWRAPPED (see the bridge's JSDoc for why wrapping them loses
+ * the abort signal).
+ *
+ * A MISS THROWS the typed {@link A2aAddressError} (D7): a roster-known a6 whose
+ * plane is down → 'unreachable'; an a6 no store has ever seen → 'unknown-agent'
+ * when the addressed machine is self or paired, else 'unknown-machine' — the
+ * WHY survives the resolver boundary for future consumers (P4 exec, P5
+ * injection) to branch on.
+ * @param options - hub home + optional raw in-process native gateway.
+ * @returns the resolver (a gateway, or it throws A2aAddressError).
+ */
+export declare function resolveA2aGatewayFor(options: A2aHostOptions): (addr: A2aAddress) => A2aGateway;
+/**
+ * Build the LOCAL machine's initiator identity from the calling world's
+ * roster key and the live DSH session driving the tool call.
+ * @param home - hub home (self m4 + a6 id store).
+ * @param agentKey - roster key of the calling world ('native' for ctx0's own agent).
+ * @param sessionId - the live DSH session id making the call (T4: the tool call's agent context).
+ * @returns the initiator envelope Task 2's service teaches the peer.
+ */
+export declare function localA2aInitiator(home: string, agentKey: string, sessionId: string): A2aInitiator;
+/**
+ * Assemble the full A2A service on the hub's live surfaces: Task 2's pure
+ * core with the host gatewayFor resolution (delivery glue is per-conversation
+ * — T4's tool wires `wireCompletionToDelivery` after each send).
+ * @param options - hub home + optional in-process native gateway.
+ * @returns the A2A conversation service.
+ */
+export declare function createA2aHost(options: A2aHostOptions): A2aService;