super-dsh 0.1.0 → 0.1.2

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

@@ -0,0 +1,289 @@
+/**
+ * Hermes TUI-gateway event → omp wire vocabulary projection (AW-H Task 2).
+ *
+ * The wire vocabulary is the same internal `Wire*` vocabulary as
+ * agent-codex/src/codex-events.ts (ported from agent-omp/src/rpc-types.ts);
+ * the omp event `type` STRINGS are kept verbatim (`agent_start` / `turn_start`
+ * / `message_start` / `message_update` / `message_end` /
+ * `tool_execution_start` / `tool_execution_end` / `turn_end` / `agent_end`)
+ * so the Task 7 agent.ts port consumes the exact same switch it consumes on
+ * the codex line.
+ *
+ * The projector is a PURE function `projectGatewayEvent(type, payload, ctx)`:
+ * no I/O, no timers, no module state. Accumulation (open assistant text,
+ * thinking buffer, seen tool ids) is the CLIENT's job — the read-only
+ * `ProjectionCtx { turnOpen, openAssistant }` is the client's per-frame
+ * answer to the only two questions the projection needs state for.
+ *
+ * Projection mapping (as-built; grounded in the Task 1 live fixture
+ * `agent-hermes/spike-events@1` + gateway source pins):
+ *
+ *   message.start (no payload key)     → turn open: [agent_start, turn_start,
+ *                                        message_start(assistant, [])]; turn
+ *                                        already open: message_start alone.
+ *                                        Hermes has NO thread.started /
+ *                                        turn.started events — message.start
+ *                                        IS the live-pinned turn-open bracket
+ *                                        (Task 1 §9.2 ①), gated on
+ *                                        !ctx.turnOpen so repeats stay bare.
+ *   message.delta {text}               → message_update(assistantMessageEvent
+ *                                        { type:"text_delta", contentIndex:0,
+ *                                        delta }) — healed with a leading
+ *                                        message_start when !ctx.openAssistant.
+ *   thinking.delta {text}              → null (incl. empty-string frames —
+ *   reasoning.delta {text, verbose?}   →  live display is the client's
+ *                                        accumulation; the durable thinking
+ *                                        block rides message.complete.reasoning)
+ *   tool.start {tool_id, name,         → tool_execution_start {toolCallId,
+ *     context, args?, args_text?}        toolName, args, argumentsJson }
+ *                                        (id field is `tool_id` — Task 1 §3④
+ *                                        correction; args_text, when present,
+ *                                        is the RAW JSON string and wins)
+ *   tool.complete {tool_id, name,      → tool_execution_end {toolCallId,
+ *     args, result, duration_s?,         toolName, result:{content,isError},
+ *     summary?, inline_diff?, …}         isError, duration_s? } — result is a
+ *                                        parsed-JSON value or raw string;
+ *                                        objects render as pretty JSON text,
+ *                                        strings verbatim, summary is the
+ *                                        fallback. isError is ALWAYS false in
+ *                                        V1: the gateway pins no error/status
+ *                                        field on tool.complete.
+ *   message.complete {text, usage,     → [message_end, turn_end, agent_end]
+ *     status:"complete", reasoning?}     — message_end carries the text block
+ *                                        (+ trailing thinking block from
+ *                                        `reasoning`) and the RAW hermes usage
+ *                                        verbatim at `usage` (brief table);
+ *                                        turn_end carries the same usage at
+ *                                        `data.usage` (the agent.ts seam —
+ *                                        codex parity) plus `data.status`;
+ *                                        agent_end closes the run.
+ *   message.complete {status:"error",  → same terminal triple, with
+ *     error, recoverable, partial?, …}   message_end {stopReason:"error",
+ *                                        errorMessage, content from `partial`}
+ *                                        (failure classification stays in
+ *                                        agent.ts's wireFailure, unchanged)
+ *   message.complete                   → same triple, plain message_end with
+ *     {status:"interrupted", …}          the partial text; the interrupt
+ *                                        intent itself reaches the client via
+ *                                        its own cancel path, not the wire.
+ *   error {message}                    → agent_end (data.error.message),
+ *                                        ONLY while ctx.turnOpen — abnormal
+ *                                        finish with no message.complete.
+ *   session.info (running true/false),   } null — log-only. The settled pair
+ *   session.usage, status.update,        } message.complete →
+ *   approval.request,                    } session.info(running=false) is the
+ *   sessions.changed,                    } CLIENT's turn-boundary signal
+ *   gateway.ready, message.interim,      } (Task 1 §9.2), never wire.
+ *   session.title {session_id, title}   → session_title {name} (pi wire
+ *                                        parity) — the AGENT mirrors it as
+ *                                        `session/title` (provider source);
+ *                                        empty/missing titles stay null.
+ *   todo.updated {todos, revision}      → todo_updated {todos: DSH-shaped
+ *                                        [{content, status}]} — the AGENT
+ *                                        appends the log-only `todo/write`
+ *                                        whole-list snapshot. Items map:
+ *                                        trimmed non-empty content, status
+ *                                        ∈ {pending, in_progress, completed};
+ *                                        `cancelled`/unknown-status and
+ *                                        duplicate-content items are dropped
+ *                                        (DSH's todo/write invariant has no
+ *                                        cancelled status and forbids
+ *                                        repeated content). A well-formed
+ *                                        empty list passes through — a real
+ *                                        clear (revision ≥ 1 per gateway).
+ *   anything unrecognized                 }
+ *
+ * KNOWN SEAM (documented for Task 3): gateway tool-frame emission is
+ * CONDITIONAL and the gates differ between start and complete (server.py:
+ * _on_tool_start requires progress-enabled ∥ lifecycle-required-for-ui;
+ * _on_tool_complete additionally fires for inline_diff ∥ todo tools) — so an
+ * orphan tool.complete without a prior tool.start is possible. The projector
+ * cannot dedup/pair without state (purity contract); the CLIENT, which owns
+ * accumulation state, should synthesize the missing tool_execution_start for
+ * an unseen toolCallId before forwarding the end.
+ *
+ * Never throws: any internal failure collapses to `null` (fail-soft).
+ */
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function asText(value) {
+    return typeof value === "string" ? value : "";
+}
+function assistantMessageStart() {
+    return { type: "message_start", message: { role: "assistant", content: [] } };
+}
+function textDelta(delta) {
+    const assistantMessageEvent = { type: "text_delta", contentIndex: 0, delta };
+    return { type: "message_update", assistantMessageEvent };
+}
+/** Render a tool.complete `result` (parsed JSON value or raw string) as the wire result text. */
+function renderToolResult(payload) {
+    const result = payload.result;
+    if (typeof result === "string")
+        return result;
+    if (result !== null && result !== undefined) {
+        const rendered = JSON.stringify(result, null, 2);
+        if (typeof rendered === "string")
+            return rendered;
+    }
+    return asText(payload.summary);
+}
+/**
+ * message.complete — the turn-terminal event (Task 1 §9.2 ①). Emits the
+ * terminal triple [message_end, turn_end, agent_end] for every status
+ * ("complete" | "interrupted" | "error"): the wire run bracket that
+ * agent_start/turn_start opened at message.start closes here.
+ */
+function messageComplete(p) {
+    const status = asText(p.status);
+    const usage = asRecord(p.usage);
+    const content = [];
+    const message = { role: "assistant", content };
+    if (status === "error") {
+        const partial = asText(p.partial);
+        if (partial !== "")
+            content.push({ type: "text", text: partial });
+        message.stopReason = "error";
+        const error = asText(p.error);
+        if (error !== "")
+            message.errorMessage = error;
+    }
+    else {
+        content.push({ type: "text", text: asText(p.text) });
+        const reasoning = asText(p.reasoning);
+        if (reasoning !== "")
+            content.push({ type: "thinking", thinking: reasoning });
+    }
+    const end = { type: "message_end", message };
+    if (usage !== null)
+        end.usage = usage;
+    const data = {};
+    if (usage !== null)
+        data.usage = usage;
+    if (status !== "")
+        data.status = status;
+    const turnEnd = Object.keys(data).length === 0 ? { type: "turn_end" } : { type: "turn_end", data };
+    return [end, turnEnd, { type: "agent_end" }];
+}
+/**
+ * Project one Hermes gateway event frame (duck-typed: the client passes
+ * `params.type` and `params.payload` — payload is OPTIONAL, `message.start`
+ * carries none) onto the omp wire vocabulary. Returns one event, an ordered
+ * array, or null for ignorable/malformed input. Never throws.
+ */
+export function projectGatewayEvent(type, payload, ctx) {
+    try {
+        if (typeof type !== "string")
+            return null;
+        const turnOpen = ctx !== null && typeof ctx === "object" && ctx.turnOpen === true;
+        const openAssistant = ctx !== null && typeof ctx === "object" && ctx.openAssistant === true;
+        switch (type) {
+            case "message.start": {
+                // Turn-open bracket: no payload key exists on this frame.
+                const start = assistantMessageStart();
+                return turnOpen ? start : [{ type: "agent_start" }, { type: "turn_start" }, start];
+            }
+            case "message.delta": {
+                const p = asRecord(payload);
+                if (p === null)
+                    return null;
+                const update = textDelta(asText(p.text));
+                return openAssistant ? update : [assistantMessageStart(), update];
+            }
+            case "thinking.delta":
+            case "reasoning.delta":
+                // Folded into the final message_end via message.complete.reasoning;
+                // live display is the client's accumulation. Never wire.
+                return null;
+            case "tool.start": {
+                const p = asRecord(payload);
+                if (p === null)
+                    return null;
+                const args = asRecord(p.args) ?? {};
+                // args_text (verbose sessions) is the RAW string — keep it verbatim,
+                // mirroring codex's raw mcp argumentsJson seam.
+                const argumentsJson = typeof p.args_text === "string" ? p.args_text : JSON.stringify(args);
+                return {
+                    type: "tool_execution_start",
+                    toolCallId: asText(p.tool_id),
+                    toolName: asText(p.name),
+                    args,
+                    argumentsJson,
+                };
+            }
+            case "tool.complete": {
+                const p = asRecord(payload);
+                if (p === null)
+                    return null;
+                const end = {
+                    type: "tool_execution_end",
+                    toolCallId: asText(p.tool_id),
+                    toolName: asText(p.name),
+                    result: { content: [{ type: "text", text: renderToolResult(p) }], isError: false },
+                    isError: false,
+                };
+                if (typeof p.duration_s === "number")
+                    end.duration_s = p.duration_s;
+                return end;
+            }
+            case "message.complete": {
+                const p = asRecord(payload);
+                if (p === null)
+                    return null;
+                return messageComplete(p);
+            }
+            case "error": {
+                const p = asRecord(payload);
+                if (p === null || !turnOpen)
+                    return null; // abnormal finish, only mid-turn
+                const message = asText(p.message);
+                return message === "" ? { type: "agent_end" } : { type: "agent_end", data: { error: { message } } };
+            }
+            case "session.title": {
+                // Gateway-owned title → session_title wire event; the AGENT mirrors it
+                // as `session/title` (pi pattern). Empty/missing titles stay null.
+                const p = asRecord(payload);
+                const title = typeof p?.title === "string" ? p.title : "";
+                return title === "" ? null : { type: "session_title", name: title };
+            }
+            case "todo.updated": {
+                // Whole-list todo snapshot {todos, revision} → todo_updated with
+                // DSH-shaped items; the AGENT appends the log-only `todo/write`.
+                // Mapping: trimmed non-empty content; status ∈ {pending, in_progress,
+                // completed} (gateway `cancelled`/unknown statuses drop); duplicate
+                // content drops (the DSH todo/write invariant forbids repeats). A
+                // well-formed empty list passes through — a real clear (revision ≥ 1).
+                const p = asRecord(payload);
+                if (p === null || !Array.isArray(p.todos))
+                    return null;
+                const todos = [];
+                const seenContent = new Set();
+                for (const item of p.todos) {
+                    if (item === null || typeof item !== "object" || Array.isArray(item))
+                        continue;
+                    const raw = item;
+                    const content = typeof raw.content === "string" ? raw.content.trim() : "";
+                    if (content === "" || seenContent.has(content))
+                        continue;
+                    const status = raw.status;
+                    if (status !== "pending" && status !== "in_progress" && status !== "completed")
+                        continue;
+                    seenContent.add(content);
+                    todos.push({ content, status });
+                }
+                return { type: "todo_updated", todos };
+            }
+            default:
+                // session.info / session.usage / status.update /
+                // approval.request / sessions.changed /
+                // gateway.ready / message.interim / unknown → ignorable (S5).
+                return null;
+        }
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,158 @@
+/**
+ * DSH-session ↔ Hermes-gateway-session identity map (the "mapping only"
+ * model, 2026-09-17).
+ *
+ * The DSH session id is the authority: it is supplied by the harness at
+ * create/resume and is what the API layer routes on. The gateway's session id
+ * only materializes after the first prompt, so the pairing is persisted here,
+ * in an adapter-owned JSON file in the hermes world's DSH-side app dir (NOT
+ * hermes data — the hermes runtime keeps its native `~/.hermes` home since the
+ * 2026-09-17 user ruling; DSH bookkeeping never lives in the runtime's native
+ * tree):
+ *
+ *   `<appDir>/dsh-sessions.json`   (`<DSH home>/agents/hermes/dsh-sessions.json`)
+ *
+ * Shape: `{ "<dshSessionId>": { gatewaySessionId, cwd, createdAt, preset } }` —
+ * `gatewaySessionId` is `null` until the gateway session materializes (the
+ * first prompt is pending). Writes are atomic (temp file + rename); reads are
+ * fail-soft (malformed JSON reads as empty) and never throw, so a corrupt map
+ * degrades to "unknown session" rather than breaking every operation.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+/** Prod homes that must never be resolved into (repo red line). */
+const PROD_HOMES = [join(homedir(), ".dsh"), join(homedir(), ".superd")];
+function assertNotProdHome(path, label) {
+    if (PROD_HOMES.includes(path) || PROD_HOMES.some((p) => path.startsWith(`${p}/`))) {
+        throw new Error(`hermes-store: refusing prod home as ${label}: ${path}`);
+    }
+}
+/**
+ * The adapter's DSH-side state dir — `<dshHome>/agents/hermes`. This is DSH-SIDE
+ * adapter state (the identity map), NOT hermes data: hermes keeps its native
+ * `~/.hermes` home (user ruling 2026-09-17) and this module never touches it.
+ *
+ * Two forms (2026-09-17 r2 fix):
+ *   - Form-A: the boot-provided home (or `$DSH_HOME`) is the DSH home ROOT —
+ *     the per-agent world dir is NESTED, so the map lands at
+ *     `<root>/agents/hermes/dsh-sessions.json`.
+ *   - Form-B: the boot-provided home is ALREADY the world home
+ *     (`<root>/agents/hermes`) — passed through as-is, never double-nested.
+ * Precedence: explicit home (boot-provided `dshHomePath`), then `$DSH_HOME`,
+ * then the line's historical test-home default. Prod-guarded.
+ */
+export function resolveHermesAppDir(home) {
+    const base = resolve(home ?? process.env.DSH_HOME ?? join(process.cwd(), ".tests", "aw"));
+    // Form-B world home is already `<root>/agents/hermes` — never double-nest.
+    const dir = basename(base) === "hermes" && basename(dirname(base)) === "agents" ? base : join(base, "agents", "hermes");
+    assertNotProdHome(dir, "hermes app dir");
+    return dir;
+}
+/** The map file's path inside the adapter's DSH-side app dir. */
+export function sessionMapPath(home) {
+    return join(resolveHermesAppDir(home), "dsh-sessions.json");
+}
+/** Read the map. Fail-soft: a missing or malformed file reads as `{}`. */
+export function readSessionMap(home) {
+    let raw;
+    try {
+        raw = readFileSync(sessionMapPath(home), "utf8");
+    }
+    catch {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    const out = {};
+    for (const [id, value] of Object.entries(parsed)) {
+        const record = coerceRecord(value);
+        if (record !== undefined)
+            out[id] = record;
+    }
+    return out;
+}
+/** Validate one entry; malformed entries are dropped (fail-soft). */
+function coerceRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const cwd = raw["cwd"];
+    const createdAt = raw["createdAt"];
+    if (typeof cwd !== "string" || cwd === "")
+        return undefined;
+    const gatewaySessionId = raw["gatewaySessionId"];
+    const gatewayStoredSessionId = raw["gatewayStoredSessionId"];
+    const preset = raw["preset"];
+    return {
+        gatewaySessionId: typeof gatewaySessionId === "string" && gatewaySessionId !== "" ? gatewaySessionId : null,
+        gatewayStoredSessionId: typeof gatewayStoredSessionId === "string" && gatewayStoredSessionId !== "" ? gatewayStoredSessionId : null,
+        cwd,
+        createdAt: typeof createdAt === "number" && Number.isFinite(createdAt) ? createdAt : 0,
+        preset: typeof preset === "string" && preset !== "" ? preset : null,
+    };
+}
+/** One session's record, or `undefined` when the id is unknown. */
+export function sessionRecord(home, dshSessionId) {
+    return readSessionMap(home)[dshSessionId];
+}
+/**
+ * Insert or merge one session's record and persist the map atomically
+ * (temp file + rename, same directory). Merge semantics: an omitted `patch`
+ * field keeps the stored value; `gatewaySessionId: null` explicitly records
+ * "not yet materialized" (first prompt pending). Throws only when the write
+ * itself fails — the caller owns that decision (create treats an unwritable
+ * map as fatal; the observation path logs and continues).
+ */
+export function upsertSession(home, dshSessionId, patch) {
+    const path = sessionMapPath(home);
+    const map = readSessionMap(home);
+    const previous = map[dshSessionId];
+    const next = {
+        gatewaySessionId: patch.gatewaySessionId !== undefined ? patch.gatewaySessionId : previous?.gatewaySessionId ?? null,
+        gatewayStoredSessionId: patch.gatewayStoredSessionId !== undefined ? patch.gatewayStoredSessionId : previous?.gatewayStoredSessionId ?? null,
+        cwd: patch.cwd !== undefined ? patch.cwd : previous?.cwd ?? "",
+        createdAt: patch.createdAt !== undefined ? patch.createdAt : previous?.createdAt ?? Date.now(),
+        preset: patch.preset !== undefined ? patch.preset : previous?.preset ?? null,
+    };
+    map[dshSessionId] = next;
+    writeMapAtomic(path, map);
+    return next;
+}
+/** Drop one session's record (idempotent; failure to persist rethrows). */
+export function forgetSession(home, dshSessionId) {
+    const path = sessionMapPath(home);
+    if (!existsSync(path))
+        return;
+    const map = readSessionMap(home);
+    if (map[dshSessionId] === undefined)
+        return;
+    delete map[dshSessionId];
+    writeMapAtomic(path, map);
+}
+/** Atomic persist: temp file (mode 0600) + same-directory rename. */
+function writeMapAtomic(path, map) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(map, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        renameSync(temp, path);
+    }
+    catch (error) {
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch {
+            // The rename failure is primary.
+        }
+        throw error;
+    }
+}

package/agent-hermes/dist/inbox.js

@@ -0,0 +1,53 @@
+export class Inbox {
+    #nextTurn = [];
+    #nextStep = [];
+    get nextTurn() {
+        return this.#nextTurn;
+    }
+    get nextStep() {
+        return this.#nextStep;
+    }
+    clear() {
+        this.#nextTurn = [];
+        this.#nextStep = [];
+    }
+    append(target, message) {
+        this.#list(target).push(message);
+    }
+    prepend(target, message) {
+        this.#list(target).unshift(message);
+    }
+    replace(messageId, newMessage) {
+        const list = this.#find(messageId);
+        if (list === undefined)
+            return false;
+        const index = list.findIndex((message) => message.id === messageId);
+        if (index < 0)
+            return false;
+        list.splice(index, 1, newMessage);
+        return true;
+    }
+    remove(messageId) {
+        const list = this.#find(messageId);
+        if (list === undefined)
+            return false;
+        const index = list.findIndex((message) => message.id === messageId);
+        if (index < 0)
+            return false;
+        list.splice(index, 1);
+        return true;
+    }
+    splice(target, start, deleteCount, inserted) {
+        return this.#list(target).splice(start, deleteCount, ...inserted);
+    }
+    #list(target) {
+        return target === "next-turn" ? this.#nextTurn : this.#nextStep;
+    }
+    #find(messageId) {
+        if (this.#nextTurn.some((message) => message.id === messageId))
+            return this.#nextTurn;
+        if (this.#nextStep.some((message) => message.id === messageId))
+            return this.#nextStep;
+        return undefined;
+    }
+}