@magpie-community/opencode-cursor-auth 0.2.12 → 0.2.14

package/index.mjs

@@ -21,13 +21,15 @@
 // a conversation, the caller's system prompt at its head; the Run only
 // resumes it. The caller's tools are MCP tools, which the model calls
 // through Cursor's CallDynamicTool: the server hands each call to the
-// client to run, and once it has said how many a step made, the stream is
-// closed and the calls go back to OpenCode as a chat completion's tool
-// calls. Nothing else the server asks the client to run (a shell, a file
-// read) is run.
+// client to run, and once it has said how many a step made, the calls
+// go back to OpenCode. When the owner is available their results continue
+// that Run; otherwise the caller's history starts a stateless Run. Nothing
+// else the server asks the client to run (a shell, a file read) is run.
 //
 // OpenCode speaks chat completions to it (@ai-sdk/openai-compatible); the
 // fetch here answers them.
+import { NATIVE_LIMITS, nativeSessions, NativeSessionError, nativeFields, nativeMcpArgs } from "./native-session.mjs"
+import { isDeepStrictEqual } from "node:util"
 import http2 from "node:http2"
 import { STATUS_CODES } from "node:http"
 import { gunzipSync } from "node:zlib"
@@ -1358,17 +1360,18 @@ function usageOf(uf) {
 // event: its step looks for it as before, and is guessed without it.
 const STEP_WAIT = { first: 1500, every: 500, until: 6000, ask: 5000, skipAfter: 3, retryEvery: 10, owedAt: 5000, owedFor: 600_000 }
 
-// claimed are the usage events already counted, by conversation and time,
-// so that two steps of one conversation never count the same one.
+// claimed are the usage events already counted, by account, conversation
+// and time, so that two steps of one conversation never count the same one.
 const claimed = new Map()
 
-// owed are what each conversation still owes, by conversation_id: n Runs
-// whose events are to be counted, the earliest started at since, looked
-// for from ready on; and carry, a count collected that no step gave out.
+// owed are what each account's conversation still owes, by credential
+// fingerprint and conversation_id: n Runs whose events are to be counted,
+// the earliest started at since, looked for from ready on; and carry, a
+// count collected that no step gave out.
 const owed = new Map()
 
-// flights are each conversation's collections still going, which a step
-// that ends the turn waits for.
+// flights are each account's conversation collections still going, which
+// a step that ends the turn waits for.
 const flights = new Map()
 
 // unreadable are the accounts (by token) whose usage events Cursor won't
@@ -1378,6 +1381,7 @@ const flights = new Map()
 const unreadable = new Map()
 const misses = new Map()
 const tokKey = (tok) => createHash("sha256").update(tok).digest("hex")
+const usageKey = (tok, conv) => tokKey(tok) + "\0" + conv
 function canRead(tok) {
   const at = unreadable.get(tokKey(tok))
   if (at === undefined) return true
@@ -1394,14 +1398,43 @@ function addUsage(a, b) {
   return a
 }
 
-// owe adds to conversation conv's debt.
-function owe(conv, { since = Date.now(), n = 0, ready = Date.now(), carry = null }) {
-  for (const [k, d] of owed) if (Date.now() - d.since > STEP_WAIT.owedFor) owed.delete(k)
+// owe adds to the account/conversation's debt. A native Run bounds older
+// event timestamps before its start: its authoritative final must never be
+// collected as an earlier Run. Keep that bound when a later stateless Run
+// adds unbounded debt. Ordinary stateless debt retains its original shape.
+const DEBT_GROUP_LIMIT = 64
+function owe(key, { since = Date.now(), n = 0, ready = Date.now(), carry = null, before }) {
+  for (const [k, d] of owed) {
+    if (d.groups) {
+      d.groups = d.groups.filter((g) => Date.now() - g.since <= STEP_WAIT.owedFor)
+      d.n = d.groups.reduce((sum, g) => sum + g.n, 0)
+      if (Date.now() - d.since > STEP_WAIT.owedFor) d.carry = null
+      if (!d.n && !d.carry) owed.delete(k)
+      else if (d.groups.length) d.since = Math.min(...d.groups.map((g) => g.since))
+    } else if (Date.now() - d.since > STEP_WAIT.owedFor) owed.delete(k)
+  }
   if (n <= 0 && !carry) return
-  const d = owed.get(conv)
-  if (!d) return void owed.set(conv, { since, n, ready, carry: carry && { ...carry } })
-  d.since = Math.min(d.since, since)
-  d.n += n
+  const d = owed.get(key)
+  if (!d) return void owed.set(key, { since, n, ready, carry: carry && { ...carry }, ...(before !== undefined ? { before } : {}) })
+  if (n > 0 && (d.groups || d.before !== undefined || before !== undefined)) {
+    const groups = d.groups ?? (d.n > 0 ? [{ since: d.since, n: d.n, ready: d.ready, before: d.before }] : [])
+    const same = groups.find((g) => g.before === before)
+    if (same) {
+      same.since = Math.min(same.since, since)
+      same.n += n
+      same.ready = Math.min(same.ready, ready)
+    } else groups.push({ since, n, ready, before })
+    // As with expired dashboard debt, overflow stays unknown, never estimated
+    // or merged across bounds into an authoritative native Run's event.
+    groups.sort((a, b) => a.since - b.since)
+    d.groups = groups.slice(-DEBT_GROUP_LIMIT)
+    delete d.before
+    d.n = d.groups.reduce((sum, g) => sum + g.n, 0)
+    d.since = Math.min(...d.groups.map((g) => g.since))
+  } else {
+    d.since = Math.min(d.since, since)
+    d.n += n
+  }
   d.ready = Math.min(d.ready, ready)
   d.carry = addUsage(d.carry, carry)
 }
@@ -1412,7 +1445,8 @@ function owe(conv, { since = Date.now(), n = 0, ready = Date.now(), carry = null
 // when the account can't read them.
 // Polling, they are looked for as STEP_WAIT says, from `first` on, until
 // all show; else asked for once.
-async function usageEvents(tok, conv, since, want, { poll = false, first = STEP_WAIT.first, signal } = {}) {
+async function usageEvents(tok, conv, since, want, { poll = false, first = STEP_WAIT.first, signal, before = () => Infinity, groups, abortFetch = false } = {}) {
+  const key = usageKey(tok, conv)
   const end = Date.now() + STEP_WAIT.until
   const wait = (ms) => new Promise((r) => {
     const t = setTimeout(r, ms)
@@ -1423,6 +1457,7 @@ async function usageEvents(tok, conv, since, want, { poll = false, first = STEP_
   let usage = null
   let got = 0
   const events = []
+  const counts = groups?.map(() => 0)
   if (poll) await wait(first)
   while (!signal?.aborted) {
     try {
@@ -1430,20 +1465,27 @@ async function usageEvents(tok, conv, since, want, { poll = false, first = STEP_
         method: "POST",
         headers: await headersFor(tok),
         body: JSON.stringify({ teamId: 0, startDate: String(since - 60_000), endDate: String(Date.now() + 60_000), page: 1, pageSize: 50 }),
-        signal: AbortSignal.timeout(STEP_WAIT.ask),
+        signal: abortFetch && signal ? AbortSignal.any([signal, AbortSignal.timeout(STEP_WAIT.ask)]) : AbortSignal.timeout(STEP_WAIT.ask),
       })
       if (res.status >= 400 && res.status < 500 && res.status !== 429) {
         // not this account's to read
         unreadable.set(tokKey(tok), Date.now())
-        return { usage, events, got, refused: true }
+        return { usage, events, got, counts, refused: true }
       }
       const evs = res.ok ? ((await res.json())?.usageEventsDisplay ?? []) : []
       const found = evs
-        .filter((e) => e?.conversationId === conv && e.tokenUsage && num(e.timestamp) >= since - 1000 && !claimed.has(conv + "\0" + e.timestamp))
+        .filter((e) => e?.conversationId === conv && e.tokenUsage && num(e.timestamp) >= since - 1000 && !claimed.has(key + "\0" + e.timestamp))
         .sort((a, b) => num(a.timestamp) - num(b.timestamp))
-        .slice(0, want - got)
       for (const ev of found) {
-        claimed.set(conv + "\0" + ev.timestamp, Date.now())
+        if (got >= want) break
+        const at = num(ev.timestamp)
+        // found already excludes timestamps claimed by earlier fetches. Two
+        // distinct events in this response may share a millisecond; count both.
+        if (at >= before()) continue
+        const group = groups?.findIndex((g, i) => counts[i] < g.n && at >= g.since - 1000 && at < (g.before ?? Infinity))
+        if (groups && group === -1) continue
+        if (groups) counts[group]++
+        claimed.set(key + "\0" + ev.timestamp, Date.now())
         const t = ev.tokenUsage
         const u = { input: num(t.inputTokens), output: num(t.outputTokens), cacheRead: num(t.cacheReadTokens), cacheWrite: num(t.cacheWriteTokens), reasoning: 0 }
         usage = addUsage(usage ?? ZERO(), u)
@@ -1455,7 +1497,7 @@ async function usageEvents(tok, conv, since, want, { poll = false, first = STEP_
     if (!poll || Date.now() + STEP_WAIT.every > end) break
     await wait(STEP_WAIT.every)
   }
-  return { usage, events, got, refused: false }
+  return { usage, events, got, counts, refused: false }
 }
 
 // stepUsage is the usage of the Run of conversation conv started at since,
@@ -1464,31 +1506,45 @@ async function stepUsage(tok, conv, since, signal) {
   return (await usageEvents(tok, conv, since, 1, { poll: true, signal })).usage
 }
 
-// collect takes conversation conv's debt and asks for its events (polling
-// when poll): what was carried and what was found (usage), what was
-// carried alone (carry) and the events found (events), and whether any is
+// collect takes the account's debt for conversation conv and asks for its
+// events (polling when poll): what was carried and what was found (usage),
+// what was carried alone (carry) and the events found (events), and whether any is
 // still owed (short), which is owed on. What comes back once the Run that
 // asked is over (over() true) is carried to the next instead.
-function collect(tok, conv, { poll = false, first, signal, over = () => false } = {}) {
-  const d = owed.get(conv)
+function collect(tok, conv, { poll = false, first, signal, over = () => false, abortFetch = false } = {}) {
+  const key = usageKey(tok, conv)
+  const d = owed.get(key)
   if (!d) return Promise.resolve({ usage: null, carry: null, events: [], short: false })
-  owed.delete(conv)
+  owed.delete(key)
   const p = (async () => {
+    const groups = (d.groups ?? [d]).filter((g) => (g.before === undefined && !d.groups) || Date.now() - g.since <= STEP_WAIT.owedFor)
+    const want = groups.reduce((sum, g) => sum + g.n, 0)
     let r = { usage: null, events: [], got: 0 }
-    if (d.n > 0 && canRead(tok)) r = await usageEvents(tok, conv, d.since, d.n, { poll, first, signal }).catch(() => r)
-    const short = d.n > r.got && canRead(tok)
-    if (short) owe(conv, { since: d.since, n: d.n - r.got, ready: d.ready })
+    if (want > 0 && canRead(tok)) r = await usageEvents(tok, conv, Math.min(...groups.map((g) => g.since)), want, {
+      poll, first, signal, abortFetch, before: () => d.before ?? Infinity, ...(d.groups ? { groups } : {}),
+    }).catch(() => r)
+    let short = false
+    for (const [i, g] of groups.entries()) {
+      const remaining = g.n - (d.groups ? r.counts?.[i] ?? 0 : r.got)
+      if (remaining > 0 && canRead(tok)) {
+        short = true
+        owe(key, { since: g.since, n: remaining, ready: g.ready, before: g.before })
+      }
+    }
     const carry = d.carry && { ...d.carry }
     const usage = addUsage(d.carry, r.usage)
     if (!over()) return { usage, carry, events: r.events ?? [], short }
-    owe(conv, { carry: usage })
+    owe(key, { carry: usage })
     return { usage: null, carry: null, events: [], short }
   })()
-  const set = flights.get(conv) ?? new Set()
-  flights.set(conv, set.add(p))
+  // Native admission may happen while an older collector is still in flight.
+  // Its dynamic event bound must apply before that response is claimed too.
+  p.debt = d
+  const set = flights.get(key) ?? new Set()
+  flights.set(key, set.add(p))
   p.finally(() => {
     set.delete(p)
-    if (!set.size && flights.get(conv) === set) flights.delete(conv)
+    if (!set.size && flights.get(key) === set) flights.delete(key)
   })
   return p
 }
@@ -1513,13 +1569,18 @@ function collect(tok, conv, { poll = false, first, signal, over = () => false }
 // owed(), apart. A Run of its conversation begins only once the one
 // before has ended, so the two never meet; were the time off, the step's
 // count would be told in the wrong field, never twice nor lost.
-function ledger(tok, conv, since, signal, kept) {
+function ledger(tok, conv, since, signal, kept, { before } = {}) {
   const key = tokKey(tok)
+  const debtKey = usageKey(tok, conv)
+  if (kept && before !== undefined) {
+    const debts = [owed.get(debtKey), ...[...(flights.get(debtKey) ?? [])].map((p) => p.debt)]
+    for (const d of debts) for (const g of d?.groups ?? (d ? [d] : [])) g.before = Math.min(g.before ?? Infinity, before)
+  }
   let mine = null // this Run's own, collected, not given out yet
   let theirs = null // earlier Runs', collected, not given out yet
   let over = false
   const gather = (opts) =>
-    collect(tok, conv, { ...opts, over: () => over }).then((r) => {
+    collect(tok, conv, { ...opts, over: () => over, abortFetch: before !== undefined }).then((r) => {
       theirs = addUsage(theirs, r.carry)
       for (const e of r.events ?? []) {
         if (e.at >= since - 1000) mine = addUsage(mine, e.usage)
@@ -1528,7 +1589,7 @@ function ledger(tok, conv, since, signal, kept) {
       return r
     })
   let collecting = null
-  const debt = kept ? owed.get(conv) : undefined
+  const debt = kept ? owed.get(debtKey) : undefined
   const timer = debt ? setTimeout(() => (collecting = gather()), Math.max(0, debt.ready - Date.now())) : null
   timer?.unref?.()
   const takeMine = () => {
@@ -1552,7 +1613,7 @@ function ledger(tok, conv, since, signal, kept) {
         else if (!r.refused) misses.set(key, m + 1)
         return r.usage ?? null
       }
-      owe(conv, { since, n: 1, ready: Date.now() + STEP_WAIT.owedAt })
+      owe(debtKey, { since, n: 1, ready: Date.now() + STEP_WAIT.owedAt })
       if (waits) {
         const r = await gather({ poll: true, signal })
         if (!canRead(tok)) return null
@@ -1565,8 +1626,8 @@ function ledger(tok, conv, since, signal, kept) {
       if (!kept) return null
       if (final) {
         await collecting
-        await Promise.all([...(flights.get(conv) ?? [])])
-        if (owed.has(conv)) await gather({ poll: owed.get(conv).n > 0, first: 0, signal })
+        await Promise.all([...(flights.get(debtKey) ?? [])])
+        if (owed.has(debtKey)) await gather({ poll: owed.get(debtKey).n > 0, first: 0, signal })
       }
       return take()
     },
@@ -1574,7 +1635,7 @@ function ledger(tok, conv, since, signal, kept) {
       over = true
       clearTimeout(timer)
       const u = take()
-      if (u) owe(conv, { carry: u })
+      if (u) owe(debtKey, { carry: u })
     },
   }
 }
@@ -1666,12 +1727,21 @@ async function agentURL(tok, fresh) {
 // connection that failed (refused, no network) or a stream the server
 // refused leaves the next Run to try HTTP/2 again.
 let h1Until = 0
+const cancelledOpen = () => ({ error: { status: 410, message: "the request was cancelled" }, h2Failed: false })
 async function open(base, headers, signal) {
+  if (signal?.aborted) return cancelledOpen()
   if (Date.now() >= h1Until) {
     const o = await openH2(base, headers, signal)
+    // The head can arrive just before abort, before this continuation owns it.
+    if (signal?.aborted) {
+      o.req?.close(http2.constants.NGHTTP2_CANCEL)
+      o.session?.destroy()
+      return cancelledOpen()
+    }
     if (!o.h2Failed) return o
     if (o.blocked) h1Until = Date.now() + H2.retryAfter
   }
+  if (signal?.aborted) return cancelledOpen()
   return openH1(headers, signal)
 }
 
@@ -1702,6 +1772,7 @@ function h2Blocked(e) {
 // than by being cancelled, says h2Failed, and blocked when h2Blocked says
 // so of the failure.
 function openH2(base, headers, signal) {
+  if (signal?.aborted) return Promise.resolve(cancelledOpen())
   return new Promise((resolve) => {
     const u = new URL(base)
     const session = http2.connect(u.origin)
@@ -1710,9 +1781,11 @@ function openH2(base, headers, signal) {
       if (done) return
       done = true
       clearTimeout(timer)
+      signal?.removeEventListener("abort", abort)
       session.destroy()
-      resolve({ error: { status: 502, message: e?.message ?? String(e) }, h2Failed, blocked: h2Failed && h2Blocked(e) })
+      resolve({ error: { status: h2Failed ? 502 : 410, message: e?.message ?? String(e) }, h2Failed, blocked: h2Failed && h2Blocked(e) })
     }
+    const abort = () => fail(new Error("the request was cancelled"), false)
     const timer = setTimeout(() => fail(Object.assign(new Error(`no answer over HTTP/2 in ${H2.wait / 1000}s`), { h2Timeout: true })), H2.wait)
     session.on("error", fail)
     const req = session.request({
@@ -1728,9 +1801,11 @@ function openH2(base, headers, signal) {
       if (done) return
       done = true
       clearTimeout(timer)
+      signal?.removeEventListener("abort", abort)
       resolve({ session, req, status: Number(h[":status"]) })
     })
-    signal?.addEventListener("abort", () => fail(new Error("the request was cancelled"), false), { once: true })
+    signal?.addEventListener("abort", abort, { once: true })
+    if (signal?.aborted) abort()
   })
 }
 
@@ -1750,23 +1825,29 @@ function connectCode(status) {
 // ends the stream with Connect's end frame, which runOnce reads as the
 // Run's own.
 function openH1(headers, signal) {
+  if (signal?.aborted) return Promise.resolve(cancelledOpen())
   const ac = new AbortController()
-  signal?.addEventListener("abort", () => ac.abort(), { once: true })
   const id = headers["x-request-id"]
   const h = { ...headers, "accept-encoding": "identity", "x-cursor-streaming": "true" }
   let ended = false
   let seq = 0
-  let chain = Promise.resolve()
+  let reader
   const req = new Duplex({
     read() {},
     write(chunk, _enc, cb) {
       // runOnce writes one whole frame each time
       const msg = Buffer.from(chunk).subarray(5)
       const n = seq++
-      chain = chain.then(() => (ended ? undefined : append(msg, n)))
-      cb()
+      // Keep the write buffered until its append finishes, so callbacks and
+      // drain reflect the pending upload rather than an unbounded promise chain.
+      append(msg, n).then(() => cb(), (e) => cb(e))
     },
   })
+  const cleanup = () => {
+    signal?.removeEventListener("abort", close)
+    ac.abort()
+    reader?.cancel().catch(() => {})
+  }
   const end = (body) => {
     if (ended || req.destroyed) return
     ended = true
@@ -1774,7 +1855,7 @@ function openH1(headers, signal) {
     f[0] = 2
     req.push(f)
     req.push(null)
-    ac.abort()
+    cleanup()
   }
   const failed = async (res) => {
     const text = await res.text().catch(() => "")
@@ -1788,6 +1869,7 @@ function openH1(headers, signal) {
   // (more time for a large one) ends the Run, as cursor-agent's
   // bidi_append_deadline_exceeded does: the messages after it wait on it.
   const append = async (msg, n) => {
+    if (ended || ac.signal.aborted) return
     const body = pb().str(1, msg.toString("hex")).bytes(2, pb().str(1, id).done()).varint(3, n).done()
     const ms = H1.appendWait + Math.ceil(body.length / 65536) * 1000
     const deadline = AbortSignal.timeout(ms)
@@ -1798,6 +1880,7 @@ function openH1(headers, signal) {
         body,
         signal: AbortSignal.any([ac.signal, deadline]),
       })
+      if (ended || ac.signal.aborted) { await res.body?.cancel().catch(() => {}); return }
       if (!res.ok) return failed(res)
       await res.arrayBuffer()
     } catch (e) {
@@ -1806,6 +1889,16 @@ function openH1(headers, signal) {
       end(JSON.stringify({ error: { code: "unavailable", message: `BidiAppend: ${e?.message ?? e}` } }))
     }
   }
+  const close = () => {
+    ended = true
+    cleanup()
+    req.destroy()
+  }
+  signal?.addEventListener("abort", close, { once: true })
+  if (signal?.aborted) {
+    close()
+    return Promise.resolve(cancelledOpen())
+  }
   ;(async () => {
     try {
       const res = await fetch(API + "/agent.v1.AgentService/RunSSE", {
@@ -1814,25 +1907,229 @@ function openH1(headers, signal) {
         body: frame(pb().str(1, id).done()),
         signal: ac.signal,
       })
+      if (ended || ac.signal.aborted) { await res.body?.cancel().catch(() => {}); return }
       if (!res.ok) return failed(res)
-      for await (const c of res.body) {
-        if (ended || req.destroyed) return
-        req.push(Buffer.from(c))
+      reader = res.body.getReader()
+      try {
+        while (!ended && !req.destroyed) {
+          const { value, done } = await reader.read()
+          if (done) break
+          if (!ended && !req.destroyed) req.push(Buffer.from(value))
+        }
+      } finally {
+        reader.releaseLock()
+        reader = undefined
       }
       if (!ended && !req.destroyed) {
         ended = true
         req.push(null)
+        cleanup()
       }
     } catch (e) {
       if (!ac.signal.aborted) end(JSON.stringify({ error: { code: "unavailable", message: `RunSSE: ${e?.message ?? e}` } }))
     }
   })()
+  return Promise.resolve(signal?.aborted ? cancelledOpen() : { session: { close, destroy: close }, req: Object.assign(req, { close }), status: 200, h1: true })
+}
+
+// Every outbound frame, including KV replies and heartbeats, uses the same
+// bounded FIFO. Admission is synchronous; a result is reserved only once even
+// when a later write fails. Count bytes until both callback and drain complete.
+function nativeTransport(req, close, fail, limits = NATIVE_LIMITS) {
+  const outbound = { bytes: 0, messages: 0 }
+  const queue = []
+  let closed = false, flushing = false, rejectWrite
+  const flush = async () => {
+    if (closed || flushing) return
+    flushing = true
+    try {
+      while (!closed && queue.length) {
+        const packet = queue.shift()
+        await new Promise((resolve, reject) => {
+          let written = false, drained = false, started = false, settled = false
+          const finish = (error) => {
+            if (settled) return
+            settled = true
+            rejectWrite = undefined
+            req.removeListener("drain", drain)
+            req.removeListener("error", failed)
+            req.removeListener("close", lost)
+            error ? reject(error) : resolve()
+          }
+          const check = () => { if (started && written && drained) finish() }
+          const drain = () => { drained = true; check() }
+          const failed = (e) => finish(e)
+          const lost = () => finish(new NativeSessionError(502, "native transport closed during a write; its outcome is uncertain"))
+          rejectWrite = finish
+          req.once("drain", drain)
+          req.once("error", failed)
+          req.once("close", lost)
+          try {
+            drained = req.write(packet, (e) => {
+              if (e) return finish(e)
+              written = true
+              check()
+            }) || drained
+            started = true
+            if (drained) req.removeListener("drain", drain)
+            check()
+          } catch (e) { finish(e) }
+        })
+        if (!closed) { outbound.bytes -= packet.length; outbound.messages-- }
+      }
+    } catch (e) {
+      if (!closed) fail(e)
+    } finally { flushing = false }
+  }
+  return {
+    outbound,
+    send(message) {
+      if (closed || req.destroyed || !req.writable) throw new NativeSessionError(502, "native transport is no longer writable")
+      const size = message.length + 5
+      if (outbound.bytes + size > limits.outboundBytes) throw new NativeSessionError(503, "native outbound bytes limit reached")
+      if (outbound.messages + 1 > limits.outboundMessages) throw new NativeSessionError(503, "native outbound messages limit reached")
+      outbound.bytes += size
+      outbound.messages++
+      queue.push(frame(message))
+      void flush()
+    },
+    close() {
+      if (closed) return
+      closed = true
+      queue.length = 0
+      outbound.bytes = 0
+      outbound.messages = 0
+      rejectWrite?.(new NativeSessionError(410, "native transport was cancelled"))
+      close()
+    },
+  }
+}
+
+// runNative opens a session-owned Run. Its background decoder survives the end
+// of each Chat segment; only terminal completion, failure, or cancellation
+// releases the transport.
+async function runNative({ tok, base, id, tools, conv, convID, signal, maxMode, params, native }) {
+  const cid = convID || randomUUID()
+  const since = Date.now()
+  // Transport shutdown precedes final debt collection. Keep its cancellation
+  // separate, and return any undelivered collection through the ledger's carry.
+  const accounting = new AbortController()
+  const book = ledger(tok, cid, since, accounting.signal, !!convID, { before: since })
+  const debtKey = usageKey(tok, cid)
+  let started = false, settled = false, deferred = null
+  native.accounting = {
+    started() { started = true },
+    async settle() {
+      const more = await book.owed(true)
+      if (settled) {
+        if (more) owe(debtKey, { carry: more })
+        return null
+      }
+      deferred = more
+      return more
+    },
+    delivered() {
+      if (settled) return
+      settled = true
+      deferred = null
+      book.done()
+      accounting.abort()
+    },
+    abandon() {
+      if (settled) return
+      settled = true
+      book.done()
+      accounting.abort()
+      if (deferred) owe(debtKey, { carry: deferred })
+      deferred = null
+      // Every handoff of this owner belongs to one Run. Only an abandoned
+      // started/pending Run is owed; a final snapshot (including zero) is not.
+      if (started && native.segments > 0 && !native.finalUsage && convID && canRead(tok)) {
+        owe(debtKey, { since, n: 1, ready: Date.now() + STEP_WAIT.owedAt })
+      }
+    },
+  }
+  const { first, blobs } = buildRun(conv.msgs, conv.last, tools, id, cid, { maxMode, params })
+  native.chatTools = tools
+  native.attach(signal)
+  if (native.error) {
+    nativeSessions.forget(native)
+    return { error: native.error }
+  }
+  const o = await open(
+    base,
+    {
+      "content-type": "application/connect+proto",
+      "connect-protocol-version": "1",
+      authorization: `Bearer ${tok}`,
+      "x-cursor-client-version": await clientVersion(),
+      "x-cursor-client-type": "cli", // else Cursor adds a prompt of its own
+      "x-ghost-mode": "true", // privacy mode: nothing kept for training
+      "x-request-id": randomUUID(),
+      // none of Cursor's own tools, only the caller's
+      "x-cursor-agent-allowed-tools": "mcp_tool_call,get_mcp_tools_tool_call",
+    },
+    native.ac.signal,
+  )
+  if (o.error) {
+    native.fail(o.error)
+    nativeSessions.forget(native)
+    return o
+  }
+  const { session, req } = o
   const close = () => {
-    ended = true
-    ac.abort()
-    req.destroy()
+    try { req.close(http2.constants.NGHTTP2_CANCEL) } catch {}
+    session.close()
+    session.destroy()
+  }
+  const transport = nativeTransport(req, close, (e) => native.fail({ status: e.status ?? 502, message: e.message }), native.limits)
+  try {
+    native.bind(transport, blobs, conv.estimate)
+    if (native.error) {
+      nativeSessions.forget(native)
+      return { error: native.error }
+    }
+    native.send(first)
+    native.accounting.started()
+    if (o.status < 200 || o.status > 299) {
+      const chunks = []
+      for await (const c of req) chunks.push(c)
+      native.fail(failure(o.status, Buffer.concat(chunks).toString("utf8").slice(0, 1 << 20)))
+      nativeSessions.forget(native)
+      return { error: native.error, h1: !!o.h1 }
+    }
+    native.pumpTask = (async () => {
+      await native.pump(frames(req))
+    })()
+    const response = native.response()
+    const it = response.events
+    const head = await it.next()
+    if (head.done || head.value.error) {
+      const error = head.value?.error ?? { status: 502, message: "an empty reply" }
+      await native.cancel(error.message)
+      nativeSessions.forget(native)
+      return { error, h1: !!o.h1 }
+    }
+    let firstEvent = head
+    response.events = {
+      next() {
+        if (firstEvent) {
+          const r = firstEvent
+          firstEvent = null
+          return Promise.resolve(r)
+        }
+        return it.next()
+      },
+      return: () => it.return(),
+      [Symbol.asyncIterator]() { return this },
+    }
+    return response
+  } catch (e) {
+    native.fail({ status: e.status ?? 502, message: e.message })
+    await native.pumpTask
+    nativeSessions.forget(native)
+    return { error: native.error, h1: !!o.h1 }
   }
-  return Promise.resolve({ session: { close, destroy: close }, req: Object.assign(req, { close }), status: 200, h1: true })
 }
 
 // runOnce is one Run of the chat on the agent API at base: an async
@@ -1865,14 +2162,15 @@ async function runOnce({ tok, base, id, tools, conv, convID, signal, maxMode, pa
   if (o.error) return book.done(), o
   const { session, req } = o
   let closed = false
+  let heartbeat
   const send = (msg) => {
     if (!closed && !req.destroyed && req.writable) req.write(frame(msg))
   }
-  const heartbeat = setInterval(() => send(pb().bytes(7, EMPTY).done()), 5000) // the client is still there, as the CLI says
   const close = () => {
     if (closed) return
     closed = true
     clearInterval(heartbeat)
+    signal?.removeEventListener("abort", close)
     try {
       req.close(http2.constants.NGHTTP2_CANCEL)
     } catch {}
@@ -1880,6 +2178,13 @@ async function runOnce({ tok, base, id, tools, conv, convID, signal, maxMode, pa
     setTimeout(() => session.destroy(), 1000).unref?.()
   }
   signal?.addEventListener("abort", close, { once: true })
+  // Abort can win after open's head check but before this Run takes ownership.
+  if (signal?.aborted) {
+    close()
+    book.done()
+    return cancelledOpen()
+  }
+  heartbeat = setInterval(() => send(pb().bytes(7, EMPTY).done()), 5000) // the client is still there, as the CLI says
   send(first)
   if (o.status < 200 || o.status > 299) {
     const chunks = []
@@ -2125,18 +2430,50 @@ function emptyWhy(how, seen, usage) {
 // exec answers what the server asks the client to run: a call of the
 // caller's tools is returned, the list of them is given, and anything else
 // is refused.
-function exec(msg, tools, send, closeExec, refused) {
-  const es = fields(msg)
+function exec(msg, tools, send, closeExec, refused, native = false) {
+  const es = native ? nativeFields(msg) : fields(msg)
+  // ExecServerMessage.id is a proto3 uint32: an omitted field means zero.
+  // Explicit malformed fields must not acquire that valid default.
+  if (native && es.some((e) => e.num === 1 && (e.wire !== 0 || !Number.isInteger(e.n) || e.n < 0 || e.n > 0xffffffff)))
+    throw new NativeSessionError(502, "invalid native exec request ID")
   const id = pbNum(es, 1)
   const execID = pbStr(es, 15)
+  // Validate every MCP envelope before any exec can publish a call or send a
+  // response. Differing duplicates have no supported selection/merge contract.
+  let nativeCall, nativeUnavailable = false
+  if (native) for (const e of es) if (e.num === 11) {
+    if (e.wire !== 2) throw new NativeSessionError(502, "invalid native MCP argument envelope")
+    const { fields: a, args } = nativeMcpArgs(e.data)
+    const name = pbStr(a, 5) || pbStr(a, 1).replace(/^magpie-/, "")
+    const provider = pbStr(a, 4)
+    const server = pbStr(a, 9)
+    if (provider && provider !== "magpie" || server && server !== "magpie") nativeUnavailable = true
+    if (pbNum(a, 7) || field(a, 6)) nativeUnavailable = true
+    if (!tools.some((t) => t.name === name)) nativeUnavailable = true
+    if (!pbStr(a, 5) && pbStr(a, 1) !== "magpie-" + name) nativeUnavailable = true
+    const call = { requestID: id, execID, nativeID: pbStr(a, 3), name, args }
+    if (nativeCall && !isDeepStrictEqual(nativeCall, call)) throw new NativeSessionError(502, "ambiguous repeated native MCP argument envelopes")
+    nativeCall ??= call
+  }
   const answer = (num, res) => {
     send(pb().bytes(2, pb().varint(1, id).str(15, execID).bytes(num, res)).done())
     closeExec(id)
   }
+  const unavailable = () => {
+    const kind = es.find((e) => ![1, 15, 19, 55].includes(e.num))?.num ?? 0
+    refused?.set(kind, (refused.get(kind) ?? 0) + 1)
+    send(pb().bytes(5, pb().bytes(2, pb().varint(1, id).str(2, "not available"))).done())
+    closeExec(id)
+    return null
+  }
+  // A foreign/unregistered MCP or approval flow is unavailable to this bridge.
+  // Refuse it like a native shell request, then let the model continue.
+  if (nativeUnavailable) return unavailable()
   for (const e of es) {
     switch (e.num) {
       case 11: {
         // mcp_args: a call of the caller's tools
+        if (native) return { ...nativeCall, args: JSON.stringify(nativeCall.args) }
         const a = fields(e.data)
         const args = {}
         for (const kv of a) {
@@ -2164,11 +2501,7 @@ function exec(msg, tools, send, closeExec, refused) {
     }
   }
   // a shell, a file read or an edit of Cursor's own: never run
-  const kind = es.find((e) => e.num !== 1 && e.num !== 15)?.num ?? 0
-  refused?.set(kind, (refused.get(kind) ?? 0) + 1)
-  send(pb().bytes(5, pb().bytes(2, pb().varint(1, id).str(2, "not available"))).done())
-  closeExec(id)
-  return null
+  return unavailable()
 }
 
 // ---- chat completions ------------------------------------------------------------------
@@ -2209,67 +2542,117 @@ async function answerOf(auth, chat, signal, session = "") {
   } catch (e) {
     return errorResponse({ status: e.status ?? 401, message: e.message })
   }
-  const model = String(chat.model ?? "")
-  let raw = []
-  try {
-    raw = await usable(tok)
-  } catch {}
-  // fast only when asked: a service_tier of priority or fast is on; any
-  // other tier, or none, is off, unless the id is a fast one of Cursor's own
-  const tier = chat.service_tier
-  const fast = tier === "priority" || tier === "fast" ? true : tier ? false : undefined
-  const req = request(raw, model, chat.reasoning_effort ?? "", fast)
-  const id = req.id
-  const params = req.params
-  let maxMode = req.maxMode || maxOnly.has(id)
+  if (signal?.aborted) return errorResponse({ status: 410, message: "the request was cancelled" })
   const tools = toolsOf(chat)
-  const conv = conversation(chat, tools)
   const convID = conversationID(chat, session)
-  let base = await agentURL(tok, false)
-  const once = () => runOnce({ tok, base, id, tools, conv, convID, signal, maxMode, params })
-  let r = await once()
-  if (r.error && regional(r.error.message)) {
-    // the team moved, or the config was kept from before: once more with
-    // what the config says now. A Run that went over HTTP/1.1 went to api2,
-    // not the region's agent host: once more over HTTP/2 there.
-    const viaH1 = !!r.h1
-    h1Until = 0
-    const fresh = await agentURL(tok, true)
-    if (fresh !== base || viaH1) {
-      base = fresh
-      r = await once()
+  const prepared = nativeSessions.prepare(tok, chat, convID, tools)
+  let r
+  if (prepared.owner) r = prepared.owner.resume(prepared, signal)
+  const model = String(chat.model ?? "")
+  if (!r) {
+    let raw = []
+    try {
+      raw = await usable(tok)
+    } catch {}
+    // fast only when asked: a service_tier of priority or fast is on; any
+    // other tier, or none, is off, unless the id is a fast one of Cursor's own
+    const tier = chat.service_tier
+    const fast = tier === "priority" || tier === "fast" ? true : tier ? false : undefined
+    const req = request(raw, model, chat.reasoning_effort ?? "", fast)
+    const id = req.id
+    const params = req.params
+    let maxMode = req.maxMode || maxOnly.has(id)
+    const conv = conversation(chat, tools)
+    let base = await agentURL(tok, false)
+    const once = async () => {
+      // Retention is an optimization. Admission pressure or unavailable ownership
+      // 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)
+      const rebuild = async () => {
+        const fallback = await runOnce(args)
+        fallback.diagnostic = "stateless; bootstrap=imported-history; reason=missing-batch-count"
+        return fallback
+      }
+      // A missing native batch count may be retried once, only before Chat
+      // output is exposed or any native result was submitted. Never repeat an
+      // uncertain tool result write or duplicate a progressive stream's output.
+      if (response.error?.retentionIneligible && !signal?.aborted) response = await rebuild()
+      else if (native) response.rebuild = rebuild
+      response.diagnostic ??= "stateless; bootstrap=imported-history; reason=" + (prepared.fallback || "retention capacity or reservation unavailable")
+      return response
     }
-  }
-  if (r.error && !maxMode && maxRequired(r.error.message)) {
-    // a model Cursor serves only in Max Mode that neither list said so of:
-    // in Max Mode, as the CLI turns it on for such a model, and so from
-    // now on. An account Max Mode isn't open to is answered as Cursor
-    // answers that.
-    maxMode = true
-    maxOnly.add(id)
     r = await once()
+    if (r.error && regional(r.error.message)) {
+      // the team moved, or the config was kept from before: once more with
+      // what the config says now. A Run that went over HTTP/1.1 went to api2,
+      // not the region's agent host: once more over HTTP/2 there.
+      const viaH1 = !!r.h1
+      h1Until = 0
+      const fresh = await agentURL(tok, true)
+      if (fresh !== base || viaH1) {
+        base = fresh
+        r = await once()
+      }
+    }
+    if (r.error && !maxMode && maxRequired(r.error.message)) {
+      // a model Cursor serves only in Max Mode that neither list said so of:
+      // in Max Mode, as the CLI turns it on for such a model, and so from
+      // now on. An account Max Mode isn't open to is answered as Cursor
+      // answers that.
+      maxMode = true
+      maxOnly.add(id)
+      r = await once()
+    }
   }
   if (r.error) return errorResponse(r.error)
+  // A resumed owner may fail while submitting results. Surface that uncertain
+  // write once; later history rebuilds never submit it again on that owner.
   const it = r.events
+  let head = await it.next()
+  if (head.value?.error) return errorResponse(head.value.error)
+  let events = {
+    next() {
+      if (head) { const value = head; head = null; return Promise.resolve(value) }
+      return it.next()
+    },
+    return: () => it.return?.(),
+    [Symbol.asyncIterator]() { return this },
+  }
+  const responseHeaders = { "X-Magpie-Cursor-Continuity": r.diagnostic }
   const cid = "chatcmpl-" + randomBytes(12).toString("hex")
   const created = Math.floor(Date.now() / 1000)
 
   if (!chat.stream) {
-    const msg = { role: "assistant", content: "" }
-    let reasoning = ""
-    const calls = []
-    let stop = "stop"
-    let usage
-    for await (const e of it) {
-      if (e.error) return errorResponse(e.error)
-      if (e.text) msg.content += e.text
-      if (e.reasoning) reasoning += e.reasoning
-      if (e.tool) calls.push({ id: e.tool.id, type: "function", function: { name: e.tool.name, arguments: e.tool.args } })
-      if (e.stop) [stop, usage] = [e.stop, e.usage]
+    while (true) {
+      let retry = false
+      const msg = { role: "assistant", content: "" }
+      let reasoning = ""
+      const calls = []
+      let stop = "stop"
+      let usage
+      for await (const e of events) {
+        if (e.error) {
+          if (!e.error.retentionIneligible || !r.rebuild || signal?.aborted) return errorResponse(e.error)
+          r = await r.rebuild()
+          if (r.error) return errorResponse(r.error)
+          events = r.events
+          responseHeaders["X-Magpie-Cursor-Continuity"] = r.diagnostic
+          retry = true
+          break
+        }
+        if (e.text) msg.content += e.text
+        if (e.reasoning) reasoning += e.reasoning
+        if (e.tool) calls.push({ id: e.tool.id, type: "function", function: { name: e.tool.name, arguments: e.tool.args } })
+        if (e.stop) [stop, usage] = [e.stop, e.usage]
+      }
+      if (retry) continue
+      if (reasoning) msg.reasoning_content = reasoning
+      if (calls.length) msg.tool_calls = calls
+      r.delivered?.()
+      return Response.json({ id: cid, object: "chat.completion", created, model, choices: [{ index: 0, message: msg, finish_reason: stop }], ...(usage ? { usage } : {}) }, { headers: responseHeaders })
     }
-    if (reasoning) msg.reasoning_content = reasoning
-    if (calls.length) msg.tool_calls = calls
-    return Response.json({ id: cid, object: "chat.completion", created, model, choices: [{ index: 0, message: msg, finish_reason: stop }], ...(usage ? { usage } : {}) })
   }
 
   const chunk = (delta, finish_reason = null, extra = {}) =>
@@ -2277,16 +2660,17 @@ async function answerOf(auth, chat, signal, session = "") {
   let began = false
   const stream = new ReadableStream({
     async pull(ctl) {
-      const r = await it.next()
+      const next = await events.next()
       if (!began) {
         began = true
         ctl.enqueue(chunk({ role: "assistant", content: "" }))
       }
-      if (r.done) {
+      if (next.done) {
+        r.delivered?.()
         ctl.enqueue(enc.encode("data: [DONE]\n\n"))
         return ctl.close()
       }
-      const e = r.value
+      const e = next.value
       if (e.text) ctl.enqueue(chunk({ content: e.text }))
       else if (e.reasoning) ctl.enqueue(chunk({ reasoning_content: e.reasoning }))
       else if (e.tool) ctl.enqueue(chunk({ tool_calls: [{ index: e.tool.index, id: e.tool.id, type: "function", function: { name: e.tool.name, arguments: e.tool.args } }] }))
@@ -2296,11 +2680,12 @@ async function answerOf(auth, chat, signal, session = "") {
         ctl.close()
       }
     },
-    cancel() {
-      it.return?.()
+    async cancel() {
+      await r.cancel?.()
+      await events.return()
     },
   })
-  return new Response(stream, { status: 200, headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" } })
+  return new Response(stream, { status: 200, headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", ...responseHeaders } })
 }
 
 // ---- the plugin ---------------------------------------------------------------------------
@@ -2397,4 +2782,4 @@ export async function CursorAuthPlugin() {
 }
 
 // for tests
-export const _internal = { onDemandOf,resetH1: () => (h1Until = 0), onH1: () => Date.now() < h1Until, H2, H1, h2Blocked, open, openH1, STEP_WAIT, stepUsage, ledger, owed, flights, misses, unreadable, catalog, usable, request, modelsOf, tokensOf, maxRequired, conversationID, usageOf, sessionOf, SESSION, errorResponse, kept, poolBase, conversation, buildRun, decode, exec, fields, pb, pbValue, pbAny, frame, frames, failure, toolsOf, expiry }
+export const _internal = { nativeTransport, onDemandOf,resetH1: () => (h1Until = 0), onH1: () => Date.now() < h1Until, H2, H1, h2Blocked, open, openH1, openH2, STEP_WAIT, stepUsage, usageKey, ledger, owed, flights, misses, unreadable, catalog, usable, request, modelsOf, tokensOf, maxRequired, conversationID, usageOf, sessionOf, SESSION, errorResponse, kept, poolBase, conversation, buildRun, decode, exec, fields, pb, pbValue, pbAny, frame, frames, failure, toolsOf, expiry }