opencode-muse 0.1.0 → 0.1.2

package/README.md

@@ -16,7 +16,7 @@ Add the published package to your project-level `opencode.jsonc` (or
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["opencode-muse@0.1.0"],
+  "plugins": ["opencode-muse@0.1.2"],
 }
 ```
 
@@ -104,6 +104,16 @@ setup placeholder rather than advertising a model that will fail on use.
   tested. The plugin also allows only one active writer per workspace, so a
   new turn may be reported as busy while another is still finishing.
 
+## Troubleshooting
+
+- **"Muse Spark 1.3 Contributor" never connects after a model switch:** that
+  entry is a retired OpenCode-gateway model (`opencode/muse-spark-1.3-contributor-free`),
+  not this plugin's model. It no longer resolves anywhere, so OpenCode keeps
+  retrying and the session appears stuck on "connecting". Pick the model under
+  provider **Muse Code** — `muse/muse-profile-tbh-model-muse-spark-1.3` —
+  instead of any historical "contributor-free" entry in recent-model lists. See
+  [#26](https://github.com/pgquiles/opencode-muse/issues/26).
+
 ## Credits and references
 
 - [opencode-claude](https://github.com/openchamber/opencode-claude) — a
@@ -117,5 +127,6 @@ setup placeholder rather than advertising a model that will fail on use.
 
 ## Related projects
 
-- [opencode-muse-auth](https://github.com/TheStreamCode/opencode-muse-auth) lets OpenCode use a Muse Code subscription by extracting the credentials (API key) embedded in that subscription. Unsure this abides by the Muse Code subscription ToS (issue #12](https://github.com/TheStreamCode/opencode-muse-auth/issues/12)).
-- [Official Muse Code documenation](https://dev.meta.ai/docs/quickstart#agent-setup), describing how to use the Muse models in OpenCode via API key (a lot more expensive)
+- [opencode-muse-auth](https://github.com/TheStreamCode/opencode-muse-auth) is another credential-extraction/direct-API approach; see its [issue #12](https://github.com/TheStreamCode/opencode-muse-auth/issues/12) for its discussion of subscription-term concerns.
+- [opencode-muse-code](https://github.com/swalker326/opencode-muse-code) is an unofficial direct-API alternative. It reads the Muse CLI login, requests an API key from Meta, and sends model requests to Meta's API from OpenCode instead of routing inference through `muse serve` and MSP. Its subscription eligibility is separate from this plugin's CLI-mediated approach and has not been established by this project.
+- [Official Muse Code documentation](https://dev.meta.ai/docs/quickstart#agent-setup) describes using Muse models in OpenCode through the Meta API.

package/dist/model/language-model.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { MspCommandRejectedError, MuseBridgeError, MuseTranscriptDivergedError, MuseUnsupportedInputError, MuseUnsupportedRequestError, MspProtocolError, MspTransportError } from "../errors.js";
+import { notificationCursorKey } from "../msp/notification.js";
 import { MUSE_CONTEXT_HEADERS, readRequestContext } from "./context.js";
 import { classifyMetaRequest, makeCompactionDigest, makeLocalTitle } from "./meta.js";
 import { promptContainsCompactionFingerprint } from "../session/fingerprint.js";
@@ -93,7 +94,7 @@ function eventTurnId(notification, itemTurnIds) {
 async function* pageGapNotifications(host, sessionId, gap) {
     let cursor = gap.after;
     const requestedCursors = new Set([gap.after]);
-    const eventCursors = new Set();
+    const eventKeys = new Set();
     for (let pageNumber = 0; pageNumber < 100; pageNumber += 1) {
         const requestCursor = cursor;
         const page = await host.request("view/page", {
@@ -104,6 +105,7 @@ async function* pageGapNotifications(host, sessionId, gap) {
         });
         if (!Array.isArray(page.events))
             throw new MspProtocolError("view/page");
+        let boundaryReached = false;
         for (const event of page.events) {
             if (typeof event !== "object" || event === null)
                 throw new MspProtocolError("view/page");
@@ -112,14 +114,20 @@ async function* pageGapNotifications(host, sessionId, gap) {
             if (typeof record.method !== "string" || !params || params.sessionId !== sessionId || typeof params.viewCursor !== "string") {
                 throw new MspProtocolError("view/page");
             }
-            if (params.viewCursor === gap.next)
-                return;
-            if (eventCursors.has(params.viewCursor))
-                throw new MspProtocolError("view/page");
-            eventCursors.add(params.viewCursor);
+            const atBoundary = params.viewCursor === gap.next;
+            if (atBoundary)
+                boundaryReached = true;
             cursor = params.viewCursor;
-            yield { jsonrpc: "2.0", method: record.method, params };
+            const notification = { jsonrpc: "2.0", method: record.method, params };
+            const key = notificationCursorKey(notification);
+            if (key && eventKeys.has(key))
+                throw new MspProtocolError("view/page");
+            if (key)
+                eventKeys.add(key);
+            yield notification;
         }
+        if (boundaryReached)
+            return;
         if (page.nextCursor === null || typeof page.nextCursor !== "string"
             || page.nextCursor === requestCursor || requestedCursors.has(page.nextCursor)) {
             throw new MspProtocolError("view/page");
@@ -196,7 +204,7 @@ export async function runMuseTurn(context, input, options, runtime, transcriptFi
         const events = {
             [Symbol.asyncIterator]: async function* () {
                 const itemTurnIds = new Map();
-                const seenCursors = new Set();
+                const seenNotifications = new Set();
                 const processNotification = async function* (notification) {
                     const params = notification.params ?? {};
                     if (params.sessionId !== session.sessionId)
@@ -227,11 +235,11 @@ export async function runMuseTurn(context, input, options, runtime, transcriptFi
                             if (typeof params.after !== "string" || typeof params.next !== "string")
                                 throw new MspProtocolError("view/gap");
                             for await (const replay of pageGapNotifications(session.host, session.sessionId, { after: params.after, next: params.next })) {
-                                const replayCursor = replay.params?.viewCursor;
-                                if (typeof replayCursor === "string" && seenCursors.has(replayCursor))
+                                const replayKey = notificationCursorKey(replay);
+                                if (replayKey && seenNotifications.has(replayKey))
                                     continue;
-                                if (typeof replayCursor === "string")
-                                    seenCursors.add(replayCursor);
+                                if (replayKey)
+                                    seenNotifications.add(replayKey);
                                 for await (const output of processNotification(replay))
                                     yield output;
                                 if (terminalSeen)
@@ -239,13 +247,13 @@ export async function runMuseTurn(context, input, options, runtime, transcriptFi
                             }
                         }
                         else {
-                            const viewCursor = params.viewCursor;
-                            if (typeof viewCursor === "string" && seenCursors.has(viewCursor)) {
+                            const notificationKey = notificationCursorKey(notification);
+                            if (notificationKey && seenNotifications.has(notificationKey)) {
                                 next = await subscription.next();
                                 continue;
                             }
-                            if (typeof viewCursor === "string")
-                                seenCursors.add(viewCursor);
+                            if (notificationKey)
+                                seenNotifications.add(notificationKey);
                             for await (const output of processNotification(notification))
                                 yield output;
                             if (terminalSeen)

package/dist/model/stream.d.ts

@@ -14,7 +14,7 @@ export declare class MuseStreamMapper {
     private readonly reasoningStarted;
     private readonly itemDeltaCounts;
     private readonly itemText;
-    private readonly seenUsageCursors;
+    private readonly seenUsageNotifications;
     private readonly textParts;
     private terminalUsage;
     private callUsage;

package/dist/model/stream.js

@@ -1,4 +1,5 @@
 import { MspProtocolError, MuseTurnFailedError, MuseTurnUnqueuedError, } from "../errors.js";
+import { notificationCursorKey } from "../msp/notification.js";
 function isNumber(value) {
     return typeof value === "number" && Number.isFinite(value) && value >= 0;
 }
@@ -17,7 +18,7 @@ export class MuseStreamMapper {
     reasoningStarted = new Set();
     itemDeltaCounts = new Map();
     itemText = new Map();
-    seenUsageCursors = new Set();
+    seenUsageNotifications = new Set();
     textParts = [];
     terminalUsage;
     callUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, reasoningTokens: 0 };
@@ -168,9 +169,10 @@ export class MuseStreamMapper {
     tokenUsageEvent(params) {
         if (params.turnId !== this.turnId || typeof params.viewCursor !== "string")
             return;
-        if (this.seenUsageCursors.has(params.viewCursor))
+        const key = notificationCursorKey({ method: "session/tokenUsage", params });
+        if (!key || this.seenUsageNotifications.has(key))
             return;
-        this.seenUsageCursors.add(params.viewCursor);
+        this.seenUsageNotifications.add(key);
         const raw = params.usage;
         if (!raw)
             return;

package/dist/msp/notification.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Stable identity for exact notification replay suppression.
+ * A view cursor may be shared by multiple distinct notification methods or
+ * payloads, so the cursor alone is not an event identity.
+ */
+export declare function notificationCursorKey(notification: {
+    method: string;
+    params?: Record<string, unknown>;
+}): string | undefined;

package/dist/msp/notification.js

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+function stableJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, child]) => child !== undefined)
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+    return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
+}
+/**
+ * Stable identity for exact notification replay suppression.
+ * A view cursor may be shared by multiple distinct notification methods or
+ * payloads, so the cursor alone is not an event identity.
+ */
+export function notificationCursorKey(notification) {
+    const params = notification.params ?? {};
+    const cursor = params.viewCursor;
+    if (typeof cursor !== "string")
+        return undefined;
+    const digest = createHash("sha256")
+        .update(stableJson({ method: notification.method, params }))
+        .digest("hex");
+    return `${cursor}:${digest}`;
+}

package/dist/session/registry.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, chmodSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, chmodSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readlinkSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve, sep, win32 } from "node:path";
+import { dirname, isAbsolute, join, posix, win32 } from "node:path";
 import { RegistryCorruptError, RegistryStorageError, RegistryValidationError, RegistryWorkspaceMismatchError, } from "../errors.js";
 const REGISTRY_VERSION = 1;
 const MAX_ENTRY_BYTES = 1_048_576;
@@ -9,29 +9,82 @@ const HASH_PATTERN = /^[a-f0-9]{64}$/;
 const UUID_V7_PATTERN = /^[a-f0-9]{8}-[a-f0-9]{4}-7[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
 const IDENTIFIER_PATTERN = /^[A-Za-z0-9._:@+_-]{1,512}$/;
 const METHOD_PATTERN = /^[a-z][A-Za-z0-9]*(?:\/[A-Za-z][A-Za-z0-9]*)+$/;
+const MAX_PATH_SYMLINKS = 40;
+/** Resolve existing path components while retaining a normalized not-yet-created suffix. */
+function canonicalPath(path, platform) {
+    const pathApi = platform === "win32" ? win32 : posix;
+    if (platform !== process.platform)
+        return pathApi.resolve(path);
+    const absolute = pathApi.resolve(path);
+    const root = pathApi.parse(absolute).root;
+    let current = root;
+    let remaining = absolute.slice(root.length).split(pathApi.sep).filter(Boolean);
+    let followedSymlinks = 0;
+    while (remaining.length > 0) {
+        const [component, ...rest] = remaining;
+        const candidate = pathApi.join(current, component);
+        let stats;
+        try {
+            stats = lstatSync(candidate);
+        }
+        catch (error) {
+            // A missing component ends filesystem traversal; normalize the remaining suffix lexically.
+            if (isMissingFile(error))
+                return pathApi.resolve(current, ...remaining);
+            throw new RegistryValidationError();
+        }
+        if (stats.isSymbolicLink()) {
+            followedSymlinks += 1;
+            if (followedSymlinks > MAX_PATH_SYMLINKS)
+                throw new RegistryValidationError();
+            let target;
+            try {
+                target = readlinkSync(candidate);
+            }
+            catch {
+                throw new RegistryValidationError();
+            }
+            const absoluteTarget = pathApi.isAbsolute(target)
+                ? pathApi.resolve(target)
+                : pathApi.resolve(current, target);
+            const targetRoot = pathApi.parse(absoluteTarget).root;
+            current = targetRoot;
+            remaining = [
+                ...absoluteTarget.slice(targetRoot.length).split(pathApi.sep).filter(Boolean),
+                ...rest,
+            ];
+            continue;
+        }
+        try {
+            current = realpathSync(candidate);
+        }
+        catch {
+            throw new RegistryValidationError();
+        }
+        remaining = rest;
+    }
+    return pathApi.resolve(current);
+}
 /** Refuse a caller-selected state root inside Muse's CLI-owned config directory. */
 export function assertSafeStateDirectory(path, options = {}) {
     const env = options.env ?? process.env;
     const homeDirectory = options.homeDirectory ?? homedir();
     const platform = options.platform ?? process.platform;
     const windows = platform === "win32";
-    const pathJoin = windows ? win32.join : join;
-    const pathResolve = windows ? win32.resolve : resolve;
-    const pathRelative = windows ? win32.relative : relative;
-    const pathSeparator = windows ? win32.sep : sep;
-    const pathIsAbsolute = windows ? win32.isAbsolute : isAbsolute;
+    const pathApi = windows ? win32 : posix;
     const configuredHome = env.XDG_CONFIG_HOME;
-    const configHome = requiredString(configuredHome) && pathIsAbsolute(configuredHome)
+    const configHome = requiredString(configuredHome) && pathApi.isAbsolute(configuredHome)
         ? configuredHome
-        : pathJoin(homeDirectory, ".config");
-    const museConfigDirectory = pathResolve(pathJoin(configHome, "muse"));
-    const relativePath = pathRelative(museConfigDirectory, pathResolve(path));
+        : pathApi.join(homeDirectory, ".config");
+    const museConfigDirectory = canonicalPath(pathApi.join(configHome, "muse"), platform);
+    const canonicalStateDirectory = canonicalPath(path, platform);
+    const relativePath = pathApi.relative(museConfigDirectory, canonicalStateDirectory);
     const outsideMuseConfig = relativePath === ".."
-        || relativePath.startsWith(`..${pathSeparator}`)
-        || pathIsAbsolute(relativePath);
+        || relativePath.startsWith(`..${pathApi.sep}`)
+        || pathApi.isAbsolute(relativePath);
     if (!outsideMuseConfig)
         throw new RegistryValidationError();
-    return path;
+    return canonicalStateDirectory;
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-muse",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "OpenCode plugin backed by the official Muse Code CLI and MSP",
   "license": "MIT",
   "type": "module",