@oar-sh/oar 0.9.5 → 0.9.7

package/server/README.md

@@ -431,6 +431,135 @@ On Windows it opens a `Claude Worker <id>` terminal window.
 turns. Those replies carry no usage line rather than displaying Copilot premium-request numbers under
 a reply that never touched Copilot.
 
+## Claude Cloud provider
+
+Provider type `claude-cloud`: a provider of its own, never an alias of `claude`. Its conversations
+run Claude Code in a sandbox at Anthropic, on a clone of a GitHub repository. The worker,
+`server/claude-cloud-worker/claude-cloud-session-worker.mjs`, is a plain Node process per
+conversation that speaks the usual worker contracts (WebSocket link, heartbeat, control poller,
+crash guard) but runs no agent: it sends the user's messages to the cloud session and follows the
+session's event stream (`claude-cloud-session-process.mjs`, `claude-cloud-event-normalizer.mjs`).
+The user-facing description, including what the provider does with the Claude CLI's login, is in
+the [README](../README.md#claude-cloud); the tracker is
+[docs/feature-tracker/claude-cloud.md](../docs/feature-tracker/claude-cloud.md).
+
+### The cloud client and the login
+
+`shared/claude-cloud/api-client.mjs` (`createClaudeCloudClient`) is the only code that knows the
+cloud API: paths, headers and bodies were measured from what the Claude CLI sends, not taken from
+a documented API, so every expectation about them lives in that one file. It is SDK-free (Node's
+`fetch`), turns every failure into a `ClaudeCloudError` with a `code` (`login_missing`,
+`login_expired`, `github_not_connected`, `repo_access_denied`, `environment_missing`, `not_found`,
+`rate_limited`, `bad_request`, `transient`), and never reconnects or retries on a timer by itself.
+
+`shared/claude-cloud/credentials.mjs` (`createClaudeCloudCredentials`) is the only code that reads
+the login: `CLAUDE_CODE_OAUTH_TOKEN` from the environment, else `claudeAiOauth.accessToken` in
+`<CLAUDE_CONFIG_DIR | ~/.claude>/.credentials.json`. The token is cached until a minute before it
+expires and then read again; the refresh token is never used. The relay process has one reader and
+one client (`server-runtime.mjs`), whose `nudge` lets the CLI look at its own status
+(`claudeAuthService.getStatus({ force: true })`) at most once in five minutes; each worker builds
+its own reader, without a nudge. `applyClaudeCloudProviderEnvironment` adds no credential to the
+launch environment (`COPILOT_WEB_RELAY_WORKER_KIND=claude-cloud` and `CLAUDE_CLOUD_RELAY_MODEL`,
+nothing else). Only a relay that itself runs on `CLAUDE_CODE_OAUTH_TOKEN` passes a login on: the
+variable is one of `WORKER_SECRET_ENV_VARS`, restricted to the `claude-cloud` worker kind
+(`workerSecretEnvVarsFor`), so under tmux it reaches a cloud worker through the owner-only secret
+env file, never as an `export` and never in the environment tmux is started with, and no other
+worker kind gets it that way. `redact()` takes the token out of every error text.
+
+The client's base URL is the Anthropic API. `shared/claude-cloud/base-url.mjs`
+(`resolveClaudeCloudBaseUrl`) lets `OAR_CLAUDE_CLOUD_API_BASE_URL` replace it for tests, and only
+with an `http(s)` URL of `127.0.0.1`, `[::1]` or `localhost` without credentials; any other value
+is ignored, because the client sends the login to whatever its base URL is. The relay's client and
+the worker's both resolve it there.
+
+### Settings
+
+`services/claude-cloud-settings-service.mjs` keeps three `app_settings` rows:
+`claude_cloud_enabled` (default off), `claude_cloud_default_model` (default `claude-sonnet-5-5`)
+and `claude_cloud_environment_id`. Everything else the tab shows is read, not stored: the account
+from `claude auth status`, the login's source and expiry from `credentials.describe()`, the
+environments from the cloud (cached for a minute). **While the provider is off, nothing is asked of
+Anthropic**: the environments are listed only when it is on and a login exists. With no
+environment stored, `resolveEnvironmentId` takes the account's first active one and stores it.
+`models` is the Claude provider's model list with the `[…]` tier suffix dropped, deduplicated, the
+default first (`buildClaudeCloudModelList`). Every change is broadcast as the socket event
+`claude_cloud_settings_updated` with the GET body.
+
+Switching the provider off does not rebind anything: there is no reconciliation as for the other
+providers, and an existing cloud conversation still launches its worker.
+
+### Creating a conversation
+
+`POST /api/conversation/bootstrap` takes `providerType: 'claude-cloud'` with
+`cloudSource: { repoUrl, branch? }`. The provider is only ever asked for by name (its model ids are
+the Claude provider's own, so a model never selects it). Refusals are `400` with a `code`:
+`claude_cloud_disabled`, `claude_cloud_repo_invalid`, `claude_cloud_branch_invalid`,
+`claude_cloud_environment_missing`, and `CLAUDE_CLOUD_MODEL_UNAVAILABLE` for a model outside the
+list. The repository is normalized to `https://github.com/<owner>/<repo>`
+(`shared/claude-cloud/repo-url.mjs` → `normalizeGitHubRepoUrl`; https, ssh and scp forms of
+github.com only), the branch is checked against git's ref rules (`isValidBranchName`; empty = the
+default branch), and the result is stored in `conversations.cloud_source_json` in the same
+transaction as the conversation. Nothing is created at Anthropic here. `POST /api/message` with
+`providerType: 'claude-cloud'` on a conversation of another provider is `409
+CLAUDE_CLOUD_REQUIRES_NEW_CONVERSATION`.
+
+`POST /api/message` accepts another model of the list until the first message has created the
+cloud session, and stores it on the runtime session; after that a different model is `409
+CLAUDE_CLOUD_MODEL_REQUIRES_NEW_CONVERSATION`. The worker, however, creates the session with the
+model it was launched with: `resolveModel` prefers `CLAUDE_CLOUD_RELAY_MODEL` over the delivered
+`providerModel`, so a change made after the worker started only takes effect if the worker is
+launched again before the first message. Reasoning effort is always `none` and the context tier
+always `default`, whatever the request says.
+
+### Delivery, binding and resume
+
+`buildDequeuedRelayMessage` adds a `claudeCloud` field to every message delivered to a cloud
+worker (`buildClaudeCloudDelivery`): `{ sessionId, lastSequence, repoUrl, branch, environmentId,
+title }`. A restarted worker therefore needs nothing but the delivery. The worker reports the
+binding with `POST /api/claude-cloud-session` (`{ conversationId, cloudSessionId, sessionUrl?,
+lastSequence, pushedBranch?, costUsd?, model? }`) after it created the session, after every
+`result`, and on a push. `recordWorkerReport` (`services/claude-cloud-session-service.mjs`) stores
+the session id, the sequence (never moved back) and the cost on the runtime session row, keeps the
+session link and the list of pushed branches (the newest 20) in `cloud_source_json`, and emits the
+socket event `claude_cloud_session` with `{ conversationId, cloud }`. A report that names another
+cloud session than the stored one starts sequence, cost and pushed branches again.
+
+The conversation list, the conversation payload and the bootstrap answer carry the same `cloud`
+field: `{ repoUrl, slug, branch, sessionUrl, pushedBranches: [{ branch, at }], costUsd }`, or
+`null` for a conversation that is not a cloud one. There is no session root for a cloud
+conversation (`buildConversationSessionRootPayload` returns `null`).
+
+### Usage
+
+The worker posts to the Claude worker's two usage routes. `POST /api/claude-context-usage` accepts
+a `claude-cloud` conversation and stores the session's context occupancy (used and maximum tokens,
+no categories) in `runtime_sessions.context_usage_json`, which `GET /api/context/:id` serves.
+`POST /api/claude-plan-usage` keeps a cloud worker's report under its own snapshot key
+(`claude-cloud`), so the Claude card stays what the Claude workers wrote.
+
+`GET /api/usage` builds two things from the cloud client while the provider is on
+(`services/claude-account-usage-service.mjs`: the usage body, the prepaid credits and the credit
+offer, read without a model turn, cached for 60 s, a failed read for 15 s; the route waits at most
+3 s for them and falls back to the last turn's snapshot. Nothing is read and nothing cached is
+handed out while the provider is off):
+
+- the **Claude card's** live windows (`normalizeClaudeAccountUsage` in
+  `services/plan-usage-claude.mjs`): the 5-hour, weekly and model-scoped windows with the
+  account's own severity word, the week by product, and the organisation's prepaid credits;
+- the **Claude Cloud card** (`services/plan-usage-claude-cloud.mjs` → `buildClaudeCloudPlanCard`):
+  one meter per top-level bucket of the usage body that carries a dollar limit (the cloud credit,
+  with its expiry), the relay's own cloud spend (`readClaudeCloudSpend`: the sum of
+  `runtime_sessions.claude_cloud_cost_usd` over the cloud conversations that still exist, plus the
+  cost of the conversation named by `?conversationId=`), the latest cloud snapshot's session
+  detail, and a note when a credit is offered but not claimed.
+
+### Archive
+
+`DELETE /api/conversation/:id` and `POST /api/conversation/:id/archive` call
+`archiveSessionInBackground` for a cloud conversation: the cloud session is archived at Anthropic,
+best effort and not waited for, so neither action ever depends on Anthropic. Nothing is deleted
+there.
+
 ## Cursor Agent SDK provider
 
 Cursor conversations run through `server/cursor-worker/cursor-session-worker.mjs`, a per-conversation
@@ -792,13 +921,14 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | GET | `/api/git/status` | Git status for the conversation's workspace root (`branch`, `upstream`, `ahead`, `behind`, `files[]` incl. untracked); a non-repo root returns `isRepo: false` rather than an error |
 | GET | `/api/git/diff` | Full-context unified diff for one changed file (`path`, optional `untracked=1`); the client renders both "changes only" and "full file" views from this single patch |
 | POST | `/api/git/pull` | Run `git pull` in the conversation's workspace root and return the combined output |
+| GET | `/api/git/remote` | Where a folder lives on GitHub, for the New Chat modal of a Claude Cloud chat: `?root=<absolute path>` → `{ ok, root, hasGit, remoteUrl, repoUrl, slug, branch, upstream, ahead, behind, dirty }`. The one git route that takes a path from the client; it passes the same policy as a requested CWD (`403` outside `workspaceRootAllowList`, `400` otherwise). Read-only (`git status`, `git remote get-url`) |
 | GET | `/api/conversations` | List all conversations |
 | GET | `/api/sessions` | List runtime sessions bound 1:1 to conversations |
 | GET | `/api/conversation/:id` | Get conversation message windows (`before*`, `after*`, or `aroundMessageId`) plus session-root metadata |
 | GET | `/api/search/messages` | Search message text across all conversations (`q`, `limit`, `offset`) |
 | PATCH | `/api/conversation/:id` | Update a conversation title |
 | POST | `/api/conversation/:id/compact` | Compact a conversation into a new one with carry-over summary seed |
-| DELETE | `/api/conversation/:id` | Delete a conversation: stops its session worker, deletes its CLI session, removes its rows. A Copilot session the relay only imported and never ran is hidden and tombstoned instead: nothing is stopped and its CLI session is kept. `409 conversation-active` (`reason: turn-running` / `background-tasks`) while it is still working; `409 worker-stop-failed` when its worker survives the stop (nothing deleted) |
+| DELETE | `/api/conversation/:id` | Delete a conversation: stops its session worker, deletes its CLI session, removes its rows. A Claude Cloud conversation's cloud session is archived at Anthropic in the background (never waited for). A Copilot session the relay only imported and never ran is hidden and tombstoned instead: nothing is stopped and its CLI session is kept. `409 conversation-active` (`reason: turn-running` / `background-tasks`) while it is still working; `409 worker-stop-failed` when its worker survives the stop (nothing deleted) |
 | GET | `/api/sdk-session-delete/pending` | (CLI relay) Fetch next pending SDK session delete request |
 | POST | `/api/sdk-session-delete/result` | (CLI relay) Report SDK session delete result |
 | POST | `/api/session-sync` | (CLI relay) Sync conversation↔SDK binding and optionally confirm orchestrator rebind completion |
@@ -822,20 +952,23 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | GET | `/api/models` | Live/cached model catalog used by the UI picker |
 | POST | `/api/models/snapshot` | (CLI/relay) Publish discovered model snapshot |
 | POST | `/api/conversation/:id/refresh-history` | Re-import an existing conversation's history through the local Copilot SDK |
-| GET | `/api/context/:conversationId` | Context metrics for a conversation or `sdk_session_id`. Copilot sessions are parsed from session-state events (falling back to a labeled lower-bound completion-token estimate when full legacy buckets are missing); Claude sessions are served from the breakdown their worker stored. Both return the same normalized `contextUsage` view alongside `providerType` and the runtime's own `text` dump |
+| GET | `/api/context/:conversationId` | Context metrics for a conversation or `sdk_session_id`. Copilot sessions are parsed from session-state events (falling back to a labeled lower-bound completion-token estimate when full legacy buckets are missing); Claude sessions are served from the breakdown their worker stored, and so are Cursor, Grok and Claude Cloud sessions. All return the same normalized `contextUsage` view alongside `providerType` and the runtime's own `text` dump |
 | GET | `/api/context` | Same payload when a `conversationId` query is provided; otherwise returns a missing-selection response |
-| GET | `/api/usage` | Unified plan usage: one card per configured provider (`providers[]` with `meters`, `details`, `links`) built from the live Copilot quota, the Claude worker's latest stored snapshot, and the derived Cursor cycle totals. A provider that cannot be read yields an unavailable card rather than failing the response, so the modal always renders. Legacy top-level Copilot quota fields are spread alongside `providers` for cached clients; `?legacy=1` returns the Copilot-only snapshot on its own |
+| GET | `/api/usage` | Unified plan usage: one card per configured provider (`providers[]` with `meters`, `details`, `links`) built from the live Copilot quota, the Claude worker's latest stored snapshot, and the derived Cursor cycle totals. A provider that cannot be read yields an unavailable card rather than failing the response, so the modal always renders. While Claude Cloud is on, the Claude card's windows are read live from the account, and a Claude Cloud card is added (credit meters, the relay's cloud spend, and the cost of the conversation named by `?conversationId=` when it is a cloud one); a card may carry `notes[]` (a line of text with an optional https link), and a meter `severity` and `resetKind: 'expiry'`. Legacy top-level Copilot quota fields are spread alongside `providers` for cached clients; `?legacy=1` returns the Copilot-only snapshot on its own |
 | GET | `/api/settings/cursor-allowance` | Read the manual Cursor plan allowances (`cursorModelsUsd`, `otherModelsUsd`, `resetDay`) |
 | POST | `/api/settings/cursor-allowance` | Set the Cursor pool allowances and billing reset day; `null` clears an allowance, and `resetAccounting: true` re-baselines the derived spend tracking |
 | GET | `/api/settings/claude` | Read Claude provider settings (`enabled`, `model`, `models`, `availableModels`) |
 | POST | `/api/settings/claude` | Enable/disable Claude, set the default model or the enabled model subset; triggers discovery and unstarted-conversation reconciliation |
+| GET | `/api/settings/claude-cloud` | Read Claude Cloud settings: `{ enabled, defaultModel, environmentId, environments: [{ id, name }] \| null, environmentsError, account: { loggedIn, email, orgName, subscriptionType } \| null, token: { source, hasToken, expiresAt }, models }`. `token` says where the login is read from (`env`, `file`, `none`) and when it runs out, never the token. `environments` is `null` while the provider is off or the host has no login: nothing is asked of Anthropic then |
+| POST | `/api/settings/claude-cloud` | `{ enabled?, defaultModel?, environmentId? }` → `{ ok: true, …the GET body }`. Enabling without a Claude login on the host is `400` with `code: 'claude_cloud_login_missing'`; an empty `environmentId` clears the stored one. Emits `claude_cloud_settings_updated` |
 | GET | `/api/settings/cursor` | Read Cursor provider settings — same shape as Claude's: `models` is the enabled subset, `availableModels` the full discovered list, plus per-model `efforts` |
 | POST | `/api/settings/cursor` | Set/remove the Cursor API key, default model, or enabled model subset; key changes reset discovered models and effort tiers |
 | GET | `/api/settings/turn-ceiling` | Read the max turn duration plus slider bounds (`minMinutes`, `maxMinutes`, `stepMinutes`, `defaultMinutes`) |
 | POST | `/api/settings/turn-ceiling` | Set the max turn duration in minutes (`0` = no limit) |
 | POST | `/api/claude-native-session` | (Claude worker) Persist the native Agent SDK session id for resume |
-| POST | `/api/claude-context-usage` | (Claude worker) Report the session's context-window breakdown after a turn |
-| POST | `/api/claude-plan-usage` | (Claude worker) Report the session's structured `/usage` data — plan rate-limit windows plus session cost totals — falling back to the stable `modelUsage`/`totalCostUsd` result fields. Stored as the latest Claude snapshot |
+| POST | `/api/claude-context-usage` | (Claude and Claude Cloud workers) Report the session's context-window breakdown after a turn; `409` for a conversation of any other provider |
+| POST | `/api/claude-plan-usage` | (Claude and Claude Cloud workers) Report the session's structured `/usage` data — plan rate-limit windows plus session cost totals — falling back to the stable `modelUsage`/`totalCostUsd` result fields. Stored as the latest Claude snapshot; a Claude Cloud conversation's report is stored under its own snapshot key, `claude-cloud` |
+| POST | `/api/claude-cloud-session` | (Claude Cloud worker) Report the cloud session a conversation is bound to: `{ conversationId, cloudSessionId, sessionUrl?, lastSequence, pushedBranch?, costUsd?, model? }` → `{ ok, cloud }`. Sent after the session was created, after every `result` and on a push; emits `claude_cloud_session`. `404` without a runtime session, `409` for a conversation that is not a cloud one |
 | POST | `/api/cursor-plan-usage` | (Cursor worker) Report the agent's cumulative billed usage; the relay diffs it against a per-agent checkpoint and books the increase into the current billing cycle under the pool implied by the turn's model |
 | POST | `/api/subagent-run` | (Worker) Register/update a subagent run for the active turn |
 | POST | `/api/conversation/:conversationId/subagent/:subagentRunId/cancel` | Request cancellation of one subagent run (unsupported by the Claude runtime) |
@@ -853,10 +986,12 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | DELETE | `/api/remote-relays/:id` | Remove a paired relay here (the other side keeps its entry) |
 | POST | `/api/remote-relays/:id/check` | Probe a paired relay now |
 | POST | `/api/remote-relays/pair` | (Relay to relay) Another relay introduces itself after the user paired it there |
-| GET | `/api/remote-relays/summary` | (Worker) Number of paired relays; workers register `remote_relay` only when it is above zero |
-| POST | `/api/remote-relays/tool` | (Worker) One `remote_relay` tool call: `{ conversationId, action, args }`. The relay checks the mention unlock, the permission, the hop limit and (ask/plan mode) the user's approval, then forwards the call to the remote |
+| GET | `/api/remote-relays/summary` | (Worker) `{ count, online, localEnabled }`: the number of paired relays, how many of them are online, and whether agent sessions are switched on. Workers register `remote_relay` when `count` is above zero or `localEnabled` is `true` |
+| POST | `/api/remote-relays/tool` | (Worker) One `remote_relay` tool call: `{ conversationId, action, args }`. For a paired relay the relay checks the mention unlock, the permission, the hop limit and (ask/plan mode) the user's approval, then forwards the call to the remote. For this relay itself (named by its name or `this`; refused with `REMOTE_RELAY_LOCAL_DISABLED` while agent sessions are off) it checks instead that the call does not aim at the caller's own conversation (`REMOTE_RELAY_OWN_SESSION`) and, for `create_session`, that the caller was not created by an agent (`REMOTE_RELAY_NESTED_SESSION`), that fewer than 4 sessions it created have a turn queued or running (`REMOTE_RELAY_SESSION_LIMIT`) and that the user allowed it once for the conversation; the call then runs against this relay's own routes in-process. `wait_seconds` is cut to the `maxWaitSeconds` setting for every target |
 | GET | `/api/remote-relays/inflight` | (Worker) Number of `remote_relay` calls running for `conversationId` |
 | GET/POST | `/api/settings/remote-relays` | This relay's `publicUrl` and `inboundEnabled` (accept prompts from other relays' agents) |
+| GET | `/api/settings/agent-sessions` | Agent sessions: `{ enabled, maxWaitSeconds, limits: { minWaitSeconds: 120, maxWaitSeconds: 3600, stepSeconds: 60 }, maxActiveSessions: 4 }`. `enabled` (default `false`) lets this relay's agents start and use sessions on it through `remote_relay`; `maxWaitSeconds` (default `600`) is the longest wait of one `remote_relay` call, for this relay and paired ones |
+| POST | `/api/settings/agent-sessions` | `{ enabled?, maxWaitSeconds? }` → `{ ok: true, …the GET body }`, and the socket event `agent_sessions_settings_updated` with the GET body. `enabled` must be a boolean and `maxWaitSeconds` a whole number of seconds inside `limits` and on its step; anything else is `400` with `{ ok: false, error }` and nothing is stored |
 
 ### Manual relay shutdown / self-restart
 
@@ -1015,6 +1150,14 @@ workspace root, backed by `services/git-changes-service.mjs` and `routes/git-rou
 File paths passed to `/api/git/diff` go through the same `resolveWorkspaceFilePath` containment
 check as the file bridge, so traversal outside the workspace root is rejected.
 
+`GET /api/git/remote?root=…` belongs to the New Chat modal, not to this one: it reads the `origin`
+remote (else the remote of the upstream branch), the current branch, ahead/behind and whether the
+checkout is dirty, for the Repository and Branch fields of a Claude Cloud chat
+(`services/git-remote-service.mjs`). There is no conversation yet at that point, so it is the one
+git route that takes a path from the client, validated like a requested CWD
+(`validateRequestedWorkspaceRoot`). Credentials in a remote URL are dropped before it is returned,
+and a remote that is not a github.com repository comes back with `repoUrl: null`.
+
 ### Changing the launch CWD
 
 Two endpoints set a conversation's launch directory. Both accept the same aliases —
@@ -1417,6 +1560,23 @@ and on `messages`:
 `0005-remote-relays.mjs` adds `origin_json` to `messages` and `conversations` (provenance of
 prompts and sessions another relay's agent created) and the table
 `conversation_remote_relay_unlocks` (the remote relays the user mentioned per conversation).
+Agent sessions reuse both without a migration of their own: a conversation an agent of this relay
+created stores an origin with `local: true` that names the conversation it was created from, and
+the user's **Allow** for a conversation's agent to start sessions here is a row of that table
+under the relay id `self` (`remote-relay-repository.mjs`).
+
+`0007-claude-cloud.mjs` adds the storage of [Claude Cloud](#claude-cloud-provider) conversations.
+It is additive and idempotent, runs on every boot, and a failure is logged and retried on the next
+one:
+
+- `runtime_sessions.claude_cloud_session_id` (TEXT) — the cloud session the conversation runs in,
+  reported by its worker after the first message
+- `runtime_sessions.claude_cloud_last_sequence` (TEXT) — the event sequence number of the last
+  finished turn's `result`: where a restarted worker reads the session's event log on from
+- `runtime_sessions.claude_cloud_cost_usd` (REAL) — what the session has cost so far, as the cloud
+  reports it
+- `conversations.cloud_source_json` (TEXT/JSON) — `{ repoUrl, branch, environmentId, sessionUrl,
+  pushedBranches: [{ branch, at }] }`
 
 New tables are likewise created at startup with `CREATE TABLE IF NOT EXISTS` in both the fresh-schema
 and migration blocks — most recently `workflow_runs` (final workflow digest per assistant message,
@@ -1449,6 +1609,13 @@ working with the corresponding feature inert rather than crashing at startup.
 | `data/copilot.db` | Persisted conversations, settings, and queue storage (gitignored) |
 | `relay-tools.md` | Markdown tool guidance loaded by the relay extension |
 | `claude-worker/` | Claude Agent SDK session worker (turn runner, ask-user bridge, attachments, SDK message normalizer) |
+| `claude-cloud-worker/` | Claude Cloud session worker (turn runner over the cloud session's event stream, event normalizer) |
+| `../shared/claude-cloud/` | Claude Cloud API client, the reader of the Claude CLI's login, repository/branch/model string rules |
+| `services/claude-cloud-settings-service.mjs` | Claude Cloud switch, default model and environment |
+| `services/claude-cloud-session-service.mjs` | What the relay keeps per cloud conversation: worker reports, the `cloud` payload field, archiving |
+| `services/claude-account-usage-service.mjs` | Live Claude account usage for Check Usage (only while Claude Cloud is on) |
+| `services/git-remote-service.mjs` | GitHub remote and branch of a folder, for the New Chat modal |
+| `services/remote-relay-loopback.mjs` | The `remote_relay` client for this relay itself (agent sessions): hands the dispatcher's requests to the relay's own HTTP handler in-process instead of opening a connection |
 | `services/claude-session-root-service.mjs` | Resolves the browsable session folder for Claude conversations |
 | `services/context-usage-view.mjs` | Normalizes Copilot and Claude context data into one payload |
 | `services/cloudflared-tunnel-service.mjs` | Supervises the `cloudflared` child process for the Cloudflare Tunnel mode |

package/server/claude-cloud-worker/claude-cloud-event-normalizer.mjs

@@ -0,0 +1,340 @@
+import { capThought } from '../../shared/thought-cap.mjs';
+import {
+  compactBoundaryActivityAction,
+  displayToolName,
+  formatApiRetryNotice,
+  formatToolActivityText,
+  isSubagentToolName,
+} from '../claude-worker/sdk-message-normalizer.mjs';
+
+const MAX_ACTIVITY_LENGTH = 140;
+const REDACTED_THINKING_PLACEHOLDER = '[Reasoning redacted by the model provider]';
+// The cloud sends most thinking blocks with the text left out (a signature
+// only): the bubble says that the model thought rather than showing nothing.
+const EMPTY_THINKING_PLACEHOLDER = '[Thinking — the cloud does not show the text]';
+// Sandbox log lines worth a row: a step that begins, is skipped or fails.
+// Each step also logs its completion, and lines without a step are the
+// runner talking to itself (the path it launches the CLI from).
+const QUIET_STEP_STATUSES = new Set(['completed']);
+const LOUD_LOG_LEVELS = new Set(['warn', 'warning', 'error']);
+
+function truncate(text, maxLength = MAX_ACTIVITY_LENGTH) {
+  const value = String(text || '').trim();
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+
+function finiteOrNull(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** The sequence number of a cloud event (`sequence_num` is a string on the wire), or null. */
+export function toCloudSequence(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+/**
+ * A turn the user stopped ends with an error result too
+ * (`error_during_execution`, `terminal_reason: "aborted_tools"`); what tells
+ * it from a failure is the terminal reason.
+ */
+export function isInterruptedCloudResult(payload) {
+  return String(payload?.terminal_reason || '').trim().toLowerCase().startsWith('aborted');
+}
+
+/** The `result` payload of a turn in the shape the Claude worker's publisher reads. */
+export function readCloudResult(payload) {
+  const subtype = String(payload?.subtype || '').trim();
+  const errors = (Array.isArray(payload?.errors) ? payload.errors : [])
+    .map((entry) => String(entry || '').trim())
+    .filter(Boolean);
+  const apiErrorStatus = Number(payload?.api_error_status ?? NaN);
+  return {
+    // An interrupted or failed turn carries no `result` string at all.
+    text: typeof payload?.result === 'string' ? payload.result.trim() : '',
+    isError: subtype !== 'success' || payload?.is_error === true,
+    subtype,
+    interrupted: isInterruptedCloudResult(payload),
+    terminalReason: String(payload?.terminal_reason || '').trim(),
+    assistantError: '',
+    apiErrorStatus: Number.isFinite(apiErrorStatus) ? apiErrorStatus : null,
+    errors,
+    modelUsage: payload?.modelUsage && typeof payload.modelUsage === 'object' ? payload.modelUsage : null,
+    totalCostUsd: finiteOrNull(payload?.total_cost_usd),
+  };
+}
+
+/**
+ * What `GET /v1/code/sessions/{id}` says after a turn, for the relay's usage
+ * routes: the context occupancy in the shape `/api/claude-context-usage`
+ * stores, the session's cost so far, and the session's page on claude.ai.
+ * Accepts the bare `response_shape` or the body that wraps it.
+ */
+export function readCloudSessionUsage(sessionBody, { model = '' } = {}) {
+  const shape = sessionBody?.response_shape || sessionBody?.raw?.response_shape || sessionBody || {};
+  const metadata = shape?.external_metadata && typeof shape.external_metadata === 'object'
+    ? shape.external_metadata
+    : {};
+  const usage = metadata.usage && typeof metadata.usage === 'object' ? metadata.usage : {};
+  const usedTokens = finiteOrNull(metadata.context_usage?.used_tokens);
+  const maxTokens = finiteOrNull(metadata.context_usage?.max_tokens);
+  const contextUsage = usedTokens === null && maxTokens === null
+    ? null
+    : {
+      model: String(metadata.last_served_model || model || '').trim() || null,
+      totalTokens: usedTokens,
+      maxTokens,
+      percentage: usedTokens !== null && maxTokens ? Math.round((usedTokens / maxTokens) * 10000) / 100 : null,
+      categories: [],
+      apiUsage: {
+        input_tokens: finiteOrNull(usage.input_tokens),
+        output_tokens: finiteOrNull(usage.output_tokens),
+        cache_read_input_tokens: finiteOrNull(usage.cache_read_tokens),
+        cache_creation_input_tokens: finiteOrNull(usage.cache_write_tokens),
+      },
+    };
+  return {
+    contextUsage,
+    costUsd: finiteOrNull(usage.cost_usd),
+    sessionUrl: String(shape?.session_url || sessionBody?.sessionUrl || '').trim() || null,
+    workerStatus: String(shape?.worker_status || '').trim().toLowerCase() || null,
+  };
+}
+
+/**
+ * Stateful normalizer mapping the events of one cloud turn onto relay channel
+ * actions. One instance per turn. The event `payload` is the plain SDK
+ * message, delivered one complete content block per `assistant` event and
+ * without partial frames.
+ *
+ * `normalize(event, { sequence })` takes the event envelope
+ * (`{ event_type, source, sequence_num, payload }`) and returns
+ * `{ channel, payload }` actions:
+ * - `init`       → `{ model }`
+ * - `stream`     → `{ text, done:false }`: every text block of the turn so far,
+ *   blank line between blocks
+ * - `thought`    → `{ reasoningId, text, done:true }`
+ * - `activity`   → `{ text, subagentRunId? }`
+ * - `subagent`   → `{ subagentRunId, parentSubagentId, displayName, status }`
+ * - `push`       → `{ branch }` (the agent pushed a branch)
+ * - `permission` → `{ requestId, toolName, displayName, input, toolUseId }`
+ *   (the agent waits for the user: a question or a permission prompt)
+ * - `permission_settled` → `{ requestId }` (some client answered it)
+ *
+ * The turn's `result` is not an action: the runner pairs it with the turn by
+ * sequence number and reads it with `readCloudResult`.
+ */
+export function createClaudeCloudEventNormalizer() {
+  const textBlocks = [];
+  const knownSubagentRuns = new Map(); // toolUseId -> { displayName, parentSubagentId }
+  let model = '';
+  let lastSandboxLine = '';
+  let lastRateLimitStatus = 'allowed';
+
+  function streamText() {
+    return textBlocks.join('\n\n');
+  }
+
+  function sandboxLogActions(payload) {
+    const data = payload?.data && typeof payload.data === 'object' ? payload.data : {};
+    const content = String(data.content || '').trim();
+    if (!content) return [];
+    const stepStatus = String(data.extra?.step_status || '').trim().toLowerCase();
+    const loud = LOUD_LOG_LEVELS.has(String(data.level || '').trim().toLowerCase());
+    if (!loud && (!stepStatus || QUIET_STEP_STATUSES.has(stepStatus))) return [];
+    const text = truncate(`Cloud: ${content}`);
+    if (text === lastSandboxLine) return [];
+    lastSandboxLine = text;
+    return [{ channel: 'activity', payload: { text, subagentRunId: null } }];
+  }
+
+  function assistantActions(payload, sequence) {
+    const actions = [];
+    const parentToolUseId = String(payload?.parent_tool_use_id || '').trim() || null;
+    const content = Array.isArray(payload?.message?.content) ? payload.message.content : [];
+    for (const [index, block] of content.entries()) {
+      const blockType = String(block?.type || '');
+      if (blockType === 'text') {
+        // Only the main thread's prose is the reply; a subagent's text is its
+        // own report to the agent that started it.
+        const text = String(block?.text || '').trim();
+        if (parentToolUseId || !text) continue;
+        textBlocks.push(text);
+        actions.push({ channel: 'stream', payload: { text: streamText(), done: false, subagentRunId: null } });
+        continue;
+      }
+      if (blockType === 'thinking' || blockType === 'redacted_thinking') {
+        const text = blockType === 'redacted_thinking'
+          ? (String(block?.data || '').trim() ? REDACTED_THINKING_PLACEHOLDER : '')
+          : (capThought(block?.thinking || '').trim() || (String(block?.signature || '').trim() ? EMPTY_THINKING_PLACEHOLDER : ''));
+        if (!text.trim()) continue;
+        actions.push({
+          channel: 'thought',
+          payload: {
+            // Keyed by the event's sequence number: a replayed event (stream
+            // reconnect, catch-up after a restart) updates its thought in
+            // place instead of adding a second one.
+            reasoningId: `claude-cloud-thought-${sequence ?? 'x'}-${index}`,
+            text,
+            done: true,
+            subagentRunId: parentToolUseId,
+          },
+        });
+        continue;
+      }
+      if (blockType === 'tool_use') {
+        const toolName = displayToolName(block?.name) || 'unknown';
+        const toolUseId = String(block?.id || '').trim();
+        const input = block?.input && typeof block.input === 'object' ? block.input : {};
+        if (isSubagentToolName(toolName) && toolUseId) {
+          const displayName = String(input.description || input.name || input.subagent_type || 'Subagent').trim()
+            || 'Subagent';
+          knownSubagentRuns.set(toolUseId, { displayName, parentSubagentId: parentToolUseId });
+          actions.push({
+            channel: 'subagent',
+            payload: { subagentRunId: toolUseId, parentSubagentId: parentToolUseId, displayName, status: 'running' },
+          });
+        }
+        actions.push({
+          channel: 'activity',
+          payload: { text: formatToolActivityText(toolName, input), subagentRunId: parentToolUseId },
+        });
+      }
+    }
+    return actions;
+  }
+
+  function toolResultActions(payload) {
+    const actions = [];
+    const parentToolUseId = String(payload?.parent_tool_use_id || '').trim() || null;
+    const content = Array.isArray(payload?.message?.content) ? payload.message.content : [];
+    for (const block of content) {
+      if (block?.type !== 'tool_result') continue;
+      const toolUseId = String(block?.tool_use_id || '').trim();
+      const isError = block?.is_error === true;
+      const run = toolUseId ? knownSubagentRuns.get(toolUseId) : null;
+      if (run) {
+        actions.push({
+          channel: 'subagent',
+          payload: {
+            subagentRunId: toolUseId,
+            parentSubagentId: run.parentSubagentId,
+            displayName: run.displayName,
+            status: isError ? 'failed' : 'completed',
+          },
+        });
+      }
+      if (isError) {
+        const errorText = typeof block?.content === 'string'
+          ? block.content
+          : (Array.isArray(block?.content) ? block.content.map((entry) => String(entry?.text || '')).join(' ') : '');
+        actions.push({
+          channel: 'activity',
+          payload: { text: truncate(`Tool failed: ${errorText || 'unknown error'}`), subagentRunId: parentToolUseId },
+        });
+      }
+    }
+    return actions;
+  }
+
+  function systemActions(payload) {
+    const subtype = String(payload?.subtype || '');
+    if (subtype === 'init') {
+      // Every turn of a cloud session opens with its own init.
+      model = String(payload?.model || '').trim() || model;
+      return [
+        { channel: 'init', payload: { model } },
+        {
+          channel: 'activity',
+          payload: { text: `Claude Code running in the cloud${model ? ` (model ${model})` : ''}`, subagentRunId: null },
+        },
+      ];
+    }
+    if (subtype === 'vcs_state_changed') {
+      const branch = String(payload?.branch || '').trim();
+      if (String(payload?.kind || '').trim().toLowerCase() !== 'push' || !branch) return [];
+      return [
+        { channel: 'activity', payload: { text: truncate(`Cloud: pushed branch ${branch}`), subagentRunId: null } },
+        { channel: 'push', payload: { branch } },
+      ];
+    }
+    if (subtype === 'task_notification') {
+      const taskId = String(payload?.task_id || '').trim() || 'unknown';
+      const status = String(payload?.status || '').trim() || 'unknown';
+      return [{
+        channel: 'activity',
+        payload: {
+          text: truncate(`Background task ${taskId} ${status}: ${String(payload?.summary || '').trim()}`),
+          subagentRunId: null,
+        },
+      }];
+    }
+    if (subtype === 'api_retry') {
+      return [{ channel: 'activity', payload: { text: formatApiRetryNotice(payload), subagentRunId: null } }];
+    }
+    if (subtype === 'compact_boundary') return [compactBoundaryActivityAction(payload)];
+    return [];
+  }
+
+  function rateLimitActions(payload) {
+    const info = payload?.rate_limit_info && typeof payload.rate_limit_info === 'object' ? payload.rate_limit_info : {};
+    const status = String(info.status || '').trim().toLowerCase() || 'allowed';
+    if (status === lastRateLimitStatus) return [];
+    lastRateLimitStatus = status;
+    if (status === 'allowed') return [];
+    const resetsAt = Number(info.resetsAt);
+    const reset = Number.isFinite(resetsAt) && resetsAt > 0
+      ? `, resets ${new Date(resetsAt * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z')}`
+      : '';
+    const text = status === 'rejected'
+      ? `Claude usage limit reached${reset}`
+      : `Claude usage limit warning (${status.replace(/_/g, ' ')}${reset})`;
+    return [{ channel: 'activity', payload: { text: truncate(text), subagentRunId: null } }];
+  }
+
+  function controlActions(event, payload) {
+    if (payload.type === 'control_response') {
+      const requestId = String(payload?.response?.request_id || '').trim();
+      return requestId ? [{ channel: 'permission_settled', payload: { requestId } }] : [];
+    }
+    // The clients' own requests (set_permission_mode, interrupt) come back on
+    // the stream as well; only the agent's requests ask the user something.
+    if (String(event?.source || '').trim().toLowerCase() === 'client') return [];
+    const request = payload?.request && typeof payload.request === 'object' ? payload.request : {};
+    const requestId = String(payload?.request_id || '').trim();
+    if (request.subtype !== 'can_use_tool' || !requestId) return [];
+    return [{
+      channel: 'permission',
+      payload: {
+        requestId,
+        toolName: String(request.tool_name || '').trim(),
+        displayName: String(request.display_name || request.tool_name || '').trim(),
+        input: request.input && typeof request.input === 'object' ? request.input : {},
+        toolUseId: String(request.tool_use_id || '').trim() || null,
+      },
+    }];
+  }
+
+  function normalize(event, { sequence = toCloudSequence(event?.sequence_num) } = {}) {
+    const payload = event?.payload;
+    if (!payload || typeof payload !== 'object') return [];
+    const type = String(payload.type || event.event_type || '');
+    if (type === 'env_manager_log') return sandboxLogActions(payload);
+    if (type === 'system') return systemActions(payload);
+    if (type === 'assistant') return assistantActions(payload, sequence);
+    if (type === 'user') return toolResultActions(payload);
+    if (type === 'rate_limit_event') return rateLimitActions(payload);
+    if (type === 'control_request' || type === 'control_response') return controlActions(event, { ...payload, type });
+    return [];
+  }
+
+  return {
+    normalize,
+    streamText,
+    get model() { return model; },
+  };
+}