@sagentlab/navarch-runtime 0.1.112 → 0.1.117

package/node_modules/@muse-code/sdk/dist/src/pending/pending-command-set.js

@@ -0,0 +1,468 @@
+/**
+ * `PendingCommand`: the client-side fold over pending commands.
+ *
+ * Normative source: tdd SS4.13 (owned by decision record D-032). This module
+ * implements that subsection and does not re-derive it; every rule below
+ * quotes or cites the clause it realizes. It is **client state only** — no
+ * wire event, method, snapshot member, or durable record (INV-007), and it
+ * never crosses the wire.
+ *
+ * The full fold is `S' = f(S, server events, pending client events)`: server
+ * events remain the only source of durable truth, and a `PendingCommand`
+ * entry is a rendering of the client's own intent.
+ *
+ * The entry itself is client-local by ruling, and its join keys (`commandId`,
+ * `turnId`, `itemId`) are opaque strings by protocol rule (SS3.1.4, SS4.1).
+ * The wire vocabulary it touches is fully generated: spec 206 Phase 11
+ * (#22772) enrolled the `turn/start` ack and the `-32030` `commandRejected`
+ * registry row, so INV-001's one recorded interim exception is discharged
+ * here — nothing below restates a wire shape.
+ *
+ * Every comparison against a wire value goes through a constant ANNOTATED
+ * with the generated vocabulary (`Extract<...>`), which is what makes a
+ * misspelling a compile error. Comparing a bare literal against the open
+ * `ErrorKind`/`TurnStartDisposition` unions typechecks either way — that
+ * invisibility is precisely what the exception cost.
+ */
+import { MuseSessionDiscardedError } from "../errors.js";
+/**
+ * The JSON-RPC code for a durable command rejection (tdd SS3.1.2, Appendix B).
+ *
+ * `@muse-code/msp` is a types-only package, so the registry's CODE cannot be
+ * imported the way its types can. It is named exactly once, here, and
+ * `pending-command-wire-binding.test.ts` pins it to the `commandRejected` row
+ * in `schema/msp/stable/msp.schema.json` — the same pin shape
+ * `EXPECTED_SCHEMA_FINGERPRINT` uses, so a schema advance that moves the code
+ * reds this lane instead of silently leaving the SDK settling on a dead code.
+ */
+export const COMMAND_REJECTED_CODE = -32030;
+/**
+ * The registry row's `kind`, bound to the CLOSED generated vocabulary.
+ *
+ * `ErrorKind` is open (`| (string & {})`), so a typo compared against it still
+ * typechecks. `MspErrorDataKind` is the closed registry vocabulary, so this
+ * annotation makes a misspelling fail `tsc`.
+ */
+export const COMMAND_REJECTED_KIND = "commandRejected";
+/** The `"queued"` disposition, bound so a misspelling fails `tsc` (SS3.2). */
+const QUEUED_DISPOSITION = "queued";
+/**
+ * Tracks the commands you have submitted that the server has not yet woven
+ * into the view: their optimistic display order, acknowledgements, replay
+ * answers at reconnect, and retirements. `Session` owns and drives one per
+ * conversation; read it through the session's pending view.
+ */
+export class PendingCommandSet {
+    #entries = new Map();
+    #ephemeralDiscardedCommandIds;
+    #discarded = false;
+    #nextSubmissionIndex = 0;
+    constructor(options) {
+        this.#ephemeralDiscardedCommandIds = options?.discardedCommandIds ?? new Set();
+    }
+    /**
+     * Record a submission. `anchorAfterItemId` is the last item present in the
+     * client's fold right now (SS4.13 insertion point).
+     */
+    submitted(params) {
+        // Replay check FIRST: for an id this set actually retired, "cannot be
+        // replayed against a new host" is the precise diagnosis, and the generic
+        // set-closed message below would bury it.
+        this.#assertNotEphemeralReplay(params.commandId);
+        // Then the whole SET, not just the ids it retired. A brand-new submit
+        // after an ephemeral host died would otherwise be accepted and retired
+        // `terminalUnknown` by the next discharge — "we don't know whether this
+        // ran" about input provably never sent to any host, which is the
+        // fabricated annotation SS2.13.3b exists to forbid.
+        this.#assertSessionActive();
+        if (this.#entries.has(params.commandId)) {
+            // A resubmit of the same commandId is the sanctioned exactly-once
+            // retry (SS3.1.1); it does not create a second entry and MUST NOT
+            // move the original's anchor.
+            return;
+        }
+        const entry = {
+            commandId: params.commandId,
+            input: params.input,
+            anchorAfterItemId: params.anchorAfterItemId ?? null,
+            submissionIndex: this.#nextSubmissionIndex++,
+        };
+        if (params.displayText !== undefined)
+            entry.displayText = params.displayText;
+        this.#entries.set(params.commandId, entry);
+    }
+    /** The submit (or a replay) was acked. */
+    acked(commandId, ack) {
+        const entry = this.#entries.get(commandId);
+        if (entry === undefined)
+            return;
+        entry.ack = ack;
+    }
+    /**
+     * The submit (or a replay) answered with an error.
+     *
+     * Only a durable `commandRejected` (-32030) is a settlement. Every other
+     * error admits nothing — the other SS3.1.2 admission errors and SS1's
+     * envelope errors, `inputTooLarge` among them — so the entry HOLDS while
+     * the client retries with the same `commandId` (SS4.13 "Nothing-admitted
+     * errors are not settlements").
+     */
+    ackErrored(commandId, error) {
+        const entry = this.#entries.get(commandId);
+        if (entry === undefined)
+            return "held";
+        if (!PendingCommandSet.isSettlement(error))
+            return "held";
+        return this.#retire(entry, this.#rejectionRetirement(entry, error));
+    }
+    /**
+     * The client has decided to stop retrying a nothing-admitted error. The
+     * entry must not linger as a durable-looking echo (SS4.13).
+     */
+    stopRetrying(commandId) {
+        const entry = this.#entries.get(commandId);
+        if (entry === undefined)
+            return undefined;
+        return this.#retire(entry, {
+            kind: "retryAbandonedByClient",
+            commandId,
+            input: entry.input,
+            restoreToComposer: true,
+        });
+    }
+    /**
+     * A `userMessage` item carrying this `commandId` folded in: the entry
+     * materialized and the item replaces it at the item's own transcript
+     * position (SS4.13 "Materialized").
+     *
+     * Multi-client echo de-duplication falls out of the same join: a
+     * `userMessage` with no matching local entry is another client's
+     * submission — this returns `undefined` and the caller renders it plainly.
+     */
+    observedUserMessage(commandId, itemId) {
+        const entry = this.#entries.get(commandId);
+        if (entry === undefined)
+            return undefined;
+        return this.#retire(entry, { kind: "materialized", commandId, matchedBy: "userMessage", itemId });
+    }
+    /**
+     * A reclaim this client actually observed (its own reclaim ack, or any live
+     * fold D-024's lane charters). Retire immediately — same composer restore,
+     * without waiting for a snapshot join (SS4.13 "Reclaimed").
+     */
+    observedReclaim(commandId) {
+        const entry = this.#entries.get(commandId);
+        if (entry === undefined)
+            return undefined;
+        return this.#retire(entry, {
+            kind: "reclaimed",
+            commandId,
+            input: entry.input,
+            restoreToComposer: true,
+        });
+    }
+    /**
+     * Queue movement: a `turn/started` or `turn/completed` for a turn that is
+     * NOT the entry's own.
+     *
+     * SS4.3 carries no view event for a command-intake settlement, so a
+     * post-ack rejection reaches a live client only by replay: on each such
+     * event a client holding an acked-QUEUED entry MUST re-verify it by
+     * replaying its `commandId`. Queue movement is the trigger precisely
+     * because a queued turn's fate is decided at its launch boundary — no
+     * polling loop and no invented timeout (SS3.1.3 stays intact).
+     *
+     * @returns the `commandId`s the caller must replay.
+     */
+    observedQueueMovement(turnId) {
+        const out = [];
+        for (const entry of this.#entries.values()) {
+            if (entry.ack === undefined)
+                continue;
+            if (entry.ack.disposition !== QUEUED_DISPOSITION)
+                continue;
+            if (entry.ack.turnId === turnId)
+                continue; // the entry's own turn
+            out.push(entry.commandId);
+        }
+        return out;
+    }
+    /**
+     * Feed back a `commandId` replay answer (SS3.1.1 — always safe).
+     *
+     * Three shapes, per SS4.13's rejected/abandoned arms:
+     *  - a durable rejection: retire (reason `"abandoned"` → Abandoned arm,
+     *    any other reason → Rejected arm);
+     *  - the original ack, still pending: keep waiting;
+     *  - an ack whose staleness only a snapshot can prove: keep waiting — the
+     *    reclaimed signature needs `queuedTurns` in hand (`joinSnapshot`).
+     */
+    replayAnswered(commandId, answer) {
+        this.#assertNotEphemeralReplay(commandId);
+        const entry = this.#entries.get(commandId);
+        if (entry === undefined)
+            return "held";
+        if (answer.kind === "ack") {
+            entry.ack = answer.ack;
+            return "held";
+        }
+        if (!PendingCommandSet.isSettlement(answer.error))
+            return "held";
+        return this.#retire(entry, this.#rejectionRetirement(entry, answer.error));
+    }
+    /**
+     * Reconnect with NO snapshot (`history.mode: "none"`, the default
+     * cursor-resume path). There is no join to run, so reconnect itself is the
+     * trigger: replay each ACKED entry's `commandId` once; resubmit each
+     * UNACKED entry's same `commandId` once before any retire-to-composer.
+     *
+     * Without `queuedTurns` in hand the reclaimed signature is undecidable, so
+     * a stale `"queued"` ack waits for the next snapshot join or queue
+     * movement — never a locally invented terminal.
+     */
+    reconnectedWithoutSnapshot() {
+        // Once-per-plan comes from the single `#ordered()` pass (each entry is
+        // visited exactly once); a NEW reconnect demands again, which SS3.1.1
+        // same-`commandId` idempotency makes safe — a once-per-lifetime latch
+        // would strand an entry whose demand was lost to a second disconnect
+        // (SS4.13 forbids).
+        const mustReplay = [];
+        const mustResubmit = [];
+        for (const entry of this.#ordered()) {
+            if (entry.ack === undefined) {
+                mustResubmit.push(entry.commandId);
+            }
+            else {
+                mustReplay.push(entry.commandId);
+            }
+        }
+        return {
+            retirements: [],
+            mustReplay,
+            mustResubmit,
+            kept: this.#ordered().map((e) => e.commandId),
+        };
+    }
+    /**
+     * Join local entries against an authoritative snapshot (SS4.9), by
+     * `commandId`. The five arms, in the order SS4.13 states them.
+     */
+    joinSnapshot(facts) {
+        // Once-per-plan comes from the single ordered pass below, exactly as in
+        // `reconnectedWithoutSnapshot`; a NEW join demands again, which SS3.1.1
+        // same-`commandId` idempotency makes safe (SS4.13 forbids stranding an
+        // entry whose demand was lost to a second disconnect).
+        const retirements = [];
+        const mustReplay = [];
+        const mustResubmit = [];
+        const userMessageItemByCommandId = new Map();
+        for (const pair of facts.userMessageCommandIds) {
+            userMessageItemByCommandId.set(pair.commandId, pair.itemId);
+        }
+        const queuedIndexByCommandId = new Map();
+        facts.queuedTurns.forEach((q, index) => queuedIndexByCommandId.set(q.commandId, index));
+        for (const entry of this.#ordered()) {
+            const { commandId } = entry;
+            // Arm 1 — materialized: a userMessage item (its own item id is in the
+            // join facts), or the activeTurn's commandId (no item id in hand — the
+            // retirement says so via matchedBy, never aliasing the command id).
+            const userMessageItemId = userMessageItemByCommandId.get(commandId);
+            if (userMessageItemId !== undefined) {
+                retirements.push(this.#retire(entry, {
+                    kind: "materialized",
+                    commandId,
+                    matchedBy: "userMessage",
+                    itemId: userMessageItemId,
+                }));
+                continue;
+            }
+            if (facts.activeTurn?.commandId === commandId) {
+                retirements.push(this.#retire(entry, { kind: "materialized", commandId, matchedBy: "activeTurn" }));
+                continue;
+            }
+            // Arm 2 — server-confirmed queued: keep, reordered to queuedTurns order.
+            const queuedIndex = queuedIndexByCommandId.get(commandId);
+            if (queuedIndex !== undefined) {
+                entry.queuedOrder = queuedIndex;
+                // A kept entry re-anchors after the last item of the reconciled fold.
+                entry.anchorAfterItemId = facts.lastItemId;
+                continue;
+            }
+            // Arm 3 — an acked STEER matches neither activeTurn.commandId nor
+            // queuedTurns by design: it is pending on the running turn's
+            // PendingSteerQueue (SS3.3), not settled. Keep it as server-confirmed
+            // pending; retiring here shows "never ran" and then double-sends when
+            // the steer delivers. A steer keeps its submission anchor — it has no
+            // launch position.
+            if (entry.ack !== undefined &&
+                facts.activeTurn !== null &&
+                entry.ack.turnId === facts.activeTurn.turnId) {
+                continue;
+            }
+            // Arm 4 — acked, matching nothing: resolve by replaying the commandId.
+            if (entry.ack !== undefined) {
+                mustReplay.push(commandId);
+                continue;
+            }
+            // Arm 5 — unacked, and the join did not match it. The intake is durable
+            // BEFORE the ack (SS3.1.3), and a join miss does not prove the intake
+            // was never written (a parked steer is in none of the join surfaces),
+            // so demand a SAME-commandId resubmit before any retire-to-composer.
+            mustResubmit.push(commandId);
+        }
+        return {
+            retirements,
+            mustReplay,
+            mustResubmit,
+            kept: this.#ordered().map((e) => e.commandId),
+        };
+    }
+    /**
+     * The reclaimed signature, decidable only with a snapshot in hand: an
+     * acked-queued entry ABSENT from the snapshot's `queuedTurns` whose replay
+     * still answers the stale `"queued"` ack retires as *reclaimed* at the
+     * snapshot join (SS4.13 "Reclaimed").
+     *
+     * Call this with the replay answer for a `mustReplay` entry produced by
+     * `joinSnapshot`, passing the same snapshot's `queuedTurns` commandIds.
+     */
+    resolveReplayAtJoin(commandId, answer, snapshotQueuedCommandIds) {
+        this.#assertNotEphemeralReplay(commandId);
+        const entry = this.#entries.get(commandId);
+        if (entry === undefined)
+            return "held";
+        if (answer.kind === "error") {
+            if (!PendingCommandSet.isSettlement(answer.error))
+                return "held";
+            return this.#retire(entry, this.#rejectionRetirement(entry, answer.error));
+        }
+        const stillQueuedByServer = new Set(snapshotQueuedCommandIds).has(commandId);
+        if (answer.ack.disposition === QUEUED_DISPOSITION && !stillQueuedByServer) {
+            // The snapshot just proved this ack stale.
+            return this.#retire(entry, {
+                kind: "reclaimed",
+                commandId,
+                input: entry.input,
+                restoreToComposer: true,
+            });
+        }
+        // A still-pending "steered" or "started" ack: the entry stays pending and
+        // materializes or settles later. Never promote it locally.
+        entry.ack = answer.ack;
+        return "held";
+    }
+    /**
+     * Abnormal death of an EPHEMERAL-profile host (SS2.13, SS4.4.3 carve-out):
+     * nothing is ever settled, replaying a `commandId` at a new host is
+     * forbidden, and every entry falls under the discard obligation as
+     * terminal-unknown — a client-side annotation, never a wire fact.
+     */
+    discardEphemeral() {
+        const out = [];
+        for (const entry of this.#ordered()) {
+            this.#ephemeralDiscardedCommandIds.add(entry.commandId);
+            out.push(this.#retire(entry, {
+                kind: "terminalUnknown",
+                commandId: entry.commandId,
+                input: entry.input,
+            }));
+        }
+        this.#discarded = true;
+        return out;
+    }
+    /** Has the ephemeral discard closed this set? */
+    get discarded() {
+        return this.#discarded;
+    }
+    #assertSessionActive() {
+        if (this.#discarded) {
+            throw new MuseSessionDiscardedError("ephemeral session was discarded after abnormal host death; it accepts no new submissions");
+        }
+    }
+    #assertNotEphemeralReplay(commandId) {
+        if (this.#ephemeralDiscardedCommandIds.has(commandId)) {
+            throw new MuseSessionDiscardedError(`ephemeral host died; commandId \`${commandId}\` cannot be replayed against a new host`);
+        }
+    }
+    /**
+     * Entries in render order.
+     *
+     * Before any join this is submission order. After a join, entries the
+     * server confirmed queued are re-anchored to the end of the reconciled
+     * fold and ordered among themselves by `queuedTurns` — so they sort after
+     * the submission-anchored entries (steers and unacked), which keep their
+     * own anchors. That is SS4.13's "entries render in submission order, and
+     * for queued submits the server-confirmed order wins whenever it is
+     * observed".
+     */
+    list() {
+        return this.#ordered().map((entry) => {
+            const out = {
+                commandId: entry.commandId,
+                input: entry.input,
+                anchorAfterItemId: entry.anchorAfterItemId,
+                submissionIndex: entry.submissionIndex,
+                ...(entry.displayText !== undefined ? { displayText: entry.displayText } : {}),
+                ...(entry.ack !== undefined ? { ack: entry.ack } : {}),
+                ...(entry.queuedOrder !== undefined ? { queuedOrder: entry.queuedOrder } : {}),
+            };
+            return out;
+        });
+    }
+    get(commandId) {
+        return this.list().find((e) => e.commandId === commandId);
+    }
+    has(commandId) {
+        return this.#entries.has(commandId);
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    /**
+     * Only a durable `commandRejected` (-32030) settles a command. Everything
+     * else admitted nothing (SS4.13).
+     *
+     * The registry binds `-32030` <-> `commandRejected` one-to-one (SS3.1.2
+     * Appendix B), so a response where the two fields DISAGREE is a server
+     * fault in which one field still asserts the durable rejection. Either
+     * signal settles (OR): SS3.1.2's stated bias for unfamiliar vocabulary is
+     * toward terminal ("treat unknown reasons as terminal rejections"), and
+     * holding forever on a half-asserted rejection strands the entry as the
+     * durable-looking echo SS4.13 forbids.
+     */
+    static isSettlement(error) {
+        return error.code === COMMAND_REJECTED_CODE || error.kind === COMMAND_REJECTED_KIND;
+    }
+    #rejectionRetirement(entry, error) {
+        const reason = error.reason ?? "";
+        if (reason === "abandoned") {
+            return {
+                kind: "abandoned",
+                commandId: entry.commandId,
+                input: entry.input,
+                restoreToComposer: true,
+            };
+        }
+        return {
+            kind: "rejected",
+            commandId: entry.commandId,
+            reason,
+            input: entry.input,
+            restoreToComposer: true,
+        };
+    }
+    #retire(entry, retirement) {
+        this.#entries.delete(entry.commandId);
+        return retirement;
+    }
+    #ordered() {
+        const submissionAnchored = [];
+        const launchOrdered = [];
+        for (const entry of this.#entries.values()) {
+            (entry.queuedOrder === undefined ? submissionAnchored : launchOrdered).push(entry);
+        }
+        submissionAnchored.sort((a, b) => a.submissionIndex - b.submissionIndex);
+        launchOrdered.sort((a, b) => (a.queuedOrder ?? 0) - (b.queuedOrder ?? 0));
+        return [...submissionAnchored, ...launchOrdered];
+    }
+}

package/node_modules/@muse-code/sdk/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@muse-code/sdk",
+  "version": "1.4.6",
+  "description": "TypeScript SDK for the Muse Session Protocol (MSP): connect to a Muse Code session, drive turns, and fold the event stream. Zero runtime dependencies.",
+  "license": "MIT",
+  "homepage": "https://github.com/meta-models/muse-code-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meta-models/muse-code-sdk.git",
+    "directory": "clients/sdk-ts"
+  },
+  "bugs": {
+    "url": "https://github.com/meta-models/muse-code-sdk/issues"
+  },
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "check": "tsc --build",
+    "prepack": "npm run build && node scripts/bundle-msp-types.mjs",
+    "test": "npm run build && node --test --test-timeout=300000 \"dist/test/**/*.test.js\"",
+    "qa:sdk": "npm run build && node dist/qa/bin.js"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@types/node": ">=20"
+  },
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@muse-code/msp": "*",
+    "@types/node": "26.2.0"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.112",
+  "version": "0.1.117",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through local coding agents.",
   "type": "commonjs",
   "license": "MIT",
@@ -19,10 +19,12 @@
     "opencode",
     "agent-client-protocol",
     "deepseek-harness",
-    "task-runner"
+    "task-runner",
+    "muse-code"
   ],
   "bin": {
-    "navarch-runtime": "bin/navarch.cjs"
+    "navarch-runtime": "bin/navarch.cjs",
+    "navarch-muse-mcp-bridge": "bin/muse-mcp-bridge.cjs"
   },
   "files": [
     "dist",
@@ -56,11 +58,13 @@
     "@modelcontextprotocol/sdk": "^1.30.1",
     "playwright": "1.63.0",
     "typescript": "^5.7.2",
-    "zod": "^3.25.76"
+    "zod": "^3.25.76",
+    "@muse-code/sdk": "1.4.6"
   },
   "bundleDependencies": [
     "@agentclientprotocol/sdk",
     "@modelcontextprotocol/sdk",
+    "@muse-code/sdk",
     "playwright",
     "typescript",
     "zod"