@aexol/spectral 0.9.234 → 0.9.241

package/README.md

@@ -53,6 +53,11 @@ Requires Node.js **20 or newer**.
    can create projects, open sessions, and chat with the agent on that machine
    from any tab.
 
+   Steps 2 and 3 are one command: `spectral desktop`. It starts `serve` as a
+   background daemon (survives closing the terminal), waits until the relay is
+   genuinely connected, then opens the UI in your default browser — see
+   [`spectral desktop`](#spectral-desktop).
+
 You can also run Spectral as a plain local TUI without the relay — just invoke
 `spectral` (no subcommand) and it acts as a normal pi terminal session with the
 Aexol MCP extension auto-loaded.
@@ -65,6 +70,7 @@ Aexol MCP extension auto-loaded.
 | `spectral login`     | Interactive auth. Verifies the key against the MCP backend and stores it.   |
 | `spectral logout`    | Removes `~/.spectral/config.json`. Idempotent.                              |
 | `spectral serve`     | Connect this machine to the Aexol relay. Stays up; survives reconnects.     |
+| `spectral desktop`   | Start `serve` as a daemon, wait for it, open the UI. `status` / `stop` too. |
 | `spectral --version` | Print version.                                                              |
 | `spectral --help`    | Print Spectral header, then pi's full help.                                 |
 
@@ -74,6 +80,39 @@ Aexol MCP extension auto-loaded.
 | ----------------------- | ----------------------------------------------------- |
 | `--machine-name <name>` | Override the display name (default: `os.hostname()`). |
 
+### `spectral desktop`
+
+The headless replacement for the removed Electron app: same lifecycle, no
+bundled browser, and the UI is your own browser at
+`https://aexol.ai/agent` (override with `SPECTRAL_LANDING_URL`).
+
+| Command                 | Description                                                            |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `spectral desktop`      | Start the agent, or reuse the one already running, then open the UI.    |
+| `spectral desktop status` | Report pid / version / readiness signal. Exit `3` when not running.   |
+| `spectral desktop stop` | SIGTERM, then SIGKILL after 10s. Removes the pid / ready files.         |
+
+Mechanics worth knowing:
+
+- Single instance via `~/.spectral/serve.pid`, claimed atomically (`O_EXCL`)
+  *before* the daemon is spawned — two simultaneous `spectral desktop` runs
+  start exactly one daemon. A dead pid is detected and pruned, so a crashed
+  daemon never blocks the next start, and a pid file held by a process this
+  command did not launch is never overwritten or deleted.
+- If `~/.spectral/config.json` has no Studio token, `desktop` runs the
+  interactive `spectral login` flow first (and refuses to prompt when there is
+  no terminal, telling you to run `spectral login` yourself).
+- Readiness is a real signal, not a timeout: the daemon prints
+  `SPECTRAL_SERVE_READY` once the relay WebSocket opens and writes
+  `serve-ready.json`. Opening the UI only after that avoids the
+  `machine_disconnected` flash you get if the page subscribes before the socket
+  exists.
+- `~/.spectral/serve.log` is created `0600` and rotated to `serve.log.old` at
+  start once it passes 10 MB (`SPECTRAL_DESKTOP_LOG_MAX_BYTES`).
+- The daemon is spawned detached with an augmented `PATH` (`/etc/paths`,
+  `getconf PATH`, Homebrew/nvm/Node dirs), so MCP servers declared as
+  `npx -y <pkg>` work even when Spectral was launched from a GUI context.
+
 Anything that isn't a Spectral subcommand is forwarded verbatim to pi, so any pi
 flag you know works. Example: `spectral -p "summarize this repo"`.
 
@@ -139,10 +178,18 @@ behaves like a vanilla pi install.
 | `~/.spectral/config.json`  | Aexol MCP URL + team API key. Created by `spectral login`. Mode `0600`. |
 | `~/.spectral/machine.json` | Machine identity + relay JWT. Created on first `spectral serve`.        |
 | `~/.spectral/sessions.db`  | Local SQLite for projects, sessions, messages.                          |
+| `~/.spectral/serve.pid`    | Relay daemon pid (single-instance lock). Pruned when stale.             |
+| `~/.spectral/serve-ready.json` | `{pid, ts, version}` written when the relay socket opens.            |
+| `~/.spectral/serve.log`    | Daemon stdout/stderr, written by `spectral desktop`.                    |
 | `SPECTRAL_CONFIG_DIR`      | Override the directory above.                                           |
 | `SPECTRAL_MCP_URL`         | Override the MCP URL at login time.                                     |
 | `SPECTRAL_BACKEND_URL`     | Override the backend HTTP base for `spectral serve`.                    |
 | `SPECTRAL_RELAY_URL`       | Override the derived relay WebSocket URL.                               |
+| `SPECTRAL_LANDING_URL`     | UI that `spectral desktop` opens (default `https://aexol.ai/agent`).    |
+| `SPECTRAL_SERVE_LOG_PATH`  | Daemon log path for `spectral desktop`.                                 |
+| `SPECTRAL_DESKTOP_READY_TIMEOUT_MS` | Readiness wait before `desktop` gives up (default 15000).      |
+| `SPECTRAL_DESKTOP_STOP_TIMEOUT_MS`  | SIGTERM grace before SIGKILL in `desktop stop` (default 10000). |
+| `SPECTRAL_DESKTOP_LOG_MAX_BYTES`    | Serve-log size that triggers rotation at start (default 10485760). |
 
 Pi's own auth state for the local TUI path (Codex subscription) lives in
 `~/.pi/agent/auth.json` on the same machine. Spectral never reads it and never

package/dist/agent/index.d.ts

@@ -24,14 +24,16 @@
  *   - Signal propagation (abort passthrough)
  *   - Access to observational memory via the `recall` and
  *     `write_project_observation` tools, which run against a parent-session
- *     point-in-time snapshot (branch + session id); other observation tools
- *     (`share_project_observation`, `receive_agent_observations`,
- *     `compact_context`, `subagent`) remain excluded
+ *     point-in-time snapshot (branch + session id). `receive_agent_observations`
+ *     also runs inside subagents but polls with a DISTINCT derived
+ *     observation session id (never the bare parent id); `share_project_observation`,
+ *     `compact_context`, and `subagent` remain excluded
  */
-import type { AgentTool } from "../sdk/agent-core/index.js";
+import type { AgentEvent, AgentTool } from "../sdk/agent-core/index.js";
 import { type ExtensionAPI, type ExtensionContext } from "../sdk/coding-agent/index.js";
 import { type AgentConfig } from "./agents.js";
 import type { ServerEvent } from "../server/wire.ts";
+import { type TpsUsageFields } from "../server/agent-bridge/tps-metrics.ts";
 import type { ReadonlySessionManager } from "../sdk/coding-agent/core/session-manager.js";
 /**
  * Build the system prompt for a subagent session.
@@ -49,7 +51,32 @@ export declare function buildSubagentSystemPrompt(baseSystemPrompt: string | und
  * SessionManager. Each getBranch call returns fresh clones of the snapshot.
  */
 export declare function createSubagentSessionManagerSnapshot(sessionManager: ExtensionContext["sessionManager"]): Pick<ReadonlySessionManager, "getBranch" | "getSessionId">;
-export declare function resolveSubagentTools(cwd: string, ext: ExtensionAPI, ctx: ExtensionContext): AgentTool[];
+export declare function resolveSubagentTools(cwd: string, ext: ExtensionAPI, ctx: ExtensionContext, agentName?: string): AgentTool[];
+/**
+ * Runs a child agent with an independent per-subagent timeout.
+ *
+ * Combines the parent's abort signal with a fresh timeout AbortController so
+ * that no single subagent can exhaust the parent prompt's full timeout budget.
+ * The budget covers the WHOLE child run including any resume retries (see
+ * `runSingleAgent`), so wall time stays bounded by SUBAGENT_TIMEOUT_MS.
+ * On timeout, returns a clear error result instead of throwing so the parent
+ * agent can continue (e.g. stop a chain, or surface the error as the tool
+ * result for parallel/single modes).
+ */
+/**
+ * LIVE TPS snapshot emitted by the subagent runner after each LLM round that
+ * produced tokens (subagent_progress contract). Carried through
+ * `onInternalEvent` alongside real `AgentEvent`s; the subagent extension maps
+ * it to the `subagent_tps` wire event for the bridge, which folds it into the
+ * throttled `subagent_progress` frames keyed by the parent tool call id.
+ */
+export interface SubagentTpsSnapshotEvent {
+    type: "subagent_tps_snapshot";
+    /** Token-weighted TPS fields so far (omitted fields = no sound data yet). */
+    tps: TpsUsageFields;
+}
+/** Internal events the subagent runner forwards through `onInternalEvent`. */
+export type SubagentInternalEvent = AgentEvent | SubagentTpsSnapshotEvent;
 /** Test hook: replace the run-level retry sleep (e.g. with an instant/collecting stub). */
 export declare function setSubagentRetrySleepForTesting(fn?: (ms: number, signal?: AbortSignal) => Promise<void>): void;
 /**

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAqBpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAKrB,MAAM,8BAA8B,CAAC;AAItC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQrD,OAAO,KAAK,EAAE,sBAAsB,EAAgB,MAAM,6CAA6C,CAAC;AAyGxG;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AAiMD;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,sBAAsB,EAAE,WAAW,GAAG,cAAc,CAAC,CAe5D;AA6BD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAwCb;AAqHD,2FAA2F;AAC3F,wBAAgB,+BAA+B,CAC9C,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GACtD,IAAI,CAEN;AAmBD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAC9D,MAAM,CAiBR;AAogBD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CAqcN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAEX,UAAU,EAEV,SAAS,EAET,MAAM,4BAA4B,CAAC;AAqBpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAKrB,MAAM,8BAA8B,CAAC;AAItC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAGN,KAAK,cAAc,EACnB,MAAM,uCAAuC,CAAC;AAS/C,OAAO,KAAK,EAAE,sBAAsB,EAAgB,MAAM,6CAA6C,CAAC;AAyGxG;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AA2ND;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,sBAAsB,EAAE,WAAW,GAAG,cAAc,CAAC,CAe5D;AAgCD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,EACrB,SAAS,CAAC,EAAE,MAAM,GAChB,SAAS,EAAE,CAkDb;AAyBD;;;;;;;;;;GAUG;AACH;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,6EAA6E;IAC7E,GAAG,EAAE,cAAc,CAAC;CACpB;AAED,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,wBAAwB,CAAC;AAmF1E,2FAA2F;AAC3F,wBAAgB,+BAA+B,CAC9C,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GACtD,IAAI,CAEN;AAmBD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAC9D,MAAM,CAiBR;AAmmBD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CA+cN"}

package/dist/agent/index.js

@@ -24,9 +24,10 @@
  *   - Signal propagation (abort passthrough)
  *   - Access to observational memory via the `recall` and
  *     `write_project_observation` tools, which run against a parent-session
- *     point-in-time snapshot (branch + session id); other observation tools
- *     (`share_project_observation`, `receive_agent_observations`,
- *     `compact_context`, `subagent`) remain excluded
+ *     point-in-time snapshot (branch + session id). `receive_agent_observations`
+ *     also runs inside subagents but polls with a DISTINCT derived
+ *     observation session id (never the bare parent id); `share_project_observation`,
+ *     `compact_context`, and `subagent` remain excluded
  */
 import { agentLoop, agentLoopContinue, } from "../sdk/agent-core/index.js";
 import { buildIsolatedRequestTimePrunedMessagesResult, COMPACT_CONTEXT_TOOL_NAME, } from "../memory/tools/compact-context.js";
@@ -37,6 +38,8 @@ import { sleep } from "../sdk/coding-agent/utils/sleep.js";
 import { Type } from "typebox";
 import { discoverAgents, agentMetadataBlock, } from "./agents.js";
 import { loadAgentSettings } from "../server/handlers/agent-settings.js";
+import { buildTpsUsageFields, computeTpsMetrics, } from "../server/agent-bridge/tps-metrics.js";
+import { randomUUID } from "node:crypto";
 // ---------------------------------------------------------------------------
 // Built-in tool resolution (no spawn needed — tools are registered in-process)
 // ---------------------------------------------------------------------------
@@ -294,14 +297,16 @@ export function createSubagentSessionManagerSnapshot(sessionManager) {
  * - `compact_context`: depends on parent session/UI state (sessionManager,
  *   settingsManager, ui, compaction actions) that is unavailable inside the
  *   isolated `{ cwd, getSystemPrompt }` subagent context.
- * - `receive_agent_observations` / `share_project_observation`: require the
- *   parent session id and branch, which are not exposed to the isolated
- *   subagent context.
+ * - `share_project_observation`: requires the parent session identity to
+ *   attribute shared observations; exposing it to subagents would let them
+ *   misattribute messages and create share/receive feedback loops.
+ * - `receive_agent_observations` is NOT excluded: it runs with a derived
+ *   `observationSessionId` (see `resolveSubagentTools`) so a subagent polls
+ *   its own inbox instead of consuming the parent session's.
  */
 const SUBAGENT_EXCLUDED_TOOL_NAMES = new Set([
     "subagent",
     COMPACT_CONTEXT_TOOL_NAME,
-    RECEIVE_AGENT_OBSERVATIONS_TOOL_NAME,
     SHARE_PROJECT_OBSERVATION_TOOL_NAME,
 ]);
 /**
@@ -311,8 +316,9 @@ const SUBAGENT_EXCLUDED_TOOL_NAMES = new Set([
 const SUBAGENT_SESSION_SNAPSHOT_TOOL_NAMES = new Set([
     RECALL_OBSERVATION_TOOL_NAME,
     WRITE_PROJECT_OBSERVATION_TOOL_NAME,
+    RECEIVE_AGENT_OBSERVATIONS_TOOL_NAME,
 ]);
-export function resolveSubagentTools(cwd, ext, ctx) {
+export function resolveSubagentTools(cwd, ext, ctx, agentName) {
     // Subagents receive every tool registered on the primary agent. Built-in
     // tools are created fresh with the subagent's isolated cwd/jobs, and
     // extension-registered tools are wrapped with a `SubagentToolContext`:
@@ -325,6 +331,16 @@ export function resolveSubagentTools(cwd, ext, ctx) {
     // One shared snapshot per invocation so all snapshot-routed tools observe
     // the same parent-session epoch (branch + session id).
     const sharedSnapshot = createSubagentSessionManagerSnapshot(ctx.sessionManager);
+    // Distinct observation identity for inter-agent tools. Derived from the
+    // parent session id so the inbox stays project/session-scoped, but never
+    // equal to it: per-recipient delivery means a subagent polling with the
+    // bare parent id would consume (and mark delivered) the parent's
+    // broadcast observations. The suffix is per-invocation, so parallel and
+    // retried subagent runs each get their own inbox view.
+    const parentSessionId = ctx.sessionManager?.getSessionId?.();
+    const observationSessionId = parentSessionId
+        ? `${parentSessionId}#sub:${(agentName ?? "agent").replace(/^@/, "")}:${randomUUID().slice(0, 8)}`
+        : undefined;
     for (const toolInfo of ext.getAllTools()) {
         const name = toolInfo.name;
         if (SUBAGENT_EXCLUDED_TOOL_NAMES.has(name))
@@ -345,8 +361,8 @@ export function resolveSubagentTools(cwd, ext, ctx) {
         if (!toolDef)
             continue;
         const isolatedContext = SUBAGENT_SESSION_SNAPSHOT_TOOL_NAMES.has(name)
-            ? { cwd, sessionManager: sharedSnapshot, getSystemPrompt: ctx.getSystemPrompt }
-            : { cwd, getSystemPrompt: ctx.getSystemPrompt };
+            ? { cwd, sessionManager: sharedSnapshot, getSystemPrompt: ctx.getSystemPrompt, observationSessionId }
+            : { cwd, getSystemPrompt: ctx.getSystemPrompt, observationSessionId };
         tools.push(wrapToolDefinition(toolDef, () => isolatedContext));
     }
     return tools;
@@ -371,17 +387,6 @@ async function mapWithConcurrencyLimit(items, concurrency, fn) {
     await Promise.all(workers);
     return results;
 }
-/**
- * Runs a child agent with an independent per-subagent timeout.
- *
- * Combines the parent's abort signal with a fresh timeout AbortController so
- * that no single subagent can exhaust the parent prompt's full timeout budget.
- * The budget covers the WHOLE child run including any resume retries (see
- * `runSingleAgent`), so wall time stays bounded by SUBAGENT_TIMEOUT_MS.
- * On timeout, returns a clear error result instead of throwing so the parent
- * agent can continue (e.g. stop a chain, or surface the error as the tool
- * result for parallel/single modes).
- */
 async function runSingleAgentWithTimeout(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx, maxRetries) {
     const timeoutMs = SUBAGENT_TIMEOUT_MS;
     const timeoutSeconds = timeoutMs / 1000;
@@ -545,7 +550,7 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
     // per-agent tool filtering). Built-ins (read, bash, apply_patch) plus
     // observational-memory tools (recall, read-project-observations) are
     // always available so subagents can actually do work.
-    const tools = resolveSubagentTools(effectiveCwd, ext, ctx);
+    const tools = resolveSubagentTools(effectiveCwd, ext, ctx, agentName);
     const currentResult = {
         agent: agentName,
         agentSource: agent.source,
@@ -571,6 +576,18 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
     // Responses API reasoning metadata that lets the UI classify accumulated
     // subagent thinking as activity (mirrors the main-session thinking metadata).
     let thinkingMetadata;
+    // Per-invocation TPS accumulation (subagent_end contract). Declared before
+    // the try block so both the settled and thrown return paths can attach it;
+    // survives the run-level resume retry so retried rounds count like their
+    // usage does.
+    const tpsAccumulator = {
+        durationMsSum: 0,
+        outputTokens: 0,
+        outputDurationMs: 0,
+        ttftMsSum: 0,
+        ttftRounds: 0,
+        lastRoundTps: null,
+    };
     const emitUpdate = () => {
         if (onUpdate) {
             const liveResult = {
@@ -653,6 +670,11 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
         const collectedMessages = [];
         let hadError = false;
         let segments = 0;
+        // Per-LLM-round timing stamps (TPS contract), mirroring the bridge's
+        // main-session `pending` stamps: message_start opens the round, the
+        // first text/thinking delta ends the TTFT window, message_end closes it.
+        let roundStartAt;
+        let roundFirstDeltaAt;
         // One child run may span several segments: the first one starts the
         // loop, any later one resumes it. Tool results already recorded in
         // `collectedMessages` are part of the resumed context, so tools are
@@ -664,15 +686,25 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
                     break;
                 }
                 onInternalEvent?.(event, parentToolCallId);
+                if (event.type === "message_start" && event.message?.role === "assistant") {
+                    // New LLM round begins. Reset the delta stamp so a stale
+                    // first-delta timestamp from a previous round cannot poison TTFT.
+                    roundStartAt = Date.now();
+                    roundFirstDeltaAt = undefined;
+                }
                 if (event.type === "message_update" && event.message?.role === "assistant") {
                     // Forward streaming text/thinking deltas so the UI can show the
                     // subagent process as it's generated, not just the final result.
                     const inner = event.assistantMessageEvent;
                     if (inner?.type === "text_delta" && inner.delta) {
+                        if (roundFirstDeltaAt === undefined)
+                            roundFirstDeltaAt = Date.now();
                         streamingText += inner.delta;
                         emitUpdate();
                     }
                     else if (inner?.type === "thinking_delta" && inner.delta) {
+                        if (roundFirstDeltaAt === undefined)
+                            roundFirstDeltaAt = Date.now();
                         thinkingText += inner.delta;
                         if (inner.metadata) {
                             thinkingMetadata = { ...(thinkingMetadata ?? {}), ...inner.metadata };
@@ -682,6 +714,9 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
                     continue;
                 }
                 if (event.type === "message_end" && event.message) {
+                    // Stamp at handler entry so the round metrics below measure the
+                    // whole stream (same source as the bridge's main-session path).
+                    const roundEndAt = Date.now();
                     const msg = event.message;
                     collectedMessages.push(msg);
                     if (msg.role === "assistant") {
@@ -703,6 +738,36 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
                             currentResult.stopReason = msg.stopReason;
                         if (msg.errorMessage)
                             currentResult.errorMessage = msg.errorMessage;
+                        // Per-round TPS metrics (mirrors the main-session token_usage
+                        // stamping): message_start → first delta → message_end with this
+                        // round's output tokens. Zero-token rounds contribute timing but
+                        // are skipped in the TPS numerator/denominator.
+                        const roundMetrics = computeTpsMetrics(roundStartAt, roundFirstDeltaAt, roundEndAt, usage?.output ?? 0);
+                        if (roundMetrics.durationMs != null) {
+                            tpsAccumulator.durationMsSum += roundMetrics.durationMs;
+                        }
+                        if (roundMetrics.tokensPerSecond != null &&
+                            roundMetrics.durationMs != null) {
+                            tpsAccumulator.outputTokens += usage?.output ?? 0;
+                            tpsAccumulator.outputDurationMs += roundMetrics.durationMs;
+                            tpsAccumulator.lastRoundTps = roundMetrics.tokensPerSecond;
+                        }
+                        if (roundMetrics.ttftMs != null) {
+                            tpsAccumulator.ttftMsSum += roundMetrics.ttftMs;
+                            tpsAccumulator.ttftRounds += 1;
+                        }
+                        // LIVE TPS snapshot (subagent_progress contract): after each LLM
+                        // round that produced tokens, push the token-weighted
+                        // accumulator snapshot through onInternalEvent so the bridge can
+                        // fold it into the throttled subagent_progress frames keyed by
+                        // the parent tool call id. Omitted until the first round with
+                        // tokens; unsound fields are omitted by buildTpsUsageFields.
+                        if (roundMetrics.tokensPerSecond != null) {
+                            onInternalEvent?.({
+                                type: "subagent_tps_snapshot",
+                                tps: buildTpsUsageFields(tpsAccumulator),
+                            }, parentToolCallId);
+                        }
                         if (msg.stopReason === "error" || msg.stopReason === "aborted") {
                             hadError = true;
                         }
@@ -730,6 +795,10 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
             // shows the resumed segment's reasoning, not stale text.
             thinkingText = "";
             thinkingMetadata = undefined;
+            // Drop round stamps from the previous segment so a resumed segment's
+            // first assistant round measures from its own message_start onward.
+            roundStartAt = undefined;
+            roundFirstDeltaAt = undefined;
             currentResult.stopReason = undefined;
             currentResult.errorMessage = undefined;
             currentResult.stderr = "";
@@ -810,6 +879,15 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
                 currentResult.errorMessage = `${currentResult.errorMessage} (failed after ${segments} attempts)`;
             }
         }
+        if (tpsAccumulator.durationMsSum > 0 || tpsAccumulator.ttftRounds > 0) {
+            currentResult.tps = {
+                ...buildTpsUsageFields(tpsAccumulator),
+                outputTokens: tpsAccumulator.outputTokens,
+                outputDurationMs: tpsAccumulator.outputDurationMs,
+                ttftMsSum: tpsAccumulator.ttftMsSum,
+                ttftRounds: tpsAccumulator.ttftRounds,
+            };
+        }
         return currentResult;
     }
     catch (err) {
@@ -818,6 +896,15 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
         currentResult.stopReason = "error";
         currentResult.errorMessage = errorMsg;
         currentResult.stderr = errorMsg;
+        if (tpsAccumulator.durationMsSum > 0 || tpsAccumulator.ttftRounds > 0) {
+            currentResult.tps = {
+                ...buildTpsUsageFields(tpsAccumulator),
+                outputTokens: tpsAccumulator.outputTokens,
+                outputDurationMs: tpsAccumulator.outputDurationMs,
+                ttftMsSum: tpsAccumulator.ttftMsSum,
+                ttftRounds: tpsAccumulator.ttftRounds,
+            };
+        }
         return currentResult;
     }
 }
@@ -1000,6 +1087,17 @@ export default function subagentExtension(ext, opts) {
                             finishedAt,
                         });
                     }
+                    else if (event.type === "subagent_tps_snapshot") {
+                        // LIVE TPS snapshot from the runner (subagent_progress
+                        // contract): forward as the internal `subagent_tps` wire
+                        // event; the bridge folds it into the throttled
+                        // subagent_progress frames for this tool call.
+                        emitSubagentEvent({
+                            type: "subagent_tps",
+                            toolCallId: parentToolCallId,
+                            ...event.tps,
+                        });
+                    }
                 }
                 : undefined;
             if (modeCount !== 1) {

package/dist/cli.d.ts

@@ -8,6 +8,8 @@
  *  - `spectral login`  → interactive auth flow (writes ~/.spectral/config.json)
  *  - `spectral logout` → deletes ~/.spectral/config.json
  *  - `spectral serve`  → start the Aexol relay WebSocket server (headless)
+ *  - `spectral desktop`→ start `serve` detached + open the Studio UI in the
+ *                        browser (the thin replacement for the old desktop app)
  *  - `spectral bind`   → link directory to an Aexol Studio project
  *  - `spectral unbind` → remove Aexol Studio project binding
  *  - `spectral --version` / `--help` → branded short-circuits, no auth needed.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG"}

package/dist/cli.js

@@ -8,6 +8,8 @@
  *  - `spectral login`  → interactive auth flow (writes ~/.spectral/config.json)
  *  - `spectral logout` → deletes ~/.spectral/config.json
  *  - `spectral serve`  → start the Aexol relay WebSocket server (headless)
+ *  - `spectral desktop`→ start `serve` detached + open the Studio UI in the
+ *                        browser (the thin replacement for the old desktop app)
  *  - `spectral bind`   → link directory to an Aexol Studio project
  *  - `spectral unbind` → remove Aexol Studio project binding
  *  - `spectral --version` / `--help` → branded short-circuits, no auth needed.
@@ -16,8 +18,7 @@
 import { getVersion } from "./version.js";
 // ---- Read our own version ----------------------------------------------------
 // Centralized in src/version.ts so the standalone Bun binary, the npm
-// install, and the electron app all resolve the same real version instead of
-// silently falling back to "0.0.0".
+// install all resolve the same real version instead of falling back to "0.0.0".
 const VERSION = getVersion();
 const TAGLINE = "Coding agent that never sleeps";
 // ---- Branded helpers ---------------------------------------------------------
@@ -33,6 +34,7 @@ function printHeader() {
         "  spectral login         Interactive authentication (team API key or OAuth)",
         "  spectral logout        Remove stored Aexol credentials",
         "  spectral serve         Connect this machine to the Aexol relay backend",
+        "  spectral desktop       Start the agent in the background and open the UI",
         "  spectral bind          Link this directory to an Aexol Studio project",
         "  spectral unbind        Remove the Aexol Studio project binding",
         "  spectral update        Check for and install the latest Spectral version",
@@ -40,8 +42,9 @@ function printHeader() {
         "  spectral --version     Print version and exit",
         "  spectral --help        Print this help and exit",
         "",
-        "TUI/interactive mode has been removed. Use `spectral serve` and connect",
-        "via the Aexol Studio web frontend or relay WebSocket.",
+        "TUI/interactive mode has been removed. Use `spectral desktop` to work in",
+        "the Aexol Studio web frontend, or `spectral serve` to only connect this",
+        "machine to the relay backend.",
         "",
     ].join("\n"));
 }
@@ -99,6 +102,17 @@ async function main() {
         await runServeCli(args.slice(1));
         return;
     }
+    if (first === "desktop") {
+        const { runDesktop } = await import("./commands/desktop.js");
+        // Thin wrapper: it spawns a detached `spectral serve`, waits for its
+        // readiness marker, opens the browser, then exits. The exit code tells the
+        // shell whether the agent came up.
+        // `exitCode` (not `process.exit`) so buffered stdout is flushed and any
+        // pending cleanup still runs — the wrapper has nothing left open, but a
+        // hard exit here would truncate the message on a slow terminal.
+        process.exitCode = await runDesktop(args.slice(1));
+        return;
+    }
     if (first === "bind") {
         const { runBind } = await import("./commands/bind.js");
         await runBind(args.slice(1));

package/dist/commands/desktop.d.ts

@@ -0,0 +1,167 @@
+/**
+ * `spectral desktop` — the thin, headless replacement for the Electron shell.
+ *
+ * What the Electron app actually contributed was four things, all reproduced
+ * here without a bundled Chromium:
+ *
+ *   1. single-instance guarantee      → `~/.spectral/serve.pid` + liveness check
+ *   1. single-instance guarantee      → `~/.spectral/serve.pid`, claimed
+ *                                       atomically (`O_EXCL`) before the spawn
+ *   2. start the local relay daemon   → detached `spectral serve`, unref'd,
+ *                                       stdout+stderr appended to serve.log
+ *   3. "wait until it is really up"   → the `SPECTRAL_SERVE_READY` stdout marker
+ *                                       and `serve-ready.json` (see
+ *                                       src/utils/serve-state.ts), replacing the
+ *                                       old "assume ready after 3 s" heuristic
+ *   4. show the UI                    → open the system browser at
+ *                                       https://aexol.ai/agent
+ *                                       (override: SPECTRAL_LANDING_URL)
+ *
+ * The PATH augmentation the app performed for its child process now happens in
+ * `augmentPath()` (src/utils/augment-path.ts) and is applied to the spawned
+ * daemon, so MCP servers launched via `npx` keep working.
+ *
+ * What is deliberately NOT reproduced (see the removal notes): the splash
+ * window, in-app auto-update (use `spectral update`), the native app menu, and
+ * the JWT-via-IPC login bridge — authentication goes through the existing
+ * `spectral login` browser flow, which already writes `userJwt` to
+ * `~/.spectral/config.json`.
+ *
+ * Exit codes: 0 success / already running, 1 failure, 3 stopped-state for
+ * `status` when the daemon is not running.
+ */
+import { type SpectralConfig } from "../config.js";
+import { type OpenBrowserResult } from "../utils/open-browser.js";
+import { type ServeReadyResult, type ServeGenealogy } from "../utils/serve-state.js";
+/** Where the Studio agent UI lives. */
+export declare const DEFAULT_LANDING_URL = "https://aexol.ai/agent";
+/** How long to wait for the daemon's readiness signal. */
+export declare const DEFAULT_READY_TIMEOUT_MS = 15000;
+/** Grace period between SIGTERM and SIGKILL in `desktop stop`. */
+export declare const DEFAULT_STOP_TIMEOUT_MS = 10000;
+/**
+ * Set in the daemon's env to the wrapper's own pid. The daemon sees the
+ * placeholder we left in `serve.pid` and must not read it as "another serve is
+ * running" — it is the claim of the process that just launched it.
+ */
+export declare const SERVE_PID_CLAIM_ENV = "SPECTRAL_SERVE_PID_CLAIM";
+export declare function getLandingUrl(env?: NodeJS.ProcessEnv): string;
+/** Render a grace window the way it is actually configured (10s, 250ms). */
+export declare function formatGraceMs(ms: number): string;
+export interface ServeSpawnPlan {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    logFile: string;
+}
+interface ResolveCommandInput {
+    execPath?: string;
+    execArgv?: readonly string[];
+    argv1?: string;
+    standalone?: boolean;
+    /** Entry points to try, in order (already-resolved absolute paths). */
+    candidates?: string[];
+    exists?: (path: string) => boolean;
+}
+/**
+ * Decide how to launch a detached `spectral serve`.
+ *
+ * Three launch shapes must all work:
+ *   - standalone Bun binary  → exec the binary itself with `serve`
+ *   - npm install (`spectral` bin → dist/cli.js) → `node <cli.js> serve`
+ *   - `npm run dev` (tsx src/cli.ts) → re-run the very entry the user invoked,
+ *     with `process.execArgv` so the tsx loader is carried over
+ *
+ * @returns the spawn plan's command/args portion. Falls back to whatever
+ *   `spectral` is on PATH when no entry point can be identified.
+ */
+export declare function resolveServeCommand(input?: ResolveCommandInput): {
+    command: string;
+    args: string[];
+};
+/** Compose the full plan for spawning the daemon. */
+export declare function planServeSpawn(env?: NodeJS.ProcessEnv, input?: ResolveCommandInput): ServeSpawnPlan;
+/**
+ * Will this spawn re-exec into the daemon instead of becoming it directly?
+ *
+ * Matters for readiness: a standalone binary and `node dist/cli.js serve` are
+ * the daemon, so their exit is a hard failure we can report instantly. Under
+ * `npm run dev` (`tsx src/cli.ts`) the child is a loader wrapper that execs
+ * something else — its death tells us nothing, and only the ready signal or the
+ * timeout may decide.
+ */
+export declare function spawnExpectsReExec(plan: ServeSpawnPlan): boolean;
+/**
+ * Launch the daemon detached from this terminal so it survives the wrapper
+ * exiting (that is the whole point: close the shell, the agent stays up).
+ * Returns the child pid, or null when the spawn itself failed.
+ */
+export declare function spawnDetachedServe(plan: ServeSpawnPlan): number | null;
+export interface DesktopDeps {
+    env?: NodeJS.ProcessEnv;
+    spawnServe?: (plan: ServeSpawnPlan) => number | null;
+    waitForReady?: (opts: {
+        pid: number;
+        logFile: string;
+        logOffset: number;
+        /** Timestamp captured before the spawn, for ready-signal freshness. */
+        sinceMs: number;
+        /** True when the child re-execs, so its own exit proves nothing. */
+        expectReExec: boolean;
+        timeoutMs: number;
+    }) => Promise<ServeReadyResult>;
+    openUrl?: (url: string) => Promise<OpenBrowserResult>;
+    /** Interactive `spectral login`. */
+    runLogin?: () => Promise<void>;
+    readCfg?: () => Promise<SpectralConfig | null>;
+    signal?: (pid: number, signal: NodeJS.Signals) => void;
+    alive?: (pid: number) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+    /** Override the SIGTERM→SIGKILL grace window (tests, exotic supervisors). */
+    stopGraceMs?: number;
+    /**
+     * Injectable genealogy verdict for the serve.pid hand-off confirmation. The
+     * real probe walks `ps -o ppid=` and can transiently fail under parallel
+     * test load, so tests pin the verdict to keep the
+     * `daemon`/`foreign`/`unknown` classification deterministic.
+     */
+    genealogy?: (pid: number, ancestors: number[]) => ServeGenealogy;
+    planInput?: ResolveCommandInput;
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+    isInteractive?: () => boolean;
+}
+export interface TerminateAgentOptions {
+    /** Pid to stop — always the one from the pid file, never a stale handle. */
+    pid: number;
+    /** SIGTERM grace window before SIGKILL. */
+    graceMs: number;
+    alive: (pid: number) => boolean;
+    signal: (pid: number, signal: NodeJS.Signals) => void;
+    sleep: (ms: number) => Promise<void>;
+    out?: (text: string) => void;
+    /** Poll interval while waiting for the daemon to drain. */
+    pollMs?: number;
+    /** How long to wait after SIGKILL before giving up. */
+    killWaitMs?: number;
+}
+export type TerminateAgentOutcome = "stopped" | "killed" | "failed";
+/**
+ * SIGTERM → wait out the drain → SIGKILL. Shared by `desktop stop` and by the
+ * start path's "it never came up, do not leave it half-started" branch — the
+ * old start path fired a bare SIGTERM and walked away, which left a detached
+ * daemon that ignored TERM (or won the race) running behind a failed command.
+ *
+ * The wait is bounded by a poll COUNT rather than a wall-clock deadline, so a
+ * caller with a synchronous `sleep` (tests) is both fast and deterministic.
+ */
+export declare function terminateAgentPid(opts: TerminateAgentOptions): Promise<TerminateAgentOutcome>;
+/**
+ * `spectral desktop [start|status|stop]`
+ *
+ * @returns process exit code; `cli.ts` assigns it to `process.exitCode`.
+ */
+export declare function runDesktop(args?: string[], deps?: DesktopDeps): Promise<number>;
+export {};
+//# sourceMappingURL=desktop.d.ts.map