@aexol/spectral 0.9.231 → 0.9.240

package/dist/commands/serve.js

@@ -40,7 +40,7 @@ import { refreshCloudAgents as refreshCloudAgentsImpl } from "../agent/agents.js
 import { requireLogin } from "../preflight.js";
 import { RelayClient } from "../relay/client.js";
 import { getFanoutManager } from "../server/fanout/fanout-manager.js";
-import { detachAllSubscribers, handleAutoOptimizeFrame, handleAutoResearchFrame, handleCancelTurn, handleClientMessage, handleRestRequest, handleSubscribe, } from "../relay/dispatcher.js";
+import { detachAllSubscribers, handleAutoOptimizeFrame, handleAutoResearchFrame, handleCancelTurn, handleClientMessage, handleRestRequest, handleStopToolCall, handleSubscribe, } from "../relay/dispatcher.js";
 import { ensureMachineRegistered } from "../relay/registration.js";
 import { saveMachine } from "../relay/machine-store.js";
 import { SessionStreamManager } from "../server/session-stream.js";
@@ -49,6 +49,8 @@ import { getLiveMcpState } from "../mcp/state-getter.js";
 import { preflightSqlite, SessionStore } from "../server/storage.js";
 import { DevProcessRegistry } from "../server/dev-process-registry.js";
 import { sweepOffloads } from "../server/offload-gc.js";
+import { SERVE_READY_MARKER, clearServeState, getLiveServePid, ownsServeState, writeServePid, writeServeReady, } from "../utils/serve-state.js";
+import { applyAugmentedPath } from "../utils/augment-path.js";
 /** Default backend base URL when neither env nor override is set. */
 const DEFAULT_BACKEND_URL = "https://api.aexol.ai";
 import { getVersion } from "../version.js";
@@ -127,6 +129,7 @@ export async function runServe(opts = {}) {
     const installSignalHandlers = opts.installSignalHandlers ?? true;
     const silent = opts.silent ?? false;
     const dbPath = opts.dbPath ?? join(getConfigDir(), "sessions.db");
+    const serveState = opts.serveState ?? true;
     // Pre-flight: native sqlite. Fail fast with a friendly hint BEFORE we
     // start opening sockets — keeps the error close to the cause.
     const preflight = preflightSqlite(dbPath);
@@ -134,6 +137,29 @@ export async function runServe(opts = {}) {
         process.stderr.write(`✗ ${preflight.error}\n`);
         process.exit(1);
     }
+    // Single-instance bookkeeping. Claim the pid file before any long-running
+    // work so `spectral desktop status|stop` and a second `spectral desktop`
+    // can find this daemon. Readers prune a stale file with a liveness check,
+    // so a SIGKILLed run never wedges the next start.
+    if (serveState) {
+        // Warn (never refuse) when another live daemon already holds the pid file.
+        // Two relays from one machine are legal — the second simply takes over
+        // ownership, which would otherwise silently make `desktop stop` target the
+        // wrong process.
+        //
+        // `spectral desktop` claims the pid file with its OWN pid before spawning
+        // us (that is what makes the single-instance check atomic), and passes that
+        // pid in `SPECTRAL_SERVE_PID_CLAIM`. Seeing it is the expected hand-off,
+        // not a competing daemon — ditto our direct parent.
+        const previous = getLiveServePid();
+        const launchClaim = Number.parseInt(process.env.SPECTRAL_SERVE_PID_CLAIM ?? "", 10);
+        const expectedHolder = previous === process.ppid || (Number.isInteger(launchClaim) && previous === launchClaim);
+        if (previous !== null && previous !== process.pid && !expectedHolder && !silent) {
+            process.stderr.write(`warning: another spectral serve appears to be running (pid ${previous}); ` +
+                `this process will take over ~/.spectral/serve.pid\n`);
+        }
+        writeServePid();
+    }
     // Pre-flight: sweep stale large-result offload files (fire-and-forget).
     const store = new SessionStore(dbPath);
     const devProcessRegistry = new DevProcessRegistry(getAgentDir());
@@ -278,6 +304,30 @@ export async function runServe(opts = {}) {
     // resume mid-turn.
     const subscribers = new Map();
     let relay;
+    /**
+     * Announce readiness to whoever launched us. The Electron app used to guess
+     * ("is the child still alive after 3 s?"), which raced the relay handshake:
+     * the web app loaded, subscribed to the relay before it existed, and showed
+     * `machine_disconnected` on every start. Instead, the FIRST time the socket
+     * is genuinely open we (a) drop `serve-ready.json` {pid, ts, version} and
+     * (b) print `SPECTRAL_SERVE_READY` on stdout. A launcher that redirected our
+     * stdio to a log file still has the file; a launcher watching stdout doesn't
+     * need the file. Later reconnects refresh the ready file's timestamp but do
+     * not re-print the marker — it is a startup signal, not a liveness ping.
+     */
+    let readyAnnounced = false;
+    const announceServeReady = () => {
+        // Only the pid-file holder may publish readiness. A second daemon that took
+        // over, or one that lost the file to a restart, must not overwrite the
+        // ready signal of the process that owns it — `desktop`/`status` read that
+        // file as the answer to "is MY agent up".
+        if (ownsServeState())
+            writeServeReady(version);
+        if (readyAnnounced)
+            return;
+        readyAnnounced = true;
+        process.stdout.write(`${SERVE_READY_MARKER}\n`);
+    };
     /** Wire event handlers on a (possibly new) RelayClient instance. */
     function wireRelay(r) {
         // Wire the meta publisher now that we have both the relay socket and
@@ -350,6 +400,17 @@ export async function runServe(opts = {}) {
                 handleCancelTurn(frame, { manager });
                 return;
             }
+            if (frame.kind === "stop_tool_call") {
+                // Per-tool-call stop: abort ONE hung tool call, keep the turn alive.
+                // Fire-and-forget with an internal catch — an unresolved settle must
+                // never hang the relay loop (the manager isolates per-call failures).
+                void handleStopToolCall(frame, {
+                    manager,
+                }).catch((err) => {
+                    process.stderr.write(`[serve] stop_tool_call failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                });
+                return;
+            }
             if (frame.kind === "auto_research") {
                 handleAutoResearchFrame(frame, {
                     store,
@@ -453,6 +514,12 @@ export async function runServe(opts = {}) {
                 process.stdout.write(`Reconnect attempt ${attempt} in ${delayMs}ms\n`);
             });
         }
+        // Readiness: fires on every successful socket open, including after the
+        // auth-failed re-registration below swaps in a fresh RelayClient.
+        r.on("open", () => {
+            if (serveState)
+                announceServeReady();
+        });
         // The `error` listener must be registered regardless of `silent`:
         // without it, a transport hiccup in silent mode would surface as an
         // unhandled 'error' event and kill the whole serve process. (RelayClient
@@ -586,10 +653,23 @@ export async function runServe(opts = {}) {
         catch {
             // browser extension may not be loaded or already closed
         }
+        // Only clear what we still own: a daemon that lost (or never took) the pid
+        // file must not delete the state of the daemon that holds it.
+        if (serveState && ownsServeState())
+            clearServeState();
         if (!silent)
             process.stdout.write("Spectral relay stopped\n");
     };
     if (installSignalHandlers) {
+        // Bookkeeping cleanup on EVERY exit route. The graceful-shutdown path calls
+        // `process.exit()` itself, so `close()` never runs on SIGTERM/SIGINT — and
+        // `spectral desktop stop` must not find a stale pid file after a clean
+        // shutdown. SIGKILL / crashes still leave a file behind, which readers prune
+        // via the liveness check in `getLiveServePid()`.
+        process.on("exit", () => {
+            if (serveState && ownsServeState())
+                clearServeState();
+        });
         // Top-level error nets. A daemon must NOT die from a transient
         // unhandled rejection (e.g. a fetch promise that lost its `.catch`
         // when the relay flapped) or a stray throw from a third-party
@@ -716,11 +796,19 @@ async function handleConfigPatch(frame, deps) {
 }
 /**
  * CLI entry point used by `cli.ts`. Surfaces the deprecation warning for
- * `--port`/`SPECTRAL_PORT` once, then defers to `runServe`.
+ * `--port`/`SPECTRAL_PORT` once, augments PATH for child processes, then defers
+ * to `runServe`.
  */
 export async function runServeCli(rawArgs) {
     const parsed = parseServeArgs(rawArgs);
     const machineName = parsed.machineName ?? process.env.SPECTRAL_MACHINE_NAME;
+    // A GUI-launched daemon (LaunchAgent, `.app` helper, `desktop` wrapper)
+    // inherits a minimal PATH, which breaks every `npx`-based MCP server and any
+    // shell tool that expects node/git. Augment the daemon's own PATH once here so
+    // all descendants — in-process AgentBridge shells, dev-process registry, MCP
+    // stdio transports — inherit a usable one. Deliberately in the CLI driver and
+    // not `runServe()`, so in-process tests never mutate the runner's env.
+    applyAugmentedPath();
     if (parsed.deprecatedPort || process.env.SPECTRAL_PORT) {
         process.stderr.write(`warning: --port / SPECTRAL_PORT are no longer used. ` +
             `spectral serve now connects outbound to the Aexol relay; there is no local port to bind.\n`);

package/dist/commands/update.d.ts

@@ -2,16 +2,96 @@
  * `spectral update` — standalone binary self-update.
  *
  * Fetches the latest release manifest from api.aexol.ai, compares versions,
- * downloads the new binary, verifies its SHA256 checksum, and atomically
- * replaces the running binary on disk.
+ * downloads the new artifacts, verifies their SHA256 digests, and installs them
+ * over the current installation.
  *
- * Non-standalone install modes (Electron desktop app, npm global) are detected
- * and the user is pointed at the correct update path instead.
+ * Two manifest shapes are supported:
+ *
+ *   - binary only (every manifest ever published): `url` + `sha256` pin the
+ *     single-file binary. Only the binary is replaced — the companion assets an
+ *     `install.sh` user has next to it (`data/systems/`, `mcp/`,
+ *     `app-bridge.bundle.js`) keep the previous version, which is called out
+ *     with a warning telling the user to re-run `curl | sh`.
+ *   - release zip (ADDITIVE `zipUrl` + `zipSha256`, emitted by
+ *     cli-node/scripts/generate-cli-manifest.sh once scripts/package-standalone.sh
+ *     produced the archive): the zip carries the binary *and* the
+ *     `<platform>-data/` companion directory. Both are installed with the same
+ *     replace-don't-merge semantics as scripts/install.sh, so files deleted
+ *     between releases do not linger.
+ *
+ * Nothing is installed unverified: the zip digest is checked before unpacking,
+ * the inner binary digest before swapping, and any mismatch aborts without
+ * touching the current installation.
+ *
+ * Non-standalone install modes (npm global install) are detected and the user
+ * is pointed at the correct update path instead.
+ */
+/** Shape of the per-platform latest release manifest. */
+export interface ReleaseManifest {
+    version: string;
+    platform: string;
+    url: string;
+    sha256: string;
+    /**
+     * Additive fields: manifests published before the release-zip scheme do not
+     * have them, so every reader must treat them as optional. When both are
+     * present, the release zip (binary + `<platform>-data/` companion assets) can
+     * be verified and installed instead of the raw binary alone.
+     */
+    zipUrl?: string;
+    zipSha256?: string;
+}
+/**
+ * Spawn a helper process (`unzip`, `tar`) and resolve with its exit code.
+ * Rejects when the executable cannot be started at all (ENOENT), which is how
+ * callers tell "tool missing" apart from "tool failed".
+ */
+export type RunCommand = (cmd: string, args: string[]) => Promise<number>;
+/**
+ * Everything I/O-shaped in the update flow, injectable for tests: the flow
+ * (verify → unpack → swap → stamp) is then covered without network access, real
+ * archives, or a real standalone binary.
+ */
+export interface UpdateDeps {
+    out?: (t: string) => void;
+    err?: (t: string) => void;
+    fetchManifest?: (platform: string) => Promise<ReleaseManifest>;
+    download?: (url: string, destPath: string) => Promise<void>;
+    run?: RunCommand;
+    /** Executable to update (defaults to `process.execPath`). */
+    execPath?: string;
+    /** Current version (defaults to `getVersion()`). */
+    version?: string;
+    /** Standalone detection (defaults to `isStandaloneBinary()`). */
+    standalone?: boolean;
+    /** Release platform slug (defaults to `detectPlatform()`). */
+    platform?: string | null;
+}
+/**
+ * Replace the companion assets next to the binary with the ones from the zip.
+ *
+ * Semantics are those of scripts/install.sh: the `<platform>-data/` directory is
+ * placed next to the binary and *then* its contents are copied alongside it,
+ * with the previous `data/`, `mcp/` and `app-bridge.bundle.js` removed first —
+ * replace, not merge, so files deleted between releases do not linger.
+ *
+ * SAFETY: `installDir` is `dirname(process.execPath)` — the directory that
+ * *holds* the running binary. Only the explicitly named companion paths inside
+ * it are ever removed, and only for a real absolute path, so a bad `execPath`
+ * can never wipe a directory that contains the binary.
  */
+export declare function swapCompanionAssets(params: {
+    stageDir: string;
+    installDir: string;
+}): Promise<{
+    dataDirName: string | null;
+    replaced: string[];
+}>;
 /**
  * Run the `spectral update` subcommand.
  *
  * @param args remaining CLI args after the `update` subcommand
+ * @param deps injectable I/O for tests (network, spawns, exec path, version)
  */
-export declare function runUpdate(args: string[]): Promise<void>;
+export declare function runUpdate(args: string[], deps?: UpdateDeps): Promise<void>;
 //# sourceMappingURL=update.d.ts.map

package/dist/commands/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA2NH;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8H7D"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA2BH,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1B,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1B,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IAC/D,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAwMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwC9D;AA2FD;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA4OpF"}