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 => {