feat(web): start and stop managed VM instances through hooks

VM management solutions had no way to boot or shut down the machine
hosting a T3 server from inside T3 Code, so users had to open the
management app before every remote session.

The server's settings gain nullable startHookUrl/stopHookUrl, delivered
to clients inside the cached server config. On Settings -> Connections,
Connect now POSTs the start hook first, renders its component form when
the endpoint asks for input, polls until the instance reports ready with
a 204, then runs the normal connect flow. Connected environments with a
stop hook show a Stop button backed by a new server.runStopHook RPC; the
server DELETEs the endpoint and clears the setting on a 404 so clients
drop the control.

Done by Claude Fable 5 on Claude Code.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: IAmJSD

apps/server/src/auth/RpcAuthorization.ts

@@ -39,6 +39,7 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.serverRemoveKeybinding]: AuthOrchestrationOperateScope,
   [WS_METHODS.serverGetSettings]: AuthOrchestrationReadScope,
   [WS_METHODS.serverUpdateSettings]: AuthOrchestrationOperateScope,
+  [WS_METHODS.serverRunStopHook]: AuthOrchestrationOperateScope,
   [WS_METHODS.serverDiscoverSourceControl]: AuthOrchestrationReadScope,
   [WS_METHODS.serverGetTraceDiagnostics]: AuthOrchestrationReadScope,
   [WS_METHODS.serverGetProcessDiagnostics]: AuthOrchestrationReadScope,

apps/server/src/instanceHooks.test.ts

@@ -0,0 +1,102 @@
+import { ServerStopHookError } from "@t3tools/contracts";
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+
+import * as InstanceHooks from "./instanceHooks.ts";
+import * as ServerSettings from "./serverSettings.ts";
+
+interface RecordedHookRequest {
+  readonly method: string;
+  readonly url: string;
+}
+
+const makeHookEndpointLayer = (requests: Array<RecordedHookRequest>, status: number) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.sync(() => {
+        requests.push({ method: request.method, url: request.url });
+        return HttpClientResponse.fromWeb(request, new Response(null, { status }));
+      }),
+    ),
+  );
+
+const isStopHookError = Schema.is(ServerStopHookError);
+
+it.effect("DELETEs the stop hook and reports the instance as stopping on 204", () =>
+  Effect.gen(function* () {
+    const requests: Array<RecordedHookRequest> = [];
+    const result = yield* InstanceHooks.runStopHook.pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          makeHookEndpointLayer(requests, 204),
+          ServerSettings.layerTest({ stopHookUrl: "https://mgmt.example.test/instances/1/stop" }),
+        ),
+      ),
+    );
+    assert.deepEqual(result, { outcome: "stopped" });
+    assert.deepEqual(requests, [
+      { method: "DELETE", url: "https://mgmt.example.test/instances/1/stop" },
+    ]);
+  }),
+);
+
+it.effect("clears the stop hook setting when the endpoint is gone", () =>
+  Effect.gen(function* () {
+    const requests: Array<RecordedHookRequest> = [];
+    const settingsLayer = ServerSettings.layerTest({
+      stopHookUrl: "https://mgmt.example.test/instances/1/stop",
+    });
+    const result = yield* Effect.gen(function* () {
+      const outcome = yield* InstanceHooks.runStopHook.pipe(
+        Effect.provide(makeHookEndpointLayer(requests, 404)),
+      );
+      const settings = yield* (yield* ServerSettings.ServerSettingsService).getSettings;
+      return { outcome, stopHookUrl: settings.stopHookUrl };
+    }).pipe(Effect.provide(settingsLayer));
+    assert.deepEqual(result.outcome, { outcome: "gone" });
+    assert.equal(result.stopHookUrl, null);
+  }),
+);
+
+it.effect("fails when no stop hook is configured", () =>
+  Effect.gen(function* () {
+    const requests: Array<RecordedHookRequest> = [];
+    const failure = yield* InstanceHooks.runStopHook.pipe(
+      Effect.provide(
+        Layer.mergeAll(makeHookEndpointLayer(requests, 204), ServerSettings.layerTest()),
+      ),
+      Effect.flip,
+    );
+    assert.isTrue(isStopHookError(failure));
+    assert.equal(isStopHookError(failure) ? failure.reason : null, "not-configured");
+    assert.deepEqual(requests, []);
+  }),
+);
+
+it.effect("surfaces unexpected statuses without clearing the hook", () =>
+  Effect.gen(function* () {
+    const requests: Array<RecordedHookRequest> = [];
+    const settingsLayer = ServerSettings.layerTest({
+      stopHookUrl: "https://mgmt.example.test/instances/1/stop",
+    });
+    const result = yield* Effect.gen(function* () {
+      const failure = yield* InstanceHooks.runStopHook.pipe(
+        Effect.provide(makeHookEndpointLayer(requests, 500)),
+        Effect.flip,
+      );
+      const settings = yield* (yield* ServerSettings.ServerSettingsService).getSettings;
+      return { failure, stopHookUrl: settings.stopHookUrl };
+    }).pipe(Effect.provide(settingsLayer));
+    assert.isTrue(isStopHookError(result.failure));
+    assert.equal(
+      isStopHookError(result.failure) ? result.failure.reason : null,
+      "unexpected-status",
+    );
+    assert.equal(result.stopHookUrl, "https://mgmt.example.test/instances/1/stop");
+  }),
+);

apps/server/src/instanceHooks.ts

@@ -0,0 +1,37 @@
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import { ServerStopHookError, type ServerStopHookResult } from "@t3tools/contracts";
+
+import * as ServerSettings from "./serverSettings.ts";
+
+const STOP_HOOK_TIMEOUT = "20 seconds";
+
+/**
+ * Run the configured stop hook: DELETE the management endpoint that stops
+ * this instance. A 204 reports the instance as stopping. A 404 means the
+ * hook no longer exists, so the setting is cleared and clients drop their
+ * stop controls with it.
+ */
+export const runStopHook = Effect.gen(function* () {
+  const serverSettings = yield* ServerSettings.ServerSettingsService;
+  const httpClient = yield* HttpClient.HttpClient;
+  const settings = yield* serverSettings.getSettings;
+  if (settings.stopHookUrl === null) {
+    return yield* new ServerStopHookError({ reason: "not-configured" });
+  }
+  const response = yield* httpClient.execute(HttpClientRequest.delete(settings.stopHookUrl)).pipe(
+    Effect.timeout(STOP_HOOK_TIMEOUT),
+    Effect.mapError(
+      (error) => new ServerStopHookError({ reason: "request-failed", detail: String(error) }),
+    ),
+  );
+  if (response.status === 204) {
+    return { outcome: "stopped" } satisfies ServerStopHookResult;
+  }
+  if (response.status === 404) {
+    yield* serverSettings.updateSettings({ stopHookUrl: null });
+    return { outcome: "gone" } satisfies ServerStopHookResult;
+  }
+  return yield* new ServerStopHookError({ reason: "unexpected-status", status: response.status });
+});

apps/server/src/ws.ts

@@ -59,7 +59,12 @@ import {
   WsRpcGroup,
 } from "@t3tools/contracts";
 import { resolveServerBackgroundActivitySettings } from "@t3tools/shared/backgroundActivitySettings";
-import { HttpRouter, HttpServerRequest, HttpServerRespondable } from "effect/unstable/http";
+import {
+  HttpClient,
+  HttpRouter,
+  HttpServerRequest,
+  HttpServerRespondable,
+} from "effect/unstable/http";
 import { RpcSerialization, RpcServer } from "effect/unstable/rpc";
 
 import * as CheckpointDiffQuery from "./checkpointing/CheckpointDiffQuery.ts";
@@ -83,6 +88,7 @@ import * as ProviderMaintenanceRunner from "./provider/providerMaintenanceRunner
 import * as ServerSelfUpdate from "./cloud/selfUpdate.ts";
 import * as ServerLifecycleEvents from "./serverLifecycleEvents.ts";
 import * as ServerRuntimeStartup from "./serverRuntimeStartup.ts";
+import * as InstanceHooks from "./instanceHooks.ts";
 import * as ServerSettings from "./serverSettings.ts";
 import * as TerminalManager from "./terminal/Manager.ts";
 import * as PreviewAutomationBroker from "./mcp/PreviewAutomationBroker.ts";
@@ -372,6 +378,7 @@ const makeWsRpcLayer = (
       const config = yield* ServerConfig.ServerConfig;
       const lifecycleEvents = yield* ServerLifecycleEvents.ServerLifecycleEvents;
       const serverSettings = yield* ServerSettings.ServerSettingsService;
+      const stopHookHttpClient = yield* HttpClient.HttpClient;
       const startup = yield* ServerRuntimeStartup.ServerRuntimeStartup;
       const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
       const workspaceFileSystem = yield* WorkspaceFileSystem.WorkspaceFileSystem;
@@ -1490,6 +1497,17 @@ const makeWsRpcLayer = (
               "rpc.aggregate": "server",
             },
           ),
+        [WS_METHODS.serverRunStopHook]: (_input) =>
+          observeRpcEffect(
+            WS_METHODS.serverRunStopHook,
+            InstanceHooks.runStopHook.pipe(
+              Effect.provideService(ServerSettings.ServerSettingsService, serverSettings),
+              Effect.provideService(HttpClient.HttpClient, stopHookHttpClient),
+            ),
+            {
+              "rpc.aggregate": "server",
+            },
+          ),
         [WS_METHODS.serverDiscoverSourceControl]: (_input) =>
           observeRpcEffect(
             WS_METHODS.serverDiscoverSourceControl,