@cerebriline/core 4.100.245 → 4.100.247

package/assets/prompt-templates/claude.md

@@ -236,6 +236,8 @@ Changes or creates one text file. Use this, never the shell, for anything that w
 
 Which arguments you send decides what the call does. Use one form per call; don't mix `old_text` with a line range.
 
+Write the arguments in this order: `path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
+
 1. Replace text: `path`, `old_text`, `new_text`. `old_text` must match exactly, whitespace and indentation included. If it occurs more than once, add `occurrence` (one-based, in file order) to pick one, or `replace_all: true` for all of them.
 2. Replace lines: `path`, `start_line`, `new_text`, optional `end_line` (inclusive, defaults to `start_line`). Best where the text is long, minified or repeated, because a line number cannot be ambiguous. An empty `new_text` deletes the range.
 3. Replace characters: `path`, `start_line`, `start_column`, `new_text`, optional `end_line`/`end_column` (inclusive, each defaulting to its start). This is the unit a diagnostic speaks in — `line 108, column 385` — and on a minified line it is the only form that leaves the other 400 characters alone. `start_column` alone replaces exactly one character.

package/assets/prompt-templates/deepseek.md

@@ -120,6 +120,7 @@ An editor for controlled filesystem edits on the text file at the provided path.
 - Insert: `insert_line` plus `new_text`, which adds text before that line without replacing anything. Use `line_count + 1` to append at EOF. Add `insert_column` to insert *within* that line instead, before the character at that column — this is how you add one missing bracket. Use `line_length + 1` to append at the end of the line.
 - Create, or replace a file whole: `new_text` alone. When the file does not exist this creates it; when it exists this replaces every line, which is allowed once you have read the file, since reading it is what tells you what you are overwriting. `start_line: 1` with `end_line: <line count>` is the same write by another name. Neither has a size limit, because a file written whole cannot be split — but reach for a whole-file write only once a targeted edit has failed, since a rewrite that is slightly wrong quietly loses the parts you did not mean to touch. Never delete a file to get a clean slate: this call already is one, and a deleted file is simply gone if the turn ends before you write it back.
 
+Write the arguments in this order: `path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
 Use this rather than a shell command for anything that changes a file. Make one edit at a time and check it before starting the next: reads and searches cost nothing if one turns out to be unnecessary, but several edits made together and checked once leave several things to undo and no way to tell which one was wrong.
 
 Read the lines you are about to change before you change them: an edit aimed at a range you have not read in its current state is refused. Your own edits count — one that changes the file's length moves every line below it, so read that region again before editing it a second time. Line numbers taken from an earlier turn, from a task summary, or from a diagnostic issued before your last edit are the ones that go stale.

package/assets/prompt-templates/default.md

@@ -73,6 +73,7 @@ An editor for controlled filesystem edits on the text file at the provided path.
 - Replace characters: `start_line` and `start_column` plus `new_text`, with optional `end_line`/`end_column` (both inclusive; each defaults to its start). This is the unit a diagnostic speaks in — `Line 108, column 385` — and on a long or minified line it is the only edit that leaves the other 400 characters untouched. `start_column` on its own replaces exactly one character.
 - Insert: `insert_line` plus `new_text`, which adds text before that line without replacing anything. Use `line_count + 1` to append at EOF. Add `insert_column` to insert *within* that line instead, before the character at that column — this is how you add one missing bracket. Use `line_length + 1` to append at the end of the line.
 - Create, or replace a file whole: `new_text` alone. When the file does not exist this creates it; when it exists this replaces every line, which is allowed once you have read the file, since reading it is what tells you what you are overwriting. `start_line: 1` with `end_line: <line count>` is the same write by another name. Neither has a size limit, because a file written whole cannot be split — but reach for a whole-file write only once a targeted edit has failed, since a rewrite that is slightly wrong quietly loses the parts you did not mean to touch. Never delete a file to get a clean slate: this call already is one, and a deleted file is simply gone if the turn ends before you write it back.
+Write the arguments in this order: `path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
 Use this rather than a shell command for anything that changes a file. Make one edit at a time and check it before starting the next: reads and searches cost nothing if one turns out to be unnecessary, but several edits made together and checked once leave several things to undo and no way to tell which one was wrong. Read the lines you are about to change before you change them: an edit aimed at a range you have not read in its current state is refused. Your own edits count — one that changes the file's length moves every line below it, so read that region again before editing it a second time. Line numbers taken from an earlier turn, from a task summary, or from a diagnostic issued before your last edit are the ones that go stale. Repeating the lines already in the range and then continuing is how you insert after them, and it is allowed — the range says which lines you mean, so repeating them is your own choice. What is refused is a `new_text` that goes on to repeat lines from *outside* the range: that appends a second copy of text already elsewhere in the file rather than replacing anything, and the refusal names the lines it matched so you can aim the next call at them. Output: a single `{query, result, success, error?}` object for this one edit, where `query` is `edit:<path>` or `insert:<path>` and `result` describes what changed. A failed edit changes nothing: `success` is false, `error` says why, and the file is exactly as it was. Do not resend the same call — `error` names the fix. In particular, text copied out of a `read_files` result must have its `123 | ` line-number gutter removed first.
 
 # tool: sed
@@ -123,7 +124,7 @@ Output: a single `{query, result, success, error?}` object covering the whole pa
 Ask user a question for clarifying or gathering information needed to complete the task. For example, ask the user clarifying questions about a key implementation decision. You should only ask one question. Provide an array of 2-5 options for the user to choose from. Never include an option to toggle to Act mode. Mark the option you would pick: end it with ' (recommended)' and say why in one sentence in the question. Mark exactly one. Leave every option unmarked only when the choice turns on the user's taste or on something only they know. Output: the user's answer, as plain text — one of the options you offered, or whatever they wrote instead. Act on it in the same turn; the answer arriving is not a reason to stop.
 
 # tool: submit_and_exit
-Submit the final answer and exit the conversation. For example, submit a summary of the investigation and confirm the issue is resolved. You should only submit once all necessary steps are completed. Make sure to verify your output matches the expected format, data types, and file locations specified. Provide a summary of the investigation and confirm the issue is resolved. Output: a short confirmation, as plain text. This call ends the run — nothing you plan after it will happen, so call it only when there is nothing left to do.
+Submit the final answer and exit the conversation. For example, submit a summary of the investigation and confirm the issue is resolved. You should only submit once all necessary steps are completed AND you have verified the result by execution. Before calling this, re-read the task, then confirm from your own tool output that every required file exists at the specified path and that its contents match the expected format, data types, and values. If the task provides tests, run them and confirm they pass; if it does not, run your own solution end to end and read the output back as evidence. Do not submit on the assumption that your solution works — submit because you have observed evidence that it does. Provide a summary of the investigation and confirm the issue is resolved. Output: a short confirmation, as plain text. This call ends the run — nothing you plan after it will happen, so call it only when there is nothing left to do.
 
 # tool: run_commands
 {{DEFAULT}}

package/assets/prompt-templates/kimi-k3.md

@@ -167,6 +167,7 @@ Make precise edits to a single text file at `path`. Six modes, chosen by which a
 - Insert: `insert_line` plus `new_text`, which adds text before that line without replacing anything. Use `line_count + 1` to append at EOF. Add `insert_column` to insert inside that line instead, before the character at that column — this is how you add one missing bracket, with `line_length + 1` appending at the end of the line.
 - Create or replace whole: `new_text` alone. Creates the file when it does not exist; replaces every line when it does, which needs the file read first. No size limit on this one — a file written whole cannot be split. Never `rm` a file to write it fresh: this is that, and a deleted file is gone if the turn ends first.
 
+Write the arguments in this order: `path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
 Use this rather than a shell command for anything that changes a file. Make one edit at a time and check it before starting the next: reads and searches cost nothing if one turns out to be unnecessary, but several edits made together and checked once leave several things to undo and no way to tell which one was wrong. Read the lines you are about to change before you change them: an edit aimed at a range you have not read in its current state is refused. Your own edits count — one that changes the file's length moves every line below it, so read that region again before editing it a second time. Line numbers taken from an earlier turn, from a task summary, or from a diagnostic issued before your last edit are the ones that go stale. Repeating the lines already in the range and then continuing is how you insert after them, and it is allowed — the range says which lines you mean, so repeating them is your own choice. What is refused is a `new_text` that goes on to repeat lines from *outside* the range: that appends a second copy of text already elsewhere in the file rather than replacing anything, and the refusal names the lines it matched so you can aim the next call at them.
 
 Output: a single `{query, result, success, error?}` object for this one edit, where `query` is `edit:<path>` or `insert:<path>` and `result` describes what changed. A failed edit changes nothing: `success` is false, `error` says why, and the file is exactly as it was. Do not resend the same call — `error` names the fix. In particular, text copied out of a `read_files` result must have its `123 | ` line-number gutter removed first.

package/assets/prompt-templates/kimi.md

@@ -107,6 +107,7 @@ Make precise edits to a single text file at `path`. Six modes, chosen by which a
 - Insert: `insert_line` plus `new_text`, which adds text before that line without replacing anything. Use `line_count + 1` to append at EOF. Add `insert_column` to insert inside that line instead, before the character at that column — this is how you add one missing bracket, with `line_length + 1` appending at the end of the line.
 - Create or replace whole: `new_text` alone. Creates the file when it does not exist; replaces every line when it does, which needs the file read first. No size limit on this one — a file written whole cannot be split. Never `rm` a file to write it fresh: this is that, and a deleted file is gone if the turn ends first.
 
+Write the arguments in this order: `path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
 Use this rather than a shell command for anything that changes a file. Make one edit at a time and check it before starting the next: reads and searches cost nothing if one turns out to be unnecessary, but several edits made together and checked once leave several things to undo and no way to tell which one was wrong.
 
 Read the lines you are about to change before you change them: an edit aimed at a range you have not read in its current state is refused. Your own edits count — one that changes the file's length moves every line below it, so read that region again before editing it a second time. Line numbers from an earlier turn, from a task summary, or from a diagnostic issued before your last edit are the ones that go stale.

package/assets/prompt-templates/minimax.md

@@ -134,6 +134,8 @@ An editor for controlled filesystem edits on the text file at `path`. Six operat
 4. **Insert** — `insert_line` plus `new_text`, which adds text before that line without replacing anything. Use `line_count + 1` to append at EOF. Add `insert_column` to insert *within* that line, before the character at that column — this is how you add one missing bracket. Use `line_length + 1` to append at the end of the line.
 5. **Create or replace a file whole** — `new_text` alone. When the file does not exist this creates it; when it exists this replaces every line, which is allowed once you have read the file, since reading it is what tells you what you are overwriting. `start_line: 1` with `end_line: <line count>` is the same write by another name. Neither has a size limit, because a file written whole cannot be split — but reach for a whole-file write only once a targeted edit has failed, since a rewrite that is slightly wrong quietly loses the parts you did not mean to touch. Never delete a file to get a clean slate: this call already is one, and a deleted file is simply gone if the turn ends before you write it back.
 
+**Argument order:** write the arguments in this order: `path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
+
 **When to use it:** for anything that changes a file. Use `editor` rather than `run_commands` for `sed -i`, `echo >`, `> file`, redirect-into-file, or any other shell write.
 
 **One at a time, confirmed before the next:** send one `editor` call, run the cheap check (`check_file`, or a `read_files` of the lines you touched if no language server covers that file), and only then send the next. Reads, searches and commands are batched; edits are not, because several edits made together and checked once leave several things to undo and no way to tell which one was wrong.

package/assets/prompt-templates/nemotron.md

@@ -92,6 +92,7 @@ An editor for controlled filesystem edits on the text file at the provided path.
 - Insert: `insert_line` plus `new_text`, which adds text before that line without replacing anything. Use `line_count + 1` to append at EOF. Add `insert_column` to insert *within* that line instead, before the character at that column — this is how you add one missing bracket. Use `line_length + 1` to append at the end of the line.
 - Create, or replace a file whole: `new_text` alone. When the file does not exist this creates it; when it exists this replaces every line, which is allowed once you have read the file, since reading it is what tells you what you are overwriting. `start_line: 1` with `end_line: <line count>` is the same write by another name. Neither has a size limit, because a file written whole cannot be split — but reach for a whole-file write only once a targeted edit has failed, since a rewrite that is slightly wrong quietly loses the parts you did not mean to touch. Never delete a file to get a clean slate: this call already is one, and a deleted file is simply gone if the turn ends before you write it back.
 
+Write the arguments in this order: `path` and every other short argument first — line and column numbers, `intent`, `task_progress`, `old_text` — and `new_text` last. The text you are writing is the long part of the call, and whatever is written after a long text is the part most easily left out.
 Use this rather than a shell command for anything that changes a file. Make one edit at a time and check it before starting the next: reads and searches cost nothing if one turns out to be unnecessary, but several edits made together and checked once leave several things to undo and no way to tell which one was wrong. Read the lines you are about to change before you change them: an edit aimed at a range you have not read in its current state is refused. Your own edits count — one that changes the file's length moves every line below it, so read that region again before editing it a second time. Line numbers taken from an earlier turn, from a task summary, or from a diagnostic issued before your last edit are the ones that go stale. Repeating the lines already in the range and then continuing is how you insert after them, and it is allowed — the range says which lines you mean, so repeating them is your own choice. What is refused is a `new_text` that goes on to repeat lines from *outside* the range: that appends a second copy of text already elsewhere in the file rather than replacing anything, and the refusal names the lines it matched so you can aim the next call at them. Output: a single `{query, result, success, error?}` object for this one edit, where `query` is `edit:<path>` or `insert:<path>` and `result` describes what changed. A failed edit changes nothing: `success` is false, `error` says why, and the file is exactly as it was. Do not resend the same call — `error` names the fix. In particular, text copied out of a `read_files` result must have its `123 | ` line-number gutter removed first.
 
 **Do not use `run_commands` for file operations when `read_files`, `editor`, `apply_patch`, `search_codebase`, `list_files`, `check_file`, or `ask_lsp` exist for that purpose.** The shell is for running the program, not for inspecting or changing its source.

package/assets/skills/browser-automation/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: browser-automation
+description: >-
+  Drives a real browser through the Playwright MCP server: opening pages,
+  clicking, typing, filling forms, uploading files, reading what a page shows
+  and what it requested, taking screenshots. Use when the user asks to automate
+  a browser task, test a web page or flow end to end, fill in a web form, or
+  get content from a page that only renders with JavaScript or behind a login.
+disabled: true
+---
+
+# Browser automation with Playwright
+
+This skill uses the tools of the Playwright MCP server. They appear as
+`playwright__browser_navigate`, `playwright__browser_click` and so on, where
+`playwright` is the name the server was added under. The names below leave the
+prefix out.
+
+## Before starting
+
+If no `…__browser_navigate` tool is offered, the server is not set up. Tell the
+user to add it under **MCP Servers > Add Local**, where **Playwright** is a
+preset (command `npx`, argument `@playwright/mcp@latest`), then stop. Do not
+try to install it or drive a browser from the shell instead.
+
+The first call downloads the server and may download a browser, so it can take
+a minute. If a call reports that the browser is not installed, say so and name
+the command the message gives.
+
+## The loop
+
+1. `browser_navigate` to the URL.
+2. `browser_snapshot`. It returns the page as an accessibility tree in which
+   every element carries a reference. This is how you see the page: it is
+   text, it is exact, and it is what the other tools take.
+3. Act on one element: `browser_click`, `browser_type`, `browser_select_option`,
+   `browser_hover`, `browser_press_key`, `browser_file_upload`.
+4. Read the result the tool returns. Take a new snapshot when the page changed
+   and you need references for what is on it now.
+
+References belong to the snapshot they came from. After a navigation or any
+change that redraws the page, the old ones are gone: take a new snapshot
+before the next action, never reuse a reference from an earlier one.
+
+## Naming an element
+
+Tools that act on an element take two things:
+
+- `target`: the element's reference copied exactly from the latest snapshot,
+  or a selector that matches one element only.
+- `element`: a short description in plain words ("Submit button"). It is what
+  the user is shown when asked to allow the action.
+
+Prefer the reference. Use a selector only when the snapshot does not list the
+element, and make it specific enough to match once. A selector that matches
+several elements is refused.
+
+## Forms
+
+`browser_fill_form` fills several fields in one call. Each entry needs all of
+`target`, `name`, `type` and `value`. `type` is one of `textbox`, `checkbox`,
+`radio`, `combobox`, `slider`. For a checkbox the value is `true` or `false`;
+for a combobox it is the visible text of the option.
+
+Fill, then snapshot and check the values took before submitting. Submit with a
+click on the form's own button, or `browser_type` with `submit: true` on the
+last field.
+
+## Waiting
+
+Do not guess with fixed delays. `browser_wait_for` takes `text` (wait until it
+appears), `textGone` (until it disappears) or `time` in seconds as a last
+resort. After a click that loads something, wait for a text that only the
+loaded state shows.
+
+## Reading a page
+
+- `browser_snapshot` for what is on the page. `browser_find` searches the
+  snapshot for a text or a regular expression when the page is long.
+- `browser_evaluate` runs a function in the page and returns its value. Use it
+  to read data the snapshot does not carry, such as a table as rows:
+  `() => [...document.querySelectorAll("table tr")].map((r) => [...r.cells].map((c) => c.innerText))`
+- `browser_console_messages` and `browser_network_requests` for what the page
+  logged and requested; `browser_network_request` for one request's headers
+  and body.
+- `browser_take_screenshot` is for the user to look at, or for a model that
+  reads images. You cannot act on a screenshot; act on a snapshot.
+
+Large results take a `filename` and are saved to the workspace instead of
+being returned. Use it for a long snapshot or a full-page screenshot.
+
+For a whole site as files (pages, stylesheets, scripts, pictures), the
+`web_scrape` tool is the right one when it is offered. Use the browser for
+pages that need a login, a click or a form before they show their content.
+
+## When an action is refused or does nothing
+
+1. Take a new snapshot. The element may have moved, been replaced, or sit
+   under a dialog. `browser_handle_dialog` answers an alert or a confirm.
+2. Check the element is the one you mean: same text, same role.
+3. Check `browser_tabs`: a link may have opened a new tab, and the tools act on
+   the selected one.
+4. Only then use `browser_run_code_unsafe`. It takes a function,
+   `async (page) => { ... }`, and runs it with full access to the machine the
+   server is on, not only to the page. Keep the snippet to the one step that
+   failed, and await every call in it.
+
+## Finishing
+
+- Report what was done and what the page showed at the end, with the URL.
+- `browser_close` when the task is over, so no browser is left open.
+- Never type a password, a card number or a one-time code the user did not
+  give you for this task. If a page asks for one, stop and ask.

package/dist/ClineCore.d.ts

@@ -344,6 +344,15 @@ export declare class ClineCore {
      * ```
      */
     subscribe(listener: (event: CoreSessionEvent) => void, options?: RuntimeHostSubscribeOptions): () => void;
+    /**
+     * Whether this instance is subscribed to a session's live events.
+     *
+     * In hub mode ClineCore subscribes to a session when it starts, sends to,
+     * or lists pending prompts for it, and unsubscribes on stop. A client that
+     * also observes the hub directly can use this to render one copy of the
+     * session's events instead of both.
+     */
+    hasSessionSubscription(sessionId: string): boolean;
     /**
      * Updates the AI model used by an active session.
      *

package/dist/account/index.d.ts

@@ -1,3 +1,4 @@
 export { ClineAccountService, type ClineAccountServiceOptions, } from "./cline-account-service";
 export { type ClineAccountOperations, executeClineAccountAction, isClineAccountActionRequest, type ProviderActionExecutor, RpcClineAccountService, } from "./rpc";
+export { type ClineAccountTelemetryIdentity, persistClineAccountTelemetryIdentity, resolveClineAccountTelemetryIdentity, } from "./telemetry";
 export type { ClineAccountBalance, ClineAccountOrganization, ClineAccountOrganizationBalance, ClineAccountOrganizationUsageTransaction, ClineAccountPaymentTransaction, ClineAccountUsageTransaction, ClineAccountUser, ClineOrganization, ClineSubscriptionPlan, FeaturebaseTokenResponse, UserCurrentPlan, UserRemoteConfigOrganization, UserRemoteConfigResponse, } from "./types";

package/dist/account/telemetry.d.ts

@@ -0,0 +1,22 @@
+import type { ProviderSettingsManager } from "../services/storage/provider-settings-manager";
+import type { ClineAccountUser } from "./types";
+/** Account identity shared by telemetry and feature-flag integrations. */
+export interface ClineAccountTelemetryIdentity {
+    id: string;
+    email?: string;
+    provider: "cline";
+    organizationId?: string;
+    organizationName?: string;
+    memberId?: string;
+}
+/**
+ * Resolve the authenticated user and active organization once so every client
+ * applies the same cross-surface account dimensions.
+ */
+export declare function resolveClineAccountTelemetryIdentity(user: ClineAccountUser): ClineAccountTelemetryIdentity;
+/**
+ * Persist the latest active organization alongside OAuth settings. Detached
+ * runtime processes (notably the shared Hub) can then enrich task telemetry
+ * without making their own account API request.
+ */
+export declare function persistClineAccountTelemetryIdentity(manager: Pick<ProviderSettingsManager, "getProviderSettings" | "saveProviderSettings">, identity: ClineAccountTelemetryIdentity): boolean;

package/dist/cloud/api.d.ts

@@ -0,0 +1,122 @@
+import { type AgentMode, type MessageWithMetadata } from "@cerebriline/shared";
+import type { CloudBranchListOptions, CloudBranchListResult, CloudRepositoryListResult } from "./repositories";
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type CloudSessionRecord = {
+    id: string;
+    status: string;
+    sandboxType?: "standard" | "resumable";
+    title?: string;
+    sandboxUrl: string;
+    repoContext: {
+        repoUrl?: string;
+        branch?: string;
+    };
+    metadata: {
+        sandboxType?: "standard" | "resumable";
+        modelId?: string;
+        taskId?: string;
+        statusReason?: string;
+        provisioningPhase?: CloudProvisioningPhase;
+        createRequestTitle?: string;
+        cwd?: string;
+    };
+    expiredAt?: string | null;
+    lastActivityAt?: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export type CloudProvisioningPhase = "provisioning" | "cloning_repo" | "agent_starting" | "ready" | "failed";
+export declare function deriveCloudSessionTitle(prompt: string): string;
+export type CreateCloudSessionInput = {
+    sandboxType?: "standard" | "resumable";
+    /** Stable client-planned id for single-flighting one chat's start request. */
+    requestId?: string;
+    modelId: string;
+    repoUrl: string;
+    initialPrompt?: string;
+    branch?: string;
+    autoApproveTools?: boolean;
+    thinking?: boolean;
+    reasoningEffort?: "low" | "medium" | "high" | "xhigh";
+    mode?: AgentMode;
+    workspaceRelativePath?: string;
+    /** Null explicitly selects Personal; controllers resolve an omitted scope. */
+    organizationId?: string | null;
+    /** Host persistence hooks; never serialized into the provisioning request. */
+    handoff?: {
+        sourceSessionId: string;
+        resolveMessages: () => Promise<MessageWithMetadata[]>;
+        /** Persist dispatch intent after successful recovery lookup, before POST. */
+        onCreating: () => void | Promise<void>;
+        onOuterSessionCreated: (sessionId: string, context?: {
+            created: boolean;
+        }) => Promise<void>;
+        onOuterSessionRemoved?: (sessionId: string) => Promise<void>;
+        onSeeding?: () => void | Promise<void>;
+    };
+};
+export type { CloudBranchListOptions, CloudBranchListResult, CloudRepositoryListResult, CloudRepositoryOption, } from "./repositories";
+export type CloudSessionApiOptions = {
+    apiBaseUrl: string;
+    appBaseUrl: string;
+    getAuthToken: () => Promise<string | undefined>;
+    fetch?: FetchLike;
+    createTimeoutMs?: number;
+};
+export type CloudErrorCode = "authentication_required" | "github_not_connected" | "session_not_found" | "session_expired" | "session_failed" | "request_failed";
+export declare class CloudSessionError extends Error {
+    readonly code: CloudErrorCode;
+    readonly detail: string;
+    readonly connectUrl?: string | undefined;
+    /** HTTP status of the failed request, when one was received. */
+    readonly status?: number | undefined;
+    constructor(code: CloudErrorCode, detail: string, connectUrl?: string | undefined, 
+    /** HTTP status of the failed request, when one was received. */
+    status?: number | undefined);
+}
+/** The fresh handoff POST definitely did not create a workspace. Marker/list
+ * failures and ambiguous transport outcomes deliberately never use this type. */
+export declare class CloudHandoffCreationRejectedError extends Error {
+    constructor(cause: unknown);
+}
+export declare function parseCloudProvisioningPhase(value: unknown): CloudProvisioningPhase | undefined;
+export declare class CloudSessionApi {
+    private readonly options;
+    private readonly apiBaseUrl;
+    private readonly appBaseUrl;
+    private readonly fetchImpl;
+    private readonly createTimeoutMs;
+    private readonly unconfirmedHandoffCreates;
+    private readonly completedHandoffCreates;
+    constructor(options: CloudSessionApiOptions);
+    private request;
+    list(organizationId?: string): Promise<CloudSessionRecord[]>;
+    private listWithToken;
+    listRepositories(organizationId?: string): Promise<CloudRepositoryListResult>;
+    listBranches(repositoryId: number, organizationId?: string, options?: CloudBranchListOptions): Promise<CloudBranchListResult>;
+    status(sessionId: string, options?: {
+        authToken?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        sessionId?: string;
+        status?: string;
+        phase?: CloudProvisioningPhase;
+        statusReason?: string;
+    }>;
+    create(input: CreateCloudSessionInput): Promise<{
+        sessionId: string;
+        status: string;
+        sandboxUrl: string;
+        cleanupAuthToken: string;
+    }>;
+    private persistHandoffOuterSession;
+    waitUntilReady(sessionId: string, signal: AbortSignal, onStatus?: (status: {
+        phase?: CloudProvisioningPhase;
+    }) => void): Promise<void>;
+    resume(sessionId: string, signal?: AbortSignal): Promise<CloudSessionRecord>;
+    delete(sessionId: string, authToken?: string): Promise<void>;
+    private deleteWithAuth;
+    updateTitle(sessionId: string, title: string): Promise<CloudSessionRecord>;
+    /** Raw archived snapshot; null distinguishes a missing archive from []. */
+    history(sessionId: string): Promise<unknown[] | null>;
+}

package/dist/cloud/controller.d.ts

@@ -0,0 +1,172 @@
+import type { BasicLogger, MessageWithMetadata, ToolApprovalResult } from "@cerebriline/shared";
+import { NodeHubClient } from "../hub/client/index";
+import { type CloudSessionApi, CloudSessionError, type CloudSessionRecord, type CreateCloudSessionInput } from "./api";
+import { type CloudModel } from "./models";
+import type { CloudBranchListOptions, CloudBranchListResult, CloudRepositoryListResult } from "./repositories";
+import type { CloudCreationOptions, CloudHandoffSeed, CloudSessionAttachment, CloudSessionEvent, CloudSessionSnapshot, CloudSessionState, JsonRecord } from "./types";
+/** The seed command was not dispatched; the host may clear its seed marker. */
+export declare class CloudHandoffSeedRejectedError extends Error {
+    constructor(cause: unknown);
+}
+/** A queued prompt may have been accepted even when recovery also fails. */
+export declare class CloudQueueUnconfirmedError extends CloudSessionError {
+    constructor();
+}
+export declare class CloudHandoffSeedUnsupportedError extends Error {
+    constructor();
+}
+type CloudHubClient = Pick<NodeHubClient, "command" | "connect" | "dispose" | "getClientId" | "subscribe">;
+export type CloudSessionControllerOptions = {
+    logger?: BasicLogger;
+    clientIdentity?: {
+        prefix: string;
+        type: string;
+        displayName: string;
+        source: string;
+    };
+    /** Desktop preserves its historical cleanup; CLI keeps late successful creations recoverable. */
+    lateCreateDisposition?: "preserve" | "delete";
+    /** Host-owned first-task policy survives controller replacement; established tasks never qualify. */
+    pendingInitialTasks?: Map<string, CloudCreationOptions>;
+    api: Pick<CloudSessionApi, "create" | "resume" | "delete" | "list" | "status" | "waitUntilReady" | "history" | "updateTitle" | "listRepositories" | "listBranches">;
+    getAuthToken: () => Promise<string | undefined>;
+    apiBaseUrl: string;
+    getActiveOrganizationId?: (options?: {
+        fresh?: boolean;
+    }) => Promise<string | undefined>;
+    createHubClient?: (options: ConstructorParameters<typeof NodeHubClient>[0]) => CloudHubClient;
+};
+export declare function isCloudOuterSessionId(sessionId: string): boolean;
+export declare function cloudSessionToDiscoveryRecord(record: CloudSessionRecord): JsonRecord;
+export declare class CloudSessionController {
+    private readonly options;
+    private readonly sessionGenerations;
+    private readonly sessions;
+    private readonly approvals;
+    private readonly listeners;
+    private readonly detachedSessions;
+    private readonly restoredOptions;
+    private readonly authoritativeMessages;
+    private readonly streamingMessages;
+    private disposed;
+    private readonly connections;
+    private readonly connectionPromises;
+    private readonly knownSessions;
+    private readonly unlistedSessions;
+    private readonly pendingInitialTasks;
+    private lastListedSessions;
+    private discoveryRefresh?;
+    private readonly unconfirmedInnerCreates;
+    private readonly createRequests;
+    private readonly provisioningControllers;
+    private readonly sendAbortTokens;
+    private readonly titleWrites;
+    private readonly deletingSessions;
+    private readonly createHubClient;
+    constructor(options: CloudSessionControllerOptions);
+    /** Restores only pre-creation settings; never mutates a running Hub session's policy. */
+    restoreCreationOptions(sessionId: string, options: CloudCreationOptions): void;
+    protected seedSessionState(sessionId: string, state: CloudSessionState): void;
+    private stateFromRecord;
+    getSnapshot(sessionId: string): CloudSessionSnapshot | undefined;
+    subscribe(listener: (event: CloudSessionEvent) => void, sessionId?: string): () => void;
+    private publish;
+    private publishSnapshot;
+    private readonly snapshotTimers;
+    private cancelScheduledSnapshot;
+    private scheduleSnapshot;
+    private notify;
+    private applyLiveEvent;
+    respondApproval(sessionId: string, approvalId: string, result: ToolApprovalResult): Promise<void>;
+    /** Detaches this viewer and invalidates waiting sends without stopping or deleting remote work. */
+    detach(sessionId: string): Promise<void>;
+    isCloudSession(sessionId: string): boolean;
+    /** Returns a session this process already created or discovered without
+     * making account/environment availability a prerequisite for opening it. */
+    getCachedDiscoveryRecord(sessionId: string): JsonRecord | undefined;
+    /** Revalidates a cached row by id when the active-scope list does not include it. */
+    getCrossScopeDiscoveryRecord(sessionId: string): Promise<JsonRecord | undefined>;
+    list(): Promise<CloudSessionRecord[]>;
+    handoffTargetExists(sessionId: string): Promise<boolean>;
+    private preserveConnectedRuntimeModel;
+    private resolveActiveOrganizationId;
+    listRepositories(): Promise<CloudRepositoryListResult>;
+    listModels(): Promise<CloudModel[]>;
+    /** Validates account auth and GitHub access before provisioning a handoff. */
+    prepareHandoffRepository(repoUrl: string): Promise<{
+        organizationId?: string;
+    }>;
+    listBranches(repositoryId: number, options?: CloudBranchListOptions): Promise<CloudBranchListResult>;
+    listForDiscovery(options?: {
+        timeoutMs?: number;
+    }): Promise<JsonRecord[]>;
+    create(input: CreateCloudSessionInput): Promise<CloudSessionAttachment>;
+    private trackProvisioningController;
+    private abortProvisioningControllers;
+    /** Waits for an adopted pending handoff target before opening its Hub proxy. */
+    waitUntilReady(outerSessionId: string): Promise<void>;
+    /** Seeds an already-provisioned outer session when retrying a pending handoff. */
+    seedHandoff(outerSessionId: string, seed: CloudHandoffSeed): Promise<{
+        innerSessionId: string;
+    }>;
+    verifyHandoffTranscript(outerSessionId: string, expected: readonly MessageWithMetadata[], options?: {
+        allowAppendedMessages?: boolean;
+    }): Promise<void>;
+    private createOnce;
+    private deleteProvisionedSessionAfterDispose;
+    attach(outerSessionId: string, creationOptions?: CloudCreationOptions): Promise<CloudSessionAttachment>;
+    send(outerSessionId: string, prompt: string, requestedDelivery?: "queue" | "steer", modelId?: string, userImages?: string[]): Promise<{
+        sessionId: string;
+        ok: true;
+        queued?: boolean;
+        recoveredAfterDisconnect?: boolean;
+        status?: string;
+        result?: unknown;
+    }>;
+    private updateModel;
+    private applyModel;
+    private rehydrateAfterTransportDrop;
+    private performTransportRehydration;
+    abort(outerSessionId: string): Promise<{
+        sessionId: string;
+        ok: true;
+    }>;
+    pendingPrompts(outerSessionId: string): Promise<JsonRecord>;
+    updatePendingPrompt(outerSessionId: string, promptId: string, changes: {
+        prompt?: string;
+        delivery?: "queue" | "steer";
+    }): Promise<JsonRecord>;
+    removePendingPrompt(outerSessionId: string, promptId: string): Promise<JsonRecord>;
+    private queueCommand;
+    private applyQueueSnapshot;
+    readMessages(outerSessionId: string): Promise<unknown[]>;
+    updateTitle(outerSessionId: string, title: string): Promise<void>;
+    delete(outerSessionId: string): Promise<void>;
+    dispose(): Promise<void>;
+    private attachExpired;
+    private loadArchivedMessages;
+    private refreshKnownSession;
+    private ensureKnownSession;
+    private assertSessionActive;
+    private ensureConnection;
+    private resolveInnerSession;
+    private restoreSavedInnerSession;
+    private assertHandoffConnectionReusable;
+    private createInnerSession;
+    private adoptExistingHandoffSession;
+    private createInnerSessionOnce;
+    private handleEvent;
+    private forwardEvent;
+    private handleApprovalRequested;
+    private storePendingApproval;
+    private removeApproval;
+    private clearPendingApprovals;
+    private sendApprovalSnapshot;
+    private ensureAttached;
+    private subscribeToInnerSession;
+    private applySessionModel;
+    private disposeConnection;
+    /** Stop reconnecting when the sandbox is unavailable, not when lookup fails. */
+    private disposeConnectionIfSessionGone;
+}
+export {};

package/dist/cloud/index.d.ts

@@ -0,0 +1,9 @@
+/** Experimental cloud execution client. No local runtime or tool execution is initialized. */
+export * from "../services/cloud-handoff";
+export * from "./api";
+export * from "./controller";
+export * from "./models";
+export * from "./repositories";
+export * from "./snapshots";
+export { normalizeSessionTitle, resolveSessionListTitle, stringifyMessageContent, } from "./state";
+export * from "./types";