@magpie-community/opencode-cursor-auth 0.2.34 → 0.2.36

package/README.md

@@ -123,8 +123,11 @@ caller's tool results is bounded by the 120 seconds above instead.
 
 Cursor's count of a step's tool calls includes calls the plugin answers itself:
 a tool the request doesn't have is refused to the model, and Cursor's own
-`get_mcp_tools` is answered with the request's tools. The step's calls are the
-rest.
+`get_mcp_tools` is answered with the request's tools. It also includes calls
+Cursor completes by itself, which it writes and completes in the step but never
+starts on the client or sends to it; those count toward it too. Once the count
+has come, a checkpoint whose state waits on exactly the calls the caller was
+given also ends the step (#550). The step's calls are the rest.
 
 These are retention limits. A missing, expired, restarted, busy, incompatible,
 or full owner uses the original history reconstruction and stateless decoder
@@ -312,7 +315,10 @@ portable data folder. The newest 20 are kept. A file holds the Run's
 frames in order, both ways, as each frame's time (ms from the Run's
 start), size, kind (text, thinking, checkpoint, heartbeat, ...), field
 numbers and sizes, and the field numbers and sizes one level inside them,
-plus the error and the model id. No prompt, reply or thinking text, tool
+plus the error and the model id. A few of Cursor's numbers are kept too: a
+tool count's value, which kind of call (the field number of Cursor's tool
+call) a call update is about, how many calls a checkpoint waits on, and,
+for a Run that went without the native session, why. No prompt, reply or thinking text, tool
 name or argument, blob or checkpoint content, token, header, account or
 conversation id is written; the error's message has anything shaped like
 an email, id or token taken out. Look the file over before you attach it.

package/index.mjs

@@ -28,7 +28,7 @@
 //
 // OpenCode speaks chat completions to it (@ai-sdk/openai-compatible); the
 // fetch here answers them.
-import { NATIVE_LIMITS, nativeSessions, NativeSessionError, nativeFields, nativeMcpArgs, Quiet, setWireTrace } from "./native-session.mjs"
+import { NATIVE_LIMITS, nativeSessions, NativeSessionError, nativeFields, nativeMcpArgs, pendingCalls, Quiet, setWireTrace, StepCalls } from "./native-session.mjs"
 import { isDeepStrictEqual } from "node:util"
 import http2 from "node:http2"
 import { STATUS_CODES } from "node:http"
@@ -2747,7 +2747,7 @@ async function runNative({ tok, base, id, tools, conv, convID, signal, maxMode,
 
 // runOnce is one Run of the chat on the agent API at base: an async
 // iterator of the answer's pieces, or the error it failed with before any.
-async function runOnce({ tok, base, id, tools, conv, convID, signal, maxMode, params }) {
+async function runOnce({ tok, base, id, tools, conv, convID, signal, maxMode, params, why }) {
   // the Run's conversation_id, a new one when nothing names the session:
   // its usage event is found by it
   const cid = convID || randomUUID()
@@ -2778,7 +2778,7 @@ async function runOnce({ tok, base, id, tools, conv, convID, signal, maxMode, pa
   let closed = false
   let heartbeat
   // a Run Cursor stops answering ends, as a retained one does (#2672)
-  const quiet = new Quiet(NATIVE_LIMITS, () => close(), { path: "stateless", model: id })
+  const quiet = new Quiet(NATIVE_LIMITS, () => close(), { path: "stateless", model: id, why })
   const send = (msg) => {
     if (!closed && !req.destroyed && req.writable) {
       quiet.trace?.frame("out", msg)
@@ -2822,6 +2822,7 @@ async function runOnce({ tok, base, id, tools, conv, convID, signal, maxMode, pa
     close,
     stepUsage: book.own,
     owedUsage: book.owed,
+    note: (name) => quiet.trace?.event(name),
   })
   const wrapped = (async function* () {
     try {
@@ -2852,7 +2853,7 @@ async function runOnce({ tok, base, id, tools, conv, convID, signal, maxMode, pa
 
 // decode follows the server's messages into the answer's pieces until the
 // turn ends, or the model has made its tool calls.
-async function* decode(stream, { send, blobs, tools, estimate, close, stepUsage, owedUsage }) {
+async function* decode(stream, { send, blobs, tools, estimate, close, stepUsage, owedUsage, note, countWait = NATIVE_LIMITS.countWait }) {
   let calls = 0
   // answered: the step's calls answered here (a refusal, the MCP tool
   // list), which Cursor's count of the step's calls takes in too (#142)
@@ -2860,14 +2861,18 @@ async function* decode(stream, { send, blobs, tools, estimate, close, stepUsage,
   // ended: Cursor said what the turn used
   let ended = false
   let listed = 0
+  // what Cursor said of the step's calls: those it completed by itself
+  // count toward listed too, and never come as an exec (plugins#550)
+  const step = new StepCalls(fields)
   // stepDone is whether every call the step listed has come. A step whose
   // calls were all answered here goes on on Cursor's side, under a count of
   // its own.
   const stepDone = () => {
-    if (!listed || calls + answered < listed) return false
+    if (!listed || calls + answered + step.completed < listed) return false
     if (calls > 0) return true
     listed = 0
     answered = 0
+    step.nextStep()
     return false
   }
   let said = 0
@@ -2932,8 +2937,48 @@ async function* decode(stream, { send, blobs, tools, estimate, close, stepUsage,
     return finish(owedUsage ? await owedUsage(calls === 0).catch(() => null) : null)
   }
   const closeExec = (id) => send(pb().bytes(5, pb().bytes(1, pb().varint(1, id))).done())
+  // A step whose calls came and whose count never does: Cursor sent the
+  // calls and then only heartbeats (plugins#550, the fifth trace: two
+  // calls, no count, 240 s of heartbeats until quiet). Once countWait has
+  // passed since Cursor's last frame that wasn't a heartbeat, with no call
+  // still being written, the calls that came are the step's. Heartbeats
+  // never move the deadline: they are all such a Run sends.
+  const it = (stream[Symbol.asyncIterator] ?? stream[Symbol.iterator]).call(stream)
+  let heardAt = Date.now()
+  const read = async () => {
+    const next = Promise.resolve(it.next())
+    if (!calls || listed || step.writing) return next
+    next.catch(() => {}) // a read left behind by the cut fails unheard
+    let timer
+    const cut = new Promise((r) => {
+      timer = setTimeout(() => r({ cut: true }), Math.max(0, heardAt + countWait - Date.now()))
+      timer.unref?.()
+    })
+    try {
+      return await Promise.race([next, cut])
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+  const beat = (data) => {
+    try {
+      const ms = fields(data)
+      return ms.length > 0 && ms.every((m) => m.num === 1 && fields(m.data).every((u) => u.num === 13))
+    } catch {
+      return false
+    }
+  }
   try {
-    for await (const f of stream) {
+    for (;;) {
+      const r = await read()
+      if (r.cut) {
+        note?.("no count")
+        yield await settled()
+        return
+      }
+      if (r.done) break
+      const f = r.value
+      if (f.end || !beat(f.data)) heardAt = Date.now()
       if (f.end) {
         const e = failure(200, f.data)
         if (e.status < 200 || e.status > 299) yield { error: e }
@@ -2984,6 +3029,16 @@ async function* decode(stream, { send, blobs, tools, estimate, close, stepUsage,
                     return
                   }
                   break
+                case 2: // a call started on the client
+                case 3: // a call completed: by Cursor itself when it never started here
+                case 7: // a call the model is writing
+                  // still named in an empty reply's list: only their ids are read
+                  count(seen.updates, u.num)
+                  if (step.update(u.num, uf) && (note?.("completed by Cursor"), stepDone())) {
+                    yield await settled()
+                    return
+                  }
+                  break
                 default:
                   count(seen.updates, u.num)
               }
@@ -2991,6 +3046,7 @@ async function* decode(stream, { send, blobs, tools, estimate, close, stepUsage,
             break
           case 2: {
             // exec_server_message: the server asks the client to run something
+            step.exec(m.data)
             const call = exec(m.data, tools, send, closeExec, seen.refused)
             if (call) {
               said += call.args.length
@@ -3003,6 +3059,18 @@ async function* decode(stream, { send, blobs, tools, estimate, close, stepUsage,
             }
             break
           }
+          case 3:
+            // conversation_checkpoint_update: Cursor's state. Once the step
+            // has its count, a state waiting on just the calls handed to the
+            // caller is a step Cursor has finished: what more the count
+            // says will not come (plugins#550)
+            if (listed && calls > 0 && pendingCalls(m.data, fields) === calls) {
+              note?.("waited on")
+              yield await settled()
+              return
+            }
+            count(seen.messages, m.num)
+            break
           case 4: {
             // kv_server_message: a blob wanted, or one to keep
             const kv = fields(m.data)
@@ -3033,7 +3101,10 @@ async function* decode(stream, { send, blobs, tools, estimate, close, stepUsage,
   } catch (e) {
     // gone quiet is no answer, calls or not: the step's count never came
     if (e?.quiet) {
-      yield { error: { status: e.status, message: e.message } }
+      // with what came of the step's calls, as the native path's batch
+      // error says it (plugins#550)
+      const batch = calls || listed ? `; the step's tool count ${listed || "not sent"}: ${calls} calls came, ${answered} answered here, ${step.completed} completed by Cursor` : ""
+      yield { error: { status: e.status, message: batch ? e.message.replace(/( \(try again\))?$/, batch + "$1") : e.message } }
       return
     }
     if (calls > 0 && /EOF/.test(e?.message ?? "")) {
@@ -3041,6 +3112,9 @@ async function* decode(stream, { send, blobs, tools, estimate, close, stepUsage,
       return
     }
     yield { error: { status: 502, message: "the reply broke off: " + (e?.message ?? e) } }
+  } finally {
+    // not waited for: after a cut, the read left behind ends with the Run
+    Promise.resolve(it.return?.()).catch(() => {})
   }
 }
 
@@ -3207,10 +3281,11 @@ async function answerOf(auth, chat, signal, session = "") {
       // uses the original history builder/decoder without cancelling a live parent.
       const native = prepared.fallback ? null : nativeSessions.create(prepared, { id, maxMode, params }, { pb, exec, usageOf, failure })
       const args = { tok, base, id, tools, conv, convID, signal, maxMode, params }
-      let response = native ? await runNative({ ...args, native }) : await runOnce(args)
+      let response = native ? await runNative({ ...args, native }) : await runOnce({ ...args, why: prepared.fallback || "retention capacity or reservation unavailable" })
       const rebuild = async () => {
-        const fallback = await runOnce(args)
-        fallback.diagnostic = "stateless; bootstrap=imported-history; reason=" + (response.error?.continuityReason || "missing-batch-count")
+        const why = response.error?.continuityReason || "missing-batch-count"
+        const fallback = await runOnce({ ...args, why })
+        fallback.diagnostic = "stateless; bootstrap=imported-history; reason=" + why
         return fallback
       }
       // A missing or conflicting native batch count may be retried once,

package/native-session.mjs

@@ -9,6 +9,12 @@ export const NATIVE_LIMITS = {
   resultWait: 120_000,
   lifetime: 15 * 60_000,
   batchWait: 30_000,
+  // How long a stateless step whose calls came waits for Cursor's count of
+  // them (update 27) with nothing but heartbeats before it hands the calls
+  // that came to the caller (plugins#550). A count comes within ms of the
+  // step's last call; a Run that sent calls and then only heartbeats has
+  // stopped, and the caller's next request goes on from the calls' results.
+  countWait: 60_000,
   drain: 6000,
   replayWait: 120_000,
   blobBytes: 64 << 20,
@@ -55,7 +61,13 @@ const failureOf = (e) => ({ status: e?.status ?? 502, message: e?.message ?? Str
 
 // kindOf is what a frame of AgentServerMessage is, for Quiet: a heartbeat
 // alone, or what an error names as the last thing Cursor sent
-const UPDATES = { 1: "text", 4: "thinking", 14: "turn end", 27: "tool count" }
+// (names after cursor-agent's agent.v1 InteractionUpdate, 2026.10.01)
+const UPDATES = {
+  1: "text", 2: "tool call started", 3: "tool call completed", 4: "thinking", 5: "thinking done",
+  6: "user message", 7: "partial tool call", 8: "token count", 9: "summary", 10: "summary started",
+  11: "summary done", 12: "shell output", 14: "turn end", 15: "tool call delta", 16: "step started",
+  17: "step done", 27: "tool count",
+}
 const MESSAGES = { 2: "tool call", 3: "checkpoint", 4: "blob request" }
 function kindOf(f) {
   if (f.end) return "stream end"
@@ -249,6 +261,26 @@ export function scrub(s) {
     .replace(/[A-Za-z0-9_\-+/=.]{24,}/g, "<redacted>")
     .slice(0, 2000)
 }
+// detail is what a trace keeps of an inbound frame past its shape, all of
+// it numbers of Cursor's protocol, never content (plugins#550): a tool
+// count's number, the kind of call (ToolCall's field) a call update is
+// of, and how many calls a checkpoint's state waits on
+function detail(data) {
+  const out = {}
+  for (const m of nativeFields(data)) {
+    if (m.num === 1) {
+      for (const u of nativeFields(m.data)) {
+        if (u.num === 27) out.count = num(nativeFields(u.data), 1)
+        else if (u.num === 2 || u.num === 3 || u.num === 7) {
+          const tc = field(nativeFields(u.data), 2)
+          const kind = tc && nativeFields(tc.data)[0]
+          if (kind) out.tool = kind.wire === 2 ? [kind.num, nativeFields(kind.data)[0]?.num ?? 0] : [kind.num]
+        }
+      }
+    } else if (m.num === 3) out.pending = pendingCalls(m.data)
+  }
+  return out
+}
 export class WireTrace {
   static open(meta) {
     let dir = ""
@@ -258,6 +290,8 @@ export class WireTrace {
   constructor(dir, meta = {}) {
     this.dir = dir
     this.meta = { path: String(meta.path ?? ""), model: String(meta.model ?? "") }
+    // why a Run went stateless: the retention fallback's reason
+    if (meta.why) this.meta.why = String(meta.why)
     this.started = Date.now()
     this.head = []
     this.tail = []
@@ -281,6 +315,7 @@ export class WireTrace {
     if (dir === "in") entry.kind = kind ?? "heartbeat"
     if (dir === "in" && f.end) entry.end = true
     else try { entry.fields = shape(data, true) } catch { entry.malformed = true }
+    if (dir === "in" && !f.end) try { Object.assign(entry, detail(data)) } catch {}
     this.push(entry)
   }
   event(name, extra = {}) {
@@ -438,6 +473,75 @@ const field = (fs, n) => fs.find((f) => f.num === n)
 const str = (fs, n) => field(fs, n)?.data.toString("utf8") ?? ""
 const num = (fs, n) => field(fs, n)?.n ?? 0
 
+// StepCalls is what Cursor says of a step's calls besides its execs
+// (plugins#550). InteractionUpdate 2 (tool_call_started), 3
+// (tool_call_completed) and 7 (partial_tool_call) each carry the call's
+// call_id (field 1). A call Cursor completed by itself, never started on
+// the client and never sent as an exec, is in tool_requests_listed's count
+// all the same, and no exec of it will come: 0.2.34 waited for it while
+// Cursor waited for the one call it had sent, 240 s, heartbeats only.
+// parse is the path's field reader.
+export class StepCalls {
+  constructor(parse) {
+    this.parse = parse
+    this.started = new Set()
+    this.execs = new Set() // the short strings of each exec's args: its tool_call_id among them
+    this.partial = new Set() // calls the model is writing in this step
+    this.byCursor = new Set()
+  }
+  // update takes an InteractionUpdate's own field (num) and its fields; it
+  // says whether a call was completed by Cursor: one this step wrote (7)
+  // and completed (3) with no start on the client (2) and no exec. A
+  // completion of an earlier step's call is never counted again.
+  update(n, uf) {
+    if (n !== 2 && n !== 3 && n !== 7) return false
+    const id = str(uf, 1)
+    if (!id) return false
+    if (n === 2) this.started.add(id)
+    if (n === 7) this.partial.add(id)
+    if (n !== 3) return false
+    if (!this.partial.has(id) || this.started.has(id) || this.execs.has(id) || this.byCursor.has(id)) return false
+    this.byCursor.add(id)
+    return true
+  }
+  // exec notes an exec's args, whatever its kind: each kind keeps its
+  // tool_call_id at a field of its own (ShellArgs 4, ReadArgs 2, McpArgs 3)
+  exec(data) {
+    try {
+      for (const e of this.parse(data)) {
+        if (e.wire !== 2 || e.num === 15 || e.num === 19) continue
+        for (const a of this.parse(e.data)) if (a.wire === 2 && a.data.length && a.data.length <= 512) this.execs.add(a.data.toString("utf8"))
+      }
+    } catch {}
+  }
+  get completed() {
+    return this.byCursor.size
+  }
+  // writing is how many calls the step wrote (7) that are neither started
+  // on the client, sent as an exec, nor completed by Cursor: a call of
+  // Cursor's own still running, or one still to be sent
+  get writing() {
+    let n = 0
+    for (const id of this.partial) if (!this.started.has(id) && !this.execs.has(id) && !this.byCursor.has(id)) n++
+    return n
+  }
+  // nextStep starts the next step's count
+  nextStep() {
+    this.partial.clear()
+    this.byCursor.clear()
+  }
+}
+// pendingCalls is how many calls a checkpoint (ConversationStateStructure)
+// says Cursor waits on: its pending_tool_calls, field 4; null when it
+// can't be read
+export function pendingCalls(data, parse = nativeFields) {
+  try {
+    return parse(data).filter((f) => f.num === 4).length
+  } catch {
+    return null
+  }
+}
+
 function argsOf(s) {
   try {
     const v = typeof s === "string" ? JSON.parse(s) : s
@@ -737,6 +841,8 @@ class NativeSession {
     this.ac = new AbortController()
     this.execs = new Map()
     this.nativeCalls = new Map()
+    // what Cursor said of the step's calls besides its execs (plugins#550)
+    this.stepCalls = new StepCalls(nativeFields)
     this.blobs = new Map()
     this.knownHashes = new Set()
     this.blobSize = 0
@@ -934,6 +1040,7 @@ class NativeSession {
   // caller's results, or after a step whose calls were all answered here.
   nextStep(estimate) {
     this.steps++
+    this.stepCalls.nextStep()
     this.quiet.nextStep(this.steps)
     this.stepSaid = this.said
     if (estimate != null) this.stepEstimate = estimate
@@ -951,7 +1058,7 @@ class NativeSession {
     this.batchTimer = later(() => {
       const s = this.segment
       if (s.expected == null && s.calls.length && !this.resultSubmitted) this.missingCount()
-      else this.fail({ status: 502, message: `Cursor did not complete its declared native tool batch: ${s.calls.length} of ${s.expected ?? "?"} calls came, ${s.answered} answered here, none since ${Date.now() - since} ms` })
+      else this.fail({ status: 502, message: `Cursor did not complete its declared native tool batch: ${s.calls.length} of ${s.expected ?? "?"} calls came, ${s.answered} answered here${this.stepCalls.completed ? `, ${this.stepCalls.completed} completed by Cursor` : ""}, none since ${Date.now() - since} ms` })
     }, this.limits.batchWait)
   }
   missingCount() {
@@ -967,6 +1074,23 @@ class NativeSession {
     if (this.batchTimer) this.waitForBatch()
     this.sealBatch()
   }
+  // A call of the step Cursor completed by itself (plugins#550): in its
+  // count, and never sent as an exec.
+  completedByCursor() {
+    if (this.terminal || this.state === "awaiting-results") return
+    if (this.batchTimer) this.waitForBatch()
+    this.sealBatch()
+  }
+  // A checkpoint whose state waits on just the calls handed to the caller,
+  // after the step's count, is a step Cursor has finished: what more the
+  // count says will not come (plugins#550).
+  waitedOn(data) {
+    const s = this.segment
+    if (this.terminal || this.state === "awaiting-results" || s.closed || s.expected == null || !s.calls.length) return
+    if (pendingCalls(data) !== s.calls.length) return
+    s.waitedOn = true
+    this.sealBatch()
+  }
   listed(count) {
     if (!Number.isSafeInteger(count) || count < 1) invalid("invalid native tool count", 502)
     if (this.segment.expected != null && this.segment.expected !== count) {
@@ -986,7 +1110,8 @@ class NativeSession {
     if (segment.expected == null) return
     const made = segment.calls.length + segment.answered
     if (made > segment.expected) invalid("native tool batch exceeded its declared count", 502)
-    if (made !== segment.expected || segment.closed) return
+    // the calls Cursor completed by itself make up the rest (plugins#550)
+    if ((made + this.stepCalls.completed < segment.expected && !segment.waitedOn) || segment.closed) return
     if (!segment.calls.length) {
       // Every call of the step was answered here: Cursor goes on with the
       // turn by itself, and its next step lists a count of its own.
@@ -1183,10 +1308,14 @@ class NativeSession {
                   if (this.error) return
                 } else if (u.num === 13) {
                   if (this.batchTimer && !this.terminal && this.state !== "awaiting-results") this.waitForBatch()
+                } else if ((u.num === 2 || u.num === 3 || u.num === 7) && this.stepCalls.update(u.num, uf)) {
+                  this.completedByCursor()
+                  if (this.error) return
                 }
               }
               break
             case 2: {
+              this.stepCalls.exec(m.data)
               const c = exec(m.data, this.chatTools, (b) => this.send(b), (id) => this.execClose(id), null, true)
               if (c) this.acceptCall(c)
               // request_context is Cursor asking for the environment, not a call
@@ -1195,6 +1324,7 @@ class NativeSession {
             }
             case 3:
               this.checkpointReceived(m.data)
+              this.waitedOn(m.data)
               break
             case 4: {
               const kv = nativeFields(m.data)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpie-community/opencode-cursor-auth",
-  "version": "0.2.34",
+  "version": "0.2.36",
   "description": "Cursor subscriptions (Pro, Pro+, Ultra, Teams) in OpenCode and magpie, through the API cursor-agent talks to",
   "type": "module",
   "main": "./index.mjs",