From 0495fad19aa826d86f25f24415eb5a3a24095bc7 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Fri, 13 Nov 2026 04:00:21 -0800 Subject: [PATCH] Keep PATH when checking managed SSH ACP prerequisites Managed SSH ACP checked its command with an empty environment. The shared resolver needs the controller PATH to locate the local SSH client, so the default Claude and Codex ACP commands were rejected before startup. Retain only PATH for the SSH prerequisite check. Keep sandbox behavior and controller credential exclusion intact. Exercise the real resolver from both public execution entries with a fixture SSH executable and an empty PATH. Clarify the local prerequisite and remote installation requirements in docs. Validation: reproduced four default/explicit ACP failures before the fix; 140 provider tests and both provider typechecks pass after the fix. Co-Authored-By: Paperclip --- doc/connections/AI-CONNECTIONS.md | 6 ++-- .../adapters/claude-local/src/server/acp.ts | 2 +- .../src/server/execute.remote.test.ts | 33 ++++++++++++++++--- .../adapters/codex-local/src/server/acp.ts | 2 +- .../src/server/execute.remote.test.ts | 33 ++++++++++++++++--- 5 files changed, 62 insertions(+), 14 deletions(-) diff --git a/doc/connections/AI-CONNECTIONS.md b/doc/connections/AI-CONNECTIONS.md index 79a10419b0b..913d09c2a24 100644 --- a/doc/connections/AI-CONNECTIONS.md +++ b/doc/connections/AI-CONNECTIONS.md @@ -483,10 +483,12 @@ account-scoped conversation references across server persistence. ACP SSH sessions use the existing remote process bridge and session reuse lifecycle. Both provider adapters admit managed SSH through their public -execution entry points when the remote ACP command is available. SSH ACP needs +execution entry points. SSH ACP needs an agent-managed account and a copied workspace. Host authentication, in-place SSH workspaces, and local filesystem/network confinement require the CLI engine. -Command availability checks do not send controller credentials to the SSH host. +The SSH prerequisite check retains only the controller's `PATH` to resolve the +local SSH client; it excludes controller credentials. The ACP server command +must be installed on the remote machine and is started there by the process bridge. A compatible session can retain its private remote home; workspace sync and credential refresh run at turn teardown, and the session disposal hook removes the home on retirement. Workspace identity includes the company, agent, diff --git a/packages/adapters/claude-local/src/server/acp.ts b/packages/adapters/claude-local/src/server/acp.ts index f49b8536e52..cda1d2beec5 100644 --- a/packages/adapters/claude-local/src/server/acp.ts +++ b/packages/adapters/claude-local/src/server/acp.ts @@ -565,7 +565,7 @@ async function commandIsResolvable( trimmed, target, resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()), - {}, + target.transport === "ssh" ? { PATH: process.env.PATH } : {}, { // Fresh sandboxes need the same ACP server that ships with this // adapter. Only bootstrap our default command; an operator's custom diff --git a/packages/adapters/claude-local/src/server/execute.remote.test.ts b/packages/adapters/claude-local/src/server/execute.remote.test.ts index 01290a97ad2..c97cd2ee831 100644 --- a/packages/adapters/claude-local/src/server/execute.remote.test.ts +++ b/packages/adapters/claude-local/src/server/execute.remote.test.ts @@ -33,7 +33,7 @@ const { pid: 123, startedAt: new Date().toISOString(), })), - ensureCommandResolvable: vi.fn(async () => undefined), + ensureCommandResolvable: vi.fn(async () => undefined), resolveCommandForLogs: vi.fn(async () => "ssh://fixture@127.0.0.1:2222/remote/workspace :: claude"), prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })), restoreWorkspaceFromSshExecution: vi.fn(async () => undefined), @@ -123,6 +123,14 @@ describe("claude remote execution", () => { it.each([undefined, "acp"])("admits managed SSH ACP through the public execution entry (engine=%s)", async engine => { const ctx = managedSshAcpContext(engine); + const actual = await vi.importActual("@paperclipai/adapter-utils/server-utils"); + const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-client-probe-")); + cleanupDirs.push(bin); + await writeFile(path.join(bin, "ssh"), "#!/bin/sh\nexit 0\n", { mode: 0o700 }); + const originalResolve = ensureCommandResolvable.getMockImplementation()!; + ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable); + const previousPath = process.env.PATH; + process.env.PATH = bin; const previous = process.env.CLAUDE_CODE_OAUTH_TOKEN; process.env.CLAUDE_CODE_OAUTH_TOKEN = "fixture-server-secret"; try { @@ -130,15 +138,19 @@ describe("claude remote execution", () => { expect(executeAcp).toHaveBeenCalledWith(ctx); const probe = ensureCommandResolvable.mock.calls[0] as unknown as unknown[]; expect(probe[0]).toBe("claude-agent-acp"); - expect(Object.keys(probe[2] as Record)).toEqual([]); + expect(Object.keys(probe[2] as Record)).toEqual(["PATH"]); + expect((probe[2] as Record).PATH === bin).toBe(true); expect(probe[3]).toMatchObject({ remoteExecution: { host: "ssh.example.test", useHostAuth: false } }); } finally { + ensureCommandResolvable.mockReset().mockImplementation(originalResolve); + if (previousPath === undefined) delete process.env.PATH; + else process.env.PATH = previousPath; if (previous === undefined) delete process.env.CLAUDE_CODE_OAUTH_TOKEN; else process.env.CLAUDE_CODE_OAUTH_TOKEN = previous; } }); - it.each(["host auth", "legacy auth", "missing account", "in-place", "confinement", "missing command"])("rejects unsupported SSH ACP at the public execution entry: %s", async reason => { + it.each(["host auth", "legacy auth", "missing account", "in-place", "confinement", "missing SSH client"])("rejects unsupported SSH ACP at the public execution entry: %s", async reason => { const ctx = managedSshAcpContext("acp"); const originalResolve = ensureCommandResolvable.getMockImplementation()!; if (reason === "host auth") ctx.executionTarget.spec.useHostAuth = true; @@ -146,11 +158,22 @@ describe("claude remote execution", () => { if (reason === "missing account") delete ctx.config.managedAiConnection; if (reason === "in-place") ctx.executionTarget.workspaceRealization.mode = "in_place"; if (reason === "confinement") ctx.config.filesystemScope = "workspace"; - if (reason === "missing command") ensureCommandResolvable.mockRejectedValueOnce(new Error("fixture ACP command unavailable")); + const previousPath = process.env.PATH; + if (reason === "missing SSH client") { + const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-no-ssh-client-")); + cleanupDirs.push(bin); + process.env.PATH = bin; + const actual = await vi.importActual("@paperclipai/adapter-utils/server-utils"); + ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable); + } try { expect(await execute(ctx)).toMatchObject({ exitCode: 1, errorCode: "adapter_engine_unavailable" }); expect(executeAcp).not.toHaveBeenCalled(); - } finally { ensureCommandResolvable.mockReset().mockImplementation(originalResolve); } + } finally { + ensureCommandResolvable.mockReset().mockImplementation(originalResolve); + if (previousPath === undefined) delete process.env.PATH; + else process.env.PATH = previousPath; + } }); it.each([false, true])("keeps managed SSH Claude conversations and scrubs credentials (follow-up fails=%s)", async fails => { diff --git a/packages/adapters/codex-local/src/server/acp.ts b/packages/adapters/codex-local/src/server/acp.ts index 361cf2c190f..59aa900d62f 100644 --- a/packages/adapters/codex-local/src/server/acp.ts +++ b/packages/adapters/codex-local/src/server/acp.ts @@ -463,7 +463,7 @@ async function commandIsResolvable( trimmed, target, resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()), - target.transport === "ssh" ? {} : process.env, + target.transport === "ssh" ? { PATH: process.env.PATH } : process.env, ); return true; } catch { diff --git a/packages/adapters/codex-local/src/server/execute.remote.test.ts b/packages/adapters/codex-local/src/server/execute.remote.test.ts index c48a3203674..a795040c5c1 100644 --- a/packages/adapters/codex-local/src/server/execute.remote.test.ts +++ b/packages/adapters/codex-local/src/server/execute.remote.test.ts @@ -26,7 +26,7 @@ const { pid: 123, startedAt: new Date().toISOString(), })), - ensureCommandResolvable: vi.fn(async () => undefined), + ensureCommandResolvable: vi.fn(async () => undefined), resolveCommandForLogs: vi.fn(async () => "/usr/bin/codex"), prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })), restoreWorkspaceFromSshExecution: vi.fn(async () => undefined), @@ -113,6 +113,14 @@ describe("codex remote execution", () => { it.each([undefined, "acp"])("admits managed SSH ACP through the public execution entry (engine=%s)", async engine => { const ctx = managedSshAcpContext(engine); + const actual = await vi.importActual("@paperclipai/adapter-utils/server-utils"); + const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-client-probe-")); + cleanupDirs.push(bin); + await writeFile(path.join(bin, "ssh"), "#!/bin/sh\nexit 0\n", { mode: 0o700 }); + const originalResolve = ensureCommandResolvable.getMockImplementation()!; + ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable); + const previousPath = process.env.PATH; + process.env.PATH = bin; const previous = process.env.OPENAI_API_KEY; process.env.OPENAI_API_KEY = "fixture-server-secret"; try { @@ -120,15 +128,19 @@ describe("codex remote execution", () => { expect(executeAcp).toHaveBeenCalledWith(ctx); const probe = ensureCommandResolvable.mock.calls[0] as unknown as unknown[]; expect(probe[0]).toBe("codex-acp"); - expect(Object.keys(probe[2] as Record)).toEqual([]); + expect(Object.keys(probe[2] as Record)).toEqual(["PATH"]); + expect((probe[2] as Record).PATH === bin).toBe(true); expect(probe[3]).toMatchObject({ remoteExecution: { host: "ssh.example.test", useHostAuth: false } }); } finally { + ensureCommandResolvable.mockReset().mockImplementation(originalResolve); + if (previousPath === undefined) delete process.env.PATH; + else process.env.PATH = previousPath; if (previous === undefined) delete process.env.OPENAI_API_KEY; else process.env.OPENAI_API_KEY = previous; } }); - it.each(["host auth", "legacy auth", "missing account", "in-place", "confinement", "missing command"])("rejects unsupported SSH ACP at the public execution entry: %s", async reason => { + it.each(["host auth", "legacy auth", "missing account", "in-place", "confinement", "missing SSH client"])("rejects unsupported SSH ACP at the public execution entry: %s", async reason => { const ctx = managedSshAcpContext("acp"); const originalResolve = ensureCommandResolvable.getMockImplementation()!; if (reason === "host auth") ctx.executionTarget.spec.useHostAuth = true; @@ -136,11 +148,22 @@ describe("codex remote execution", () => { if (reason === "missing account") delete ctx.config.managedAiConnection; if (reason === "in-place") ctx.executionTarget.workspaceRealization.mode = "in_place"; if (reason === "confinement") ctx.config.filesystemScope = "workspace"; - if (reason === "missing command") ensureCommandResolvable.mockRejectedValueOnce(new Error("fixture ACP command unavailable")); + const previousPath = process.env.PATH; + if (reason === "missing SSH client") { + const bin = await mkdtemp(path.join(os.tmpdir(), "paperclip-no-ssh-client-")); + cleanupDirs.push(bin); + process.env.PATH = bin; + const actual = await vi.importActual("@paperclipai/adapter-utils/server-utils"); + ensureCommandResolvable.mockImplementationOnce(actual.ensureCommandResolvable); + } try { expect(await execute(ctx)).toMatchObject({ exitCode: 1, errorCode: "adapter_engine_unavailable" }); expect(executeAcp).not.toHaveBeenCalled(); - } finally { ensureCommandResolvable.mockReset().mockImplementation(originalResolve); } + } finally { + ensureCommandResolvable.mockReset().mockImplementation(originalResolve); + if (previousPath === undefined) delete process.env.PATH; + else process.env.PATH = previousPath; + } }); it.each([false, true])("retains a managed SSH Codex conversation across turns and removes credentials (second turn throws=%s)", async fails => {