@stablekernel/opencode-cursor 0.6.2-next.0 → 0.7.0-next.0

package/CHANGELOG.md

@@ -4,11 +4,64 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
-## [0.6.2-next.0] — 2026-07-27 (pre-release)
+## [0.7.0-next.0] — 2026-07-30 (pre-release)
 
-Pre-release of the version-check UX cleanup from #79. Not yet on `latest`; install with
+Pre-release of structured logging (#85), the stream-watchdog tool-phase budget (#86), and the
+session-pool title-generation race fix (#84). Not yet on `latest`; install with
 `npm install @stablekernel/opencode-cursor@next` to test.
 
+- **Structured logging via `client.app.log()` instead of raw `console.*`.** The
+  plugin's own diagnostics (transport fallback warnings, per-turn debug traces
+  gated on `OPENCODE_CURSOR_DEBUG=1`) now route through opencode's plugin
+  logging API (`service: "opencode-cursor"`) rather than `console.warn`/
+  `console.error`. Falls back to `console.*` when no client is available
+  (e.g. running the provider standalone).
+- **Cursor SDK's own "rules"/"skills" load diagnostics captured and forwarded.**
+  `@cursor/sdk`'s bundled local-exec runtime writes internal messages like
+  `LocalCursorRulesService load completed meta={durationMs, ruleCount}` and
+  `AgentSkillsCursorRulesService load completed meta={durationMs, ruleCount,
+  skillCount}` straight to `console.log`, with no public logger hook to
+  redirect it. These are now recognized (in-process transport via a narrowly
+  scoped `console.log` interceptor; sidecar transport via the child process's
+  own interceptor forwarding over the existing JSONL protocol) and re-emitted
+  as structured opencode logs instead of raw terminal noise. Every other
+  `console.log` call passes through unchanged.
+- **Fixed: the stream watchdog killed healthy runs during long tool execution.** The watchdog
+  re-armed only on mapped event types, so a long shell command, build, or test suite that streamed
+  nothing for 60s was cancelled and the turn lost. It now uses two budgets — an idle budget
+  (`OPENCODE_CURSOR_STALL_MS`, default raised to `120000`) and a larger tool-phase budget
+  (`OPENCODE_CURSOR_TOOL_STALL_MS`, default `600000`) applied while a tool call is in flight — and
+  re-arms on **any** SDK update, including types the plugin doesn't model (progress/heartbeats). A
+  tool-phase stall is terminal and names the in-flight tool. `OPENCODE_CURSOR_STALL_MS=0` still
+  disables the whole watchdog; the tool-phase bound is independently disabled with
+  `OPENCODE_CURSOR_TOOL_STALL_MS=0`. Open tool calls are reconciled on `turn-ended` and on a forced
+  resend, so a dropped completion can't pin a turn to the 10-minute budget.
+- **Fixed: a non-numeric `OPENCODE_CURSOR_STALL_MS` stalled every turn immediately.**
+  `Number("abc")` is `NaN`; `NaN <= 0` is `false`, so the guard passed and `setTimeout(fn, NaN)`
+  fired at once. Env parsing now falls back to the default for non-finite values (an empty string
+  still disables, preserving the historical escape hatch).
+- **Fixed: an over-large stall budget overflowed to a ~1 ms deadline.** A `setTimeout` delay is
+  stored as a signed 32-bit int, so anything above `2147483647` is silently clamped to `1` — and the
+  tool-phase stall message tells operators to *raise* `OPENCODE_CURSOR_TOOL_STALL_MS`, making the
+  trap reachable by following the plugin's own advice. Setting it to e.g. `999999999999` stalled
+  every tool-bearing turn within milliseconds while reporting `no events for 999999999999ms`. Both
+  budgets are now capped at `2147483647`.
+- **Fixed: opencode's title-generation call could poison a session's pool entry.** opencode forks a
+  title-generation call on the same `sessionID` as the session's real first turn, concurrently and
+  with an empty system prompt. `classifyTurn`'s side-call detection only fires once a prior pool
+  record exists, so on turn 1 both calls classified as "new" and both wrote to the pool — whichever
+  agent-creation round-trip resolved last silently overwrote the other, leaving the session
+  fingerprinted against the title prompt. Two fixes: the plugin's `chat.params` hook now marks
+  opencode's `title` agent call as `providerOptions.cursor.ephemeral = true` (the provider already
+  honored this flag but nothing set it), and `withSessionLock` (a per-`sessionID` async lock) now
+  wraps `agentRun`'s classify-then-acquire span so concurrent turns for one session serialize and
+  the second call always observes the first's completed pool write.
+- **Dependency bumps:** `@cursor/sdk` 1.0.24 → 1.0.26, `@opencode-ai/plugin` (opencode-ai group).
+
+## [0.6.2] — 2026-07-28
+
+Version-check UX cleanup from #79.
+
 - **Fixed: startup toast no longer suspends into the user's first prompt on slow networks.**
   The version-check toast previously ran `setTimeout(callback, 2000)` and then `await
   _versionCheckPromise` inside the callback, so a slow npm registry fetch could block the

package/README.md

@@ -192,7 +192,8 @@ See [SECURITY.md](./SECURITY.md) for the full threat model.
 | `OPENCODE_CURSOR_MODEL_CACHE_TTL_MS` | `86400000` | Model-list cache lifetime (ms) |
 | `OPENCODE_CURSOR_DEBUG` | — | Set to `1` for trace logging on stderr |
 | `OPENCODE_CURSOR_TRANSPORT` | — | Force a transport: `http1` \| `http2-direct` \| `sidecar` — see [Transport](#transport) |
-| `OPENCODE_CURSOR_STALL_MS` | `60000` | Stream watchdog timeout (ms); `0` disables — see [Reliability](#reliability) |
+| `OPENCODE_CURSOR_STALL_MS` | `120000` | Idle stream-watchdog timeout in ms (no tool call open). `0` disables the whole watchdog; an empty string also disables — see [Reliability](#reliability) |
+| `OPENCODE_CURSOR_TOOL_STALL_MS` | `600000` | Stream-watchdog timeout in ms while a tool call is in flight (e.g. a long build or test suite). `0` disables the bound during tool execution only — see [Reliability](#reliability) |
 | `OPENCODE_CURSOR_SIDECAR` | — | Legacy: `1` maps to `sidecar`, `0` maps to `http2-direct` (superseded by `OPENCODE_CURSOR_TRANSPORT`) |
 | `OPENCODE_CURSOR_TOOL_INPUT_STREAM` | on | Set to `0` to disable live tool-input streaming (`tool-input-start`/`-delta`/`-end` parts) |
 
@@ -378,10 +379,20 @@ The provider classifies Cursor SDK errors into typed kinds (`agent-not-found`, `
 
 Sends carry an idempotency key so a retry is a server-side dedupe, not a duplicate turn.
 
-A **stream watchdog** guards against a wedged run that streams nothing: if no event arrives within
-`OPENCODE_CURSOR_STALL_MS` (default `60000`), a pre-first-event stall cancels and force-resends
-once; a stall after partial output is surfaced as a terminal error rather than re-emitting the
-already-yielded prefix. Set `OPENCODE_CURSOR_STALL_MS=0` to disable.
+A **stream watchdog** guards against a wedged run that streams nothing. It uses two budgets:
+
+- **Idle** (`OPENCODE_CURSOR_STALL_MS`, default `120000`): when no tool call is open. A
+  pre-first-event stall cancels and force-resends once; a stall after partial output is surfaced
+  as a terminal error rather than re-emitting the already-yielded prefix.
+- **Tool-phase** (`OPENCODE_CURSOR_TOOL_STALL_MS`, default `600000`): while at least one Cursor
+  tool call is in flight. A long shell command, build, or test suite legitimately streams nothing
+  for minutes; the larger budget stops a healthy run from being killed mid-tool. A tool-phase
+  stall is terminal and names the in-flight tool. Set `0` to disable the bound during tool
+  execution only.
+
+The watchdog re-arms on **any** SDK update — including types the plugin doesn't model — so
+progress/heartbeat updates count as liveness. Set `OPENCODE_CURSOR_STALL_MS=0` to disable the whole
+watchdog (an empty string also disables, for backward compatibility).
 
 ## Troubleshooting
 

package/dist/{chunk-52IYLL6B.js → chunk-COE6ZXMP.js}

@@ -16,6 +16,50 @@ function fingerprintApiKey(apiKey) {
   return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
 }
 
+// src/provider/log-bridge.ts
+var BRIDGE_KEY = /* @__PURE__ */ Symbol.for("@stablekernel/opencode-cursor:log-bridge");
+function setLogBridge(bridge) {
+  globalThis[BRIDGE_KEY] = bridge;
+}
+function clearLogBridge() {
+  delete globalThis[BRIDGE_KEY];
+}
+function getLogBridge() {
+  return globalThis[BRIDGE_KEY];
+}
+var SERVICE = "opencode-cursor";
+function pluginLog(level, message, extra) {
+  const bridge = getLogBridge();
+  if (bridge) {
+    void bridge.client.app.log({
+      body: {
+        service: SERVICE,
+        level,
+        message,
+        ...extra ? { extra } : {}
+      },
+      ...bridge.directory ? { query: { directory: bridge.directory } } : {}
+    }).catch(() => {
+    });
+    return;
+  }
+  const line = extra ? `[${SERVICE}] ${message} ${JSON.stringify(extra)}` : `[${SERVICE}] ${message}`;
+  switch (level) {
+    case "debug":
+      console.debug(line);
+      break;
+    case "info":
+      console.info(line);
+      break;
+    case "warn":
+      console.warn(line);
+      break;
+    case "error":
+      console.error(line);
+      break;
+  }
+}
+
 // src/provider/agent-backend.ts
 import { execSync } from "child_process";
 import { existsSync } from "fs";
@@ -36,6 +80,48 @@ async function loadCursorSdk() {
   return cached;
 }
 
+// src/provider/cursor-log-intercept.ts
+var ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
+function stripAnsi(input) {
+  return input.replace(ANSI_PATTERN, "");
+}
+var RULE_LOAD_PATTERN = /^\d{2}:\d{2}:\d{2}\.\d{3}\s+INFO\s+(LocalCursorRulesService|AgentSkillsCursorRulesService|CursorPluginsAgentSkillsService) load completed(?:\s+ctx=\S+)?\s+meta=\{([^}]*)\}\s*$/;
+function parseCursorLogMeta(raw) {
+  const out = {};
+  for (const part of raw.split(",")) {
+    const [key, value] = part.split(":").map((s) => s.trim());
+    if (!key || value === void 0) continue;
+    const num = Number(value);
+    if (Number.isFinite(num)) out[key] = num;
+  }
+  return out;
+}
+function parseCursorRuleLoadLine(line) {
+  const match = RULE_LOAD_PATTERN.exec(stripAnsi(line));
+  if (!match) return void 0;
+  const [, service, meta] = match;
+  if (!service) return void 0;
+  return { service, meta: parseCursorLogMeta(meta ?? "") };
+}
+var installed = false;
+var original;
+function installCursorLogInterceptor() {
+  if (installed) return;
+  original = console.log.bind(console);
+  const passthrough = original;
+  console.log = (...args) => {
+    if (args.length === 1 && typeof args[0] === "string") {
+      const parsed = parseCursorRuleLoadLine(args[0]);
+      if (parsed) {
+        pluginLog("info", `${parsed.service} load completed`, parsed.meta);
+        return;
+      }
+    }
+    passthrough(...args);
+  };
+  installed = true;
+}
+
 // src/provider/sidecar-client.ts
 import { spawn } from "child_process";
 import { createInterface } from "readline";
@@ -120,6 +206,18 @@ var SidecarClient = class {
     } catch {
       return;
     }
+    if (msg["ev"] === "log") {
+      const level = msg["level"];
+      const message = msg["message"];
+      if (typeof level === "string" && typeof message === "string") {
+        this.options.onLog?.(
+          level,
+          message,
+          msg["meta"]
+        );
+      }
+      return;
+    }
     const id = msg["id"];
     if (typeof id !== "number") return;
     const pending = this.pending.get(id);
@@ -280,6 +378,7 @@ async function ensureHttp1Configured() {
   http1Configured = true;
 }
 function inProcessBackend(useHttp1) {
+  installCursorLogInterceptor();
   return {
     kind: "in-process",
     createAgent: async (options) => {
@@ -310,7 +409,11 @@ function resolveSidecarScript() {
   return void 0;
 }
 function sidecarBackend(nodePath, scriptPath) {
-  const client = new SidecarClient({ scriptPath, nodePath });
+  const client = new SidecarClient({
+    scriptPath,
+    nodePath,
+    onLog: (level, message, meta) => pluginLog(level, message, meta)
+  });
   return {
     kind: "sidecar",
     createAgent: (options) => client.createAgent(options),
@@ -324,15 +427,18 @@ function loadAgentBackend() {
     const transport = resolveTransport(env);
     const scriptPath = transport === "sidecar" ? resolveSidecarScript() : void 0;
     if (transport === "sidecar" && (!env.nodePath || !scriptPath)) {
-      console.error(
-        `[opencode-cursor] Node sidecar requested but unavailable (node: ${env.nodePath ?? "not found"}, script: ${scriptPath ?? "not found"}); falling back to in-process HTTP/1.1 transport.`
+      pluginLog(
+        "warn",
+        "Node sidecar requested but unavailable; falling back to in-process HTTP/1.1 transport.",
+        { node: env.nodePath ?? null, script: scriptPath ?? null }
       );
       cached2 = inProcessBackend(true);
       return cached2;
     }
     if (transport === "http2-direct" && env.isBun) {
-      console.error(
-        "[opencode-cursor] http2-direct under Bun: Cursor streams may fail (Bun node:http2 incompatibility, oven-sh/bun#31499). Set OPENCODE_CURSOR_TRANSPORT=http1 (recommended) or sidecar."
+      pluginLog(
+        "warn",
+        "http2-direct under Bun: Cursor streams may fail (Bun node:http2 incompatibility, oven-sh/bun#31499). Set OPENCODE_CURSOR_TRANSPORT=http1 (recommended) or sidecar."
       );
     }
     cached2 = transport === "sidecar" && env.nodePath && scriptPath ? sidecarBackend(env.nodePath, scriptPath) : inProcessBackend(transport === "http1");
@@ -436,15 +542,15 @@ function resolveSystemDelivery(options) {
 }
 
 // src/provider/subagent-bridge.ts
-var BRIDGE_KEY = /* @__PURE__ */ Symbol.for("@stablekernel/opencode-cursor:subagent-bridge");
+var BRIDGE_KEY2 = /* @__PURE__ */ Symbol.for("@stablekernel/opencode-cursor:subagent-bridge");
 function setSubagentBridge(bridge) {
-  globalThis[BRIDGE_KEY] = bridge;
+  globalThis[BRIDGE_KEY2] = bridge;
 }
 function clearSubagentBridge() {
-  delete globalThis[BRIDGE_KEY];
+  delete globalThis[BRIDGE_KEY2];
 }
 function getSubagentBridge() {
-  return globalThis[BRIDGE_KEY];
+  return globalThis[BRIDGE_KEY2];
 }
 function isRecord(v) {
   return typeof v === "object" && v !== null;
@@ -590,6 +696,15 @@ function toolDisplayName(toolCall) {
   }
   return toolCall.type ?? "tool";
 }
+var MAX_TIMEOUT_MS = 2147483647;
+function envMs(name, fallback) {
+  const raw = process.env[name];
+  if (raw === void 0) return fallback;
+  if (raw === "") return 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(n, MAX_TIMEOUT_MS);
+}
 async function* streamAgentTurn(agent, message, options) {
   const queue = [];
   let wake;
@@ -597,10 +712,12 @@ async function* streamAgentTurn(agent, message, options) {
   let failure;
   const debug = process.env.OPENCODE_CURSOR_DEBUG === "1";
   const counts = {};
-  const stallMs = Number(process.env.OPENCODE_CURSOR_STALL_MS ?? 6e4);
+  const stallMs = envMs("OPENCODE_CURSOR_STALL_MS", 12e4);
+  const toolStallMs = envMs("OPENCODE_CURSOR_TOOL_STALL_MS", 6e5);
   let stallTimer;
   let forced = false;
   let anyEvent = false;
+  const openTools = /* @__PURE__ */ new Map();
   const push = (event) => {
     anyEvent = true;
     queue.push(event);
@@ -610,10 +727,15 @@ async function* streamAgentTurn(agent, message, options) {
   };
   const armWatchdog = () => {
     if (stallMs <= 0 || finished) return;
+    const budget = openTools.size > 0 ? toolStallMs : stallMs;
     if (stallTimer) clearTimeout(stallTimer);
+    if (budget <= 0) {
+      stallTimer = void 0;
+      return;
+    }
     stallTimer = setTimeout(() => {
       void onStall();
-    }, stallMs);
+    }, budget);
     stallTimer.unref?.();
   };
   const onDelta = ({ update }) => {
@@ -642,6 +764,7 @@ async function* streamAgentTurn(agent, message, options) {
         });
         break;
       case "tool-call-started":
+        openTools.set(String(update.callId), toolDisplayName(update.toolCall));
         push({
           type: "tool-call",
           id: String(update.callId),
@@ -650,6 +773,7 @@ async function* streamAgentTurn(agent, message, options) {
         });
         break;
       case "tool-call-completed": {
+        openTools.delete(String(update.callId));
         const tool = update.toolCall ?? {};
         const result = tool.result;
         const mcpError = tool.type === "mcp" && result?.value?.isError === true;
@@ -663,12 +787,14 @@ async function* streamAgentTurn(agent, message, options) {
         break;
       }
       case "turn-ended":
+        openTools.clear();
         if (update.usage) {
           const summed = addUsage(options.usageBase, update.usage);
           if (summed) push({ type: "usage", usage: summed });
         }
         break;
     }
+    armWatchdog();
   };
   const runHolder = {};
   const onAbort = () => {
@@ -697,9 +823,11 @@ async function* streamAgentTurn(agent, message, options) {
       });
       const result = await run.wait();
       if (debug) {
-        console.error(
-          `[cursor:debug] updates=${JSON.stringify(counts)} status=${result.status} resultLen=${(result.result ?? "").length}`
-        );
+        pluginLog("debug", "turn finished", {
+          updates: counts,
+          status: result.status,
+          resultLen: (result.result ?? "").length
+        });
       }
       if (gen !== runGen || finished) return;
       if (result.status === "error") {
@@ -711,7 +839,11 @@ async function* streamAgentTurn(agent, message, options) {
     }).catch((err) => {
       if (gen !== runGen) return;
       failure = err;
-      if (debug) console.error(`[cursor:debug] send failed: ${err instanceof Error ? err.message : String(err)}`);
+      if (debug) {
+        pluginLog("debug", "send failed", {
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
     }).finally(() => {
       if (gen !== runGen) return;
       finished = true;
@@ -736,7 +868,13 @@ async function* streamAgentTurn(agent, message, options) {
       wake = void 0;
     };
     if (anyEvent) {
-      await failTerminal(`Cursor run stalled (no events for ${stallMs}ms)`);
+      const budget = openTools.size > 0 ? toolStallMs : stallMs;
+      const inFlight = [...openTools.values()];
+      const toolHint = inFlight.length > 0 ? `; tool${inFlight.length > 1 ? "s" : ""} ${inFlight.map((n) => `"${n}"`).join(", ")} still in flight` : "";
+      const knob = openTools.size > 0 ? "OPENCODE_CURSOR_TOOL_STALL_MS" : "OPENCODE_CURSOR_STALL_MS";
+      await failTerminal(
+        `Cursor run stalled (no events for ${budget}ms${toolHint}). Raise ${knob} (or set 0 to disable) if this legitimately runs longer.`
+      );
       return;
     }
     if (forced) {
@@ -744,11 +882,12 @@ async function* streamAgentTurn(agent, message, options) {
       return;
     }
     forced = true;
-    if (debug) console.error("[cursor:debug] stream stalled; cancelling and resending with local.force");
+    if (debug) pluginLog("debug", "stream stalled; cancelling and resending with local.force");
     try {
       await runHolder.run?.cancel();
     } catch {
     }
+    openTools.clear();
     armWatchdog();
     startRun(true);
   };
@@ -781,14 +920,14 @@ async function sendWithRecovery(agent, message, sendOptions, debug) {
     } catch (err) {
       const classified = classifyError(err);
       if (classified.kind === "agent-busy") {
-        if (debug) console.error("[cursor:debug] agent busy; retrying send with local.force");
+        if (debug) pluginLog("debug", "agent busy; retrying send with local.force");
         return agent.send(message, { ...sendOptions, local: { force: true } });
       }
       if ((classified.kind === "rate-limit" || classified.kind === "network") && attempt < RETRY_BACKOFF_MS.length) {
         if (debug)
-          console.error(
-            `[cursor:debug] ${classified.kind}; retrying send in ${RETRY_BACKOFF_MS[attempt]}ms`
-          );
+          pluginLog("debug", `${classified.kind}; retrying send`, {
+            delayMs: RETRY_BACKOFF_MS[attempt]
+          });
         await sleep(RETRY_BACKOFF_MS[attempt]);
         continue;
       }
@@ -924,6 +1063,19 @@ function dropSessionRecord(sessionID) {
   hydrate();
   if (pool.delete(sessionID)) saveSessionRecords(pool);
 }
+var sessionLocks = /* @__PURE__ */ new Map();
+function withSessionLock(sessionID, fn) {
+  if (!sessionID) return fn();
+  const prior = sessionLocks.get(sessionID) ?? Promise.resolve();
+  const run = prior.then(fn, fn);
+  const guarded = run.catch(() => {
+  });
+  sessionLocks.set(sessionID, guarded);
+  void guarded.finally(() => {
+    if (sessionLocks.get(sessionID) === guarded) sessionLocks.delete(sessionID);
+  });
+  return run;
+}
 async function acquireAgent(params) {
   const backend = loadAgentBackend();
   const createOptions = {
@@ -979,6 +1131,9 @@ export {
   resolveCursorApiKey,
   fingerprintApiKey,
   loadCursorSdk,
+  setLogBridge,
+  clearLogBridge,
+  pluginLog,
   setPreferredTransport,
   extractSystemText,
   removeSystemRule,
@@ -994,6 +1149,7 @@ export {
   resolveControls,
   getSessionRecord,
   dropSessionRecord,
+  withSessionLock,
   acquireAgent
 };
-//# sourceMappingURL=chunk-52IYLL6B.js.map
+//# sourceMappingURL=chunk-COE6ZXMP.js.map