@tduyng/pi-cursor 0.0.1 → 0.0.3

package/README.md

@@ -1,25 +1,21 @@
 # pi-cursor
 
-Cursor models in Pi through the official Cursor SDK. Pi keeps its own system prompt, tools, approvals, compaction and session tree. Cursor is only the authenticated model transport.
+Cursor models in pi, through the official Cursor SDK. Pi keeps the prompt, the tools, the approvals, the compaction, and the session tree.
 
-No Cursor CLI is installed or called. Login is the SDK browser flow, which mints a stored Cursor API key under `~/.cursor/sdk/auth.json`.
+## What it costs
 
-The provider id is `cursor`, and model ids are Cursor's own ids. `/model cursor/gpt-5.5` and `/model cursor/claude-opus-4-8` work as written.
+No tools, no prompt block, no schema. It is a model provider, so it adds nothing to the context and nothing to the cold start.
+
+What it saves on the wire is the replay. A normal turn sends only the new user message, a tool round sends nothing, and a restarted pi process resumes the same Cursor agent instead of replaying the conversation.
 
 ## Requirements
 
 - Pi 1.4 or newer.
 - Node 24 or newer.
 - A Cursor account.
-- The extension dependency `@cursor/sdk` 1.0.40, installed by the workspace.
+- `@cursor/sdk` 1.0.40, installed by the workspace.
 
-## Install
-
-```sh
-pi install /path/to/extensions/pi-cursor
-```
-
-In this repository the workspace already registers the extension in the root `package.json`.
+No Cursor CLI is installed or called. Login is the SDK browser flow, which mints a stored Cursor key under `~/.cursor/sdk/auth.json`.
 
 ## Login
 
@@ -27,11 +23,11 @@ In this repository the workspace already registers the extension in the root `pa
 /cursor login
 ```
 
-The SDK opens the Cursor login page and mints a key when the browser flow finishes. If the browser does not open, the command prints the URL. `/cursor status` shows the account and `/cursor logout` removes the stored key.
+The SDK opens the Cursor login page and mints a key when the flow finishes. If the browser does not open, the command prints the URL. `/cursor status` shows the account and `/cursor logout` removes the stored key.
 
-`CURSOR_API_KEY` overrides the stored login. The key is read by the SDK, not copied into Pi's `auth.json`.
+`CURSOR_API_KEY` overrides the stored login. The key is read by the SDK and not copied into pi's `auth.json`.
 
-Cursor bills SDK traffic under its own terms. This extension cannot tell you whether a run is plan-included, so check the Cursor dashboard for the account's SDK usage.
+Cursor bills SDK traffic under its own terms, and this extension cannot tell you whether a run is plan-included. Check the Cursor dashboard for the account's SDK usage.
 
 ## Use
 
@@ -39,50 +35,84 @@ Cursor bills SDK traffic under its own terms. This extension cannot tell you whe
 /model cursor/gpt-5.5
 ```
 
-The first model list is a small fallback so `/model` is usable before login. After login, or on the next session start, the extension reads `Cursor.models.list()` and registers every model the account can reach. `/cursor models` prints them.
+The provider id is `cursor` and model ids are Cursor's own. The list comes from `Cursor.models.list()`, cached after the last successful read in `~/.pi/agent/pi-cursor-models.json` at mode 0600 and keyed by the credential. Startup registers the cache with no network call, session start refreshes it, and a small built-in list is the fallback.
+
+A model that offers several context windows is registered once per window: the plain id uses the smallest one, and `cursor/gpt-5.5@1m` asks for 1M. Cursor bills the larger windows as Max Mode, so the small default is the cheap one. `/cursor models` prints them.
+
+`/cursor fast on` adds Cursor's `fast` parameter to every model that exposes it. It is a billing choice, so it stays off until you ask. `/cursor status` shows the current setting.
 
 ## How it works
 
-| Pi                        | Cursor SDK                                                                           |
-| ------------------------- | ------------------------------------------------------------------------------------ |
-| Pi system prompt          | `AgentOptions.systemPrompt`, replaces the Cursor harness prompt                      |
-| Pi tools                  | `LocalAgentOptions.customTools`, one in-process callback per Pi tool                 |
-| Cursor built-ins          | `AgentOptions.tools: ['mcp']`, so only Pi's custom tools exist                       |
-| Cursor rules, skills, MCP | `local.settingSources: []`                                                           |
-| Pi tool execution         | the custom tool callback parks, Pi runs the tool, the next provider call resolves it |
+| Pi | Cursor SDK |
+| --- | --- |
+| Pi system prompt | `AgentOptions.systemPrompt`, replacing the Cursor harness prompt |
+| Pi tools | `LocalAgentOptions.customTools`, one in-process callback per tool |
+| Cursor built-ins | `AgentOptions.tools: ['mcp']`, so only pi's custom tools exist |
+| Cursor rules, skills, MCP | `local.settingSources: []` |
+| Pi tool execution | The callback parks, pi runs the tool, the next provider call resolves it |
+
+A tool call does not end the Cursor run. The callback waits, pi executes the named tool through its normal pipeline, and the next `streamSimple` call resolves the callback with the result. The same run continues, so the model sees the result in the same conversation.
+
+A message you steer in while a tool runs is delivered with `Run.steer`, so the model reads it before its next step. Images attached to such a message become a one-line note, because steering carries text only.
+
+One agent runs per pi session. The agent is replaced only when the prompt, tool set, or working directory changes, or when the pi history diverges, and that replacement replays the conversation once as a single message.
+
+A restarted pi process resumes the same agent instead of replaying. At the end of every clean turn the extension records the agent id with the working folder, prompt and tool hashes, the pi message count, and its own hash of that prefix, in `~/.pi/agent/pi-cursor-agents.json`. The next process calls `Agent.resume` when all of those still match and the pending turn is a single new user message. A stale id, a diverged fork, or a turn killed mid tool round falls back to the replay. The ledger keeps the last 20 sessions, and `/cursor clear`, `/cursor login`, and `/cursor logout` delete it, so those commands really do start from a fresh agent.
+
+There is no HTTP MCP server, no Hono server, and no tool-name rewriting: the SDK invokes the callback directly.
+
+## What the wire costs
 
-A tool call does not end the Cursor run. The callback waits, Pi executes the named tool through its normal pipeline, and the next `streamSimple` call resolves the callback with the result. The same Cursor run continues, so the model sees the tool result in the same conversation.
+Measured on the account this extension was built on, with gpt-5.5 and auto-smart, thinking off:
 
-One Cursor agent runs per Pi session. A normal turn sends only the new user message. A tool round resolves parked callbacks and sends nothing. The agent is only replaced when Pi's prompt, tool set or working directory changes, or when the Pi history diverges. That replacement replays the existing Pi conversation once as a single message.
+| Call | Input tokens | Wall time |
+| --- | --- | --- |
+| First call of an agent | 11.9k fresh plus 2.6k cached | 4.8 to 5.5s |
+| Plain follow-up turn | 12.9k fresh plus 12.7k cached | 2.2s |
+| Call after a tool round | 36.9k fresh plus 36.0k cached | 4.4 to 13s |
 
-There is no HTTP MCP server, no Hono server and no tool-name rewriting. Cursor's SDK invokes the callback directly.
+The tool-round number is Cursor's, not the tool result. The SDK re-prefills its own context around the custom tool callback, so one tool call costs about three plain calls. A turn that ends in a tool call is the slow turn, and there is no pi-side switch for it. The same 32k fresh appears with an empty working directory, so it is not workspace scanning. Fewer, wider tool calls per turn is the lever that exists.
 
-## Token and cache behavior
+Thinking levels map to Cursor model parameters: `thinking` and `effort` for Claude models, `reasoning` for GPT, `effort` for Grok, from the live catalog.
 
-Cursor's backend owns its own conversation and cache. Pi does not replay a linear conversation on every turn, and it does not run a second agent for tool rounds. The Pi system prompt is stable for the lifetime of an agent, and the tool list is stable too. A divergence is the only case that pays a replay.
+## Limits
 
-Thinking levels map to Cursor model parameters. For Claude models the extension sets both `thinking` and `effort`. For GPT models it sets `reasoning`. For Grok it sets `effort`. The mapping comes from the live model catalog.
+- Cursor owns the agent loop and its context management, so pi's compaction does not reach inside a live agent.
 
-## Limitations
+- `AgentOptions.systemPrompt` is server-gated. A rejected prompt comes back as a failed run about 20 seconds in, not from `Agent.create`, so the extension retries that turn with the prompt prepended to the first message.
 
-- Cursor owns the agent loop and its context management. Pi's compaction does not reach inside a live Cursor agent.
-- `AgentOptions.systemPrompt` is server-gated. If Cursor rejects it, the extension recreates the agent without it and prepends Pi's prompt to the first message. That fallback works but spends more tokens because Cursor's harness prompt remains.
-- Usage tokens come from Cursor's `turn-ended` events. Pi shows a zero money cost because Cursor bills outside Pi.
-- Images work in new messages. Replayed history carries images without their original message labels.
-- A model id that Cursor no longer serves fails at `send`, not at model selection.
-- A long Pi tool run is held open by Cursor local runtime. The SDK does not document a timeout for custom tools.
-- The Cursor SDK is a 25 MB dependency with optional platform packages.
+- The rejection is recorded as `noSystemPrompt` in `~/.pi/agent/pi-cursor.json`, and every later agent skips the doomed attempt. Clear it with `/cursor login` or by editing the file, and `/cursor status` shows which path is in use. The fallback works but spends more tokens, because the Cursor harness prompt remains.
 
-## Configuration
+- A failed run reaches pi as an error message, so an empty answer means a broken transport rather than a silent backend rejection.
+
+- Usage tokens come from Cursor's `turn-ended` events plus the run's own total, and pi records each message's share, so the numbers add across a tool round. A message that ends in a tool call shows zero, because that step has not ended server side, and the next message carries both. Pi shows zero money cost because Cursor bills outside pi.
+
+- Images ride with the message that carries them. A replay replaces earlier images with an `[image: mime]` placeholder and keeps only the pending message's images, so reattach one to ask about it again after a restart.
+
+- A model id Cursor no longer serves fails at `send`, not at selection.
+
+- A long pi tool run is held open by the Cursor local runtime, and the SDK documents no timeout for custom tools.
+
+- The SDK is a 25 MB dependency with optional platform packages.
+
+## Configure
+
+`CURSOR_API_KEY` overrides the stored login.
+
+`~/.pi/agent/pi-cursor.json` holds the two preferences: `fast`, from `/cursor fast`, and `noSystemPrompt`, once Cursor has refused pi's prompt for this account.
+
+## Install
+
+```sh
+pi install npm:@tduyng/pi-cursor
+```
 
-| Variable         | Meaning                                         |
-| ---------------- | ----------------------------------------------- |
-| `CURSOR_API_KEY` | Cursor API key. Overrides the stored SDK login. |
+Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-cursor`
 
 ## Tests
 
 ```sh
-bunx vitest run extensions/pi-cursor
+bun test extensions/pi-cursor
 bun run typecheck
 bun run lint:anti-slop
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-cursor",
-  "version": "0.0.1",
-  "description": "Use Cursor models in Pi through the official Cursor SDK, with Pi's own prompt and tools.",
+  "version": "0.0.3",
+  "description": "Cursor models in Pi through the official Cursor SDK: one warm agent per session, Pi's own prompt and tools, resumed instead of replayed.",
   "keywords": [
     "pi",
     "pi-package",

package/src/catalog.ts

@@ -0,0 +1,69 @@
+import { readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+import { Validator, type Infer } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+import type { ModelInfo } from './models.js'
+
+const ParameterValue = t.object({ value: t.string(), displayName: t.optional(t.string()) })
+const Parameter = t.object({
+    id: t.string(),
+    displayName: t.optional(t.string()),
+    values: t.array(ParameterValue)
+})
+const Variant = t.object({
+    params: t.array(t.object({ id: t.string(), value: t.string() })),
+    displayName: t.string(),
+    isDefault: t.optional(t.boolean())
+})
+const CachedModel = t.object({
+    id: t.string(),
+    displayName: t.string(),
+    parameters: t.optional(t.array(Parameter)),
+    variants: t.optional(t.array(Variant))
+})
+const CachedCatalog = t.object({ key: t.string(), models: t.array(CachedModel) })
+
+const isCatalog = new Validator(CachedCatalog).isValidObject
+
+export type KnownCatalog = Infer<typeof CachedCatalog>
+
+function cachePath(): string {
+    return join(getAgentDir(), 'pi-cursor-models.json')
+}
+
+export function parseCatalog(text: string, key: string): ModelInfo[] | undefined {
+    try {
+        const parsed: unknown = JSON.parse(text)
+        if (!isCatalog(parsed) || parsed.key !== key) return undefined
+        return parsed.models
+    } catch {
+        return undefined
+    }
+}
+
+export function readCatalog(key: string): ModelInfo[] | undefined {
+    try {
+        return parseCatalog(readFileSync(cachePath(), 'utf8'), key)
+    } catch {
+        return undefined
+    }
+}
+
+export function writeCatalog(key: string, models: ModelInfo[]): void {
+    const path = cachePath()
+    const temp = `${path}.${process.pid}.tmp`
+    const catalog: KnownCatalog = {
+        key,
+        models: models.map((model) => ({
+            id: model.id,
+            displayName: model.displayName,
+            parameters: model.parameters,
+            variants: model.variants
+        }))
+    }
+    writeFileSync(temp, JSON.stringify(catalog), { mode: 0o600 })
+    renameSync(temp, path)
+}

package/src/index.ts

@@ -2,7 +2,10 @@ import type { SdkLoginOptions } from '@cursor/sdk'
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent'
 
 import { fallbackModels, rememberModels, toPiModels, type PiModelEntry } from './models.js'
+import { readCatalog, writeCatalog } from './catalog.js'
 import { cursorApiKey, cursorSdk } from './sdk.js'
+import { dropAllRecords } from './resume.js'
+import { noSystemPrompt, patchState } from './state.js'
 import { allSessions, dropSessions, sweep } from './session.js'
 import { createRuntime, streamCursor } from './turn.js'
 
@@ -12,7 +15,10 @@ const IDLE_MS = 20 * 60_000
 
 export default function piCursor(pi: ExtensionAPI): void {
     const runtime = createRuntime()
-    let models: PiModelEntry[] = fallbackModels()
+    const catalogKey = () => cursorApiKey() ?? 'stored-login'
+    const cached = readCatalog(catalogKey())
+    let models: PiModelEntry[] = cached && cached.length > 0 ? toPiModels(cached) : fallbackModels()
+    if (cached && cached.length > 0) rememberModels(cached)
     let refreshing: Promise<PiModelEntry[]> | undefined
     let refreshed = false
     let sweeper: ReturnType<typeof setInterval> | undefined
@@ -36,8 +42,9 @@ export default function piCursor(pi: ExtensionAPI): void {
                 const { Cursor } = await cursorSdk()
                 const items = await Cursor.models.list({ apiKey: cursorApiKey() })
                 rememberModels(items)
+                writeCatalog(catalogKey(), items)
                 const next = toPiModels(items)
-                if (next.length > 0) register(next)
+                if (next.length > 0) models = next
                 return models
             } catch {
                 return models
@@ -82,7 +89,9 @@ export default function piCursor(pi: ExtensionAPI): void {
         }
         if (ctx.signal) options.signal = ctx.signal
         const result = await Cursor.auth.login(options)
-        await refresh()
+        patchState({ noSystemPrompt: false })
+        dropAllRecords()
+        register(await refresh())
         await show(
             `Cursor: logged in${result.email ? ` as ${result.email}` : ''}. ${models.length} model(s) available.`
         )
@@ -97,6 +106,7 @@ export default function piCursor(pi: ExtensionAPI): void {
                 { value: 'logout', label: 'logout', description: 'forget the SDK credential' },
                 { value: 'models', label: 'models', description: 'every Cursor model the provider exposes' },
                 { value: 'clear', label: 'clear', description: 'close every warm Cursor agent' },
+                { value: 'fast', label: 'fast', description: 'toggle cursor fast mode: fast on|off' },
                 { value: 'help', label: 'help', description: 'usage' }
             ].filter((item) => item.value.startsWith(prefix.trim())),
         handler: async (args: string, ctx: ExtensionCommandContext) => {
@@ -108,6 +118,7 @@ export default function piCursor(pi: ExtensionAPI): void {
             if (sub === 'logout') {
                 const { Cursor } = await cursorSdk()
                 await Cursor.auth.logout()
+                dropAllRecords()
                 rememberModels([])
                 register(fallbackModels())
                 await show('Cursor: logged out. The SDK credential is gone.')
@@ -115,9 +126,21 @@ export default function piCursor(pi: ExtensionAPI): void {
             }
             if (sub === 'clear') {
                 dropSessions(runtime.sessions)
+                dropAllRecords()
                 await show('Cursor: closed every warm agent.')
                 return
             }
+            if (sub === 'fast') {
+                const value = args.trim().split(/\s+/).filter(Boolean)[1]
+                if (value !== 'on' && value !== 'off') {
+                    await show(`Cursor fast mode is ${runtime.fast ? 'on' : 'off'}. Use /cursor fast on|off.`)
+                    return
+                }
+                runtime.fast = value === 'on'
+                patchState({ fast: runtime.fast })
+                await show(`Cursor fast mode ${runtime.fast ? 'on' : 'off'} for models that expose it.`)
+                return
+            }
             if (sub === 'models') {
                 await show(
                     [
@@ -130,12 +153,13 @@ export default function piCursor(pi: ExtensionAPI): void {
             if (sub === 'help') {
                 await show(
                     [
-                        'Usage: /cursor [status|login|logout|models|clear|help]',
+                        'Usage: /cursor [status|login|logout|models|clear|fast|help]',
                         '',
                         'Login uses the official Cursor SDK browser flow and mints a stored API key.',
                         'No Cursor CLI is installed or called.',
                         'Pick a model with /model, for example cursor/gpt-5.5.',
-                        'CURSOR_API_KEY overrides the stored SDK login.'
+                        'CURSOR_API_KEY overrides the stored SDK login.',
+                        'Models default to their smallest context window. Pick /model cursor/gpt-5.5@1m for the 1M one.',
                     ].join('\n')
                 )
                 return
@@ -157,6 +181,12 @@ export default function piCursor(pi: ExtensionAPI): void {
                     `credential: ${cursorApiKey() ? 'CURSOR_API_KEY' : 'stored SDK login'}`,
                     `models: ${models.length}`,
                     `live agents: ${sessions.length}, parked tool calls: ${parked}`,
+                    `system prompt: ${
+                        noSystemPrompt()
+                            ? 'not enabled for this account, Pi prompt rides in the first message'
+                            : 'sent as AgentOptions.systemPrompt'
+                    }`,
+                    `fast mode: ${runtime.fast ? 'on' : 'off'}`,
                     'prompt: Pi system prompt and Pi tools only; Cursor built-in tools disabled'
                 ].join('\n')
             )

package/src/models.ts

@@ -0,0 +1,198 @@
+import type { ModelListItem, ModelParameterDefinition, ModelParameterValue } from '@cursor/sdk'
+import type { ModelThinkingLevel, ThinkingLevelMap } from '@earendil-works/pi-ai'
+
+export type PiModelEntry = {
+    id: string
+    name: string
+    reasoning: boolean
+    thinkingLevelMap?: ThinkingLevelMap
+    input: ('text' | 'image')[]
+    cost: { input: number; output: number; cacheRead: number; cacheWrite: number }
+    contextWindow: number
+    maxTokens: number
+}
+
+export type ModelSelection = { id: string; params?: ModelParameterValue[] }
+
+type ThinkingParams = { boolean?: ModelParameterDefinition; levels?: ModelParameterDefinition }
+
+const LEVELS: ModelThinkingLevel[] = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']
+export type ModelInfo = Pick<ModelListItem, 'id' | 'displayName' | 'parameters' | 'variants'>
+
+const catalog = new Map<string, ModelInfo>()
+
+const FALLBACK_MODELS: PiModelEntry[] = [
+    entry('auto-smart', 'Auto'),
+    entry('claude-opus-4-8', 'Claude Opus 4.8', 300_000),
+    entry('claude-sonnet-5-5', 'Claude Sonnet 5.5'),
+    entry('gpt-5.5', 'GPT-5.5', 272_000),
+    entry('grok-4.6', 'Grok 4.6', 256_000),
+    entry('composer-2.5', 'Composer 2.5'),
+    entry('gemini-3.7-flash', 'Gemini 3.7 Flash')
+]
+
+function entry(id: string, name: string, contextWindow = 200_000): PiModelEntry {
+    return {
+        id,
+        name,
+        reasoning: false,
+        input: ['text', 'image'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow,
+        maxTokens: 32_768
+    }
+}
+
+export function rememberModels(items: ModelInfo[]): void {
+    catalog.clear()
+    for (const item of items) catalog.set(item.id, item)
+}
+
+export function fallbackModels(): PiModelEntry[] {
+    return FALLBACK_MODELS.map((model) => ({ ...model }))
+}
+
+export function toPiModels(items: ModelInfo[]): PiModelEntry[] {
+    const entries: PiModelEntry[] = []
+    for (const item of items) {
+        const contexts = contextValues(item)
+        entries.push(toPiModel(item, undefined, contexts[0]))
+        for (const context of contexts.slice(1)) entries.push(toPiModel(item, context, context))
+    }
+    return entries
+}
+
+export type ModelIdParts = { base: string; context?: string }
+
+export function parseModelId(id: string): ModelIdParts {
+    const match = /^(.+)@(\d+[km])$/.exec(id)
+    if (!match?.[1] || !match[2]) return { base: id }
+    return { base: match[1], context: match[2] }
+}
+
+function contextValues(item: ModelInfo): string[] {
+    const values = item.parameters?.find((candidate) => candidate.id === 'context')?.values.map((value) => value.value)
+    if (!values) return []
+    return values.toSorted((left, right) => contextSize(left) - contextSize(right))
+}
+
+function contextSize(context: string): number {
+    const match = /^(\d+)([km])$/.exec(context)
+    if (!match?.[1] || !match[2]) return Number.MAX_SAFE_INTEGER
+    const size = Number(match[1])
+    return match[2] === 'm' ? size * 1_000_000 : size * 1_000
+}
+
+export function contextWindowOf(id: string): number {
+    const { base, context } = parseModelId(id)
+    if (context) return contextSize(context)
+    return contextWindowFor(base)
+}
+
+function toPiModel(item: ModelInfo, suffix: string | undefined, window: string | undefined): PiModelEntry {
+    const params = thinkingParams(item)
+    const id = suffix ? `${item.id}@${suffix}` : item.id
+    const displayName = item.displayName || item.id
+    const name = suffix ? `${displayName} ${suffix.toUpperCase()}` : displayName
+    const model = entry(id, name, window ? contextSize(window) : contextWindowFor(item.id))
+    if (params) {
+        model.reasoning = true
+        model.thinkingLevelMap = thinkingLevelMap(params)
+    }
+    return model
+}
+
+function thinkingParams(item: ModelInfo): ThinkingParams | undefined {
+    const boolean = item.parameters?.find(
+        (candidate) =>
+            candidate.id === 'thinking' &&
+            candidate.values.length > 0 &&
+            candidate.values.every((value) => value.value === 'true' || value.value === 'false')
+    )
+    const levels =
+        item.parameters?.find((candidate) => candidate.id === 'effort' && candidate.values.length > 0) ??
+        item.parameters?.find((candidate) => candidate.id === 'reasoning' && candidate.values.length > 0)
+    if (!boolean && !levels) return undefined
+    return { boolean, levels }
+}
+
+function thinkingLevelMap(params: ThinkingParams): ThinkingLevelMap | undefined {
+    const map: ThinkingLevelMap = {}
+    let any = false
+    for (const level of LEVELS) {
+        let value: string | undefined
+        if (level === 'off') value = params.boolean ? 'false' : mapLevel(params.levels, level)
+        else if (params.levels) value = mapLevel(params.levels, level)
+        else value = params.boolean ? 'true' : undefined
+        map[level] = value ?? null
+        if (value) any = true
+    }
+    return any ? map : undefined
+}
+
+function mapLevel(param: ModelParameterDefinition | undefined, level: ModelThinkingLevel): string | undefined {
+    const values = param?.values.map((value) => value.value) ?? []
+    if (level === 'off') return values.find((value) => value === 'none' || value === 'false' || value === 'off')
+    if (level === 'minimal') {
+        return values.find((value) => value === 'minimal') ?? values.find((value) => value === 'low')
+    }
+    if (level === 'low') return values.find((value) => value === 'low')
+    if (level === 'medium') return values.find((value) => value === 'medium')
+    if (level === 'high') return values.find((value) => value === 'high')
+    if (level === 'xhigh') {
+        return values.find((value) => value === 'xhigh') ?? values.find((value) => value === 'extra-high')
+    }
+    return (
+        values.find((value) => value === 'max') ??
+        values.find((value) => value === 'xhigh') ??
+        values.find((value) => value === 'extra-high')
+    )
+}
+
+export function selectionFor(id: string, level: ModelThinkingLevel | undefined, fast = false): ModelSelection {
+    const { base, context } = parseModelId(id)
+    const item = catalog.get(base)
+    if (!item) return { id: base }
+    const variant = item.variants?.find((candidate) => candidate.isDefault) ?? item.variants?.[0]
+    const ordered = variant?.params.map((param) => param.id) ?? []
+    const values = new Map<string, string>()
+    for (const param of variant?.params ?? []) values.set(param.id, param.value)
+    const chosenContext = context ?? contextValues(item)[0]
+    if (chosenContext) {
+        values.set('context', chosenContext)
+        if (!ordered.includes('context')) ordered.push('context')
+    }
+    if (fast && item.parameters?.some((candidate) => candidate.id === 'fast')) {
+        values.set('fast', 'true')
+        if (!ordered.includes('fast')) ordered.push('fast')
+    }
+    const params = thinkingParams(item)
+    if (params && level) {
+        if (params.boolean) {
+            values.set(params.boolean.id, level === 'off' ? 'false' : 'true')
+            if (!ordered.includes(params.boolean.id)) ordered.push(params.boolean.id)
+        }
+        if (params.levels) {
+            const value = mapLevel(params.levels, level)
+            if (value) values.set(params.levels.id, value)
+            if (!ordered.includes(params.levels.id)) ordered.push(params.levels.id)
+        }
+    }
+    const result: ModelParameterValue[] = []
+    for (const key of ordered) {
+        const value = values.get(key)
+        if (value !== undefined) result.push({ id: key, value })
+    }
+    return result.length > 0 ? { id: base, params: result } : { id: base }
+}
+
+export function contextWindowFor(id: string): number {
+    if (id.startsWith('gpt-5')) return 272_000
+    if (id.startsWith('grok')) return 256_000
+    return 200_000
+}
+
+export function modelName(id: string): string {
+    const { base } = parseModelId(id)
+    return catalog.get(base)?.displayName ?? FALLBACK_MODELS.find((model) => model.id === base)?.name ?? id
+}

package/src/resume.ts

@@ -0,0 +1,81 @@
+import { readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+import { Validator, type Infer } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+import type { SessionKey } from './session.js'
+import type { Transcript, TurnMessage } from './transcript.js'
+
+const ResumeRecord = t.object({
+    sessionId: t.string(),
+    agentId: t.string(),
+    cwd: t.string(),
+    toolsHash: t.string(),
+    count: t.number(),
+    chain: t.string(),
+    at: t.number()
+})
+
+const ResumeLedger = t.object({ records: t.array(ResumeRecord) })
+
+const isLedger = new Validator(ResumeLedger).isValidObject
+
+export type AgentRecord = Infer<typeof ResumeRecord>
+
+const KEEP = 20
+
+function ledgerPath(): string {
+    return join(getAgentDir(), 'pi-cursor-agents.json')
+}
+
+function readLedger(): AgentRecord[] {
+    try {
+        const parsed: unknown = JSON.parse(readFileSync(ledgerPath(), 'utf8'))
+        return isLedger(parsed) ? parsed.records : []
+    } catch {
+        return []
+    }
+}
+
+export function dropAllRecords(): void {
+    rmSync(ledgerPath(), { force: true })
+}
+
+export function readRecord(sessionId: string): AgentRecord | undefined {
+    return readLedger().findLast((record) => record.sessionId === sessionId)
+}
+
+export function writeRecord(record: AgentRecord): void {
+    const records = readLedger().filter((candidate) => candidate.sessionId !== record.sessionId)
+    records.push(record)
+    const path = ledgerPath()
+    const temp = `${path}.${process.pid}.tmp`
+    const kept = records.toSorted((left, right) => left.at - right.at).slice(-KEEP)
+    writeFileSync(temp, JSON.stringify({ records: kept }), { mode: 0o600 })
+    renameSync(temp, path)
+}
+
+export function dropRecord(sessionId: string): void {
+    const records = readLedger().filter((candidate) => candidate.sessionId !== sessionId)
+    const path = ledgerPath()
+    const temp = `${path}.${process.pid}.tmp`
+    writeFileSync(temp, JSON.stringify({ records }), { mode: 0o600 })
+    renameSync(temp, path)
+}
+
+export function resumeTail(
+    record: AgentRecord,
+    transcript: Transcript,
+    key: SessionKey
+): TurnMessage[] | undefined {
+    if (record.cwd !== key.cwd) return undefined
+    if (record.toolsHash !== key.toolsHash) return undefined
+    if (record.count >= transcript.chain.length) return undefined
+    if (transcript.chain[record.count] !== record.chain) return undefined
+    const tail = transcript.messages.slice(record.count)
+    if (tail.some((message) => message.role === 'assistant' || message.role === 'toolResult')) return undefined
+    if (!tail.some((message) => message.role === 'user')) return undefined
+    return tail
+}

package/src/session.ts

@@ -1,7 +1,17 @@
-import type { AgentOptions, Run, SDKAgent, SDKCustomTool, SDKCustomToolResult, TokenUsage } from '@cursor/sdk'
+import type {
+    AgentOptions,
+    Run,
+    RunResult,
+    SDKAgent,
+    SDKCustomTool,
+    SDKCustomToolResult,
+    TokenUsage
+} from '@cursor/sdk'
 import type { AssistantMessage, Tool, ToolResultMessage } from '@earendil-works/pi-ai'
+import type { AgentRecord } from './resume.js'
 
 import { sha, type JsonObject } from './json.js'
+import { noSystemPrompt, patchState } from './state.js'
 import { selectionFor, type ModelSelection } from './models.js'
 import { cursorApiKey, cursorSdk } from './sdk.js'
 import {
@@ -44,6 +54,7 @@ export type CursorSession = {
     chain: string
     count: number
     usage?: TokenUsage
+    reported?: TokenUsage
     toolCounter: number
     promptFallback?: boolean
     promptSent?: boolean
@@ -129,6 +140,7 @@ export function createSession(
         chain: transcript.chain[transcript.messages.length] ?? transcript.chain[0] ?? sha('prompt'),
         count: transcript.messages.length,
         toolCounter: 0,
+        promptFallback: noSystemPrompt(),
         busy: true,
         dead: false,
         lastUsed: Date.now()
@@ -178,23 +190,25 @@ export function updateChain(session: CursorSession, transcript: Transcript, outp
     session.lastUsed = Date.now()
 }
 
+function agentOptions(session: CursorSession, model: string, systemPrompt: string | undefined): AgentOptions {
+    const options: AgentOptions = {
+        apiKey: cursorApiKey(),
+        model: selectionFor(model, undefined),
+        tools: ['mcp'],
+        local: {
+            cwd: session.key.cwd,
+            settingSources: [],
+            customTools: customTools(session)
+        }
+    }
+    if (systemPrompt !== undefined) options.systemPrompt = systemPrompt
+    return options
+}
+
 export async function ensureAgent(session: CursorSession, model: string): Promise<SDKAgent> {
     if (session.agent) return session.agent
     const { Agent } = await cursorSdk()
-    const create = (systemPrompt: string | undefined) => {
-        const options: AgentOptions = {
-            apiKey: cursorApiKey(),
-            model: selectionFor(model, undefined),
-            tools: ['mcp'],
-            local: {
-                cwd: session.key.cwd,
-                settingSources: [],
-                customTools: customTools(session)
-            }
-        }
-        if (systemPrompt !== undefined) options.systemPrompt = systemPrompt
-        return Agent.create(options)
-    }
+    const create = (systemPrompt: string | undefined) => Agent.create(agentOptions(session, model, systemPrompt))
     try {
         session.agent = await create(session.promptFallback ? undefined : session.systemPrompt)
         return session.agent
@@ -203,6 +217,7 @@ export async function ensureAgent(session: CursorSession, model: string): Promis
         if (!session.promptFallback && /system.?prompt/i.test(message)) {
             session.promptFallback = true
             session.agent = await create(undefined)
+            patchState({ noSystemPrompt: true })
             return session.agent
         }
         if (/auth|api.?key|login|credential/i.test(message)) {
@@ -212,6 +227,32 @@ export async function ensureAgent(session: CursorSession, model: string): Promis
     }
 }
 
+export async function resumeSession(
+    store: CursorSessionStore,
+    id: string,
+    key: SessionKey,
+    systemPrompt: string,
+    tools: Tool[],
+    transcript: Transcript,
+    model: string,
+    record: AgentRecord
+): Promise<CursorSession | undefined> {
+    const session = createSession(store, id, key, systemPrompt, tools, transcript)
+    session.promptFallback = noSystemPrompt()
+    session.promptSent = true
+    session.count = record.count
+    session.chain = record.chain
+    try {
+        const { Agent } = await cursorSdk()
+        const prompt = session.promptFallback ? undefined : systemPrompt
+        session.agent = await Agent.resume(record.agentId, agentOptions(session, model, prompt))
+        return session
+    } catch {
+        dropSession(store, session)
+        return undefined
+    }
+}
+
 function customTools(session: CursorSession) {
     const tools: Record<string, SDKCustomTool> = {}
     for (const tool of session.tools) {
@@ -241,6 +282,7 @@ export async function startRun(session: CursorSession, input: CursorInput, selec
     const payload = session.promptFallback && !session.promptSent ? withPreamble(input, session.systemPrompt) : input
     if (session.promptFallback) session.promptSent = true
     session.usage = undefined
+    session.reported = undefined
     let run: Run
     try {
         run = await agent.send(toSdkMessage(payload), {
@@ -249,22 +291,14 @@ export async function startRun(session: CursorSession, input: CursorInput, selec
                 if (update.type === 'text-delta') session.queue.push({ kind: 'text', text: update.text })
                 else if (update.type === 'thinking-delta') session.queue.push({ kind: 'thinking', text: update.text })
                 else if (update.type === 'turn-ended' && update.usage) {
-                    const usage = update.usage
-                    session.usage = {
-                        ...usage,
-                        totalTokens:
-                            usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
-                    }
+                    session.usage = addUsage(session.usage, normalizeUsage(update.usage))
                 }
             }
         })
     } catch (error) {
         const message = error instanceof Error ? error.message : String(error)
         if (!session.promptFallback && /system.?prompt/i.test(message)) {
-            session.promptFallback = true
-            session.agent?.close()
-            session.agent = undefined
-            await startRun(session, input, selection)
+            await restartWithoutPrompt(session, input, selection)
             return
         }
         throw error
@@ -272,8 +306,17 @@ export async function startRun(session: CursorSession, input: CursorInput, selec
     session.run = run
     void run
         .wait()
-        .then((result) => {
-            if (!session.usage && result.usage) session.usage = result.usage
+        .then(async (result) => {
+            if (result.usage) session.usage = largerUsage(session.usage, normalizeUsage(result.usage))
+            const outcome = outcomeOf(result, session.promptFallback === true)
+            if (outcome.kind === 'retry') {
+                await restartWithoutPrompt(session, input, selection)
+                return
+            }
+            if (outcome.kind === 'error') {
+                session.queue.push({ kind: 'error', message: outcome.message })
+                return
+            }
             session.queue.push({ kind: 'done' })
         })
         .catch((error: Error) => {
@@ -281,6 +324,72 @@ export async function startRun(session: CursorSession, input: CursorInput, selec
         })
 }
 
+type ReportedUsage = Omit<TokenUsage, 'totalTokens'>
+
+function normalizeUsage(usage: ReportedUsage): TokenUsage {
+    return {
+        ...usage,
+        totalTokens: usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
+    }
+}
+
+export function addUsage(current: TokenUsage | undefined, next: TokenUsage): TokenUsage {
+    if (!current) return { ...next }
+    const reasoning = current.reasoningTokens
+    const extra = next.reasoningTokens
+    const total: TokenUsage = {
+        inputTokens: current.inputTokens + next.inputTokens,
+        outputTokens: current.outputTokens + next.outputTokens,
+        cacheReadTokens: current.cacheReadTokens + next.cacheReadTokens,
+        cacheWriteTokens: current.cacheWriteTokens + next.cacheWriteTokens,
+        totalTokens: current.totalTokens + next.totalTokens
+    }
+    if (reasoning !== undefined || extra !== undefined) total.reasoningTokens = (reasoning ?? 0) + (extra ?? 0)
+    return total
+}
+
+export function largerUsage(current: TokenUsage | undefined, next: TokenUsage): TokenUsage {
+    if (!current || next.totalTokens > current.totalTokens) return { ...next }
+    return current
+}
+
+export function usageDelta(total: TokenUsage | undefined, reported: TokenUsage | undefined): TokenUsage | undefined {
+    if (!total) return undefined
+    if (!reported) return total
+    const delta: TokenUsage = {
+        inputTokens: Math.max(total.inputTokens - reported.inputTokens, 0),
+        outputTokens: Math.max(total.outputTokens - reported.outputTokens, 0),
+        cacheReadTokens: Math.max(total.cacheReadTokens - reported.cacheReadTokens, 0),
+        cacheWriteTokens: Math.max(total.cacheWriteTokens - reported.cacheWriteTokens, 0),
+        totalTokens: Math.max(total.totalTokens - reported.totalTokens, 0)
+    }
+    if (total.reasoningTokens !== undefined) {
+        delta.reasoningTokens = Math.max(total.reasoningTokens - (reported.reasoningTokens ?? 0), 0)
+    }
+    return delta
+}
+
+export type RunOutcome = { kind: 'done' } | { kind: 'retry' } | { kind: 'error'; message: string }
+
+export function outcomeOf(result: RunResult, promptFallback: boolean): RunOutcome {
+    if (result.status !== 'error') return { kind: 'done' }
+    const message = result.error?.message ?? 'the Cursor run failed'
+    if (!promptFallback && /system.?prompt/i.test(message)) return { kind: 'retry' }
+    return { kind: 'error', message }
+}
+
+async function restartWithoutPrompt(
+    session: CursorSession,
+    input: CursorInput,
+    selection: ModelSelection
+): Promise<void> {
+    session.promptFallback = true
+    session.agent?.close()
+    session.agent = undefined
+    await startRun(session, input, selection)
+    patchState({ noSystemPrompt: true })
+}
+
 export function deliverToolResult(session: CursorSession, message: ToolResultMessage): void {
     const result = toolResultCustom(message)
     const resolve = session.parked.get(message.toolCallId)

package/src/state.ts

@@ -0,0 +1,43 @@
+import { readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+import { Validator, type Infer } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+const CursorPreferences = t.object({
+    noSystemPrompt: t.optional(t.boolean()),
+    fast: t.optional(t.boolean())
+})
+
+const isPreferences = new Validator(CursorPreferences).isValidObject
+
+export type CursorState = Infer<typeof CursorPreferences>
+
+function statePath(): string {
+    return join(getAgentDir(), 'pi-cursor.json')
+}
+
+export function readState(): CursorState {
+    try {
+        const parsed: unknown = JSON.parse(readFileSync(statePath(), 'utf8'))
+        return isPreferences(parsed) ? parsed : {}
+    } catch {
+        return {}
+    }
+}
+
+export function patchState(patch: CursorState): void {
+    const path = statePath()
+    const temp = `${path}.${process.pid}.tmp`
+    writeFileSync(temp, JSON.stringify({ ...readState(), ...patch }), { mode: 0o600 })
+    renameSync(temp, path)
+}
+
+export function noSystemPrompt(): boolean {
+    return readState().noSystemPrompt === true
+}
+
+export function fastMode(): boolean {
+    return readState().fast === true
+}

package/src/transcript.ts

@@ -181,15 +181,13 @@ export function replayInput(messages: TurnMessage[]): CursorInput {
         if (rendered) parts.push(`ASSISTANT:\n${rendered}`)
     }
 
+    const pending = messages.findLast((message) => message.role === 'user')
     const images: CursorImage[] = []
-    for (const message of messages) {
-        if (message.role !== 'user' || !Array.isArray(message.content)) continue
-        for (const block of message.content) {
-            if (block.type !== 'image') continue
-            images.push(image(block))
+    if (pending && Array.isArray(pending.content)) {
+        for (const block of pending.content) {
+            if (block.type === 'image') images.push(image(block))
         }
     }
-    if (images.length > 0) parts.push(`The replay includes ${images.length} image(s) from earlier user messages.`)
     return { text: parts.join('\n\n'), images }
 }
 

package/src/turn.ts

@@ -11,6 +11,8 @@ import {
 } from '@earendil-works/pi-ai'
 
 import { sha } from './json.js'
+import { fastMode } from './state.js'
+import { dropRecord, readRecord, resumeTail, writeRecord } from './resume.js'
 import { selectionFor } from './models.js'
 import {
     attachSession,
@@ -19,8 +21,10 @@ import {
     deliverToolResult,
     dropSession,
     failMissingResults,
+    resumeSession,
     startRun,
     updateChain,
+    usageDelta,
     type Attached,
     type CursorSession,
     type CursorEvent,
@@ -29,10 +33,10 @@ import {
 } from './session.js'
 import { readTranscript, replayInput, systemPreamble, userInput, type CursorContext } from './transcript.js'
 
-export type CursorRuntime = { sessions: CursorSessionStore }
+export type CursorRuntime = { sessions: CursorSessionStore; fast: boolean }
 
 export function createRuntime(): CursorRuntime {
-    return { sessions: createSessionStore() }
+    return { sessions: createSessionStore(), fast: fastMode() }
 }
 
 const TOOL_GRACE_MS = 250
@@ -113,7 +117,7 @@ async function runTurn(
             .join('\n\n')
         const key: SessionKey = { systemPrompt, toolsHash: transcript.toolsHash, cwd }
         const sessionId = options?.sessionId ?? sha(systemPrompt)
-        const selection = selectionFor(model.id, options?.reasoning)
+        const selection = selectionFor(model.id, options?.reasoning, runtime.fast)
         let attached: Attached | undefined = attachSession(runtime.sessions, transcript, key)
         if (attached?.session.dead) {
             dropSession(runtime.sessions, attached.session)
@@ -140,6 +144,14 @@ async function runTurn(
                 }
                 failMissingResults(active, seen)
                 active.awaiting.clear()
+                const steering = userInput(rest)
+                if (steering.text.length > 0 && active.run?.steer) {
+                    const note =
+                        steering.images.length > 0
+                            ? `${steering.text}\n[${steering.images.length} image(s) could not be injected mid-turn]`
+                            : steering.text
+                    await active.run.steer(note)
+                }
             } else {
                 const input = userInput(rest)
                 if (input.text.length === 0 && input.images.length === 0) {
@@ -151,9 +163,37 @@ async function runTurn(
             const previous = runtime.sessions.sessions.get(sessionId)
             if (previous?.busy) throw new Error('this Pi session already has a request in flight')
             if (previous) dropSession(runtime.sessions, previous)
-            const created = createSession(runtime.sessions, sessionId, key, systemPrompt, transcript.tools, transcript)
-            session = created
-            await startRun(created, replayInput(transcript.messages), selection)
+            const record = options?.sessionId ? readRecord(options.sessionId) : undefined
+            const tail = record ? resumeTail(record, transcript, key) : undefined
+            const resumed =
+                record && tail
+                    ? await resumeSession(
+                          runtime.sessions,
+                          sessionId,
+                          key,
+                          systemPrompt,
+                          transcript.tools,
+                          transcript,
+                          model.id,
+                          record
+                      )
+                    : undefined
+            if (resumed && tail) {
+                session = resumed
+                await startRun(resumed, userInput(tail), selection)
+            } else {
+                if (record && options?.sessionId) dropRecord(options.sessionId)
+                const created = createSession(
+                    runtime.sessions,
+                    sessionId,
+                    key,
+                    systemPrompt,
+                    transcript.tools,
+                    transcript
+                )
+                session = created
+                await startRun(created, replayInput(transcript.messages), selection)
+            }
         }
 
         const active = session
@@ -180,6 +220,18 @@ async function runTurn(
             active.abortCleanup?.()
             active.abortCleanup = undefined
             active.run = undefined
+            const agentId = active.agent?.agentId
+            if (options?.sessionId && agentId) {
+                writeRecord({
+                    sessionId: options.sessionId,
+                    agentId,
+                    cwd: key.cwd,
+                    toolsHash: key.toolsHash,
+                    count: active.count,
+                    chain: active.chain,
+                    at: Date.now()
+                })
+            }
         }
 
         stream.push({ type: 'done', reason: step.reason, message: output })
@@ -196,15 +248,16 @@ async function runTurn(
 }
 
 function applyUsage(output: AssistantMessage, session: CursorSession): void {
-    const usage = session.usage
-    if (!usage) return
-    output.usage.input = usage.inputTokens
-    output.usage.output = usage.outputTokens
-    output.usage.cacheRead = usage.cacheReadTokens
-    output.usage.cacheWrite = usage.cacheWriteTokens
+    const delta = usageDelta(session.usage, session.reported)
+    if (!delta) return
+    session.reported = session.usage ? { ...session.usage } : undefined
+    output.usage.input = delta.inputTokens
+    output.usage.output = delta.outputTokens
+    output.usage.cacheRead = delta.cacheReadTokens
+    output.usage.cacheWrite = delta.cacheWriteTokens
     output.usage.totalTokens =
-        usage.totalTokens || usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
-    if (usage.reasoningTokens !== undefined) output.usage.reasoning = usage.reasoningTokens
+        delta.inputTokens + delta.outputTokens + delta.cacheReadTokens + delta.cacheWriteTokens
+    if (delta.reasoningTokens !== undefined) output.usage.reasoning = delta.reasoningTokens
     output.usage.cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
 }