pi-soly 1.9.3 → 1.11.0

package/mcp/__tests__/sampling-handler.upstream-test.ts

@@ -0,0 +1,285 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { CreateMessageRequest, ModelPreferences } from "@modelcontextprotocol/sdk/types.js";
+import type { SamplingHandlerOptions } from "../sampling-handler.ts";
+
+const mocks = vi.hoisted(() => ({
+  complete: vi.fn(),
+}));
+
+vi.mock("@earendil-works/pi-ai", () => ({
+  complete: mocks.complete,
+}));
+
+const usage = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+
+const model = {
+  provider: "anthropic",
+  id: "claude-sonnet",
+  api: "anthropic-messages",
+  name: "Claude Sonnet",
+  baseUrl: "https://api.anthropic.com",
+  input: ["text"],
+  reasoning: false,
+  cost: usage.cost,
+  contextWindow: 200000,
+  maxTokens: 8192,
+} satisfies Model<"anthropic-messages">;
+
+const opus = {
+  ...model,
+  id: "claude-opus",
+  name: "Claude Opus",
+} satisfies Model<"anthropic-messages">;
+
+const haiku = {
+  ...model,
+  id: "claude-haiku",
+  name: "Claude Haiku",
+} satisfies Model<"anthropic-messages">;
+
+const geminiFlash = {
+  ...model,
+  provider: "google",
+  id: "gemini-2.5-flash",
+  api: "google-generative-ai",
+  name: "Gemini 2.5 Flash",
+  baseUrl: "https://generativelanguage.googleapis.com",
+} satisfies Model<"google-generative-ai">;
+
+type SamplingTestOptions = Omit<SamplingHandlerOptions, "modelRegistry"> & {
+  modelRegistry: Pick<SamplingHandlerOptions["modelRegistry"], "getAvailable" | "getApiKeyAndHeaders">;
+};
+
+function createOptions(overrides: Partial<SamplingTestOptions> = {}): SamplingHandlerOptions {
+  const options = {
+    serverName: "i18n",
+    autoApprove: true,
+    modelRegistry: {
+      getAvailable: vi.fn(() => [model]),
+      getApiKeyAndHeaders: vi.fn(async () => ({ ok: true, apiKey: "key", headers: { "x-test": "1" } })),
+    },
+    getCurrentModel: vi.fn(() => undefined),
+    getSignal: vi.fn(() => undefined),
+    ...overrides,
+  } satisfies SamplingTestOptions;
+  return options as SamplingHandlerOptions;
+}
+
+async function runBasicSampling(
+  overrides: Partial<SamplingTestOptions>,
+  modelPreferences?: ModelPreferences,
+): Promise<void> {
+  const { handleSamplingRequest } = await import("../sampling-handler.ts");
+  await handleSamplingRequest(createOptions(overrides), createSamplingRequest({
+    ...(modelPreferences ? { modelPreferences } : {}),
+    messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
+    maxTokens: 50,
+  }));
+}
+
+function createSamplingRequest(params: CreateMessageRequest["params"]): CreateMessageRequest {
+  return { method: "sampling/createMessage", params };
+}
+
+describe("sampling handler", () => {
+  beforeEach(() => {
+    mocks.complete.mockReset().mockResolvedValue({
+      role: "assistant",
+      content: [{ type: "text", text: "Bonjour" }],
+      api: "anthropic-messages",
+      provider: "anthropic",
+      model: "claude-sonnet",
+      usage,
+      stopReason: "stop",
+      timestamp: 1,
+    });
+  });
+
+  it("converts approved MCP sampling requests into pi-ai completions", async () => {
+    const { handleSamplingRequest } = await import("../sampling-handler.ts");
+    const result = await handleSamplingRequest(createOptions(), createSamplingRequest({
+      systemPrompt: "Translate tersely.",
+      messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
+      maxTokens: 50,
+      temperature: 0.2,
+      metadata: { locale: "fr" },
+    }));
+
+    expect(mocks.complete).toHaveBeenCalledWith(
+      model,
+      {
+        systemPrompt: "Translate tersely.",
+        messages: [
+          {
+            role: "user",
+            content: [{ type: "text", text: "Hello" }],
+            timestamp: expect.any(Number),
+          },
+        ],
+      },
+      {
+        apiKey: "key",
+        headers: { "x-test": "1" },
+        maxTokens: 50,
+        temperature: 0.2,
+        metadata: { locale: "fr" },
+        signal: undefined,
+      },
+    );
+    expect(result).toEqual({
+      role: "assistant",
+      content: { type: "text", text: "Bonjour" },
+      model: "anthropic/claude-sonnet",
+      stopReason: "endTurn",
+    });
+  });
+
+  it("requires UI approval unless auto-approve is enabled", async () => {
+    const { handleSamplingRequest } = await import("../sampling-handler.ts");
+
+    await expect(handleSamplingRequest(
+      createOptions({ autoApprove: false, ui: undefined }),
+      createSamplingRequest({ messages: [], maxTokens: 50 }),
+    )).rejects.toThrow("MCP sampling requires interactive approval");
+    expect(mocks.complete).not.toHaveBeenCalled();
+  });
+
+  it("asks for approval with inspectable request and response content", async () => {
+    const { handleSamplingRequest } = await import("../sampling-handler.ts");
+    const ui = { confirm: vi.fn(async () => true) };
+
+    await handleSamplingRequest(createOptions({ autoApprove: false, ui }), createSamplingRequest({
+      systemPrompt: "Translate tersely.",
+      messages: [{ role: "user", content: { type: "text", text: "Hello" } }],
+      maxTokens: 50,
+    }));
+
+    expect(ui.confirm).toHaveBeenCalledTimes(2);
+    expect(ui.confirm.mock.calls[0][0]).toBe("Approve MCP sampling request");
+    expect(ui.confirm.mock.calls[0][1]).toContain("System: Translate tersely.");
+    expect(ui.confirm.mock.calls[0][1]).toContain("1. user: Hello");
+    expect(ui.confirm.mock.calls[1][0]).toBe("Return MCP sampling response");
+    expect(ui.confirm.mock.calls[1][1]).toContain("Bonjour");
+  });
+
+  it("uses model preference hints before the current conversation model", async () => {
+    await runBasicSampling({
+      modelRegistry: {
+        getAvailable: vi.fn(() => [haiku, opus]),
+        getApiKeyAndHeaders: vi.fn(async () => ({ ok: true, apiKey: "key" })),
+      },
+      getCurrentModel: vi.fn(() => opus),
+    }, { hints: [{ name: "haiku" }] });
+
+    expect(mocks.complete.mock.calls[0][0]).toBe(haiku);
+  });
+
+  it("matches model preference hints case-insensitively after trimming", async () => {
+    await runBasicSampling({
+      modelRegistry: {
+        getAvailable: vi.fn(() => [haiku, opus]),
+        getApiKeyAndHeaders: vi.fn(async () => ({ ok: true, apiKey: "key" })),
+      },
+      getCurrentModel: vi.fn(() => opus),
+    }, { hints: [{ name: " HAIKU " }] });
+
+    expect(mocks.complete.mock.calls[0][0]).toBe(haiku);
+  });
+
+  it("matches model preference hints against display names", async () => {
+    await runBasicSampling({
+      modelRegistry: {
+        getAvailable: vi.fn(() => [geminiFlash, opus]),
+        getApiKeyAndHeaders: vi.fn(async () => ({ ok: true, apiKey: "key" })),
+      },
+      getCurrentModel: vi.fn(() => opus),
+    }, { hints: [{ name: "2.5 Flash" }] });
+
+    expect(mocks.complete.mock.calls[0][0]).toBe(geminiFlash);
+  });
+
+  it("matches model preference hints against provider/id", async () => {
+    await runBasicSampling({
+      modelRegistry: {
+        getAvailable: vi.fn(() => [geminiFlash, opus]),
+        getApiKeyAndHeaders: vi.fn(async () => ({ ok: true, apiKey: "key" })),
+      },
+      getCurrentModel: vi.fn(() => opus),
+    }, { hints: [{ name: "google/gemini" }] });
+
+    expect(mocks.complete.mock.calls[0][0]).toBe(geminiFlash);
+  });
+
+  it("preserves preference order across multiple model hints", async () => {
+    await runBasicSampling({
+      modelRegistry: {
+        getAvailable: vi.fn(() => [haiku, geminiFlash, opus]),
+        getApiKeyAndHeaders: vi.fn(async () => ({ ok: true, apiKey: "key" })),
+      },
+      getCurrentModel: vi.fn(() => opus),
+    }, { hints: [{ name: "gemini" }, { name: "haiku" }] });
+
+    expect(mocks.complete.mock.calls[0][0]).toBe(geminiFlash);
+  });
+
+  it("falls back when hinted models do not have configured auth", async () => {
+    const getApiKeyAndHeaders = vi.fn(async (candidate: Model<Api>) => {
+      if (candidate.id === "claude-haiku") return { ok: false, error: "missing key" };
+      return { ok: true, apiKey: "key" };
+    });
+
+    await runBasicSampling({
+      modelRegistry: {
+        getAvailable: vi.fn(() => [haiku, opus]),
+        getApiKeyAndHeaders,
+      },
+      getCurrentModel: vi.fn(() => opus),
+    }, { hints: [{ name: "haiku" }] });
+
+    expect(getApiKeyAndHeaders).toHaveBeenNthCalledWith(1, haiku);
+    expect(getApiKeyAndHeaders).toHaveBeenNthCalledWith(2, opus);
+    expect(mocks.complete.mock.calls[0][0]).toBe(opus);
+  });
+
+  it("preserves current-model-first selection when no hints are provided", async () => {
+    await runBasicSampling({
+      modelRegistry: {
+        getAvailable: vi.fn(() => [haiku]),
+        getApiKeyAndHeaders: vi.fn(async () => ({ ok: true, apiKey: "key" })),
+      },
+      getCurrentModel: vi.fn(() => opus),
+    });
+
+    expect(mocks.complete.mock.calls[0][0]).toBe(opus);
+  });
+
+  it("rejects unsupported sampling features loudly", async () => {
+    const { handleSamplingRequest } = await import("../sampling-handler.ts");
+
+    await expect(handleSamplingRequest(createOptions(), createSamplingRequest({
+      messages: [{ role: "user", content: { type: "image", data: "abc", mimeType: "image/png" } }],
+      maxTokens: 50,
+    }))).rejects.toThrow("MCP sampling image content is not supported");
+
+    await expect(handleSamplingRequest(createOptions(), createSamplingRequest({
+      messages: [{ role: "user", content: { type: "audio", data: "abc", mimeType: "audio/wav" } }],
+      maxTokens: 50,
+    }))).rejects.toThrow("MCP sampling audio content is not supported");
+
+    await expect(handleSamplingRequest(createOptions(), createSamplingRequest({
+      messages: [],
+      maxTokens: 50,
+      includeContext: "thisServer",
+    }))).rejects.toThrow("MCP sampling context inclusion is not supported");
+
+    expect(mocks.complete).not.toHaveBeenCalled();
+  });
+});

package/mcp/__tests__/server-manager-http-auth.upstream-test.ts

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+type OAuthProviderLike = {
+  redirectUrl?: string;
+  clientMetadata?: {
+    redirect_uris?: string[];
+    client_name?: string;
+    client_uri?: string;
+  };
+};
+
+type TransportOptions = {
+  requestInit?: {
+    headers?: Record<string, string>;
+  };
+  authProvider?: OAuthProviderLike;
+};
+
+type HttpTransportMock = {
+  url: URL;
+  options: TransportOptions;
+  close: () => Promise<void>;
+};
+
+const mocks = vi.hoisted(() => ({
+  httpTransports: [] as HttpTransportMock[],
+}));
+
+vi.mock("@modelcontextprotocol/sdk/client/index.js", () => ({
+  Client: vi.fn().mockImplementation((info: unknown, options: unknown) => ({
+    info,
+    options,
+    setRequestHandler: vi.fn(),
+    setNotificationHandler: vi.fn(),
+    connect: vi.fn(async () => undefined),
+    listTools: vi.fn(async () => ({ tools: [] })),
+    listResources: vi.fn(async () => ({ resources: [] })),
+    close: vi.fn(async () => undefined),
+  })),
+}));
+
+vi.mock("@modelcontextprotocol/sdk/client/stdio.js", () => ({
+  StdioClientTransport: vi.fn(),
+}));
+
+vi.mock("@modelcontextprotocol/sdk/client/streamableHttp.js", () => ({
+  StreamableHTTPClientTransport: vi.fn().mockImplementation((url: URL, options: TransportOptions) => {
+    const transport = { url, options, close: vi.fn(async () => undefined) };
+    mocks.httpTransports.push(transport);
+    return transport;
+  }),
+}));
+
+vi.mock("@modelcontextprotocol/sdk/client/sse.js", () => ({
+  SSEClientTransport: vi.fn(),
+}));
+
+vi.mock("../npx-resolver.ts", () => ({
+  resolveNpxBinary: vi.fn(async () => null),
+}));
+
+describe("McpServerManager HTTP bearer auth", () => {
+  const originalEnv = {
+    MCP_TEST_BEARER_TOKEN: process.env.MCP_TEST_BEARER_TOKEN,
+    MCP_TEST_BEARER_TOKEN_ENV: process.env.MCP_TEST_BEARER_TOKEN_ENV,
+  };
+
+  beforeEach(() => {
+    mocks.httpTransports.length = 0;
+  });
+
+  afterEach(() => {
+    for (const [key, value] of Object.entries(originalEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  it("interpolates ${VAR} bearerToken placeholders", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    process.env.MCP_TEST_BEARER_TOKEN = "placeholder-token";
+
+    const manager = new McpServerManager();
+    await manager.connect("remote", {
+      url: "https://example.test/mcp",
+      auth: "bearer",
+      bearerToken: "${MCP_TEST_BEARER_TOKEN}",
+    });
+
+    expect(mocks.httpTransports.at(-1)!.options.requestInit?.headers?.Authorization).toBe("Bearer placeholder-token");
+  });
+
+  it("interpolates $env:VAR bearerToken placeholders", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    process.env.MCP_TEST_BEARER_TOKEN = "env-prefix-token";
+
+    const manager = new McpServerManager();
+    await manager.connect("remote", {
+      url: "https://example.test/mcp",
+      auth: "bearer",
+      bearerToken: "$env:MCP_TEST_BEARER_TOKEN",
+    });
+
+    expect(mocks.httpTransports.at(-1)!.options.requestInit?.headers?.Authorization).toBe("Bearer env-prefix-token");
+  });
+
+  it("keeps bearerTokenEnv support", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    process.env.MCP_TEST_BEARER_TOKEN_ENV = "named-env-token";
+
+    const manager = new McpServerManager();
+    await manager.connect("remote", {
+      url: "https://example.test/mcp",
+      auth: "bearer",
+      bearerTokenEnv: "MCP_TEST_BEARER_TOKEN_ENV",
+    });
+
+    expect(mocks.httpTransports.at(-1)!.options.requestInit?.headers?.Authorization).toBe("Bearer named-env-token");
+  });
+
+  it("preserves OAuth redirect URI and client metadata for HTTP transports", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+
+    const manager = new McpServerManager();
+    await manager.connect("remote", {
+      url: "https://example.test/mcp",
+      auth: "oauth",
+      oauth: {
+        redirectUri: "http://127.0.0.1:3118/callback",
+        clientName: "Custom MCP",
+        clientUri: "https://example.com/custom-mcp",
+      },
+    });
+
+    const authProvider = mocks.httpTransports.at(-1)!.options.authProvider;
+    expect(authProvider?.redirectUrl).toBe("http://127.0.0.1:3118/callback");
+    expect(authProvider?.clientMetadata?.redirect_uris).toEqual(["http://127.0.0.1:3118/callback"]);
+    expect(authProvider?.clientMetadata?.client_name).toBe("Custom MCP");
+    expect(authProvider?.clientMetadata?.client_uri).toBe("https://example.com/custom-mcp");
+  });
+});

package/mcp/__tests__/server-manager-sampling.upstream-test.ts

@@ -0,0 +1,236 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const mocks = vi.hoisted(() => ({
+  clients: [] as any[],
+  transports: [] as any[],
+  open: vi.fn(async () => undefined),
+}));
+
+vi.mock("open", () => ({ default: mocks.open }));
+
+vi.mock("@modelcontextprotocol/sdk/client/index.js", () => ({
+  Client: vi.fn().mockImplementation(function (this: any, info: unknown, options: unknown) {
+    this.info = info;
+    this.options = options;
+    this.setRequestHandler = vi.fn();
+    this.setNotificationHandler = vi.fn();
+    this.connect = vi.fn(async () => undefined);
+    this.listTools = vi.fn(async () => ({ tools: [] }));
+    this.listResources = vi.fn(async () => ({ resources: [] }));
+    this.close = vi.fn(async () => undefined);
+    mocks.clients.push(this);
+  }),
+}));
+
+vi.mock("@modelcontextprotocol/sdk/client/stdio.js", () => ({
+  StdioClientTransport: vi.fn().mockImplementation(function (this: any, options: unknown) {
+    this.options = options;
+    this.close = vi.fn(async () => undefined);
+    mocks.transports.push(this);
+  }),
+}));
+
+vi.mock("@modelcontextprotocol/sdk/client/streamableHttp.js", () => ({
+  StreamableHTTPClientTransport: vi.fn(),
+}));
+
+vi.mock("@modelcontextprotocol/sdk/client/sse.js", () => ({
+  SSEClientTransport: vi.fn(),
+}));
+
+vi.mock("../npx-resolver.ts", () => ({
+  resolveNpxBinary: vi.fn(async () => null),
+}));
+
+describe("McpServerManager sampling", () => {
+  const originalMcpTestCwd = process.env.MCP_TEST_CWD;
+
+  beforeEach(() => {
+    mocks.clients.length = 0;
+    mocks.transports.length = 0;
+    mocks.open.mockClear();
+  });
+
+  afterEach(() => {
+    if (originalMcpTestCwd === undefined) {
+      delete process.env.MCP_TEST_CWD;
+    } else {
+      process.env.MCP_TEST_CWD = originalMcpTestCwd;
+    }
+  });
+
+  it("advertises sampling and registers the handler before connecting", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    const manager = new McpServerManager();
+    manager.setSamplingConfig({
+      autoApprove: true,
+      modelRegistry: {} as any,
+      getCurrentModel: () => undefined,
+      getSignal: () => undefined,
+    });
+
+    await manager.connect("demo", { command: "node", args: ["server.js"] });
+
+    const client = mocks.clients[0];
+    expect(client.options).toEqual({ capabilities: { sampling: {} } });
+    expect(client.setRequestHandler).toHaveBeenCalledTimes(1);
+    expect(client.setRequestHandler.mock.invocationCallOrder[0]).toBeLessThan(
+      client.connect.mock.invocationCallOrder[0],
+    );
+  });
+
+  it("advertises elicitation capabilities and registers the handler before connecting", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    const manager = new McpServerManager();
+    manager.setElicitationConfig({
+      allowUrl: true,
+      ui: {} as any,
+    });
+
+    await manager.connect("demo", { command: "node", args: ["server.js"] });
+
+    const client = mocks.clients[0];
+    expect(client.options).toEqual({
+      capabilities: {
+        elicitation: {
+          form: {},
+          url: {},
+        },
+      },
+    });
+    expect(client.setRequestHandler).toHaveBeenCalledTimes(1);
+    expect(client.setRequestHandler.mock.invocationCallOrder[0]).toBeLessThan(
+      client.connect.mock.invocationCallOrder[0],
+    );
+  });
+
+  it("advertises form-only elicitation when URL navigation is unavailable", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    const manager = new McpServerManager();
+    manager.setElicitationConfig({ allowUrl: false, ui: {} as any });
+
+    await manager.connect("demo", { command: "node", args: ["server.js"] });
+
+    expect(mocks.clients[0].options).toEqual({
+      capabilities: { elicitation: { form: {} } },
+    });
+  });
+
+  it("notifies only when a known URL elicitation completes", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    const ui = {
+      select: vi.fn().mockResolvedValue("Open"),
+      input: vi.fn(),
+      notify: vi.fn(),
+    };
+    const manager = new McpServerManager();
+    manager.setElicitationConfig({ allowUrl: true, ui: ui as any });
+    await manager.connect("demo", { command: "node", args: ["server.js"] });
+
+    const client = mocks.clients[0];
+    const requestHandler = client.setRequestHandler.mock.calls[0][1];
+    await requestHandler({
+      method: "elicitation/create",
+      params: {
+        mode: "url",
+        message: "Connect",
+        elicitationId: "known-id",
+        url: "https://example.com/connect",
+      },
+    });
+    const completionHandler = client.setNotificationHandler.mock.calls[0][1];
+    completionHandler({ params: { elicitationId: "unknown-id" } });
+    completionHandler({ params: { elicitationId: "known-id" } });
+    completionHandler({ params: { elicitationId: "known-id" } });
+
+    expect(ui.notify).toHaveBeenCalledWith("Opened browser for MCP elicitation.", "info");
+    expect(ui.notify).toHaveBeenCalledWith(
+      "MCP browser interaction for demo completed. You can retry the tool now.",
+      "info",
+    );
+    expect(ui.notify).toHaveBeenCalledTimes(2);
+  });
+
+  it("handles every URL in a URL-required error", async () => {
+    const { UrlElicitationRequiredError } = await import("@modelcontextprotocol/sdk/types.js");
+    const { McpServerManager } = await import("../server-manager.ts");
+    const ui = {
+      select: vi.fn().mockResolvedValue("Open"),
+      input: vi.fn(),
+      notify: vi.fn(),
+    };
+    const manager = new McpServerManager();
+    manager.setElicitationConfig({ allowUrl: true, ui: ui as any });
+    const result = await manager.handleUrlElicitationRequired("demo", new UrlElicitationRequiredError([
+      { mode: "url", message: "First", elicitationId: "one", url: "https://example.com/one" },
+      { mode: "url", message: "Second", elicitationId: "two", url: "https://example.com/two" },
+    ]));
+
+    expect(result).toBe("accept");
+    expect(mocks.open).toHaveBeenNthCalledWith(1, "https://example.com/one");
+    expect(mocks.open).toHaveBeenNthCalledWith(2, "https://example.com/two");
+  });
+
+  it("advertises sampling and elicitation together", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    const manager = new McpServerManager();
+    manager.setSamplingConfig({
+      autoApprove: true,
+      modelRegistry: {} as any,
+      getCurrentModel: () => undefined,
+      getSignal: () => undefined,
+    });
+    manager.setElicitationConfig({
+      allowUrl: true,
+      ui: {} as any,
+    });
+
+    await manager.connect("demo", { command: "node", args: ["server.js"] });
+
+    expect(mocks.clients[0].options).toEqual({
+      capabilities: {
+        sampling: {},
+        elicitation: {
+          form: {},
+          url: {},
+        },
+      },
+    });
+    expect(mocks.clients[0].setRequestHandler).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not advertise sampling when no sampling config is set", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    const manager = new McpServerManager();
+
+    await manager.connect("demo", { command: "node", args: ["server.js"] });
+
+    const client = mocks.clients[0];
+    expect(client.options).toBeUndefined();
+    expect(client.setRequestHandler).not.toHaveBeenCalled();
+  });
+
+  it("expands environment variables and tilde in stdio cwd", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    process.env.MCP_TEST_CWD = "/tmp/pi-mcp-cwd";
+
+    const envManager = new McpServerManager();
+    await envManager.connect("env-cwd", {
+      command: "node",
+      args: ["server.js"],
+      cwd: "${MCP_TEST_CWD}/nested",
+    });
+
+    const homeManager = new McpServerManager();
+    await homeManager.connect("home-cwd", {
+      command: "node",
+      args: ["server.js"],
+      cwd: "~/nested",
+    });
+
+    expect(mocks.transports[0].options).toMatchObject({ cwd: "/tmp/pi-mcp-cwd/nested" });
+    expect(mocks.transports[1].options).toMatchObject({ cwd: join(homedir(), "nested") });
+  });
+});