@vgai/sdk 0.5.53 → 0.5.56

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.53",
+  "version": "0.5.56",
   "type": "module",
   "repository": {
     "type": "git",
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@vgai/engine": "0.5.53",
+    "@vgai/engine": "0.5.56",
     "playwright": "^1.58.2",
     "zod": "^4.3.6"
   }

package/src/editor/session-registry-format.ts

@@ -14,9 +14,17 @@
  * project.
  */
 
-import { readFileSync, realpathSync } from 'node:fs';
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 
 /** One registry entry, exactly as the server's write half records it. */
 export interface EditorSessionEntry {
@@ -103,6 +111,61 @@ export function readLiveRegisteredSessions(): EditorSessionEntry[] {
   }
 }
 
+/** Announce a launch before the server can register. Each launcher owns its file. */
+export function announceEditorLaunch(project: string): () => void {
+  const directory = join(project, '.vgai', 'editor-launches');
+  mkdirSync(directory, { recursive: true });
+  const file = join(directory, `${process.pid}.json`);
+  writeFileSync(file, JSON.stringify({ pid: process.pid }));
+  const clear = () => {
+    process.removeListener('exit', clear);
+    try {
+      unlinkSync(file);
+    } catch {
+      // Already cleared when the server became ready.
+    }
+  };
+  process.once('exit', clear);
+  return clear;
+}
+
+function hasPendingEditorLaunch(project: string): boolean {
+  const directory = join(project, '.vgai', 'editor-launches');
+  try {
+    return readdirSync(directory).some((name) => {
+      if (!/^\d+\.json$/.test(name)) return false;
+      const pid = Number(name.slice(0, -5));
+      return pid !== process.pid && pidAlive(pid);
+    });
+  } catch {
+    return false;
+  }
+}
+
+/** Wait only for an observed live launcher, never for a missing editor. */
+export async function waitForPendingEditorLaunch(project: string): Promise<void> {
+  const canon = canonicalizeProjectPath(project);
+  const ready = () =>
+    readLiveRegisteredSessions().some(
+      (session) => session.project !== null && canonicalizeProjectPath(session.project) === canon,
+    );
+  if (ready() || !hasPendingEditorLaunch(canon)) return;
+  const deadline = Date.now() + 180_000;
+  while (!ready()) {
+    if (!hasPendingEditorLaunch(canon)) {
+      // The launcher clears its announcement only after registration.
+      if (ready()) return;
+      throw new Error(`The editor launch for ${canon} ended before registering a session.`);
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `The editor launch for ${canon} is still running but has not registered within 180s.`,
+      );
+    }
+    await delay(100);
+  }
+}
+
 /**
  * WHICH PROJECT a `/__editor/project` body says its server is serving.
  *
@@ -186,6 +249,10 @@ export async function resolveRegisteredSession<
     return options.notRunning();
   }
 
+  if (editorUrl === undefined && ctx.projectRoot !== undefined) {
+    await waitForPendingEditorLaunch(ctx.projectRoot);
+  }
+
   let sessions: T[];
   try {
     sessions = await options.withTimeout(

package/src/project/session-journal.ts

@@ -35,7 +35,7 @@
 import { appendFileSync, mkdirSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import type { TripwireTier } from './build-discipline';
-import type { RecordedTabCensus } from './tab-census';
+import type { BlenderTabMetrics, RecordedTabCensus } from './tab-census';
 
 /** `editor-` + an ISO instant with `:`/`.` flattened + `.jsonl` — the same
  *  lexicographic-order-is-chronological-order shape `play-*.jsonl` uses. */
@@ -709,6 +709,35 @@ function tabDeathProfileBody(line: SessionJournalEvent & { kind: 'tab-death-prof
  *  phrasings of the same numbers is how a reader ends up believing there are
  *  two measurements. Renderer counts appear only when the page could read them
  *  (no mounted render-debug adapter = the words are absent, never a zero). */
+/**
+ * The Blender block's words: what the twin's worker and this tab's main thread
+ * have been doing. Absent entirely in a tab with no Blender session.
+ *
+ * `in flight` is the field that speaks during a wedge — the 2026-09-16 call
+ * that held the worker 1,800s produced no other number anywhere in the product.
+ * A field the page could not measure is OMITTED rather than printed as 0: no
+ * call yet, or no Long Tasks API (Safari/Firefox), is not "never stalled".
+ */
+function formatBlenderMetrics(blender: BlenderTabMetrics): string {
+  const s = (ms: number): string => `${Math.round(ms / 100) / 10}s`;
+  const parts = [
+    blender.inFlightMs === null ? 'idle' : `IN FLIGHT ${s(blender.inFlightMs)}`,
+    ...(blender.lastCallMs === null ? [] : [`last call ${s(blender.lastCallMs)}`]),
+    ...(blender.maxCallMs === null ? [] : [`max ${s(blender.maxCallMs)}`]),
+    `over 5s ${blender.callsOver5s}`,
+    `over 30s ${blender.callsOver30s}`,
+    ...(blender.longestTaskMs === null
+      ? []
+      : [
+          `longest main-thread task ${s(blender.longestTaskMs)} (${blender.tasksOver100ms} over 100ms)`,
+        ]),
+    ...(blender.lastCallLongestTaskMs === null
+      ? []
+      : [`${s(blender.lastCallLongestTaskMs)} of that during the last call`]),
+  ];
+  return `blender: ${parts.join(', ')}`;
+}
+
 export function formatTabCensus(census: RecordedTabCensus | null): string {
   if (census === null) return 'no resource census';
   const parts = [
@@ -721,7 +750,13 @@ export function formatTabCensus(census: RecordedTabCensus | null): string {
   if (census.textures !== undefined) parts.push(`tex ${census.textures}`);
   if (census.geometries !== undefined) parts.push(`geo ${census.geometries}`);
   if (census.programs !== undefined) parts.push(`prog ${census.programs}`);
-  return parts.join(', ');
+  const line = parts.join(', ');
+  // On its own line: the Blender block answers a different question from the
+  // resource profile (is the tab ANSWERING, not what is it holding), and
+  // running the two together is how a reader stops seeing either.
+  return census.blender === undefined
+    ? line
+    : `${line}\n            ${formatBlenderMetrics(census.blender)}`;
 }
 
 /**

package/src/project/tab-census.ts

@@ -25,6 +25,12 @@
  * Deliberately import-free so a browser bundle can take it: the census's other
  * `@vgai/sdk` home, `project/session-journal.ts`, reads `node:fs`.
  *
+ * WHAT ELSE RIDES IT. The beat is the one channel that still moves when the
+ * page's main thread or the Blender worker is blocked, so `blender` — how long
+ * the twin's calls are taking and how long the main thread has been stalled —
+ * is carried here too (absent unless a Blender session exists in the tab). Same
+ * rule as the rest of this file: measurement only, no budget anywhere.
+ *
  * ABSENT IS NOT ZERO. `heapUsedMB`/`heapLimitMB` are null off Chromium
  * (`performance.memory` is non-standard). The renderer counts are ABSENT rather
  * than zero when no game has registered a render-debug adapter, and `programs`
@@ -32,6 +38,47 @@
  * a different claim from "nobody measured".
  */
 
+/**
+ * THE BLENDER TWIN'S STALLS, as numbers.
+ *
+ * WHY (measured 2026-09-16): one `blender-execute` held the twin's worker for
+ * over 1,800s and wedged the tab, and a 0.86s-per-call scene stretched into
+ * heartbeat timeouts that read as "tab present, did not respond". The product
+ * had no number for either. Owner ruling: a tab that stops answering is the
+ * product's defect regardless of what the machine is doing, and the product has
+ * to surface it — so these ride the census to `vgai status`.
+ *
+ * MEASURED BY THE PAGE, because neither blocked party can report on itself: the
+ * worker's own loop is what is stuck, and a stalled main thread cannot send.
+ * The call half comes from `BlenderRuntime.metrics()`
+ * (`packages/bpy-twin/browser/runtime.ts`), the stall half from a `longtask`
+ * PerformanceObserver (`packages/editor/src/blender-tab-metrics.ts`).
+ *
+ * MEASUREMENT ONLY. No threshold here cancels, kills or budgets a call.
+ */
+export interface BlenderTabMetrics {
+  /** Age of the oldest OUTSTANDING worker call, or null when the twin is idle.
+   *  The only field with a number during a wedge. */
+  readonly inFlightMs: number | null;
+  /** Duration of the newest completed call; null before the first one. */
+  readonly lastCallMs: number | null;
+  /** The longest call this page has seen, counting an outstanding one. */
+  readonly maxCallMs: number | null;
+  /** Calls past 5s, and past 30s, since this page loaded. */
+  readonly callsOver5s: number;
+  readonly callsOver30s: number;
+  /** Longest `longtask` entry since page load, in ms; null off Chromium (the
+   *  Long Tasks API is not implemented everywhere) — never 0, which would read
+   *  as "the main thread never stalled". */
+  readonly longestTaskMs: number | null;
+  /** How many long tasks ran past 100ms since page load. */
+  readonly tasksOver100ms: number;
+  /** The longest long task that overlapped the newest call's window — what the
+   *  MAIN thread was doing while the worker was busy. Null when there has been
+   *  no call yet, or no long task during it. */
+  readonly lastCallLongestTaskMs: number | null;
+}
+
 /**
  * A census as a CURRENT page produces it and the server files it.
  *
@@ -57,6 +104,8 @@ export interface TabCensus {
   readonly geometries?: number;
   /** Compiled programs — absent with no adapter, or before the first render. */
   readonly programs?: number;
+  /** {@link BlenderTabMetrics} — absent unless this tab has a Blender session. */
+  readonly blender?: BlenderTabMetrics;
 }
 
 /**

package/src/project-tool-catalog.ts

@@ -4,7 +4,8 @@ export type ToolContributionPoint =
   | 'asset.inspector'
   | 'generation.result'
   | 'workspace.utility'
-  | 'workspace.analytics';
+  | 'workspace.analytics'
+  | 'workspace.status';
 
 /**
  * One contribution module, FOUND BY SCANNING — never listed anywhere.