mirror of
https://github.com/cline/cline.git
synced 2026-09-24 23:20:16 +08:00
Saoud RizwanandCursor Agent
cde49170db
* fix(desktop): don't let a stale queued send response wedge the composer
A fresh session is still busy while its interactive loop starts, so the
sidecar coerces the first send onto the pending-prompt queue and replies
{queued:true} with a queue snapshot taken at enqueue time. The turn itself
runs via the runtime's queue drain and completes through stream events
(chat_queued_prompt_start -> deltas -> chat_done). On cold/slow sidecars the
RPC response lands only after those events; the webview then applied the
stale snapshot and unconditionally set status back to "running", leaving
the composer on "Agent is working..." forever and resurrecting a phantom
queue entry.
Webview: capture the turn epoch at send dispatch; chat_queued_prompt_start
bumps it, so a mismatch when the queued response arrives means the stream
already advanced the turn lifecycle and the response is ignored. Aborts now
resolve the queued branch to "cancelled" like the direct path.
Sidecar: the queued send response no longer routes its enqueue-time snapshot
through applyPendingPrompts, which overwrote the event-maintained
session.promptsInQueue and rebroadcast the stale list to every webview.
Includes deterministic regression tests for the stale-response orderings
plus temporary [P0DBG] debug instrumentation (region-marked, to be removed
after runtime verification).
* fix(desktop): ignore stale hub 'running' status after turn settles
The sidecar core is hub-attached, so chat_session_status events are
asynchronous projections of the hub's session record. A stale 'running'
can trail the stream's chat_done and flip a settled turn back to busy,
wedging the composer on 'Agent is working…' with nothing left to
reconcile. Track the epoch at which the turn settled and drop 'running'
status events until a new turn bumps the epoch.
* chore: remove stray QA screenshot artifacts from repo root
* chore(desktop): remove P0 debug instrumentation and fault injection
Strips all [P0DBG] logging, the /p0dbg sidecar route, the webview log
mirror + heartbeat, and the P0DBG_STARTUP_BUSY_MS /
P0DBG_DELAY_QUEUED_RESPONSE_MS fault-injection paths used to reproduce
the stuck-composer P0. The two real fixes (stale queued-response epoch
guard + stale-running-after-settle guard in the webview, and the
sidecar's non-clobbering queued-send snapshot) and the regression tests
remain.
* refactor(desktop): replace turn-epoch guards with an explicit turn lifecycle
The stuck-composer fixes left the hook with two hand-rolled epoch refs
(turnEpochRef / turnSettledEpochRef) mutated and compared inline across
eight call sites. Extract the rules into a pure TurnLifecycle module that
is now the only writer of the session status:
- a settled turn cannot be reopened: stale hub 'running' projections and
stale queued-send acknowledgements are dropped by the lifecycle instead
of by inline epoch comparisons
- async work (send RPC responses, queue reconciliation) captures an opaque
token and the lifecycle decides whether the world moved on, instead of
handlers comparing counters
- every status write goes through a named operation (begin, turnStarted,
settle, projectStatus, apply, reset), so the state machine is explicit
and unit-testable in isolation
No behavior change: the 5 wedge regression tests and the full hook suite
pass unchanged, plus 10 new unit tests for the lifecycle module itself.
* Revert "refactor(desktop): replace turn-epoch guards with an explicit turn lifecycle"
This reverts commit c480aaabe8.
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Cline SDK Examples
Learn how to build with the Cline SDK through working examples, ordered from simple to complex.
SDK Skill
If you use a coding agent (Claude Code, Codex, Cline, etc.), install the Cline SDK skill to give your agent context on the SDK's APIs and best practices to help you build with the Cline SDK.
npx skills add cline/sdk-skill
Prompt it to scaffold agents, create custom tools, wire up plugins, configure providers, and more.
Getting started
All examples live in this directory. Each is a standalone project with its own package.json and README. To run any example:
cd apps/examples/<example-name>
bun install
bun run build:sdk
export CLINE_API_KEY="cline_..."
bun dev
Requires Node.js 22+.
Examples
Beginner
| Example | Description | Concepts |
|---|---|---|
| quickstart | Send one prompt, stream the response. ~15 lines of code. | Agent, subscribe, run() |
| cli-agent | Interactive terminal chat with a shell tool. | createTool, multi-turn run()/continue(), streaming |
| cline-core-cli-agent | Interactive terminal chat powered by ClineCore. | ClineCore.create(), cline.start(), cline.send(), built-in tools, streaming |
Intermediate
| Example | Description | Concepts |
|---|---|---|
| code-review-bot | AI code reviewer that reads git diffs and produces structured comments. | Multiple tools, completesRun lifecycle, systemPrompt, zod schemas |
| multi-agent | Web app that fans out to three specialist agents in parallel, streams results via SSE, then synthesizes a unified answer. | Concurrent agents, Promise.all, per-agent subscribe(), SSE streaming, agent composition |
Advanced
| Example | Description | Concepts |
|---|---|---|
| desktop-app | Full Tauri + Next.js desktop app for running and inspecting chat sessions. | Sidecar runtime, websocket transport, session persistence |
| menubar | macOS menu bar app with Tauri. | Native app integration, compact UI |
| vscode | VS Code extension with chat panel. | Extension API, webview, workspace context |
SDK packages
When building your own app, install the public SDK package:
npm add @cline/sdk
@cline/sdk re-exports everything from @cline/core. You only need @cline/agents or @cline/llms if you want lower-level control over the agent runtime or model gateway directly.
Learn more
- SDK package docs
- Architecture guide
- Plugin examples - extend the Cline SDK and CLI with custom tools and event hooks
- Hook examples - lifecycle hooks for logging, blocking, and injection for Cline SDK and CLI