@kata-sh/pi-symphony-extension 0.1.0

package/src/index.test.ts

@@ -0,0 +1,80 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => {
+  type Handler = (...args: unknown[]) => unknown;
+  const instances: Array<{
+    state: {
+      stopOwnedOnShutdown: boolean;
+      ownedProcess?: { baseUrl?: string };
+    };
+    processManager: { shutdown: ReturnType<typeof vi.fn> };
+    restore: ReturnType<typeof vi.fn>;
+    clearAttachmentIfBaseUrl: ReturnType<typeof vi.fn>;
+    persist: ReturnType<typeof vi.fn>;
+  }> = [];
+
+  const SymphonyRuntime = vi.fn(function SymphonyRuntimeMock() {
+    const runtime = {
+      state: { stopOwnedOnShutdown: true },
+      processManager: { shutdown: vi.fn(async () => undefined) },
+      restore: vi.fn(),
+      clearAttachmentIfBaseUrl: vi.fn(),
+      persist: vi.fn(),
+    };
+    instances.push(runtime);
+    return runtime;
+  });
+
+  return {
+    instances,
+    SymphonyRuntime,
+    registerSymphonyCommands: vi.fn(),
+    registerSymphonyTools: vi.fn(),
+    setSymphonyStatus: vi.fn(),
+    handlers: new Map<string, Handler>(),
+  };
+});
+
+vi.mock("./runtime.ts", () => ({ SymphonyRuntime: mocks.SymphonyRuntime }));
+vi.mock("./commands.ts", () => ({
+  registerSymphonyCommands: mocks.registerSymphonyCommands,
+  setSymphonyStatus: mocks.setSymphonyStatus,
+}));
+vi.mock("./tools.ts", () => ({ registerSymphonyTools: mocks.registerSymphonyTools }));
+
+import symphonyExtension from "./index.ts";
+
+function extensionApi(): ExtensionAPI {
+  return {
+    on: vi.fn((event: string, handler: (...args: unknown[]) => unknown) => {
+      mocks.handlers.set(event, handler);
+    }),
+    appendEntry: vi.fn(),
+  } as unknown as ExtensionAPI;
+}
+
+beforeEach(() => {
+  mocks.instances.length = 0;
+  mocks.handlers.clear();
+  mocks.SymphonyRuntime.mockClear();
+  mocks.registerSymphonyCommands.mockClear();
+  mocks.registerSymphonyTools.mockClear();
+  mocks.setSymphonyStatus.mockClear();
+});
+
+describe("symphony extension lifecycle", () => {
+  it("cleans and persists owned attachment state when shutdown fails", async () => {
+    const pi = extensionApi();
+    symphonyExtension(pi);
+    const runtime = mocks.instances[0];
+    const shutdownError = new Error("shutdown failed");
+    runtime.state.ownedProcess = { baseUrl: "http://127.0.0.1:8080" };
+    runtime.processManager.shutdown.mockRejectedValueOnce(shutdownError);
+
+    await expect(mocks.handlers.get("session_shutdown")!()).rejects.toThrow(shutdownError);
+
+    expect(runtime.clearAttachmentIfBaseUrl).toHaveBeenCalledWith("http://127.0.0.1:8080");
+    expect(runtime.persist).toHaveBeenCalledWith(pi);
+  });
+});

package/src/index.ts

@@ -0,0 +1,27 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerSymphonyCommands, setSymphonyStatus } from "./commands.ts";
+import { SymphonyRuntime } from "./runtime.ts";
+import { registerSymphonyTools } from "./tools.ts";
+
+export default function symphonyExtension(pi: ExtensionAPI): void {
+  const runtime = new SymphonyRuntime();
+
+  pi.on("session_start", async (_event, ctx) => {
+    runtime.restore(ctx);
+    setSymphonyStatus(ctx, runtime);
+  });
+
+  pi.on("session_shutdown", async () => {
+    const hadOwnedProcess = runtime.state.stopOwnedOnShutdown && Boolean(runtime.state.ownedProcess);
+    const ownedBaseUrl = runtime.state.stopOwnedOnShutdown ? runtime.state.ownedProcess?.baseUrl : undefined;
+    try {
+      await runtime.processManager.shutdown();
+    } finally {
+      runtime.clearAttachmentIfBaseUrl(ownedBaseUrl);
+      if (hadOwnedProcess) runtime.persist(pi);
+    }
+  });
+
+  registerSymphonyCommands(pi, runtime);
+  registerSymphonyTools(pi, runtime);
+}

package/src/package-smoke.test.ts

@@ -0,0 +1,24 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packagePath = resolve(here, "../package.json");
+
+describe("pi package manifest", () => {
+  it("declares the Pi extension entrypoint and package identity", async () => {
+    const manifest = JSON.parse(await readFile(packagePath, "utf8")) as {
+      name?: string;
+      keywords?: string[];
+      pi?: { extensions?: string[] };
+      peerDependencies?: Record<string, string>;
+    };
+
+    expect(manifest.name).toBe("@kata-sh/pi-symphony-extension");
+    expect(manifest.keywords).toContain("pi-package");
+    expect(manifest.pi?.extensions).toEqual(["./src/index.ts"]);
+    expect(manifest.peerDependencies?.["@earendil-works/pi-coding-agent"]).toBe("*");
+    expect(manifest.peerDependencies?.["@earendil-works/pi-tui"]).toBe("*");
+  });
+});

package/src/process-manager.test.ts

@@ -0,0 +1,232 @@
+import { chmod, mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createServer, type Server } from "node:http";
+import { afterEach, describe, expect, it } from "vitest";
+import { SymphonyProcessManager } from "./process-manager.ts";
+import { createDefaultState } from "./state.ts";
+
+let server: Server | undefined;
+
+async function stateServer(): Promise<string> {
+  server = createServer((_req, res) => {
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({
+      running: {},
+      retry_queue: [],
+      blocked: [],
+      completed: [],
+      polling: { checking: false, next_poll_in_ms: 0, poll_interval_ms: 30000 },
+      shared_context: { total_entries: 0, entries_by_scope: {}, oldest_entry_at: null, newest_entry_at: null },
+      supervisor: { active: true, steers_issued: 0, conflicts_detected: 0, patterns_detected: 0, escalations_created: 0 },
+      codex_totals: { input_tokens: 0, output_tokens: 0, total_tokens: 0, event_count: 0, seconds_running: 0 },
+      codex_rate_limits: null,
+    }));
+  });
+  await new Promise<void>((resolve) => server!.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("expected TCP address");
+  return `http://127.0.0.1:${address.port}`;
+}
+
+async function writeNodeScript(dir: string, name: string, source: string): Promise<string> {
+  const script = join(dir, name);
+  await writeFile(script, source, "utf8");
+  return script;
+}
+
+function isPidRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ESRCH") return false;
+    if (code === "EPERM") return true;
+    throw error;
+  }
+}
+
+async function waitForProcessExit(pid: number): Promise<void> {
+  await expect.poll(() => isPidRunning(pid), { interval: 50, timeout: 3000 }).toBe(false);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+afterEach(async () => {
+  if (!server) return;
+  await new Promise<void>((resolve, reject) => server!.close((error) => (error ? reject(error) : resolve())));
+  server = undefined;
+});
+
+describe("SymphonyProcessManager", () => {
+  it("starts Symphony with --no-tui and records owned process metadata", async () => {
+    const baseUrl = await stateServer();
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-process-"));
+    const script = join(dir, "fake-symphony.sh");
+    await writeFile(script, `#!/bin/sh\necho "dashboard listening at ${baseUrl}"\nsleep 30\n`, "utf8");
+    await chmod(script, 0o755);
+
+    const state = createDefaultState();
+    const manager = new SymphonyProcessManager(state);
+    const started = await manager.start({ binary: script, cwd: dir, workflow: ".symphony/WORKFLOW.md", timeoutMs: 2000 });
+
+    expect(started.baseUrl).toBe(baseUrl);
+    expect(started.owned).toBe(true);
+    expect(state.ownedProcess?.command).toContain("--no-tui");
+    expect(state.ownedProcess?.command).toContain(".symphony/WORKFLOW.md");
+
+    await manager.stopOwned();
+  });
+
+  it("does not mark the runtime attached before the caller attaches", async () => {
+    const baseUrl = await stateServer();
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-process-"));
+    const script = join(dir, "fake-symphony.sh");
+    await writeFile(script, `#!/bin/sh\necho "dashboard listening at ${baseUrl}"\nsleep 30\n`, "utf8");
+    await chmod(script, 0o755);
+
+    const state = createDefaultState();
+    const manager = new SymphonyProcessManager(state);
+    const started = await manager.start({ binary: script, cwd: dir, timeoutMs: 2000 });
+
+    expect(started.baseUrl).toBe(baseUrl);
+    expect(state.attachedBaseUrl).toBeUndefined();
+
+    await manager.stopOwned();
+  });
+
+  it("reads the workflow server port before probing health", async () => {
+    const baseUrl = await stateServer();
+    const port = new URL(baseUrl).port;
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-process-"));
+    const workflowDir = join(dir, ".symphony");
+    await mkdir(workflowDir);
+    await writeFile(join(workflowDir, "WORKFLOW.md"), `---\nserver:\n  port: ${port}\n---\nRun Symphony\n`, "utf8");
+    const script = join(dir, "fake-symphony.sh");
+    await writeFile(script, "#!/bin/sh\nsleep 30\n", "utf8");
+    await chmod(script, 0o755);
+
+    const state = createDefaultState();
+    const manager = new SymphonyProcessManager(state);
+    const started = await manager.start({ binary: script, cwd: dir, workflow: ".symphony/WORKFLOW.md", timeoutMs: 2000 });
+
+    expect(started.baseUrl).toBe(baseUrl);
+
+    await manager.stopOwned();
+  });
+
+  it("hard-kills a SIGTERM-ignoring owned child and clears state", async () => {
+    const baseUrl = await stateServer();
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-process-"));
+    const script = await writeNodeScript(
+      dir,
+      "ignore-term.js",
+      `process.on("SIGTERM", () => {});\nconsole.log("dashboard listening at ${baseUrl}");\nsetInterval(() => {}, 1000);\n`,
+    );
+
+    const state = createDefaultState();
+    const manager = new SymphonyProcessManager(state);
+    const started = await manager.start({ binary: process.execPath, cwd: dir, workflow: script, timeoutMs: 2000 });
+
+    await manager.stopOwned();
+
+    expect(state.ownedProcess).toBeUndefined();
+    await waitForProcessExit(started.pid);
+  }, 10_000);
+
+  it("cleans up a spawned child when startup is aborted", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-process-"));
+    const pidFile = join(dir, "child.pid");
+    const script = await writeNodeScript(
+      dir,
+      "hang.js",
+      `const { writeFileSync } = require("node:fs");\nwriteFileSync(${JSON.stringify(pidFile)}, String(process.pid));\nsetInterval(() => {}, 1000);\n`,
+    );
+
+    const state = createDefaultState();
+    const manager = new SymphonyProcessManager(state);
+    const controller = new AbortController();
+    const start = manager.start({ binary: process.execPath, cwd: dir, workflow: script, timeoutMs: 5000, signal: controller.signal });
+
+    await expect.poll(async () => readFile(pidFile, "utf8").catch(() => ""), { interval: 50, timeout: 1000 }).not.toBe("");
+    const pid = Number(await readFile(pidFile, "utf8"));
+    controller.abort(new Error("startup cancelled"));
+
+    await expect(start).rejects.toThrow("startup cancelled");
+    expect(state.ownedProcess).toBeUndefined();
+    await waitForProcessExit(pid);
+  }, 10_000);
+
+  it("cleans up a spawned child when startup times out", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-process-"));
+    const pidFile = join(dir, "child.pid");
+    const script = await writeNodeScript(
+      dir,
+      "hang-no-api.js",
+      `const { writeFileSync } = require("node:fs");\nwriteFileSync(${JSON.stringify(pidFile)}, String(process.pid));\nsetInterval(() => {}, 1000);\n`,
+    );
+
+    const state = createDefaultState();
+    const manager = new SymphonyProcessManager(state);
+    const start = manager.start({ binary: process.execPath, cwd: dir, workflow: script, timeoutMs: 250 });
+
+    await expect.poll(async () => readFile(pidFile, "utf8").catch(() => ""), { interval: 50, timeout: 1000 }).not.toBe("");
+    const pid = Number(await readFile(pidFile, "utf8"));
+
+    await expect(start).rejects.toMatchObject({ kind: "start_timeout" });
+    expect(state.ownedProcess).toBeUndefined();
+    await waitForProcessExit(pid);
+  }, 10_000);
+
+  it("allows start after a previous owned child exits", async () => {
+    const baseUrl = await stateServer();
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-process-"));
+    const quickExit = await writeNodeScript(dir, "quick-exit.js", `console.log("dashboard listening at ${baseUrl}");\nsetTimeout(() => process.exit(0), 100);\n`);
+    const longRunning = await writeNodeScript(dir, "long-running.js", `console.log("dashboard listening at ${baseUrl}");\nsetInterval(() => {}, 1000);\n`);
+
+    const state = createDefaultState();
+    const manager = new SymphonyProcessManager(state);
+    const first = await manager.start({ binary: process.execPath, cwd: dir, workflow: quickExit, timeoutMs: 2000 });
+    await waitForProcessExit(first.pid);
+
+    const second = await manager.start({ binary: process.execPath, cwd: dir, workflow: longRunning, timeoutMs: 2000 });
+
+    expect(second.baseUrl).toBe(baseUrl);
+    expect(state.ownedProcess?.pid).toBe(second.pid);
+
+    await manager.stopOwned();
+  });
+
+  it("clears stale owned state when the owned child exits unexpectedly", async () => {
+    const baseUrl = await stateServer();
+    const dir = await mkdtemp(join(tmpdir(), "pi-symphony-process-"));
+    const script = await writeNodeScript(dir, "quick-exit.js", `console.log("dashboard listening at ${baseUrl}");\nsetTimeout(() => process.exit(0), 300);\n`);
+
+    const state = createDefaultState();
+    const manager = new SymphonyProcessManager(state);
+    const started = await manager.start({ binary: process.execPath, cwd: dir, workflow: script, timeoutMs: 2000 });
+    state.attachedBaseUrl = baseUrl;
+    state.lastKnownState = {
+      baseUrl,
+      runningCount: 0,
+      retryCount: 0,
+      blockedCount: 0,
+      completedCount: 0,
+      pollingChecking: false,
+      nextPollInMs: 0,
+      updatedAt: "2026-05-14T00:00:00.000Z",
+    };
+    await waitForProcessExit(started.pid);
+
+    await expect.poll(() => state.ownedProcess, { interval: 50, timeout: 1000 }).toBeUndefined();
+    expect(state.attachedBaseUrl).toBeUndefined();
+    expect(state.lastKnownState).toBeUndefined();
+    await expect(manager.stopOwned()).rejects.toMatchObject({ kind: "not_owned" });
+  });
+
+  it("does not stop when no owned child exists", async () => {
+    const state = createDefaultState();
+    const manager = new SymphonyProcessManager(state);
+    await expect(manager.stopOwned()).rejects.toThrow("No Symphony process owned by this extension");
+  });
+});

package/src/process-manager.ts

@@ -0,0 +1,290 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { SymphonyExtensionError } from "./errors.ts";
+import { SymphonyHttpClient } from "./http-client.ts";
+import type { ExtensionState } from "./state.ts";
+
+const TERMINATE_GRACE_MS = 2000;
+const KILL_GRACE_MS = 2000;
+const MAX_OUTPUT_CHARS = 64_000;
+
+export interface StartOptions {
+  binary: string;
+  cwd: string;
+  workflow?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface StartResult {
+  baseUrl: string;
+  owned: true;
+  pid: number;
+}
+
+export class SymphonyProcessManager {
+  private child?: ChildProcessWithoutNullStreams;
+  private output = "";
+
+  constructor(private readonly state: ExtensionState) {}
+
+  async start(options: StartOptions): Promise<StartResult> {
+    throwIfAborted(options.signal);
+
+    if (this.child) {
+      if (isChildRunning(this.child)) {
+        throw new SymphonyExtensionError("command_failed", "Symphony is already running as an owned child process", {
+          pid: this.child.pid,
+        });
+      }
+      this.clearOwnedState();
+    }
+
+    const args = options.workflow ? [options.workflow, "--no-tui"] : ["--no-tui"];
+    this.output = "";
+    const child = spawn(options.binary, args, { cwd: options.cwd, stdio: "pipe" });
+    this.child = child;
+    child.once("exit", () => {
+      if (this.child === child) this.clearOwnedState();
+    });
+
+    const pid = child.pid;
+    if (!pid) {
+      this.clearOwnedState();
+      throw new SymphonyExtensionError("command_failed", "Failed to spawn Symphony process");
+    }
+
+    child.stdout.on("data", (chunk) => this.appendOutput(chunk));
+    child.stderr.on("data", (chunk) => this.appendOutput(chunk));
+
+    try {
+      const baseUrl = await this.waitForReady(options.cwd, options.workflow, options.timeoutMs ?? 10_000, options.signal);
+      throwIfAborted(options.signal);
+      this.state.ownedProcess = {
+        pid,
+        command: [options.binary, ...args].join(" "),
+        cwd: options.cwd,
+        baseUrl,
+        startedAt: new Date().toISOString(),
+      };
+      if (!isChildRunning(child)) this.clearOwnedState();
+
+      return { baseUrl, owned: true, pid };
+    } catch (error) {
+      try {
+        await this.stopOwnedInternal(false);
+      } catch {
+        this.clearOwnedState();
+      }
+      throw error;
+    }
+  }
+
+  async stopOwned(): Promise<void> {
+    await this.stopOwnedInternal(true);
+  }
+
+  async shutdown(): Promise<void> {
+    if (!this.state.stopOwnedOnShutdown) return;
+    await this.stopOwnedInternal(false);
+  }
+
+  private async stopOwnedInternal(throwIfNotOwned: boolean): Promise<void> {
+    if (!this.child || !isChildRunning(this.child)) {
+      this.clearOwnedState();
+      if (throwIfNotOwned) {
+        throw new SymphonyExtensionError("not_owned", "No Symphony process owned by this extension is running");
+      }
+      return;
+    }
+
+    const child = this.child;
+    child.kill("SIGTERM");
+    await waitForExitOrTimeout(child, TERMINATE_GRACE_MS);
+
+    if (isChildRunning(child)) {
+      child.kill("SIGKILL");
+      await waitForExitOrTimeout(child, KILL_GRACE_MS);
+    }
+
+    this.clearOwnedState();
+  }
+
+  private clearOwnedState(): void {
+    const ownedBaseUrl = this.state.ownedProcess?.baseUrl;
+    this.child = undefined;
+    this.state.ownedProcess = undefined;
+    if (ownedBaseUrl && this.state.attachedBaseUrl === ownedBaseUrl) {
+      this.state.attachedBaseUrl = undefined;
+      this.state.lastKnownState = undefined;
+    }
+  }
+
+  private appendOutput(chunk: unknown): void {
+    this.output = (this.output + String(chunk)).slice(-MAX_OUTPUT_CHARS);
+  }
+
+  private async waitForReady(cwd: string, workflow: string | undefined, timeoutMs: number, signal?: AbortSignal): Promise<string> {
+    const started = Date.now();
+    let lastError: unknown;
+
+    while (Date.now() - started < timeoutMs) {
+      throwIfAborted(signal);
+      const baseUrl = this.detectOutputBaseUrl() ?? (Date.now() - started >= Math.min(500, timeoutMs) ? this.detectBaseUrl(cwd, workflow) : undefined);
+      if (baseUrl) {
+        try {
+          const client = new SymphonyHttpClient(baseUrl);
+          await client.verify(signal);
+          return baseUrl;
+        } catch (error) {
+          if (signal?.aborted) throw error;
+          lastError = error;
+        }
+      }
+
+      if (this.child && !isChildRunning(this.child)) break;
+      await delay(150, signal);
+    }
+
+    throw new SymphonyExtensionError("start_timeout", "Timed out waiting for Symphony HTTP API", {
+      expectedBaseUrl: this.detectBaseUrl(cwd, workflow),
+      output: this.output.slice(-4000),
+      childExitCode: this.child?.exitCode,
+      cause: lastError instanceof Error ? lastError.message : String(lastError),
+    });
+  }
+
+  private detectBaseUrl(cwd: string, workflow: string | undefined): string {
+    const outputBaseUrl = this.detectOutputBaseUrl();
+    if (outputBaseUrl) return outputBaseUrl;
+
+    const workflowPath = workflow ? resolve(cwd, workflow) : join(cwd, ".symphony", "WORKFLOW.md");
+    const configured = readWorkflowServerConfigSyncBestEffort(workflowPath);
+    return `http://${configured.host}:${configured.port}`;
+  }
+
+  private detectOutputBaseUrl(): string | undefined {
+    return this.output.match(/https?:\/\/(?:127\.0\.0\.1|localhost|\[::1\]):\d+/)?.[0];
+  }
+}
+
+function isChildRunning(child: ChildProcessWithoutNullStreams): boolean {
+  return child.exitCode === null && child.signalCode === null;
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (!signal?.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new DOMException("This operation was aborted", "AbortError");
+}
+
+async function delay(timeoutMs: number, signal?: AbortSignal): Promise<void> {
+  throwIfAborted(signal);
+  await new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    };
+    const abort = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", abort);
+      reject(signal?.reason instanceof Error ? signal.reason : new DOMException("This operation was aborted", "AbortError"));
+    };
+    const timeout = setTimeout(done, timeoutMs);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+  });
+}
+
+async function waitForExitOrTimeout(child: ChildProcessWithoutNullStreams, timeoutMs: number): Promise<void> {
+  if (!isChildRunning(child)) return;
+
+  await new Promise<void>((resolve) => {
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      child.off("exit", done);
+      resolve();
+    };
+    const timeout = setTimeout(done, timeoutMs);
+    child.once("exit", done);
+    if (!isChildRunning(child)) done();
+  });
+}
+
+function readWorkflowServerConfigSyncBestEffort(workflowPath: string): { host: string; port: number } {
+  try {
+    return parseWorkflowServerConfig(readFileSync(workflowPath, "utf8"));
+  } catch {
+    return { host: "127.0.0.1", port: 8080 };
+  }
+}
+
+function parseWorkflowServerConfig(content: string): { host: string; port: number } {
+  const yaml = extractYamlFrontmatter(content) ?? content;
+  let inServerSection = false;
+  let serverIndent = -1;
+  let host = "127.0.0.1";
+  let port = 8080;
+
+  for (const rawLine of yaml.split(/\r?\n/)) {
+    const line = stripYamlComment(rawLine).trimEnd();
+    if (!line.trim()) continue;
+    const indent = leadingWhitespaceLength(line);
+    const trimmed = line.trim();
+
+    if (trimmed === "server:") {
+      inServerSection = true;
+      serverIndent = indent;
+      continue;
+    }
+
+    if (inServerSection && indent <= serverIndent) {
+      inServerSection = false;
+    }
+
+    if (!inServerSection) continue;
+
+    const match = trimmed.match(/^(host|port):\s*(.+)$/);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    const value = parseYamlScalar(rawValue);
+    if (key === "host" && value) host = value;
+    if (key === "port") {
+      const parsedPort = Number(value);
+      if (Number.isInteger(parsedPort) && parsedPort >= 0 && parsedPort <= 65535) port = parsedPort;
+    }
+  }
+
+  return { host, port };
+}
+
+function extractYamlFrontmatter(content: string): string | undefined {
+  const lines = content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return undefined;
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (end === -1) return undefined;
+  return lines.slice(1, end).join("\n");
+}
+
+function stripYamlComment(line: string): string {
+  return line.replace(/\s+#.*$/, "");
+}
+
+function leadingWhitespaceLength(value: string): number {
+  return value.length - value.trimStart().length;
+}
+
+function parseYamlScalar(value: string): string {
+  const trimmed = value.trim();
+  const quoted = trimmed.match(/^(["'])(.*)\1$/);
+  return quoted ? quoted[2] : trimmed;
+}