@vgai/sdk 0.5.0 → 0.5.2

package/src/play/index.ts

@@ -1,7 +1,7 @@
 /**
  * B4 — `play.*` operations
  * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B4). Registered
- * separately from B1's `registerBuiltinOperations` (`../operations.ts`),
+ * separately from B1's `registerBuiltinTools` (`../operations.ts`),
  * B2's `registerProjectOperations` (`../project/index.ts`), and B3's
  * `registerEditorOperations` (`../editor/index.ts`) — the default
  * `operations` singleton (`../index.ts`) calls all four.
@@ -43,7 +43,7 @@ export {
   withPlayTimeout,
 } from './transport.js';
 
-import type { OperationRegistry } from '../registry.js';
+import type { ToolRegistry } from '../registry.js';
 import { registerControlOperations } from './control-operations.js';
 import { registerDebugCommandOperations } from './debug-command-operations.js';
 import { registerInputOperations } from './input-operations.js';
@@ -54,7 +54,7 @@ import { registerStateOperations } from './state-operations.js';
 import { registerStatusOperations } from './status-operations.js';
 
 /** Register every B4 `play.*` operation onto `registry`. */
-export function registerPlayOperations(registry: OperationRegistry): void {
+export function registerPlayOperations(registry: ToolRegistry): void {
   registerLifecycleOperations(registry);
   registerStatusOperations(registry);
   registerLogOperations(registry);

package/src/play/input-operations.ts

@@ -58,8 +58,8 @@
  */
 
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { ToolError } from '../errors.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import type { InputInjectionRequest, PlayCommandResult } from './transport.js';
 import {
   getPlayTransport,
@@ -205,22 +205,22 @@ function throwForInjectFailure(result: PlayCommandResult): never {
   const marker = relayErrorMarker(result);
   const message = result.error ?? 'inject-input command failed';
   if (marker?.code === 'INPUT_ACTION_NOT_FOUND') {
-    throw new OperationError('INPUT_ACTION_NOT_FOUND', message, {
+    throw new ToolError('INPUT_ACTION_NOT_FOUND', message, {
       registered: relayStringArray(marker.data['registered']),
     });
   }
   if (marker?.code === 'TICK_ALREADY_PASSED') {
-    throw new OperationError('TICK_ALREADY_PASSED', message, {
+    throw new ToolError('TICK_ALREADY_PASSED', message, {
       currentTick: typeof marker.data['currentTick'] === 'number' ? marker.data['currentTick'] : 0,
     });
   }
   if (marker?.code === 'DEBUG_INPUT_WORLD_NOT_FOUND') {
-    throw new OperationError('INPUT_WORLD_NOT_FOUND', message, {
+    throw new ToolError('INPUT_WORLD_NOT_FOUND', message, {
       worldId: typeof marker.data['worldId'] === 'string' ? marker.data['worldId'] : '',
       registered: relayStringArray(marker.data['registered']),
     });
   }
-  throw new OperationError('COMMAND_FAILED', message, { message });
+  throw new ToolError('COMMAND_FAILED', message, { message });
 }
 
 const PlayInputInjectResult = z.object({
@@ -234,7 +234,7 @@ const PlayInputInjectResult = z.object({
     ),
 });
 
-export const playInputInject = defineOperation({
+export const playInputInject = defineTool({
   name: 'play.input.inject',
   summary: 'Inject synthetic input into a running play session through the normal action path.',
   description:
@@ -289,7 +289,7 @@ export const playInputInject = defineOperation({
       'play.input.inject',
     ).catch(() => undefined);
     if (!result) {
-      throw new OperationError(
+      throw new ToolError(
         'INPUT_INJECTION_UNSUPPORTED',
         'The connected editor page predates the inject-input relay command — reload it.',
         {},
@@ -303,7 +303,7 @@ export const playInputInject = defineOperation({
       | undefined;
     if (outcome?.delivered === false) {
       const reason = outcome.reason ?? 'input-gated';
-      throw new OperationError('INPUT_GATED', reason, { reason });
+      throw new ToolError('INPUT_GATED', reason, { reason });
     }
     return outcome?.scheduled === true
       ? { ok: true as const, scheduled: true }
@@ -311,6 +311,6 @@ export const playInputInject = defineOperation({
   },
 });
 
-export function registerInputOperations(registry: OperationRegistry): void {
+export function registerInputOperations(registry: ToolRegistry): void {
   registry.register(playInputInject);
 }

package/src/play/lifecycle-operations.ts

@@ -35,8 +35,8 @@
  */
 
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { ToolError } from '../errors.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import {
   getPlayTransport,
   PLAY_COMMAND_TIMEOUT_MS,
@@ -74,7 +74,7 @@ async function relayAndCheck(
     error: err instanceof Error ? err.message : String(err),
   }));
   if (!result.ok) {
-    throw new OperationError('COMMAND_FAILED', result.error ?? `${op} command failed`, {
+    throw new ToolError('COMMAND_FAILED', result.error ?? `${op} command failed`, {
       message: result.error ?? `${op} command failed`,
     });
   }
@@ -106,7 +106,7 @@ const PlayStartInput = z.object({
     ),
 });
 
-export const playStart = defineOperation({
+export const playStart = defineTool({
   name: 'play.start',
   summary: 'Start (or restart) play mode in a connected editor session and wait for readiness.',
   description:
@@ -137,7 +137,7 @@ export const playStart = defineOperation({
       );
     } catch (err) {
       if (err instanceof PlayTimeoutError) {
-        throw new OperationError(
+        throw new ToolError(
           'PLAY_START_TIMEOUT',
           `The runtime did not report readiness within ${timeoutMs}ms.`,
           { timeoutMs },
@@ -146,7 +146,7 @@ export const playStart = defineOperation({
       throw err;
     }
     if (!result.ok) {
-      throw new OperationError('COMMAND_FAILED', result.error ?? 'play command failed', {
+      throw new ToolError('COMMAND_FAILED', result.error ?? 'play command failed', {
         message: result.error ?? 'play command failed',
       });
     }
@@ -160,7 +160,7 @@ export const playStart = defineOperation({
 
 const NoInput = z.object({});
 
-export const playPause = defineOperation({
+export const playPause = defineTool({
   name: 'play.pause',
   summary: 'Pause the running play session in a connected editor.',
   description: 'Relays {type:"pause"} through POST /__editor/command (already-handled case).',
@@ -184,7 +184,7 @@ export const playPause = defineOperation({
   },
 });
 
-export const playResume = defineOperation({
+export const playResume = defineTool({
   name: 'play.resume',
   summary: 'Resume a paused play session in a connected editor.',
   description: 'Relays {type:"resume"} through POST /__editor/command (already-handled case).',
@@ -208,7 +208,7 @@ export const playResume = defineOperation({
   },
 });
 
-export const playStop = defineOperation({
+export const playStop = defineTool({
   name: 'play.stop',
   summary: 'Stop play mode in a connected editor and clean up the launched runtime.',
   description:
@@ -238,7 +238,7 @@ export const playStop = defineOperation({
   },
 });
 
-export const playFrameStep = defineOperation({
+export const playFrameStep = defineTool({
   name: 'play.frameStep',
   summary: 'Advance a paused play session by exactly one frame.',
   description: 'Relays {type:"step"} through POST /__editor/command (already-handled case).',
@@ -262,7 +262,7 @@ export const playFrameStep = defineOperation({
   },
 });
 
-export function registerLifecycleOperations(registry: OperationRegistry): void {
+export function registerLifecycleOperations(registry: ToolRegistry): void {
   registry.register(playStart);
   registry.register(playPause);
   registry.register(playResume);

package/src/play/log-operations.ts

@@ -43,7 +43,7 @@
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
+import { ToolError } from '../errors.js';
 import {
   FILE_NOT_FOUND_ERROR,
   NO_PROJECT_ROOT_ERROR,
@@ -52,7 +52,7 @@ import {
   requireProjectRoot,
   resolveProjectPath,
 } from '../project/shared.js';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import {
   getPlayTransport,
   PLAY_READ_TIMEOUT_MS,
@@ -81,7 +81,7 @@ const PlayLogDiscoverResult = z.object({
     .describe('Filenames (e.g. "play-2026-07-11T10-00-00.jsonl"), oldest first (name-sorted).'),
 });
 
-export const playLogDiscover = defineOperation({
+export const playLogDiscover = defineTool({
   name: 'play.log.discover',
   summary: "List every persisted play-mode log file under the project's logs/ directory.",
   description:
@@ -189,7 +189,7 @@ function parseLogLine(
   };
 }
 
-export const playLogRead = defineOperation({
+export const playLogRead = defineTool({
   name: 'play.log.read',
   summary: 'Read entries from a persisted play-mode log file.',
   description:
@@ -238,7 +238,7 @@ const PlayLogFollowResult = z.object({
     .describe('Live count of entries buffered for the active play session.'),
 });
 
-export const playLogFollow = defineOperation({
+export const playLogFollow = defineTool({
   name: 'play.log.follow',
   summary: "Describe how to poll-follow the currently active play session's log.",
   description:
@@ -262,7 +262,7 @@ export const playLogFollow = defineOperation({
       'play.log.follow',
     ).catch(() => undefined);
     if (!metadata) {
-      throw new OperationError(
+      throw new ToolError(
         'PLAY_LOG_FOLLOW_UNAVAILABLE',
         'The connected editor session did not answer the log-entries read in time.',
         {},
@@ -272,7 +272,7 @@ export const playLogFollow = defineOperation({
   },
 });
 
-export function registerLogOperations(registry: OperationRegistry): void {
+export function registerLogOperations(registry: ToolRegistry): void {
   registry.register(playLogDiscover);
   registry.register(playLogRead);
   registry.register(playLogFollow);

package/src/play/run-ticks-operations.ts

@@ -20,8 +20,8 @@
  */
 
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { ToolError } from '../errors.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import {
   getPlayTransport,
   PLAY_COMMAND_TIMEOUT_MS,
@@ -81,7 +81,7 @@ const PlayRunTicksInput = z.object({
 
 const PlayRunTicksResult = z.object({ ok: z.literal(true) });
 
-export const playRunTicks = defineOperation({
+export const playRunTicks = defineTool({
   name: 'play.runTicks',
   summary: 'Synchronously fast-forward a running play session by n fixed gameplay ticks.',
   description:
@@ -115,7 +115,7 @@ export const playRunTicks = defineOperation({
       'play.runTicks',
     ).catch(() => undefined);
     if (!result) {
-      throw new OperationError(
+      throw new ToolError(
         'RUN_TICKS_UNSUPPORTED',
         'The connected editor page predates the run-ticks relay command — reload it.',
         {},
@@ -125,17 +125,17 @@ export const playRunTicks = defineOperation({
       const marker = relayErrorMarker(result);
       const message = result.error ?? 'run-ticks command failed';
       if (marker?.code === 'RUN_TICKS_UNAVAILABLE') {
-        throw new OperationError('RUN_TICKS_UNAVAILABLE', message, {});
+        throw new ToolError('RUN_TICKS_UNAVAILABLE', message, {});
       }
       if (marker?.code === 'RUN_TICKS_PAUSED') {
-        throw new OperationError('RUN_TICKS_PAUSED', message, {});
+        throw new ToolError('RUN_TICKS_PAUSED', message, {});
       }
-      throw new OperationError('COMMAND_FAILED', message, { message });
+      throw new ToolError('COMMAND_FAILED', message, { message });
     }
     return { ok: true as const };
   },
 });
 
-export function registerRunTicksOperations(registry: OperationRegistry): void {
+export function registerRunTicksOperations(registry: ToolRegistry): void {
   registry.register(playRunTicks);
 }

package/src/play/state-operations.ts

@@ -21,8 +21,8 @@
  */
 
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { ToolError } from '../errors.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import {
   getPlayTransport,
   PLAY_READ_TIMEOUT_MS,
@@ -61,14 +61,14 @@ const COMMAND_FAILED_ERROR = {
 function throwStateRelayFailure(result: PlayCommandResult, label: string): never {
   const marker = relayErrorMarker(result);
   if (marker?.code === 'STATE_PROVIDER_NOT_FOUND') {
-    throw new OperationError(
+    throw new ToolError(
       'STATE_PROVIDER_NOT_FOUND',
       result.error ?? 'state provider not found',
       { registered: relayStringArray(marker.data['registered']) },
     );
   }
   const message = result.error ?? `${label} command failed`;
-  throw new OperationError('COMMAND_FAILED', message, { message });
+  throw new ToolError('COMMAND_FAILED', message, { message });
 }
 
 // ---------------------------------------------------------------------------
@@ -92,7 +92,7 @@ const PlayGameplayStateInspectResult = z.object({
     .describe('The game-provided state snapshot, or null when the game exposes none.'),
 });
 
-export const playGameplayStateInspect = defineOperation({
+export const playGameplayStateInspect = defineTool({
   name: 'play.gameplayState.inspect',
   summary: 'Inspect game-registered state providers from a running play session.',
   description:
@@ -126,7 +126,7 @@ export const playGameplayStateInspect = defineOperation({
       'play.gameplayState.inspect',
     ).catch(() => undefined);
     if (result === undefined) {
-      throw new OperationError(
+      throw new ToolError(
         'GAMEPLAY_STATE_UNSUPPORTED',
         'The connected editor page predates the gameplay-state relay commands — reload it.',
         {},
@@ -158,7 +158,7 @@ const PlayGameplayStateListResult = z.object({
     .describe('Every registered state provider of the running game, with its honesty tier.'),
 });
 
-export const playGameplayStateList = defineOperation({
+export const playGameplayStateList = defineTool({
   name: 'play.gameplayState.list',
   summary: 'List the state providers a running play session registers, with honesty tiers.',
   description:
@@ -190,7 +190,7 @@ export const playGameplayStateList = defineOperation({
       'play.gameplayState.list',
     ).catch(() => undefined);
     if (result === undefined) {
-      throw new OperationError(
+      throw new ToolError(
         'GAMEPLAY_STATE_UNSUPPORTED',
         'The connected editor page predates the gameplay-state relay commands — reload it.',
         {},
@@ -204,7 +204,7 @@ export const playGameplayStateList = defineOperation({
   },
 });
 
-export function registerStateOperations(registry: OperationRegistry): void {
+export function registerStateOperations(registry: ToolRegistry): void {
   registry.register(playGameplayStateInspect);
   registry.register(playGameplayStateList);
 }

package/src/play/status-operations.ts

@@ -20,8 +20,8 @@
  */
 
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { ToolError } from '../errors.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import {
   getPlayTransport,
   PLAY_READ_TIMEOUT_MS,
@@ -73,7 +73,7 @@ const PlayStatusResult = z.object({
     .describe('Currently applied simulation time-scale, or null when never successfully set.'),
 });
 
-export const playStatus = defineOperation({
+export const playStatus = defineTool({
   name: 'play.status',
   summary: 'Read the current play-mode status (running/paused/stopped, seed, time-scale).',
   description:
@@ -97,7 +97,7 @@ export const playStatus = defineOperation({
       'play.status',
     ).catch(() => undefined);
     if (!status) {
-      throw new OperationError(
+      throw new ToolError(
         'PLAY_STATUS_UNAVAILABLE',
         'The connected editor session did not answer the status read in time.',
         {},
@@ -120,7 +120,7 @@ const PlayActiveWorldInspectResult = z.object({
   worldKind: z.string(),
 });
 
-export const playActiveWorldInspect = defineOperation({
+export const playActiveWorldInspect = defineTool({
   name: 'play.activeWorld.inspect',
   summary: 'Inspect the active world of a running play session (id/kind).',
   description:
@@ -144,7 +144,7 @@ export const playActiveWorldInspect = defineOperation({
       'play.activeWorld.inspect',
     ).catch(() => undefined);
     if (!world) {
-      throw new OperationError(
+      throw new ToolError(
         'ACTIVE_WORLD_UNAVAILABLE',
         "The connected editor's wire protocol does not carry active-world data today.",
         {},
@@ -154,7 +154,7 @@ export const playActiveWorldInspect = defineOperation({
   },
 });
 
-export function registerStatusOperations(registry: OperationRegistry): void {
+export function registerStatusOperations(registry: ToolRegistry): void {
   registry.register(playStatus);
   registry.register(playActiveWorldInspect);
 }

package/src/play/transport.ts

@@ -78,9 +78,9 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import type { ErrorDefinition } from '../registry.js';
-import type { OperationContext } from '../types.js';
+import { ToolError } from '../errors.js';
+import type { ToolErrorDefinition } from '../registry.js';
+import type { ToolContext } from '../types.js';
 
 // ---------------------------------------------------------------------------
 // Named timeouts
@@ -92,8 +92,35 @@ export const PLAY_SESSION_DISCOVERY_TIMEOUT_MS = 2000;
 export const PLAY_PROBE_TIMEOUT_MS = 1500;
 /** Bound on a plain read (status, log-entries count, ...). */
 export const PLAY_READ_TIMEOUT_MS = 3000;
-/** Bound on a relayed pause/resume/stop/frame-step command — mirrors the relay's generic `COMMAND_TIMEOUT_MS` (editor-server.ts). */
-export const PLAY_COMMAND_TIMEOUT_MS = 5000;
+/**
+ * Bound on a relayed pause/resume/stop/frame-step command.
+ *
+ * The relay's own generic window is `COMMAND_TIMEOUT_MS = 5000`
+ * (`packages/editor/server/editor-server.ts`), and this bound must sit ABOVE
+ * it for exactly the reason `PLAY_START_TIMEOUT_MS` documents below: the
+ * client's clock starts before the request has even reached the server, so a
+ * client bound EQUAL to the server's can only ever fire first. It did. A
+ * command the editor merely answered slowly came back as
+ * `AbortSignal.timeout` → `postJson` returning undefined → "Command relay
+ * unreachable." — which reads as "no editor is running" and sends the caller
+ * to restart a perfectly healthy session. The server's own honest verdict
+ * ("editor connected but did not respond", `timedOut: true`) could never be
+ * delivered, because nobody was still listening when it was written.
+ *
+ * Caught by 39-play-sdk-live's AC-A2.3/AC-A2.5, where every
+ * `play.gameplayState.inspect` poll reported an unreachable relay while
+ * `play.input.inject` on the same session had just succeeded.
+ *
+ * 8000 was not enough margin. The server's generic window is 5000
+ * (`COMMAND_TIMEOUT_MS`), so 8000 left 3s to cover the request reaching the
+ * server, the SSE hop to the browser, the result hop back, and the response —
+ * and on a loaded machine that is not enough: the 2026-07-27 nightly saw the
+ * same misleading "Command relay unreachable." on a session that was fine.
+ * Waiting longer costs a HEALTHY call nothing (it returns as soon as the
+ * browser answers); the bound exists only to cap the pathological path, and
+ * on that path the server's own verdict is the message worth having.
+ */
+export const PLAY_COMMAND_TIMEOUT_MS = 20_000;
 /**
  * Bound on `play.start`. Mirrors the real relay's own
  * `PLAY_COMMAND_TIMEOUT_MS = 120_000` (`packages/editor/server/editor-server.ts:385`)
@@ -145,6 +172,8 @@ export interface PlaySessionInfo {
   port: number;
   project: string | null;
   pid: number | null;
+  /** Registry discriminator. `kind: 'e2e'` is standalone and cannot host editor-relayed play control. */
+  kind?: string;
   /** Exact explicitly targeted editor origin/base URL, including protocol and host. */
   url?: string;
 }
@@ -364,6 +393,7 @@ interface RegistrySessionEntry {
   port: number;
   pid: number;
   startedAt: string;
+  kind?: string;
 }
 
 function isRegistrySessionEntry(v: unknown): v is RegistrySessionEntry {
@@ -373,7 +403,8 @@ function isRegistrySessionEntry(v: unknown): v is RegistrySessionEntry {
     (typeof s['project'] === 'string' || s['project'] === null) &&
     typeof s['port'] === 'number' &&
     typeof s['pid'] === 'number' &&
-    typeof s['startedAt'] === 'string'
+    typeof s['startedAt'] === 'string' &&
+    (s['kind'] === undefined || typeof s['kind'] === 'string')
   );
 }
 
@@ -393,7 +424,10 @@ function readRegisteredSessions(): RegistrySessionEntry[] {
   try {
     const raw: unknown = JSON.parse(readFileSync(registryFile, 'utf8'));
     return Array.isArray(raw)
-      ? raw.filter(isRegistrySessionEntry).filter((s) => pidAlive(s.pid))
+      ? raw
+          .filter(isRegistrySessionEntry)
+          .filter((s) => s.kind !== 'e2e')
+          .filter((s) => pidAlive(s.pid))
       : [];
   } catch {
     return [];
@@ -410,11 +444,39 @@ async function fetchJson(url: string, timeoutMs: number): Promise<unknown | unde
   }
 }
 
-async function postJson(
-  url: string,
-  body: unknown,
-  timeoutMs: number,
-): Promise<{ status: number; json: unknown } | undefined> {
+/** Either a response came back, or it didn't and `reason` says why.
+ *
+ *  This used to be `… | undefined`, and the single caller turned every
+ *  `undefined` into the same sentence: "Command relay unreachable." That
+ *  sentence names a CONNECTION fault, but the `catch` it came from covers a
+ *  refused socket, a DNS failure, an aborted request, and a body that never
+ *  arrived — four different diagnoses wearing one message. The cost is on the
+ *  record: the 2026-07-27 nightly reported an unreachable relay, the message
+ *  read as "no editor is running", the fix went into timeout constants
+ *  (`PLAY_COMMAND_TIMEOUT_MS`, twice), and the run stayed red because the
+ *  actual cause was never in the log. The relay's SERVER always answers within
+ *  its per-type window with an explicit verdict (`relayCommand`,
+ *  editor-server.ts) — so when nothing comes back at all, WHICH transport
+ *  fault it was is the entire diagnosis, and it is the one thing we were
+ *  throwing away. */
+type PostOutcome =
+  | { delivered: true; status: number; json: unknown }
+  | { delivered: false; reason: string };
+
+/** Turn a `fetch` rejection into something a caller can act on. Undici hangs
+ *  the useful part off `cause.code` (`ECONNREFUSED`, `ENOTFOUND`, …) while the
+ *  abort path shows up as the error's own `name`. */
+function describeFetchFailure(error: unknown, timeoutMs: number): string {
+  const err = error as { name?: string; message?: string; cause?: { code?: string } };
+  if (err?.name === 'TimeoutError' || err?.name === 'AbortError') {
+    return `no response within ${timeoutMs}ms`;
+  }
+  const code = err?.cause?.code;
+  if (typeof code === 'string') return code;
+  return err?.message ?? String(error);
+}
+
+async function postJson(url: string, body: unknown, timeoutMs: number): Promise<PostOutcome> {
   try {
     const res = await fetch(url, {
       method: 'POST',
@@ -423,9 +485,9 @@ async function postJson(
       signal: AbortSignal.timeout(timeoutMs),
     });
     const json = await res.json().catch(() => undefined);
-    return { status: res.status, json };
-  } catch {
-    return undefined;
+    return { delivered: true, status: res.status, json };
+  } catch (error) {
+    return { delivered: false, reason: describeFetchFailure(error, timeoutMs) };
   }
 }
 
@@ -438,8 +500,11 @@ async function relayCommand(
   command: Record<string, unknown>,
   timeoutMs: number,
 ): Promise<PlayCommandResult> {
-  const result = await postJson(`${baseUrl(session)}/__editor/command`, command, timeoutMs);
-  if (!result) return { ok: false, error: 'Command relay unreachable.' };
+  const target = `${baseUrl(session)}/__editor/command`;
+  const result = await postJson(target, command, timeoutMs);
+  if (!result.delivered) {
+    return { ok: false, error: `Command relay unreachable (${target}): ${result.reason}.` };
+  }
   const json = result.json as Record<string, unknown> | undefined;
   // `commandResponseFor` (editor server-utils.ts) SPREADS the browser
   // handler's `data` into the response body at the top level, beside
@@ -498,7 +563,12 @@ export class HttpPlayTransport implements PlayTransport {
         );
         if (body === undefined) return undefined;
         const project = (body as { project?: { path?: string } | null }).project?.path ?? null;
-        const info: PlaySessionInfo = { port: s.port, project, pid: s.pid };
+        const info: PlaySessionInfo = {
+          port: s.port,
+          project,
+          pid: s.pid,
+          ...(s.kind !== undefined ? { kind: s.kind } : {}),
+        };
         return info;
       }),
     );
@@ -673,7 +743,7 @@ export class HttpPlayTransport implements PlayTransport {
 const defaultTransport = new HttpPlayTransport();
 
 /** Resolve the transport to use: `ctx['playTransport']` when injected (tests), else the shared real transport. */
-export function getPlayTransport(ctx: OperationContext): PlayTransport {
+export function getPlayTransport(ctx: ToolContext): PlayTransport {
   const injected = ctx['playTransport'];
   return (injected as PlayTransport | undefined) ?? defaultTransport;
 }
@@ -683,7 +753,7 @@ export function getPlayTransport(ctx: OperationContext): PlayTransport {
 // + deterministic session resolution
 // ---------------------------------------------------------------------------
 
-export const PLAY_RUNTIME_NOT_AVAILABLE_ERROR: ErrorDefinition = {
+export const PLAY_RUNTIME_NOT_AVAILABLE_ERROR: ToolErrorDefinition = {
   code: 'EDITOR_NOT_RUNNING',
   summary:
     'No live, responsive editor session is available to host a play runtime (none running, ' +
@@ -717,12 +787,12 @@ function portOf(url: string): number | undefined {
  * > `ctx.projectRoot` match > lowest live port > `EDITOR_NOT_RUNNING`.
  */
 export async function resolvePlaySession(
-  ctx: OperationContext,
+  ctx: ToolContext,
   transport: Pick<PlayTransport, 'listSessions' | 'probeSessionUrl'>,
 ): Promise<PlaySessionInfo> {
   const editorUrl = ctx.editorUrl;
   const notRunning = (): never => {
-    throw new OperationError('EDITOR_NOT_RUNNING', 'No editor connected to host a play runtime.', {
+    throw new ToolError('EDITOR_NOT_RUNNING', 'No editor connected to host a play runtime.', {
       ...(editorUrl !== undefined ? { editorUrl } : {}),
     });
   };
@@ -749,6 +819,7 @@ export async function resolvePlaySession(
   } catch {
     return notRunning();
   }
+  sessions = sessions.filter((session) => session.kind !== 'e2e');
   if (sessions.length === 0) return notRunning();
 
   if (editorUrl !== undefined) {