super-dsh 0.3.3-c → 0.3.4-a

package/agent-hermes/bridge/hermes-ws-bridge.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""superd hermes WS-attach bridge: stdio JSON-RPC (adapter contract) <-> the profile's gateway WS.
+
+The standalone `tui_gateway.entry` stdio server can no longer co-own a Hermes home: a running
+gateway holds `gateway.lock` and refuses a second owner ("attach to it instead"). The sanctioned
+attach is the canonical WebSocket (`ui-tui` attaches over it; `hermes_cli.gateway_client` is the
+product client module). This bridge keeps the adapter's stdio ndjson JSON-RPC contract byte-stable
+while the frames ride that WebSocket:
+
+  stdin  line -> `GatewayClient.rpc` (ids mapped 1:1; the gateway reader drops bare replies whose
+                 ids it does not own, so requests MUST ride the product client), reply -> stdout
+  ws event    -> stdout line (`{"method":"event","params":{...}}` wire events via the event queue)
+  on connect  -> one synthesized `gateway.ready` event (the stdio contract; the canonical gateway
+                 has no ready frame - readiness is the discovery grant + open socket)
+
+The adapter was built against the STANDALONE serve; the ws authority path re-shapes exactly five
+verbs (contract files: `tui_gateway/contracts/canonical*.py`, `gateway/session_controls.py`,
+`gateway/session_busy_controls.py`; every params model is `extra="forbid"`). The bridge reconciles:
+
+  session.create    drop `cols` (standalone-only field; CanonicalCreateParams forbids it)
+  prompt.submit     inject `submission_id` (authority refuses without a client request id; the
+                    adapter never sends one) and translate the AdmissionStatus receipt into the
+                    standalone `{"status":"streaming"}` ack the adapter's busy path requires;
+                    `{voice_stopped:true}` becomes a JSON-RPC error (a DSH turn is never voice)
+  session.steer     inject `execution_generation` (CanonicalCorrectionParams requires it)
+  session.interrupt inject `execution_generation` (CanonicalControlParams requires it)
+  approval.respond  translate `{request_id, choice}` into the authority's EXACT
+                    `{prompt_id, execution_generation, choice}` set, with the generation tracked
+                    from the `approval.request` event payload
+
+The generation tracker seeds from the session.create/session.resume snapshot and refreshes from
+every live event frame (`execution_generation` rides the frame top level, the CanonicalReplayEvent
+shape), every `prompt.submit` receipt, `approval.request` payload and control ack that carries one.
+Unknown-on-authority methods (`session.usage` / `session.status` / `session.compress` /
+`session.close`) answer the gateway's own -32601 verbatim; the adapter treats close as
+fire-and-forget and the other two degrade to tool errors without touching the turn log.
+
+Events: frames for foreign sessions are dropped once a session is bound (the adapter demuxes on
+the live id anyway; filtering here keeps foreign approval requests away from the bridge layer).
+`connect_gateway()` attaches to the home's running owner, or starts one (idle-exit) when none
+runs, so the same bridge serves both machines with a persistent gateway and machines where the
+adapter previously owned the home. Failure to obtain a gateway exits 2 with the
+`[bridge-attach-unavailable]` stderr marker (maps onto the adapter's existing spawn-failure UX).
+
+Env: PYTHONPATH / HERMES_PYTHON_SRC_ROOT (set by the adapter) put `hermes_cli` on the path.
+HERMES_HOME stays unset (default profile home), matching the stdio spawn's strip list.
+"""
+import asyncio
+import json
+import os
+import sys
+import uuid
+from pathlib import Path
+
+
+def _bootstrap_deps() -> None:
+    """Boot the committed dependency generation, exactly like gateway_bootstrap.py does for the TUI."""
+    root = os.environ.get("HERMES_PYTHON_SRC_ROOT", "")
+    if root:
+        sys.path.insert(0, root)
+    try:
+        from pm.environments import NoCommittedEnvironment, activate_dependencies  # type: ignore
+
+        try:
+            activate_dependencies(Path(root))
+        except NoCommittedEnvironment:
+            pass
+    except ImportError:
+        pass  # a venv python already carries the deps
+
+
+class BridgeAttachUnavailable(Exception):
+    """No owner to attach and none startable (or the client module is unusable)."""
+
+
+class BridgeState:
+    """One adapter connection's session-bound translation state."""
+
+    def __init__(self) -> None:
+        self.session_id = None
+        self.generation = 0
+        self.prompt_generations = {}
+
+    # -- request side ---------------------------------------------------------
+    def translate_request(self, method, params):
+        """Return (method, params) as the authority contract requires them."""
+        if method == "session.create":
+            # Standalone-only field; CanonicalCreateParams is extra="forbid".
+            params = {k: v for k, v in params.items() if k != "cols"}
+        elif method == "prompt.submit":
+            # Authority refusal without a client-chosen request id (replay guard).
+            if not params.get("submission_id") and not params.get("input_id"):
+                params = {**params, "submission_id": f"superd-{uuid.uuid4().hex}"}
+        elif method in ("session.steer", "session.interrupt"):
+            if "execution_generation" not in params:
+                params = {**params, "execution_generation": self.generation}
+            print(f"[bridge-ctl] {method} injected_gen={params.get('execution_generation')} tracked={self.generation}", file=sys.stderr)
+        elif method == "approval.respond":
+            params = self._translate_approval(params)
+        return method, params
+
+    def _translate_approval(self, params):
+        if "prompt_id" in params and "request_id" not in params:
+            return params  # already canonical
+        request_id = params.get("request_id")
+        generation = self.prompt_generations.get(request_id, self.generation)
+        return {"session_id": params.get("session_id"), "prompt_id": request_id,
+                "execution_generation": generation, "choice": params.get("choice")}
+
+    # -- reply side -----------------------------------------------------------
+    def translate_result(self, method, params, result):
+        """Return the reply the standalone-shaped adapter expects, or an error dict."""
+        if method in ("session.create", "session.resume") and isinstance(result, dict):
+            sid = result.get("session_id") or result.get("stored_session_id")
+            if isinstance(sid, str) and sid:
+                self.session_id = sid
+            gen = result.get("execution_generation")
+            if isinstance(gen, int):
+                self.generation = gen
+            return result
+        if method == "prompt.submit":
+            if not isinstance(result, dict):
+                return result
+            if result.get("voice_stopped") is True:
+                return {"__error__": {"code": -32001, "message": "voice stopped: nothing was admitted"}}
+            gen = result.get("execution_generation")
+            if isinstance(gen, int):
+                self.generation = gen
+            # Standalone ack contract: status "streaming" (the adapter rejects anything else);
+            # the canonical AdmissionStatus rides along for tracing.
+            return {"status": "streaming", "receipt": result}
+        if isinstance(result, dict) and method in ("session.steer", "session.interrupt"):
+            gen = result.get("execution_generation")
+            if isinstance(gen, int):
+                self.generation = gen
+            return result
+        return result
+
+    # -- event side -----------------------------------------------------------
+    def observe_event(self, params):
+        """Track generations/pending prompts; return False when the frame must not reach stdout."""
+        if not isinstance(params, dict):
+            return True
+        sid = params.get("session_id")
+        if self.session_id is not None and isinstance(sid, str) and sid and sid != self.session_id:
+            return False  # foreign session: never forward (adapter demux would drop it anyway)
+        gen = params.get("execution_generation")  # live frames carry it top-level (CanonicalReplayEvent shape)
+        if isinstance(gen, int):
+            self.generation = gen
+        payload = params.get("payload")
+        if not isinstance(payload, dict):
+            return True
+        gen = payload.get("execution_generation")
+        if isinstance(gen, int):
+            self.generation = gen
+        if params.get("type") == "approval.request" and isinstance(payload.get("prompt_id"), str):
+            self.prompt_generations[payload["prompt_id"]] = gen if isinstance(gen, int) else self.generation
+            if len(self.prompt_generations) > 64:  # settled prompts are answered once; bound the map
+                self.prompt_generations.pop(next(iter(self.prompt_generations)))
+        return True
+
+
+async def _answer(client, state, rid, method, params) -> None:
+    """One adapter request through the product client (the gateway reader drops
+    bare replies whose ids it does not own, so raw forwarding cannot work)."""
+    from hermes_cli.gateway_client import GatewayRPCError  # type: ignore
+    try:
+        method, params = state.translate_request(method, params)
+        result = await client.rpc(method, _timeout=float("inf"), **params)
+        translated = state.translate_result(method, params, result)
+        if isinstance(translated, dict) and "__error__" in translated:
+            frame = {"jsonrpc": "2.0", "id": rid, "error": translated["__error__"]}
+        else:
+            frame = {"jsonrpc": "2.0", "id": rid, "result": translated}
+    except GatewayRPCError as exc:
+        code = exc.code if isinstance(exc.code, int) else -32000
+        frame = {"jsonrpc": "2.0", "id": rid, "error": {"code": code, "message": str(exc)}}
+    except Exception as exc:  # transport died mid-call: surface as the turn error
+        frame = {"jsonrpc": "2.0", "id": rid, "error": {"code": -32603, "message": f"{type(exc).__name__}: {exc}"}}
+    sys.stdout.write(json.dumps(frame, separators=(",", ":")) + "\n")
+    sys.stdout.flush()
+
+
+async def _stdin_pump(client, state) -> None:
+    loop = asyncio.get_running_loop()
+    reader = asyncio.StreamReader()
+    protocol = asyncio.StreamReaderProtocol(reader)
+    await loop.connect_read_pipe(lambda: protocol, sys.stdin)
+    inflight = set()
+    while True:
+        line = await reader.readline()
+        if not line:
+            return  # adapter closed its side: the ws close ends the process
+        text = line.decode("utf-8", "replace").strip()
+        if not text:
+            continue
+        req = None
+        try:
+            req = json.loads(text)
+            rid = req.get("id")
+            method = req.get("method")
+            params = req.get("params")
+            if not isinstance(method, str) or (params is not None and not isinstance(params, dict)):
+                raise ValueError("request needs a string method and object params")
+            task = asyncio.create_task(_answer(client, state, rid, method, params or {}))
+            inflight.add(task)
+            task.add_done_callback(inflight.discard)
+        except Exception as exc:
+            broken_id = req.get("id") if isinstance(req, dict) else None
+            sys.stdout.write(json.dumps(
+                {"jsonrpc": "2.0", "id": broken_id, "error": {"code": -32700, "message": str(exc)}}) + "\n")
+            sys.stdout.flush()
+
+
+async def _event_pump(client, state) -> None:
+    while True:
+        frame = await client.events.get()
+        params = frame.get("params") if isinstance(frame, dict) else None
+        if not state.observe_event(params if isinstance(params, dict) else {}):
+            continue
+        sys.stdout.write(json.dumps(frame, separators=(",", ":")) + "\n")
+        sys.stdout.flush()
+
+
+async def _run() -> int:
+    try:
+        from hermes_cli.gateway_client import connect_gateway  # type: ignore
+    except Exception as exc:  # ImportError and activation failures alike
+        raise BridgeAttachUnavailable(f"gateway client module unavailable: {exc}") from exc
+
+    try:
+        async with connect_gateway() as client:
+            state = BridgeState()
+            pump_events = asyncio.create_task(_event_pump(client, state))
+            # Readiness contract first: the adapter queues every RPC behind gateway.ready.
+            sys.stdout.write(json.dumps({
+                "jsonrpc": "2.0", "method": "event",
+                "params": {"type": "gateway.ready", "payload": {"transport": "ws-attach"}},
+            }) + "\n")
+            sys.stdout.flush()
+            pump_stdin = asyncio.create_task(_stdin_pump(client, state))
+            done, pending = await asyncio.wait({pump_events, pump_stdin}, return_when=asyncio.FIRST_COMPLETED)
+            for task in pending:
+                task.cancel()
+            for task in done:
+                exc = task.exception()
+                if exc is not None:
+                    raise exc
+    except BridgeAttachUnavailable:
+        raise
+    except Exception as exc:  # GatewayUnavailableError / GatewayClientError / transport failures
+        raise BridgeAttachUnavailable(f"{type(exc).__name__}: {exc}") from exc
+    return 0
+
+
+def main() -> int:
+    _bootstrap_deps()
+    try:
+        return asyncio.run(_run())
+    except BridgeAttachUnavailable as exc:
+        # No owner and none startable: the marker lets the adapter map this onto
+        # the ordinary spawn-failure surface (message lands in the turn error).
+        print(f"[bridge-attach-unavailable] {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 0
+    except Exception as exc:  # transport/protocol failures: ordinary child failure
+        print(f"[bridge-exit] {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/agent-hermes/dist/agent.js

@@ -273,6 +273,10 @@ export class HermesAgent {
     #step = 0;
     #lastTurn = 0;
     #turnOpen = false;
+    /** True once the reserved turn's `turn/start` (+ user/message) actually committed to the log. */
+    #turnStarted = false;
+    /** The reserved turn's prompt, held until its opening pair commits (or the turn unwinds). */
+    #reservedMessage = undefined;
     #cancelCause = null;
     /** Terminal model failure of the open turn (`message_end` stopReason "error"); consumed by `agent_end`. */
     #pendingFailure = null;
@@ -478,7 +482,9 @@ export class HermesAgent {
         // Reserve the turn synchronously: busy-flag semantics stay identical to the
         // eager line, but NOTHING is appended yet — the log stays empty until the
         // gateway session exists, so a failed cold start leaves no orphan turn.
-        this.#reserveTurn();
+        // The message rides the reservation so a failure that closes the turn
+        // inside the reserved window can still commit the opening pair.
+        this.#reserveTurn(message);
         clearTimeout(this.#idleExitTimer);
         this.#idleExitTimer = undefined;
         this.#beginActivity();
@@ -501,8 +507,8 @@ export class HermesAgent {
             const failure = classifyTurnError(error, this.#failureContext());
             trace(`#startTurn cold start failed [${failure.code}]: ${failure.message}`);
             if (this.#turnOpen) {
-                this.session.append("turn/start", { turn: this.#dashTurn });
-                this.session.append("user/message", message, { surfaceOp: "append" });
+                // #closeTurn commits the opening pair (turn/start + user/message) when
+                // the turn never got past its reservation — the single append path.
                 this.#closeTurn({ kind: "error", error: failure });
             }
             this.#endActivity();
@@ -514,6 +520,8 @@ export class HermesAgent {
         if (this.#disposed)
             return;
         this.session.append("turn/start", { turn: this.#dashTurn });
+        this.#turnStarted = true;
+        this.#reservedMessage = undefined;
         await this.#emitRequestContext();
         const event = this.session.append("user/message", message, { surfaceOp: "append" });
         this.#titleSourceSeq ??= event.seq;
@@ -689,17 +697,32 @@ export class HermesAgent {
      * synchronously, then commits turn/start + user/message only after the
      * cold start (#startTurn).
      */
-    #reserveTurn() {
+    #reserveTurn(message) {
         if (this.#turnOpen)
             return;
         this.#dashTurn = ++this.#lastTurn;
         this.#step = 0;
         this.#turnOpen = true;
+        this.#turnStarted = false;
+        this.#reservedMessage = message;
     }
     #closeTurn(reason) {
         if (!this.#turnOpen)
             return;
+        if (!this.#turnStarted) {
+            // Failure closed the turn while it was still only RESERVED (pre
+            // `turn/start`; the cold-start window). Commit the opening pair first:
+            // a `turn/end` without `turn/start` is a corrupt v4 log (2026-11-02 —
+            // `client.onFailure` beat the cold-start catch to `#closeTurn` when the
+            // gateway child exited during `#materializeSession`).
+            this.session.append("turn/start", { turn: this.#dashTurn });
+            if (this.#reservedMessage !== undefined) {
+                this.session.append("user/message", this.#reservedMessage, { surfaceOp: "append" });
+            }
+            this.#turnStarted = true;
+        }
         this.#turnOpen = false;
+        this.#reservedMessage = undefined;
         this.#clearTurnDeadline();
         this.session.append("turn/end", { turn: this.#dashTurn, reason });
     }

package/agent-hermes/dist/hermes-client.js

@@ -1,8 +1,11 @@
 /**
  * HermesGatewayClient — the reusable TUI-gateway client seam (AW-H Task 3).
  *
- * One client = one spawned gateway child (`python -m tui_gateway.entry`,
- * stdio ndjson JSON-RPC) = one bound gateway session. Spawn/env/ready patterns
+ * One client = one gateway child bound to one gateway session. Transports:
+ * `stdio` (legacy default) spawns `python -m tui_gateway.entry` (owns the
+ * Hermes home); `attach` (SUPERD_HERMES_TRANSPORT=attach) spawns the
+ * WS-attach bridge — same stdio ndjson JSON-RPC contract, frames relayed to
+ * the profile's canonical gateway WebSocket. Spawn/env/ready patterns
  * follow the upstream reference client `ui-tui/src/gatewayClient.ts` and the
  * Task 1 spike (`src/spike.ts`, live-pinned protocol facts):
  *
@@ -64,6 +67,7 @@ import { spawn, execFile } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { prepareHermesNativePlugin } from "@pgmi-builds/superd-hub/foreign-native";
 import { createInterface } from "node:readline";
@@ -166,6 +170,28 @@ export function loadHermesDotEnv() {
         return {};
     }
 }
+/** Gateway child transport. `stdio` = the legacy in-child `tui_gateway.entry`
+ *  server (owns the Hermes home exclusively). `attach` = the WS-attach bridge
+ *  (`bridge/hermes-ws-bridge.py`): frames ride the profile's canonical gateway
+ *  WebSocket via `hermes_cli.gateway_client.connect_gateway`, which attaches
+ *  to the running owner or starts an idle-exit one — REQUIRED whenever the
+ *  user's native Hermes gateway already owns `~/.hermes` (2026-11-02: every
+ *  stdio spawn died with `[gateway-exit] refused: ... owned by a running
+ *  gateway`, and the reserved-turn failure window corrupted session logs).
+ *  Selection: `SUPERD_HERMES_TRANSPORT` process env wins, then the native
+ *  `~/.hermes/.env` key (hot-editable without touching the host process),
+ *  else `stdio`. Unknown values fall back to `stdio`. */
+export function resolveHermesTransport(dotEnv = {}) {
+    const raw = process.env.SUPERD_HERMES_TRANSPORT?.trim() || dotEnv.SUPERD_HERMES_TRANSPORT?.trim() || "stdio";
+    return raw === "attach" ? "attach" : "stdio";
+}
+/** The WS-attach bridge script, shipped at the package root (`bridge/`). */
+export function hermesBridgeScriptPath() {
+    const path = fileURLToPath(new URL("../bridge/hermes-ws-bridge.py", import.meta.url));
+    if (!existsSync(path))
+        throw new Error(`hermes ws-attach bridge missing: ${path}`);
+    return path;
+}
 function asRecord(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return null;
@@ -244,6 +270,8 @@ export class HermesGatewayClient {
         const attempt = this.#spawnAttempts;
         const root = resolveHermesRoot();
         const python = resolveHermesPython(root);
+        const dotEnv = loadHermesDotEnv();
+        const transport = resolveHermesTransport(dotEnv);
         const env = { ...(opts.env ?? process.env) };
         if (this.#hubSession !== undefined)
             env.SUPERD_HUB_SESSION = this.#hubSession;
@@ -253,7 +281,7 @@ export class HermesGatewayClient {
         // pi runtimes load their own native `.env`; the hermes gateway child does
         // not, and the harness env carries no provider keys — without this fill
         // every provider request dies as quota/auth regardless of model.
-        for (const [dotKey, dotValue] of Object.entries(loadHermesDotEnv())) {
+        for (const [dotKey, dotValue] of Object.entries(dotEnv)) {
             if (env[dotKey] === undefined || env[dotKey] === "")
                 env[dotKey] = dotValue;
         }
@@ -266,12 +294,11 @@ export class HermesGatewayClient {
         delete env.HERMES_CWD;
         delete env.HERMES_TUI_GATEWAY_URL;
         delete env.HERMES_TUI_SIDECAR_URL;
-        this.#child = gatewayFactory({
-            command: python,
-            args: ["-m", "tui_gateway.entry"],
-            cwd: opts.cwd ?? root,
-            env,
-        });
+        const childSpec = transport === "attach"
+            ? { command: python, args: [hermesBridgeScriptPath()], cwd: opts.cwd ?? root, env }
+            : { command: python, args: ["-m", "tui_gateway.entry"], cwd: opts.cwd ?? root, env };
+        this.#trace(`spawn transport=${transport} cmd=${childSpec.command} args=${JSON.stringify(childSpec.args)}`);
+        this.#child = gatewayFactory(childSpec);
         // The ready gate is created ONCE and survives every pre-ready respawn —
         // replacing it would orphan callers awaiting the earlier object.
         if (this.#readyPromise === null) {
@@ -283,7 +310,9 @@ export class HermesGatewayClient {
             // surface an unhandledRejection when this gate rejects (timeout/close).
             this.#readyPromise.catch(() => { });
         }
-        const readyTimeoutMs = opts.readyTimeoutMs ?? READY_TIMEOUT_MS;
+        // attach: gateway discovery (5s) or an idle-exit daemon start (ensure
+        // timeout 30s) can exceed the stdio boot budget before gateway.ready.
+        const readyTimeoutMs = opts.readyTimeoutMs ?? (transport === "attach" ? 45_000 : READY_TIMEOUT_MS);
         this.#readyTimer = setTimeout(() => {
             this.#preReadyFailure(new Error(`timed out waiting for gateway.ready after ${readyTimeoutMs}ms (spawn attempt ${attempt}/${HERMES_SPAWN_ATTEMPTS}); stderr tail:\n${this.#stderrTail()}`));
         }, readyTimeoutMs);

package/agent-hermes/dist/index.js

@@ -364,9 +364,18 @@ export class HermesProvider extends Service {
             throw new Error(`cannot resume session "${id}": no Hermes gateway session is recorded for this Dash session id`);
         }
         const persistence = this.requirePersistence("resume");
-        if ((record.gatewayStoredSessionId === null || record.gatewayStoredSessionId === undefined)
-            && (await readStoredEvents(persistence, id, options.signal)).some(event => event.type === "turn/start" || event.type === "user/message" || event.type === "assistant/message")) {
-            throw new Error(`cannot resume session "${id}": no durable gateway session id is recorded (this record predates durable-id capture; re-create the session)`);
+        if (record.gatewayStoredSessionId === null || record.gatewayStoredSessionId === undefined) {
+            const events = await readStoredEvents(persistence, id, options.signal);
+            if (events.some(event => event.type === "turn/start" || event.type === "user/message" || event.type === "assistant/message")) {
+                if (events.some(event => event.type === "assistant/message")) {
+                    // Completed turns but no durable id: a record from before the adapter captured ids.
+                    throw new Error(`cannot resume session "${id}": no durable gateway session id is recorded (this record predates durable-id capture; re-create the session)`);
+                }
+                // Turn content with no assistant output and no durable id: the gateway never produced a
+                // session for this record (cold-start failure — e.g. the native home was owned by a
+                // running gateway). Nothing in it reached the model, so resume has nothing to attach to.
+                throw new Error(`cannot resume session "${id}": no durable gateway session id is recorded (the Hermes gateway failed before this session was created; its recorded turn never reached the model — re-create the session)`);
+            }
         }
         // Spawn cwd comes from the recorded pairing — re-realpath and re-verify.
         const spawnCwd = validatedCwd(record.cwd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-dsh",
-  "version": "0.3.3-c",
+  "version": "0.3.4-a",
   "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",
@@ -61,6 +61,7 @@
     "agent-hermes/dist",
     "agent-hermes/package.json",
     "agent-hermes/cordis.patch.yml",
+    "agent-hermes/bridge",
     "agent-agy/dist",
     "agent-agy/package.json",
     "agent-agy/cordis.patch.yml",