Allow user feedback messages in the VS Code extension to be edited inline and regenerated from that point. Adds a TaskService RPC, truncates persisted SDK history before the selected visible user prompt, and starts a new session with the edited prompt. Also ensures the regenerated active task appears in extension history while SDK history catches up.
cf25cd66a ("make extension plan mode more similar to CLI") removed the
file-level ACT_MODE_CONTINUATION_PROMPT constant and stopped passing the
autoContinue / continuationPrompt options when rebuilding a session for
a mode change, but left the corresponding block inside
rebuildSessionForMode in place. The block still references the deleted
constant, so tsc fails on the SDK migration branch with TS2304: Cannot
find name "ACT_MODE_CONTINUATION_PROMPT".
No caller passes options to rebuildSessionForMode anymore, so the block
is dead. Drop the block and narrow the signature to take only newMode.
Existing tests already invoke rebuildSessionForMode(<mode>) with no
second argument and assert that fireAndForgetSend is not called on a
mode rebuild, so they keep passing.
* fix(terminal): surface standalone terminal spawn diagnostics
Add Logger calls at every chokepoint of the standalone terminal pipeline
so the (currently silent) failure modes around JetBrains-hosted
cline-core become debuggable from cline-core-service.log.
Lines added, all using the existing Logger facility (no new
dependencies, no behavioral changes):
* StandaloneTerminalProcess.run() now logs:
- `[StandaloneTerminalProcess] run() entered: shell=… cwd=… args=…`
on entry, before the try block;
- `[StandaloneTerminalProcess] spawned pid=… for shell=…` right
after child_process.spawn returns;
- `[StandaloneTerminalProcess] close: code=… signal=… fullOutputLen=…`
inside the `close` handler (the `fullOutputLen` reveals when the
child exits 0 with empty pipes — the symptom in issue #10948);
- `[StandaloneTerminalProcess] child error: …` in the `error`
handler;
- `[StandaloneTerminalProcess] spawn threw synchronously: …` in
the outer catch.
* StandaloneTerminalManager.runCommand() now logs entry
(`[StandaloneTerminalManager] runCommand terminalId=…: <cmd>`) and
attaches a `.catch` to the previously fire-and-forget
`process.run(…)` Promise so an unhandled rejection surfaces as
`[StandaloneTerminalManager] process.run rejected for terminal …`
instead of disappearing.
* CommandExecutor.execute() extends the existing "Executing command
in … terminal" line with `mode=<terminalExecutionMode>` and
`managerCtor=<manager.constructor.name>`, so it's possible to
confirm whether the `vscodeTerminal` path is in fact backed by a
`StandaloneTerminalManager` on JetBrains (it is — see
notes/issue-10948-…md).
* CommandOrchestrator.orchestrateCommandExecution() logs the
`process.once("completed")` event with `exitCode`/`signal`/
`terminalType`, the "resolved completed" return branch with the
line/byte totals, and emits a `WARN` on the silent "still running"
fall-through. The last one matters because the original repro
reported "Command executed successfully (exit code 0)" with empty
output — the WARN makes that branch loud the next time it fires.
These logs are what made the two distinct bugs in #10948 visible
(see the 2026-05-28 update in
notes/issue-10948-terminal-output-investigation-2026-05-27.md). They
stay in to keep the next regression debuggable.
Refs: cline/cline#10948
* fix(terminal): keep Windows child stdio attached to parent pipes
The non-cmd Windows branch in StandaloneTerminalProcess.run() spawned
the shell (powershell.exe in practice) with `detached: true` and no
`windowsHide`. When cline-core is launched by the JetBrains plugin it
has no console of its own, so Windows CreateProcess allocates a NEW
console for the detached child and the child's stdio routes to that
new console instead of the pipe handles the parent created. From the
parent's point of view the pipes immediately EOF, `close` fires with
`code=0`, and `fullOutput` is 0 bytes — exactly the symptom reported
in cline/cline#10948 ("Command executed successfully (exit code 0)"
with no output and no filesystem effect).
This bug applies to every command the agent runs through the
standalone terminal path on Windows, not just the
double-wrapped-PowerShell cases (verified by re-running a clean
`dir <file>` after the diagnostics from the previous commit landed:
`run() entered` and `spawned pid=<num>` both fired, then `close: code=0
fullOutputLen=0`).
Fix:
* `detached: process.platform !== "win32"` — keep the existing
POSIX behavior (a separate process group helps `tree-kill`), but
drop it on Windows where `tree-kill` walks the PID tree with
`taskkill /T` and doesn't need a process group.
* `windowsHide: true` — matches every other `child_process.spawn`
call site in cline-core (git, MCP, hooks, browser) and flips on
`CREATE_NO_WINDOW`, keeping the child attached to our pipes
without popping a console window.
Verified on Windows 11 + IntelliJ IDEA 2026.1 + Cline plugin
1.1.59-Internal: `dir <path>`-style probes now produce a non-zero
`fullOutputLen` in the close log, and the captured output bytes
match what would have been visible interactively. PowerShell
double-wrapping (the other half of #10948) is handled in a
follow-up commit.
Refs: cline/cline#10948
* fix(terminal): harden PowerShell command wrapping for standalone shell
`StandaloneTerminalProcess.getShellArgs()` blindly wrapped every
PowerShell command as `["-Command", command]`. That has two
end-user-visible failure modes on Windows, both observed in
cline/cline#10948:
1. The agent's `run_commands` tool call sometimes arrives already
prefixed with `powershell -Command "…"`. We then spawned
`powershell.exe -Command 'powershell -Command "…"'`, and the
outer shell shredded the inner single/double-quote pairs while
re-parsing its `-Command` argument. The inner pwsh saw
quote-empty `Test-Path` calls, fell through to the `else` branch
and reported "File not found" — to ITS stdout, which the outer
inherited but the file deletion the LLM intended never ran.
2. The user's `$PROFILE` script ran on every spawn, leaking
non-deterministic noise (e.g.
`%windir%\System32\REG.exe : The module '%windir%' could not be
loaded`) into the captured output and confusing the agent.
3. Bonus: the POSIX branch used `["-l", "-c", command]`. The `-l`
re-sources login files on every command, which is slow and lets
greeter scripts leak into output.
4. Bonus: the cmd branch used `["/c", command]`. `/d` skips
AutoRun, `/s` makes the embedded-quote handling deterministic.
Fix:
* PowerShell branch returns
`["-NoProfile", "-NonInteractive", "-Command", unwrap(command)]`.
`-NoProfile` suppresses (1) the spurious profile noise that
contaminated the captured output, and `-NonInteractive` ensures
the child doesn't deadlock waiting on a prompt no one will answer.
* `unwrapPowerShell(command)` strips a leading
`powershell|pwsh [.exe] -Command|-c "…"` (or single-quoted)
wrapper that the LLM sometimes emits, fixing the double-pass
argument-quoting destruction. If the command does not match the
exact wrapper shape it is returned verbatim — worst case is "no
change", preserving pre-fix behavior.
* cmd branch returns `["/d", "/s", "/c", command]`, matching the
canonical helper in cline/sdk/packages/shared/src/parse/shell.ts.
* POSIX branch returns `["-c", command]`, dropping the unhelpful
`-l`. Also matches the SDK helper.
Verified on Windows 11 + IntelliJ IDEA 2026.1 + Cline plugin
1.1.59-Internal in combination with the previous "keep Windows
child stdio attached" commit: `Remove-Item CHANGELOG.md` now
deletes the file, the agent's verification `Get-ChildItem CHANGELOG*`
returns nothing, and the profile-load REG.exe error no longer leaks
into captured output.
Refs: cline/cline#10948
* refactor(terminal): tone down standalone terminal diagnostics
The diagnostics added while chasing #10948 were intentionally loud so the
two bugs were visible. Now that the fixes are in, reduce them to a normal
operating posture:
* Demote fine-grained traces to `debug`: the per-spawn `spawning …` and
`spawned pid=…` lines, `StandaloneTerminalManager.runCommand`, and the
orchestrator's `resolved completed` summary.
* Drop the orchestrator's `completed event` line entirely — the
`resolved completed` debug line already carries exit code, signal, and
line/byte totals.
* Stop echoing the full command in the manager line and stop echoing the
args vector in the spawn line. The command is still logged once at
`info` by CommandExecutor (unchanged, pre-existing), so we go back from
three command echoes to one. Commands routinely embed secrets
(Authorization headers, tokens), so fewer copies on disk is better.
Kept loud on purpose:
* `info` on `close: code=… fullOutputLen=…` — the single line that proves
the Windows stdio-capture fix and the most useful per-command signal.
* `warn` on `resolved without completion event` — the silent-success
canary for the #10948 failure mode.
* `error` on child error / synchronous spawn failure / unhandled
process.run rejection.
Refs: cline/cline#10948
* fix(terminal): tighten PowerShell unwrap regex and extract to a pure module
Two review follow-ups for the #10948 shell-arg handling:
1. The wrapper-strip regex used a greedy `([\s\S]*)` body, so a command
like `powershell -Command "foo" "bar"` would match with the body
captured as `foo" "bar`, silently rewriting a command into something
different. Replace the body with a tempered match `((?:(?!\1).)*)`
that cannot contain the captured delimiter, so anything other than
exactly one quoted token is returned verbatim. Worst case is now
"no change" rather than an incorrect rewrite. The legitimate
double-wrapped case from #10948 (outer ", inner ') still unwraps.
2. `getShellArgs` and `unwrapPowerShell` were private methods on
StandaloneTerminalProcess, untestable without spawning a process.
Move them to a pure `shellArgs.ts` module. `getShellArgs` now takes
an injectable `platform` (defaulting to `process.platform`) purely so
the win32-vs-posix branch is testable; behavior is unchanged. This
also gives us a single local seam to later consolidate onto the
canonical `@cline/shared` helper (tracked as a follow-up).
No behavioral change beyond the regex correctness fix.
Refs: cline/cline#10948
* test(terminal): cover shell-arg construction and PowerShell unwrap
Add mocha unit tests (matching the repo's node:assert/strict + __tests__/
convention so the existing mocharc spec globs pick them up) for the newly
extracted shellArgs module:
* unwrapPowerShell: double-quote and single-quote wrappers, powershell.exe
-c form, the #10948 nested-quote repro (inner quotes preserved),
non-wrapped passthrough, and the two regressions the tightened regex
must reject (`… "foo" "bar"` and a command that merely mentions
powershell mid-string).
* getShellArgs: PowerShell -> -NoProfile -NonInteractive -Command (with
unwrap), cmd -> /d /s /c, POSIX -> -c. The injectable platform arg lets
these run on any CI host.
This closes the M1 review finding (the regex was the riskiest line in the
change and had zero coverage) and exercises the cmd/POSIX flag changes
called out in M2.
Refs: cline/cline#10948
* docs(terminal): drop issue references and clarify windowsHide comment
Remove inline issue-number references from source comments and a test
name; that context belongs in the commit history, not the code. Also add
a one-line note that windowsHide is a no-op on non-Windows platforms,
since it is set unconditionally while the surrounding comment is
Windows-specific.
No behavior change.
* refactor(terminal): drop warn on the non-completion return path
The orchestrator's final fall-through return is a normal, expected path:
the process resolved via `continue` without a `completed` event (e.g. a
terminal mode without shell integration, or proceed-while-running flows).
Logging it at `warn` cries wolf on healthy runs, so remove it. The
genuine failure mode this was meant to catch surfaces through the
`close`/error logs and the result string itself.
* fix(terminal): address review feedback on standalone spawn paths
Three follow-ups from code review:
* StandaloneTerminalManager.runCommand: the unawaited process.run()
.catch only logged. run() emits "error" for failures it catches, but a
rejection escaping without an "error" event would leave the outer
promise (resolved via the "continue"/"error" events) pending forever,
stalling the caller. Re-emit "error" from the catch so both paths stay
consistent. Cannot trigger today (no await outside run()'s try/catch)
but the guard exists precisely for future rejections.
* shellArgs POSIX branch: document that dropping the login flag (`-l`)
is intentional and relies on the child inheriting the parent's PATH via
process.env, with a note that a GUI-launched IDE without a login PATH
is the edge case to watch.
* StandaloneTerminalProcess cmd.exe branch: add windowsHide:true. The
console-allocation/window-pop problem is not exclusive to the non-cmd
branch; a console-less parent could pop a window for cmd.exe too.
No-op on non-Windows.
compile-tests runs 'tsc -p tsconfig.test.json' (module: commonjs) over all
src/**/*.test.ts for the VS Code integration runner. The new src/sdk vitest
suites use top-level 'await import(...)' (after vi.mock), which is invalid
under CommonJS and fails with TS1378. The integration runner never runs
src/sdk anyway (.vscode-test.mjs only globs core/test/utils/shared/
integrations/hosts/services); these run via 'npm run test:vitest'. Exclude
src/sdk/**/*.test.ts from the integration compile.
The rebase dropped '--config-path ./biome.jsonc' from the lint/format/
postprotos scripts and removed the '!!**/.vscode-test' ignore from
biome.jsonc. Without the explicit config path, biome auto-discovered the
root biome.json instead of apps/vscode/biome.jsonc, applying the wrong
rule severities (449 errors at error level for rules that are off/info in
the nested config). Restore both to match origin/main and apply the
pending buf format fix to models.proto.
The command row reflects an executing state while a command runs. The
message translator includes the command-output marker on the running
command row so the webview renders it as executing; the row is finalized
with output and a completed flag when the command ends.
Also remove the unused onChange parameter from the foreground run_commands
path: the SDK runtime does not pass it, so it had no effect. Foreground
command output is surfaced to the chat at completion, not incrementally.
Fixes CLINE-2298 and CLINE-2162
The footer Approve/Reject buttons stayed disabled when a second consecutive
approval ask arrived. The button configs are shared singletons (e.g.
BUTTON_CONFIGS.tool_approve), so two identical asks return the same object
reference and the effect that reset the processing latch never re-ran.
Key the processing latch on the ask identity (anchored turn timestamp plus the
button labels) rather than the config object reference, using a ref-based latch
so each new ask re-enables the buttons. Adds a regression test.
Test plan:
1. Ask the agent to generate two requests to ls /tmp at once
2. Approve (or reject) the first request
3. Check that the buttons for the second request are enabled
Run Cline inference through the VS Code Language Model API (vscode.lm), enabling
models contributed by any extension that registers a language model chat
provider with VS Code. GitHub Copilot is the most common such vendor, but the
implementation is vendor-agnostic — it selects models via
vscode.lm.selectChatModels and has no Copilot-specific logic.
- VsCodeLmHandler implements the Cline SDK ApiHandler and is registered with the
SDK handler registry; the model selector travels as a vendor/family[/version/id]
string in modelId and is parsed back here. Selector segments are
percent-encoded so values containing slashes round-trip intact.
- Native tool calling: tool definitions are passed to sendRequest and tool calls
are surfaced as tool-call chunks; tool results round-trip as
LanguageModelToolResultPart, with structured tool output serialized to text and
a trailing user message appended when a turn ends on tool results so models can
read the output.
- Gated to VS Code: registration is conditioned on the vscode.lm API being
present, and the provider is hidden in the UI on hosts without it (JetBrains).
Depends on @cline/{shared,llms,agents,core} 0.0.42-nightly.1780514867, the first
published SDK build with the custom-registered-handler routing this provider
needs.
Both packages are imported directly from source but were never declared in
apps/vscode/package.json, so they only resolved transitively. On a clean
install this broke:
- @grpc/proto-loader — imported by scripts/proto-utils.mjs,
src/standalone/utils.ts and src/standalone/hostbridge-client.ts; its absence
made `npm run protos` (and therefore the whole build) fail on a fresh checkout.
- @opentelemetry/api-logs — imported by the OpenTelemetry telemetry providers;
its absence produced TS2307 "Cannot find module" errors under tsc.
Versions are pinned to align with the existing dependency families already
declared in this package (@grpc/grpc-js ^1.9.x → proto-loader ^0.7.13;
the @opentelemetry/* 0.56.x line → api-logs ^0.56.0). The npm and bun
lockfiles are updated accordingly (the api-logs change also dedupes several
previously-nested copies to a single hoisted entry).
* fix(vscode): wire auto compact into SDK sessions
* test(sdk): cover both directions of useAutoCondense task override
The previous test left the global mock at `true` for both calls, so the
`taskSettings: true` branch would have passed even if task settings were
ignored entirely. Make the mock read a mutable flag and flip it to `false`
before the second call so both override directions — task `false` over
global `true`, and task `true` over global `false` — are genuinely
exercised.
* Fix mock return type in cline-session-factory test
The getGlobalSettingsKey mock inferred a literal 'false | undefined' return type, so later mockImplementation overrides returning 'true' failed type checking (TS2345). Annotate the implementation as 'boolean | undefined' to widen the inferred mock signature.
---------
Co-authored-by: Mikołaj Kondratek <19799111+mkondratek@users.noreply.github.com>
The MCP SDK calls redirectToAuthorization() on every connection attempt,
and a single server can be reconnected repeatedly (settings watcher,
reconnect handler, restart). Regenerating the OAuth `state` on each call
replaced the state stored for a flow whose authorization URL the user may
already have open, so the completed callback failed validation with
"Invalid OAuth state".
redirectToAuthorization() now keeps an in-progress, still-fresh flow
instead of starting a new one (freshness measured from when the flow
started, never extended, so a stale flow always expires). The PKCE
verifier is pinned to the kept flow so token exchange still validates.
Also add local dev/test tooling:
- src/dev/mcp-oauth-test-server: a zero-dependency OAuth AS + MCP
StreamableHTTP server for exercising the flow locally, with
fault-injection flags (--auto-deny, --slow-authorize, --code-ttl).
- src/extension.ts: a debug-only globalThis.__clineHandleUri hook (gated
on CLINE_CAPTURE_BROWSER) so the debug harness can deliver simulated
vscode:// OAuth callbacks; documented in the harness README.
Bedrock requests built by the SDK adapter dropped the AWS region and
authentication mode, so a pasted Bedrock API key (awsBedrockApiKey +
awsAuthentication "apikey") was silently ignored and requests fell
through to the SigV4 credential chain with no region.
Two bugs, both verified end-to-end against a live Bedrock endpoint via
the debug harness:
1. The SDK ProviderConfig was built with only providerId/modelId/apiKey/
baseUrl. New bedrock-config.ts maps the legacy ApiConfiguration onto
the SDK's structured region + aws block (including the webview's
"credentials" radio -> SDK "iam"), wired into both inference paths
(buildSdkProviderConfig for utility calls, buildSessionConfig for the
main task loop).
2. The main chat path's gateway config is built by core from the
providers.json `stored` entry, which the session's providerConfig does
not override. A stale Bedrock entry (e.g. a legacy migration with
region us-east-1 + SigV4 keys) silently won, sending requests to the
wrong region (403). buildSessionConfig now persists the
StateManager-derived Bedrock settings to providers.json so `stored` is
authoritative. The bearer apiKey is only persisted for api-key auth to
keep stored clean for profile/iam.
Also documents the ELECTRON_RUN_AS_NODE debug-harness gotcha in
.clinerules/general.md.
fix sesion usubscriptions
fix soft-lock on auth fail retry
refactor(vscode): source provider model catalogs from @cline/llms SDK
(ENG-2116)
Migrates the vscode extension off its hand-curated static model catalogs
in apps/vscode/src/shared/api.ts and on to the @cline/llms SDK as the
single source of truth for provider/model metadata, end-to-end across
the extension host and the webview.
Net impact on the static catalog file:
apps/vscode/src/shared/api.ts: 5092 -> 468 lines (~90% gone).
What changed at each layer
--------------------------
SDK / catalog plumbing (apps/vscode/src/sdk/model-catalog/):
- New `ProviderCatalog.peekModels(providerId)` synchronous cache read.
- `resolveModelInfo` rewritten: committed selection -> catalog peek
-> await catalog.resolveModels on cache miss. No race with a
background warmer; if the catalog truly has nothing, returns
source: "unknown" and the webview renders a neutral loading state.
- `applyHostModelInfoOverrides` is the canonical seam for the few
fields the SDK does not yet carry. Today it carries only the Vertex
`supportsGlobalEndpoint` allowlist (vertex-global-endpoint.ts, with
a TODO to upstream into the SDK).
- `ProviderListing` extended with SDK metadata (`is_popular`,
`popular_rank`, `usage_cost_display`, `capabilities[]`) and plumbed
through proto + conversion.
Extension-host handlers (apps/vscode/src/core/api/providers/):
- New shared helper `apps/vscode/src/shared/sdk-handler-models.ts`:
`getProviderModelFromSdk(providerId, requestedModelId,
committedInfo?)`
returns `{ id, info }` from `getProviderCollectionSync` with
Vertex global-endpoint overrides applied.
- 27 handlers converted to a one-liner `getModel()` through that
helper. Per-handler nuances preserved:
* Anthropic: strips `:fast` and `:1m` host-side suffixes before
SDK lookup; carries them back on the returned id so the
per-request betas still flip.
* Bedrock: keeps the custom Application Inference Profile ARN
branch; base-model info from the SDK.
* Cerebras: keeps the `qwen-3-coder-480b-free` ->
`qwen-3-coder-480b`
paid alias.
* Qwen / ZAi: SDK has a single catalog each; handlers keep the
regional base-URL switch but no longer fork the catalog.
* Wandb: keeps the "unknown id falls through to safe defaults"
escape hatch via `MODEL_COLLECTIONS_BY_PROVIDER_ID`.
Refresh-models background tasks:
- `refreshBasetenModels`, `refreshGroqModels`,
`refreshHuggingFaceModels`
source their offline-fallback catalog from the SDK via
`getProviderCollectionSync` + `adaptSdkModelInfo`. Live fetch path
unchanged; only the seeding/fallback data changed.
Webview (apps/vscode/webview-ui/):
- `useNormalizedApiConfiguration` always routes through gRPC
`resolveModelInfo`. Removed the `isMigratedSdkProvider` /
`MIGRATED_SDK_PROVIDER_IDS` feature flag and the legacy
`normalizeApiConfiguration` switch entirely.
- New `useStaticProviderSelection` hook for the 22 settings
components whose catalog is now SDK-driven, and
`useDynamicProviderSelection` for the 12 dynamic-list pickers
(openrouter, cline, openai-compatible, ollama, lmstudio, requesty,
litellm, hicap, groq, baseten, huggingface, vercel-ai-gateway,
aihubmix, oca, huawei-cloud-maas, dify, fireworks, together,
vscode-lm) so all of them stop calling the legacy switch.
- `ModelInfoView` reads its `isGemini` check via
`useProviderModels("gemini")` instead of importing `geminiModels`.
- `App.stories.tsx` ships a small inline fixture instead of
importing `bedrockModels`.
- `ExtensionStateContext` no longer seeds `groqModelsState` /
`basetenModelsState` from the deleted catalog; the slices start
empty and the SDK-curated catalog is layered in by the pickers at
render time.
Misc:
- `src/utils/model-utils.ts`: `isAnthropicModelId` consults
`MODEL_COLLECTIONS_BY_PROVIDER_ID["anthropic"]` instead of the
deleted `anthropicModels` map.
- `src/shared/storage/provider-keys.ts`: `getProviderDefaultModelId`
no longer hard-codes 24 per-provider defaults. The function now
consults the SDK catalog and only keeps an override map for
providers whose default is intentionally not the SDK default
(openrouter-shared dynamic providers and local-only providers).
- `src/shared/openai-codex-models.ts`: relative path for
`shape-adapter` import so both the extension and webview build
contexts resolve it identically.
Tests retargeted to assert SDK behavior, not static-map shapes
--------------------------------------------------------------
- claude-code, anthropic, bedrock, vertex, wandb, provider-keys
test suites had assertions tied to deleted shapes. Rewrote them
to either assert through the SDK catalog
(anthropic compares against
`adaptSdkModelInfo(sdkCollection.models[id])`,
wandb uses the SDK-declared default, etc.) or focus on the
host-side semantics (bedrock's "global endpoint" block now tests
`vertexModelSupportsGlobalEndpoint` directly).
- claude-code test trimmed its 8 `[1m]`/version-pin variants down
to three SDK-shaped cases. The 8 deleted assertions exercised
extension-only model-id derivations that the SDK does not carry;
matching the CLI's behavior was the explicit goal.
- resolveModelInfo test rewritten around the new peek -> await
-> unknown contract.
- proto-lint: added missing `go_package` option to
`proto/cline/remote_config.proto`.
Verification (npm scripts under apps/vscode/):
- npm run protos OK
- npm run check-types OK (apps/vscode + apps/vscode/webview-ui)
- npm run lint OK (biome + proto-lint)
- npm run build:webview OK (tsc -b && vite build)
- node esbuild.mjs OK (dist/extension.js produced)
- Runtime smoke test: 27/27 provider collections resolve from the
SDK with correct model counts, defaults, and usage-cost-display
flags. openai-codex returns cost=hide as expected; every other
provider returns cost=show.
fix(vscode): preserve provider model selection fields
chore(vscode): clean up SDK migration branch (comments, dead code,
scree, tests)
- Remove porting scree: docs/sdk-model-catalog/* planning docs,
TODO-resume-session.md, and stale doc references in code/comments.
- Rewrite before/after narrative comments in the 'eternal now' style;
drop transient 'Step N'/'Phase N' labels.
- Remove leftover [HistoryPerf] diagnostic logging and a dead try/catch
rethrow; minor readability/naming.
- Restore .clinerules/network.md (still relevant) and update
sdk-migration.md to drop dangling references.
- Fix latent circular-init TDZ in openai-codex-models (lazy catalog
build).
- toggleRemoteConfigSetting no longer returns a never-resolving promise.
- Move vitest config into apps/vscode and rename script test:sdk ->
test:vitest; wire it into CI.
- Repair/reimplement the SDK-adapter vitest suites (auth-service,
provider-migration, sdk-task-history) to match current behavior; all 432
tests pass.
fix(vscode): support OpenAI Compatible provider on the SDK adapter
Selecting the OpenAI Compatible provider failed with 'Unknown provider
"openai"', and manually entered model ids were displayed as the catalog
default (gpt-4o).
- Map the extension's 'openai' provider id to the SDK's
'openai-compatible' built-in at the SDK boundary (toSdkProviderId), and
convert before handing the provider id to core when building a session
config.
- Treat openai-compatible as a custom-model-id provider so model
resolution honors a user-entered model id instead of coercing it to the
catalog default. Adds providerAllowsCustomModelIds() as the shared
signal.
- Bump @cline/core, @cline/llms, @cline/shared, @cline/agents to ^0.0.42
(which registers the openai-compatible built-in) and dedupe the
dependency tree.
- Carry the tool name on reconstructed Anthropic-format tool_result
blocks to satisfy the SDK's ToolResultContent contract.
- Update tests for the refreshed SDK model catalog (Gemini default).
fix(vscode): fix webview provider-model tests and a Windows path test
The nightly publish runs the full webview-ui suite and the Windows
extension suite, which surfaced failures the extension-only run does
not.
- Harden useProviderModels against a missing providerModelsByProvider
map so a partially-mocked ExtensionStateContext no longer crashes the
hook.
- Update the SapAiCoreModelPicker and APIOptions specs to provide the
provider model-list context the components now read from the SDK
catalog, and seed the model ids each test asserts. Removes the now-dead
@shared/api sapAiCoreModels mock.
- Compare resolveDataDir() against path.join() instead of a hardcoded
POSIX path so the CLINE_DIR fallback test passes on Windows.
fix(vscode): load real @cline/llms in unit-test harness; fix/trim
provider tests
The mocha unit-test harness stubbed @cline/llms with an empty catalog,
so the SDK-migrated provider handlers (which read the real catalog)
failed ~51 tests under the nightly suite.
- src/test/requires.ts now loads the real @cline/llms by resolving its
package directory and requiring the ESM entry by absolute path (Node 22
require(esm)), bypassing the package's import-only exports map. This
restores real catalog data to provider unit tests.
- vertexModelSupportsGlobalEndpoint: also match legacy ':'
context-window/speed suffixes (e.g. claude-opus-4-7:1m), not just '@'
snapshot variants.
- refreshClineModels: derive prompt-cache support from reported
input_cache_read pricing for any provider, not just openai/google
prefixes.
- Delete the failing tests for the classic provider handlers (bedrock
cross-region/native-tool-calling, gemini metadata, cline/openrouter qwen
cache, wandb unknown-model). These handlers are only reached via
buildApiHandler (explain-changes + commit-message generation) and the
provider/catalog domain is owned and tested by the SDK; they will be
removed when buildApiHandler is retired.
refactor: remove legacy Cline model overrides, wire reasoning effort
through SDK
- Delete refreshClineModels.ts, refreshClineModelsRpc.ts, and test
- Remove refreshClineModelsRpc proto RPC
- Remove clineModels state from ExtensionStateContext, StateManager
cache, disk
- ClineModelPicker and useOnboardingModels use SDK catalog directly
- Replace ThinkingBudgetSlider with ReasoningEffortSelector for Cline
provider
- Use supportsReasoning from SDK catalog instead of hardcoded model
names
- Add ProviderReasoningPatch to proto and ProviderConfigPatch contract
- Wire reasoning effort changes through writeProviderConfig to SDK
ProviderSettingsManager
- Remove hardcoded Claude switch in openrouter-stream.ts
- Add supportsReasoning to supportsReasoningEffort check in
openrouter-stream
refactor(vscode): route buildApiHandler through the SDK; remove
OpenRouter handler
Replace the legacy per-provider buildApiHandler factory with an
SDK-backed
handler (apps/vscode/src/sdk/sdk-api-handler.ts) built via @cline/llms
createHandler(). The two standalone callers (commit-message generation
and
explain-changes) now import buildApiHandler directly from the SDK
module;
@core/api stays types-only (re-exporting SDK types) so it can keep being
imported widely without pulling the SDK runtime graph into activation.
Also:
- Delete the now-dead OpenRouterHandler and its test
(createOpenRouterStream
stays; it is still used by ClineHandler).
- buildSdkProviderConfig never sends both reasoning.effort and
reasoning.max_tokens (some providers reject it), and supports
disableReasoning for fast one-shot utility calls; commit-message and
explain-changes opt in.
- commit-message generation surfaces the real SDK stream error instead
of a
generic "empty API response".
- getGitDiff: run git diff --staged even before the first commit; only
gate
the git diff HEAD fallback on having commits (fixes "no changes" for
the
initial commit of a new repo).
refactor(vscode): delete legacy API provider handlers and dead
transforms
Now that buildApiHandler routes through the @cline/llms SDK, the legacy
per-provider handler classes and their supporting code are unused.
Remove them:
- apps/vscode/src/core/api/providers/** (all 40+ handler classes, types,
tests)
- apps/vscode/src/core/api/transform/** except stream.ts (format/stream/
tool-call helpers only the handlers used)
- apps/vscode/src/core/api/utils/** (messages/responses API support)
- apps/vscode/src/core/api/retry.ts (+ test)
- apps/vscode/src/shared/sdk-handler-models.ts (getProviderModelFromSdk;
only the deleted handlers' getModel() used it)
core/api now contains just index.ts (types + SDK re-exports),
transform/stream.ts
(ApiStream types still referenced by the local ApiHandler interface),
and
adapters/.
Supporting changes to keep everything compiling/working:
- context-window-utils: drop the dead `api instanceof OpenAiHandler`
DeepSeek
branch (handlers are SDK GatewayApiHandlers now); the 64k switch case
already
handles DeepSeek context sizing.
- Relocate fetchLiteLlmModelsInfo from the deleted litellm handler into
core/controller/models/fetchLiteLlmModels.ts (used by
refreshLiteLlmModels).
- Move the `declare module "vscode"` Language Model API augmentation
(previously
carried by the vscode-lm handler) into
src/types/vscode-language-model.d.ts so
live consumers (getVsCodeLmModels, vsCodeSelectorUtils) keep their
types.
- Move the @google/genai test mock out of the deleted providers dir to
src/test/fixtures/google-genai-mock.ts and repoint test-setup.js.
refactor(vscode): delete dead classic system-prompt + slash-command code
The classic system-prompt builder (core/prompts/system-prompt/**), the
deep-planning prompt variants, core/prompts/commands.ts, and the
core/slash-commands handler are no longer reachable from any shipped
entry
point (extension host, standalone host, or webview) after the SDK
migration:
the SDK provides prompt construction (buildClineSystemPrompt) and
slash-command
handling. Removed them and their orphaned tests.
Kept core/prompts/responses.ts (still live) and its tests.
Dead-code reachability was computed with scripts/find-dead-src.mjs
(esbuild
metafile reachability from src/extension.ts +
src/standalone/cline-core.ts,
plus webview src/shared references), then gated on tsc --noEmit +
vitest.
refactor(vscode): delete dead tree-sitter code-definition service
src/services/tree-sitter/** (language parsers + queries for the classic
list_code_definition_names path) is unreachable from any shipped entry
point
after the SDK migration. Verified via scripts/find-dead-src.mjs (esbuild
reachability from extension + standalone entries, plus webview shared
refs) and
an importer cross-check (no live value or type importers), gated on
tsc --noEmit + vitest (436 passing).
refactor(vscode): delete more dead classic code (hooks, permissions,
claude-code, misc)
Removes additional source files unreachable from any shipped entry point
(extension host, standalone host, webview) after the SDK migration,
verified
via esbuild reachability + a per-file importer cross-check that excludes
any
file still referenced by a live non-test survivor or generated/test
glue, then
gated on tsc --noEmit + vitest (436 passing):
- services/ripgrep, integrations/notifications, utils/string,
utils/tabFiltering
- core/assistant-message/parse-assistant-message
- core/hooks: hook-model-context, notification-hook,
precompact-executor,
PreToolUseHookCancellationError
- core/permissions/CommandPermissionController
- core/workspace/detection
- integrations/claude-code: run, message-filter
- integrations/editor: FileEditProvider, detect-omission
- integrations/misc: extract-file-content, extract-images
Dropped the now-dead re-exports from core/assistant-message/index.ts and
core/permissions/index.ts (those barrels stay; they still export live
types
used by generated host glue).
chore(vscode): add scripts/find-dead-src.mjs dead-code oracle
Computes src files unreachable from the shipped entry points (extension
host + standalone host used by JetBrains/CLI) plus webview shared refs,
using esbuild metafile reachability. Used to drive the
post-SDK-migration dead-code deletions; keep for future pruning. Note:
results still need a tsc-gated importer cross-check because esbuild
drops import-type-only edges.
fix(vscode): drop dead barrel re-exports of deleted files
The previous deletion commit (2c9bd62) removed
core/assistant-message/parse-assistant-message.ts and
core/permissions/CommandPermissionController.ts, but the corresponding
barrel
edits (removing their re-exports from index.ts) were dropped by
lint-staged's
stash and never committed, leaving HEAD referencing deleted modules.
Remove the
dead re-exports so the barrels only export live members.
chore(vscode): drop npm deps only used by deleted provider handlers
Remove dependencies that became unused after the legacy API provider
handlers
and tree-sitter service were deleted (no remaining imports in src,
webview, or
build config):
@anthropic-ai/vertex-sdk, @aws-sdk/client-bedrock-runtime,
@aws-sdk/credential-providers, @azure/identity,
@cerebras/cerebras_cloud_sdk, @google-cloud/vertexai,
@mistralai/mistralai,
@sap-ai-sdk/ai-api, @sap-ai-sdk/orchestration,
@sap-cloud-sdk/connectivity,
ollama, tree-sitter-wasms, web-tree-sitter
Also remove the now-dead copyWasmFiles esbuild plugin (it only copied
tree-sitter WASM files for the deleted code-definition service). Kept
openai,
@anthropic-ai/sdk, @google/genai, and aws4fetch — still imported by live
code.
Verified: extension + standalone esbuild builds succeed, tsc --noEmit
clean,
vitest 436 passing.
refactor(vscode): remove dead cost utils and createOpenAIClient
- Delete src/utils/cost.ts (+ test):
calculateApiCostAnthropic/OpenAI/Qwen had
no consumers left after the provider handlers were removed (only the
test
referenced them).
- Remove createOpenAIClient from src/shared/net.ts (no remaining
callers) and
its now-unused openai + EnvUtils imports. The proxy-aware fetch and
getAxiosSettings exports remain.
tsc --noEmit clean, vitest 436 passing.
refactor(vscode): delete genuinely-unused telemetry/auth helpers
- services/telemetry/events/EventHandlerBase.ts: abstract base for
telemetry
event handlers whose concrete subclasses were removed with the classic
task
code; no remaining references (it was the only file left in events/).
- services/auth/AuthServiceMock.ts: test mock with no importers after
the
associated test was deleted.
Note: the rest of services/* (TelemetryService, McpHub,
FeatureFlagsService,
ErrorService and their IFoo interfaces) IS live — the interfaces only
looked
unreachable to the esbuild oracle because they're consumed via type-only
imports (erased at emit). Verified via importer cross-check; tsc +
vitest green.
refactor(vscode): remove dead sapAiCoreModelDescription const
Unused leftover from the deleted SAP AI Core provider handler (found via
biome noUnusedVariables). tsc + vitest green.
refactor(vscode): delegate Cline recommended-models fetch to the SDK;
TODO others
refreshClineRecommendedModels now delegates the HTTP fetch + response
normalization + offline fallback to the SDK's
fetchClineRecommendedModels
(@cline/core), removing ~80 lines of duplicated logic. The extension
wrapper
keeps its distinct behavior: the CLINE_RECOMMENDED_MODELS_UPSTREAM
feature-flag
gate, the in-memory TTL cache, and in-flight dedup. The proxy-aware
fetch
(@/shared/net) and the configured apiBaseUrl are passed through to
preserve
network/proxy behavior. The SDK's offline fallback list is identical to
CLINE_RECOMMENDED_MODELS_FALLBACK, so offline behavior is unchanged.
Because the module now imports the ESM-only @cline/core, its unit test
moves
from mocha to vitest (joining the other SDK-touching models tests):
added to
vitest include + mocha ignore, and fetchClineRecommendedModels added to
the
vitest @cline/core stub (and the mocha/integration @cline/core mocks for
completeness). Rewrote the test vitest-native, asserting flag-gate,
delegation,
and flag re-check.
Also:
- Add TODO(sdk-consolidation) notes to the remaining bespoke
live-model-refresh
handlers (Groq, Baseten, Hicap, HuggingFace, Vercel AI Gateway,
OpenRouter)
documenting the path to share them with the CLI via the SDK (register
modelsSourceUrl) and then delete the extension-only handlers + RPCs.
These
are NOT migrated yet because the SDK does not currently live-fetch
those
providers (only ollama/lmstudio register modelsSourceUrl), so deleting
them
today would regress to the curated catalog.
- Remove an unused local type (RuleLoadPart) found while reviewing biome
noUnusedVariables output.
tsc --noEmit clean; vitest 439 passing.
docs(vscode): refine sdk-consolidation TODOs for live model fetching
After inspecting the SDK's generic models-URL fetcher
(sdk/packages/core/src/services/providers/model-source.ts
`fetchModelIdsFromSource` + `resolveModelsSourceUrl`), update the TODOs
on the
bespoke refresh*Models handlers to capture the real constraint
discovered:
- The SDK fetcher exists and is provider-agnostic, but returns model
*ids only*
(unknown ids get placeholder ModelInfo with no real
pricing/capabilities).
- `mergeKnownModels` treats a registered `modelsSourceUrl` as the
authoritative
"installed" list (Ollama/LM Studio semantics) and DISCARDS the curated
catalog
when the live fetch returns results.
So simply registering `modelsSourceUrl` for
Groq/Baseten/Hicap/HuggingFace/
Vercel/OpenRouter would regress rich model metadata. Proper
consolidation needs
an SDK enhancement first (merge-mode or richer per-provider parsing),
then the
extension handlers + RPCs can be deleted. refreshGroqModels.ts carries
the
detailed note; the others reference it.
refactor(vscode): unify ClineMessage id minting behind one
MessageIdMinter
Message ids (ClineMessage.ts) were minted from Date.now() in two
independent
generators: the live message translator (pure ++counter seeded once) and
the
interaction coordinator (Math.max(Date.now(), last+1)). Because the
translator
counter drifts behind wall-clock, it can later catch up to a clock-based
id
minted by the interaction coordinator, producing colliding ids for
different
messages. That breaks any merge-by-id scheme on the webview side.
Introduce a single process-wide MessageIdMinter (pure monotonic
id/seq/epoch
counters, never reads the clock) owned by MessageTranslatorState and
shared by:
- live SDK event translation,
- the interaction coordinator (tool approval / ask_question /
user_feedback),
- history rendering (sdkMessagesToClineMessages).
This makes every id globally unique within the process, so regenerated
history
ids never overlap live-session ids. Behavior is otherwise unchanged.
Also adds the message-state pipeline design + investigation docs under
src/sdk/docs.
S1 of the message-state redesign; seq/epoch stamping and the remaining
one-off
Date.now() mint sites follow in S2.
refactor(vscode): stamp seq/epoch on messages and state; fire-and-forget
delivery
S2 of the message-state redesign. Lays the groundwork for the
convergent-replica
webview reducer (S3) so the webview can never get stuck on
stale/out-of-order
delivery.
Stamping (extension-owned, synchronous, from the single
MessageIdMinter):
- Every ClineMessage flowing to the webview is stamped in
SdkMessageCoordinator with
a fresh `seq` (freshness) and the current `epoch`
(conversation/replica fence),
before it is stored or emitted. The same object references go to both
the message
state handler and the partial-message stream, so both channels carry
identical
stamps. An updated message (partial -> final, same ts) passes through
again and
gets a higher seq, so the freshest copy always wins regardless of
arrival order.
- Every state snapshot is stamped in
SdkController.getStateToPostToWebview with a
fresh `stateVersion` (sampled from the same counter) and the current
`epoch`.
- `epoch` is bumped at every conversation boundary via a new
resetMessageTranslatorAndFence() wired into the existing
resetMessageTranslator
sites (task start/clear, history open, reinit, mode rebuild,
new-session
follow-up). iteration_start streaming resets do NOT bump it.
Transport:
- ClineMessage proto gains seq/epoch (fields 24/25) and the conversions
carry them.
- ExtensionState gains stateVersion/epoch (ride inside state_json, no
proto change).
Fire-and-forget delivery:
- sendPartialMessageEvent and sendStateUpdate no longer await
postMessage to the
webview. A hidden/reloaded/closed webview can make postMessage hang or
resolve
false; awaiting it could stall the backend turn loop. Correctness no
longer
depends on any single delivery — the webview will be a convergent
replica (S3).
All new fields are optional/default-0 so the classic/legacy path is
unaffected.
Cancel's epoch bump + fence-before-abort and the remaining one-off
Date.now() mint
sites are handled in later steps (S6/S2-tail). 423 unit tests pass; tsc
clean.
fix(vscode): converge webview transcript via a pure reducer (fixes
last-message-missing)
S3 of the message-state redesign. The webview received the same
conversation over
two unordered, fire-and-forget channels — incremental partial messages
and full
state snapshots — and the state handler REPLACED clineMessages wholesale
("// HACK:
Preserve clineMessages if currentTaskItem is the same"). A stale
snapshot captured
before the last message landed could clobber the transcript, dropping
the final
message and leaving the UI stuck on "Thinking…" (reproduced earlier on
camera).
Introduce a pure convergent-replica reducer (messageReducer.ts) keyed on
the three
extension-stamped quantities from S2:
- ts : identity / merge key
- seq : freshness (higher seq wins for the same ts)
- epoch : conversation/replica fence (newer replaces, older is
dropped, equal merges)
applyMessage / applyStateSnapshot are total and side-effect free:
- older epoch -> drop (straggler from a previous task/render)
- newer epoch -> replace the transcript wholesale (new task / history
load)
- same epoch -> merge by ts keeping the higher seq; a snapshot may
ADD/UPDATE
rows but NEVER truncate, so it can't drop a message
the partial
stream already delivered. Stale (older stateVersion)
snapshots are
ignored wholesale.
ExtensionStateContext now feeds both subscription callbacks through the
reducer via a
replicaRef, replacing the wholesale-replace HACK and the findLastIndex
append. Classic/
legacy state is unstamped (epoch 0 / version 0) and merges by ts exactly
as before.
Tests (messageReducer.test.ts): deterministic cases mapping 1:1 to the
bugs (stale
snapshot must not shrink the transcript; lower-seq ignored;
partial->final in place;
older-epoch straggler dropped; older-version snapshot ignored), PLUS an
order-independence proof — all 120 permutations of a causal log, with
duplication and
with non-final drops, converge to the same canonical state. This is the
high-confidence
guarantee that the webview cannot get stuck regardless of delivery
timing.
62 webview chat tests pass; tsc and biome clean.
feat(vscode): add authoritative TurnState (backend-owned UI mode)
S4 of the message-state redesign. Introduces the single source of truth
for the
webview's UI mode so it no longer has to be inferred from the tail of
clineMessages
(the root of RC1: missing/stuck "Thinking", vanishing approval buttons,
footer and
buttons disagreeing).
- Add TurnPhase / TurnState to shared types and ExtensionState.turnState
(rides inside
state_json; no proto change).
- Add TurnStateTracker, owned by SdkController, sharing the one
id/seq/epoch authority.
Each transition stamps a fresh seq so the webview keeps only the
newest TurnState.
- Set the phase at the exact lifecycle points where the backend knows
it:
streaming — initTask / reinit / user responded
(resolvePending*)
awaiting_approval — handleRequestToolApproval (anchored on the ask)
awaiting_followup — handleAskQuestion; and a turn that ends WITHOUT
attempt_completion
completed — turn ends and attempt_completion was used
error — onSendError; mistake_limit
resumable — cancelTask (set before abort)
idle — clearTask
The completed-vs-awaiting_followup decision uses
MessageTranslatorState.wasAttemptCompletionSeen().
- getStateToPostToWebview now ships turnState in every snapshot.
This is ADDITIVE: the webview does not read turnState yet (S5 wires
footer/buttons to
it and deletes the tail heuristics). Classic/legacy paths leave
turnState undefined and
keep the legacy behavior. 427 SDK unit tests pass (incl. new
turn-state-tracker tests);
tsc and biome clean.
fix(vscode): drive webview footer + buttons from TurnState (fixes RC1)
S5 of the message-state redesign. The webview decided "thinking vs
approving vs done"
and which buttons to show by inspecting the TAIL of clineMessages.
Because the backend
appends bookkeeping (api_req_started usage) after content and even after
approval asks,
the tail routinely meant the wrong thing — producing stuck "Thinking",
vanishing
Approve/Reject, and the footer disagreeing with the buttons (RC1,
reproduced on camera).
Now the webview reads the authoritative backend-owned TurnState (added
in S4):
- buttonConfig: add buttonsForPhase(turnState, anchoredMessage) and the
dispatcher
getButtonConfigFromState(messages, turnState, mode). The button SET is
chosen by phase;
approval labels (Approve vs Save, Run Command, MCP, subagents) come
from the anchored
message (turnState.anchorTs). When turnState is absent (classic/older
state) it falls
back to the legacy tail-walking getButtonConfigForMessages.
- ActionButtons reads turnState from useExtensionState and uses
getButtonConfigFromState.
- MessagesArea.isWaitingForResponse short-circuits to `phase ===
"streaming"` when
turnState is present (and only shows the footer loader until a content
row is actually
streaming); the legacy tail inference is kept as the fallback.
Button actions (approve/reject/proceed/new_task) already send a fixed
responseType
independent of clineAsk, and the SDK backend resolves the pending
approval/followup
promise — so routing is correct under TurnState. Classic fallback paths
are untouched.
New unit tests cover buttonsForPhase (every phase + anchored-label
selection +
mistake_limit-vs-api_req_failed) and getButtonConfigFromState (prefers
TurnState over a
trailing bookkeeping tail; legacy fallback). 68 webview chat tests pass;
tsc + biome clean.
fix(vscode): cancel raises the epoch fence before aborting (no
post-cancel stragglers)
S6 of the message-state redesign. sdkHost.abort() is cooperative — the
SDK can emit a
few more events after it. Previously cancelTask aborted first and only
the (post-abort)
!isRunning filter stripped two trailing ask types, letting say:*
stragglers land after
the resume_task ask and wedge the UI.
Now cancel raises the fence SYNCHRONOUSLY before the abort:
- SdkController.cancelTask sets turnState.phase = "resumable" (already
in S4), then
- SdkTaskControlCoordinator.cancelTask calls raiseCancelFence() (epoch
bump) BEFORE
awaiting sdkHost.abort().
Any event the SDK emits after the abort request therefore carries the
OLD epoch and is
dropped by the webview's convergent reducer; the authoritative phase is
"resumable"
(Resume Task), independent of the message tail. Order matters and is
covered by a unit
test (fence before abort).
Usage accounting is exempt from the fence — it was never gated by the
message filter, so
a post-cancel usage event still bills the tokens the provider actually
generated.
The legacy !isRunning ask-only filter is now redundant but kept as
defense-in-depth.
428 SDK unit tests pass; tsc + biome clean.
refactor(vscode): translator hygiene — suppress ask_question row, drop
done synthetic ask
S7 (a + c) of the message-state redesign — removes two order-dependent
hacks now that
TurnState is authoritative.
(a) ask_question / ask_followup_question are suppressed from the generic
say:"tool"
renderer (both content_start and content_end). The
SdkInteractionCoordinator services
these and emits the proper ask:"followup"; the generic tool row was
an orphan partial
that never finalized and defeated the tail heuristics. The CLI
already does this.
(c) The `done` handler no longer synthesizes a trailing
ask:"completion_result" — that
was the "must be last message" hack (ENG-1887) that existed only
because the webview
inferred UI mode from the array tail. `done` now emits no transcript
message and only
signals turnComplete; the webview reads phase from TurnState
(completed when
attempt_completion was used, else awaiting_followup). The green
"Task Completed" box
still comes from the say:"completion_result" emitted at
attempt_completion content_end.
Translator unit tests updated to the new contract (done → 0 messages,
turnComplete=true).
Deferred to a follow-up (lower risk if left): (b) collapsing the
approval ask onto the
streaming tool's id (needs cross-coordinator id threading), and (d) the
mistake_limit
forced abort (now harmless since phase is authoritative). The
persisted-history renderer
still appends its own trailing ask so reopened tasks show the resume
affordance —
intentional.
428 SDK unit tests pass; tsc + biome clean.
fix(vscode): fix stuck/missing footer buttons from TurnState regressions
Webview now gates turnState by seq (a stale snapshot can no longer
revert
streaming->idle), never empties a live transcript on a lone newer-epoch
partial,
and routes a follow-up after completed/awaiting_followup to askResponse
instead
of starting a new task.
Backend phase emission fixes surfaced by live testing:
- post state on turn end even when the done event carries no messages
- askResponse sets phase=streaming (resume/continue shows Cancel,
unblocks send)
- a post-cancel turn-complete straggler no longer clobbers resumable
Adds reducer, send-routing, and session-event-coordinator unit tests.
See
src/sdk/docs/webview-message-state-design.md §11 for the full debugging
log.
improve openai compatible provider settings
fix(vscode): show Start New Task after multi-iteration completion turns
The completion signal (attemptCompletionSeen) was scoped to the message
translator's per-iteration reset(), so a turn that called the completion
tool
and then ran another iteration before 'done' lost the signal — the turn
ended
as awaiting_followup instead of completed and the footer showed no
'Start New Task' button despite the green Task Completed box.
Make the completion signal turn-scoped: reset() only clears streaming
pointers;
a new clearTurnOutcome() clears it at genuine turn/task boundaries
(initTask,
reinitExistingTaskFromId, askResponse). Also recognize the SDK's
built-in
submit_and_exit completion tool (summary field) alongside the VSCode
attempt_completion tool (result field).
Removes the webview-message-state design/findings docs and rewrites the
related comments to describe the system as-is.
improve OCA provider
- oca provider login now works
fix history view bugs
- deleting entries works
- favoriting works
fix open task conversation file
fix(vscode): include ambient vscode LM type decls in test tsconfig
The nightly CI "Build Tests and Extension" step (npm run ci:build)
failed
in compile-tests (tsc -p tsconfig.test.json) with:
getVsCodeLmModels.ts: Property 'lm' does not exist on type 'typeof
import("vscode")'
state-keys.ts: Module '"vscode"' has no exported member
'LanguageModelChatSelector'
@types/vscode is pinned to 1.84.0, which predates the Language Model
API.
The repo compensates with an ambient augmentation in
src/types/vscode-language-model.d.ts, which the main tsconfig picks up
via
its 'src/**/*' include. tsconfig.test.json overrides include to only
'src/**/*.test.ts'; listing src/types under typeRoots does not load a
loose
.d.ts (typeRoots only auto-loads @types-style package folders), so the
augmentation was missing from the test program.
Add 'src/types/**/*.d.ts' to tsconfig.test.json include so the
augmentation
is part of the test compilation.
change zai provider to user providers.json instead of statemanager
fix litellm provider
fix(vscode): load ambient vscode LM type decls in unit-test ts-node
program
The nightly CI 'Unit Tests with coverage - Linux' step (npm run
test:unit) failed in ts-node compilation:
state-keys.ts: Module 'vscode' has no exported member
'LanguageModelChatSelector'
This surfaced as a misleading 'Cannot find package @shared/...'
ERR_MODULE_NOT_FOUND: Mocha tried require() first (which threw the
ts-node TSError), then fell back to import(), whose ESM resolver cannot
resolve the @shared/* path alias.
tsconfig.unit-test.json is driven by ts-node, which defaults to
files:false and compiles modules on demand from their imports. The loose
ambient augmentation in src/types/vscode-language-model.d.ts was
therefore never loaded, so state-keys.ts failed to compile.
Set ts-node.files=true and add src/types/**/*.d.ts to include so the
augmentation is part of the unit-test program. Mirrors the earlier
tsconfig.test.json fix for the separate build toolchain.
fix(vscode): widen ZAiProvider getEventValue to accept VSCodeDropdown
event union
The nightly 'vscode test' job (npm run ci:build -> build:webview -> tsc
-b) failed on both Linux and windows-latest:
ZAiProvider.tsx: Argument of type 'Event | FormEvent<HTMLElement>' is
not assignable to parameter of type 'Event'
VSCodeDropdown's onChange supplies 'Event |
React.FormEvent<HTMLElement>', but the getEventValue helper (added when
the zai provider was moved to providers.json) was typed to accept only
Event. The helper only reads target.value, which exists on both, so
widen the parameter to the same union the dropdown provides.
Note: this only surfaces under 'tsc -b' / 'tsc --noEmit -p
tsconfig.app.json'; the webview's root tsconfig.json is a solution file
with files:[] so a bare 'tsc --noEmit' checks nothing.
The separate 'test / test' job failure is an aggregate gate that fails
because vscode-test failed; fixing this resolves it too.
deleteServerRPC and addRemoteServer wrote cline_mcp_settings.json without
setting isUpdatingClineSettings, so the chokidar settings watcher was not
suppressed during the plugin's own write. The watcher is configured with
atomic: true and awaitWriteFinish (stabilityThreshold 100ms); on Windows it
races the non-atomic writeFile, reads a transient/empty file, and
readAndValidateMcpSettingsFile() returns { mcpServers: {} }. updateServerConnections({})
then tears down every in-memory connection, so deleting one MCP server emptied
the whole list in the UI after navigating away and back (CLINE-2097).
Wrap both methods in the same guard the sibling RPCs already use
(toggleServerDisabledRPC, toggleToolAutoApproveRPC, updateServerTimeoutRPC):
set isUpdatingClineSettings = true before the write and clear it on a 300ms
timer in finally, so the delayed watcher "change" event is skipped. addRemoteServer
had the same latent omission and is fixed in the same change.
Known tradeoff (pre-existing, unchanged by this fix): the guard is a single
shared boolean cleared by uncoordinated 300ms timers, so two settings writes
within 300ms can clear the flag early. Because awaitWriteFinish only emits once
the file is stable, the worst case there is a redundant reconnect, not the
empty-list data loss this fixes. A deterministic guard (per-op token or
content-compare-and-skip in the watcher) is out of scope for this targeted fix.
Adds McpHub.deleteServerRPC.test.ts covering the user-visible symptom (delete
one of two servers -> remaining server still returned/persisted, list not empty)
and the guard contract (flag set during write, cleared after 300ms, cleared on
the not-found error path).
* docs(cli): release the SDK before the CLI in the publish-cli skill
Add a Step 0 to the publish-cli skill that gates a CLI release on an SDK
release when the SDK changed since its last release, and relocate the
publish-cli skill to the repo root.
Why release the SDK alongside the CLI: the CLI bundles the SDK source via
workspace:*, so the CLI always ships the latest SDK code, but the hub
daemon stamps a buildId that defaults to the @cline/core version and a
running hub is only respawned when that buildId changes. Bumping the SDK
version forces a stale hub to be retired and respawned with the new code.
It also keeps SDK releases on a regular cadence in step with the CLI.
Step 0 covers detecting unreleased sdk/packages changes, bumping the
shared SDK version + llms CHANGELOG, committing to main, kicking off
sdk-publish.yml on the latest channel, and waiting for it before cutting
the CLI release. Also fixes the now-stale working-directory note (commands
run from the repo root, not sdk/) and updates the DEVELOPMENT.md path.
* chore: move opentui skill to repo root
Relocate the opentui TUI skill from apps/cli to the repo root, matching
the real-dir + symlink convention used by the other root skills (real dir
in .agents/skills, symlink from .claude/skills).
* docs(sdk): reformat the SDK changelog and move it to sdk/CHANGELOG.md
The changelog covers all SDK packages (they share one version and release
together), so move it from sdk/packages/llms/ to the SDK root, parallel to
apps/cli/CHANGELOG.md. Reformat to match the CLI changelog: a titled
header with flat, version-only sections, newest on top, no dates, and no
Next Release bucket. The unreleased entry that bucket held is captured
from commits when the next SDK release is drafted. Update the publish-cli
skill to draft SDK notes from commits and prepend a ## <version> section
at sdk/CHANGELOG.md.
* fix(slack): normalize channel mentions to original post thread
Route top-level Slack channel mentions to the originating post thread so
replies land in the correct conversation. Add `resolveSlackChannelMentionThread`
to rewrite non-DM mention threads using the message's `thread_ts`/`ts` and
channel, while preserving DM threads and already-correct threads.
Includes unit tests covering normalization, no-op, and DM cases.
* thread id
* feat: update Fireworks model registry to improve Cline UX for Fireworks API users
The VS Code extension's Fireworks model list was significantly out of
date compared to the current active models available on the Fireworks
platform. This commit updates the registry to match the current model
lineup, ensuring users can select from the latest available models.
Changes:
- Default model: accounts/fireworks/models/kimi-k2p6 (was kimi-k2p5)
- SDK default: accounts/fireworks/models/kimi-k2p6 (was minimax-m2p5)
Removed 6 stale/phantom models no longer available:
- qwen3-vl-30b-a3b-thinking
- qwen3-vl-30b-a3b-instruct
- deepseek-v3p2
- glm-4p7
- glm-5
- minimax-m2p1
Added 9 missing models:
- accounts/fireworks/models/kimi-k2p6
- accounts/fireworks/routers/kimi-k2p6-turbo
- accounts/fireworks/models/deepseek-v4-flash
- accounts/fireworks/models/deepseek-v4-pro
- accounts/fireworks/models/glm-5p1
- accounts/fireworks/routers/glm-5p1-fast
- accounts/fireworks/models/minimax-m2p7
- accounts/fireworks/models/qwen3p6-plus
- accounts/fireworks/models/gpt-oss-20b
Fixed metadata for 3 overlapping models:
- kimi-k2p5: contextWindow 262144 → 256000, maxTokens 16384 → 256000
- minimax-m2p5: maxTokens 16384 → 196608
- gpt-oss-120b: maxTokens 16384 → 32768, cacheReadsPrice 0.01 → 0.015
All models now have cacheWritesPrice: 0 because Fireworks does not
charge a separate rate for prompt cache writes (cache writes are
billed at the standard input rate, matching the SDK catalog).
Three models remain in the UI but are scheduled for deprecation on
June 17 and will be removed then:
- accounts/fireworks/models/kimi-k2p5
- accounts/fireworks/models/minimax-m2p5
- accounts/fireworks/models/qwen3p6-plus
Files:
- apps/vscode/src/shared/api.ts
- apps/vscode/webview-ui/src/components/settings/__tests__/APIOptions.spec.tsx
- sdk/packages/llms/src/providers/builtins.ts
* fix: update qwen3p6-plus context window and maxTokens
* fix(cli): recover stale interactive sessions and suppress shutdown hook races
This fixes the CLI/TUI regression introduced between `3.0.14` and `3.0.15` where the interactive CLI could enter a broken state after stopping and restarting Cline Hub, then attempting to cancel a request with Escape.
The affected release window was:
- `49e8c1b32` / `v3.0.14`: known-good baseline
- `c33c3176e` / `v3.0.15`: release containing the regression
- `fad8271f4 feat: Cline Hub web app (#10969)`: relevant behavior change in the window
The Hub web app change introduced new Hub-backed runtime/session lifecycle behavior. After Ctrl+C or Hub shutdown, the CLI could still retain an `activeSessionId` that no longer existed in the Hub/runtime process. On the next interactive send, the CLI attempted to reuse that stale session and received `session not found`. Because cancellation also targeted the stale session, Escape stopped working and OpenTUI ended up receiving failures during input handling, which made the TUI look corrupted.
The same lifecycle issue also explains the Ctrl+C errors:
```text
error: hook dispatch failed: Hub connection closed (code=1006, reason=Connection ended)
error: WebSocket connection to 'ws://127.0.0.1:50168/hub' failed: Failed to connect
```
Those were caused by late hook dispatches racing against Hub shutdown. The CLI was still trying to send hook events over a Hub WebSocket that had already closed.
**What changed**
- Added missing-session recovery in the interactive runtime.
- Detects `session not found` / stale session errors.
- Reads any recoverable messages from the missing session.
- Clears the stale active session state.
- Starts a new interactive runtime session.
- Retries the current turn once against the fresh session.
- Made hook dispatch shutdown-aware.
- Runtime hooks now mark themselves as shutting down before session disposal.
- Hook dispatches are skipped once shutdown begins.
- Dispatch failures during shutdown are suppressed, since the Hub transport closing is expected at that point.
- Reordered CLI cleanup.
- Hooks are shut down before stopping/disposing runtime sessions.
- This prevents abort/stop lifecycle events from trying to dispatch over a closing Hub connection.
**Regression coverage**
Added tests for:
- Recovering from a disappeared active interactive session and retrying against a new session.
- Ensuring hook events are not dispatched after shutdown begins.
**Verification**
Passed:
```text
bunx vitest run apps/cli/src/utils/hooks.test.ts apps/cli/src/runtime/interactive/session-runtime.test.ts
bun -F @cline/cli typecheck
bun -F @cline/cli test:unit
bun -F @cline/cli test:e2e:cli:tui
git diff --check
```
* SessionNotFoundError
* fix(core): preserve stale session errors in hub runs
* clean up
---------
Co-authored-by: Saoud Rizwan <7799382+saoudrizwan@users.noreply.github.com>
* feat(cli): add Slack socket mode support
Add socket mode as an alternative to webhook mode for Slack
connector, allowing connections without a public URL.
- Introduce `--connection` flag to select webhook or socket mode
- Add `--app-token` option for socket mode authentication
- Make signing secret and base URL conditional on webhook mode
- Add `parseSlackConnectionMode` with validation and tests
- Update CLI platform definition to support hybrid connection type
- Update README docs with socket mode usage examples
* use base-url and remove connection flag
* isSocketMode
* fix(core): use union schema for read files tool input validation
Move the normalizeReadFileRequests helper logic directly into the
read_files tool executor, replacing the legacy helper with inline
validation against ReadFilesInputUnionSchema. This ensures invalid
union inputs are rejected before reaching the executor.
Update tests to reflect validation behavior and add coverage for
rejecting invalid union inputs.
* add new schema support
* feat(llms,core): route custom registered handlers through the agent runtime
Expose the handler-registry helpers (hasRegisteredHandler, getRegisteredHandler,
getRegisteredHandlerAsync, isRegisteredHandlerAsync) from @cline/llms, and have
core's createAgentModelFromConfig consult the registry: when a handler is
registered for a provider, build it via createHandler and adapt its ApiHandler
surface onto the AgentModel contract (the inverse of the gateway's
toApiStreamChunk).
This lets hosts register provider handlers that need host-only dependencies
(e.g. a vscode.lm-backed handler) and have them used by the main agent loop,
not just standalone createHandler callers.
* fix(core): resolve registered handlers lazily and avoid double finish
Address review feedback:
- createAgentModelFromConfig built the handler eagerly with the sync
createHandler, which throws for providers registered via registerAsyncHandler.
The adapter now accepts a handler factory and resolves it on the first stream
via createHandlerAsync, supporting both sync- and async-registered handlers.
- Guard the adapter's catch-block finish with sawFinish so a handler that emits
an explicit done chunk and then throws does not produce two finish events.
* fix(core): preserve thought signatures and finish-reason semantics in adapter
Further review feedback on the ApiHandler -> AgentModel adapter:
- Reasoning and tool-call thought signatures are now surfaced under
metadata.thoughtSignature (the key downstream adapters read), instead of being
stored as metadata.signature / dropped.
- A done chunk whose incompleteReason indicates max output tokens now maps to
finish{reason:"max-tokens"} rather than "stop".
- A turn that ends with tool calls (no explicit done) now terminates as
finish{reason:"tool-calls"}, matching the gateway/AI-SDK adapters.
* Apply remaining changes
* fix(core): report lazy handler-factory rejection as a finish(error) event
The lazy handler resolution (await source()) ran outside the adapter's
try/catch, so a rejecting factory (e.g. when the host API is unavailable at
stream time) escaped as a raw generator exception instead of a terminal
finish{reason:"error"} event. Move the resolution inside the try block so all
failure paths converge on the same terminal finish.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
- user's who are signed in with oauth in old extension were not properly
migrating their token. this commit handles that
Co-authored-by: Max Paulus 🥪 <max@cline.bot>
* docs(sdk): add custom model provider plugin example
Add an OpenRouter-backed example plugin demonstrating the providers
capability and registerProvider. It registers an OpenAI-compatible
provider plus its model catalog with the gateway so the agent can run
inference against an endpoint Cline does not bundle.
Registers under a distinct id (openrouter-plugin) to avoid colliding
with the built-in openrouter provider.
* docs(sdk): drop redundant provider section from plugin examples readme
* docs(sdk): drop provider demo line from plugin examples readme
* fix: support plugin model providers
* docs: remove provider plugin demo
* docs: address provider example review
* Move the apps to the root dir
* Update all references from sdk/apps/ to apps/
* Update dependencies
* Install bun types
* Fix types
* Fix types
* Fix linter
* Ingore apps from vscode
* Fix security warning
* Fix windows install
* Enable windows dev mode
* Revert "Enable windows dev mode"
This reverts commit a46c99282e.
* Revert "Ingore apps from vscode"
This reverts commit 47f7b265d2.
* Revert "Fix windows install"
This reverts commit 1dabba1556.
* update the repo root
* fix root dir
* fix path
* fix other path
* Fix unrelated changes
* fix: address apps move follow-up blockers (#11228)
* fix: update root app command paths
* fix: include moved apps in root checks
* fix: clean up moved app path references
---------
Co-authored-by: Saoud Rizwan <7799382+saoudrizwan@users.noreply.github.com>
- Fold provider/model setup into a single `cline` run; drop the auth command
- Remove the /yolo on step from the Telegram setup
- Present scheduling as two clear options (Telegram chat vs terminal with
delivery flags)
- Clarify how to find the schedule id before triggering a test run
* docs(cli): add supply-chain scan alerts sample
Walkthrough for scheduling the Cline CLI to run Perplexity's Bumblebee
scanner and deliver compromise alerts to Telegram. Covers installing the
CLI, cloning/building Bumblebee and how it stays read-only, the Telegram
connector, and creating a scheduled scan that texts a clean/alert verdict.
* docs(cli): drop unsupported --delivery-thread from supply-chain sample
* feat(cli): bundle and serve Cline Hub dashboard with cline dashboard
Add the @cline/cline-hub workspace dependency to the CLI and build the
Hub webview as part of CLI packaging. Copy the generated dashboard assets
into platform-specific CLI distributions so the dashboard is available in
built artifacts.
Refactor the Cline Hub server startup into an exported function so the CLI
can start and stop the dashboard server programmatically.
* fix(cli): resolve dashboard webview in wrapper installs
Detect the platform-specific CLI package from the published wrapper layout
and use its bundled cline-hub webview assets when no explicit dist path is
set. Add test coverage for resolving assets via CLINE_WRAPPER_PATH.
* patches
* patch
* fix server detachHub on stop
Imported detachHub.
Changed ClineHubDashboardServer.stop to () => Promise<void>.
Made stop() idempotent with a stopped guard.
Clears the health interval.
Calls server.stop(true).
Always calls await detachHub(ctx) in a finally, so hub client teardown still happens if the HTTP server stop throws.
---------
Co-authored-by: Saoud Rizwan <7799382+saoudrizwan@users.noreply.github.com>
* fix(plugin-sandbox): expose CLINE_PLUGIN_IMPORT_TIMEOUT_MS env override
The hardcoded 4000 ms importTimeoutMs default is too tight on Windows
cold-start; the plugin-sandbox tests already use 30_000 ms for the same
reason. This patch lets hosts raise the ceiling via env var without
touching code or adding a CLI flag, with explicit options.importTimeoutMs
still taking precedence.
Precedence: options.importTimeoutMs > env var > 4000.
Refs: #11065
* fix(plugin-sandbox): tighten env parsing + use vi.stubEnv (PR feedback)
- Number.parseInt accepts trailing garbage ("4000ms" -> 4000); switch
to Number() + Number.isInteger() so malformed env values fall back
to the default instead of silently consuming the numeric prefix.
- Replace manual process.env save/restore in the regression test with
the idiomatic vi.stubEnv() / vi.unstubAllEnvs() pattern.
Per Greptile review on #11084.
* docs(sdk): add env-blocker plugin example
Adds a beforeTool hook plugin that deterministically blocks the agent
from reading .env secret files via read_files, editor, or run_commands
(e.g. cat .env), while leaving .env.example/.sample/.template readable.
Demonstrates moving a security policy out of an AGENTS.md rule (a
suggestion the model can ignore) and into the execution path.
* docs(sdk): install env-blocker globally in usage examples
A secret-protection guard is most useful applied to every project, so
drop the --cwd . project-scoped install in favor of the global default.
* docs(sdk): trim env-blocker usage docs
* docs(sdk): limit env-blocker to read paths only
It is a read blocker, so only guard read_files and run_commands.
Drop the editor case (and with it the symmetric apply_patch concern),
keeping the example focused and simple.
* docs(sdk): rename env-blocker helpers for readability
collectPaths -> extractFilePaths, collectCommands -> extractShellCommands
so the beforeTool call sites read clearly at a glance.
* docs(sdk): rename commandTouchesEnv to commandReadsEnv
* docs(sdk): drop console.error from env-blocker hook
2026-06-01 12:12:16 -07:00
2021 changed files with 61042 additions and 136748 deletions
@@ -9,12 +9,13 @@ Use this skill when the user asks to release the CLI, publish `cline`, bump the
The CLI is npm-only. Do not add alternate distribution or signing steps.
> Working directory: this skill lives in the SDK sub-monorepo. Run `cd sdk` (from the repo root) before any of the shell commands below. Paths in commands and instructions (e.g. `apps/cli/package.json`, `bun release cli`) are written relative to `sdk/`.
> Working directory: run every command below from the repository root. Paths and scripts (e.g. `apps/cli/package.json`, `sdk/packages/`, `bun release cli`, `bun run version`) are written relative to the repo root.
The skill should guide the user through one release preparation flow, then offer the publish path options. The two normal publish paths are GitHub Actions and local publishing from an authenticated machine.
## Release contract
- SDK prerequisite: the CLI depends on the SDK via `workspace:*` (`@cline/core`, `@cline/shared`, and friends). If the SDK changed since its last release, release the SDK first and wait for it to finish publishing before releasing the CLI. See "Step 0: Release the SDK first if it changed" below.
- Version source: `apps/cli/package.json`.
- Main release tag: `cli-vX.Y.Z`, where `X.Y.Z` matches `apps/cli/package.json`.
@@ -30,8 +31,93 @@ The skill should guide the user through one release preparation flow, then offer
- Always ask before pushing commits or tags.
- Do not amend commits unless explicitly requested.
## Step 0: Release the SDK first if it changed
Do this before anything else in the Workflow below.
The CLI builds and ships against the SDK source in the monorepo (`workspace:*` for `@cline/core`, `@cline/shared`, and the rest), so a CLI release always contains the latest SDK code whether or not the SDK was released. The build and tests use that source too, not anything from npm. Releasing the SDK alongside the CLI is still worth doing for two reasons:
- Hub freshness. The hub daemon lives in `@cline/core` and stamps a `buildId` that defaults to the `@cline/core` package version (`resolveHubBuildId` in `sdk/packages/core/src/hub/discovery/index.ts`). A running hub is only retired and respawned when that `buildId` changes (`isCompatibleHubRecord` / `retireIncompatibleHub` in `sdk/packages/core/src/hub/daemon/index.ts`). So if the SDK code changed but the version did not, a user who upgrades the CLI keeps talking to their already-running hub, which is still executing the old SDK code. Bumping the SDK version makes the new CLI's `buildId` differ, so the stale hub is detected as incompatible and respawned with the fresh code.
- Release hygiene. We want regular SDK releases; cutting one whenever we cut a CLI release keeps the published SDK in step with what the CLI ships.
So when the SDK has changed, release it first (which bumps the `@cline/core` version), then cut the CLI release on top of that bump. Leave the CLI's SDK dependency as `workspace:*` — the fix is to release the SDK, not to pin the CLI.
1. Check for unreleased SDK changes.
```sh
git fetch origin --tags
git tag --list 'sdk/sdk/v*' 'sdk-v*' --sort=-v:refname | head -1
`sdk/<pkg>/v*` tags are created by the `sdk-publish.yml` workflow; `sdk-v*` tags are created by the local `bun release sdk` helper. Use whichever is newest as the baseline.
If `git log` prints no commits, the SDK is already up to date. Skip the rest of Step 0 and continue with the Workflow below.
If it prints commits, sanity-check the diff (ignore entries that are only the previous version-bump commit's lockfile or generated files), then release the SDK.
2. Decide the SDK version bump.
All SDK packages share one version, read from `sdk/packages/llms/package.json`. Ask whether this is patch, minor, major, or an explicit version. Patch is the default. Do not guess if the user has not made it clear.
3. Draft the SDK release notes and update the changelog.
Draft user-facing notes from the SDK commits found in step 1, translating commit messages into user-facing language (same approach as the CLI release notes below). Prepend a new `## <version>` section with those notes to the top of `sdk/CHANGELOG.md`, using the header format `## <version>` with no date — the same flat, newest-on-top format as `apps/cli/CHANGELOG.md`. This is the SDK changelog (all SDK packages share one version) and it is maintained by hand; the `sdk-publish.yml` workflow does not read it.
4. Bump versions and regenerate.
```sh
bun run version <version>
```
This bumps every SDK `package.json` to the new version, regenerates the lockfile and the generated model catalog, formats, and builds. Review the result.
5. Commit and push the bump to `main`.
The `sdk-publish.yml` workflow publishes the version that is committed on `main` and tags that commit, so the bump must land on `main` before the workflow runs.
```sh
git add -A
git commit -m "chore(sdk): release v<version>"
```
Ask before pushing:
```sh
git push origin HEAD
```
6. Trigger the SDK publish workflow on the `latest` channel.
```sh
gh workflow run sdk-publish.yml -f channel=latest -f confirm_publish=publish
gh run list --workflow=sdk-publish.yml --limit=1 --json databaseId,url,status,createdAt --jq '.[0]'
```
The workflow runs the SDK tests, publishes `@cline/shared`, `@cline/llms`, `@cline/agents`, `@cline/core`, and `@cline/sdk` to npm with the `latest` dist-tag in dependency order, and pushes `sdk/<pkg>/v<version>` git tags.
7. Wait for the SDK workflow to succeed before starting the CLI release.
```sh
gh run watch <run-id> --exit-status
```
Do not start the CLI release until this run has finished successfully. The CLI does not install the SDK from npm, but cutting the CLI release on top of a clean, completed SDK release keeps the two in step: the CLI release commit then sits on top of the `@cline/core` version bump, so the shipped CLI carries the new version that forces a running hub to respawn with the new code, and you are not building a CLI release on top of an SDK release that failed midway.
After the SDK release succeeds, pull `main` so the CLI release is prepared on top of the SDK version bump:
```sh
git checkout main && git pull --ff-only
```
Then continue with the Workflow below.
For a local SDK publish from an authenticated machine instead of the workflow, `bun release sdk <version>` exists, but prefer the `sdk-publish.yml` workflow for normal releases so the CLI release can gate on a single GitHub Actions run.
## Workflow
Complete Step 0 first. Only proceed once the SDK is released (or you confirmed no SDK release was needed).
1. Gather context.
```sh
@@ -46,10 +132,10 @@ Find the latest CLI tag. If there is no `cli-v*` tag, use the first relevant CLI
If the release includes broader SDK changes that affect the CLI, also inspect commits outside `apps/cli`.
The `sdk/packages` commits matter here even though the SDK was released separately in Step 0: the CLI bundles the SDK, so SDK changes ship in this CLI release too. Read those commits and fold anything user-relevant to the CLI into the release notes (provider/model updates, behavior changes, fixes the CLI inherits). Skip SDK changes that are purely internal or have no CLI-visible effect.
All via `POST localhost:19229/api` with `{"method":"...", "params":{...}}`:
- **`launch`** / **`shutdown`** — lifecycle
- **`ui.screenshot`** — screenshot to `/tmp/cline-debug/`; returns `{path}` — **use `read_file` on the path to examine, do NOT `open` the file** (Preview.app covers the VSCode window)
- **`web.evaluate`** `{expression}` — eval in webview
- **`web.post_message`** `{message}` — send postMessage to extension host via exposed vsCodeApi
- **`wait_for_pause`** `{timeout?}` — block until breakpoint hit
- **`ui.locator`** `{role?, testId?, text?, frame?}` — Playwright locator (auto-retries on stale sidebar frame)
- **`ui.react_input`** `{text, selector?, clear?, submit?}` — set React textarea value via `execCommand('insertText')`; works reliably across multiple tasks
- **⚠️ Dismiss promotional overlays FIRST**: On fresh launches, full-screen promo overlays block the sidebar. **Dismiss immediately after `ui.open_sidebar`**, before any other interaction or screenshot. May need to run twice:
- **Screenshots — don't open the file**: `ui.screenshot` and `ui.sidebar_screenshot` save PNGs to `/tmp/cline-debug/` and return the `{path}`. Use `read_file` on that path to examine screenshots. Running `open <path>` launches Preview.app on macOS which covers the VSCode window.
- **Scripts count = 0 after launch**: CDP connects after extension host starts, so scripts parsed during startup aren't tracked. Breakpoints still work via sourcemap resolution.
- **Port 9230**: Extension host inspector. If another VSCode instance uses this port, the harness will fail to connect. Kill other debug instances first.
- **macOS only** for now (Playwright Electron launch behavior).
- **Webview CDP**: `connect_webview` may fail depending on Electron version. `web.evaluate` still works via Playwright's `frame.evaluate()` fallback.
- **Sourcemap paths**: esbuild outputs relative paths like `../src/extension.ts` in the sourcemap. The resolver handles this, but if a file isn't found, use `ext.source_files` to see exact paths.
- **OAuth with fake codes**: Browser capture intercepts the URL but doesn't provide a valid auth code. For real OAuth testing, open the captured URL in a browser. For unit testing, mock the token exchange.
See `src/dev/debug-harness/README.md` for full API reference.
@@ -13,11 +13,55 @@ This file is the secret sauce for working effectively in this codebase. It captu
**What NOT to add:** Stuff you can figure out from reading a few files, obvious patterns, or standard practices. This file should be high-signal, not comprehensive.
## Miscellaneous
- Avoid provider-specific string matching / hardcoded provider branches when fixing provider/config plumbing. Prefer provider metadata, shared catalog/defaults, explicit protocol/client capabilities, or centralized normalization utilities that apply by data shape rather than `providerId === "..."`. If a provider exception seems necessary, stop and explain why instead of adding ad-hoc string matching.
- This is a VS Code extension—check `package.json` for available scripts before trying to verify builds (e.g., `npm run compile`, not `npm run build`).
- When creating PRs, contributors should not create changelog-entry files. Maintainers handle release versioning and changelog curation during the release process.
- When adding new feature flags, see this PR as a reference https://github.com/cline/cline/pull/7566
- Additional instructions about making requests: @.clinerules/network.md
## Searching the Codebase — Avoiding Build Output
Several directories contain build output or generated code that produces
noisy or unusable results with `search_files` / `grep`:
| Directory | What it is | Why it's a problem |
|-----------|-----------|-------------------|
| `out/` | esbuild bundle output | Mirrors `src/` structure as minified JS — every search gets duplicate hits on single-line files |
| `dist/` | Packaged extension | Entire extension bundled into one minified `extension.js` (~1 long line) |
When adding a new provider (e.g., "openai-codex"), you must update the proto conversion layer in THREE places or the provider will silently reset to Anthropic:
1.`proto/cline/models.proto` - Add to the `ApiProvider` enum (e.g., `OPENAI_CODEX = 40;`)
2.`convertApiProviderToProto()` in `src/shared/proto-conversions/models/api-configuration-conversion.ts` - Add case mapping string to proto enum
3.`convertProtoToApiProvider()` in the same file - Add case mapping proto enum back to string
**Why this matters:** Without these, the provider string hits the `default` case and returns `ANTHROPIC`. The webview, provider list, and handler all work fine, but the state silently resets when it round-trips through proto serialization. No error is thrown.
**Other files to update when adding a provider:**
-`src/shared/api.ts` - Add to `ApiProvider` union type, define models
-`src/shared/providers/providers.json` - Add to provider list for dropdown
-`src/core/api/index.ts` - Register handler in `createHandlerForProvider()`
-`webview-ui/src/components/settings/utils/providerUtils.ts` - Add cases in `getModelsForProvider()` and `normalizeApiConfiguration()`
-`webview-ui/src/utils/validate.ts` - Add validation case
## Responses API Providers (OpenAI Codex, OpenAI Native)
Providers using OpenAI's Responses API require native tool calling. XML tools don't work with the Responses API.
**Symptoms of broken native tool calling:**
- Tools get called multiple times (e.g., `ask_followup_question` asks the same question twice)
- Tool arguments get duplicated or malformed
- The model responds but tools aren't recognized
**Root causes to check:**
1.**Provider missing from `isNextGenModelProvider()`** in `src/utils/model-utils.ts`. The native variant matchers (e.g., `native-gpt-5/config.ts`) call this function. If your provider isn't in the list, the matcher returns false and falls back to XML tools.
2.**Model missing `apiFormat: ApiFormat.OPENAI_RESPONSES`** in its model info (`src/shared/api.ts`). This property signals that the model requires native tool calling. The task runner in `src/core/task/index.ts` checks this and forces `enableNativeToolCalls: true` regardless of user settings.
**When adding a new Responses API provider:**
1. Add provider to `isNextGenModelProvider()` list in `src/utils/model-utils.ts`
2. Set `apiFormat: ApiFormat.OPENAI_RESPONSES` on all models that use the Responses API
3. The variant matcher and task runner will handle the rest automatically
## Adding Tools to System Prompt
This is tricky—multiple prompt variants and configs. **Always search for existing similar tools first and follow their pattern.** Look at the full chain from prompt definition → variant configs → handler → UI before implementing.
1.**Add to `ClineDefaultTool` enum** in `src/shared/tools.ts`
2.**Tool definition** in `src/core/prompts/system-prompt/tools/` (create file like `generate_explanation.ts`)
- Define variants for each `ModelFamily` (generic, next-gen, xs, etc.)
- **Fallback behavior**: If a variant isn't defined for a model family, `ClineToolSet.getToolByNameWithFallback()` automatically falls back to GENERIC. So you only need to export `[GENERIC]` unless the tool needs model-specific behavior.
3.**Register in `src/core/prompts/system-prompt/tools/init.ts`** - Import and spread into `allToolVariants`
4.**Add to variant configs** - Each model family has its own config in `src/core/prompts/system-prompt/variants/*/config.ts`. Add your tool's enum to the `.tools()` list:
**How overrides work:** Variants can override components via `componentOverrides` in their `config.ts`, or provide a custom template in `template.ts` (e.g., `next-gen/template.ts` exports `rules_template`). If no override, the shared component from `components/` is used.
**Example: Adding a rule to RULES section**
1. Check if variant overrides rules: look for `rules_template` in `variants/*/template.ts` or `componentOverrides.RULES` in `config.ts`
2. If shared: modify `components/rules.ts`
3. If overridden: modify that variant's template
4. XS variant is special—has heavily condensed inline content in `template.ts`
**After any changes, regenerate snapshots:**
```bash
UPDATE_SNAPSHOTS=true npm run test:unit
```
Snapshots live in `__tests__/__snapshots__/`. Tests validate across model families and context variations (browser, MCP, focus chain).
Adding a new key to global state requires updates in multiple places. Missing any step causes silent failures.
Required steps:
1. Type definition in `src/shared/storage/state-keys.ts` - Add to `GlobalState` or `Settings` interface
2. Read from globalState in `src/core/storage/utils/state-helpers.ts`:
- Add `const myKey = context.globalState.get<GlobalStateAndSettings["myKey"]>("myKey")` in `readGlobalStateFromDisk()`
- Add to the return object: `myKey: myKey ?? defaultValue,`
3. StateManager handles read/write via `setGlobalState()`/`getGlobalStateKey()` after initialization
2. Add any default value or transform in `src/shared/storage/state-keys.ts` if the key needs one
3. Read and write the value through `StateManager` (`setGlobalState()` / `getGlobalStateKey()`) after initialization
Common mistake: Adding only the return value without the `context.globalState.get()` call. This compiles but the value is always `undefined` on load.
Persistent state is file-backed through `StateManager`; do not add new runtime reads or writes against VS Code `ExtensionContext` storage. That storage is only a legacy migration source.
Settings plumbing gotcha: if a key is user-toggleable from settings, wire both controller update paths:
- `src/core/controller/state/updateSettings.ts` for webview `updateSetting(...)`
@@ -159,22 +114,20 @@ Webview toggle gotcha: settings changes must also round-trip back in state paylo
If this round-trip wiring is missing, the backend value can update but the toggle in webview appears stuck or reverts.
## StateManager Cache vs Direct globalState Access
StateManager uses an in-memory cache populated during `StateManager.initialize(context)` in `common.ts`. For most state, use `controller.stateManager.setGlobalState()`/`getGlobalStateKey()`.
StateManager uses an in-memory cache populated during `StateManager.initialize()` from file-backed storage. For most state, use `controller.stateManager.setGlobalState()`/`getGlobalStateKey()`.
Exception: State needed immediately at extension startup (before cache is ready)
Exception: host migration code may read legacy VS Code storage before file-backed storage is initialized.
When Window A sets state and immediately opens Window B, the new window's StateManager cache is populated from `context.globalState` during initialization. If you need to read state in Window B right at startup (e.g., in `common.ts` during `initialize()`), read directly from `context.globalState.get()` instead of StateManager's cache.
Example pattern (see `lastShownAnnouncementId` and `worktreeAutoOpenPath`):
const value = controller.stateManager.getGlobalStateKey("myKey")
```
This is only needed for cross-window state read during the brief startup window before StateManager cache is fully usable. Normal state access after initialization should use StateManager.
Use `context.globalState` only in VS Code migration code that copies legacy ExtensionContext values into the shared file-backed stores.
## ChatRow Cancelled/Interrupted States
When a ChatRow displays a loading/in-progress state (spinner), you must handle what happens when the task is cancelled. This is non-obvious because cancellation doesn't update the message content—you have to infer it from context.
**See also:** `BrowserSessionRow.tsx` uses similar pattern with `isLastApiReqInterrupted` and `isLastMessageResume`.
**Backend side:** When streaming is cancelled, clean up properly (close tabs, clear comments, etc.) by checking `taskState.abort` after the streaming function returns.
## Debug Harness: clear inherited VSCode/Electron env vars before launching
The debug harness (`apps/vscode/src/dev/debug-harness/server.ts`) launches a child
VSCode via Playwright's `_electron.launch({ env: { ...process.env, ... } })`. If you
run the harness from a process that was itself spawned by VSCode (e.g. the Cline
extension host, an integrated terminal, or an agent running inside VSCode), the
parent's VSCode/Electron env vars leak into the child and break the launch.
The fatal one is **`ELECTRON_RUN_AS_NODE=1`**: it makes the child VSCode binary run
as plain Node, so it rejects every VSCode CLI flag. Symptom:
```
.../Visual Studio Code.app/Contents/MacOS/Code: bad option: --extensionDevelopmentPath=...
Error: Process failed to launch! (Playwright _electron.launch)
```
This is NOT the macOS Playwright flakiness mentioned in the harness README — it's
env inheritance. Fix: strip the inherited vars before starting the harness:
@@ -44,7 +44,7 @@ For Responses API providers: add to `isNextGenModelProvider()` in `src/utils/mod
Modular: `components/` (shared) + `variants/` (model-specific) + `templates/` (`{{PLACEHOLDER}}`). Variants override components via `componentOverrides` in `config.ts` or custom `template.ts`. XS variant is heavily condensed inline. Always regenerate snapshots after changes.
## Global State Keys (silent failure risk)
Adding a key requires: type in `src/shared/storage/state-keys.ts`, read via `context.globalState.get()` in `src/core/storage/utils/state-helpers.ts``readGlobalStateFromDisk()`, and add to return object. Missing the `.get()` call compiles fine but value is always `undefined`.
Adding a key requires updating the typed storage definitions in `src/shared/storage/state-keys.ts`; runtime reads and writes should go through `StateManager`, not VS Code `ExtensionContext` storage. Persistent state is file-backed so it works across VS Code, CLI, and JetBrains hosts.
"rule":"Any new tool handler added to packages/agents/src or packages/core/src that performs a user-visible action (writes files, executes commands, modifies state, calls external APIs) must include a call to captureToolUsage() from packages/core/src/services/telemetry/core-events.ts, or emit a task.tool_used event via telemetry.capture(). Pure read-only helpers and getters are exempt. When in doubt, prefer instrumentation.",
"rule":"New session start, end, or state-transition code paths in packages/core/src must call the appropriate typed helper from packages/core/src/services/telemetry/core-events.ts (captureTaskCreated, captureTaskCompleted, captureConversationTurnEvent, captureTokenUsage, etc.). Do not inline raw telemetry.capture() calls for session lifecycle events — always use the typed helper, which guarantees a consistent payload shape.",
"scope":[
"packages/core/src/cline-core/**",
"packages/core/src/runtime/**"
"sdk/packages/core/src/cline-core/**",
"sdk/packages/core/src/runtime/**"
],
"severity":"high"
},
@@ -22,8 +25,8 @@
"id":"sdk-no-raw-event-strings",
"rule":"All telemetry event name strings must be sourced from CORE_TELEMETRY_EVENTS in packages/core/src/services/telemetry/core-events.ts. If a PR introduces a string literal in a telemetry.capture(), telemetry.captureRequired(), or recordCounter()/recordHistogram()/recordGauge() call that does not reference CORE_TELEMETRY_EVENTS, flag it. New events must be added to CORE_TELEMETRY_EVENTS first, with a typed capture helper created alongside them.",
"scope":[
"packages/core/src/**",
"packages/agents/src/**",
"sdk/packages/core/src/**",
"sdk/packages/agents/src/**",
"apps/cli/src/**",
"apps/vscode/src/**"
],
@@ -32,13 +35,17 @@
{
"id":"sdk-auth-telemetry-completeness",
"rule":"Any new OAuth or authentication provider added under packages/core/src/auth must emit all four lifecycle events using the typed helpers from core-events.ts: captureAuthStarted (at flow entry), captureAuthSucceeded + identifyAccount (on token success), captureAuthFailed (on error), and captureAuthLoggedOut (on token invalidation or explicit logout). Flag PRs that introduce a new auth flow file without all four. Cross-reference packages/core/src/auth/cline.ts and packages/core/src/auth/codex.ts as canonical examples.",
"scope":["packages/core/src/auth/**"],
"scope":[
"sdk/packages/core/src/auth/**"
],
"severity":"high"
},
{
"id":"sdk-telemetry-doc-update",
"rule":"Any PR that adds new event constants to CORE_TELEMETRY_EVENTS in packages/core/src/services/telemetry/core-events.ts, adds new capture* helper functions, or changes the payload shape of an existing event must update the Event Catalog section in DOC.md. Flag PRs that modify core-events.ts without a corresponding change to DOC.md.",
"description":"Single source of truth for all telemetry event names (CORE_TELEMETRY_EVENTS) and their typed capture helper functions. Every PR touching telemetry must be evaluated against this catalog. New events must be defined here first."
"description":"OpenTelemetry-backed provider that wires logs/metrics/traces exporters. Contains createConfiguredTelemetryService and createConfiguredTelemetryHandle, the canonical factories every host should use."
},
{
@@ -21,11 +21,11 @@
"description":"Public API and event documentation. The Event Catalog and 'Activation funnel' sections must be kept in sync with core-events.ts. Host integration rules (CLI dir ordering, hub daemon metadata forwarding) are documented here."
},
{
"path":"ARCHITECTURE.md",
"path":"sdk/ARCHITECTURE.md",
"description":"Architecture reference. Telemetry design decisions, completion semantics (submit_and_exit anchoring), and hub-daemon telemetry forwarding are documented here. Use as ground truth for design intent."
},
{
"path":"AGENTS.md",
"path":"sdk/AGENTS.md",
"description":"Package boundary rules. Telemetry runtime services live in @cline/core; @cline/agents must not own stateful telemetry. Use to evaluate whether a telemetry change is being made in the correct package."
- Update VS Code extension dependencies to resolve security issues in `@xmldom/xmldom`, `basic-ftp`, `axios`, `undici`, and other direct/transitive packages.
Chat with your agent from any messaging platform: Telegram, Slack, Discord, Google Chat, WhatsApp, and Linear. Each conversation thread maps to an agent session with full context. Set up access control to restrict who can interact with your agent.
- Installed plugin wrappers are now named from their source (npm package name, git repo, remote filename, official slug, or local directory) instead of an opaque hash, making installed plugins easier to identify.
## 3.0.19
- Fixed CLI auto-update to use `npm update` so updates apply reliably, while preserving the installed release channel (e.g. nightly).
## 3.0.18
- Fix Slack channel mentions so replies post in the original message's thread.
- Fix the abort indicator to clear immediately when a task is cancelled.
- Sync the Fireworks AI model registry and refresh the bundled model catalog with current platform offerings.
- Bump the bundled SDK to v0.0.43, which forces a running Cline Hub to restart so it picks up the latest SDK code.
## 3.0.17
- Fix a regression introduced in 3.0.15 where the interactive CLI could get stuck after stopping and restarting Cline Hub and then pressing Escape to cancel a request. The CLI now detects stale or missing sessions, recovers any pending messages, and starts a fresh session instead of failing with "session not found".
- Fix Ctrl+C and Hub shutdown races that surfaced as "hook dispatch failed" and WebSocket connection errors from late hook events racing against Hub shutdown.
- Fix the Hub daemon being shut down prematurely when a runtime request was aborted, so the daemon now stays alive.
- Improve the Telegram connector with a new `--allowed-user-id` flag to restrict which Telegram users are authorized to interact with the agent.
## 3.0.16
- Install official Cline plugins by slug off the new github.com/cline/plugins collection.
- Uninstall plugins using `cline plugin uninstall <plugin>` or in the TUI.
- Plugins can now bundle skills, and plugin skills are grouped together in settings.
- Add Slack socket mode support.
- Allow a custom base URL for Anthropic vendor-type providers.
- Fix OAuth token migration for users signed in through the old extension.
- Use a union schema for read-files tool input validation.
- Add a `CLINE_PLUGIN_IMPORT_TIMEOUT_MS` env override to control the plugin import timeout.
## 3.0.15
- Add Cline Hub, a web app for monitoring connected clients, viewing and driving sessions, streaming assistant output, and restarting the local hub, with local, LAN, and tunnel usage gated by a room secret.
@@ -416,7 +416,7 @@ Then attach VS Code or Chrome DevTools to `ws://127.0.0.1:6499`.
## Publishing
The CLI is published as the `cline` wrapper package on npm with platform-specific binaries under `@cline/cli-*`. The release flow lives in the `publish-cli` skill (`sdk/apps/cli/.cline/skills/publish-cli/SKILL.md`).
The CLI is published as the `cline` wrapper package on npm with platform-specific binaries under `@cline/cli-*`. The release flow lives in the `publish-cli` skill (`.cline/skills/publish-cli/SKILL.md` at the repo root).
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Max Paulus 🥪