tinker-agent 2.13.0 → 3.0.0

package/src/cli/serve-runner.ts

@@ -1,45 +1,179 @@
-import { loadRemoteConfig } from "../remote/config";
+import { loadPackageMetadata } from "./package-metadata";
+import { prepareDefaultServiceConfig } from "./default-service-config";
+import { stopLocalService } from "./service-control";
+import {
+  disableSupervisor,
+  installSupervisor,
+  startSupervisor,
+  uninstallSupervisor,
+  supervisedEnvironment,
+  supervisorPaths,
+} from "./service-supervisor";
+import {
+  defaultServiceConfigPath,
+  discoverLocalService,
+  loadLocalServiceTarget,
+  publishLocalService,
+} from "../remote/local-service-discovery";
+import { ensureLocalService } from "./local-service-start";
 import { startRemoteHttpServer } from "../remote/http-server";
 import { RemoteService } from "../remote/service";
 import { RemoteServiceStore } from "../remote/service-store";
-import { defaultHomeRoot } from "../session/workspace-storage";
 import { createHostedRuntimeFactory } from "./serve-runtime";
 import { writeCliOutput, type CliOutputWriter } from "./output";
 
 export async function runServe(input: {
-  configPath: string;
+  configPath?: string;
+  background?: boolean;
+  install?: boolean;
+  uninstall?: boolean;
+  stop?: boolean;
+  restart?: boolean;
+  force?: boolean;
+  status?: boolean;
   env: NodeJS.ProcessEnv;
   stdout: CliOutputWriter;
 }): Promise<number> {
-  const config = await loadRemoteConfig(input.configPath);
-  const homeRoot = defaultHomeRoot(input.env);
-  const store = await RemoteServiceStore.open(config.stateDirectory);
-  const service = new RemoteService(
-    store,
-    config.workspaces,
-    createHostedRuntimeFactory(config.workspaces, input.env, homeRoot),
-    homeRoot,
+  const env = await supervisedEnvironment(input.env);
+  // MCP and tool subprocesses inherit the service process environment.
+  if (input.env.TINKER_SERVICE_ENV_FILE) Object.assign(process.env, env);
+  if (input.install && !input.configPath) await prepareDefaultServiceConfig(env);
+  const target = await loadLocalServiceTarget(
+    input.configPath ?? defaultServiceConfigPath(env),
+    env,
   );
+  if (input.install && (await Bun.file(supervisorPaths(target).marker).exists())) {
+    const instance = await ensureLocalService(target, env);
+    await writeCliOutput(
+      input.stdout,
+      `${JSON.stringify({ status: "online", ...instance })}\n`,
+    );
+    return 0;
+  }
+  if (input.install || input.uninstall || input.stop || input.restart) {
+    await disableSupervisor(target);
+    try {
+      await stopLocalService(target, input.force);
+    } catch (error) {
+      await startSupervisor(target).catch(() => undefined);
+      throw error;
+    }
+    if (input.uninstall) await uninstallSupervisor(target);
+    if (input.install) await installSupervisor(target, env);
+    const instance =
+      input.install || input.restart
+        ? await ensureLocalService(target, env)
+        : undefined;
+    await writeCliOutput(
+      input.stdout,
+      `${JSON.stringify(instance ? { status: "online", ...instance } : { status: "stopped", stateDirectory: target.config.stateDirectory })}\n`,
+    );
+    return 0;
+  }
+  if (input.background || input.status) {
+    const instance = input.status
+      ? await discoverLocalService(target, true)
+      : await ensureLocalService(target, env);
+    await writeCliOutput(
+      input.stdout,
+      `${JSON.stringify(
+        instance
+          ? { status: "online", ...instance }
+          : {
+              status: "offline",
+              configPath: target.configPath,
+              stateDirectory: target.config.stateDirectory,
+            },
+      )}\n`,
+    );
+    return instance ? 0 : 1;
+  }
+  const { config, homeRoot } = target;
+  const store = await RemoteServiceStore.open(config.stateDirectory);
+  let service: RemoteService;
+  try {
+    service = new RemoteService(
+      store,
+      config.workspaces,
+      createHostedRuntimeFactory(() => service.workspaces, env, homeRoot),
+      homeRoot,
+      config.resident,
+    );
+  } catch (error) {
+    await store.close();
+    throw error;
+  }
   let transport: ReturnType<typeof startRemoteHttpServer> | undefined;
+  let unpublish: (() => Promise<void>) | undefined;
+  let stopRequested = false;
+  let signalStop: (() => void) | undefined;
+  let hardStop: ReturnType<typeof setTimeout> | undefined;
+  const setDeadline = () => {
+    hardStop ??= setTimeout(
+      () => {
+        console.error(
+          "Service shutdown timed out; recovery will mark unfinished work interrupted on restart.",
+        );
+        process.exit(1);
+      },
+      (config.resident?.shutdownGraceMs ?? 30000) + 10000,
+    );
+    hardStop.unref();
+  };
+  const stop = () => {
+    setDeadline();
+    stopRequested = true;
+    signalStop?.();
+  };
+  const onSignal = () => {
+    setDeadline();
+    void service
+      .drain(true)
+      .catch(() => undefined)
+      .finally(stop);
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
   try {
     await service.initialize();
     transport = startRemoteHttpServer(service, config);
+    if (stopRequested) return 0;
+    if (process.platform !== "win32")
+      unpublish = await publishLocalService(
+        target,
+        service.epoch,
+        transport.port,
+        (directory) => service.registerLocalWorkspace(directory),
+        {
+          appVersion: (await loadPackageMetadata()).version,
+          status: () => service.residentStatus(),
+          shutdown: async (force) => {
+            await service.drain(force);
+            return stop;
+          },
+        },
+      );
     await writeCliOutput(
       input.stdout,
-      `Tinker service listening on https://${config.hostname}:${transport.port}; ${config.workspaces.length} workspace(s).\nClient disconnects detach only. Stop the process to shut down hosted sessions.\n`,
+      `Tinker service listening on https://${config.hostname === "::1" ? "[::1]" : config.hostname}:${transport.port}; ${service.workspaces.length} workspace(s).\nClient disconnects detach only. Stop the process to shut down hosted sessions.\n`,
     );
     await new Promise<void>((resolve) => {
-      const stop = () => {
-        process.off("SIGINT", stop);
-        process.off("SIGTERM", stop);
-        resolve();
-      };
-      process.once("SIGINT", stop);
-      process.once("SIGTERM", stop);
+      signalStop = resolve;
+      if (stopRequested) resolve();
     });
     return 0;
   } finally {
-    await transport?.stopTransport();
-    await service.close();
+    process.off("SIGINT", onSignal);
+    process.off("SIGTERM", onSignal);
+    try {
+      await unpublish?.();
+    } finally {
+      try {
+        await transport?.stopTransport();
+      } finally {
+        await service.close();
+        if (hardStop) clearTimeout(hardStop);
+      }
+    }
   }
 }

package/src/cli/serve-runtime.ts

@@ -1,32 +1,23 @@
-import { createRuntimeSession } from "../agent/runtime-session";
 import { parseSessionId } from "../ids/runtime-id";
-import {
-  buildSystemPrompt,
-  loadProjectInstructions,
-  projectInstructionManifest,
-} from "../instructions/project-instructions";
-import { createReasoningEffortController } from "../model/reasoning-effort";
 import { resolveSessionDatabasePath } from "../session/session-store";
 import { SessionCatalog } from "../session/session-catalog";
-import { loadSkillCatalog } from "../skills/skill-loader";
 import type { RemoteWorkspaceConfig } from "../remote/config";
 import type { HostedRuntimeFactory } from "../agent/runtime-hosted-session";
 import { deriveRunnerConfig, resolvePublicConfig } from "./config";
 import { resolveSessionProfileName } from "./model-profiles";
-import {
-  createRunnerModelClient,
-  createWebFetchRefiner,
-  RUNTIME_INSTRUCTIONS,
-} from "./runner-dependencies";
+import { createInteractiveRuntimeSession } from "./interactive-runtime";
 
 /** Service composition reuses the existing configuration/provider/runtime contracts. */
 export function createHostedRuntimeFactory(
-  workspaces: readonly RemoteWorkspaceConfig[],
+  workspaces:
+    | readonly RemoteWorkspaceConfig[]
+    | (() => readonly RemoteWorkspaceConfig[]),
   env: NodeJS.ProcessEnv,
   homeRoot?: string,
 ): HostedRuntimeFactory {
-  return async ({ record, sink }) => {
-    const workspace = workspaces.find((entry) => entry.id === record.workspaceId);
+  const entries = () => (typeof workspaces === "function" ? workspaces() : workspaces);
+  const factory: HostedRuntimeFactory = async ({ record, sink, lease }) => {
+    const workspace = entries().find((entry) => entry.id === record.workspaceId);
     if (!workspace || workspace.path !== record.workspacePath)
       throw new Error("Managed workspace configuration changed.");
     const sessionId = parseSessionId(record.id);
@@ -34,7 +25,7 @@ export function createHostedRuntimeFactory(
       env: { ...env, TINKER_WORKSPACE: workspace.path },
       cwd: workspace.path,
     });
-    let profileName = workspace.profile;
+    let profileName = record.profileName ?? workspace.profile;
     if (record.initialized && publicConfig.mode === "profile") {
       const summary = await new SessionCatalog({
         workspaceRoot: workspace.path,
@@ -46,38 +37,16 @@ export function createHostedRuntimeFactory(
       sessionId,
       ...(profileName ? { profileName } : {}),
     });
-    const reasoning = createReasoningEffortController(config.reasoning);
-    const projectInstructions = await loadProjectInstructions(workspace.path);
-    const runtime = await createRuntimeSession({
+    const runtime = await createInteractiveRuntimeSession({
+      config,
+      sessionLease: lease,
       workspaceRoot: workspace.path,
       ...(homeRoot === undefined ? {} : { homeRoot }),
-      ...(record.initialized
-        ? { selection: { mode: "resume" as const, sessionId } }
-        : { selection: { mode: "new" as const, sessionId } }),
-      modelName: config.modelName,
-      profileName: config.profileName,
-      maxIterations: config.maxIterations,
-      includeReasoningContent: config.includeReasoningContent,
-      contextProfile: config.contextProfile,
-      contextBudget: config.contextBudget,
-      modelClient: createRunnerModelClient(config, undefined, env, reasoning),
-      systemPrompt: buildSystemPrompt({
-        workspaceRoot: workspace.path,
-        runtimeInstructions: RUNTIME_INSTRUCTIONS(workspace.path),
-        projectInstructions,
-      }),
-      projectInstruction: projectInstructionManifest(projectInstructions),
-      skillCatalog: await loadSkillCatalog({ workspaceRoot: workspace.path }),
-      presentationSinks: [sink],
-      assistantTextDeltaSink: sink,
+      selection: { mode: record.initialized ? "resume" : "new", sessionId },
       toolingConfig: publicConfig.tooling,
-      webFetchRefiner: createWebFetchRefiner(config, env, reasoning),
-      enableAskUser: true,
-      bashGuard: {
-        mode: config.bashGuardMode,
-        source: config.bashGuardSource,
-        surface: "tui",
-      },
+      env,
+      sink,
+      owner: "service",
     });
     try {
       return {
@@ -88,6 +57,8 @@ export function createHostedRuntimeFactory(
           homeRoot,
         ),
         modelName: config.modelName,
+        profileName: config.profileName,
+        modelCatalog: await factory.profiles!(workspace.id),
       };
     } catch (error) {
       await runtime.dispose({
@@ -97,4 +68,34 @@ export function createHostedRuntimeFactory(
       throw error;
     }
   };
+  const readConfig = async (workspaceId: string) => {
+    const workspace = entries().find((entry) => entry.id === workspaceId);
+    if (!workspace) throw new Error("Workspace is not configured.");
+    return resolvePublicConfig({
+      env: { ...env, TINKER_WORKSPACE: workspace.path },
+      cwd: workspace.path,
+    });
+  };
+  factory.profiles = async (workspaceId) => {
+    const config = await readConfig(workspaceId);
+    if (config.mode !== "profile") return undefined;
+    return {
+      defaultProfile: config.profiles.defaultProfile,
+      profiles: [...config.profiles.profiles.values()].map(
+        ({ name, model, contextWindowTokens, maxSupportedOutputTokens }) => ({
+          name,
+          model,
+          contextWindowTokens,
+          maxSupportedOutputTokens,
+        }),
+      ),
+    };
+  };
+  factory.persistDefaultProfile = async (workspaceId, profileName) => {
+    const config = await readConfig(workspaceId);
+    if (config.mode !== "profile")
+      throw new Error("Model profiles are not configured.");
+    await config.persistDefaultProfile(profileName);
+  };
+  return factory;
 }

package/src/cli/service-control.ts

@@ -0,0 +1,27 @@
+import { inspectSessionLock } from "../session/session-lock";
+import { SERVICE_LEASE_ID } from "../remote/service-store";
+import {
+  shutdownLocalService,
+  type LocalServiceTarget,
+} from "../remote/local-service-discovery";
+
+/** Uses the private live endpoint; never sends signals to a PID from stale metadata. */
+export async function stopLocalService(
+  target: LocalServiceTarget,
+  force = false,
+): Promise<void> {
+  await shutdownLocalService(target, force);
+  const deadline =
+    Date.now() + (target.config.resident?.shutdownGraceMs ?? 30000) + 15000;
+  while (Date.now() < deadline) {
+    const ownership = await inspectSessionLock({
+      sessionDirectory: target.config.stateDirectory,
+      sessionId: SERVICE_LEASE_ID,
+    });
+    if (ownership === "none" || ownership === "stale") return;
+    await Bun.sleep(50);
+  }
+  throw new Error(
+    `Service has not released ownership. Inspect ${target.config.stateDirectory}; no process was killed automatically.`,
+  );
+}

package/src/cli/service-supervisor.ts

@@ -0,0 +1,170 @@
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile, chmod } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { LocalServiceTarget } from "../remote/local-service-discovery";
+
+export function supervisorPaths(target: LocalServiceTarget) {
+  const label = `dev.tinker.service.${createHash("sha256").update(target.config.stateDirectory).digest("hex").slice(0, 16)}`;
+  return {
+    label,
+    job: `gui/${process.getuid?.()}/${label}`,
+    plist: path.join(homedir(), "Library/LaunchAgents", `${label}.plist`),
+    enabled: path.join(target.config.stateDirectory, "supervisor.enabled"),
+    environment: path.join(target.config.stateDirectory, "supervisor-env.json"),
+    marker: path.join(target.config.stateDirectory, "supervisor.json"),
+  };
+}
+const xml = (text: string) =>
+  text.replace(
+    /[&<>"']/g,
+    (c) =>
+      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[c]!,
+  );
+export function launchAgentPlist(target: LocalServiceTarget): string {
+  const files = supervisorPaths(target);
+  const args = [
+    process.execPath,
+    fileURLToPath(new URL("./index.ts", import.meta.url)),
+    "serve",
+    "--config",
+    target.configPath,
+  ];
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>
+<key>Label</key><string>${xml(files.label)}</string>
+<key>ProgramArguments</key><array>${args.map((value) => `<string>${xml(value)}</string>`).join("")}</array>
+<key>WorkingDirectory</key><string>${xml(path.dirname(target.configPath))}</string>
+<key>EnvironmentVariables</key><dict><key>TINKER_HOME</key><string>${xml(target.homeRoot)}</string><key>TINKER_SERVICE_ENV_FILE</key><string>${xml(files.environment)}</string></dict>
+<key>KeepAlive</key><dict><key>PathState</key><dict><key>${xml(files.enabled)}</key><true/></dict></dict>
+<key>ThrottleInterval</key><integer>10</integer>
+<key>ExitTimeOut</key><integer>${Math.ceil((target.config.resident?.shutdownGraceMs ?? 30000) / 1000) + 10}</integer>
+<key>StandardOutPath</key><string>${xml(path.join(target.config.stateDirectory, "service.log"))}</string>
+<key>StandardErrorPath</key><string>${xml(path.join(target.config.stateDirectory, "service.log"))}</string>
+<key>Umask</key><integer>63</integer>
+</dict></plist>\n`;
+}
+export async function launchctl(args: string[]): Promise<void> {
+  const child = Bun.spawn(["/bin/launchctl", ...args], {
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const [error, code] = await Promise.all([
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  if (code !== 0)
+    throw new Error(`launchctl ${args[0]} failed (${code}): ${error.trim()}`);
+}
+export async function installSupervisor(
+  target: LocalServiceTarget,
+  env: NodeJS.ProcessEnv,
+): Promise<void> {
+  if (process.platform !== "darwin")
+    throw new Error(
+      "System supervision currently supports macOS LaunchAgents; use serve --background elsewhere.",
+    );
+  const files = supervisorPaths(target);
+  if (await Bun.file(files.marker).exists())
+    throw new Error(
+      "Supervision is already installed. Stop and uninstall before replacing its configuration.",
+    );
+  await mkdir(path.dirname(files.plist), { recursive: true, mode: 0o700 });
+  await mkdir(target.config.stateDirectory, { recursive: true, mode: 0o700 });
+  const kept = Object.fromEntries(
+    Object.entries(env).filter(
+      ([key, value]) =>
+        value !== undefined &&
+        key !== "TINKER_SERVICE_ENV_FILE" &&
+        (key.startsWith("TINKER_") ||
+          [
+            "PATH",
+            "HOME",
+            "LANG",
+            "LC_ALL",
+            "TZ",
+            "EXA_API_KEY",
+            "HTTP_PROXY",
+            "HTTPS_PROXY",
+            "ALL_PROXY",
+            "NO_PROXY",
+            "SSL_CERT_FILE",
+            "SSL_CERT_DIR",
+          ].includes(key)),
+    ),
+  );
+  await writeFile(
+    files.environment,
+    JSON.stringify({ ...kept, TINKER_HOME: target.homeRoot }) + "\n",
+    { mode: 0o600, flag: "wx" },
+  );
+  let wrotePlist = false;
+  let bootstrapped = false;
+  try {
+    await writeFile(files.plist, launchAgentPlist(target), { mode: 0o600, flag: "wx" });
+    wrotePlist = true;
+    await writeFile(files.enabled, "enabled\n", { mode: 0o600 });
+    await launchctl(["bootstrap", `gui/${process.getuid?.()}`, files.plist]);
+    bootstrapped = true;
+    await writeFile(
+      files.marker,
+      JSON.stringify({ version: 1, label: files.label }) + "\n",
+      { mode: 0o600 },
+    );
+  } catch (error) {
+    await rm(files.enabled, { force: true });
+    if (bootstrapped) await launchctl(["bootout", files.job]).catch(() => undefined);
+    await Promise.all(
+      [...(wrotePlist ? [files.plist] : []), files.environment].map((file) =>
+        rm(file, { force: true }),
+      ),
+    );
+    throw error;
+  }
+}
+export async function disableSupervisor(target: LocalServiceTarget): Promise<void> {
+  await rm(supervisorPaths(target).enabled, { force: true });
+}
+export async function startSupervisor(target: LocalServiceTarget): Promise<boolean> {
+  const files = supervisorPaths(target);
+  if (!(await Bun.file(files.marker).exists())) return false;
+  if (process.platform !== "darwin")
+    throw new Error("This service is managed by macOS launchd.");
+  await writeFile(files.enabled, "enabled\n", { mode: 0o600 });
+  // A job may be registered after a login, or may need bootstrap after an explicit bootout.
+  try {
+    await launchctl(["print", files.job]);
+  } catch {
+    await launchctl(["bootstrap", `gui/${process.getuid?.()}`, files.plist]);
+  }
+  await launchctl(["kickstart", files.job]);
+  return true;
+}
+export async function uninstallSupervisor(target: LocalServiceTarget): Promise<void> {
+  const files = supervisorPaths(target);
+  if (!(await Bun.file(files.marker).exists())) return;
+  await disableSupervisor(target);
+  await launchctl(["bootout", files.job]);
+  await Promise.all(
+    [files.plist, files.marker, files.environment].map((file) =>
+      rm(file, { force: true }),
+    ),
+  );
+}
+export async function supervisedEnvironment(
+  env: NodeJS.ProcessEnv,
+): Promise<NodeJS.ProcessEnv> {
+  if (!env.TINKER_SERVICE_ENV_FILE) return env;
+  const values = JSON.parse(
+    await readFile(env.TINKER_SERVICE_ENV_FILE, "utf8"),
+  ) as Record<string, unknown>;
+  if (
+    !values ||
+    Array.isArray(values) ||
+    typeof values !== "object" ||
+    Object.values(values).some((value) => typeof value !== "string")
+  )
+    throw new Error("Invalid supervised service environment.");
+  await chmod(env.TINKER_SERVICE_ENV_FILE, 0o600);
+  return { ...env, ...values } as NodeJS.ProcessEnv;
+}

package/src/cli/service-upgrade.ts

@@ -0,0 +1,106 @@
+import { createConnection } from "node:net";
+import { randomUUID } from "node:crypto";
+import { lstat, readdir, realpath, readFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  localServicePaths,
+  type LocalServiceInstance,
+} from "../remote/local-service-discovery";
+
+/** Check every live service using this installation, including explicit non-default state directories. */
+export async function assertServiceUpgradeSafe(packageRoot: string): Promise<void> {
+  if (process.platform === "win32") return;
+  const root = path.dirname(localServicePaths("").socket);
+  let entries: string[];
+  try {
+    const info = await lstat(root);
+    if (
+      !info.isDirectory() ||
+      info.isSymbolicLink() ||
+      info.uid !== process.getuid?.() ||
+      info.mode & 0o077
+    )
+      throw new Error(
+        "Unsafe local service discovery directory; cannot verify upgrade safety.",
+      );
+    entries = await readdir(root);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  const canonical = await realpath(packageRoot);
+  for (const entry of entries.filter((name) =>
+    /^[a-f0-9]{32}\.sock\.json$/.test(name),
+  )) {
+    const instance = JSON.parse(
+      await readFile(path.join(root, entry), "utf8"),
+    ) as LocalServiceInstance;
+    if (
+      instance.packageRoot === canonical &&
+      (await Bun.file(
+        path.join(instance.stateDirectory, "supervisor.enabled"),
+      ).exists())
+    )
+      throw new Error(
+        `Disable the supervised service before upgrading: tinker serve --config ${instance.configPath} --stop.`,
+      );
+  }
+  for (const entry of entries.filter((name) => /^[a-f0-9]{32}\.sock$/.test(name))) {
+    const instance = await probe(path.join(root, entry));
+    if (instance && (!instance.packageRoot || instance.packageRoot === canonical))
+      throw new Error(
+        `Stop the running service before upgrading: tinker serve --config ${instance.configPath} --stop. Upgrade does not interrupt work or replace a live runtime.`,
+      );
+  }
+}
+function probe(socketPath: string): Promise<LocalServiceInstance | undefined> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(socketPath);
+    const nonce = randomUUID();
+    let content = "";
+    let finished = false;
+    const done = (instance?: LocalServiceInstance, error?: Error) => {
+      if (finished) return;
+      finished = true;
+      socket.destroy();
+      if (error) reject(error);
+      else resolve(instance);
+    };
+    socket.setEncoding("utf8");
+    socket.setTimeout(1000, () =>
+      done(
+        undefined,
+        new Error(
+          "A local service is unresponsive; stop it explicitly before upgrading.",
+        ),
+      ),
+    );
+    socket.once("connect", () => socket.write(`${nonce}\n`));
+    socket.once("error", (error: NodeJS.ErrnoException) =>
+      ["ENOENT", "ECONNREFUSED"].includes(error.code ?? "")
+        ? done()
+        : done(undefined, error),
+    );
+    socket.once("end", () => done());
+    socket.on("data", (chunk: string) => {
+      content += chunk;
+      if (content.length > 16384)
+        return done(undefined, new Error("Invalid service upgrade probe response."));
+      if (!content.includes("\n")) return;
+      try {
+        const response = JSON.parse(content.trim()) as {
+          nonce: string;
+          instance: LocalServiceInstance;
+        };
+        if (response.nonce !== nonce || response.instance?.version !== 1)
+          throw new Error("Invalid service upgrade probe response.");
+        done(response.instance);
+      } catch (error) {
+        done(
+          undefined,
+          error instanceof Error ? error : new Error("Invalid service response."),
+        );
+      }
+    });
+  });
+}