# Cline SDK Architecture

This document is the architecture source of truth for the Cline SDK repository. It describes how the system is organized, how components interact, and the design principles that guide development decisions.

**Who should read this?**
- SDK contributors working across multiple packages
- Developers building integrations or host applications using `@cline/core`
- Plugin authors understanding the runtime and extension systems

**What this covers:**
- Package boundaries and responsibilities
- Dependency direction and layering rules
- Runtime flows (local, hub-backed, remote-config managed)
- Design seams (repeated patterns instead of one-off integrations)
- Architectural constraints and why they exist

**What this is NOT:**
- An onboarding guide for new contributors (see README.md and CONTRIBUTING.md)
- A detailed API reference (see package READMEs and inline JSDoc)
- A user guide (see the main documentation)

## Layered Model

The workspace is organized as a layered runtime stack.

```mermaid
flowchart LR
  shared["@cline/shared"]
  llms["@cline/llms"]
  agents["@cline/agents"]
  core["@cline/core"]
  apps["Host Apps"]

  llms --> shared
  agents --> llms
  agents --> shared
  core --> agents
  core --> llms
  core --> shared
  apps --> core
```

## Package Responsibilities

### `@cline/shared`

Owns reusable low-level contracts and infrastructure:

- shared types and schemas
- path resolution
- hook contracts/engine
- extension registry contracts
- prompt and parsing helpers
- storage path helpers
- remote-config schemas, managed instruction materialization, telemetry normalization, and blob upload primitives

Design rule:

- `shared` should not depend on higher-level runtime packages.

### `@cline/llms`

Owns model/provider runtime concerns:

- provider settings/config resolution
- model catalogs and manifests
- shared gateway-style provider contracts
- handler creation via an internal gateway registry
- AI SDK-backed provider execution code

Design rule:

- provider-specific behavior should be isolated here, not spread across `core` or apps.
- AI SDK response `X-Request-ID` metadata travels on the existing model `finish`
  event into `afterModel.requestId`. It identifies the final surfaced step, not
  every hidden HTTP retry. Hosts can use existing model hooks for observations
  without wrapping transports or adding a request callback API.
  VS Code Git observations belong to the open conversation, not the SDK runtime:
  an `ended` event may leave the chat open after a failure. Startup cleanup handles
  unopened observers; explicit host stop/disposal closes both normal and restored
  observation windows. The observer binds to the actual ID returned by Core's
  start/restore result. VS Code starts interactively without a prompt and sends
  prompts only after that result. Start and restore explicitly prepare their own
  input and observer, so overlapping starts need no async-context bridge.
  Telemetry never supplies or changes `config.sessionId`: doing so would turn a
  new session into a restart. `afterModel` starts a bounded background Git read
  and emits with the triggering response's request ID when available, without
  waiting before tools execute. Each observer skips captures while a read is
  already in flight, avoiding queues and out-of-order emissions.
  Tools may change files during the read: this is state observed after response R,
  not an atomic pre-tool snapshot or proof of changes caused by R.
  Each window
  emits its first snapshot, then only changes to Git fields or workspace-root count.
  There are no opening, yield, or idle emissions or Git-extension watchers. Changes
  after the final model call require a later call to be observed. Consumers must
  carry observations forward within that window rather than expect an event per
  request. Repeated edits while already dirty need not change the recorded flags.
  Status limits preserve cheap identity reads as `partial`, without dirty flags.
  The field-level contract is `GitSnapshotProperties` in
  `packages/core/src/services/telemetry/core-events.ts`.

### `@cline/agents`

Owns the stateless runtime loop:

- agent iteration loop
- tool orchestration
- runtime event emission
- hook/extension execution
- turn preparation before provider calls
- in-memory team/runtime primitives

Design rule:

- `agents` should not own persistent storage or host lifecycle concerns.

### `@cline/core`

Owns stateful orchestration:

- runtime composition
- session lifecycle
- storage and persistence
- config watching/loading and watcher projections
- settings listing and mutation orchestration
- default host tool assembly
- plugin discovery/loading
- default context compaction policy
- telemetry integration
- hub server and scheduled-runtime services under `src/hub/`
- hub discovery, the detached hub daemon, and the `@cline/core/hub/daemon-entry` subpath
- host-side hub client adapters (`NodeHubClient`, `HubSessionClient`, `HubUIClient`, `connectToHub`) exported from `@cline/core/hub`
- the experimental cloud-session client exported from `@cline/core/cloud`: cloud API access, remote session lifecycle, and transcript reconciliation

Design rules:

- `core` is the app-facing orchestration layer over `agents`.
- `session/fork-metadata` owns fork ancestry and removal of inherited handoff markers; hosts retain title, transcript, and workspace-restore policies.
- `@cline/core/cloud` owns remote cloud-session state and emits immutable snapshots and events. Viewers hydrating active runs with `readMessages` reconcile canonical history at completion even if they missed the run start. Hosts supply authentication and project those snapshots into their UI; feature flags, account selection, and host persistence remain outside the controller. Importing this subpath does not initialize a local agent.
- `cloud/models` owns cloud model eligibility; `services/cloud-handoff` owns Git preflight, fingerprints, and transcript verification. Hosts own transfer orchestration, source locks, persistence, feature gating, and draft recovery.
- The cloud controller resumes suspended sessions and restores saved tasks.
- Desktop retains pending first-task creation options in a context-owned map across credential-driven controller replacement. The shared controller consumes that intent when an inner task exists or is created; retaining an ID without its approval policy is not sufficient.
- hub-related modules live under `packages/core/src/hub/`, grouped by service:
  - `client/` contains host-facing hub clients and browser connection helpers
  - `daemon/` contains detached daemon startup, entrypoint, and local runtime handler wiring
  - `discovery/` contains endpoint defaults, discovery records, and workspace owner resolution
  - `server/` contains WebSocket server startup, native/browser socket adapters, server transport, server helpers, and `handlers/` for hub command dispatch
- settings mutations belong in core services and hub commands, not in host-specific file writes. Hosts should call the core settings facade or the `settings.*` hub command family and react to `settings.changed`.

## Runtime Flows

### Local In-Process Runtime

1. Host constructs a `RuntimeHost` through `@cline/core`.
2. `@cline/core` selects `LocalRuntimeHost` through `packages/core/src/runtime/host.ts`.
3. Hosts normalize broad local config into `RuntimeSessionConfig` plus `localRuntime` overrides before calling `RuntimeHost.start(...)`.
4. `@cline/core` prepares a local bootstrap artifact from `localRuntime`, then builds the runtime from it.
5. `@cline/core` creates an `Agent` from `@cline/agents`.
6. `@cline/agents` runs the loop using `@cline/llms` handlers.
7. `@cline/core` persists state, artifacts, and metadata.

Completion telemetry is anchored to the assistant's explicit completion
declaration, not session shutdown. After each agent turn, the local
runtime inspects `AgentResult.toolCalls` and emits `task.completed` the
moment a successful `submit_and_exit` (the SDK analog of original
Cline's `attempt_completion`) is observed. A single teardown choke
point (`emitTaskCompletedOnTeardown(...)`) retains a fallback emission
for sessions whose final turn finished cleanly without an explicit
completion-tool observation (non-interactive runs not using the yolo
preset, or hosts that disable `submit_and_exit`). It is invoked from
every session exit path — both `shutdownSession(...)` and
`releaseSessionRuntime(...)` — so the emission never depends on which
teardown branch a stop routes through. Each session emits at most one
`task.completed`. See `DOC.md` for the event payload and `source`
field.

### Hub-Backed Runtime

The hub health endpoint includes its `hubId`. Restart callers compare this instance identity while waiting for shutdown, so a replacement started by reconnecting clients at the same address counts as retirement of the original hub. Desktop local activity is recorded only at its local hub observer subscription; cloud session projection does not write to that activity list.

1. Host constructs a `RuntimeHost` through `@cline/core`.
2. `@cline/core` selects `HubRuntimeHost` or `RemoteRuntimeHost` through `packages/core/src/runtime/host.ts`.
3. When no compatible local hub is already discovered, `@cline/core` can spawn a detached hub daemon and reconnect through discovery. The spawner waits up to 15s for the daemon to publish a usable discovery record (cold starts of the compiled binary on Windows regularly need more than the previous 8s). If the daemon still fails to come up, the runtime host's `No compatible hub runtime is available` error carries the underlying reason, and the daemon reports its own startup failure to telemetry (`hub.daemon.startup`) before exiting.
4. Hosts attach and detach from shared sessions without stopping the authority runtime, so another client can keep streaming or resume the same session later.
   One daemon serves every Cline client on the machine, and a hub-hosted session's telemetry carries only its own client (`clientName`/`clientVersion`), so the daemon also records *whose build started it*. The spawner stamps `CLINE_HUB_LAUNCHER_CLIENT`, `CLINE_HUB_LAUNCHER_VERSION`, and `CLINE_HUB_LAUNCHER_TRANSPORT` on the daemon environment (`withHubLauncherIdentity` in `@cline/shared`), defaulting to the spawning process's `ClineClientIdentity` and `local`. An embedding host that starts the hub through the CLI (the desktop app running `cline-cli hub ensure`) stamps itself first, and a stamp already present is kept as a whole, so the CLI that performs the spawn never records its own name or fills in its version next to the host's name. SSH remote hubs are stamped by the client over the `env` prefix of the remote `hub ensure` command with `transport=ssh`. The daemon claims the stamp out of its environment at startup (`claimHubLauncherIdentity`, same hazard as the daemon sentinel: hosted sessions spawn processes that inherit the environment, and a hub one of them starts must record itself) and publishes it with its build id and executable name as OTel resource attributes: `cline.hub.launcher.client`, `cline.hub.launcher.version`, `cline.hub.launcher.transport`, `cline.hub.build_id`, `cline.hub.runtime`. Collectors and Langfuse surface these as `resourceAttributes.*`, so a desktop session hosted by a CLI-started hub is attributable to that CLI build.
5. The hub-hosted runtime executes the agent loop using `@cline/agents` and `@cline/llms`.
6. `@cline/core` hub services broker sessions, events, approvals, schedules, and client-owned runtime capabilities such as session-local tool executors.
7. Hub event forwarding preserves structured streaming lifecycle boundaries: text/reasoning deltas, final text/reasoning completion, tool start/update/finish, and agent done events are translated across the hub transport so host UIs can reliably close loading/streaming state. `run.started` is emitted only after the target session is resolved and carries the originating command's `requestId` and `clientId`, allowing multi-client hosts to correlate delivery acknowledgments.
8. Hub client adapters exported from `@cline/core/hub` (`NodeHubClient`, `HubSessionClient`, `HubUIClient`, `connectToHub`) translate command/reply and event streams into host-facing APIs. Node clients register their version and PID together with caller metadata on every connection; `HubSessionClient` passes metadata through at registration so client events, refreshed lists, and reconnects retain the same details.
9. Hub `session.get` records include both canonical root-session usage and explicit aggregate usage from the hub-owned `RuntimeHost`, so attached clients can intentionally render either root-only or root-plus-teammate costs without replaying event streams.

Hub `session.send_input` accepts a nonblank prompt or at least one nonblank image/file
attachment; requests with neither are rejected before starting a turn.
NodeHubClient commands may supply a synchronous, local `beforeDispatch` guard.
It runs after connection setup, before allocating or sending the command, on
each attempt. Throwing prevents that attempt's dispatch; already-dispatched runs still require
`run.abort`.

Session status is reported, never fabricated. A session's initial status
reflects whether a turn actually runs inside `start(...)`: prompt-bearing
starts (one-shot or interactive) begin `running`, interactive starts without a
prompt begin `idle` until their first turn, and resumed sessions report their
persisted status. Each turn owns its `running` → `idle` transition. On the
client side, `HubRuntimeHost` projects a status event only when the hub
session record or the session snapshot actually carries one; snapshot-only
`session.updated` events (asynchronous persistence updates, which can trail a
turn's final idle update) report the snapshot's real status. Hosts that gate
workspace-wide operations on busy sessions (for example the desktop's
checkpoint-restore gate) depend on this: a defaulted `running` with no owning
turn leaves such gates blocked with nothing to clear them.

Command progress follows the same runtime event boundary as other agent output.
Shell executors emit structured stdout/stderr chunks through
`AgentToolContext.emitUpdate`; the agent runtime projects them as tool
`content_update` events, and the Hub publishes them as `tool.updated` with the
session, tool-call, and tool identifiers intact. Hub clients reconstruct the
tool update for their host-facing event stream. Client-contributed executors
must forward capability progress through this same path rather than creating a
host-specific side channel. The built-in shell executor coalesces output on a
short interval and bounds each stream's pending tail before it enters the event
pipeline; consumers independently coalesce and cap their rendered scrollback.

Proceed-while-running is an explicit command lifecycle, separate from client
or session detachment. A shell process advertises detachability only after it
has spawned and registered with the host-scoped command execution controller.
The client sends `run.proceed_while_running` with the owning `sessionId` and,
when available, `toolCallId`; the Hub delegates to the authoritative
`RuntimeHost`, which releases every matching registered process from the tool
call. The executor removes its abort and timeout ownership, resolves the tool
call with the current bounded output and a temporary log path, and continues
draining the process into that log. Detached logs are size-capped, retained for
a bounded inspection window after the command exits, and then their temporary
directories are removed. Every process that constructs a `LocalRuntimeHost`
starts one detached-log reconciliation: it reaps completed logs outside the
retention window, reschedules retained logs, and follows active detached-command
identities until they exit, so cleanup does not depend on timers from the process
that launched the command. Hub daemons and direct embedders therefore share the
same detachment and restart lifecycle instead of relying on a daemon-specific
entrypoint. Active-command markers pair the PID with a process-generation start
token, preventing an unrelated process that later reuses the PID from extending
the log lifetime. Completion markers distinguish a live, possibly silent command
from a completed log. Process probes distinguish an absent process from an
unavailable identity provider. Transient probe failures retain the active marker
and are never treated as evidence of command completion. Reconciliation keeps
the advertised log and retries until the provider can prove that the original
process still exists, its PID belongs to a replacement process, or the process
is absent. A host exit alone never starts the retention window for a surviving
command; the replacement host continues polling the process identity and begins
retention only after the command ends. During persistent provider unavailability,
the capped log may outlive the normal retention window because preserving a
potentially live command's advertised path takes precedence over guessing that
it exited. A detached client connection alone never changes process ownership or
command execution.

### Generated Media Operation and Event Flow

Model modalities and provider operations are separate facts. Modalities describe
values a model accepts or produces; the explicit operation selects the provider
transport. Language models keep the normal agent loop even when they can emit
media, while `operation: "image-generation"` selects `generateImage` and
`operation: "transcription"` selects a declared speech-to-text transport.
Operation-specific execution variants such as recorded and realtime
transcription live in `operationModes`, not in the generic capability list.
Specialized operations fail closed unless the provider manifest and adapter
both implement them, so an OpenAI-compatible chat endpoint never implies an
image, audio, transcription, or video endpoint.

Generated media crosses package boundaries as follows:

1. `@cline/llms` validates provider output once and creates canonical
   `GeneratedMedia` values. The contract carries a stable ID, modality, MIME type,
   and a discriminated base64, HTTP(S), or artifact source. Current producers emit
   images; audio, video, and large artifact-backed files use the same contract.
2. Provider model tools are adapters, not raw AI SDK tools. An adapter owns its
   native result projection into canonical media. The generic stream layer
   coalesces preliminary or repeated results, enforces the per-turn media budget,
   and persists only a compact activity summary rather than duplicating base64 in
   model-tool metadata.
3. `@cline/agents` appends media events at their exact stream position in the
   assistant message. That message is the canonical replay and persistence source;
   observational provider-tool activity remains display-only metadata.
4. `@cline/core` projects live media as `content_end(media)`. The hub publishes
   `assistant.media`, preserving the same media ID, and clients deduplicate live
   and hydrated content by that ID.
5. Web clients share `GeneratedMediaContent` from `@cline/ui` for image, audio,
   video, file, and unavailable-source rendering. Inline bytes are exposed only
   through short-lived browser-owned object URLs; remote and artifact sources
   require a client-owned trusted resolver. CLI and ACP clients provide
   transport-appropriate materialization or fallback output without changing
   the canonical message.

Image-edit inference is intentionally local: when a dedicated image model accepts
image input and the current user message has no explicit image, only an image on
the immediately preceding assistant message is reused. Older images are not
implicitly attached across intervening turns.

Session history provenance keeps the client surface and initiation mode separate.
`StartSessionInput.source` identifies the client (`vscode`, `desktop`, `cli`,
`core`, and so on), while top-level `StartSessionInput.mode` identifies how the
session began (`user`, `automation`, `subagent`, or `team`). The persisted messages
envelope records both values, along with client version and child-session
lineage. Missing initiation mode defaults to `user`; automation runtime adapters
must pass `mode: "automation"` explicitly.

Root-session persistence is lazy. Starting a runtime allocates its session ID
and keeps configuration or seeded history in memory, but does not create a
database row, manifest, or messages artifact. The first accepted user turn
persists that same ID and its artifacts. Closing a runtime before a user turn
therefore leaves no empty history entry, and persistence code never allocates a
replacement ID for an unknown session.

Session history listing filters child rows at the persistence layer. Subagent
and team-task sessions are stored in the same table as the roots that spawned
them and always sort newer, so `listSessionHistory` asks the runtime host for
`rootOnly` rows. `LocalRuntimeHost` passes the option to the session backend,
which applies it in the query before the limit; `HubRuntimeHost` sends it as
`session.list { limit, rootOnly }` and the hub handler forwards it to its
session host. Omitting the flag returns every row, which is what callers that
render subagent trees rely on. History keeps a client-side root filter with a
widening scan only as a fallback for older hubs that ignore the flag.

Workspace bootstrap is owned by the runtime that executes the session. Hub
clients preserve an omitted `cwd` and `workspaceRoot` across the transport so
the hub-side execution host can place the session in the shared chat
workspace on its own filesystem at
`<cline-data-dir>/workspaces/chat` (by default
`~/.cline/data/workspaces/chat`). The chat workspace is seeded with an
`AGENTS.md` rules file that tells the agent to treat the session as a chat
and to create a named project folder only when the user asks for one.
The resolved paths are returned in the session snapshot and are the source of
truth for client-side manifests; transport clients must not invent a local path
for a remote runtime.

Detached daemon startup retries transient `ETXTBSY` spawn failures before
polling discovery. This covers package-manager updates that replace the CLI
binary immediately before a command restarts the shared hub.

Local hub discovery also carries the authentication contract for the shared
daemon. On startup, the hub server generates a cryptographically random
per-process auth token, stores it in the owner discovery record, and writes that
record with owner-only file permissions. Local clients resolve the token from
the discovery file at connection time rather than embedding it in endpoint URLs.
The server validates the token with a constant-time comparison before accepting
`/hub` WebSocket upgrades or `/shutdown` requests; WebSocket clients send it via
the `Sec-WebSocket-Protocol` header and shutdown requests use an
`Authorization: Bearer` header. Unauthenticated local processes can still probe
public health/build metadata, but they cannot attach to sessions, issue
commands, or stop the daemon.

Remote proxies that authenticate the client-facing WebSocket upgrade with HTTP
headers use `NodeHubClient.resolveConnectionHeaders`. The resolver runs for every
new socket, including reconnects, so hosts can refresh short-lived credentials.
Header authentication is mutually exclusive with the local hub-token subprotocol;
the proxy is responsible for authenticating the client and adding any private
upstream hub credentials. Resolver failures and rejected protocol headers fail the
connection and remain available through the client's connection-error state.
Clients with active subscriptions keep retrying after header-resolution failures,
even when no socket was created.

Local hub rediscovery is limited to managed shared-daemon endpoints obtained
through discovery or `ensure*HubServer(...)` startup paths. Managed local hubs
must match both the supported wire protocol and the current Hub build identity;
a protocol-compatible daemon from another build is retired before its
replacement starts so upgrades cannot keep executing stale runtime code. SDK
builds embed a deterministic fingerprint of the runtime sources, package
manifests, build configuration, and dependency lock, so the identity changes
with the executable Hub code even before package versions are bumped. Builds
also embed a build epoch that orders them in time: when the fingerprints
differ, a managed Hub produced *after* the client's own build is reused over
the compatible wire protocol instead of being retired (replacing it would
downgrade the daemon), and the client's build-mismatch watcher prompts the
user to update and restart. Hubs that are older, unordered, or missing build
metadata are retired and replaced as before, so two concurrently running
installations converge on the newest build instead of repeatedly replacing
each other's daemons.
Explicit endpoints, including loopback URLs such as
`ws://127.0.0.1:<port>/hub`, are sticky exact targets and remain protocol-only:
reconnects may retry the same socket URL, but command recovery and
startup-deadlock recovery must not replace them with the workspace-discovered
hub. This keeps custom local hubs and remote hubs from silently drifting to a
different process.

### Interactive CLI Startup

1. `apps/cli` owns OpenTUI startup and must render the first frame without waiting for detached hub startup.
2. Interactive sessions use `backendMode: "auto"` so an already-compatible hub can be reused immediately, while a missing hub is only prewarmed in the background and the TUI falls back to a local runtime for responsiveness.
3. Hub-required flows such as `cline hub`, schedules, connectors, and `--zen` may still call the explicit ensure path because those commands require a live hub before proceeding.
4. Resume hydration is deferred until after `renderOpenTui()` so loading previous messages cannot block initial TUI paint.
5. Any future CLI/TUI startup work should follow the same rule: daemon startup, discovery polling, provider catalog refreshes, file indexing, and resume reads must be background or user-action gated unless a command explicitly requires their result before output.

### Temporary external tool result recovery

Cache admission sizes the persisted result using the same JSON/string preview representation as `MessageBuilder`, ensuring every result truncated by the per-result limit is eligible for recovery. Native images are separated from structured preview text and excluded from the recovery copy. Plain strings remain unchanged, while structured cached text uses YAML with literal multiline blocks and no automatic line wrapping. YAML size controls the cache byte limit, not the truncation threshold. This preserves MCP payload line breaks instead of escaping them into a single JSON line. Recovery requires an available `read_files` tool and uses its existing output and per-line limits. Disabling the reader does not disable caching or remove notices.

MCP and Composio tools declare `resultPolicy: "cache-oversized"` at registration; custom tools may opt in. After result-transforming hooks finish, Core caches oversized output in a session-owned `ToolResultCache` while retaining original output in conversation history and tool events. The existing synchronous `MessageBuilder.buildForApi` produces bounded previews and model-only recovery instructions, preserving native images. Other tools keep their existing projection behavior. No disk cache or asynchronous recovery builder is involved.

Recovery URIs have the form `cline://cache/<encoded-session-id>/<unique-result-id>.result.txt`. Core injects the owning cache into the runtime tool context. The built-in file reader resolves these URIs before filesystem handling and uses the same bounded line reader, inclusive ranges, output caps, and abort handling as ordinary text files. URIs are restricted to the owning session; shell commands and filesystem search do not resolve them.

Entries expire after five additional model iterations without an explicit cache read. A session-level counter spans follow-up turns; including a URI in a model request does not refresh it. Reads refresh both the iteration age and least-recently-used order. Cached text is limited to 16 MiB of UTF-8 bytes per session, evicting the least recently read entry first; individually larger results receive a preview without a URI. Shutdown, history reset, and restore clear the cache. Resume and copied sessions do not rehydrate it from history. Missing entries return an explicit refetch instruction through `read_files`, without automatically repeating tools or side effects.

Cache eviction releases cache-owned text only; original output remains under ordinary history retention. URI references survive eviction so earlier model-facing recovery notices remain unchanged. Cache-miss feedback is emitted only by an attempted read. Generated recovery instructions reserve at most half the aggregate model text budget; instructions that cannot fit are omitted. Tool-returned metadata cannot grant recovery-instruction status.

### Connector Persistence and Recovery

1. `@cline/shared/db` owns the low-level SQLite connector store and the one-time legacy JSON import.
2. Dashboard configuration and CLI connection state are recorded separately. Configuration edits replace only dashboard-owned connector and security flags in stored reconnect arguments, preserving CLI-only runtime options, and refresh arguments only for connectors that have previously started successfully.
3. `@cline/core` owns connector autostart persistence and reconnect orchestration. The detached hub daemon is the sole startup reconnect owner, preventing dashboard startup from racing it and launching duplicate processes.
4. Detached connector starts are persisted only after a child process is created. Internal detached children preserve that state when they exit, while a clean user-interactive exit disables autostart.
5. CLI and dashboard hosts pass their connector CLI launch specification through the detached process environment. The package-owned daemon entrypoint uses that specification to start connector reconnect wrappers without importing application code.
6. The detached hub entrypoint exposes `hubDaemonReady`, which resolves only after the WebSocket server is listening. It begins reconnect attempts after signaling readiness, and reconnect failures remain best-effort rather than taking down the hub.

### Remote-Config Managed Runtime

1. A host or core wrapper fetches a normalized `RemoteConfigBundle`.
2. `@cline/shared/remote-config` caches the bundle when configured.
3. Shared remote-config materializes managed rules/workflows/skills under workspace-local `.cline/<plugin>/`.
4. Shared remote-config derives generic OpenTelemetry config and session blob upload metadata from the bundle.
5. `@cline/core` exposes the app-facing integration wrapper that applies extensions, telemetry, and session metadata to `StartSessionInput`.
6. `@cline/core` consumes the prepared local overrides during local bootstrap.

This keeps reusable remote-config behavior in `shared` while the session-specific bridge remains in `core`.

## Design Seams

The codebase relies on a few repeated seams instead of one-off integration paths.

### 1. Config Watchers

Core uses file-based discovery and watchers for:

- rules
- workflows
- skills
- agents
- hooks
- plugins

Design implication:

- new instruction sources should usually materialize into files and reuse watcher-based loading instead of inventing parallel in-memory execution paths.
- in `packages/core`, config-facing discovery, parsing, watching, and slash-command projection live under `src/extensions/config`

### 2. Runtime Builder Inputs

`DefaultRuntimeBuilder` composes a runtime from generic inputs:

- tools
- hooks
- extensions
- user instruction watcher
- telemetry

Design implication:

- higher-level integrations should prefer feeding those seams rather than patching agent internals directly.
- the local runtime bootstrap lives in `packages/core/src/services/local-runtime-bootstrap.ts` and feeds the builder rather than bypassing it

### 3. Runtime Host Boundary

Core exposes one shared execution boundary: `RuntimeHost`.

Concrete implementations:

- `LocalRuntimeHost` for in-process execution
- `HubRuntimeHost` for shared local hub execution
- `RemoteRuntimeHost` for explicit remote hub endpoints

Design implication:

- host selection happens in `packages/core/src/runtime/host.ts`
- `ClineCore` delegates uniformly to `RuntimeHost` and does not branch on local vs hub behavior
- transport-specific translation belongs inside concrete hosts, not in top-level orchestration
- `RuntimeHost` inputs stay transport-safe, while `ClineCore.start(...)` is the app-facing facade that normalizes broad local config before delegation
- `RuntimeSessionConfig` is transport-neutral across local, shared hub, and remote hub modes; host-local bootstrap concerns stay under `localRuntime`
- client-local runtime behaviors that must survive hub mode, such as `defaultToolExecutors`, are attached at session start and proxied through hub capability requests instead of changing host selection
- pending prompt list/update/delete are exposed through the grouped
  `ClineCore.pendingPrompts` service. Usage summary lookup and active-session
  model switching are also service-style capabilities exposed through
  `ClineCore` when the concrete transport implements them. These service APIs
  are intentionally outside the minimal `RuntimeHost` primitive vocabulary.
- `session.abort` remains the cancellation boundary for a root session in both
  local and hub-backed execution. The owning `LocalRuntimeHost` aborts the lead
  agent and asks only that session's team runtime to cancel active synchronous
  teammate work plus running or queued async runs. Teammate definitions and
	conversation state remain available for later turns; idle and unrelated team
	runtimes are not stopped. One-off `spawn_agent` delegations observe the parent
	turn's abort signal through their `SessionRuntime`. The team runtime marks
	intentional abort task-end events as cancelled so persistence does not record
	them as failures.
- The usage service's `getAccumulatedUsage(sessionId)` method returns a summary
  with two explicit buckets: `usage` for the root/lead agent and
  `aggregateUsage` for root plus teammates/subagents. Local execution tracks
  root usage and teammate usage as separate buckets, then derives aggregate
  totals from those buckets while telemetry remains scoped to the primary
  lead/root agent.
- Usage events report non-reasoning `outputTokens` and a separate optional
  `reasoningTokenCount` delta. `RuntimeEventAdapter` derives both deltas from
  cumulative runtime usage; the hub's `usage.updated.delta` payload preserves
  them when `HubRuntimeHost` reconstructs the event. `task.tokens` telemetry
  likewise reports reasoning separately from `tokensOut`. Provider billing
  still includes reasoning tokens at the output rate.

### 4. Settings Mutation Boundary

Core owns settings snapshots and mutations through `packages/core/src/settings`.
The hub exposes the same path through `settings.list` and `settings.toggle`.

Design implication:

- hosts should not mutate skill, tool, MCP, provider, or other settings files directly
- domain-specific persistence helpers, such as skill markdown frontmatter writes, stay internal to the owning settings provider/service
- successful hub-backed mutations return an updated settings snapshot and publish `settings.changed` with the changed settings types
- CLI settings surfaces may keep local snapshot rendering for startup responsiveness, but mutation flow must refresh the relevant watcher before reloading UI data

### 5. Session Startup Bootstrap

`ClineCore.create(...)` exposes a generic `prepare(input)` hook.

Design implication:

- higher-level packages can prepare workspace-scoped runtime state before a session starts
- core stays unaware of enterprise-specific contracts
- cleanup stays at the host boundary rather than inside the agent loop

### 6. Logging

Cross-package logging uses a small injected interface exported from `@cline/shared`:

- **`BasicLogger`** — required `debug` and `log`; optional `error`. Hosts map these to their backend (Pino, VS Code `OutputChannel`, etc.). Many runtime options take `logger?: BasicLogger`; when omitted, components skip logging or use `noopBasicLogger` where a full object is required.
- **`BasicLogMetadata`** — optional structured fields (`sessionId`, `runId`, `providerId`, `toolName`, `durationMs`, …) plus `severity` on `log` when a single method must represent both informational and warning-style messages (for example the CLI Pino bridge maps `severity: "warn"` to Pino `warn`).

Naming clarity:

- **`CliLoggerAdapter` (CLI)** — a **host bundle**: holds the raw `pino` logger (for file paths, rotation, and CLI-only concerns) and exposes `.core: BasicLogger` for anything that consumes the SDK contract. It is not an `ITelemetryAdapter`.
- **`TelemetryLoggerSink` (`@cline/core`)** — an **`ITelemetryAdapter`** that mirrors telemetry events and metrics into a `BasicLogger`. It is a telemetry sink, not a host logging implementation.

The agent and other call sites route former `info` / `warn` semantics through `log` (warnings include `severity: "warn"` in metadata). Errors prefer `error` when implemented; otherwise `log` with `severity: "error"` is used as a fallback.

Design implication:

- logging is injectable and transport-agnostic, allowing host environments (CLI, VS Code, browser) to wire their own backends
- do not hardcode logging calls; accept a `logger?: BasicLogger` parameter instead

### 6.1 Langfuse telemetry ownership

`@cline/llms` owns Langfuse instrumentation, trace attribute propagation, and
the `LangfuseAttributesSpanProcessor`. `@cline/core` owns the host OpenTelemetry
provider and installs that processor when constructing an OTLP trace pipeline.
The processor copies context attributes onto `cline-provider-langfuse` spans;
it does not create an exporter or require Langfuse credentials. User and session
IDs must be span attributes, not only observation metadata, for Langfuse tracking.

In the collector relay path, spans use the existing host OTLP exporter. The
collector owns Langfuse credentials and downstream filtering and sampling.
The relay exists only when the host registered a traces exporter, which release
builds inline at build time (`OTEL_TRACES_EXPORTER`, `CLINE_TRACE_*`) into the
CLI, the extension, and the desktop backend and its bundled CLI; a packaged
app has no runtime environment to read them from. The `--telemetry-selfcheck`
report includes `traces_exporter` so publish workflows can gate on it.
`llms` checks provider eligibility, client sampling, opt-out, and content policy
per request. The host owns flushing and shutting down its provider.

When no host relay is available, explicitly configured direct Langfuse export
uses an isolated provider owned and disposed by `llms`. It does not replace or
shut down an ambient host provider. When both routes are configured, the relay
takes precedence so a request is not exported through both routes.

Each issued agent model request gets a `modelRequestId`, shared by request-start
and stream lifecycle events, provider error logs, and AI SDK runtime context.
Transport retries within one AI SDK call share that ID; a new agent request gets
a new ID, even within the same run and iteration. Provider errors also include
run, agent, session, and conversation IDs when available. The AI SDK `callId`
is recorded separately as `aiSdkCallId` on errors.

Terminal stream failures notify both application error reporting and tracing
integrations. Native timeout aborts are failures; explicit caller cancellation
does not emit a provider `sdk.error`. AI SDK stream recovery permits three retries
per model step. Recovered attempts do not produce terminal `sdk.error` reports or
mark the operation as failed. Exhausted stream recovery disables the agent's
whole-turn retry so the two retry budgets do not multiply. Previously streamed
text and reasoning follow AI SDK's append semantics and may repeat on recovery.

### 7. Storage Adapters

Stateful persistence should be isolated behind adapter/service layers.

Design implication:

- file-backed, SQLite-backed, RPC-backed, and enterprise-specific persistence should share service logic where possible and isolate backend differences in adapters.

### 8. Extension and Hook System

Extensibility is split deliberately:

- extensions register runtime contributions
- hooks intercept lifecycle stages

Design implication:

- additive runtime behavior should usually enter through these extension points instead of bespoke special-case host code.

### 9. Context Compaction

Context compaction is owned by `core`.

- `@cline/agents` owns the generic turn-preparation seam:
  - run normal lifecycle hooks
  - allow hosts to project message history or system prompt before the provider call
  - keep its canonical runtime transcript append-only when a projection is returned
- `@cline/core` owns compaction policy:
  - inject a prepare-turn pipeline for root sessions
  - choose between built-in strategies through a registry map
  - persist the latest compacted working context as a session compaction artifact
  - keep compaction logic out of the low-level agent message builder

Design implications:

- compaction is a context-pipeline concern owned by `core`
- canonical session history lives in the session messages artifact at full fidelity; compaction state lives separately in `${sessionId}.compaction.json`
- resume loads the canonical transcript for history/debugging and, when present, reuses the latest compaction state only after validating a hash of the canonical prefix covered by that state; valid state is projected by appending canonical messages written after the compaction boundary
- sessions that were already persisted with compacted messages before this model are best-effort only because the omitted original transcript is not recoverable from the compacted artifact
- a session imported from another coding agent (`metadata.importedFrom`) that is resumed without compaction state summarizes its whole foreign transcript on the first turn, regardless of the auto-compaction setting; the summary persists as normal compaction state, so the model never replays the source agent's tool calls while the canonical transcript stays intact
- `agents` stays focused on the stateless loop and provider/tool orchestration
- delegated/subagent flows should inherit compaction behavior through core session config, not through a separate agent-level compaction hook surface

### 10. Extension Layering Inside Core

`packages/core/src/extensions` is split by concern:

- `extensions/config`: config loaders, parsers, watchers, and watcher projections such as runtime slash-command expansion
- `extensions/plugin`: runtime plugin discovery, loading, the plugin registry, the worker/subprocess sandbox transports, and their shared bootstrap
- `extensions/context`: core-owned context/message pipeline concerns such as compaction

Design implications:

- avoid mixing config discovery code into runtime/plugin code
- avoid creating thin runtime wrapper files when a helper is fundamentally projecting watcher state

#### Plugin execution

Plugin code never runs on a host's main thread. Every plugin a session uses
goes through one `PluginRegistry` per process (`getProcessPluginRegistry()`,
`extensions/plugin/plugin-registry.ts`). The registry owns status, failure
counting, timeouts, the session policy, and reload; the execution mode
(`CLINE_PLUGIN_MODE`, `resolvePluginExecutionMode`) only decides which
isolated transport a session's copy of a plugin runs in:

- `worker` (default): each plugin runs in its own worker thread per session
  (`WorkerSandbox`), so the host never imports plugin code. The copy the
  registry wraps is a proxy whose calls go to the worker over the sandbox RPC
  protocol (`plugin-sandbox.ts` / `plugin-sandbox-bootstrap.ts`). One worker
  per plugin means a worker that dies on its own (uncaught error, unhandled
  rejection, `process.exit()`) is attributed to that plugin with no stack
  inspection: the registry records an `uncaught` failure and turns the plugin
  off, and the host and other plugins keep running. A call that times out
  terminates its worker, which stops synchronous loops; the next call starts a
  fresh worker. Released copies end their worker, which stops everything the
  plugin started.
- `sandbox`: the previous per-session `node`/`bun` subprocess. It bypasses the
  registry (no status, policy, or reload) and is kept as an escape hatch.

Plugins written for the per-session sandbox keep state at module level, often
one plugin object per import that refuses a second `setup()`, so both modes
give each session its own copy. The session bootstrap, plugin tool listing
(`listPluginToolsWithDiagnostics`), plugin MCP settings sync, and plugin slash
commands all load through the registry, so they see the same mode. Worker mode
starts no child process, so plugins work in the compiled CLI, the Hub it
starts, the desktop app, the SSH remote host, and VS Code/Electron without a
runtime on `PATH`, and plugins can use the host runtime's globals (`Bun` under
the Bun-built Hub, including inside a Bun worker).

In the Hub daemon the registry is Hub-owned: the daemon checks global and
workspace plugins at startup in throwaway workers so status is known before
any session exists.

Each session gets its own guarded view of the plugins it enabled:

- `StartSessionInput.plugins` (`session.create` payload `plugins`) is shaped
  like `toolPolicies`: `"*"` sets the default and named entries override it.
  Plugins are enabled unless a policy turns them off. Tools, hooks, rules, and
  providers come only from enabled plugins; plugin tools still go through
  `toolPolicies`.
- `setup()` runs once per session with a context that carries the session's
  `cwd`, `session.sessionId`, and `emitEvent`. Plugin tools also receive `cwd`
  and `emitEvent` in their call context. `globalThis.__clinePluginHost.emitEvent`
  remains as a shim for sandbox-era plugins and routes to the calling session
  through async context.
- Every import (4 s), setup (4 s), hook (3 s), and tool, command, rule
  content, and message-builder call (60 s, or a tool's own `timeoutMs`) is
  wrapped with a timeout and error capture. `resolveAndLoadAgentPlugins`
  overrides (`importTimeoutMs`, `hookTimeoutMs`, `contributionTimeoutMs`)
  apply per session. A failing tool or command throws its error back to the
  caller. A failing hook follows `hookErrorMode` (`"ignore"` by default;
  `"throw"` rethrows). A failing rule contributes no text, and a failing
  message builder leaves the messages unchanged. Calls into a copy that is
  turned off, whose setup failed, or whose session ended are refused.
- Registrations are buffered (and capability-checked) during setup, so a
  setup that throws contributes nothing. If the host rejects a registration
  while committing, the copy's setup is recorded as failed and the error is
  rethrown so the contribution registry discards what was already committed.
- Each copy owns its cleanup. `ctx.onDispose(fn)` registers cleanup that runs
  when the session releases the copy (session stop, dispose, or a failed
  start). Plugins must stop everything they start for a session there: timers,
  child processes, sockets, listeners on shared emitters. The host does not
  track or cancel them.

The registry tracks one status per plugin: `loading`, `ready`, `degraded`,
`failed`, or `disabled`. It records the last error with its phase (`discover`,
`import`, `setup`, `dispose`, `hook:<name>`, `tool:<name>`, `command:<name>`,
`rule:<id>`, `messageBuilder:<name>`, or `uncaught`), message, stack, plugin
path, timestamp, and session, plus error and timeout counts.

Plugins are bound to a session when it starts. A plugin that is added,
changed, or reloaded reaches only sessions started afterwards; a running
session keeps the plugins, and the plugin code, it started with, even if its
`setup()` first runs on a later turn. Restarting a session (a CLI mode switch,
resuming it, or the Hub rebuilding a missing session) is a new start and gets
the current plugins. A change is detected by a content fingerprint of the
plugin's entry file and every file it reaches through relative static imports
(`fingerprintPluginSources`), so edits outside the entry file count too.
Files reached only through dynamic imports, `require()` of computed paths, or
`node_modules` are not fingerprinted; after changing those, use
`plugins.reload`.

Failures are counted per plugin. Import failures, discovery failures, an
attributed uncaught error, and five consecutive call failures turn the
plugin off for every session using it; a re-import (`plugins.reload` or a
fingerprint change) starts over with a clean slate. Running sessions keep
the copy they set up, which stays callable unless the plugin is turned off
(a broken reload fails closed for them too). Each copy is stamped with the
import it came from; a failure in a copy from before a re-import is reported
to its own session but does not count against, or change the status of, the
current module. A `setup()` failure is per
session: that session loses its copy (no tools or hooks), the status shows
`failed` with the error, only that session is told, other sessions keep
their working copies, and the next session tries setup again; a successful
setup returns the status to `ready`.

Status is surfaced, never only logged:

- `plugins.list` / `plugins.status` return each plugin's status, last error,
  and the sessions using it; `plugins.reload` re-imports one plugin by name or
  path without restarting the Hub. `cline hub plugins [--reload <plugin>]`
  wraps these.
- The Hub broadcasts `plugin.status_changed` to attached clients.
- `session.create` replies and `session.created` events carry `pluginIssues`
  for plugins the session asked for but does not have: failed, disabled in
  settings (`reason: "settings"`), or turned off by the session's policy
  (`reason: "session_policy"`).
  `StartSessionResult.pluginIssues` exposes the same list to SDK hosts.
- Because `setup()` and hooks run on the first turn, after the start reply,
  later degraded/failed transitions reach each affected session as a status
  notice (`AgentNoticeEvent` with `metadata.pluginIssue`).
- Registry logs are structured lines with `pluginName`, `phase`, and
  `sessionId`; in the Hub they go through `logHubMessage`.
- Settings listings (`listPluginToolsWithDiagnostics`, `CoreSettingsService`)
  report failed plugins with their state and `loadError`. Their inspection
  cache is keyed on each plugin's registry status, so a plugin a running
  session turned off is never answered from an earlier clean inspection.

Because no plugin code runs on the daemon's thread, its `uncaughtException` /
`unhandledRejection` handlers treat every error as the daemon's own and go to
`shutdownFatal`; there is no stack attribution to plugins.

#### Worker and subprocess transports

Both transports share one RPC protocol and one bootstrap
(`plugin-sandbox-bootstrap.ts`). After SDK compilation, Core builds
`dist/plugin-runtime/`, containing the self-contained bootstrap and the complete
SDK import graph under `node_modules/@cline`. Package exports come from the SDK
manifests, including browser subpaths. Hosts ship this directory as one artifact:

- `WorkerSandbox` (worker mode): structured clone over the worker's message
  port. A worker must not `chdir` (Bun would change the host's cwd), so the
  bootstrap overrides `process.cwd()` inside the worker. The bootstrap posts
  `ready` once it listens, and the host queues calls (as clones) until then,
  because Bun drops messages that arrive earlier. Plugin stdout is discarded
  inside the worker, since Bun workers write straight to the host's stdout.
  Workers share the host's memory limit, env snapshot, and native addons:
  crash isolation, not a security boundary.
- `SubprocessSandbox` (sandbox mode): JSON IPC to a `node`/`bun` child with
  stdout ignored.

Core resolves the complete artifact through `CLINE_PLUGIN_RUNTIME_DIR`, a
package-local `plugin-runtime` directory, or embedded resources. Source hosts
prefer their sibling TypeScript bootstrap over packaged runtimes so development
and tests execute the current bootstrap and module importer without rebuilding.
The CLI compiler embeds the runtime tree and dashboard assets in Bun's read-only
filesystem. Worker and subprocess transports read the same embedded bootstrap
and SDK exports without extracting files or creating a runtime cache.
VS Code and npm CLI copy the complete artifact into their bundles. Desktop
ships it beside its external backend script, whose plain Bun host does not
mount the CLI's filesystem.
A host without a bootstrap fails closed with
`PluginBootstrapMissingError`; plugin code never runs on the host main thread.

Compiled hosts register their subprocess entrypoint with `setPluginSandboxLauncher`.
The CLI and Desktop’s bundled CLI use the internal `--plugin-sandbox` flag,
which lazily imports the embedded bootstrap with bunfs mounted and compiled
runtime flags (including system CA trust) intact. Generic script sandboxes
still use plain Bun mode when reusing a compiled runtime.


`LocalRuntimeHost.pluginCommands` owns plugin command discovery and execution,
exposed to clients through Hub RPC (`plugins.commands.list` /
`plugins.commands.run`). The desktop sidecar, CLI, and connectors reuse their
existing runtime connections and do not load plugins themselves. Plugin command
execution can recover a connection before dispatch, but never resends a
dispatched action whose reply was lost.

A resident session lists and executes commands from its own contribution
registry, retaining the plugin instance and context shared with its hooks.
Session registrations keep their session lifetime. Without a resident session,
the runtime uses a per-workspace catalog. Each request fingerprints the enabled
discoverable plugin entries and their imported source graph, and reloads the
catalog when that changes; other settings, setup logs, and state files beside a
plugin do not. Each load uses its own `PluginRegistry`, so a catalog import
failure cannot block a resident session's copy of the same plugin, and the
retry re-imports it. A failed load keeps healthy commands, reports
`status: "error"`, and is retried by a request after 30 seconds. Catalogs idle for 10 minutes release
their workers. Reload, eviction, and disposal wait for running handlers. Clients
re-list to stay current (for example when a slash menu opens or the active
session changes); there is no catalog push event.

The shared command executor records `task.tool_used` once per matched handler,
including failures, for both direct runtime and Hub calls. Telemetry failures
cannot replace a command's result or original error. Hub status and replacement
checks count active command requests even without a chat participant; draining
refuses new catalog and command requests. CLI and desktop fallbacks treat a
failed catalog read as "not a plugin command" so skills and workflows still
work, while errors from a listed plugin's handler remain visible.

Sandboxed plugin subprocesses and workers are session-local but lazily recreatable. Core
reclaims a sandbox after 30 minutes without an in-flight RPC call (configurable
through `PluginSandboxOptions.idleTimeoutMs` or
`CLINE_PLUGIN_IDLE_TIMEOUT_MS`), and the next plugin call starts and
reinitializes it transparently. Pending requests are associated with the child
generation that owns them so an old process exiting cannot reject work sent to
its replacement. The bootstrap also exits when its parent IPC channel
disconnects. The parent is the single authority for idle shutdown so competing
deadlines cannot terminate a child while the parent is dispatching new work.

Design implications:

- worker and subprocess counts scale with recently active sessions (workers:
  sessions × plugins), not every session observed since hub startup
- eviction never interrupts an in-flight plugin call
- sandboxed plugin state is ephemeral across idle eviction; durable plugin
  state belongs in persistent storage
- a sandbox must never outlive its owning hub process

## Architectural Constraints

### Keep `agents` Stateless

Do not move these concerns into `@cline/agents`:

- session persistence
- provider settings storage
- RPC lifecycle
- host-specific approvals
- remote-config policy caching

### Keep `core` Generic

Do not make `@cline/core` organization- or provider-specific.

If a capability is truly generic and app-facing, add a generic core seam. Reusable remote-config parsing, materialization, and upload primitives belong in `@cline/shared/remote-config`.

### Use One-Way Optional Layers

Optional higher-level integrations may depend on lower layers.
Lower layers should not depend on optional feature packages.

For remote config, that means shared owns the reusable bundle/materialization/blob primitives and core owns only the session-oriented wrapper exported to apps.

## Hub-Owned Agenda Task Queue

Agenda tasks are durable proposals for future work. They are intentionally
separate from cron specs, queued prompts inside an existing session, and the
agent-team task board. Shared, browser-safe contracts use `AgendaTaskRecord`
and `AgendaTaskRunRecord`; orchestration and persistence remain in
`@cline/core`.

> **Status:** the agent-facing `kind: "todo"` half of the `tasks` tool and the
> desktop Agenda UI are temporarily disabled while the Agenda UX is reworked
> (`AGENDA_TODO_TOOL_ENABLED` in `hub-server-transport.ts` and
> `AGENDA_UI_ENABLED` in the desktop webview). While the flag is off the Hub
> also skips the agenda spec-file watchers — nothing consumes watcher-driven
> task events, and `task.*` commands reconcile spec files on demand. The
> backend described below — the manager, storage, `task.*` Hub commands, and
> desktop plumbing — stays fully wired, and the schedule kind remains active.

### Authority and persistence

- A Hub process owns one Agenda task manager. Its
  `AgendaTaskManagerApi` boundary is the only place allowed to change task
  lifecycle, approval, run, or session-link state. Hub commands, file import,
  and the agent tool all route mutations through that boundary.
- User-editable intent is represented as Markdown with YAML frontmatter in
  `~/.cline/tasks/*.task.md` for global tasks and
  `<workspace>/.cline/tasks/*.task.md` for workspace tasks. Operational fields
  such as status, revision, approval, and session IDs are not writable in a
  spec. `AgendaTaskSpecFileStore` confines paths to the selected task directory
  and writes specs atomically.
- `SqliteAgendaTaskStore` owns `tasks.db` (resolved by
  `resolveTasksDbPath()`). SQLite is the operational source of truth for task
  status, revisions, run attempts, session links, and the automation policy;
  the Markdown file is the canonical editable task description, not an
  append-only queue or a substitute for concurrency control.
- Task-file parsing and reconciliation must feed the manager instead of
  writing SQLite directly. This preserves one validation and audit boundary
  whether a change came from an editor, desktop client, SDK client, or agent.
- Manager startup scans global task specs, recovers persisted task/run state,
  and reattaches every known workspace whose directory still exists. Missing
  historical workspaces are preserved in SQLite without recreating project
  directories. Selecting/listing a workspace registers it so even its first
  hand-authored task file is discovered and watched. Filesystem changes are
  reconciled back through the same manager rather than applied from watcher
  callbacks.
- Raw-file creation and edits are attributed to `system:file_reconciler` and
  always leave changed intent awaiting manual task approval. File edits never
  reopen completed, cancelled, or expired tasks; terminal records remain
  terminal and retain their last-known-good operational state.

### Approval and session execution

- Every new task starts at `pending_approval`. Approval is bound to the exact
  task `revision` through `approvedRevision`; an execution-relevant edit
  increments the revision and revokes stale approval. An approved revision is
  therefore immutable at the point it is claimed for execution.
- Approval and execution synchronously reconcile the backing Markdown file to
  close the watcher debounce window. Both fail closed if that canonical spec
  is missing, malformed, or does not semantically match the SQLite revision;
  stale last-known-good intent is never approved or executed.
- Hub `task.create` and `task.update` payloads omit actor fields; the command
  service derives the user actor from the calling Hub client. Update,
  approval, cancellation, and run requests carry the caller's displayed
  `expectedRevision`; specifically, `task.approve`, `task.cancel`, and
  `task.run` reject a missing or stale revision.
- P0 is the most urgent priority and P5 is the least urgent. `expiresAt` is a
  required latest-start boundary: expiry prevents a new run but does not abort
  a session that already started.
- Starting a task creates an `AgendaTaskRunRecord` and a normal Hub session.
  The run owns the task/revision/session association, while the task keeps
  `currentRunId`, `lastRunId`, and `lastSessionId` projections for UI lookup.
  A global task remains globally scoped and resolves the Hub's shared chat
  workspace only when its session starts.
- The manager correlates Hub session completion, failure, and cancellation
  with the linked run and updates both run and task. Startup recovery follows
  the same boundary rather than manufacturing a second run. A completed task
  does not own or delete its session; the linked session remains normal
  session history that a user can reopen.

### Hub, agent, and desktop surfaces

- The Hub command family is `task.create`, `task.list`, `task.get`,
  `task.update`, `task.approve`, `task.cancel`, `task.run`,
  `task.automation.get`, and `task.automation.set`. Registered task events are
  `task.created`, `task.updated`, `task.deleted`, `task.run.started`,
  `task.run.completed`, `task.run.failed`, and `task.automation.updated`.
  Events are invalidation and lifecycle signals; clients re-read the current
  task or policy projection rather than rebuilding authority state from the
  event stream.
- Hub-hosted agent sessions receive one snake-case `tasks` tool with a required
  `kind` discriminator. `kind: "todo"` creates, updates, lists, and gets durable
  Agenda items within the current session's workspace (or the global scope for
  chat sessions). It cannot approve, cancel, or start a Todo, so an agent cannot
  self-authorize or terminate queue work.
- `kind: "scheduled"` routes to `HubScheduleService` and manages the same
  records shown by the desktop Routine view; the unified tool does not merge
  the two persistence or lifecycle domains. Scheduled operations inherit the
  current session workspace, cwd, and model, filter reads and mutations to that
  workspace, and allow mutations only from an interactive session. One-time
  schedules accept an exact future ISO timestamp; recurring schedules accept a
  five-field cron expression and optional IANA timezone.
- The Hub contributes one tool-conditional system-prompt rule for `tasks`. It
  distinguishes reviewed Todo work from autonomous scheduled execution, states
  that Todo `available_at` is not a timer, requires clarification for ambiguous
  “remind me” requests, and prevents creating both record kinds unless the user
  explicitly requests both.
- `AgendaAutomationPolicy` is user-owned Hub state. `manual` preserves the
  per-task review gate; `auto_start` and `unattended` are explicit opt-ins. The
  manager's automation pump enforces the policy's concurrency, chain-depth,
  and hourly-start guardrails. `auto_start` waits for a connected client with
  the tool-approval capability and starts an interactive task session that
  conservatively requires approval for each tool. Explicit `unattended` mode
  may run headlessly and auto-approves enabled tools.
- Automation never infers user consent from a raw task-file change. For
  manager-backed intent, `applyToAgentCreated` governs tasks originally
  created by an agent and tasks whose latest manager-backed edit came from an
  agent; disabling it leaves those revisions pending manual approval.
- Cline Code projects the same Hub state into an Agenda section in the desktop
  sidebar and workspace-filtered `suggestion`/`reminder` quick actions below
  the welcome composer. The sidebar supports review, start, cancellation,
  linked-session navigation, and the automation toggle; it does not maintain a
  second task store.

## File-Based And Event-Driven Automation (`ClineCore` / `CronService`)

`@cline/core` ships a file-based automation subsystem under
`packages/core/src/cron/`. It lets operators author recurring and one-off
tasks as Markdown files under global `~/.cline/cron/` by default, and
event-driven tasks as `events/*.event.md` specs. All trigger kinds run
through the same durable queue and runtime handlers. `ClineCore` exposes the
SDK-facing `cline.automation.*` entry points; `CronService` is the internal
orchestrator used by core and hub layers.

### Layers

1. **Spec parser** (`cron/specs/cron-spec-parser.ts`): parses YAML frontmatter + body
   into a `CronSpec` discriminated union (`one_off | schedule | event`).
   Types live in `@cline/shared` under `src/cron/cron-spec-types.ts`
   so other packages can consume them without the YAML parser. Schedule
   expressions and timezones are validated before a spec can become
   runnable.
2. **Store** (`cron/store/sqlite-cron-store.ts`): owns `cron.db` at
   `resolveCronDbPath()` (default `.cline/data/db/cron.db`). Schema is
   bootstrapped from `cron/store/cron-schema.ts` — sessions and cron live in separate
   DBs so their lifecycles stay decoupled.
3. **Reconciler** (`cron/specs/cron-reconciler.ts`): scans the configured cron specs
   directory (global `~/.cline/cron/` by default, or workspace-scoped when
   configured), parses each file independently, and upserts spec state.
   Invalid specs are recorded
   with `parse_status='invalid'` so state is durable rather than silently
   dropped. Files that disappear between scans get `removed=1` and their
   queued runs are cancelled.
4. **Watcher** (`cron/specs/cron-watcher.ts`): `node:fs watch({ recursive: true })`
   with a ~250ms per-path debounce. Watcher events always trigger a
   re-reconcile — the reconciler is always the source of truth, not the
   watcher stream.
5. **Materializer** (`cron/runner/cron-materializer.ts`): turns file-triggered specs into
   queued `cron_runs`. One-off: at most one run record per `(spec_id,
   revision)`, including failed runs so specs do not retry accidentally.
   Schedule: "one overdue catch-up on startup then advance" using
   timezone-aware `getNextCronTime`. New hub schedules persist the local IANA
   timezone when none is provided. The desktop form sends its own local timezone;
   explicit timezone choices and existing schedule timezones are preserved.
6. **Event ingress** (`cron/events/cron-event-ingress.ts`): accepts already-normalized
   `AutomationEventEnvelope` values, persists them into `cron_event_log`,
   matches enabled event specs by `event_type` plus declarative filters,
   applies dedupe/debounce/cooldown policy, and enqueues `cron_runs` with
   `trigger_kind='event'`. It never executes agents directly. Plugins can
   declare `automationEvents` and submit normalized events through
   `ctx.automation.ingestEvent(...)`; sandboxed plugins forward those events
   through the core plugin event bridge.
   Acceptance is one synchronous SQLite write transaction: the event log,
   matching runs, debounce changes, materialization pointers, and final
   processing status commit together. A failure rolls all of them back and
   propagates to the caller, which must redeliver the event to retry. Other
   connections cannot observe or claim partial fan-out. Committed events remain
   deduplicated by event ID, including a retry after a lost response. Failures
   are logged outside the transaction, not persisted as deduplication tombstones.

7. **Runner** (`cron/runner/cron-runner.ts`): polls `cron.db`, atomically claims
   queued runs, executes them via the existing `HubScheduleRuntimeHandlers`
   (`startSession` → `sendSession` → `stopSession` / `abortSession`),
   dispatches new work independently of unfinished agent turns, and renews
   locally active claims before polling expired work after system sleep. Startup
   installs polling without waiting for the initial batch to finish. It also
   renews the run claim while execution is active, writes a markdown report
   per run, and transactionally updates status. Optional scheduler telemetry records
   run start/finish, trigger kind, attempt count, start delay, duration, and outcome
   through the normal telemetry service. It excludes prompts, paths, and raw errors;
   capture failures do not interrupt execution. File specs can constrain
   tool availability, config extension loading (`rules`, `skills`,
   `plugins`), trigger source, and a notes directory that is injected into
   the system prompt. The automation runtime adapters explicitly persist
   `mode: "automation"` for every run and record the spec-defined trigger
   source as `sessionHistoryOrigin.trigger` in session metadata. Event runs
   include the normalized trigger event context in the prompt.
8. **Reports** (`cron/reports/cron-report-writer.ts`): writes
   `.cline/cron/reports/<run-id>.md` with run frontmatter plus
   `## Summary`, `## Usage`, `## Tool Calls`, and, for event runs,
   `## Trigger Event` sections.
9. **Service** (`cron/service/cron-service.ts`): orchestrates all of the above.
   `ClineCore.create({ automation })` owns the SDK-facing lifecycle and exposes
   `cline.automation.*` methods. Hub-side callers can submit normalized events
   through the `cron.event.ingest` command.

The detached hub daemon passes its workspace root as `cronOptions`, so
normal CLI/hub startup watches `${workspaceRoot}/.cline/cron/` without a
custom host needing to opt in.

Programmatic hub schedules are stored as `cron_specs` with source
`hub-schedule` and execute through the same `cron_runs`
claim/requeue/report flow as file-backed one-off, recurring, and
event-driven specs. The hub schedule command surface remains a thin adapter;
there is no separate schedules table, schedule store, or schedule runner.

Runner claims enforce global and per-spec capacity inside the SQLite claim
transaction, skipping saturated specs before choosing the next due run. This
keeps multiple database connections from exceeding a schedule's parallelism
and prevents a backlog of blocked siblings from starving other schedules.
Each execution has a cancellation controller and a deadline covering request
preparation, session startup, and the turn. Shutdown cancels and drains tracked
executions with bounded session cleanup; interrupted runs are recorded as
cancelled, not automatically replayed after possibly performing external work.
Late startup responses are cleaned up without sending a turn or touching the
closed store. Losing a lease cancels the old execution, and attaching its
session requires the current claim token. Terminal status is persisted before
writing the optional report, so a report filesystem failure cannot replay a
completed turn. Report and cleanup failures are logged separately.


## Navigating the Codebase

### Starting Points by Task

**I want to understand the agent loop and tool execution:**
- Start: `packages/agents/src/agent.ts` — the stateless runtime loop
- Then: `packages/agents/src/agent-step.ts` — individual iteration steps
- Extensions: `packages/core/src/extensions/plugin/` — plugin discovery, the registry, and the worker/subprocess transports

**I want to understand session persistence and state:**
- Start: `packages/core/src/runtime/host/local-runtime-host.ts` — local session lifecycle
- Then: `packages/core/src/runtime/orchestration/` — session orchestration
- Settings: `packages/core/src/settings/` — settings mutation and state

**I want to understand the hub system:**
- Start: `packages/core/src/hub/server/` — WebSocket server and hub command handlers
- Clients: `packages/core/src/hub/client/` — host-side hub clients
- Transport: `packages/core/src/hub/runtime-host/` — hub-backed runtime hosts

**I want to add a new tool:**
- Tools registry: `packages/core/src/extensions/tools/` — built-in tool definitions
- Tool execution: `packages/agents/src/tool-use.ts` — how tools are called
- Plugin tools: `packages/core/src/extensions/plugin/` — plugin-registered tools

**I want to understand settings and configuration:**
- Watcher system: `packages/core/src/extensions/config/` — file watching and loading
- Provider config: `packages/core/src/runtime/config/` — provider settings resolution
- Settings services: `packages/core/src/settings/` — settings state and mutation

**I want to add a new runtime feature (hook/extension):**
- Hook contracts: `packages/shared/src/hooks/` — hook types and engine
- Plugin system: `packages/core/src/extensions/plugin/` — plugin discovery and execution
- Runtime builder: `packages/core/src/services/local-runtime-bootstrap.ts` — how runtime is composed

### File Naming Conventions

- `*.ts` — TypeScript source
- `*.test.ts` — unit tests (Vitest)
- `*.e2e.test.ts` — end-to-end tests requiring full integration
- `*.ts` in examples — runnable example files (plugins, hooks)
- `*.md` files in `apps/examples/` — documentation and markdown-based specs (cron, events)

### Key Type Locations

- **`ClineCore`** — `packages/core/src/index.ts` — the main SDK orchestrator
- **`Agent`** — `packages/agents/src/agent.ts` — the agent loop
- **`RuntimeHost`** — `packages/core/src/runtime/host/runtime-host.ts` — execution abstraction
- **`AgentPlugin`** — `packages/shared/src/plugin/` — plugin contract
- **`CronSpec`** — `packages/shared/src/cron/cron-spec-types.ts` — automation specs

## Publishability Constraint

This repo has both publishable SDK packages and internal workspace packages.

Architectural consequence:

- internal packages must not accidentally become part of the publishable SDK surface
- release automation should only target the intended published packages
- internal code may compose with published packages, but published packages should not take hard dependencies on internal-only workspace layers unless you explicitly intend to publish that integration

### Published Packages

The following packages are published to npm:

- `@cline/shared` — shared types, contracts, and low-level utilities
- `@cline/llms` — provider integrations and model manifests
- `@cline/agents` — the agent loop and tool orchestration
- `@cline/core` — the main SDK with session management, hub, and configuration

### Internal Apps

The following workspace apps are internal and not published as SDK packages:

- `apps/cli` — CLI implementation
- `apps/webview` — VS Code webview
- `apps/examples` — example plugins and integrations

### Display-only session errors

Terminal run errors are persisted in session message history with
`metadata.displayOnly: true` and `metadata.displayRole: "error"`. Desktop and CLI
render these entries on history reload. The core message codec excludes them
from agent state (including model requests and compaction); the conversation
store retains their transcript positions when replacing agent snapshots.

Display-only failures are recorded once after automatic authentication retries
settle; recovered attempts do not emit a terminal error. The
`session.error_recorded` telemetry event reports session ID, provider, model, and
whether the terminal failure returned or threw, without error/transcript text.
Desktop reconciliation retains the full live failed turn until a saved terminal
error reaches its user-run count and is not a previously displayed error ID.

### Host connector transport

`LocalRuntimeHost` and `createLocalHubScheduleRuntimeHandlers` accept an optional
`connectorsRequest` callback for discovery and execution during startup and resume.
It supplies host authentication without reading local connector credentials or
state. Without it, the local behavior described below is unchanged.

### Composio beta access

Composio management in the desktop sidecar and tool registration/execution in
local runtimes (including the detached hub) require the account-scoped PostHog
flag `CLINE_COMPOSIO_BETA` to be exactly `true`. The shared core account flag
evaluator reads the current Cline account ID from provider settings, caches the
evaluation in memory for one minute, and discards grants on account changes.
Missing identity, provider configuration, or flag values deny access; internal
email domains do not bypass this gate. Saved connector schemas alone cannot
enable tools. Existing sessions recheck access before each tool execution.
Disconnect/cancel cleanup remains available after access is removed. The Cline
API proxy must enforce the same flag server-side for authenticated requests.

The connector client uses `/api/v1/connectors` with the Cline `{ success, data }`
envelope. The sidecar fetches every catalog and connection page, including empty
pages with continuation tokens, and rejects failed, malformed, or cyclic
pagination before caching or reconciliation. Disabled accounts (`is_disabled`)
are excluded. Connection state stores IDs, timestamps, and display metadata;
connection and status-refresh flows never fetch or persist app tool schemas.
The connector dialog uses the catalog tool count when known.

At local session bootstrap, core creates a server-owned tool-router session and
registers only `COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_MANAGE_CONNECTIONS`,
`COMPOSIO_WAIT_FOR_CONNECTIONS`, and `COMPOSIO_MULTI_EXECUTE_TOOL`. The model
searches for relevant app tools, receives their schemas in search results, and
executes them through multi-execute without registering app tools in subsequent
model requests. The flow works without saved connections and can connect apps
within the same session. Missing or failed meta-session creation leaves connector
tools unavailable; saved app schemas never provide a fallback. Execution uses
`/meta-tools/{slug}/execute` with the session ID and arguments.

Customize > Connectors displays the usage-ranked catalog, with search across
all loaded apps and installation/connection management in its detail dialog.
The backend includes managed-auth toolkits before anyone has connected them,
and provisions their auth configuration on first installation. This requires
the full-catalog backend in core-platform PR #3383. Catalog responses must
use the paginated contract; malformed responses are rejected.

Connector metadata and cancellation tombstones live in
`settings/composio/<sha256-account-id>.json`. Each account has separate
availability/catalog caches and pending operations. Async management requests
retain their initiating account and refuse to send with another account's token.
The core extension does not read this state file. It scopes meta-session creation
to the signed-in account and checks identity again before registration and
execution in an existing session.

`RuntimeOAuthTokenManager` serializes credential reads, refreshes, and saves
using a SQLite exclusive transaction keyed by provider settings path and storage
provider ID. This coordinates the sidecar, hub, and other local processes; OS
locks release on process exit. Waiters reread persisted credentials under the
lock and reuse a token another process refreshed, including for forced refresh
requests. A refresh result is discarded if sign-out or sign-in replaced the
credentials while the request was in flight.

### Queue steering

Queue steering through `pendingPrompts.steerFirst` selects and promotes the
current queue head in one synchronous core operation. Desktop Enter sends this
intent through the sidecar and Hub without fetching a prompt ID first; explicit
per-prompt steering continues to update by ID. Concurrent clients therefore
cannot make Enter promote an entry from a stale queue snapshot.

### SSH environments

`core/src/remote` owns the reusable SSH environment service and standalone remote
helper entrypoint. Clients use `RemoteEnvironmentService.connect` to obtain an
authenticated loopback endpoint, then instantiate the ordinary `ClineCore` remote
backend. The helper uploads are content-addressed and the remote Hub binds only
to loopback. SSH forwards that endpoint to a local ephemeral port. The helper's
explicit discovery record is separate from the remote account's default Hub.

Desktop retains presentation, packaged-resource lookup, and its environment-to-
runtime bindings. Settings and the chat environment selector call the shared
service; each runtime binding supplies the same session/approval/event APIs.
Workspace and session reads route by environment identity. System-prompt
bootstrap happens on the remote host when the caller omits a prompt, so local
filesystem metadata is not embedded in remote sessions. Login-shell PATH
resolution also lives in core and is reused by the helper and desktop startup.
The primary shell probe allows 5 seconds for slow profiles; a fallback shell
gets half that budget, bounding the combined wait to 7.5 seconds.

### Configured subagent approvals

Configured subagents execute their available tools without inheriting the parent
session’s tool approval policies or approval callback, matching generic subagents
and teammates. The parent’s `subagent_<name>` delegation call still follows the
parent’s approval policy. Tool allowlists and disabled-tool filtering remain in
effect when constructing child tools. Inherited runtime hooks are unchanged.